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