HylaFAX Home
Download HylaFAX
About HylaFAX
HylaFAX Howto
HylaFAX Setup
HylaFAX Links
HylaFAX Frequently Asked Questions
HylaFAX Mailing List
HylaFAX Search
HylaFAX Troubleshooting

HYLAFAX(1)                                             HYLAFAX(1)

       HylaFAX  - introduction to HylaFAX client applications and

       sendfax [options] [files...]
       sendpage [options] [message...]
       faxstat [options]
       faxrm [options]
       faxalter [options] jobid...
       fax2ps [options] [files...]

       HylaFAX is a telecommunication system  for  UNIX  systems.
       Among the features of HylaFAX are:

       o  HylaFAX  runs  as a network service; this means a modem
          may be effectively shared by a large number of users.

       o  HylaFAX can be configured to work with a  wide  variety
          of modems on a wide variety of systems.

       o  Access  to the system can be restricted by the adminis-
          trator to selected hosts and/or users.

       o  Transmission  requests  may  be  processed  immediately
          (default)  or queued for processing at a later time, in
          the manner of the at(1) command.

       o  Remote facsimile machines may  be  polled  to  retrieve
          publicly available documents.

       o  POSTSCRIPT  and  TIFF  Class  F  documents  are  passed
          directly to the fax server for transmission; the system
          attempts  to  convert  other  file  formats  to  either
          POSTSCRIPT or TIFF through the  use  of  an  extensible
          file  typing and conversion facility.  In normal opera-
          tion ASCII-text, troff(1) output, and Silicon  Graphics
          images  are  automatically  converted.  Additional file
          formats can be added; see typerules(5F).

       o  The faxcover(1) program can be automatically invoked to
          create  a cover page for each facsimile, using informa-
          tion deduced by the  sendfax  command.   Alternatively,
          users may supply their own cover pages using their pre-
          ferred tools.

       o  Facsimile are normally imaged in a system-default  page
          size (usually letter-size pages, 8.5" by 11", for sites
          in North America).  Alternate page sizes can be  speci-
          fied  with  a  -s option to all HylaFAX programs.  Well
          known page sizes include: ISO A3, ISO A4, ISO  A5,  ISO
          A6,  ISO  B4,  North  American  Letter, American Legal,
          American Ledger, American Executive,  Japanese  Letter,

                           May 8, 1996                          1

HYLAFAX(1)                                             HYLAFAX(1)

          and  Japanese Legal.  Note that it may not be permissi-
          ble to image into the full page  area;  the  guaranteed
          reproducible  area  for  a  page  is typically smaller.
          Also, note that while arbitrary page sizes can be spec-
          ified,  only  a  limited  number of page dimensions are
          supported by the facsimile protocol.  Thus if  an  odd-
          size facsimile is submitted for transmission it may not
          be possible to determine if it can be  sent  until  the
          fax  server  establishes  communication with the remote
          facsimile machine.

       o  Facsimile can be sent at low resolution (98 lines/inch)
          or  medium  resolution  (196  lines/inch)--often called
          fine mode.  Documents with mixed resolution  pages  are
          handled correctly.

       o  Users  are notified by electronic mail if a job can not
          be transmitted.  It is also possible to receive notifi-
          cation  by  mail when a job has been completed success-
          fully and each  time  that  the  job  is  requeued  for
          retransmission.    Any   untransmitted   documents  are
          returned to the sender by electronic  mail  in  a  form
          suitable for resubmission.

       o  Support  is  provided  for broadcasting facsimile.  The
          HylaFAX server software optimizes preparation of broad-
          cast  documents and the client applications support the
          notion of a job group which permits a group of jobs  to
          be manipulated together.

       o  Support is provided for transmitting alpha-numeric mes-
          sages to pager devices or GSM mobiles using the  Simple
          Network  Paging Protocol (SNPP) and the IXO or UCP pro-
          tocol (for message delivery).

       The HylaFAX software is divided into two  packages:  soft-
       ware used on client machines and software used on machines
       where  one  or  more  modems  reside.    Client   software

       o  sendfax, a program to submit outgoing facsimile;

       o  sendpage, a program to submit alpha-numeric messages to
          SNPP servers;

       o  faxstat, a  program  obtain  status  information  about
          HylaFAX servers;

       o  faxrm, a program to remove jobs and documents;

       o  faxalter,  a  program  to  change  parameters of queued
          jobs; and

       o  fax2ps, a program that converts facsimile documents  to

                           May 8, 1996                          2

