OS/2 Professional/OS2PRO194.ISO/os2/network/fingerd/fingerd.doc

Text File | 1993-09-30 | 22KB | 598 lines

                "FINGERD:  A FINGER Server for OS/2"

                       U S E R   M A N U A L

                   FIRST EDITION - August 1, 1993

               by R L Samuell  ([e-mail])



1 - GENERAL

This document is a user manual for the FINGERD program.  It
includes information of a general nature about the program as well
as specific details on features and options, program operation, files
and parameters, and program administration.

Before using the FINGERD program, please read the notices and
license in subsection 1.6.  I develop programs for several reasons:
The computing challenge, the provision of something useful for others,
the satisfaction of artistic desire, and, of course, in some cases,
the renumeration.  Please honor me as a person and my work as a
personal endeavor, and abide by the notices and license set forth in
this document.


1.1 - INTRODUCTION

FINGERD is a program that provides user information about the OS/2
system where it is running in response to a 'finger' query from
another system.


1.2 - TERMINOLOGY

FINGERD is an acronym for FINGER Daemon.  In the architecture of
client-server applications, FINGERD is also called a FINGER server
while the program making a 'finger' query is called a FINGER client.


1.3 - REQUIREMENTS

FINGERD is written in the REXX command language.

It runs under OS/2 2.0 GA with IBM's TCPIP 1.2.1 with the latest CSDs
applied.

Also, it requires the installation of the latest version of IBM's
Employee Written Software (EWS) RxSock package which may be
downloaded from any of the various Anonymous FTP sites that offer
OS/2 software.

FINGERD monitors port 79.


1.4 - OVERVIEW

Please note that if you run FINGERD on your system, then you agree
to the terms and conditions set forth in Subsection 1.6 of this
document.

FINGERD supports the following general options which are explained
in Section 3:

    /B incorporates bulletins in every reply to a client query.

    /C allows remote control of certain features.

    /L logs client access.

    /N beeps when accessed by a client.

    /R restricts access to only certain client addresses.

    /V manages the volume of messages generated in the program window.

    /X executes a program to dynamically generate a reply to a client.

Also, under certain circumstances, FINGERD treats files with the
following extensions located in its installation directory in a special
way.  These files and various program parameters are described in
Section 4:

    .BUL contain BULLETIN information.

    .CMD contain the OS/2 procedures executed to get USERID data.

    .FNG contain pre-written USERID data.

    .HST contains the list of restricted client host addresses.

    .LOG contains the history of client accesses.

See Subsection 4.3 for recovery procedures which may be required
when certain failures occur.

See subsection 5.1 for installation procedures.


1.5 - HISTORY

FINGERD 1.0 is the initial public version of this software.


1.6 - NOTICES AND LICENSE

FINGERD program is FREEWARE but that does not mean that you
are free to do whatever you want with it.

NOTICE -- COPYRIGHT 1993 by Robert L. Samuell, III
(1) -- All Rights Reserved.  Publication of this document or
           FINGERD software in whole or in part in any form,
           electronic or printed, in any forum, public or private,
           is expressly prohibited without the explicit permission
           of the author.
(2) -- The latest version of documentation for FINGERD may be
           obtained by Anonymous FTP at 138.26.65.78.

LICENSE -- TERMS and CONDITIONS
(1) -- You are not allowed to modify any portion of this program
           other than the values of variables defined in the section
           entitled 'Parameterize.'
(2) -- This program is available for you to use free of charge.
(3) -- Any distribution of this program must include both program
           and documentation, in the latest versions, unchanged.
(4) -- Commercial sale or re-sale of this program is allowed
           only with the approval of the author.
(5) -- DISCLAIMER: No warranties or guarantees are expressed or
           implied.  And the author assumes no liability for ANY damage
           or loss whatsoever arising from the use of this program.
           Furthermore, the author is under no obligation to provide
           support of any kind.  This disclaimer applies to any support
           that is provided.
(6) -- ACCEPTANCE:  By using or distributing this program, you
           agree to these terms.


1.7 - REGISTRATION

When you have installed FINGERD and intend to use it on your
system, please register your system by 'fingering' the following
user ID on the author's system from the system where you have
installed the FINGERD software:

          [e-mail]

Later, your system will be 'backfingered' to verify that FINGERD
has been installed and it will then be added to the list of
registered systems.

This will help the author keep a list of sites running the OS/2
FINGER Server for maintenance purposes.



2 - FEATURES AND OPTIONS


FINGERD provides a variety of features and configuration options
beyond those normally associated with the traditional 'finger'
function.


