                     Ripley's Finger Daemon
                           Version 1.0

                         by Mike Ripley

           Copyright (c) 1995 Brigham Young University


THIS SOFTWARE IS AVAILABLE FOR USE BY ANY PERSON OR ORGANIZATION FREE OF
CHARGE.  IF YOU WANT TO USE OR INCLUDE IT IN A COMMERCIAL PRODUCT, YOU
MUST OBTAIN A LICENSE FROM BRIGHAM YOUNG UNIVERSITY.  THIS SOFTWARE IS
PROVIDED ON AN AS-IS BASIS, WITHOUT WARRANTY OF ANY KIND OR DESCRIPTION
EITHER EXPRESS OR IMPLIED.  YOU MAY DISTRIBUTE THIS SOFTWARE PROVIDED
THAT YOU DO NOT CHARGE ANY MONEY FOR IT, AND PROVIDED THAT ALL OF THE
ORIGINAL FILES ARE INCLUDED, UNMODIFIED, IN THE ORIGINAL ARCHIVE, WITH
THIS STATEMENT INTACT.


INTRODUCTION
-------------------------------------------------------------------------

Ripley's Finger Daemon is a server for the Finger User Information
Protocol.  It is an NLM that can be run on a Novell NetWare 3.1x or 4.x
(bindery emulation) file server.  Ripley's Finger Daemon is FREE, and
includes the following features (most are optional or can be configured
in some way):

  +  Scans for matches in full names as well as usernames.
  +  Allows wildcard searches.
  +  Support for "-l" switch from client.
  +  Parses full names of the format: Full Name,Building Info,Phone Info
  +  Support for list of all users currently logged in.
  +  Support for _PROJECT and _PLAN files.
  +  Screen output configurable, from none up to verbose.
  +  File logging configurable, from none up to verbose.
  +  Support for David Harris' Pegasus Mail.
  +  Can use HOME_DIR property (as set by David Harris' SETHOME utility).
  +  Can use a file to map station addresses to descriptive names.
  +  Multi-threaded design:
            +  Can service multiple requests concurrently
            +  Maximum number of concurrent threads configurable.
  +  Use of non-blocking sockets:
            +  Prevents server from waiting indefinitely on misbehaved
               client.
            +  Send and receive timeouts configurable.

For those unfamiliar with the Finger protocol, it is a simple protocol
which provides and interface to a remote user information program.  A
user running a finger client sends a query, which in the case of a
command-line client is typically of the format

     finger searchname@host.

The specified host then replies with information on any users that match
the search name.  If no search name is given, then the host replies with
brief information on all users currently logged in.  A user is typically
considered to match the search name if the username or a portion of the
full name (i.e. first name or last name) is identical to the search name. 
Here are a few examples of finger client commands, and the response from
Ripley's Finger Daemon (running on the NetWare server with the host name
"test.et.byu.edu").

Client command:
---------------

finger ripley@test.et.byu.edu

Server response:
----------------

Login name: ripley                     In real life: Stacey Ripley
Directory: user:users/ripleys
Last login Feb  5 22:37
No plan.

Login name: ripleym                     In real life: Mike Ripley
Bldg: 405 CB                            Phone: x8-5960
Directory: user:users/ripleym
On since Jul 26 10:57 on connection 25 from Mike's PC (405 CB)
2 new mail messages.
Project: This finger daemon.
No plan.

Client command:
---------------

finger @test.et.byu.edu

Server response:
----------------

Username        Name                 Conn When       Bldg.        Phone
pagem           Marc Allen Page      8    Thu 10:42
printmon        (Name not given)     9    Wed 16:54
kirbyj          J A. Kirby           12   Thu 10:41
geos            GMS software develop 13   Thu 10:50  304 CB       x8-5713
barlowd         Danielle Barlow      14   Thu 10:38
...

Note that for some users, a building and phone number are shown.  This
will happen when the user's full name is of the form

     Full Name,Building info,Phone info.

For example, my full name on our NetWare server is set to

     Mike Ripley,405 CB,x8-5960.

Finally, Ripley's Finger Daemon supports the "-l" switch, typically
specified in the client command by something like

     finger -l @test.et.byu.edu.

When such a command is received, Ripley's Finger Daemon will return a
list of all users currently logged in (as in the second example above),
but the information will be in the longer format (as in the first example
above).


SYSTEM REQUIREMENTS
-------------------------------------------------------------------------