HYLAFAX(1)                                             HYLAFAX(1)

          POSTSCRIPT so that they may be viewed with a POSTSCRIPT
          previewer or printed on a POSTSCRIPT printer (this pro-
          gram  is  actually part of the companion TIFF distribu-
          tion that is used by HylaFAX).

       Many systems also support submission of outgoing facsimile
       by  electronic  mail  and/or  graphical  interfaces to the
       sendfax program.  Such facilities are site-dependent; con-
       sult local documentation for more information.

       To  use  the  HylaFAX  client software on your machine you
       need to either  load  the  appropriate  software  on  your
       machine,  or you need to locate a machine that already has
       the client software installed and setup symbolic links  to
       the  appropriate  directories.   If you choose the latter,
       then beware that you need links to three directories:  the
       directory  where client applications reside, /usr/bin, the
       directory where  the  client  application  database  files
       reside,  /usr/share/fax,  and the directory where document
       conversion programs reside, /usr/sbin (the last two direc-
       tories may be the same on your system).

       Once  the  software  is  setup on your machine you need to
       locate a host that has a facsimile  server  that  you  can
       use.  The host, and possibly the modem on the host, should
       be defined in your environment in the FAXSERVER  variable.
       For example, for csh users,

              setenv FAXSERVER flake.asd

       or for ksh or sh users,

              FAXSERVER=flake.asd; export FAXSERVER

       If  there  are multiple modems on your server then you may
       be assigned to use a specific modem.  For example, if  you
       are  to  use  the  modem attached to the ttym2 port on the
       server machine, then  the  FAXSERVER  variable  should  be
       setup as

              FAXSERVER=ttym2@flake.asd; export FAXSERVER

       (Note: the SNPPSERVER environment variable is used instead
       of FAXSERVER  by  the  sendpage  program;   consult  send-
       page(8C) for more information.)

       Note  also,  that before you can submit outgoing facsimile
       jobs the administrator for the facsimile server  may  need
       to  register your identity in an access control list.  You
       will encounter the message ``530 User %s access  denied.''
       if  access  to  your  server is controlled and you are not
       properly registered or you may be prompted for a  password
       and then denied service with ``530 Login incorrect.''.

                           May 8, 1996                          3

HYLAFAX(1)                                             HYLAFAX(1)

       A dial string specifies how to dial the telephone in order
       to reach a destination facsimile machine.  HylaFAX permits
       arbitrary  strings to be passed to the facsimile server so
       that users can specify credit card information, PBX  rout-
       ing information, etc.  Alphabetic characters are automati-
       cally  mapped  to  their  numeric  key  equivalents  (e.g.
       ``1800GotMilk''  becomes  ``18004686455'').  Other charac-
       ters can be included for readability; anything  that  must
       be stripped will be removed by the server before the dial-
       ing string is passed to the fax modem.   Private  informa-
       tion  such  as  credit card access codes are withheld from
       status messages and publicly accessible  log  files  (with
       proper  configuration).   Facsimile servers also automati-
       cally insert any leading dialing  prefixing  strings  that
       are  required  to place outgoing phone calls; e.g. dialing
       ``9'' to get an outside line.  Additionally,  if  a  phone
       number  is  fully  specified with the international direct
       dialing digits (IDDD), then any prefixing long distance or
       international dialing codes that are required to place the
       call will be inserted in the dial string  by  the  server.
       For  example,  ``+31.77.594.131'' is a phone number in the
       Netherlands; it would be converted to ``0113177594131'' if
       the  call  is  placed  in  the  United States.  The number
       ``+14159657824'' is a phone number in California; if  this
       number  is  called  from  within  the 415 area code in the
       United States, then the server would automatically convert
       this to ``9657824'' because in the San Francisco Bay Area,
       local phone calls must not include the area code and  long
       distance prefixing code.

       The  general  rule  in crafting dial strings is to specify
       exactly what you would dial on  your  telephone;  and,  in
       addition,  the  actual  phone number can be specified in a
       location-independent manner by using  the  IDD  syntax  of
       ``+country-code local-part''.

       The  sendfax  program  can  automatically generate a cover
       page for each outgoing facsimile.  Such  cover  pages  are
       actually  created  by  the  faxcover(1)  program  by using
       information that is deduced  by  sendfax  and  information
       that  is  supplied on the command line invocation of send-
       fax.  Users may also request that  sendfax  not  supply  a
       cover  page  and then provide their own cover page as part
       of the data that is to be transmitted.

       Automatically-generated cover pages may include  the  fol-
       lowing information:

       o  the  sender's  name,  affiliation, geographic location,
          fax number, and voice telephone number;

       o  the recipient's name, affiliation, geographic location,

                           May 8, 1996                          4

