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