2.1 - BASIC QUERIES

FINGERD supports two basic types of queries from a client:
the USERID query and the NULL query.

In the USERID query case, the client sends upto 8 significant
characters of user or other identifier to the server.  If the identifier
is meaningful to the server, then it replies with a response
associated with the designated identifier.  If the identifier is not
meaningful to the server, then a response indicating that the
identifier is 'unknown' is provided.

In the NULL query case, the client sends no significant information
to the server.  And the server replies with a general response
provided by the FINGERD administrator.

See Subsection 4.1 for information on how to set up response files
for the NULL and USERID queries.

The REMOTE CONTROL query is described in subsection 2.9.


2.2 - CLIENT LOGGING

Optionally, FINGERD provides a feature that records information
associated with each client request.

This option is specified by entering the '/L' switch (without quotes)
on the command line when FINGERD is started.  This option can be
toggled ON or OFF remotely if the REMOTE CONTROL option has
been specified.

When logging has been specified, a line of information is written to
the file FINGERD.LOG for each query received by the server while
the logging feature is ON.  This .LOG information record is described
in Subsection 4.1.


2.3 - CLIENT RESTRICTION

FINGERD also provides the option for restricting replies.  This is
accomplished by using a table of potential client addresses.

In this table, each client address is represented in the form of its
standard four-number Internet host identifier, for example:

                            138.26.65.78

The FINGERD program can be configured to use this restriction
table in one of two ways:  To allow only those hosts listed in the
restriction table to finger the server or to disallow (which is to not
allow) only the listed hosts.

If only listed client hosts are to be allowed the finger privilege,
then the restriction option is specified by entering the '/Rallow'
switch (without quotes) on the command line when FINGERD is started.
This option may be abbreviated to '/Ra.'

If only listed hosts are to be refused the client finger privilege,
then the restriction option is specified by entering the '/Rdisallow'
switch (without quotes) on the command line when FINGERD is
started.  This option may be abbreviated to '/Rd.'

Restriction can be toggled ON or OFF if the REMOTE CONTROL
option has been specified but changing the intent of the table
between 'allow' and 'disallow' is not permitted.

The restriction table is built during initialization from entries in
the host file FINGERD.HST.  See Subsection 4.3.


2.4 - BULLETINS

FINGERD provides an option for incorporating one or two of three
kinds of bulletins in any reply to a client:  a HEADING BULLETIN
and/or a TRAILING BULLETIN or an ONLY BULLETIN.

Whenever the HEADING option is specified, a HEADING BULLETIN
always precedes the server's specific reply.  This option is specified
by entering the '/Bheading' switch (without quotes) on the command
line when FINGERD is started.  This option may be abbreviated to
'/Bh.'

Whenever the TRAILING option is specified, a TRAILING BULLETIN
always follows the server's specific reply.  This option is specified
by entering the '/Btrailing' switch (without quotes) on the command
line when FINGERD is started.  This option may be abbreviated to
'/Bt.'

Whenever the ONLY option is specified, an ONLY BULLETIN always
supersedes the server's specific reply.  This option is specified by
entering the '/Bonly' switch (without quotes) on the command line
when FINGERD is started.  This option may be abbreviated to '/Bo.'

The content of each type of bulletin is stored in a file with the
extension .BUL which is located in the FINGER directory.  See
Subsection 4.4.

Both HEADING and TRAILING BULLETINS may be specified.  If
specified, the ONLY BULLETIN will supersede all other types of
bulletins.

If REMOTE CONTROL is specified, then the option of including any
type of bulletin may be toggled ON or OFF.


2.6 - ACTIVITY NOTIFICATION

FINGERD provides an option for notifying the operator of the server
computer that the server has received and responded to a client
request.

This notification consists of a two-tone sequence of beeps.

This option is specified by entering the '/N' switch (without quotes)
on the command line when FINGERD is started.  The option can be
toggled ON or OFF remotely if the REMOTE CONTROL option has
been specified.


2.7 - MESSAGE MANAGEMENT

FINGERD provides an option for managing the volume of messages
generated by FINGERD in its window when the program is running.

With this option specified, various FINGERD processing is displayed
in the FINGERD window as it happens.

This option is specified by entering the '/V' switch (without quotes)
on the command line when FINGERD is started.  This option can be
toggled ON or OFF remotely if the REMOTE CONTROL option has
been specified.

This option and the logging option operate independently.  Logging
creates a permanent record of each finger request while message
management provides more information on how requests are being
handled.


2.8 - DYNAMIC RESPONSE

