Isofax server configuration file

 Contents of this file:
  1. Queue declarations and records
  2. Optional attributes and values
  3. Value assignment
  4. Special queue names
  5. Attribute definitions
     A. Attributes You're Most Likely to Change First
     B. Dialing Attributes
     C. Fax Server Directories and Hosts
     D. Modem Control and Usage Statistics
     E. Miscellaneous Server Configuration
     F. System Print Command
     G. Print Options for Received Faxes
     H. Print Options for Outgoing Faxes
     I. DID Configuration Attributes
     J. Permissions Variables
     K. Called-Number Database
     L. Enabling FaxInbox
	 M. Remote Faxing
     N. Managing the Growth of Logs
	 O. Archiving Job Control Files

 ------------------------------------------
 1) QUEUE DECLARATIONS AND RECORDS
 ------------------------------------------

 This file contains records describing fax server configurations.  Lines
 beginning with '# ' or ';' are comments. Blank lines are ignored.

 Each record in this file consists of a queue declaration (the
 record "keyword") followed optionally by one or more attributes or
 attribute-value pairs.  Keywords consist of numbers.  Attribute names
 must be in lower case.

 Each user declaration begins with the queue number in square brackets
 on a line by itself; for example:

                        [1]


 ---------------------------------
 2) OPTIONAL ATTRIBUTES AND VALUES
 ---------------------------------

 The record itself _optionally_ contains one or more attributes
 or attribute-value pairs. Here're examples of attribute
 value pairs:

       work_dir = /var/fax/work

 All queue configuration values are either textual, string or boolean.

 Textual values consist of a one or more words from which leading and
 trailing spaces are stripped.  A string value is identical to a textual
 value, except surrounding the value with quotation marks preserves
 leading and trailing whitespace.

 Both attributes and values are case-sensitive.  Values are limited
 to 1000 characters and must consist of a single line (no newlines).

 (For a complete description of the lexical rules and syntax
 associated with attribute-value pairs, refer to the file
 README.avlex in your distribution.)

--------------------
3) VALUE ASSIGNMENT
--------------------

 All attributes are assigned one of the following values:

    A) An _initial_ value. If you do nothing, all attributes
       automatically receive the initial values given in
       the "Attribute Definition" section below.

    B) The _default_ value given in the [default] record.  The default
       value overrides the initial value for all queues (This is explained
       thoroughly in the next section.)

    C) An _explicitly assigned_ value in a [queue-number] record,
       which overrides both the initial and default values, and applies
       only to the queue.

 In other words, attributes explicitly assigned in the [queue-number]
 record override the values given in the [default] record, which in
 turn override initial values.

 -----------------------
 3) The [default] Record
 -----------------------

 The [default] record supplies default attributes that apply to
 all fax server queues declared in the file. This greatly simplifies the
 effort required to add a new queue, since each new queue automatically
 acquires default values.  Here's a reasonable example of attributes for
 the [default] record:


  [default]
        iprinter    = postscript1
        dial_prefix = 9w
 local_phone_number = "  (415) 555-1212  "

 Note: Do not try to add or remove the [default] record using the Isofax Server
 Admin Tool.

 --------------------------------------------------------------
 4)  O P T I O N A L  A T T R I B U T E   D E F I N I T I O N S
 --------------------------------------------------------------

 This section gives the definition for attributes, their initial
 values, and the range of values that can be assigned.

                   ALL ATTRIBUTES ARE OPTIONAL.

 Keep in mind that all attributes have sensible initial values.
 This means that unless you wish to customize the behaviour
 of the fax server, you need not enter any queue records.

###########################################################################

 Initial values are indicated with "*".

 Single quotes are used when punctuating values to prevent confusion with
 literal quoatation marks.

A) Attributes You're Most Likely to Change First

