User List Configuration Help File
Contents of this file:
1. User declarations and records
2. Optional attributes and values
3. Value assignment
4. Special user names
5. Attribute definitions
A) Administrative
admin_notify_level Filters admin's notification
server_mail_from "From" field on email from server
B) Used by All Clients
access_queue User's access to outgoing queues
access_history User's access to history log
client_type The type of client
email_address User's email address
when_to_notify When to notify of various events
how_to_notify How to notify of various events
human_name The user's "real" name
C) For PC Clients Only
hostname_override Admin-assigned hostname
winclient License for WinClient
D) Client Preference Override
alternative_faxservers Fallback fax server
billing_code Admin-assigned billing code
cover_locus Where cover sheets are made
hostname_override Admin-assigned hostname
highest_priority Scheduling priority
net_poll_interval How often to poll the fax server
server_cover_list PostScript cover sheets on server
server_cover_list_gui Descriptions of cover sheets
xmit_queue_list User's outgoing queues
xmit_queue_list_gui Descriptions of outgoing queues
E) Forwarding Attributes
forwarder User's DF directory assignments
group A grouping of users
group_gui Description of the group
fax_forwarding Enrolls user for fax-forwarding
F) Routing Attributes
routing_number User's number for autorouting
G) Delivery Attributes
delivery_dir User's faxinbox directory
delivery_dir_root Root path to user's faxinbox
delivery_method How to deliver fax to client
delivery_body_encoding How to encode delivery
delivery_file_format File format of delivery
delivery_naming How to name delivered file
H) Authorization Attributes
authorize_enable Limits who can send faxes
authorize_criteria Criteria for limiting sending faxes
hostname The hostname of the client
userid The hostname of the client
I) LDAP Info (LDAP users only)
alternative_ldapservers Fallback ldap_server hosts
ldap_bind String used for binding to LDAP server
ldap_passwd Password for LDAP authentication
ldap_server Name of host running LDAP server
ldap_search_base The base used for all LDAP queries
use_ldap Use LDAP server toggle
J) Miscellaneous
alternative_faxservers Fallback fax servers
alternative_licservers Fallback license servers
webclient_root User perms, Webclient public address book
6. Example User Records A) The Designated Forwarder Using Faxinbox B) The Designated Forwarder Using Email
C) Sun Client: Fax Delivery By MailTool
D) Sun Client: Fax Delivery By MIME
E) Windows Client: A Power User
F) Groups of Users
7. Setting up Routing: Step-by-Step
A) Via FaxInbox
B) Via Email
------------------------------------------
1) USER DECLARATIONS AND RECORDS
------------------------------------------
This file contains records describing users. Lines beginning
with '# ' or ';' are comments. Blank lines are ignored.
Each record in this file consists of a user declaration (the
record "keyword") followed optionally by one or more attributes or
attribute-value pairs. Keywords consist of letters, numerals, and
the underscore ('_') character. Letter case is not significant.
the context (yes for modems, no for users). White space,
punctuation and capitalization may be used for clarity, but
are ignored during parsing.
Each user declaration begins with the user's name in square brackets
on a line by itself; for example:
[fredb]
The next record begins with the next user name (or the end of the
file).
---------------------------------
2) OPTIONAL ATTRIBUTES AND VALUES
---------------------------------
The record itself _optionally_ contains one or more attribute
or attribute-value pairs. Here's are examples of attribute
value pairs:
human_name = Fred Bloggs # textual
routing_number = 1024 # numeric
server_cover_list_gui = " Plain ", " Fancy " # list of strings
fax_forwarding = false # boolean
These examples illustrate the various type of attributes (in this
order): textual, numeric, string, and comma-separated lists of any of
these. A boolean (true/false) value is also supported.
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
lead and trailing spaces. Because string values are intended for
use by a user interface, their names end with the suffix
"_gui" to stress their intended use.
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] pseudo-user.
This enables you to override the initial value for every
modem. (This is explained thoroughly in the next section.)
C) An _explicitly assigned_ value in a [user]
record. This enables you to customize each modem.
In other words, attributes explicitly assigned in the [user]
record override the values given by the [default] record, which in
turn overwrite initial values.
-----------------------
3) The [default] User
-----------------------
The [default] user supplies default attributes that apply to
all users declared in the file. This greatly simplifies the
effort required to add a new user, since each new user
automatically acquires default values. Here's a reasonable
example of attributes for the [default] user:
[default]
delivery_dir_root = /var/faxinboxes
cover_locus = server
server_cover_list = fancy.ps, bgreg.ps
server_cover_list_gui = Bristol Fancy, Bristol Regular
highest_priority = 3
net_poll_interval = 120
--------------------------------------------------------------
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 for a user to have
extraordinary capabilities, only small amount of information
must be entered for each user.
Although overriding initial and default values is, per se,
not required, several make good administrative sense. Here's
a reasonable template for all user entries:
[user_name]
human_name
client_type
email_address
###########################################################################
Initial values are indicated with "*".
Single quotes are used when punctuating values to prevent confusion with
literal quoatation marks.
A) Administrative Attributes
The administrative user [admin] is the user responsible for
IsoFax. The [admin] user is notified (usually by email) whenever a
variety of events occurs.
In addition to the admin-only attributes given below, [admin] may
have all the attributes of an ordinary user. The following
attributes may be assigned only to the [admin] user:
admin_notify_level Filters exception log notification according
to the severity of the error.
fatal
error
warning
notice
*none
admin_exception_volume This limits the number of exception_log email
messages sent to [admin] within any 24-hr period.
A value of 0 allows unlimited messages. There is
no initial value.
server_mail_from This string contains the "From" field when the
server sends notification by email. There is no
initial value.
smtp_host(NT only) Name of SMTP mail server used to receive email
notification.
pop_host(NT only) Name of POP3 mail server used to receive email
notification.
pop_user(NT only) Fax server account name to be used when querying
POP3 server for new mail.
pop_passwd(NT only) Fax server account password to be used when
querying POP3 server new mail.
pop_freq(NT only) The frequency that the POP3 mail server is
polled by the fax server for new mail.
mimefax_arguments The list of three arguments used by the mimefax
(NT only) fax gateway:
path to the coversheet template,
hostname of license server,
hostname of fax server
e.g. c:\ISOFAXSERVER\COVER_SHEET.PS lhost fhost
B) Attributes Used by Clients of All Types
The following attributes are listed in alphabetical order.
access_queue The access permissions this user has on
outgoing queues. Values:
all: all entries
none: no entries
*owner: those scheduled by [user_name] key
access_history The access permissions this user has on history
log. Values:
all: all entries
none: no entries
*owner: those scheduled by [user_name] key
client_type The type of client. Examples: 'win3.11',
'winnt', 'mac', 'unix-sun', etc. This is
currently for self-documentation; i.e., it is
not used programmatically.
email_address User's email address.
when_to_notify This is a comma-separated list of conditions
on which [user] receives notification. (The
method of the notification is defined by
admin's how_to_notify attribute). The
Values:
**never Turn off notification
fax_incoming On every incoming fax
fax_outgoing Onevery outgoing fax
*fax_failures On every fax failure
incoming_failures_only On every incoming fax
failure only.
fax_exception Notify on every write to
exception log.
** The initial value for the [admin] user, and
invalid for other users.
how_to_notify How to notify the user of various events
(e.g., that a fax has arrived). VALIDATED
values:
*email Send email message to the address
given in the email_address
attribute.
human_name The user's name as you wish it to appear in
GUIs (e.g., the Designated Forwarder's
list). If no human_name is given, the
Designated Forwarder will show the [user_name]
key.
C) Attributes Used only by PC Clients
hostname_override This allows the admin to assign a hostname to
replace the one formed on the PC client.
hostname_override This allows the admin to assign a hostname to
replace the one formed on the PC client.
winclient Boolean attribute that identifes user as a
winclient per-seat licensee. The initial value
is false.
D) Client Preference-Override
Attributes
The following attributes override their client-side
counterparts. The client queries the info daemon at power up to
ascertain these attributes.
alternative_faxservers A comma-separated list of alternative fax
server on which clients can attempt to queue
faxes if the primary fax server fails.
billing_code Clients use this value for billing code instead
of the one provided locally. There is no initial
value.
cover_locus A comma-separated list describing where cover
sheets are made. It can have two VALIDATED
values: 'client'; 'server'; or 'client,
'server'. Any other value or a missing value
is interpreted as 'client'. A default value is
recommended. The initial value is 'client'.
highest_priority The maximum priority at which this user is
allowed to schedule faxes. (Lower numbers have
higher priority.) Values: 1-9. The
intial value is (3).
hostname_override Refer to "Attributes Used only by PC Clients"
net_poll_interval How often in seconds that this user is allowed
to poll for the transmit queue information or
the faxinbox daemon. A default value is
recommended. VALIDATED value: greater than
zero. The initial value is 60.
server_cover_list A comma-separated list PostScript files available
to this user as cover sheets. The initial value
is 'server_cover1.ps'.
server_cover_list_gui A comma-separated list of strings
describing each cover sheet in the cover_list
attribute. The initial is 'Sample Server Cover
Sheet.'
userid_override Refer to "Attributes Used only by PC Clients"
xmit_queue_list A comma-separated list of outgoing queues into
which the user is allowed to submit faxes.
Values: 1-32.
xmit_queue_list_gui A comma-separated list strings giving GUI names
to each of the outgoing queue numbers that the
user is allowed to query.
E) Forwarding Attributes
The following attributes are presented as a group because together
they govern if and how a user participates in fax-forwarding via
the Inboxd.
Attribute Value
------------- --------------------------------------------------
fax_forwarding Boolean. This enrolls the user for fax-
forwarding; that is, human_name (if available)
or [user_name] appears in the Designated
Forwarder's list of users. The initial value is
true.
forwarder A comma-separated list of GUI strings
describing the incoming directories
for which the user is the Designated Forwarder.
An incoming directory can have only one Designated
Forwarder, although a single user may be the
Designated Forwarder for multiple directories.
Incoming directories are declared in the
MODEMS.info file; a GUI string attribute
(incoming_gui) must be declared for each
incoming directory.
group This is a comma-separated list of
[user_name] keys, which are assumed to
appear elsewhere in the USER_LIST.info. The
Designated Forwarder may forward faxes to the
entire group at once.
group_gui A GUI string describing or naming the group
(the name of the group proper is in the key
itself).
F) Routing Attributes
routing_number User's autorouting number. Currently this
number is required only if faxes are being
routed via DID (see README.did).
G) Delivery Attributes
The following attributes are presented as a group because
they govern whether and how a fax is delivered from
the fax servers's incoming directory to the client's space.
Attribute Value
------------- --------------------------------------------------
delivery_dir User's faxinbox directory; that is, where
received faxes are placed so that they are
accessible to the client. If the value is a full
path, delivery_dir completely specifies the faxinbox
directory. If the value is a relative path,
delivery_dir_root is prepended. If the attribute is
null or not specified, the faxinbox directory is
constructed from the user's name (characters
other than a-z, A-Z, 0-9, -, and _ are
stripped, and upper case characters are mapped
to lower case. See also: delivery_dir_root.
delivery_dir_root Root path to user's delivery_dir (delivery_dir_root
is ignored if delivery_dir is a full path). Useful
when setting defaults. The initial value
/faxinboxes is created in the IsoFax directory; i
i.e., $ISOFAXHOME/faxinboxes. See also: [default] user.
delivery_method The method of delivering the fax from the fax
servers's incoming directory to the client's.
Values:
*faxinbox Copy (move) fax into delivery_dir
email_body Send in body of email (see also:
delivery_body_encoding, below)
sunmail_attach (Implies uuencoding)
mimemail_attach (Implies base64 encoding)
exec Full path to a program
that handles delivery. The
program is executed with three
parameters:
1) The path to the received fax
2) The destination directory
3) The user's USER_LIST.info
entry via stdin. The
default script is route_fax,
provided in the distribution.
To substitute a different
script, use this syntax:
exec:/full/path/to/script.
delivery_body_encoding The type of encoding desired when a fax is
delivered in the message (body) of the fax.
Values:
*uuencode
base64
delivery_file_format The file format into which the fax must be
converted before delivery. If no value is
given, no format conversion is performed.
Values:
tiff_f deliver as TIFF Class F file
*g3 deliver as Bristol Fax File
delivery_naming How the selected method should transform the
format of filename. In no value is given, no
transformation is attempted. Values:
*posix: POSIX compliant file names
8.3: DOS-style file names.
H) Authorization Attributes
The following attributes are used to restrict users' ability to send
faxes.
authorize_enable This boolean determines whether the ability to
send faxes is limited to users with entries in
the USER_LIST.info file. If true, users without
a valid entry in this file are unable to queue
faxes. The initial value is false.
authorize_criteria If the authorize_enable attribute is true, it
contains a comma-separated list of the
criteria by which a user attempting to queue
faxes is qualified. There is no inital value, which
means that once authorize_enable is true, an
entry in USER_LIST.info is the sole criterion for
authorization.
Values:
exclude This user is explicitly excluded
from queuing faxes. (Useful when
an entry in USER_LIST.info is
needed for incoming faxes, but
user not allowed to send.
userid The userid of the user attempting
to send the fax. This requires
that the [user] record contain
a userid attribute.
hostname The name of the host from which
the fax is queued. This requires
that the [user] record contain
a valid hostname attribute.
email The email address of the user
sending the fax. This requires
that the [user] record contain
email attribute.
userid The client's userid
hostname The client's hostname
I) LDAP Info (LDAP users only)
The following attributes are to be intended for LDAP users only.
alternative_ldapservers
A comma-separated list of alternative LDAP
servers which clients can attempt to query
if the primary LDAP server fails.
ldap_bind String used for binding the user to the LDAP server
during the authentication process.
ldap_passwd String containing the passsword used for binding
the user to the LDAP server during the
authentication process.
ldap_server Name of host running LDAP server.
ldap_search_base The base used for all queries to the LDAP server.
use_ldap Values:
*no
yes
J) Miscellaneous
alternative_faxservers A comma-separated list of alternative fax
servers on which clients can attempt to queue
faxes if the primary fax server fails.
alternative_licservers A comma-separated list of alternative license
servers on which clients can attempt to obtain
licenses if the primary license server fails.
webclient_root This boolean determines the user's write permission
to the Webclient public address book. If false
the user can only read the Webclient public address
book. If true the user can both read and write to
the Webclient public address book.
---------------------------
6. Example User Records
---------------------------
A) The Designated Forwarder Using Faxinbox
The Designated Forwarder can be any user. In the example
below, the job of forwarding faxes is given to a Windows
user who is included on the Designated Forwarder list.
As with all PCs, this user is assigned a hostname and a
userid. Delivered faxes are converted to the DOS 8.3
format.
[rheuter]
human_name = Rhoda Rheuter
email_address = rrheuter@bg.com
client_type = win31
forwarder = General Incoming
delivery_method = faxinbox
fax_forwarding = true
userid = 126
hostname = sparrow
delivery_naming = 8.3
Since the forwarder's delivery_method is faxinbox, Rhoda
will be able to run the routing/forwarding interface in
IsoFax/MX and IsoFax WinClient.
B) The Designated Forwarder Using Email
Instead of using the FaxInbox mechanism to forward
and deliver faxes, the Designated Forwarder can elect to
receive every incoming fax as an email attachment.
[bertha dablues]
human_name = Bertha D. Blews
forwarder = General Incoming
email_address = bertha@bg.com
client_type = Sun-Solaris
delivery_method = mimemail_attach
delivery_file_format= tiff_f
Since Bertha's delivery_method is mimemail_attach she
receives all incoming faxes as MIME-encoded TIFF files.
C) Sun Client: Fax Delivery By MailTool
In the following example, William is an occasional user
who receives his faxes as MailTool attachments.
[wmakkid] # Unix login name
human_name = William Makkid
email_address = wmakkid@bg.com
client_type = unix-sun-solaris2.3
delivery_method = sunmail_attach
D) Sun Client: Fax Delivery By MIME
In the following example, Rebecca is an occasional user
who receives her faxes as MailTool MIME attachments.
[bwilnot] # Unix login name
human_name = Rebecca Wilnot
email_address = bettyw@bg.com
client_type = unix-sun-solaris2.5
fax_forwarding = true
delivery_method = mimemail_attach
E) Windows Client: A Power User
In the following example, Fred works from a PC, but is
also the IsoFax administrator. Accordingly, he has a
complicated entry. The routing_number attribute shows
that Fred receives faxes via DID; he is also a FaxInbox
recipient because faxinbox is the default delivery method.
Since he is running Windows 3.11, his faxes must be
converted to 8.3 format for delivery. As with all PCs,
a uid and hostname are assigned.
[fredb]
human_name = Fred Bloggs
email_address = fredb@frizby
client_type = win311
winclient = true
userid = 131
hostname = frizby
cover_locus = server,client
server_cover_list = fredcvr.ps
server_cover_list_gui = Fred's Cover
delivery_naming = 8.3
routing_number = 1024
when_to_notify = fax_incoming
highest_priority = 1
net_poll_interval = 10
F) Groups of Users
A user group is an arbitrary grouping of user keywords.
The value of the attribute group_gui appears on the
forwarding screen of the Designated Forwarder, and the
faxes are delivered to the users given in the attribute
group.
[Marketing]
group = bertha dablues, wmakkid
group_gui = Marketing
-----------------------------------
7. SETTING UP ROUTING: STEP-BY-STEP
-----------------------------------
A) Setting up Routing via FaxInbox
Here are step-by-step instructions for setting up fax
routing and delivery via the FaxInbox feature. The user record
[rheuter] in the Sample USER_LIST.info Records section later
in this chapter illustrates such a setup.
1. Select a user from the USER_LIST.info file to be
Designated Forwarder. (Do not select the [admin]
or [default] user.) To this user's record add the lines
forwarder = General Incoming
delivery_method = faxinbox
"General Incoming" is the default nick-name given to all
incoming directories in the MODEMS.info file.
2. When the Designated Forwarder runs IsoFax_MX or FaxManager
(in IsoFax WinClient), the Route Fax menu selection is active.
3. Selecting the Route Fax function shows two lists: on the left
are all the faxes in the General Incoming directory; on the right
are all the users whose records have the following line:
fax_forwarding = true
4. Double-click an incoming faxe to bring up the fax viewer in order
to see to whom the fax is addressed.
5. Highlight the recipient's name in the right-hand box.
6. Select Deliver or Discard. (Discarded faxes go to the
[admin] faxinbox directory).
7. Both IsoFax_MX and FaxManager have visual indicators that
inform recipient that a fax has been received. Users who
wish to be notified by email that a fax has been delivered
to their inbox should add the following line to their record:
when_to_notify = fax_incoming
The email's subject is "Faxinbox: Fax delivered to you"
8. To view the delivered faxes, the IsoFax_MX user presses
'Fax Browser' button; the FaxManager recipient clicks the
Local Inbox tab.
B) Setting up Routing via Mime Mail
Here are step-by-step instructions for setting up fax routing
and delivery via the FaxInbox feature. The user record
[bertha dablues] in the Sample USER_LIST.info Records section
later in this chapter illustrates such a setup.
1. Select a user from the USER_LIST.info file to be Designated
Forwarder. (Do not select the [admin] or [default] user.)
To this user's record add the lines:
forwarder = General Incoming
delivery_method = mimemail_attach,
"General Incoming" is the default nick-name given to
all incoming directories in the MODEMS.info file. This
causes all incoming faxes automatically to be emailed
in the Bristol fax file format to the Designated Forwarder
as MIME attachments.
2. You can view MIME faxes only if you make the appropriate
association in your MIME-compliant email reader. The MIME
tag for IsoFax is: content-type application/x-IsoFax,
and the application for viewing faxes is viewfax for
Unix, and FaxReader for Windows.
3. If your MIME-compliant email reader supports TIFF-F,
you can send the faxes as MIME-encoded multi-page TIFF
email attachment. For every user who desires this format
make the following entry:
delivery_format = tiff_f