FINGERD provides an option for dynamically generating information
for some USERID as the result of executing a .CMD file.

The results of the .CMD file execution are sent to the client as the
response for the specified USERID.  Because of the input-output
activity associated with this process, dynamic responses for
USERIDs should be avoided except where a static response cannot
be used.

This option is specified by entering the '/X' switch (without quotes)
on the command line when FINGERD is started.  The option can be
toggled ON or OFF remotely if the REMOTE CONTROL option has
been specified.

See Subsection 4.5 for an explanation of how to set up .CMD files
used by this option.


2.9 - REMOTE CONTROL

FINGERD provides an option for remotely controlling the operation
of the FINGER server itself.

Remote control is accomplished by fingering the FINGERD host with
a dummy USERID which is a six-character password plus a one- or
two-character control code.

See Subsection 4.6 for an explanation of how to set up the control
password.  The following is a list of control codes and what they do:

         CODE                 ACTION

          C         turns OFF remote control
          L         toggles logging ON and OFF
          N         toggles notification ON and OFF
          R         toggles restrictions ON and OFF
          V         toggles verbose output ON and OFF
          X         toggles dynamic response ON and OFF

This option is specified by entering the '/C' switch (without quotes)
on the command line when FINGERD is started.  The option can be
toggled ON or OFF remotely if the REMOTE CONTROL option has
been specified.



3 - OPERATION


FINGERD operates as a server application quietly listening for a
client query.


3.1 - NORMAL

FINGERD can be started by issuing a START command from the
OS/2 command line prompt, in a .CMD OS/2 procedure file, or by
including its icon in the System Start Up folder.

Initially, the program sets the options specified when it was started
and establishes its required network initialization.

Normally, after initialization, FINGERD waits until a client connects.
It then processes the client's 'finger' request, returns a response,
and disconnects the client.

FINGERD can be terminated normally by closing the application or
keying a CONTROL-C key combination when the application window
has the keyboard focus.


3.2 - EXCEPTIONS

If, during initialization or normal operation, a networking problem is
detected, then FINGERD will signal a halt and will abort returning a
non-zero EXIT code.


3.3 - RECOVERY

Sometimes when FINGERD terminates either normally or from an
exception, it will be necessary to do some housekeeping before it
can be restarted.  This housekeeping can be accomplished through
the use of two programs:  NETSTAT and KILLSOCK.

The NETSTAT program is included with IBM's TCPIP software.
NETSTAT can be used to display the status of network socket
connections.  This status will be displayed by specifying the '-s'
switch (without the quotes) when the NETSTAT program is entered
at the command line prompt.  In reviewing this status report, you will
want to identify any 'hanging' sockets associated with port 0079.

THE KILLSOCK program is included with the RxSock package.
KILLSOCK can be used to clear any 'hanging' sockets.  This clearing
is accomplished by specifying the number(s) of any 'hanging'
sockets each separated by a space on the command line when the
KILLSOCK program is run.

These recovery procedures will be needed whenever you start
FINGERD and discover that it has aborted with some error condition.
Perform the recovery procedures and then try FINGERD again.



4 - FILES AND PARAMETERS


Various parameters and types of files control the operation of
the FINGERD program.  FINGERD parameters are REXX variables having
default values that may be modified by the user prior to program
installation.  Types of files are distinguished by their file
extension and are located in the designated FINGERD directory.  This
directory is designated by the REXX variable 'fdir' which has the
default value of 'C:\FINGER\'.  For the purposes of this section,
this directory will be called the FINGER directory.


4.1 - USER FINGER INFORMATION (.FNG)

User finger information is stored in files with the .FNG extension
located in the FINGER directory.  The file name must be the same as
the user ID for which information is to be provided. For example, the
file named OS2USER.FNG will contain information that is provided in
response to a client supplying the user ID of OS2USER.

Information provided in response to a NULL query (which is a finger
request without any user ID) or an unknown USERID query must be
contained in a file named NULL.FNG or UNKNOWN.FNG, respectively,
located in the FINGER directory.

The contents of a user finger information file may be any free-form
text information of any reasonable length.

Files with the .FNG extension should not be generated dynamically.
This may be accomplished using .CMD files and is described in
Subsection 4.5.


4.2 - CLIENT LOG (.LOG)

When the client-logging option is turned on, log information is
written to the file named FINGERD.LOG located in the FINGER directory.

One line of log information is written to the log file for each client
request received.

For each client request, a line of the log file will include the
following text fields in left-to-right order:

(1) the date and time that the client request was received,
(2) the request code,
(3) the IP client address,
(4) the client name, and
(5) the data comprising the client request.

