\input texinfo.tex
@c %**start of header
@setfilename finger.info
@settitle GNU Finger
@setchapternewpage odd
@c %**end of header

@iftex
@finalout
@end iftex

@ifinfo
This file documents the GNU Finger program.

Copyright (C) 1988, 1992 Free Software Foundation, Inc.
Program authored by Brian Fox, Dante De Lucia, and Jan Brittenson
Manual authored by Brian Fox and Jan Brittenson

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
GNU Copyright statement is available to the distributee, and provided
that the entire resulting derived work is distributed under the terms of
a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@titlepage
@title GNU Finger
@subtitle Edition 1.3, for GNU Finger version 1.37
@subtitle October 1992
@author by Jan Brittenson and Brian Fox

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 1992 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage

@node Top
@top

@ifinfo
This document describes the GNU Finger program, a utility for finding out
useful information about users on the Internet network.

@end ifinfo

@menu
* Introduction::	What can you do with Finger?
* Using Finger::	How to use Finger.
* Advanced Use::	How to get the most out of Finger.
* Security::		Security issues.
* Bug Reports::		What to do if Finger breaks.
* Installation::	Installation, configuration, and customization.
* Invoking Finger::	A short reference for the GNU Finger client.
@end menu

@node Introduction
@unnumbered Introduction
GNU Finger is a utility program designed to allow users of Unix hosts on
the Internet network to get information about each other.  It is a
direct replacement for the Berkeley 4.3 finger code, although it
produces different looking output and is designed to run on a wide
variety of systems.

@unnumberedsec Why Another Finger?

Originally, each host on the Internet network consisted of a single,
reasonably powerful computer, capable of handling many users at the same
time.  Typically, a @dfn{site} (physical location of computer users)
would have only one or two computers, even if they had 20 or more people
who used them.  If a user at site A wanted to know about users logged on
at site B, a simple program could be invoked to query the host at site B
about the users which were logged on.

With the onset of more-power-per-person computing, the mainframe has
been set aside.  A modern computing facility usually consists of one
user per host, and many hosts per site.  This makes it a trial to find
out about logged on users at another site, since you must query each
host to find out about the single user who is logged on.  If the site
had 20 hosts, you would have to invoke a finger program 20 times just to
find out who was logged on!

@cindex server
GNU Finger is a simple and effective way around this problem.  For sites
with many hosts, a single host may be designated as the finger @dfn{server}
host.  This host collects information about who is logged on to other hosts
at that site.  If a user at site A wants to know about users logged on at
site B, only the server host need be queried, instead of each host at that
site.  This is very convenient.

GNU Finger is a direct replacement for existing finger programs.  Since
the finger @dfn{protocol} (rules for communication) is very simple, GNU
Finger follows that protocol in responding to simple requests.  But GNU
Finger also implements another protocol which allows two finger programs
to exchange information in a predetermined way, which allows faster and
wider bandwidth communication.

Finger delivers information about users in varying formats, depending on
how it is invoked.  @code{finger} invoked without any options performs a
@emph{site wide} finger request, no matter which machine it has been
invoked from.  Switch arguments exist for getting the ``long'' form of
finger information and for getting information only about the local
machine.

If a user on host A wants to know about a user on host B, finger must
make a network @dfn{connection} to host B.  If host B is running a
finger program, that program is asked to relay information about the
user in question through the connection back to host A, where finger can
display it.

GNU Finger also runs a server @dfn{daemon} process on the @dfn{server} host,
whose job is to keep track of which users are logged in to local
machines.

An optional and currently unsupported feature is passing of graphic
images. This is built on the new protocol.  A user at site A (e.g. MIT)
may see the picture of a user at site B (e.g. UCSB), by typing a finger
request.  The conversion of graphic data from one format to another is
done through GNU Finger; no site need know where or how such images are
stored on any other site to be able to display those images. You should
ask your system administrator to find out whether he has chose to
include this functionality on your network.

@node Using Finger
@chapter Using Finger

@menu
* Arguments::			How the arguments are interpreted.
* Options::			Options you can include on the command line.
* Special User Names::		Some user names can return statistics.
@end menu

@node Arguments
@section Arguments to GNU Finger