local_phone_number 

				During handshaking, two fax machines exchange phone
                numbers.  This variable holds the telephone number you wish
                to send to other fax machines.  Even though ITU T.30 says
                you're not supposed to put non-numeric characters (except
                space and '+') in this string, everybody does it.  If the
                modem complains about illegal spaces, this string is
                automatically filtered for "correctness."

                Most Class 2 fax modems reject strings longer than 20
                characters (the ITU # limit).  For this reason, IsoFax
                truncates this variable to 20 characters.

                Values:

                  *none
                   string

 dial_prefix    Dialing prefix for local phone systems. Note: the prefix
                does not appear in the fax log.  To simplify operation on
                PBX systems, if the phone number dialed contains fewer than
                five digits, then DIAL_PREFIX is ignored.  (If, however,
                DIAL_PREFIX contains a "P" to enable pulse dialing the "P"
                is retained.)

                Values:

                  *none
                   text

                Examples:
                  '9w'          # Dial 9, then wait for secondary dial tone.
                  'P9w'         # As above using pulse dialing.
                  '9,,'         # Dial 9, wait to seconds, then dial number.
                  'P9,,'        # As above using pulse dialing.

 header_string  Custom Page Header on Outgoing Faxes.  The header_string
                string appears on at the top of each fax page.  It's
                maximum length is 93 characters.  The header_string value
                _must_ be enclosed in double quotes.

                Special characters:
                  '\'           # Escape
                  '#'           # When used in first column, suppresses the
                                # page header completely, resulting in a
                                # shorter page.

                Escapes:
                  '\C[number]'  # Sender's company name
                  '\D'          # Internationalized date string
                  '\T'          # Internationalized time string
                  '\d'          # Date and time in fixed format (eg: "Sun Sep
                                # 16 01:03:52 1995 PDT").
                  '\N'          # Phone number dialed
                  '\P'          # Total pages
                  '\p'          # Current page number
                  '\r[number]'  # Recipient name
                  '\s[number]'  # Sender's name
                  '\\'          # A '\' character.

                In all fields followed by "[number]" the field is
                left-justified and right-padded with spaces up to a
                maximum length of 'number', which defaults to 20.

                Internationalized time and date are dependent on your the
                locale.  When the server fetches the time and date from
                the system,  the server asserts that LC_TIME is in effect
                (see your OS manuals for more information on locale and
                setlocale behavior).  This can be through LC_ALL, LC_TIME
                or LANG in most cases; specified in order of decreasing
                precedence.  Specifying locale information is not
                necessary if the system default is acceptable.

                Values:

                  none
                  string
        *"  \d                                       IsoFax  Page \p of \P"


 dial_one
                Prepend '1' to Long Distance Numbers.  Enable prefixing '1'
                before long distance phone numbers (Useful only in North
                America).  If dial_one_first values is YES and the phone
                number is exactly 10 digits long and doesn't begin with 0,
                then dial '1' before the number.  This happens after the
                dial_prefix, mentioned above, and the '1' appears in the
                fax log.

                Values
                  *YES
                   NO

                Examples:
                  YES           # Causes the number (408) 555 1212 to
                                # be dialed as 1-(408) 555 1212.

 iprinter       Auto Printing of Incoming Faxes.  These attributes specify
 iprinter_rl    the printer name auto-printing incoming faxes.
 iprinter_hp
                The iprinter value specifies the name of a fast PostScript
                printer.

                The iprinter_rl value specifies the name of a slow PostScript
                printer, or a slow communications link to a PostScript
                printer.  Files sent to printers specified with this
                attribute are run length compressed.

                The iprinter_hp attribute specifies the name of a PCL
                (H.P. page-descripton langauge) printer.  The main drawback
                to this choice is that the "SHRINK_TO_FIT" value for the
                printer_crop attribute is not supported.  In addition, some
                PCL printers have a smaller printable area than PostScript
                printers, resulting in faxes with the bottoms chopped off.

                Values:
                  *none
                   printer-name


 

B) Dialing Attributes


 dial_postfix   Postfix for outgoing calls.  The dial_postfix value does
                not appear in the fax log.

                Values:
                  *none
                   prefix-text

                Example:
                  ',,1234'      # Dial the number, wait two seconds, then
                                # dial "1234".

 dial_substitutes
                Phone Number Substitution.  This option recognizes a string
                in a phone number, and replaces it with a substitution
                string.  Say, for example, that you are making calls from
                the 415 area code.  If a phone number begins with 415, you
                would like to replace that with nothing, so that the number
                is dialed beginning with its prefix instead of its area code.
                The number in your address book and the number showing up on
                your cover page continue to show the 415.  This can help make
                address books more 'portable' from one geographic location
                to another, and enable easy sharing of address books between
                company branches in different area codes.

                The value is a string of substitution rules separated by
                colons.  Substitution rules are two strings separated by
                whitespace.  The entire string must end with a colon:


                  '"oldstring1 newstring1:oldstring2 newstring2:"'

                If there are several matches, the first substitution is
                performed.

                Values:
                  *none
                   substition-string

                The following example removes all "415"s from numbers, and
                replaces all "+"s with "011,"s, for international calling:

                  '415 :+ 011,:'

                Note:
                  Dial substitutions are performed _before_ dial_one_first.

 allow_duplicate_dialing:
                Allow Multiple Simultaneous Calls to Same Number.  If the
                allow_duplicate_dialing value is 'YES', the same number
                may be dialed simultaneously.  This ordinarily results
                in a busy signal for all but the first call; however,
                duplicate calls should be permitted when a single number
                rolls over to a bank of many fax machines.

                Values:
                  *NO
                   YES

 dial_filter    Valid Telephone Number Characters.  The dial_filter
                value specifies the valid telephone number characters
                other than digits.  Characters that are neither digits nor
                in the dial_filter value are discarded.  The dial_filter
                must be enclosed in double quotes.

                Values:
                  *'" -+W!,@#*?"'
                   string

                Note:
                  CHANGES TO THIS VARIABLE REQUIRE A FAXD RESTART TO
                  TAKE EFFECT.

 