The request code consists of a one-character alphabetic identifying
the request type which may be followed by a one-character operation
code.  The request types are designated as a NULL query (N), known
user ID (I), and unknown user ID (U).  The operation codes are
designated as client restricted by being in the list (+) or not in the
list (-), and the ONLY BULLETIN superseded the reply (!).

The FINGERD.LOG file is opened when FINGERD starts and remains open
until FINGERD ends.  The TYPE command can be used to display the
contents of the log at any time.


4.3 - HOST RESTRICTION LIST (.HST)

Entries in the file named FINGERD.HST are used during the FINGERD
initialization phase to build the client restriction table described
in Subsection 2.3.

Each line of the FINGERD.HST file contains as the first field of the
line the IP client address of the client to be allowed or disallowed.
The remainder of the line is ignored.  This field may be terminated
by a space or a tab character.

The format requirements of the FINGERD.HST file are compatible with
the format of the standard TCPIP HOSTS file.


4.4 - BULLETINS (.BUL)

Finger bulletin information is stored in text files with the .BUL
extension located in the FINGER directory.  The file name of a .BUL
file corresponds to one of the three kinds of bulletins presently
supported by FINGERD.  These bulletin file names are HEADING.BUL,
TRAILING.BUL, and ONLY.BUL.

The contents of a bulletin information file may be any free-form text
information of any reasonable length.


4.5 - DYNAMIC INFORMATION (.CMD)

User finger information is generated dynamically by files with the
.CMD extension located in the FINGER directory.  The file name must be
the same as the user ID for which information is to be provided.  For
example, the file named OS2USER.CMD will generate user information
that is provided in response to a client supplying the user ID of OS2USER.
When the .CMD file is executed, its STDOUT will be sent as
the response to the USERID query.

If both .FNG and .CMD files exist in the FINGERD directory, then the
contents of the .FNG file will be returned as the response and the
.CMD file will be ignored and not executed.

Information provided in response to a NULL query or an unknown query
may be generated dynamically by providing .CMD files with the file names
of NULL.CMD or UNKNOWN.CMD, respectively, in lieu of the
NULL.FNG and UNKNOWN.FNG files.


4.6 - REMOTE CONTROL PASSWORD

The remote control password is specified by the value of the REXX
variable 'password' in the FINGERD.CMD file.

If no remote control capability is desired, then the value of the
'password' variable must be set to the null string which is designated
by two consecutive single quotes as ''.

If the remote control capability is desired, then the value of the
'password' variable must be set to a six-digit alphanumeric string
which includes only numbers and upper case alphabetics.



5 - ADMINISTRATION


The administration of FINGERD is a relatively simple process
involving installation, maintenance, and error-handling procedures.


5.1 - INSTALLATION

The distribution set of FINGERD files includes:

    FINGERD.DOC - the file containing this document
    FINGERD.CMD - the FINGERD program
       NULL.FNG - the default null query response file
    UNKNOWN.FNG - the default unknown USERID query response file
    OS2USER.FNG - a sample USERID query response file
    HEADING.BUL - a sample HEADING bulletin file

To install FINGERD on your OS/2 system with the simplest configuration
follow these instructions:

    (1)  Verify that you are running OS/2 2.0 GA or later, TCPIP 1.2.1
           with April 1993 CSDs or later, and the latest version of
           the RxSock IBM EWS freeware package.
    (2)  Create the FINGER directory on drive C by using the MKDIR
           command to create C:\FINGER.
    (3)  Copy all files included in the FINGERD distribution set of
           files into the FINGER directory.
    (4)  Modify the default files NULL.FNG and UNKNOWN.FNG to suit
           your system needs.
    (5)  Create a USERID finger information file for each user for
           which you will provide a response to a finger request.
    (6)  Begin FINGERD by issuing the following command from the
           OS/2 command prompt:

                start c:\finger\fingerd.cmd

Configuration options you may want to consider include:

      -  Specify command line option '/L' to turn client-logging ON.
      -  Set up a different FINGER directory.
      -  Set up client restriction using a .HST file.
      -  Allow remote control of FINGERD operation.
      -  Enable audible notification of client request.


5.2 - MAINTENANCE

The only maintenance required for FINGERD if no options are specified
is the management of appropriate USERID information files.

If the client-logging option has been specified, then a periodic
check on the size of the FINGERD.LOG is recommended.


5.3 - PROBLEMS

If you have problems with FINGERD and you have registered
your system, then e-mail me at:

        [e-mail]

I cannot guarantee a timely or helpful reply but I will try.