Ripley's Finger Daemon requires the following:

  +  Novell NetWare 3.1x or 4.x
  +  If NetWare 4.x, then you must use bindery emulation.
  +  TCPIP NLM (from Novell).

I developed this finger daemon primarily for our NetWare 3.12 server,
which as of this writing uses CLIB.NLM version 3.12h, and TCPIP.NLM
version 2.02m.  That is the configuration under which I developed and
heavily tested the program.  I designed it to work with NetWare 4.x using
bindery emulation, and have tested it to a lesser degree on NetWare 4.0
and 4.1 servers.


LOADING THE FINGER DAEMON
-------------------------------------------------------------------------

To use Ripley's Finger Daemon, first copy the FINGERD.NLM and FINGERD.INI
files supplied with this file into the server directory of your choice
(usually SYS:\SYSTEM).  The FINGERD.INI that I have provided contains all
of the default settings.  If you wish to change any of these settings,
then use a text editor to edit the copy of FINGERD.INI that you just
made, and change the appropriate lines as desired (see the
"INITIALIZATION FILE SETTINGS" section below).

Now make sure that TCP/IP is properly configured on your server, and then
load FINGERD.NLM from the server console prompt.  The command line to
start Ripley's Finger Daemon is:

     load [path]fingerd.nlm [-i ini_file]

where the portions shown enclosed in brackets are optional.  You do not
need to supply the path to FINGERD.NLM unless you have copied it to a
location other than SYS:\SYSTEM (and which is not on the "search path"). 
If you want the finger daemon to use an initialization file other than
SYS:\SYSTEM\FINGERD.INI, then use the -i switch, followed by the full
path and file name of the initialization file.

Example command lines are:

     load fingerd.nlm
     load sys:\misc\fingerd.nlm
     load fingerd.nlm -i sys:\config\myfinger.ini


INITIALIZATION FILE SETTINGS
-------------------------------------------------------------------------
The FINGERD.INI file that comes with this documentation contains all of
the default settings for Ripley's Finger Daemon.  You can modify these
settings by using a text editor to change the appropriate lines in the
FINGERD.INI file that will be used.  Details on each setting are provided
below.  When Ripley's Finger Daemon is loaded, it will report any non-
default settings that you have specified as a means of verifying your
changes to FINGERD.INI.

Note that the FINGERD.INI is similar in format to a Microsoft Windows
.INI file, only a little more rigid.  It consists of sections, keys, and
values, which appear as follows:

[Section 1]
key1=value1
key2=value2

[Section 2]
key1=value1
key2=value2

etc...

The section names and key names are CASE SENSITIVE, and should not need
to be changed; you should only change the "values".  Also, no white space
is allowed before or after the "=", and a blank line must occur between
sections (and should not occur elsewhere, since it signals the end of a
section).  The ordering of sections, or of key/value pairs within a
section, is not important.  If a key/value pair is removed, or if the
FINGERD.INI file is completely absent, then default values are assumed.

Now on with the settings:

[Main]
Maximum Concurrent Requests Serviced=n

     Ripley's Finger Daemon begins a new "thread" (process, line of
     execution) for each finger request that it receives.  In this
     setting, n specifies the maximum number of threads that will be
     allowed to run at one time.  If a request arrives, and the maximum
     number of finger daemon threads is already running, then that
     request will be forced to wait until another thread finishes.  The
     default value for this setting is 3.  It can range from 0 up to 999. 
     The special value 0 means that there will be NO LIMIT on the number
     of concurrent threads.

