1FAXMAIL(1) General Commands Manual FAXMAIL(1)
2
6 faxmail - HylaFAX mail-to-fax gateway application
7
9 faxmail [ -O config ] [ options ] [ destination [ from ] ]
10
12 faxmail takes an electronic mail message on standard input and converts
13 it to POSTSCRIPT® in a form that is suitable for transmission as a fac‐
14 simile. The converted document is either written to the standard out‐
15 put or, if direct delivery is enabled, it is submitted directly to a
16 HylaFAX server for transmission.
17 faxmail is designed for use in constructing electronic mail to facsim‐
19 ile gateway services. For example, mail aliases may be created to
20 automatically transmit electronic mail; e.g.
21 sam: "|/usr/bin/faxmail -d sam@5551212"
23 or faxmail may be used as a ``mail transport agent'', extracting the
24 necessary delivery information directly from the envelope of the mail
25 message.
26 If faxmail is invoked without enabling direct delivery then it just
28 formats the mail message on the standard input and writes the result to
29 the standard output. To enable direct delivery the -d option must be
30 specified on the command line; see below for more information.
31
33 faxmail formats a mail message according to the following rules: First
34 it parses the envelope information interpreting any meta-header infor‐
35 mation (see below) that is present. Once the entire envelope has been
36 collected it emits a formatted set of header lines if the -N option has
37 not been used. By default all header information except the ``From'',
38 ``To'', ``Cc'', ``Subject'', and ``Date'' lines are discarded. Header
39 lines that are kept have the tag (the string to the left of the ``:'')
40 set in a bold font and the value (the string to the right of the ``:'')
41 set in an italic font. Mail messages that conform to the Multipurpose
42 Internet Mail Extensions (MIME) specification are parsed and handled
43 according to the rules given below. Plain text body parts of a mail
44 message are formatted in a text font with any long lines wrapped at
45 word boundaries unless the -c option has been specified.
46 By default, faxmail sets all text in 10 point type on an 8.5" by 11"
48 portrait-oriented page with .35" top margin, .25" bottom margin and
49 .25" left and right hand margins. There are command-line options to
50 control the point size, page dimensions, orientation, and multi-column
51 formatting. Text formatting can also be controlled through meta-header
52 directives placed in the envelope of the mail message.
53
55 faxmail pre-processes the envelope information (i.e. the header lines)
56 before formatting the message contents. Header lines whose names begin
57 with ``X-FAX-'' (case-insensitive) are handled specially-they are
58 treated as command directives that specify how to generate the resul‐
59 tant POSTSCRIPT or, optionally, how to deliver the resulting document
60 as facsimile. The set of known meta-headers corresponds to the set of
61 configuration parameters defined below. A meta-header is specified as
62 ``X-FAX-parameter'' where parameter is the name of a configuration
63 parameter; e.g. ``X-FAX-TabStop'' to set the number of spaces between
64 tab stops.
65 Controls for specifying headers to be passed through in the formatted
67 text identify not only which headers but also the order in which the
68 headers should be emitted. faxmail initializes the set of headers to
69 retain to: ``To From Subject Cc Date''. If this order is acceptable
70 then additional headers can simply be added with the X-FAX-Headers
71 directive; e.g. ``X-FAX-Headers: Message-id''. If however a different
72 order is desired then the header set should be cleared with a ``clear''
73 header tag and then completely specified in the desired order; for
74 example,
75 X-FAX-Headers: clear Message-id Date To Subject From Cc
77 will cause headers to be emitted in the order ``Message-Id Date To Sub‐
79 ject From Cc'' (depending on what headers are present). Note in par‐
80 ticular that all header lines in the envelope can be suppressed by
81 specifying ``X-FAX-Headers: clear''; this is useful, for example, when
82 the body of the mail message contains a preformatted document that is
83 to be transmitted.
84 In addition to the above controls, faxmail can also be instructed to
86 substitute an arbitrary string for a header tag when generating the
87 final envelope. This facility can be used to better format ad-hoc
88 header information that is passed through the envelope of the message.
89 The ``X-FAX-MapHeader'' meta-header specifies how to map a header line.
90 For example,
91 X-FAX-MapHeader: x_FAX_For Deliver FAX To
93 would cause any header ``x_FAX_For'' that appeared in the envelope to
95 be replaced in the formatted envelope by ``Deliver FAX To''.
96
98 faxmail parses MIME mail messages and does some rudimentary work to:
99 · strip out unprintable content such as audio, video, or binary data,
101 · decode encoded parts,
103 · insert ``digest dividers'' between multipart/digest subparts,
105 · format message/rfc822 parts as described above for the top-level
107 envelope, and
108 · optionally convert graphical parts (e.g. images) for display.
110 MIME processing is fairly simple and (currently) somewhat constrained.
112 faxmail has built-in support for the following MIME parts: text/plain,
113 multipart/mixed, multipart/digest, message/rfc822, application/post‐
114 script, and application/x-faxmail-prolog. Parts can also be processed
115 through external processing scripts that faxmail looks for in a ``MIME
116 converters'' directory hierarchy. External scripts may override
117 builtin processing or supplement the builtin support. For each MIME
118 body part with type T and subtype S faxmail checks first for an exe‐
119 cutable script named T/S in the converter hierarchy. If a script
120 exists then it is run and the result is appended as a new page to the
121 output PostScript document. (The script is expected to produce inde‐
122 pendently complete pages.) Otherwise if the part has builtin support
123 then it is processed directly. Any part that does not have external or
124 builtin support is discarded and replaced by a message that indicates
125 the part was removed. This discarded message can be suppressed with
126 the MarkDiscarded configuration parameter (also settable with an X-FAX-
127 MarkDiscarded line in the envelope).
128 The built-in handling support is as follows: text/plain parts are for‐
130 matted using the default text font and point size; multipart/mixed are
131 ``burst'' and interpreted per the specification but are otherwise
132 unformatted; multipart/digest are burst and an optional ``digest
133 divider'' marking may be inserted before each subpart; message/rfc822
134 are formatted as described above with envelope header lines culled and
135 formatted with bold and italic fonts (in addition, if there is insuffi‐
136 cient space in the current output page/column for the message envelope,
137 optional divider, and one line of text, then faxmail will insert a
138 ``break'' so the the message starts at the top of the next page/col‐
139 umn); application/postscript are copied through untouched to the out‐
140 put; application/x-faxmail-prolog are copied through untouched to the
141 end of the prologue section of the generated PostScript document to
142 permit customization of the formatted output.
143 faxmail supports the following Content-Transfer-Encoding schemes: 7bit,
145 8bit, binary, base64, quoted-printable, and x-uuencode. Any character
146 set that is not us-ascii is treated as iso-8859-1.
147 In general it is recommended that senders either permit faxmail to for‐
149 mat message contents or completely bypass the formatting facilities and
150 submit data that is to be processed by sendfax. Trying to combine the
151 two facilities by, for example, combining PostScript with text that is
152 to be formatted is unlikely to work well because faxmail does not track
153 the amount of space on the page that a non-text MIME part uses.
154
156 When faxmail is invoked with the -d option it delivers the formatted
157 document directly to a HylaFAX server for transmission as facsimile.
158 Command line arguments may be supplied to specify the delivery destina‐
159 tion and sender identity; typically from information extracted by the
160 mail transport facility. A command line destination is specified with
161 the same syntax as the argument for the -d option to the sendfax(1)
162 command. Similarly any from identity specified on the command line
163 follows the same rules as the -f option to sendfax. An explicit dial‐
164 string to use in delivery can also be specified with an X-FAX-Dial‐
165 string header in the mail message envelope. If no sender identity is
166 provided on the command line then faxmail will extract it from the
167 ``From'' line in the envelope. faxmail will not submit a message for
168 delivery if either the dialstring or sender identity is missing or
169 null.
170 When direct delivery is enabled X-FAX- header lines may be included in
172 the mail message envelope to control the submission and delivery
173 process. As above these lines are specified as ``X-FAX-parameter''
174 where parameter is the name of a configuration parameter for the send‐
175 fax program; e.g. ``X-FAX-VRes'' to set the vertical resolution of the
176 transmitted facsimile. By default automatic cover page generation is
177 enabled when direct delivery is used; this can be overridden with the
178 -n option on the command line or by including an X-FAX-AutoCoverPage
179 header in the message envelope.
180
182 -1 Set text in one column (default).
183 -2 Set text two columns.
185 -b font Make font, a POSTSCRIPT font name, the ``bold font'' used to
187 set header lines. The default bold font is Helvetica-Bold.
188 -c Clip long text lines instead of wrapping them at word bound‐
190 aries near page margins.
191 -C cover Use the cover page template file specified by cover.
193 -d Enable direct delivery of facsimile; the formatted document
195 will be submitted directly to a HylaFAX server for transmis‐
196 sion as facsimile. This option is similar to piping the out‐
197 put of faxmail to the input of sendfax(8C) except when direct
198 delivery is enabled faxmail interprets ``x-fax-'' header
199 lines in the envelope of the mail message to look for control
200 information to use in delivering the facsimile and, by
201 default, no automatic cover page generation is done.
202 -f font Make font, a POSTSCRIPT font name, the text font used to set
204 the body of mail messages. The default text font is Courier.
205 -H height Use height as the height, in inches, of the output page. The
207 default page height is taken from the default page size.
208 -i font Make font, a POSTSCRIPT font name, the ``italic font'' used
210 to set header lines. The default italic font is Helvetica-
211 Oblique.
212 -Ml=#,r=#,t=#,b=#
214 Set the page margins; the default margins are: left and right
215 .25 inch, top .35 inch, bottom .25 inch.
216 -n Suppress auto cover page generation when doing direct deliv‐
218 ery.
219 -N Suppress the formatting of envelope headers.
221 -O config Treat config as a configuration parameter specification that
223 is interpreted after reading the configuration file. For
224 example, ``-O Host:fax.example.com'' would set the Host con‐
225 figuration parameter to ``fax.example.com'', overriding any
226 setting in the configuration file.
227 -p size Set all text using size for the font point size.
229 -r Set pages rotated by 90 degrees (in ``Landscape mode'').
231 -R Set pages unrotated (in ``Portrait mode'').
233 -s size Set the page size to use. Cover pages are normally generated
235 using a system-default page size (usually letter-size pages,
236 8.5" by 11", for sites in North America). Alternate page
237 sizes are specified symbolically using either the name or
238 abbreviation of an entry in the pagesizes(5F) database; e.g.
239 a3 (ISO A3), a4 (ISO A4), a5 (ISO A5), a6 (ISO A6), b4 (ISO
240 B4), na-let (North American Letter), us-leg (American Legal),
241 us-led (American Ledger), us-exe (American Executive), jp-let
242 (Japanese Letter), and jp-leg (Japanese Legal). Comparisons
243 are case-insensitive and any match of a substring of the full
244 page-size name is sufficient; e.g. ``legal'' would match
245 ``American Legal''.
246 -S tsi Pass tsi to the server as the suggested sender identification
248 to be used, for example, in tagline imaging and fax protocol.
249 -t when Notify the sender of job status according to when. The
251 options are ``done'', ``req'' (for re-queued),
252 ``none''/``off'', or ``default''.
253 -T Trim leading blank lines on text parts.
255 -u user Set the user name to use when logging in to do direct deliv‐
257 ery. By default the user is specified by the MailUser con‐
258 figuration parameter (see below). If a null user name is
259 specified, then the facsimile will be submitted using the
260 identity of the user that invoked faxmail. On the command-
261 line, the login password may also be provided by separating
262 it from the owner login name with a colon, like
263 ``owner:pass''.
264 -v Enable tracing of envelope, MIME, and job submission process‐
266 ing. Diagnostic information is written to the standard error
267 (envelope and MIME processing) and standard output (job sub‐
268 mission).
269 -W width Use width as the width, in inches, of the output page. The
271 default page width is taken from the default page size.
272
274 faxmail reads configuration information from the files
275 /etc/hylafax/hyla.conf, /etc/hylafax/faxmail.conf, and ~/.hylarc; in
276 that order. Configuration files follow the conventions described in
277 hylafax-client(1). The following configuration parameters are recog‐
278 nized:
279 Tag Type Default Description
280 AutoCoverPage boolean Yes automatically generate cover page
281 BoldFont string Helvetica-Bold font for setting header tags
282 Columns integer 1 number of columns in formatted output
283 DigestDivider string - multipart/digest divider POSTSCRIPT command
284 FirstAlternativeOnly boolean Yesonly use the first alternative part
285 FontPath string see below directory for font metric files
286 GaudyHeaders boolean No enable/disable gaudy page headers
287 Headers string see below headers to retain in envelope
288 ISO8859 boolean Yes use ISO 8859-1 character encoding
289 ItalicFont string Helvetica-Oblique font for setting header values
290 LineWrap boolean Yes wrap/truncate text lines
291 MailUser string - user identity for doing direct delivery
292 MarkDiscarded boolean Yes mark discarded MIME body parts
293 MapHeader string - define header mapping
294 MIMEConverters string see below pathname of MIME converter scripts
295 Orientation string portrait orientation of text on page
296 OutlineMargin inches 0 width of outline line
297 Overstrike boolean No overstrike interpretation of lone carriage returns
298 PageCollation string forward collate pages in forward or reverse direction
299 PageHeaders boolean Yes enable/disable page headers
300 PageHeight float - output page height
301 PageMargins string see below margins for formatted page
302 PageSize string default output page size from database
303 PageWidth float - output page width
304 Prologfile string see below pathname of POSTSCRIPT prologue file
305 TabStop integer 8 inter-stop setting in characters
306 TextFont string Courier name of font for setting text
307 TextLineHeight inches - text formatting line height control
308 TextPointSize inches see below size to use in setting text
309 TrimText boolean No trim leading blank lines on text parts
310 UseAlternativePart integer 1which part to use in a set of alternatives
311 Verbose boolean No trace envelope and MIME processing
312 Values marked as inches are specified using a syntax that identifies
314 one of several possible units:
315 #.##bp big point (1in = 72bp)
316 #.##cc cicero (1cc = 12dd)
317 #.##cm centimeter
318 #.##dd didot point (1157dd = 1238pt)
319 #.##in inch
320 #.##mm millimeter (10mm = 1cm)
321 #.##pc pica (1pc = 12pt)
322 #.##pt point (72.27pt = 1in)
323 #.##sp scaled point (65536sp = 1pt)
324 Unit names can be upper or lower case but no white space is permitted
326 between the number and the unit. Values specified with no unit are
327 interpreted as points.
328 The configuration parameters are explained below. Most parameters cor‐
330 respond to a command line option. Parameter values identified above as
331 inches are converted according to the conventions described above.
332 AutoCoverPage Control whether or not a cover page is automatically
334 generated for each job.
335 BoldFont The name of the font to use to set header tags (i.e. the
337 string to the left of the ``:'').
338 Columns The number of columns to set text in. (Equivalent to
340 the -m option.)
341 DigestDivider The string to emit in the output before each subpart of
343 a multipart/digest mail message. This string is typi‐
344 cally a POSTSCRIPT procedure that draws a mark of some
345 sort. Dividers are expected to use no more vertical
346 space on the output page than a line of text.
347 FirstAlternativeOnly, UseAlternativePart
349 In a multipart/alternative MIME section whether or not
350 to only format the first part. A multipart/alternative
351 MIME section is typically used to present the mail
352 client with a selection of alternatives which contain
353 the same basic content (such as a text/plain and a
354 text/html part). Thus the mail client has the opportu‐
355 nity to select which part is best-suited for its pur‐
356 pose. Generally the most-portable format (text/plain)
357 is the first alternative. These options allow parts to
358 be stripped when presented in a multipart/alternative
359 section and prevents duplicate parts from being format‐
360 ted. ``FirstAlternativeOnly: true'' is synonymous with
361 ``UseAlternativePart: 1'' while ``FirstAlternativeOnly:
362 false'' is synonymous with ``UseAlternativePart: 0''
363 (which causes all alternatives to be formatted). In
364 order to format only the text/html part then ``UseAlter‐
365 nativePart: 2'' should work.
366 FontPath The path where Adobe Font Metric (AFM) files are
368 located; by default /usr/share/ghost‐
369 script/Resource/Init:/usr/share/ghost‐
370 script/lib:/usr/share/ghost‐
371 script/Resource/Font:/usr/share/ghost‐
372 script/fonts:/usr/share/fonts/urw-
373 base35:/usr/share/fonts/google-droid.
374 GaudyHeaders Control whether or not to use a gaudy-style page header.
376 Enabling gaudy headers implicitly enables page headers.
377 Headers Define the headers retained from the envelope and spec‐
379 ify the order that they should be emitted in the format‐
380 ted output. The set of headers is initialized to ``To
381 From Subject Cc Date''. Headers specified are appended
382 to this list except for a ``clear'' header that causes
383 the current set of headers to be discarded.
384 ISO8859 Control the use of ISO 8859-1 encoding in the generated
386 POSTSCRIPT
387 ItalicFont The name of the font to use to set header values (i.e.
389 the string to the right of the ``:'').
390 LineWrap Control whether long text lines are wrapped or truncated
392 at the right hand margin. (Equivalent to the -c
393 option.)
394 MailUser The account name to use to login to a fax server when
396 doing direct delivery. Note that this account name is
397 not used for the identity of the sender; this comes from
398 the command line or the ``From'' line in the mail mes‐
399 sage. If a null account name is specified, then the
400 facsimile will be submitted using the identity of the
401 user that invoked faxmail.
402 MapHeader Define a substitution for the specified header that
404 should be done each time the header is emitted in the
405 formatted envelope. Header tags are matched in a case-
406 insensitive manner.
407 MarkDiscarded Control whether discarded MIME parts are replaced by a
409 text message indicating the original content was
410 removed.
411 MIMEConverters The pathname of a directory hierarchy that has scripts
413 for external processing of MIME body parts. The default
414 pathname is /etc/hylafax/faxmail. HylaFAX comes with
415 default converter scripts for TIFF and PDF, and they can
416 be found in that path and used as a reference for con‐
417 structing other converters. The script is passed the
418 filename of the body part for conversion as the first
419 argument. Subsequent arguments are the MIME Content-
420 Description, Content-ID, Content-Disposition, Content-
421 Type name, and Content-Disposition filename information
422 which are each preceded by their respective ``-descrip‐
423 tion'', ``-id'', ``-disposition'', ``-name'', or
424 ``-filename'' argument.
425 Orientation Control whether pages are oriented horizontally (``land‐
427 scape'') or vertically (``portrait''). (Equivalent to
428 the -r and -R options.)
429 OutlineMargin Control whether columns of text have a line drawn around
431 them and the width of the line. Setting this parameter
432 to 0 disables outlines.
433 PageCollation Control whether the output file has pages collated in
435 the same order as the input file (``forward'') or in
436 reverse order (``reverse).
437 PageHeaders Control whether page headers are generated.
439 PageHeight Set the output page height (in inches).
441 PageMargins Set the output page margins. Margins are specified as
443 string of the form: ``l=#,r=#,t=#,b=#'' where l indi‐
444 cates the left margin, r indicates the right margin, t
445 indicates the top margin, b indicates the bottom margin,
446 and numbers are interpreted as inches. (Equivalent to
447 the -M option.)
448 PageSize Set the output page dimensions by name. (Equivalent to
450 the -s option.)
451 PageWidth Set the output page width (in inches).
453 PrologFile The pathname of a file containing POSTSCRIPT that should
455 be included in the prologue section of the generated
456 POSTSCRIPT. The default prologue file is
457 /etc/hylafax/faxmail.ps.
458 TabStop Set the tab stop distance (in characters).
460 TextFont Set the name of font to use for setting text. (Equiva‐
462 lent to the -f option.)
463 TextLineHeight Set the vertical text line height and spacing.
465 TextPointSize Set the point size to use in setting plain text.
467 (Equivalent to the -p option.)
468 TrimText Trim leading blank lines on text parts.
470 Verbose Control tracing envelope and MIME processing.
472
474 Because a sender's identity in an electronic mail message is inherently
475 untrustworthy, using faxmail to build a mail to fax gateway is problem‐
476 atic. Unless mail service is somehow restricted or the sender's iden‐
477 tity is verified using a mechanism such as RFC 1847's multipart/signed
478 MIME type there is no reliable way to restrict access to facilities
479 setup with faxmail.
480
482 Only the last instance of a header is kept and written to the output.
483 This means, for example, that only the last of many ``Received'' lines
484 will be included in the formatted output.
485
487 ~/.hylarc per-user configuration file
488 /etc/hylafax/pagesizes page size database
489 /etc/hylafax/faxmail.ps POSTSCRIPT prologue
490 /etc/hylafax/hyla.conf system-wide configuration file
491 /etc/hylafax/faxmail.conf system-wide configuration file
492 /etc/hylafax/sendfax.conf system-wide configuration file for direct delivery
493 /etc/hylafax/faxmail hierarchy for external MIME converters
494 /usr/share/ghostscript/Resource/Init:/usr/share/ghostscript/lib:/usr/share/ghostscript/Resource/Font:/usr/share/ghostscript/fonts:/usr/share/fonts/urw-base35:/usr/share/fonts/google-droidfor font metrics
495 /var/spool/hylafax/tmp/faxmailXXXXXXtemporary files
496
498 hylafax-client(1), textfmt(1), sendfax(1)
499 July 22, 1996 FAXMAIL(1)