HYLAFAX(1)                                             HYLAFAX(1)

          fax number, and voice telephone number;

       o  text explaining what this fax is ``regarding'';

       o  text commentary;

       o  the local date and time that the job was submitted;

       o  the number of pages to be transmitted.

       Certain  of  this information is currently obtained from a
       user's personal facsimile database file;  ~/.faxdb.   Note
       that  this  file  is deprecated; it is described here only
       because it is still supported for compatiblity with  older
       versions of the software.

       The .faxdb file is an ASCII file with entries of the form

              keyword : value

       where keyword includes:

              Name          a  name  associated  with destination
                            fax machine;

              Company       a company name;

              Location      in-company  locational   information,
                            e.g. a building#;

              FAX-Number    phone number of fax machine;

              Voice-Number  voice telephone number.

       Data is free format.  Whitespace (blank, tab, newline) can
       be freely interspersed with  tokens.   If  tokens  include
       whitespace, they must be encloseed in quote marks (``"'').
       The ``#'' character introduces  a  comment--everything  to
       the end of the line is discarded.

       Entries  are collected into aggregate records by enclosing
       them in ``[]''.  Records can be nested to create a hierar-
       chy  that  that  supports the inheritance of information--
       unspecified information is inherited from parent aggregate

       For example, a sample file might be:
              [   Company:   "Silicon Graphics, Inc."
                  Location:  "Mountain View, California"
                  [ Name: "Sam Leffler"     FAX-Number: +1.415.965.7824 ]

       which could be extended to include another person at Sili-
       con Graphics with the following:

                           May 8, 1996                          5

HYLAFAX(1)                                             HYLAFAX(1)

              [   Company:   "Silicon Graphics, Inc."
                  Location:  "Mountain View, California"
                  [ Name: "Sam Leffler"     FAX-Number: +1.415.965.7824 ]
                  [ Name: "Paul Haeberli"   FAX-Number: +1.415.965.7824 ]

       Experience indicates that the hierarchical nature of  this
       database  format makes it difficult to maintain with auto-
       mated mechanisms.  As a result it  is  being  replaced  by
       other,  more straightforward databases that are managed by
       programs that front-end the sendfax program.

       HylaFAX client applications can be tailored on a  per-user
       and  per-site basis through configuration files.  Per-site
       controls are placed in the file  /usr/share/fax/hyla.conf,
       while  per-user  controls  go in ~/.hylarc.  In addition a
       few programs that have many parameters that  are  specific
       to  their  operation  support  an additional configuration
       file; these files are identified in their manual pages.

       Configuration files have a simple format and are  entirely
       ASCII.  A configuration parameter is of the form
            tag: value
       where a tag identifies a parameter and a value is either a
       string, number, or boolean value.  Comments are introduced
       by  the ``#'' character and extend to the end of the line.
       String values start at the first non-blank character after
       the ``:'' and continue to the first non-whitespace charac-
       ter or, if whitespace is to be included, may  be  enclosed
       in  quote  marks (``"'').  String values enclosed in quote
       marks may also use the standard C programming  conventions
       for  specifying  escape  codes;  e.g. ``\n'' for a newline
       character and ``\xxx'' for an octal value.  Numeric values
       are  specified  according to the C programming conventions
       (leading ``0x'' for hex, leading ``0'' for  octal,  other-
       wise  decimal).  Boolean values are case insensitive.  For
       a true value, either ``Yes'' or  ``On''  should  be  used.
       For a false value, use ``No'' or ``Off''.

       Incoming  facsimile  are received by facsimile servers and
       deposited in a  receive  queue  directory  on  the  server
       machine.   Depending  on the server's configuration, files
       in this directory may or may not  be  readable  by  normal
       users.   The  faxstat program can be used to view the con-
       tents of the receive queue directory:
              hyla% faxstat -r
              HylaFAX scheduler on hyla.chez.sgi.com: Running
              Modem ttyf2 (+1 510 999-0123): Running and idle

              Protect Page  Owner        Sender/TSI  Recvd@ Filename
              -rw-r--    9  fax       1 510 5268781 05Jan96 fax00005.tif
              -rw-r--    8  fax       1 510 5268781 07Jan96 fax00009.tif

                           May 8, 1996                          6

HYLAFAX(1)                                             HYLAFAX(1)

              -rw-r--    2  fax       1 510 5268781 07Jan96 fax00010.tif
              -rw-r--    3  fax        +14159657824 08Jan96 fax00011.tif
              -rw-r--    2  fax        +14159657824 08Jan96 fax00012.tif

       Consult the  faxstat  manual  page  for  a  more  detailed
       description of this information.

       Received  facsimile  are  stored  as  TIFF  Class F files.
       These files are bilevel images that are encoded using  the
       CCITT T.4 or CCITT T.6 encoding algorithms.  The fax2ps(1)
       program can be used to view and print these files.  A file
       can  be  viewed  by  converting  it to POSTSCRIPT and then
       viewing it with a suitable POSTSCRIPT previewing  program,
       such   as  xpsview(1)  (Adobe's  Display  POSTSCRIPT-based
       viewer), ghostview(1)  (a  public  domain  previewer),  or
       image  viewer programs such as viewfax(1) (public domain),
       faxview(1) (another public domain  TIFF  viewer  program),
       xv(1)  (shareware  and/or  public  domain), or xtiff(1) (a
       program included in the public domain TIFF  software  dis-
       tribution).   Consult  your  local resources to figure out
       what tools are available for viewing and printing received

       HylaFAX client applications communicate with servers using
       either a special-purpose communications protocol  that  is
       modeled  after  the  Internet File Transfer Protocol (FTP)
       or, when submitting alpha-numeric pages, the  Simple  Net-
       work  Paging  Protocol (SNPP), specified in RFC 1861.  All
       client programs support a -v option that can  be  used  to
       observe  the  protocol  message exchanges.  In some situa-
       tions it may be more  effective  to  communicate  directly
       with  a  HylaFAX  server using the client-server protocol.
       This can be accomplished with  an  FTP  or  Telnet  client
       application;  though  an FTP client is recommended because
       it implements the protocol needed to obtain server  status
       information.   For  information on the server-side support
       provided with HylaFAX consult hfaxd(8C).   For  documenta-
       tion  on  the  client-server fax protocol consult RFC XXXX
       (to be filled in).

       This section gives several examples of command line usage;
       consult  the  manual pages for the individual commands for
       information on the options and program operation.

       The following command queues the file zall.ps  for  trans-
       mission to John Doe at the number (123)456-7890 using fine
       mode; the server will attempt to send it at 4:30 A.M.:
              sendfax -a "0430" -m -d  "John  Doe@1.123.456.7890"
       (the  leading ``1.'' is supplied to dial area code ``123''
       in the United States.)

                           May 8, 1996                          7

HYLAFAX(1)                                             HYLAFAX(1)

       The following command generates a one-page facsimile  that
       is just a cover page:
              faxcover -t "John Doe" -n "(123)456-7890"
                  -c "Sorry John, I forgot the meeting..." |
                  sendfax -n -d "(123)456-7890"
       (note  that  the line was broken into several lines solely
       for presentation.)

       The following command displays the status of the facsimile
       server and any jobs queued for transmission:
              faxstat -s

       The following command displays the status of the facsimile
       server and any documents waiting in the receive  queue  on
       the server machine:
              faxstat -r

       The  following command shows how to use an FTP client pro-
       gram to communicate directly with a HylaFAX server:
              hyla% ftp localhost hylafax
              Connected to localhost.
              220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
              Name (localhost:sam):
              230 User sam logged in.
              Remote system type is UNIX.
              Using binary mode to transfer files.
              ftp> dir sendq
              200 PORT command successful.
              150 Opening new data connection for "sendq".
              208  126 S    sam 5268781       0:3   1:12   16:54 No local dialtone
              226 Transfer complete.
              ftp> quote jkill 208
              200 Job 208 killed.
              ftp> dir doneq
              200 PORT command successful.
              150 Opening new data connection for "doneq".
              208  126 D    sam 5268781       0:3   1:12         No local dialtone
              226 Transfer complete.
              ftp> quote jdele 208
              200 Job 208 deleted; current job: (default).
              ftp> dir docq
              200 PORT command successful.
              150 Opening new data connection for "docq".
              -rw----   1      sam    11093 Jan 21 16:48 doc9.ps
              226 Transfer complete.
              ftp> dele docq/doc9.ps
              250 DELE command successful.
              ftp> dir recvq
              200 PORT command successful.
              150 Opening new data connection for "recvq".
              -rw-r--    4  fax       1 510 5268781 30Sep95 faxAAAa006uh
              -rw-r--    9  fax        +14159657824 11Nov95 faxAAAa006nC
              -rw----   25  fax        +14159657824 Fri08PM fax00016.tif
              226 Transfer complete.

                           May 8, 1996                          8

HYLAFAX(1)                                             HYLAFAX(1)

              ftp> quit
              221 Goodbye.

       The following command shows how to  use  a  Telnet  client
       program to communicate directly with an SNPP server:
              hyla% telnet melange.esd 444
              Connected to melange.esd.sgi.com.
              Escape character is '^]'.
              220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
              login sam
              230 User sam logged in.
              214 The following commands are recognized (* =>'s unimplemented).
              214 2WAY*   ALER*   DATA    HOLD    LOGI    MSTA*   PING    RTYP*   STAT
              214 ABOR    CALL*   EXPT*   KTAG*   MCRE*   NOQU*   QUIT    SEND    SUBJ
              214 ACKR*   COVE*   HELP    LEVE    MESS    PAGE    RESE    SITE
              250 Direct comments to FaxMaster@melange.esd.sgi.com.
              page 5551212
              250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
              250 Message processing completed.
              221 Goodbye.
              Connection closed by foreign host.

       /usr/bin/sendfax                  for sending facsimile
       /usr/bin/sendpage                 for sending alpha-numeric pages
       /usr/bin/fax2ps                   for converting facsimile to POSTSCRIPT
       /usr/bin/faxalter                 for altering queued jobs
       /usr/bin/faxcover                 for generating cover sheets
       /usr/bin/faxmail                  for converting email to POSTSCRIPT
       /usr/bin/faxrm                    for removing queued jobs
       /usr/bin/faxstat                  for facsimile server status
       /usr/sbin/sgi2fax                 SGI image file converter
       /usr/sbin/textfmt                 ASCII text converter
       /usr/share/fax/typerules          file type and conversion rules
       /usr/share/fax/pagesizes          page size database
       /usr/share/fax/faxcover.ps        prototype cover page
       /usr/share/fax/dialrules          optional client dialstring rules
       /usr/tmp/sndfaxXXXXXX             temporary files

       at(1),  fax2ps(1),  faxalter(1),  faxcover(1), faxmail(1),
       faxrm(1), faxstat(1),  sgi2fax(1),  faxq(8C),  viewfax(1),
       hylafax(5F),  dialrules(5F), pagesizes(5F), typerules(5F),

                           May 8, 1996                          9

VirtuALL Private Host Services
Report any problems to webmaster@hylafax.org

HylaFAX is a trademark of Silicon Graphics Corporation.
Internet connectivity for hylafax.org is provided by:
VirtuALL Private Host Services