OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / network / fingerd / fingerd.doc < prev next >

Wrap

Text File | 1993-09-30 | 21.5 KB | 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 (samuell@cis.uab.edu) 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: regist01@twinbrook.cis.uab.edu 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: samuell@cis.uab.edu I cannot guarantee a timely or helpful reply but I will try.