C) Fax Server Directories and Hosts


 Relative paths in this section are prepended with the value of the
 ISOFAXHOME variable if defined, otherwise with the directory where
 faxd is started.  With the exception of the "exec_dir" directory,
 all directories must be both readable and writable.  Permissions are
 discussed in section (J) "Permissions Variables", below.

 exec_dir       The fax server installation directory.  This directory
                does not grow.

                Note:
                  CHANGES TO THIS VARIABLE REQUIRE A FAXD RESTART TO
                  TAKE EFFECT.

                Values:
                  *'.'          # The current directory.
                  directory-path


 archive_switch Specify archiving of incoming faxes

                Values:
                  *none         # No archiving.
                   INCOMING     # Archive received faxes.
                   OUTGOING     # Archive sent faxes.
                   BOTH         # Archive both sent and received faxes.

 archive_dir     Directory for archived faxes.  This directory may grow
                very quickly.

                Values:
                  *none         # No archiving.
                   directory-path

 work_dir       Fax server work directory.  The directory where faxd queues
                outgoing faxes, maintains log files, etc.  It can grow to
                several megabytes, depending on traffic.  If you are using
                multiple outgoing queues, faxd automatically appends the
                queue number to the specified directory name if the queue
                number is 2 or greater.  For example, "faxd -q 2" by default
                uses ./work.2 as the work directory.

                Note:
                  CHANGES TO THIS VARIABLE REQUIRE A FAXD RESTART TO
                  TAKE EFFECT.

                Values:
                  *./work
                   directory-path

 license_server
                Host running the license server.

                Values:
                  *localhost
                   license-server-host

 