Refuse List Requests=Yes/No

     This setting determines whether requests for a list of all users
     currently logged in are honored.  Such requests are typically
     generated when the person using the finger client specifies a host
     name but no user name.  By default, this setting is set to "No"
     (meaning DON'T REFUSE such requests).  If you do NOT wish to honor
     such requests, set this to "Yes".

Check Username Only=Yes/No

     By default (when this setting is "No"), when Ripley's Finger Daemon
     receives a finger request where a search name is specified, the
     finger daemon first checks for a matching username on the file
     server, and then also checks the full names of all accounts on the
     server for a match.  Each portion of the full name, as separated by
     white space (i.e. first name, middle initial, then last name), is
     checked for a match.  If this setting is "Yes", then only the
     username is checked for a match.

Allow Wildcards=Yes/No

     If Ripley's Finger Daemon receives a finger request with a wildcard
     character (* or ?), and this setting is "No" (the default), then no
     match is returned.  If the setting is "Yes", then any usernames
     matching the wildcard expression are returned.  Note that in the
     case of a request with a wildcard, full names are NOT checked,
     regardless of the value of the "Check Username Only" setting
     described above.

Show Project File=Yes/No

     By default, this setting is "No".  If it is "Yes", then when a
     user's information is reported, Ripley's Finger Daemon looks for a
     file named _PROJECT in the user's NetWare mail directory
     (SYS:\MAIL\<userid>).  If the "Use Home Directory Property" setting
     is "Yes" (see below), then the finger daemon also checks for
     _PROJECT in the user's home directory, as indicated by the HOME_DIR
     property.  The HOME_DIR property can be set using David Harris'
     SETHOME utility.  If the _PROJECT file is found, then the first line
     of it is shown as the user's "project".

Show Plan File=Yes/No

     By default, this setting is "No".  If it is "Yes", then when a
     user's information is reported, Ripley's Finger Daemon looks for a
     file named _PLAN in the user's NetWare mail directory
     (SYS:\MAIL\<userid>).  If the "Use Home Directory Property" setting
     is "Yes" (see below), then the finger daemon also checks for _PLAN
     in the user's home directory, as indicated by the HOME_DIR property. 
     The HOME_DIR property can be set using David Harris' SETHOME
     utility.  If the _PLAN file is found, then its entire contents are
     shown as the user's "plan" (up to the number of bytes specified in
     the "Plan Size Limit" property, described below).

Plan Size Limit (Bytes)=n

     In this setting, n specifies the maximum number of bytes of a user's
     _PLAN file that the finger daemon should report.  In other words,
     if the user's _PLAN file is larger than n bytes, then only the first
     n bytes will be shown.  The value for n can range from 0 to 
     100000000.  The value 0 means that there is no limit.  The default
     value is n=1024.

[Output]
Screen Log Level=n

     In this setting, n specifies the level of screen logging that will
     occur, and can range from 0 to 2.  If the value is 0, then Ripley's
     Finger Daemon does not have its own screen, otherwise it does.  If
     the value is 1, then only warnings and errors are reported on the
     finger daemon screen.  If the value is 2, warnings and errors are
     shown, as well as detailed information on each request that is
     received.  The default setting is n=2.  Regardless of this setting's
     value, error messages are always reported to the server console
     screen, accompanied by a "beep".  When Ripley's Finger Daemon has
     its own screen (n=1 or n=2), it maintains some statistics at the top
     of that screen (see "FINGERD STATISTICS" below).

File Log Level=n

     In this setting is similar to the "Screen Log Level" described
     above, except that n specifies the level of file logging.  If the
     value is 0, then Ripley's Finger Daemon does not use a log file,
     otherwise it does.  If the value is 1, then only warnings and errors
     are recorded in the log file.  If the value is 2, then warnings and
     errors are recorded, as well as detailed information on each request
     that is received.  The default value is n=0.  The location and name
     of the log file is determined by the "Log File" setting, described
     next.

Log File=file

     Assuming that the "File Log Level" setting described above is non-
     zero, this setting determines the location and name of the log file
     to be used.  The default value is SYS:SYSTEM/FINGERD.LOG.  At the
     time Ripley's Finger Daemon is loaded, it makes sure that it can
     append to this file (creating it if it does not already exist), and
     flags the file shareable.  After that, during normal operation, if
     the finger daemon is unable to append a log entry to the file, it
     fails silently.

Log Time Format=format string

     This setting determines in what format the date and time will appear
     when Ripley's Finger Daemon logs an event to the screen or log file. 
     The string can contain any of the format specifiers used by the ANSI
     C function "strftime()", among the more useful of which are:

          Format specifier    Substitutes

               %a             Abbreviated weekday name
               %b             Abbreviated month name
               %c             Date and time
               %d             Two-digit day of the month (01 - 31)
               %H             Two-digit hour (00 - 23)
               %I             Two-digit hour (01 - 12)
               %m             Two-digit month (1 - 12)
               %M             Two-digit minute (00 - 59)
               %p             AM or PM
               %S             Two-digit second (00 - 59)
               %x             Date
               %X             Time
               %y             Two-digit year without century (00 -
                              99)
               %Y             Year with century

     Ordinary characters are displayed unchanged.  The default setting
     is "%m/%d %H:%M  " (the trailing spaces may not be obvious in the
     default FINGERD.INI file, since there the value is not surrounded
     by quotes).  The value given for this setting will be truncated to
     31 characters, and the resulting date/time string will be truncated
     to 31 characters.