The basic argument to Finger is a @var{user}@@@var{host} pair.  The
@var{user} portion is the name of the user about whom you would like
information.  The @var{host} is a machine that the user has an
account on.   When invoked in this manner, GNU Finger displays the list
of hosts that this user is currently logged in on, or, if the user is
not logged in, the last time and location that he or she was.
@var{host} may be expressed as any valid Internet address (i.e.
@dfn{dot-notation}, @dfn{host.domain}, etc).

If @var{host} is non-existent, the local host is assumed.  If @var{user}
is blank or unspecified, it is assumed that you want information about
all users.

The content and format of the output of GNU @code{finger} depends on
what is being fingered:

@table @var
@item User
Displays login information about @var{user}. If @samp{--info} or
@samp{--l} is also specified, @code{finger} will display the full name,
home directory, shell, mail forwarding, and @file{.plan} and/or
@file{.project} file. This is what the output will look like:

@example
@exdent @code{bash$ finger --info bson@@gnu.ai.mit.edu}
@exdent @code{[apple-gunkies.gnu.ai.mit.edu]}

@exdent @code{Jan Brittenson (bson)}
@exdent @code{Home: /home/fsf/bson}
@exdent @code{Shell: /usr/local/bin/bash}
@exdent @code{Mail forwarded to bson@@ai.mit.edu.}
@exdent @code{No mail.}
@exdent @code{  User     Real Name         What    Idle  TTY  Host      Console Location}
@exdent @code{bson     Jan Brittenson     fgrep          *p0 apple-gu (nutrimat.gnu.ai.)}
@exdent @code{bson     Jan Brittenson              1:57  *sb nutrimat }

@exdent @code{Plan:}
@exdent @code{	To hack GNU Finger}
@end example

The following is output, in the order listed, when asking for long
information (@samp{-l} or @samp{--info}) about a particular user:

@itemize @bullet
@item
Real and login names.
@item
Home directory.
@item
Login shell.
@item
Mail forwarding.
@item
Whether the user has any unread mail, and if so, when it was last read.
@item
Current login information, in the same format as produced by a short
finger (see below for an explanation). If the user isn't currently
logged on, then the last login time and remote host (if known) is
reported.
@item
A @file{~/.plan} file. If the file isn't readable by everyone, then a
message is printed to this effect.
@item
A @file{~/.projects} file. This file, like @file{~/.plan}, should
be readable by everyone.
@end itemize

@example

@exdent @code{bash$ finger bson@@gnu.ai.mit.edu}
@exdent @code{[apple-gunkies.gnu.ai.mit.edu]}
@exdent @code{  User     Real Name         What    Idle  TTY  Host      Console Location}
@exdent @code{bson     Jan Brittenson     fgrep          *p0 apple-gu (nutrimat.gnu.ai.)}
@exdent @code{bson     Jan Brittenson              1:57  *sb nutrimat }
@end example


Here is an explanation of what each column contains in the short
example:

@table @code
@item User
The user login name.
@item Real Name
The real name of the user.
@item What
The current or last program run by the user, depending on the system in
use. On System V Release 4, for instance, the current program is shown,
but on BSD it will be the last terminated program.
@item Idle
The time the user has been idle, as @var{hours}:@var{minutes}, or
the first 7 characters of a string such as ``14 days''.
@item TTY
The significant portion of the user's terminal connection. Exactly what
portion this is is system dependent. For example, on System V Release 4,
it might be @samp{*40} for @samp{/dev/pty/40}, while on BSD it might
be @samp{*p0} for @samp{/dev/ttyp0}. If preceded by an asterisk
(``*''), then the user allows anyone to send messages to this particular
terminal.
@item Host
The host the user is logged onto.
@item Console Location
Where the user's console is located. If logged in over the network, then
this will be the most significant portion of the remote host name if
known. A host name is always parenthesized.

@end table

In the general short output (i.e. not for a particular host), GNU Finger
lists the least idle login for a particular user on each host. A single
user often has several logins, since on some systems each window opened
creates its own login record. In addition to the least idle login, the
console login is also always listed, regardless of how long it has been
idle.

To list @dfn{all} login records for a particular, host, use the special
target @samp{.local}. For example, while the following may be part of the
general short finger listing for the host @samp{mole.gnu.ai.mit.edu}:

@example
@exdent @code{brendan  Brendan Kehoe               5:09  *p8 mole     (lisa.cygnus.com)}
@exdent @code{info     InfoMaster                 12:12  *p4 mole     (hal)}
@exdent @code{law      Jeffrey A. Law              3:52  *p7 mole     (128.110.4.17:0.0)}
@exdent @code{rms      Richard Stallman   sendmai  1:34  *p1 mole     (unix:0.0)}
@exdent @code{rms      Richard Stallman           6 days *co mole}
@end example

@noindent
The last line is the console. The following might be listed by the
command @samp{finger .local@@mole.gnu.ai.mit.edu}:

@example
@exdent @code{[mole.gnu.ai.mit.edu]}
@exdent @code{  User     Real Name         What    Idle  TTY  Host      Console Location}
@exdent @code{brendan  Brendan Kehoe               5:18  *p8 mole     (lisa.cygnus.com)}
@exdent @code{info     InfoMaster                 12:22  *p4 mole     (hal)}
@exdent @code{law      Jeffrey A. Law              4:01  *p7 mole     (128.110.4.17:0.0)}
@exdent @code{rms      Richard Stallman   sendmai  1:44  *p1 mole     (unix:0.0)}
@exdent @code{rms      Richard Stallman           23:08  *p0 mole     (unix:0.0)}
@exdent @code{rms      Richard Stallman           1 day, *p2 mole     (unix:0.0)}
@exdent @code{rms      Richard Stallman           6 days *co mole}
@end example

@item Mailing List or Alias
Expands the mailing list or alias and displays the recipients. You
always have to use @samp{--info} or (or @samp{-l}) when fingering a
mailing list or mail alias, otherwise mail aliases won't be looked up
due to the extra processing involved. This is what the output will look
like:

@example
% finger --info postmaster@@gnu.ai.mit.edu
postmaster is an alias for the following:
    Roland McGrath <roland>,
    <tower@@prep.ai.mit.edu>,
    Noah Friedman <friedman>,
    Michael I Bushnell <mib>
@end example

@item User-defined Target
Allows the remote host to display specific information, such as price
lists, literature, or weather forecasts. For example:

@example
% finger .site@@gnu.ai.mit.edu

This is the FSF GNU Project. For more information, please contact
"postmaster". For information about guest accounts, please contact
"request".
@end example

@end table


@node Options
@section Command Line Options

There are a number of command line options that you can give to GNU
Finger:

@table @samp
@item --face
@itemx -f
Ask Finger for the face of all users information has been requested
about. An explicit user list has to be provided.

@item --info
@itemx -l
@itemx -i
Display the ``long'' form of information for the users fingered. The
exact information returned depends on what finger software is run on the
remote host -- GNU Finger, for instance, returns specific information.
@samp{-l} is supplied for backwards compatibility; @code{finger} as
distributed from Berkeley has this option.

@item --brief
@itemx -b
Display the ``short'' form of information for the users fingered. This
is the opposite of @samp{--info}. 

@item --port @var{port}
@itemx -P @var{port}
Make a connection to @var{port}, which can be either a numerical port
number or a service name from @file{/etc/services}.

@item --help
@itemx -h
Print a description of all options.
@end table

@node Special User Names
@section Special User Names

You can give GNU Finger one of several ``special'' user names.  These
user names all begin with a period (@samp{.}) and instruct the receiving
finger daemon to do something that only a GNU Finger daemon can do.
Currently, the ``special'' names are:

@table @samp
@item .free
Return a list of free machines.  `Free' machines are those that have no
users logged in, or have been idle for a long time.  The information
returned makes it clear which one is true.

@item .all
Return the information about every machine that the Finger server knows
about.  @samp{.all} is equivalent to issuing the @code{finger} command
without specifying the user name.

@item .site
Returns information about the site, such as company and location.

@item .clients
Returns a list of the clients that the GNU Finger server knows about.
Also lists who is logged onto the console.

@item .faces
Return a list of the faces that this server has available.  The last
line output tells you how many lines were listed previously.

@item .local
Finger only at the specific machine. This allows finger to continue to
be useful even in the event that the server is down. It also allows you
to examine @dfn{all} the login records of a user. Normally, the server
only keeps track of the most recently active login record for each user.

@item .help
Describe services provided by the finger server.
@end table


@node Advanced Use
@chapter Advanced Use

@menu
* How Finger Works::		How things are interconnected.
* Fingerrc Scripts::		How to customize the output.
* User-defined Targets::	Targets that aren't users.
* Ports::			How Finger picks a port.
@end menu

@node How Finger Works
@section How Finger Works

GNU Finger is the collective name for a set of programs:
@table @samp
@item finger
Parses the command line and connects to the finger server,
@samp{in.fingerd}, on the @code{finger} server. Returns the output from
the server. @code{finger} connects to @code{in.fingerd} on the host
specified in the command line. This is the only program you need to know
anything about if you're a regular user. You should refer to this
program as the @dfn{finger client} to avoid possible confusion.

@item fingerd
Regularly connects to @code{in.cfingerd} on the clients specified in the
@file{fingerdir/clients} file, to obtain finger data. This client data
is saved in the file @file{fingerdir/userdata}. @code{fingerd} should
run on the host specified in the @file{fingerdir/serverhost} file.
@code{fingerd} should be started at boot time.

@item in.fingerd
Responds to @code{finger} connections through @code{inetd}. Should be
attached to the @samp{finger} service via @file{/etc/inetd.conf}.
@code{in.fingerd} behaves somewhat differently depending on what host it
runs on: on the server host it reads the @file{fingerdir/userdata}
database, on all other hosts it forwards all requests (unless
@samp{.local} is the target) to @code{in.fingerd} on the host specified
in @file{fingerdir/serverhost}.

@code{in.fingerd} reads the @file{fingerdir/userdata} database, various
system files, and makes SMTP connections to the host specified in the
@file{fingerdir/mailhost} file.

@item in.cfingerd
This is the program that responds to call-ins from @code{fingerd} by
sampling the status on the client and forwarding it to @code{fingerd}.
It should be configured to respond to the @samp{cfinger} service
specified in the @file{clients} configuration file, or port 2003 if
nothing else is specified.

@end table

@node Fingerrc Scripts
@section The @file{~/.fingerrc} Script

When the GNU Finger server receives a request for information about a
user it looks to see if the user has a @file{.fingerrc} file in the home
directory. If such a file exists, and is executable, then this file
is executed, and the normal finger output is passed to it as input.
Its output becomes what is returned for the request. Thus, it can be
used to:

@itemize @bullet
@item
Disable fingering a specific user by linking
@file{~@var{user}/.fingerrc} to @file{/bin/true}.

@item
Entirely replace the output of @code{finger} by ignoring its input. Below
is a sample script which could be put in @samp{~price-info/.fingerrc}.

@example
#! /bin/sh
#
# This sample script replaces the output of GNU Finger
#
echo Hack-O-Matic Consulting Services, Inc. "   " `date`

cat <<ETX

Hi, thanks for asking us about prices on our newly introduced support
services for Free Software. Below is a list of new services; for a list
of our previous services, please send mail to this address and someone
will contact you. Please don't forget to tell us how to reach you.

ETX
cat ~/info/new-stuff
@end example

@item
Filter the output to make changes. If the script below is put in
@samp{~bson/.fingerrc} on the finger server host for the domain
@samp{gnu.ai.mit.edu}:

@example
#! /bin/sh
#
# This sample filter replaces the "Project:" tag with
# "Working on:"
#
sed -e 's/^Project:$/Working on:/g'
@end example

Then when @samp{finger -l bson@@gnu.ai.mit.edu} is run, the output could
look something like:

@example
Jan Brittenson (bson)
Home: /home/fsf/bson
Shell: /usr/local/bin/bash
No mail.

Jan Brittenson (bson) is not presently logged in.
Last seen at wombat.gnu.ai.mit.edu on Tue Sep  1 15:08:12 1992

No plan.

Working on:
        1. Hacking GNU Finger
        2. Making friends
@end example
@end itemize

@node User-defined Targets
@section User-defined Targets

Various special targets can be added as executable files in the
directory @file{fingerdir/targets}. Each file name in this directory
starts with a letter describing when to execute it, followed by a hyphen
and the target name. The three letters are:

@table @samp
@item l
In response to a ``long'' finger; usually by typing @samp{finger -l}.

@item s
In response to a ``short'' finger; usually the default if no options are
given.

@item x
In response to either a ``long'' or ``short'' request.
@end table

For instance, the special-target file @file{x-.help} is run for either
@samp{finger .help} or @samp{finger -l .help}, whereas the special-
target file @file{l-prices} is run only for @samp{finger -l prices}.

The special-target file is run as super-user, and is given no input. By
convention, all GNU Finger sites should support at least:

@table @samp
@item .help
Display message describing what features and special targets exist
on this site.

@item .site
Display message describing the site. This may include such things as the
company name, its address, and how to contact the system manager.
@end table

@node Ports
@section How Finger Picks a Port

When invoked, the GNU Finger client looks to see if a @samp{--port}
option was specified on the command line. If so, then this becomes the
port number or service used. Otherwise, the client looks to see what
name it was started under, removes any leading directory path, and any
trailing suffixes. A suffix is the part of a filename that follows a
dot, including the dot itself. This is the service name used.  For
instance, if GNU Finger is installed as
@file{/usr/local/bin/finger.new}, then the service @samp{finger} is
used. If it's installed as @file{/usr/local/bin/gfinger}, then the
service @samp{gfinger} is used. This behavior can be changed by the
system administrator during installation.

@node Security
@chapter Security Issues

One question that often arises when installing networking software which
adds new functionality is whether it can be considered sufficiently
secure. The most significant new function in GNU Finger with regard to
security is the ability for a user to have a @file{.fingerrc} in the
home directory. The following are the precautions take by GNU Finger:

@itemize @bullet
@item
Check whether @file{.fingerrc} is writable to anyone except the owner.
Notice that check is not enabled by default, since FSF users like anyone
to be able to write any file -- enable this check during installation by
editing @file{config.h}.

@item
Check whether @file{.fingerrc} is owned by the user in whose home
directory it's found. This, like the previous check, is disabled by
default. It really only makes sense on systems where ordinary users
can't give away their files.

@item
Execute the script through the user's login shell, using the command
``@var{shell} -c @var{script}''. This means that a user who has had his
account disabled (i.e. shell set to a program that prints a notice or
just dies) can't run a @file{.fingerrc} script. This behavior can be
changed by hard-coding the shell in @file{config.h}.
@end itemize

@node Bug Reports
@chapter Bug Reports

You are strongly encouraged to submit a bug report to
bug-gnu-utils@@gnu.ai.mit.edu if you have problems with this beta
release of GNU Finger. Here are some things that are generally helpful
to mention, when relevant:

@itemize @bullet
@item
The GNU Finger version and where you obtained the distribution.
@item
Your hardware.
@item
Operating system.
@item
C Compiler used.
@item
The arguments you gave to @file{./configure}.
@item
Changes you made to the GNU Finger configuration files.
@item
Any changes you have made to the source code or installation procedures.
@item
Your network configuration; don't forget to mention what hardware,
operating systems, and C compilers are used on each node where the bug
manifests itself.
@item
Any problems you had during installation.
@end itemize

If you're having problems compiling or installing GNU Finger, then the
following is particularly helpful to mention:

@itemize @bullet
@item
The command line used to invoke @code{configure}.
@item
The current directory.
@item
The command line used to invoke @code{make} and @code{make} version
(particularly if you're using GNU Make).
@item
A capture of the compiler output.
@end itemize

Please feel free to include any patches, as well.


@node Installation
@chapter Installation

@menu
* Basic Installation::		Quickly get up and running from scratch.
* Configuration Files::		The GNU Finger configuarion files.
* Site Specific Functions::	How to customize Finger to your site.
* Configuration Options::	What can be reconfigured.
@end menu

@node Basic Installation
@section Basic Installation

Here are the steps that you will need to take in order to install
GNU Finger. 

@enumerate
@item
Pick a machine which will be the local finger server for your network.
Create a @file{clients} file, and install it in
@file{/usr/local/etc/fingerdir} (or the EtcDir as specified in
@file{config.h}). Put the names of all hosts that should report to the
finger server in this file. Don't forget to include the finger server
itself.

@item
For each client (the designated server is also a client), do the
following,

@item
Change your working directory to be the top of the GNU Finger sources.
For instance, if you have placed the source in @file{/src/gnu/finger}
you would type @samp{cd /src/gnu/finger}.

@item
In the source directory, type @samp{make clean} and @samp{./configure}
if this host is different from the previous one.  If you're using
@code{csh} on an old version of System V, you might need to type
@samp{sh ./configure} instead to prevent @code{csh} from trying to
execute @code{configure} itself.

The @code{configure} shell script attempts to guess correct values for
various system-dependent variables used during compilation, and
creates the Makefile(s) (one in each subdirectory of the source
directory).  In some packages it creates a C header file containing
system-dependent definitions.  It also creates a file @file{config.status}
that you can run in the future to recreate the current configuration.

Running @code{configure} takes a minute or two.  While it is running, it
prints some messages that tell what it is doing.  If you don't want to
see the messages, run @code{configure} with its standard output redirected
to @file{/dev/null}; for example, @samp{./configure >/dev/null}.

To compile the package in a different directory from the one containing
the source code, you must use a version of make that supports the VPATH
variable, such as GNU make.  @samp{cd} to the directory where you want
the object files and executables to go and run @code{configure}.
@code{configure} automatically checks for the source code in the
directory that @code{configure} is in and in @file{..}.  If for some
reason @code{configure} is not in the source code directory that you are
configuring, then it will report that it can't find the source code.  In
that case, run @code{configure} with the option @samp{--srcdir=DIR},
where DIR is the directory that contains the source code.

You can tell @samp{configure} to figure out the configuration for your
system, and record it in @file{config.status}, without actually
configuring the package (creating @file{Makefile} and perhaps a
configuration header file).  To do this, give @code{configure} the
@samp{--no-create} option.  Later, you can run @code{./config.status} to
actually configure the package for a particular host.  This option is
useful mainly in @file{Makefile} rules for updating @file{config.status}
and @file{Makefile}.  You can also give @file{config.status} the
@samp{--recheck} option, which makes it re-run @code{configure} with the
same arguments you used before.  This is useful if you change
@code{configure}.

@samp{configure} ignores any other arguments that you give it.

If you want to install the GNU Finger configuration files somewhere
other than @file{/usr/local/etc/fingerdir}, then you should edit the
files @file{./config.h} and @file{include/fingerpaths.h} now.  You need
to specify the alternate locations of where the configuration files will
be kept. If you want to include the unsupported code for mugshots, then
you should now also choose one of the face formats, as well as edit
@file{lib/Makefile.in}, @file{lib/site/Makefile.in}, and
@file{src/Makefile.in} to compile and link in the files necessary.

If your system requires unusual options for compilation or linking that
@code{configure} doesn't know about, you can give @code{configure}
initial values for some variables by setting them in the environment.
In Bourne-compatible shells, you can do that on the command line like
this:

@example
CC='gcc -traditional' DEFS=-D_POSIX_SOURCE ./configure
@end example

The @samp{make} variables that you might want to override with environment
variables when running @code{configure} are:

(For these variables, any value given in the environment overrides the
value that `configure' would choose:)