D) Modem Control and Usage Statistics


 These attributes control the time that the server spends testing
 modems.

 max_secs_to_spend_pinging
                Maximum Time to Spend Reconfiguring Modems.  During modem
                configuration, the fax server is unavailable to answer
                incoming calls.  Therefore, depending upon the number and
                kinds of modems in your system, you may wish to customize
                how and how often configuration occurs.  When the fax server
                powers up, it performs a full configuration of each modem.
                Every 45 seconds or so thereafter, the fax server rechecks
                ("pings") the modem to verify that it is still correctly
                configured.  This variable controls the maximum number of
                seconds the server spends checking the modems.  Modems are
                pinged in a round-robin fashion, so all are eventually
                checked.  The default value of 3 seconds is enough time to
                configure a single modem of any kind, and, in some cases,
                several modems.  Modem pinging is considered atomic--that
                is, at least one modem is pinged regardless of the value of
                this attribute.

                Values:
                  *3
                   number

 minutes_between_heroics
                The number of minutes between time-consuming "heroic"
                measures to revive an unresponding modem.  These
                heroics take several seconds--all wasted if, for example,
                the modem is simply powered off.  (When a cold modem is
                powered on, it responds to "pinging" and automatically
                receives a full configuration.) This variable determines
                how long the server waits between heroics.

                Values
                  *60
                   number

 open_delay     Milliseconds between open and close operations.  Some
 close_delay    devices such as terminal servers require delays between
                open and close operations.  As an example, a Livingston
                PortMaster typically requires both delays to be set to
                500 milliseconds (0.5 seconds).  Depending on your network
                configuration, you may need to adjust these delays.

                Values:
                  *none
                   number

 

E) Miscellaneous Server Configuration


 retries        The number of times to retry a failed call.  The number
                of retries doesn't include the first call.  The behaviour
                of this attribute is affected by the retry_nonfax_calls
                attribute discussed below.

                Values:
                  *5
                   number

 retry_interval
                The number of minutes between call retries.  The behaviour
                of this attribute is affected by the retry_nonfax_calls
                attribute discussed below.

                Values:
                  *5
                   number

 retry_nonfax_calls
                How many times (and when) the fax server retries a call
                after dialing a number that isn't answered at all or isn't
                answered by a fax machine. Usually, redialing such calls,
                ("The number you've dialed is no longer is service") is a
                waste of time.

                Values:
                   ALWAYS             # As given in the retries value.
                   NEVER              # Never reschedule.
                  *ONCE_IN_30_MINUTES # In case the number dialed did not
                                      # answer because the fax machine at
                                      # the other end is out of paper, try
                                      # once more in half an hour.


 delete_after   How long to wait, in hours, before automatically deleting
                a fax which exhausted the retry count.  The minimum is 1
                hour, and 0 means don't delete at all.

                Values:
                  *48
                   number

 delete_after_success
                How long to wait, in hours, before automatically deleting
                a fax which has been sent.  The minimum is 0 which means
                delete immediately.

                Values:
                  *0
                   number

 auto_naming    How names for incoming faxes are constructed.


                Values:
                   DOS          # Use date and time, but create PC
                                # DOS-compatible file names in the "8.3"
                                # format.  This setting, which provides
                                # 17576 unique file names per day, may be
                                # necessary for successful inter-networking
                                # between the Unix fax server and PC's.
                                # NOTE: For users who receive their faxes
                                # via the Fax Inbox, 8.3 naming can be
                                # obtained on a user-by-user basis by
                                # editing the USER_LIST.info file.
                   NO           # Use the date and time.
                  *YES          # Uses the sender's caller id (CSI). If
                                # there's no CSI, use the date and time.

 fax_queue_mute_threshold
                The number of faxes in the queue to cause the fax
                server to return 'Queue Busy' to client requests
                for fax queue information.  This attribute lets you
                control the point at which the fax server applies maximum
                computing power to transmitting faxes in the queue and no
                power reporting on them.  If the value is 0, the server
                will always return fax queue information to clients.

                Values:
                  *200
                   number


 success_fail_script
                Path to an executable that handles the success or failure
                of an incoming or outgoing fax.  The executable reads its
                input from standard input.  A sample perl script named
                success_fail.pl.proto is provided in the distribution.

                If there's no value, notification is via email.

                Values:
                  *none
                   path-to-executable


 

F) System Print Command


 printer_command
                Printer command.

                SunOS Values:
                  *'lpr -P'
                   printer-command

                Other OS Values:
                  *'lp -c -d'
                   printer-command


 

