faxmail - HylaFAX
mail-to-fax gateway application
] [ destination
takes an electronic mail message on standard input and submits it
as a facsimile to a HylaFAX
server for transmission.
is designed for use in constructing electronic mail to facsimile
gateway services. For example, mail aliases may be created to automatically
transmit electronic mail; e.g.
sam: "|/usr/bin/faxmail sam@5551212"
may be used as a ``mail transport agent'', extracting the
necessary delivery information directly from the envelope of the mail message.
formats a mail message according to the following rules: First it
parses the envelope information interpreting any meta-header information (see
below) that is present. Once the entire envelope has been collected it emits a
formatted set of header lines. By default all header information except the
``From'', ``To'', ``Cc'', ``Subject'', and ``Date'' lines are discarded.
Header lines that are kept have the tag
(the string to the left of the
``:'') set in a bold font
and the value
(the string to the right
of the ``:'') set in an italic font
. Mail messages that conform to the
Multipurpose Internet Mail Extensions (MIME) specification are parsed and
handled according to the rules given below. Plain text body parts of a mail
message are formatted in a text font
with any long lines wrapped at
word boundaries unless the -c
option has been specified.
By default, faxmail
sets all text in 10 point type on an 8.5" by
11" portrait-oriented page with .35" top margin, .25" bottom
margin and .25" left and right hand margins. There are command-line
options to control the point size, page dimensions, orientation, and
multi-column formatting. Text formatting can also be controlled through
meta-header directives placed in the envelope of the mail message.
pre-processes the envelope information (i.e. the header lines)
before formatting the message contents. Header lines whose names begin with
``X-FAX-'' (case-insensitive) are handled specially-they are treated as
command directives that specify how to generate the resultant POSTSCRIPT or,
optionally, how to deliver the resulting document as facsimile. The set of
known meta-headers corresponds to the set of configuration parameters defined
below. A meta-header is specified as ``X-FAX- parameter
is the name of a configuration parameter; e.g.
``X-FAX-TabStop'' to set the number of spaces between tab stops.
Controls for specifying headers to be passed through in the formatted text
identify not only which headers but also the order in which the headers should
be emitted. faxmail
initializes the set of headers to retain to: ``To
From Subject Cc Date''. If this order is acceptable then additional headers
can simply be added with the X-FAX-Headers directive; e.g. ``X-FAX-Headers:
Message-id''. If however a different order is desired then the header set
should be cleared with a ``clear'' header tag and then completely specified in
the desired order; for example,
X-FAX-Headers: clear Message-id Date To Subject From Cc
will cause headers to be emitted in the order ``Message-Id Date To Subject From
Cc'' (depending on what headers are present). Note in particular that all
header lines in the envelope can be suppressed by specifying ``X-FAX-Headers:
clear''; this is useful, for example, when the body of the mail message
contains a preformatted document that is to be transmitted.
In addition to the above controls, faxmail
can also be instructed to
substitute an arbitrary string for a header tag when generating the final
envelope. This facility can be used to better format ad-hoc header information
that is passed through the envelope of the message. The ``X-FAX-MapHeader''
meta-header specifies how to map a header line. For example,
X-FAX-MapHeader: x_FAX_For Deliver FAX To
would cause any header ``x_FAX_For'' that appeared in the envelope to be
replaced in the formatted envelope by ``Deliver FAX To''.
mail messages and does some
rudimentary work to:
- decode encoded parts,
- formats the message and text parts into a Postscript
- insert ``digest dividers'' between multipart/digest
- format message/rfc822 parts as described above for the
top-level envelope, and
- submit all other attached documents to be faxed.
processing is fairly simple and (currently) somewhat
has builtin support for the following MIME parts:
text/plain, multipart/mixed, multipart/digest, message/rfc822,
application/postscript, and application/x-faxmail-prolog. Parts can also be
processed through external processing scripts that faxmail
looks for in
a ``MIME converters'' directory hierachy. External scripts may override
builtin processing or suppliment the builtin support. For each
body part with type T
and subtype S
checks first for an exceutable script named T/S in the
converter heirarchy. If a script exists then it is run and the resulting
output is saved as a document submitted to HylaFAX
. If the output is
empty, the part is suppressed, and will not be submitted. All other parts will
be saved as documents and submitted to HylaFAX
(5). mechanism to convert file formats into one of the format
The builtin handling support is as follows: text/plain parts are formatted using
the default text font
and point size; multipart/mixed are ``burst'' and
interpreted per the specification but are otherwise unformatted;
multipart/digest are burst and an optional ``digest divider'' marking may be
inserted before each subpart; message/rfc822 are formatted as described above
with envelope header lines culled and formatted with bold and italic fonts (in
addition, if there is insufficient space in the current output page/column for
the message envelope, optional divider, and one line of text, then
will insert a ``break'' so the the message starts at the top of
the next page/column); application/postscript are copied through untouched to
the output; application/x-faxmail-prolog are copied through untouched to the
end of the prologue section of the generated PostScript document to permit
customization of the formatted output.
supports the following Content-Transfer-Encoding schemes: 7bit,
8bit, binary, base64, quoted-printable, and x-uuencode. Any character set that
is not us-ascii is treated as iso-8859-1.
is invoked it delivers the formatted document directly to a
server for transmission as facsimile. Command line arguments
may be supplied to specify the delivery destination and sender identity;
typically from information extracted by the mail transport facility. A command
is specified with the same syntax as the argument for
option to the sendfax
(1) command. Similarly any
identity specified on the command line follows the same rules as
option to sendfax
. An explicit dialstring to use in
delivery can also be specified with an X-FAX-Dialstring header in the mail
message envelope. If no sender identity is provided on the command line then
will extract it from the ``From'' line in the envelope.
will not submit a message for delivery if either the dialstring
or sender identity is missing or null.
X-FAX- header lines may be included in the mail message envelope to control the
submission and delivery process. As above these lines are specified as
'' where parameter
is the name of a
configuration parameter for the sendfax
program; e.g. ``X-FAX-VRes'' to
set the vertical resolution of the transmitted facsimile. By default automatic
cover page generation is enabled when direct delivery is used; this can be
overridden with the -n
option on the command line or by including an
X-FAX-AutoCoverPage header in the message envelope.
- Set text in one column (default).
- Set text two columns.
- -b font
- Make font, a POSTSCRIPT font name, the `` bold
font'' used to set header lines. The default bold font is
- Clip long text lines instead of wrapping them at page
- -C cover
- Use the cover page template file specified by
- -f font
- Make font, a POSTSCRIPT font name, the text font
used to set the body of mail messages. The default text font is
- -H height
- Use height as the height, in inches, of the output
page. The default page height is taken from the default page size.
- -i font
- Make font, a POSTSCRIPT font name, the `` italic
font'' used to set header lines. The default italic font is
- Set the page margins; the default margins are: left and
right .25 inch, top .35 inch, bottom .25 inch.
- Suppress auto cover page generation.
- Suppress formatting of mail envelope headers.
- -p size
- Set all text using size for the font point
- Set pages rotated by 90 degrees (in ``Landscape
- Set pages unrotated (in ``Portrait mode'').
- -s size
- Set the page size to use. Cover pages are normally
generated using a system-default page size (usually letter-size pages,
8.5" by 11", for sites in North America). Alternate page sizes
are specified symbolically using either the name or abbreviation of an
entry in the pagesizes(5) database; e.g. a3 (ISO A3),
a4 (ISO A4), a5 (ISO A5), a6 (ISO A6), b4 (ISO
B4), na-let (North American Letter), us-leg (American
Legal), us-led (American Ledger), us-exe (American
Executive), jp-let (Japanese Letter), and jp-leg (Japanese
Legal). Comparisons are case-insensitive and any match of a substring of
the full page-size name is sufficient; e.g. ``legal'' would match
- -t notify
- Specify the notify value to use
- Trim leading blank lines from text parts. If the text part
is completely empty, it will effectively be skipped.
- -u user
- Set the user name to use when logging in to do direct
delivery. By default the user is specified by the MailUser
configuration parameter (see below). If a null user name is specified,
then the facsimile will be submitted using the identity of the user that
- Enable tracing of envelope, MIME, and job
submission processing. Diagnostic information is written to the standard
error (envelope and MIME processing) and standard output (job
- -W width
- Use width as the width, in inches, of the output
page. The default page width is taken from the default page size.
reads configuration information from the files
, and ~/.hylarc
; in that order.
Configuration files follow the conventions described in
(1). In addition to the formatting configuration
parameters below, all of the parameters listed in the sendfax
page apply as well.
The following configuration parameters are recognized to support formatting:
Tag Type Default Description
AutoCoverPage boolean Yes automatically generate cover page
BoldFont string Helvetica-Bold font for setting header tags
Columns integer 1 number of columns in formatted output
DigestDivider string - multipart/digest divider POSTSCRIPT command
FontPath string see below directory for font metric files
GaudyHeaders boolean No enable/disable gaudy page headers
Headers string see below headers to retain in envelope
ISO8859 boolean Yes use ISO 8859-1 character encoding
ItalicFont string Helvetica-Oblique font for setting header values
LineWrap boolean Yes wrap/truncate text lines
MailUser string - user identity for doing direct delivery
MarkDiscarded boolean Yes mark discarded MIME body parts
MapHeader string - define header mapping
MIMEConverters string see below pathname of MIME converter scripts
Orientation string portrait orientation of text on page
OutlineMargin inches 0 width of outline line
PageCollation string forward collate pages in forward or reverse direction
PageHeaders boolean Yes enable/disable page headers
PageHeight float - output page height
PageMargins string see below margins for formatted page
PageSize string default output page size from database
PageWidth float - output page width
Prologfile string see below pathname of POSTSCRIPT prologue file
TabStop integer 8 inter-stop setting in characters
TextFont string Courier name of font for setting text
TextLineHeight inches - text formatting line height control
TextPointSize inches see below size to use in setting text
Verbose boolean No trace envelope and MIME processing
Values marked as inches
are specified using a syntax that identifies one
of several possible units:
#.##bp big point (1in = 72bp)
#.##cc cicero (1cc = 12dd)
#.##dd didot point (1157dd = 1238pt)
#.##mm millimeter (10mm = 1cm)
#.##pc pica (1pc = 12pt)
#.##pt point (72.27pt = 1in)
#.##sp scaled point (65536sp = 1pt)
Unit names can be upper or lower case but no white space is permitted between
the number and the unit. Values specified with no unit are interpreted as
The configuration parameters are explained below. Most parameters correspond to
a command line option. Parameter values identified above as inches
converted according to the conventions described above.
- Control whether or not a cover page is automatically
generated for each job.
- The name of the font to use to set header tags (i.e. the
string to the left of the ``:'').
- The number of columns to set text in. (Equivalent to the
- The string to emit in the output before each subpart of a
multipart/digest mail message. This string is typically a POSTSCRIPT
procedure that draws a mark of some sort. Dividers are expected to use no
more vertical space on the output page than a line of text.
- The path where Adobe Font Metric (AFM) files are located;
by default /usr/share/fonts/type1/gsfonts.
- Control whether or not to use a gaudy-style page header.
Enabling gaudy headers implicitly enables page headers.
- Define the headers retained from the envelope and specify
the order that they should be emitted in the formatted output. The set of
headers is initialized to ``To From Subject Cc Date''. Headers specified
are appended to this list except for a ``clear'' header that causes the
current set of headers to be discarded.
- Control the use of ISO 8859-1 encoding in
the generated POSTSCRIPT
- The name of the font to use to set header values (i.e. the
string to the right of the ``:'').
- Control whether long text lines are wrapper or truncated at
the right hand margin. (Equivalent to the -c option.)
- The account name to use to login to a fax server when doing
direct delivery. Note that this account name is not used for the identity
of the sender; this comes from the command line or the ``From'' line in
the mail message. If a null account name is specified, then the facsimile
will be submitted using the identity of the user that invoked
- Define a substitution for the specified header that should
be done each time the header is emitted in the formatted envelope. Header
tags are matched in a case-insensitive manner.
- Control whether discarded MIME parts are
replaced by a text message indicating the original content was
- The pathname of a directory hierarchy that has scripts for
external processing of MIME body parts. The default
pathname is /usr/sbin/faxmail.
- Control whether pages are oriented horizontally
(``landscape'') or vertically (``portrait''). (Equivalent to the -r
and -R options.)
- Control whether columns of text have a line drawn around
them and the width of the line. Setting this parameter to 0 disables
- Control whether the output file has pages collated in the
same order as the input file (``forward'') or in reverse order
- Control whether page headers are generated.
- Set the output page height (in inches).
- Set the output page margins. Margins are specified as
string of the form: `` l=#,r=#,t=#,b=#'' where
l indicates the left margin, r indicates the right margin,
t indicates the top margin, b indicates the bottom margin,
and numbers are interpreted as inches. (Equivalent to the -M
- Set the output page dimensions by name. (Equivalent to the
- Set the output page width (in inches).
- The pathname of a file containing POSTSCRIPT that should be
included in the prologue section of the generated POSTSCRIPT. The default
prologue file is /etc/hylafax/faxmail.ps.
- Set the tab stop distance (in characters).
- Set the name of font to use for setting text. (Equivalent
to the -f option.)
- Set the vertical text line height and spacing.
- Set the point size to use in setting plain text.
(Equivalent to the -p option.)
- Control tracing envelope and MIME processing.
Because a sender's identity in an electronic mail message is inherently
untrustworthy, using faxmail
to build a mail to fax gateway is
problematic. Unless mail service is somehow restricted or the sender's
identity is verified using a mechanism such as RFC 1847's multipart/signed
MIME type there is no reliable way to restrict access to facilities setup with
Only the last instance of a header is kept and written to the output. This
means, for example, that only the last of many ``Received'' lines will be
included in the formatted output.
~/.hylarc per-user configuration file
/etc/hylafax/pagesizes page size database
/etc/hylafax/faxmail.ps POSTSCRIPT prologue
/etc/hylafax/hyla.conf system-wide configuration file
/etc/hylafax/faxmail.conf system-wide configuration file
/etc/hylafax/sendfax.conf system-wide configuration file for direct delivery
/usr/sbin/faxmail hierarchy for external MIME converters
/usr/share/fonts/type1/gsfonts for font metrics
/var/spool/hylafax/tmp/faxmailXXXXXX temporary files