Provided by: hylafax-client_6.0.7-5build1_amd64 
NAME
faxmail - HylaFAX mail-to-fax gateway application
SYNOPSIS
faxmail [ options ] [ destination [ from ] ]
DESCRIPTION
faxmail takes an electronic mail message on standard input and submits it as a facsimile
to a HylaFAX server for transmission.
faxmail 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"
or faxmail may be used as a ``mail transport agent'', extracting the necessary delivery
information directly from the envelope of the mail message.
FORMATTING
faxmail 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.
ENVELOPE PROCESSING
faxmail 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'' where
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''.
MIME PROCESSING
faxmail parses MIME mail messages and does some rudimentary work to:
• decode encoded parts,
• formats the message and text parts into a Postscript document
• insert ``digest dividers'' between multipart/digest subparts,
• format message/rfc822 parts as described above for the top-level envelope, and
• submit all other attached documents to be faxed.
MIME processing is fairly simple and (currently) somewhat constrained. faxmail 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 hierarchy. External scripts may override
builtin processing or suppliment the builtin support. For each MIME body part with type T
and subtype S faxmail checks first for an executable script named T/S in the converter
hierarchy. 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.
faxmail uses the typerules(5). mechanism to convert file formats into one of the format
HylaFAX supports.
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 faxmail
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.
faxmail 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.
SERVER DELIVERY
When faxmail is invoked it delivers the formatted document directly to a HylaFAX 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 line destination is specified with the same syntax as the
argument for the -d option to the sendfax(1) command. Similarly any from identity
specified on the command line follows the same rules as the -f 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 faxmail will extract it from the ``From'' line in the envelope. faxmail 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 ``X-FAX-parameter'' 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.
OPTIONS
-1 Set text in one column (default).
-2 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 Helvetica-Bold.
-c Clip long text lines instead of wrapping them at page margins.
-C cover Use the cover page template file specified by cover.
-f font Make font, a POSTSCRIPT font name, the text font used to set the body of mail
messages. The default text font is Courier.
-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 Helvetica-Oblique.
-Ml=#,r=#,t=#,b=#
Set the page margins; the default margins are: left and right .25 inch, top .35
inch, bottom .25 inch.
-n Suppress auto cover page generation.
-N Suppress formatting of mail envelope headers.
-p size Set all text using size for the font point size.
-r Set pages rotated by 90 degrees (in ``Landscape mode'').
-R 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 ``American Legal''.
-t notify Specify the notify value to use
-T 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 invoked faxmail.
-v 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 submission).
-W width Use width as the width, in inches, of the output page. The default page width
is taken from the default page size.
CONFIGURATION PARAMETERS
faxmail reads configuration information from the files /etc/hylafax/hyla.conf,
/etc/hylafax/sendmail.conf, /etc/hylafax/faxmail.conf, and ~/.hylarc; in that order.
Configuration files follow the conventions described in hylafax-client(1). In addition to
the formatting configuration parameters below, all of the parameters listed in the
sendfax(1) man 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)
#.##cm centimeter
#.##dd didot point (1157dd = 1238pt)
#.##in inch
#.##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 points.
The configuration parameters are explained below. Most parameters correspond to a command
line option. Parameter values identified above as inches are converted according to the
conventions described above.
AutoCoverPage Control whether or not a cover page is automatically generated for each
job.
BoldFont The name of the font to use to set header tags (i.e. the string to the left
of the ``:'').
Columns The number of columns to set text in. (Equivalent to the -m option.)
DigestDivider 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.
FontPath The path where Adobe Font Metric (AFM) files are located; by default
/usr/share/fonts/type1/gsfonts.
GaudyHeaders Control whether or not to use a gaudy-style page header. Enabling gaudy
headers implicitly enables page headers.
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.
ISO8859 Control the use of ISO 8859-1 encoding in the generated POSTSCRIPT
ItalicFont The name of the font to use to set header values (i.e. the string to the
right of the ``:'').
LineWrap Control whether long text lines are wrapper or truncated at the right hand
margin. (Equivalent to the -c option.)
MailUser 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 faxmail.
MapHeader 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.
MarkDiscarded Control whether discarded MIME parts are replaced by a text message
indicating the original content was removed.
MIMEConverters The pathname of a directory hierarchy that has scripts for external
processing of MIME body parts. The default pathname is /usr/sbin/faxmail.
Orientation Control whether pages are oriented horizontally (``landscape'') or
vertically (``portrait''). (Equivalent to the -r and -R options.)
OutlineMargin Control whether columns of text have a line drawn around them and the width
of the line. Setting this parameter to 0 disables outlines.
PageCollation Control whether the output file has pages collated in the same order as the
input file (``forward'') or in reverse order (``reverse).
PageHeaders Control whether page headers are generated.
PageHeight Set the output page height (in inches).
PageMargins 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 option.)
PageSize Set the output page dimensions by name. (Equivalent to the -s option.)
PageWidth Set the output page width (in inches).
PrologFile 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.
TabStop Set the tab stop distance (in characters).
TextFont Set the name of font to use for setting text. (Equivalent to the -f
option.)
TextLineHeight Set the vertical text line height and spacing.
TextPointSize Set the point size to use in setting plain text. (Equivalent to the -p
option.)
Verbose Control tracing envelope and MIME processing.
NOTES
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 faxmail.
BUGS
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.
FILES
~/.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/gsfontsfor font metrics
/var/spool/hylafax/tmp/faxmailXXXXXXtemporary files
SEE ALSO
hylafax-client(1), textfmt(1), sendfax(1)
July 22, 1996 FAXMAIL(1)