@table @code
@item CC
C compiler program. Default is @samp{cc}, or @samp{gcc} if @samp{gcc} is
in your search path.
@item INSTALL
Program to use to install files. Default is @samp{install} if you have
it, @samp{cp} otherwise.
@end table

(For these variables, any value given in the environment is added to
the value that `configure' chooses:)

@table @code
@item DEFS
Configuration options, in the form @samp{-Dfoo -Dbar ...}
@item LIBS
Libraries to link with, in the form @samp{-lfoo -lbar ...}
@end table

@item
To build and/or install the GNU Finger executables and standard targets,
issue one of the following commands:

@table @samp
@item make server
To build and install all executables, plus install the finger-specific
server configuration files. Use this if the host is the designated
finger server.

@item make client
To build all executables, but install only those used by the non-server
clients. Use this unless the host is the designated finger server.

@item make all
To build all executables, but perform no installation.
@end table

The above commands build @file{lib/libfinger.a} and the main programs in
@file{src}: @code{finger}, @code{in.fingerd}, and @code{in.cfingerd}, as
well as @code{fingerd} on the server.  If you want to, you can override
the @samp{make} variables @code{CFLAGS} and @code{LDFLAGS} like this:

@example
make CFLAGS=-O2 LDFLAGS=-s
@end example

@item
Modify the system configuration so that the client has (refer to the
system documentation for details on how to do this on a particular
system):

@itemize @bullet
@item
Entries in the system @file{services} file, or equivalent, which
mentions the correct TCP port for @code{in.cfingerd} (port 2003) and
@code{in.fingerd} (port 79). If port 2003 is already used by something
else, then read the section on Configuration Files for details on how to
specify a port other than 2003 in the
@file{/usr/local/etc/fingerdir/clients} file. A good name for the
service is @samp{cfinger}.
@item
Entries in the system @file{inetd.conf} file, or equivalent, which
contains references to @code{in.cfingerd} and @code{in.fingerd}.
@code{in.fingerd} needs to be run with UID @code{root}.  Consult your
system documentation for details on how to do this. @code{in.cfingerd}
should be run with UID @code{root} on System V derivatives.
@item
a @file{/usr/local/etc/fingerdir/serverhost} file which contains the
name of the GNU Finger server host,
@item
a @file{/usr/local/etc/fingerdir/mailhost} file which contains the name
of the mail server to ask for user mail forwarding information and
mailing list expansion, and
@item
the inetd daemon restarted, so that server and user requests can be
answered.
@end itemize

@item
When you have performed the above steps for each client, log onto the
designated GNU Finger server.

@item
Start the server daemon, @code{fingerd}. You should arrange to have
@code{fingerd} started every time the server host is rebooted. For exact
details on how to do this, please refer to the server host's system
documentation.

@item
If you chose to include the mugshots option, now might be a good time to
install the mugshots.  But first, try getting a face from another site
running GNU Finger!  For example, you might try
@example
@code{finger --face bfox@@aurel.cns.caltech.edu}
@end example

@item
Modify the files @file{x-.help} and @file{x-.site} in
@file{/usr/local/etc/fingerdir/targets} for your site.

@end enumerate

Now you're all set! You might like to read through the section on
Configuration Files.


@node Configuration Files
@section Configuration Files

This section describes the format of the GNU Finger configuration files.

@menu
* Clients::		List of finger client hosts.
* Serverhost::		Finger server host.
* Mailhost::		Mail router for clients.
* Forwardhost::		For unresolved requests.
* Ttylocs::		Making sense out of locations.
@end menu

@node Clients
@subsection The @file{clients} file

The @file{/usr/local/etc/fingerdir/clients} file contains a list of
clients that the GNU Finger server @code{fingerd} is supposed to poll.
You can edit this file and then send the finger server a @code{SIGHUP}
to tell it that the configuration has changed. Each line in the file
should be either the name of a host or a comment. The name can be
preceded by @code{@@@var{port}}, to tell the finger server to poll the
particular host by using a port other than 2003. A comment is any line
that starts with a hash sign (#). Below is a sample @file{clients} file:

@example
# This file contains all GNU Finger clients on the gnu.ai.mit.edu
# network. Apple-gunkies is the GNU Finger server (see ``serverhost'').
apple-gunkies.gnu.ai.mit.edu

# Albert is the mail exchanger (see ``mailhost'').
albert.gnu.ai.mit.edu

# Spiff is a Sony, so port 2003 is already used for `mbanks'.
# Use port 2010 instead.
@@2010 spiff.gnu.ai.mit.edu

churchy.gnu.ai.mit.edu
mole.gnu.ai.mit.edu
geech.gnu.ai.mit.edu
wookumz.gnu.ai.mit.edu
nutrimat.gnu.ai.mit.edu
kropotkin.gnu.ai.mit.edu
goldman.gnu.ai.mit.edu
hal.gnu.ai.mit.edu
wombat.gnu.ai.mit.edu
@end example

Although this sample @file{clients} file contains the fully qualified
domain names of the hosts, it's usually enough to specify only the host
name portion. Explicit IP addresses can be used too, but this is a
practise strongly discouraged. Notice that the server is also in the
clients file and has a @code{in.cfingerd}; this is necessary in order
for the server to correctly poll itself.

@node Serverhost
@subsection The @file{serverhost} file

The @file{/usr/local/etc/fingerdir/serverhost} file holds the name of
the GNU Finger server host; this is as the name implies, the host that
the GNU Finger server @code{fingerd} runs on. Lines starting with a hash
sign (#) are treated as comments. Below is a sample @file{serverhost}
file:

@example 
# A-g does all the finger stuff
apple-gunkies.gnu.ai.mit.edu
@end example

@node Mailhost
@subsection The @file{mailhost} file

The @file{/usr/local/etc/fingerdir/mailhost} file holds the name of the
mail exchanger host for the network. This host should know how to talk
SMTP; this file should never hold the name of a host that can't. It's
contacted to obtain mail forwarding information and to expand mailing
lists if a @file{.forward} file can't be found in the user's home
directory. GNU Finger always looks and reports on user @file{.forward}
files regardless of whether @file{mailhost} exists or not. Any lines in
this file that start with a hash sign (#) are treated as comments.

@node Forwardhost
@subsection The @file{forwardhost} file

The @file{/usr/local/etc/fingerdir/forwardhost} file holds the name of
the host to forward finger requests to when the current finger server
can't find a matching user name or mail alias. No forwarding takes place
if this file doesn't exist. Any lines that start with a hash sign (#)
are treated as comments. This is a sample output of what it can look
like when a request is forwarded:

@example
% finger -l nosuchuser@@gnu.ai.mit.edu
[No user nosuchuser@@apple-gunkies.gnu.ai.mit.edu, forwarding
 request to life.ai.mit.edu]
Login name: nosuchuser			In real life: ???
@end example

@node Ttylocs
@subsection The @file{ttylocs} file

The @file{/usr/local/etc/fingerdir/ttylocs} file holds explanations for
the hosts or terminal lines that users have logged in from or through.
Each client host has its own copy of this file. Each line consists of a
host name followed by a description. The name and description are
separated by one or more blanks or TABs.

@example
spiff.gnu.ai.mit.edu            NE43 Hall
susie.gnu.ai.mit.edu            NE43 Sony 427 x8568
spike.gnu.ai.mit.edu            NE43 Sony 427 x8568
apple-gunkies.gnu.ai.mit.edu    NE43 427        
sugar-bombs.gnu.ai.mit.edu      Elsewhere
pogo.gnu.ai.mit.edu             NE43 447
albert.gnu.ai.mit.edu           Noisy Machine Room
128.52.46.42                    The salt mines
churchy.gnu.ai.mit.edu          NE43 426
mole.gnu.ai.mit.edu             NE43 430
geech.gnu.ai.mit.edu            NE43 426
wookumz.gnu.ai.mit.edu          NE43 427
calvin.gnu.ai.mit.edu           NE43
gnu.gnu.ai.mit.edu              NE43
kropotkin.gnu.ai.mit.edu        Total anarchy
@end example

@node Site Specific Functions
@section Site Specific Functions

If you are interested in customizing GNU Finger's output, then the
@file{lib/site} directory is the right place to start.  If you would
like to add new code for displaying faces, or have a particularly
interesting ``long'' information output format, I would be glad to
include it as unsupported code in the next release of GNU Finger.  (I
will direct correspondence regarding your code to you.) You can find
other contributed code in @file{lib/site}, most notably different user
info formats and code to handle different bit map file formats. The only
file supported in @file{lib/site} is @file{userinfo.c}.

@node Configuration Options
@section Configuration Options

The following definitions in @file{config.h} control the behavior
of GNU Finger:

@table @code
@item SUPPORT_FINGERRC
Undefine to prevent users from writing @file{.fingerrc} scripts. Defined
by default.

@item CHECK_OWNER_FINGERRC
Define to make sure @file{.fingerrc} is owned by the user in whose
directory it's found.

@item CHECK_RDONLY_FINGERRC
Define to make sure @file{.fingerrc} isn't writable by anyone other than
its owner.

@item FINGERRC_SHELL
The shell to use to execute @file{.fingerrc}. Undefine to use user's
login shell.

@item DEFAULT_POLL_INTERVAL
Define to be the delay between polls, in seconds, unless an interval is
explicitly given to @code{fingerd} with the @samp{--interval} option.

@item BASENAME_IS_SERVICE
Undefine if you always want the finger client to use the @samp{finger}
service. Otherwise the service is deduced from the basename of the
client. Defined by default.

@item INFO_IS_DEFAULT
Define if you prefer @samp{finger --info} to be the default, undefine if
you prefer @samp{finger --brief} to be the default.
@end table

@node Invoking Finger
@chapter GNU Finger Quick Reference

@example
finger @var{options} @var{user@@host}
@end example

Finger obtains information about @var{user} on the remote system
@var{host}. It can also be used to obtain information about mailing
lists and special site-specific services.

@var{Options} can be one or more of:

@table @samp
@item --info
@itemx -i
@itemx -l
Return as much information as possible about @var{user}.

@item --brief
@itemx -b
@itemx -s
Only display current login info.

@item --face
@itemx -f
Display a mugshot of @var{user}. Not supported.

@item --port @var{port#}
@itemx -P @var{port#}
Connect to the finger server using port or service @var{port#}.
@end table

@bye