[Network]
Socket Receive Timeout (Seconds)=n

     Ripley's Finger Daemon uses non-blocking sockets, which enables it
     to close down a connection from a client that stops sending its data
     (i.e. it's request) prematurely.  This setting determines the number
     of seconds that the finger daemon will wait for more data before
     closing down the connection.  The value can range from 5 to 300
     seconds, with the default being 30.

Socket Send Timeout (Seconds)=n

     Ripley's Finger Daemon uses non-blocking sockets, which enables it
     to close down a connection from a client that stops receiving data
     from the finger daemon prematurely.  This setting determines the
     number of seconds that the finger daemon will wait to be able to
     send more data before closing down the connection.  The value can
     range from 5 to 300 seconds, with the default being 30.

[Mail]
Use Pegasus Mail Properties=Yes/No

     The default for this setting is "No".  If it is "Yes", then Ripley's
     Finger Daemon will include some Pegasus Mail information when
     reporting on a user.  First, it will report the number of new mail
     messages, up to the limit specified by the "New Messages Limit"
     setting, described below.  Second, if the user has his/her mail
     forwarded, the finger daemon will indicate where it is forwarded to.

New Messages Limit=n

     If the "Use Pegasus Mail Properties" setting described above is
     "Yes", then this setting determines the maximum value that Ripley's
     Finger Daemon will report for the number of new messages.  This
     value can range from 0 to 100000, with the default being 100.  The
     value 0 means that there should be no limit.  The reason for this
     setting is that the finger daemon determines the number of new
     messages by counting the number of *.CNM files in the user's NetWare
     mail directory.  Theoretically, this number could be quite high.

[Misc]
Stations INI File=file

     By default, the value for this setting is "(None)".  If it is
     changed from that to the name of a real file (such as
     SYS:\SYSTEM\STATIONS.INI), then Ripley's Finger Daemon will use that
     file to map station addresses (i.e. Ethernet or "MAC" addresses) to
     descriptive names.  Included in this archive is an example
     STATIONS.INI file that shows the format.  The format is the same as
     for FINGERD.INI, and the caveats described above for that file apply
     here as well.  The station address (to the left of the "=" sign)
     must be a 12 digit, lower-case hexadecimal number, such as
     0000c00f192c.  If an entry for a station is not found (or if no
     mapping file is specified), then the finger daemon will just report
     the station address.

Use Home Directory Property=No

     By default, the value for this setting is "No".  If it is set to
     "Yes", then Ripley's Finger Daemon will use the HOME_DIR bindery
     property, which can be set using David Harris' SETHOME utility. 
     Setting the value to "Yes" will have two effects.  First, the home
     directory path (if any is found) will be reported as part of the
     information about a user.  Second, if either of "Show Project File"
     or "Show Plan File" are set to "Yes", the finger daemon will also
     look in the home directory (if any) for the _PROJECT or _PLAN file.


FINGERD STATISTICS
-------------------------------------------------------------------------

When Ripley's Finger Daemon has its own screen on the file server (i.e.
when "Screen Log Level" is set to 1 or 2), it maintains a few statistics
at the top of that screen.  The statistics have the following meanings:

Current requests:   The number of finger requests that the finger
                    daemon is currently working on.

Peak:               The peak number of concurrent outstanding finger
                    requests since the finger daemon was loaded.

Delayed:            The number of times since the finger daemon was
                    loaded that a finger request has been delayed
                    because it had to wait for another request to
                    finish (i.e. due to limit on number of threads).

Total serviced:     The total number of finger requests that have been
                    serviced since the finger daemon was loaded.


FINAL COMMENTS
-------------------------------------------------------------------------
This finger daemon does NOT support the forwarding of finger requests,
which typically occurs when a client command such as

     finger searchname@host1@host2 ...

is used.  If such a request is received, a refusal message is sent in
reply.

For those who are interested, I have included a copy of RFC 1288
(RFC1288.TXT) in this archive.  This RFC is the newest that I know of
dealing with the finger protocol.

If you try out this finger daemon, I would enjoy hearing from you.  My
e-mail address is ripleym@byu.edu.  Feel free to send any comments,
suggestions, bug reports, etc. to that address.

Enjoy,

Mike Ripley
Systems Manager, College of Engineering and Technology
Brigham Young University
