 ------------ Contents ------------	 Copyright  Notices  Authors  History  Synopsis Files  Making IUFINGERD Configuring IUFINGERD  Cache Sizes  Caveats  Comments     ------------	 Copyright  ------------  =    (C) Copyright 1992-1993 The Trustees of Indiana University   C    Permission to use, copy, modify, and distribute this program for F    non-commercial use and without fee is hereby granted, provided that@    this copyright and permission notice appear on all copies andG    supporting documentation, the name of Indiana University not be used H    in advertising or publicity pertaining to distribution of the programG    without specific prior permission, and notice be given in supporting B    documentation that copying and distribution is by permission of    Indiana University.  G    Indiana University makes no representations about the suitability of H    this software for any purpose. It is provided "as is" without express    or implied warranty.      ------------ Notices  ------------  E The authoritative distribution site for IUFINGERD is ftp.indiana.edu. : This is where you will find the most up-to-date version.       ------------ Authors  ------------   Indiana University University Computing Services  Network Applications Group  ' Larry Hughes & Jim Harvey - Version 3.0  Larry Hughes  - Version 2.0  Colin Fraizer - Version 1.0      ------------ History  ------------   Current Version : 3.0 " Release Date    : October 22, 1993N Comments        : Nearly a complete rewrite.  Create a QIO-driven asynchronousJ                   event loop, to fix the bug that caused server to hang inI                   V2.x.  Add support for all CLD command line options and E                   associated features.  Support for AXP architecture.    Version         : 2.0 # Release Date    : December 28, 1992 E Comments        : Cache users' real names from SYSUAF to minimize CPU A                   usage.  Other miscellaneous optimizations, some 3                   additional logging for debugging.    Version         : 1.0 $ Release Date    : September 25, 19910 Comments        : Initial release to the public.     ------------ Synopsis ------------  J IUFINGERD is a finger daemon for OpenVMS.  It will compile and run on mostG VMS systems with Wollongong's Pathway (aka WIN/TCP for VMS), Digital's  N TCP/IP Services for OpenVMS (aka UCX)), TGV's Multinet, or Process Software's  TCPWare.  6 IUFINGERD has several attractive and unusual features:  >    o It is a permanent server, requiring no process creations.A    o Caching of static UAF fields, to minimize I/O to SYSUAF.DAT. ?    o Caching of remote host information, to minize DNS queries. C    o Site-configurable output formats for list queries (using FAO). ;    o Optional RFC931 support to determine client usernames. A    o Optional display of users' forwarding,  new mail status, and        home directory information.C    o Optional support for multiple "plan" and "project" file names.      ------------ Files  ------------   README.TXT          - this file   H START_IUFINGERD.COM - runs at system statup (RUN/DETACH's IUFINGERD.COM)( IUFINGERD.COM       - runs IUFINGERD.EXE  7 MAKE.COM            - Builds the IUFINGERD distribution + IUFINGERD.CLD       - CLD for IUFINGERD.EXE 4 IUFINGERD.MMS       - MMS make file used by MAKE.COM/ MULTINET.OPT        - MULTINET MMS options file * UCX.OPT             - UCX MMS options file+ WINS.OPT            - WINS MMS options file . TCPWARE.OPT         - TCPWARE MMS options file  : ARGS.C              - IUFINGERD server C source code files CACHE.C  FUIP.C HASH.C JPI.C  MAIL.C MAIN.C NET.C  PLAN.C QIO.C  RFC931.C UAI.C  UTIL.C; UCX_IOCTL.C         - a somewhat functional ioctl() for UCX   8 IUFINGERD.H         - header file used by C source files8 UCX_COMPATIBILITY.H - header file used when built on UCX; VERSION.H           - header file containing version number      ---------------- Making IUFINGERD ----------------  = To build IUFINGERD, simply type this command in the IUFINGERD  distribution directory:   
    $ @MAKE  , The MAKE.COM accepts two optional paramters:  @    $ @MAKE    [UCX | WINS | MULTINET | TCPWARE]    [MMS | NOMMS]?                         *must be P1*               *must be P2*   D Although MAKE.COM should be able to automatically detect your TCP/IPD implementation and whether or not you have MMS, you may override the0 automatic detection by supplying the parameters.  G Successful completion of MAKE.COM will yield an executable of the form:         IUFINGERD_'arch'_'tcpip'.EXE  C where "arch" is "VAX" or "ALPHA", and "tcpip" is "UCX" or "WINS" or ? "MULTINET" or "TCPWARE".  For example, IUFINGERD_VAX_UCX.EXE or " IUFINGERD_ALPHA_MULTINET.EXE, etc.  < Rename or copy this file to IUFINGERD.EXE before proceeding.     ---------------------  Configuring IUFINGERD  ---------------------   A After you execute the MAKE.COM procedure, you'll have to edit the D IUFINGERD.COM (which runs IUFINGERD.EXE), START_IUFINGERD.COM (whichC runs IUFINGERD.COM as a detached process), and IUFINGERD.CLD (which 6 is the command language definition for IUFINGERD.EXE).  B The only change you'll probably need to make to these files, is toC correct the "SYS$NOWHERE:[NOBODY]" directory specifications.  These G unusual and probably invalid directory references are used to encourage > you to correctly configure IUFINGERD for your individual site.  I You might also wish to change START_IUFINGERD.COM to submit IUFINGERD.COM B to a batch queue, instead of running it as a detached process.  WeA prefer the latter approach, and therefore distribute it that way.   E In IUFINGERD.COM, the IUFINGERD.EXE executable can be run with any of  these command line options:    /DEBUG /NODEBUG  (default) H    Controls whether or not profuse debugging information will be written    to the log file.    /FAO="fao_string" H    The FAO (formatted ASCII output) string for the JPI information to beE    displayed in list queries.  If this qualifier is present, the /JPI G    qualifier must also be.  The default FAO is "!12AZ !30AZ !15AZ !AZ", 0    which corresponds to the default /JPI fields.  L    NOTE: You must use variations of "!AZ" for the JPI fields to be correctlyK    substituted in the FAO routines.  Variations of "!AS" or "!AD" may cause     the server to crash.   F    You may specify any "!AZ" size that you wish for any of the fields.E    If the actual field length is larger than your specified size, the G    string will be truncated.  If the actual length is shorter than your C    size, it will be padded with spaces (on the right).  The maximum <    size that any field will actually achieve is shown below:  "    Field      Max Size     Comment=    ---------------------------------------------------------- =    IMAGNAME      39        File name minus path and extension 2    LOGINTIM      11        Format is "MM/YY HH:MM"5    PID            8        Represented in hexadecimal $    PRCNAM        15        VMS limit7    REMOTE         ?        Undocumented in SYS$GETJPI() $    TERMINAL       8        VMS limit$    UAFOWNER      31        VMS limit$    USERNAME      12        VMS limit   /HEADER  (default) /HEADER=SYSTAT	 /NOHEADER G    Controls whether or not header information will be displayed in list I    queries.  Header information consists of the system nodename, date and I    uptime.  If you have Multinet or WIN/TCP, UNIX-style load averages are D    also shown.  Using /HEADER=SYSTAT displays the header in a formatF    similar to the TOPS-10/20 SYSTAT program and also requires /SORT to    be in effect.   /HOME_DIRECTORY  (default) /NOHOME_DIRECTORY @    Enables or disables the display of users' home directories in    single user queries.     /HOST_CACHE=(SIZE=size, TTL=ttl)M    Specifies the host cache configuration.  This is relevant only if you have J    specified one or more of the /RESOLVE_ADDRESSES and /RFC931 qualifiers.  J    The information that is cached for hosts is the host name (if availableL    through your DNS) and whether or not a remote system has an RFC931 daemon    running.   K    For details on the SIZE= parameter, see the section titled "Cache Sizes" $    below.  The default value is 100.  F    The TTL is the "time to live" for the cache entry, in seconds.  TheC    default TTL is 86400 (1 day).  A TTL of 0 represents an infinite 1    value, i.e. cache entries will never time out.    /JPI=(keyword[,...])H    Specifies the JPI (job process information) fields to be displayed inB    list queries.  If this qualifier is present, /FAO must also be.  H    Valid keywords are IMAGNAME, LOGINTIM, PID, PRCNAM, REMOTE, TERMINAL,J    UAFOWNER, and USERNAME.  The fields will be displayed in the order thatH    you specify them, in the format specified by the /FAO qualifier.  The:    default is /JPI=(USERNAME, UAFOWNER, REMOTE, LOGINTIM).  G    Technically, UAFOWNER is not JPI information, but IUFINGERD pretends 	    it is.   E    REMOTE is approximately equivalent to the TT_ACCPORNAM reported by A    $GETJPI.  For users connected via means other than TCP/IP, the D    REMOTE field is the unmodified TT_ACCPORNAM.  For those connectedI    via TCP/IP, it will be either the DNS host name or IP network address, A    depending on the value of TT_ACCPORNAM and the presence of the      /RESOLVE_ADDRESSES qualifier.   /LAST_LOGIN  (default)
 /NOLAST_LOGIN B    Enables or disables the display of "Last login:" or "On since:"F    information in single user queries.  Since both are never displayed5    together, this flag controls the behavior of both.    /MAIL_CHECK  (default)
 /NOMAIL_CHECK I    Controls the display of mail information on single user queries.  When F    the check is enabled, either "Has new mail" or "Has no new mail" isG    displayed, as well as the user's forwarding address (if one is set).    /PLAN=(filename[,...]) /NOPLAN G    The file name(s) to recognize as users' "plan" files.  If /NOPLAN is .    specified, no plan files will be displayed.  I    Plan files must be located in users' SYS$LOGIN directory, and readable K    through the SYSTEM file protection field.  The default plan file name is L    "PLAN.TXT".  If you specify more than one file name, the first file found3    for any given user is the one that is displayed.   
 /PORT=portK    The TCP port on which the server should listen for queries.  The default I    is port 79.  Any unused TCP port may be used for testing purposes.  If B    you select a port that is already in use, IUFINGERD will report    "error: bind" in the log.   /PROJECT=(filename[,...]) 
 /NOPROJECTJ    The file name(s) to recognize as users' "project" files.  If /NOPROJECT:    is specified, no project information will be displayed.  L    Project files must be located in users' SYS$LOGIN directory, and readableK    through the SYSTEM file protection field.  The default plan file name is I    "PROJECT.TXT".  If you specify more than one file name, the first file 9    found for any given user is the one that is displayed.    /PURGE_INTERVAL=intervalJ    The interval (in seconds) in which the host and user caches are checked8    for expired entries.  The default is 14400 (4 hours).   /RESOLVE_ADDRESSES  (default)  /NORESOLVE_ADDRESSESE    Controls whether or not the server resolves remote IP addresses to K    their respective host names.  This can add considerable time to queries, J    though an attempt is made to optimize this behavior by caching the host'    names.  See /HOST_CACHE for details.    /RFC931  /RFC931=(TIMEOUT=timeout)  /NORFC931  (default)E    Enables or disables checking of client usernames via RFC931.  When B    enabled, if the client machine is running an RFC931 daemon, theE    client username will be logged.  If it is not, the client username '    will appear in the log as "unknown."   E    You may also specify a timeout value, which represents the maximum B    number of seconds that IUFINGERD will wait for a reply from the<    remote RFC931 server.  The default timeout is 10 seconds.  G    It is not recommended that you always run IUFINGERD with this option E    enabled. It is a valuable option, however, if someone is fingering ?    your machine abusively, and you want to determine who it is.    /SORT  (default)$ /SORT=(POSITION=position, SIZE=size) /NOSORT I    Controls the sorting of user information on list queries.  By default, J    the records are sorted using the first 80 columns as the sort key.  YouI    may specify an alternate sort key with the POSITION and SIZE keywords. J    For example, you might choose to sort only on the username field, whose6    location and size you specified with /JPI and /FAO.  J    Note that the POSITION is an offset, so the first character in a record!    is position 0, not position 1.   G    /SORT or /SORT=(...) is required if you also specify /HEADER=SYSTAT.    /TIME_FORMAT=NUMERIC (default) /TIME_FORMAT=TEXT J    This specifies whether the last login date and time for list queries isK    displayed in a fixed numeric format (MM/YY HH:MM which requires at least L    11 characters) or a variable text format which uses at most 9 characters.   /TITLE="title" /NOTITLE  (default) F    Specifies a title line to be displayed above the JPI information in    list queries.    /USER_CACHE=(SIZE=size, TTL=ttl)J    Specifies the user cache configuration.  The only user information thatI    is cached is UAF data that is somewhat static, namely home directories G    and owner fields.  This minimizes the number of times that IUFINGERD     has to read from SYSUAF.DAT.   H    For details on sizing the cache, see the section titled "Cache Sizes"-    below.  The default for this value is 100.   F    The TTL is the "time to live" for the cache entry, in seconds.  TheC    default TTL is 86400 (1 day).  A TTL of 0 represents an infinite 1    value, i.e. cache entries will never time out.      Example:      $ iufingerd -      /nodebug -       /plan=(plan., .plan) - $      /project=(project., .project) -      /header=systat -       /home_directory -      /nomail_check -      /last_login -(      /jpi=(username, uafowner, remote) -      /fao="!12AZ !20AZ !AZ" - 8      /title="Username     Real Name            Remote" -"      /sort=(position=0, size=12) -      /time_format=numeric - )      /host_cache=(size=1000, ttl=86400) - %      /user_cache=(size=1000, ttl=0) -       /purge_interval=28800 -      /resolve_addresses -       /rfc931=(timeout=30)      ------------ Cache Sizes  ------------  L Although the term "cache size" might seem to be the maximum cache size, thisK is not really the case.  It is really the vertical dimension of an array of M linked lists, which is indexed by a simple (yet fast) hashing algorithm.  The M aggregate number of entries that can be cached is limited only by the virtual   memory available to the process.  K Think of each cache as an imperfect matrix; the vertical dimension is sized I absolutely by the "SIZE=" parameter, and the horizontal dimension of each   row grows dynamically as needed.  "              Grows Dynamically -->"              +--------------------"        ^     | 0,0  0,1  ...   0,c"        |     | 1,0  1,1  ...   1,c      Sized   |        by    | .         .      SIZE=   | .          .     Parameter | .           .        |     |"        V     | r,0  r,1  ...   r,c"              +--------------------  H For best performance, the desired result is a matrix that becomes squareL over time.  This will happen naturally when your cache is sized appropriate.  I A "SIZE=" value that is too large may waste some memory.  A value that is G too small may waste some CPU cycles.  Neither event is tragic, but some  performance could be at stake.  L To override the default cache size parameters, run IUFINGERD with the /DEBUGI flag for a period of time. It will report the cache indices as it inserts  entries into the cache.   I If the indices are spread somewhat evenly throughout the range of zero to 3 your SIZE= value, the cache is sized appropriately.   O If many indices are duplicated frequently, increase the size and observe again.   @ If many indices are unused, decrease the size and observe again.     ------------ Caveats  ------------  K If you enable host and/or user caching, IUFINGERD can consume a great deal  I of virtual memory.  You are advised to monitor its memory usage and page   fault habits on your system.    I You may need to modify the RUN/DETACH command in START_IUFINGERD.COM for  @ your site.  Qualifiers you might wish to explicitly specify are:        /WORKING_SET=      /MAXIMUM_WORKING_SET=
      /EXTENT=   G Failure to do so could result in excessive page faulting.  We have seen H as many as 300,000 page faults per day on a heavily-fingered VAX system # with an un-tuned IUFINGERD process.   D You may also need to explicitly specify other RUN/DETACH parameters,, depending on your local SYSGEN parameters.       ------------ Comments ------------  D IUFINGERD is an unsupported program.  If you decide to use it, do soA only in strict adherence to the copyright/disclaimer shown at the C top of this file, in COPYRIGHT.TXT, and throughout the source code.   C You may send comments, questions, and bug reports via Internet mail B to iufingerd@indiana.edu, or BITNET mail to IUFINGERD@INDIANA.  WeA will respond on a time-available basis.  We do appreciate hearing 	 from you!   = Also, if you wish to be notified of future updates and/or bug @ reports, please send email to one of the addresses listed above,! and ask to be placed on the list.    Enjoy!