Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FAXMAIL(1)		    General Commands Manual		    FAXMAIL(1)

       faxmail - HylaFAX mail-to-fax gateway application

       faxmail [ options ] [ destination [ from	] ]

       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  facsim-
       ile  gateway services.  For example, mail aliases may be	created	to au-
       tomatically transmit electronic mail; e.g.

	    sam: "|/usr/local/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

       faxmail formats a mail message according	to the following rules:	 First
       it  parses the envelope information interpreting	any meta-header	infor-
       mation (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.

       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	resul-
       tant  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  pa-
       rameter;	 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  di-
       rective;	 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 ex-

       X-FAX-Headers: clear Message-id Date To Subject From Cc

       will cause headers to be	emitted	in the order ``Message-Id Date To Sub-
       ject  From  Cc''	(depending on what headers are present).  Note in par-
       ticular 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 fi-
       nal 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''.

       faxmail parses MIME mail	messages and does some rudimentary work	to:

       o  decode encoded parts,

       o  formats the message and text parts into a Postscript document

       o  insert ``digest dividers'' between multipart/digest subparts,

       o  format message/rfc822	parts as described above for the top-level en-
	  velope, and

       o  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/post-
       script,	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 MIME body  part
       with type T and subtype S faxmail 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 Hy-
       laFAX.  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(5F).  mechanism  to	 convert  file
       formats into one	of the format HylaFAX supports.

       The  builtin  handling support is as follows: text/plain	parts are for-
       matted using the	default	text font and point size; multipart/mixed  are
       ``burst''  and  interpreted per the specification but are otherwise un-
       formatted; multipart/digest are burst  and  an  optional	 ``digest  di-
       vider'' marking may be inserted before each subpart; message/rfc822 are
       formatted as described above with envelope header lines culled and for-
       matted  with  bold  and italic fonts (in	addition, if there is insuffi-
       cient 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/col-
       umn);  application/postscript  are copied through untouched to the out-
       put; 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.

       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	 iden-
       tity; typically from information	extracted by the mail transport	facil-
       ity.  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  mes-
       sage  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  con-
       figuration  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.

       -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  mar-

       -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-

		 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 ab-
		 breviation of an entry	in the	pagesizes(5F)  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	deliv-
		 ery.	By  default the	user is	specified by the MailUser con-
		 figuration 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 process-
		 ing.  Diagnostic information is written to the	standard error
		 (envelope and MIME processing)	and standard output (job  sub-

       -W width	 Use  width  as	the width, in inches, of the output page.  The
		 default page width is taken from the default page size.

       faxmail	reads  configuration  information  from	 the  files   /usr/lo-
       cal/lib/fax/hyla.conf,	 /usr/local/lib/fax/sendmail.conf,    /usr/lo-
       cal/lib/fax/faxmail.conf, and ~/.hylarc;	in that	order.	 Configuration
       files  follow the conventions described in hylafax-client(1).  In addi-
       tion to the formatting configuration parameters below, all of  the  pa-
       rameters	listed in the sendfax(1) man page apply	as well.

       The  following  configuration parameters	are recognized to support for-
       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 in-
       terpreted as points.

       The configuration parameters are	explained below.  Most parameters cor-
       respond 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 typi-
		      cally 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  lo-
		      cated; by	default	/usr/local/lib/afm.

       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	 spec-
		      ify the order that they should be	emitted	in the format-
		      ted 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

       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  op-

       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  mes-
		      sage.   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 re-

       MIMEConverters The pathname of a	directory hierarchy that  has  scripts
		      for external processing of MIME body parts.  The default
		      pathname is /usr/local/sbin/faxmail.

       Orientation    Control whether pages are	oriented horizontally (``land-
		      scape'')	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 re-
		      verse 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 indi-
		      cates 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  /usr/lo-

       TabStop	      Set the tab stop distance	(in characters).

       TextFont	      Set  the name of font to use for setting text.  (Equiva-
		      lent 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.

       Because a sender's identity in an electronic mail message is inherently
       untrustworthy, using faxmail to build a mail to fax gateway is problem-
       atic.   Unless mail service is somehow restricted or the	sender's iden-
       tity 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.

       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
       /usr/local/lib/fax/pagesizes	  page size database
       /usr/local/lib/fax/	  POSTSCRIPT prologue
       /usr/local/lib/fax/hyla.conf	  system-wide configuration file
       /usr/local/lib/fax/faxmail.conf	  system-wide configuration file
       /usr/local/lib/fax/sendfax.conf	  system-wide configuration file for direct delivery
       /usr/local/sbin/faxmail		  hierarchy for	external MIME converters
       /usr/local/lib/afm		  for font metrics
       /var/spool/hylafax/tmp/faxmailXXXXXXtemporary files

       hylafax-client(1), textfmt(1), sendfax(1)

				 July 22, 1996			    FAXMAIL(1)


Want to link to this manual page? Use this URL:

home | help