G) Print Options for Received Faxes


 printer_crop   How to handle faxes longer than 11 inches.  Note:  this
                attribute only applies to postScript printers.

                Values:
                 YES               # Suppresses printing of 2nd and subsequent
                                   # sheets.
                 SHRINK_TO_FIT     # Shrinks image to fit on an 11-inch sheet.
                 SHRINK_TO_FIT_A4  # Shrinks image to fit on an 11.69-inch
                                   # sheet.
 iprinter_script
                Path to an executable that handles printing of incoming
                faxes.  Note:  This attribute overrides all other iprinter
                values.  A sample script is included in ./utils/iprint_script.

                Values:
                  *none
                   path-to-executable


 

H) Print Options for Outgoing Faxes


 oprinter       Printer name for outgoing faxes.  Only one of the
 oprinter_rl    oprinter, oprinter_rl, or oprinter_hp may be set.  The
 oprinter_hp    oprinter attribute specifies the printer name for
                standard PostScript printers, the oprinter_rl attribute
                specifies the printer name for fast PostScript printers,
                and the oprinter_hp attribute specifies the name of a
                PCL (H.P. page description language) printer.

                Values:
                  *none
                   printer-name

 oprinter_crop  How to handle faxes longer than 11 inches.  Note:  this
                attribute only applies to postScript printers.

                Values:
                   YES          # Suppress printing of subsequent sheets when
                                # outgoing pages exceed 11 inches.
                  *none

 oconf_or_fax
                Whether to print confirmations of outgoing faxes, outgoing
                faxes, or both.

                Values:
                   B            # Print both confirmation pages and faxes.
                   C            # Print confirmation pages.
                   F            # Print faxes.
                  *N            # Print neither faxes nor confirmation pages.


 

I) DID Configuration Attributes


 did_report_currency_test
                The number of seconds allowed between the parsed DID call
                report and time of fax receipt.

                Values:
                  *30
                   number

 post_call_DID_report
                Base the did_report_currency_test on the beginning or
                the end time of the incoming fax (different DID hardware
                may identify the call at the beginning or at the end.)
                If the value is 'YES', each fax_deliver process waits up
                to did_report_currency_test/2 seconds after receiving a
                call for a call report before abandoning attempts to autoroute.

                Values:
                  *NO
                   YES

 

J) Permissions Variables


 These variables affect the permissions of files and directories
 created by the fax server.  These variables should be used only by
 experienced UNIX systems administrators.

 archive_dir_perms
 incoming_perms
 work_dir_perms
                These attributes define the permissions of the archive,
                incoming, and work directories.  Permissions are octal
                numbers following the standard UNIX convention.  See the
                chmod(1) man page for more information.

                Values:
                  *0777
                   octal-number

 umask          This attribute defines the UNIX file creation mask used by
                the fax server and its associated processes.  The file
                creation mask is used for everything except the directory
                permissions defined individually above.  See the umask(1)
                man page for more information.

 admin_user     These variables define the IsoFax Administrative account and
 admin_group    group.  The fax server must be restarted for changes to
                these variables to take effect.

                When an administrative account is defined, the fax server
                and its associated processes will only run if the effective
                uid of the fax server is either the administrative account
                or root.  If the effective uid of the fax server is root,
                it will call setuid(2) to set the real and effective uid
                of the process to the administrative account.

                When an administrative group is defined, the fax server and
                its associated processes will only run if the effective gid
                of the fax server is the administrative group, or the
                effective uid of the fax server is root.  If the effective
                uid of the fax server is root, it will call setgid(2) to set
                the real and effective gid of the process to the
                administrative group.

                Values:
                  *none
                   uid/gid

 

K)Called-Number Database


 Not all fax devices are capable of receiving high-compression (i.e.,
 two-dimensionally encoded) faxes.  Whenever a fax machine is called
 for the first time, the fax server stores that machine's
 capabilities in a database. The next time the number is
 called, the fax server knows in advance whether to up- or
 down-convert the fax file.  (For historical reasons, a fax device's
 capabilities are referred to as its DIS.)

 use_dis_database
                Enable the DIS database.

                Values:
                  *YES          # Use the DIS database.
                   NO           # Don't use the DIS database.

 dis_update_interval
                The number of _minutes_ between DIS database updates if
                the use_dis_database value is YES.

                Values:
                  *60
                   number

 dis_purge_after
                The number of _hours_ that a DIS record remains in the
                DIS database if the use_dis_database value is YES.  DIS
                records older than this value are purged from the database.
                If the value is 0, records are not purged.

                Values:
                  *720          # 30 days.
                   number

 

L) Enabling FaxInbox


 The faxinboxd daemon must be running in order to use either the Designated
 Forwarder feature or to auto-transport faxes from the inbox directory
 on the server the inbox directory on the client.

 use_faxinbox   Start the faxinboxd.

                Values:
                   NO
                  *YES

                Note:
                  CHANGES TO THIS VARIABLE REQUIRE A FAXD RESTART TO
                  TAKE EFFECT.

 

M) Remote Faxing


 The following to attributes control remote fax server spooling.  Spooling
 faxes on remote servers is problematical if the network connection is slow,
 prone to timeouts, or otherwise unreliable.

 remote_server_retry
                Whether to retry sending a fax to a remote server.

                Values:
                  *YES
                   NO

 remote_server_timeout
                The number of seconds to spend attempting to send a fax
                to a remote server.

                Values:
                  *300
                   number

 The rqfaxd daemon must be running in order to allow GUI visibility of
 faxes queued on remote servers.

 use_rqfaxd   Start the rqfaxd.

                Values:
                   *NO
                   YES

                Note:
                  CHANGES TO THIS VARIABLE REQUIRES A FAXD RESTART TO
                  TAKE EFFECT.


 rqfaxd_update_interval
                   Time in minutes in between queries to remote fax servers
                   for remote queue information. This effects the visibility
                   interval of faxes spooled on remote hosts.

                Values:
                   *4
                   number



 

N) Managing the Growth of Logs


 Note: Because considerable time is required to truncate very large logs,
 it is a good idea to keep these logs small or let them grow indefintely.

 The fax server maintains a statistical log of modem usage in a format
 suitable for analysis by software.  The log, which is in the file named
 modem_log in the work_dir directory, employs a a pseudo binary format; that
 is, a binary file written out in ASCII.  The format of this file
 is given in the file in src/mlog.h.  Two helper functions ("get" and
 "put") are provided in the file src/mlog.c.

 The fax server also maintains a log of exceptions.

 As the logs can grow quite large, two attributes allow you to set the
 maximum size indepenently.  The maximum size is given in megabytes.
 A value of -1 turns off logging and a value of 0 allows unlimited growth.

 max_modem_log
 max_exception_log

                Values:
                  *5            # Limit logs to 5 megabytes.
                   number

 log_percent_trunc
                Percentage of truncation when logs reach maximum size.


                Values:
                  *30
                   percentage-of-truncation-number

 When an outgoing fax job is completed, either successfully or
 unsuccessfully it is removed from the outgoing fax queue.  All
 pertinent information about it is appended to a "recent history" log
 named history_log in the work_dir directory. Client software uses this log
 to look at past jobs.

 The growth of the recent-history log is restrained by truncating the
 oldest records from the file and appending them to an archive
 file named history_log_archive.

 The history_archive_log always grows without limit and can be deleted
 without harm. The history_log is a binary file and must not be edited.

 history_trunc
                How many days of fax jobs to retain in the recent history
                log before being moved to the history archive.  A
                value of -1 turns off history logging and a value of 0
                allows unlimited growth.  The history archive always grows
                without limit.

                Values:
                  *14           # Retain 14 _days_ of history information
                                # in the recent history log.
                   number


 

O) Archiving Job Control Files


 Relative paths in this section are prepended with the value of the
 ISOFAXHOME variable if defined, otherwise with the directory where
 faxd is started. All directories must be both readable and writable.
 Permissions are discussed in section (J) "Permissions Variables".

 cfile_archive_switch  This boolean specifies if job control files
                       are to be archived after a fax has been sent.

                Values:
                  *false         # No archiving.
                  true          # do archiving.

 cfile_archive_dir    Directory for archived job control files .  This
                      directory may grow very quickly.

                Values:
                  *none         # No archiving.
                   directory-path