                                  uwatch-0.1a
                                  22 Feb 1998


                               Table of Contents

  I.....................................................Introduction
  II....................................................Compiling
  III...................................................Usage
     A..................................................Command-Line Arguments
     B..................................................Configuration Files
     C..................................................Format Strings
  IV....................................................Contact Information


I. Introduction

Uwatch (user watch), is a program designed to inform you when users log in or
out of a system.  With uwatch, you have the ability to define only a set of
login names for which to watch and to customize the notification messages.
Uwatch also allows you to run an external program when it detects a that a
user has logged in or out.

WARNING: This is the first ALPHA release of uwatch.  This means that there may
         be unimplemented features, bugs, and incomplete documentation.  If
         you want to use this program for anything excepting testing purposes,
         you would be advised to wait until version 1.0 is released.


II. Compiling

To compile uwatch, follow these steps:

1. Visit http://www.xenos.net/~xenon/software/uwatch to get the latest version.
2. Unpack the source somewhere on the system that will be used to compile it.
   If you downloaded uwatch-0.1a.tar.gz, entering

      gzip -d -c uwatch-0.1a.tar.gz | tar xf -

   should decompress the package. If you downloaded uwatch-0.1a.tar.Z, then

      uncompress -c xenmenu-0.1a.tar.Z | tar xf -

   should decompress the package.  After unpacking the source, you will have a
   directory called uwatch-0.1a.  Change into that directory, (e.g. type cd
   uwatch-0.1a).
3. Edit config.h and change any of the options that you want to.  All of the
   options are documented in detail within the file.
4. Edit Makefile and change anything necessary.
5. Type make.  There should be no warnings or errors, (if there are, please
   send a note to the contact listed in Section IV).

You should now have an executable called uwatch.  Install this wherever you
want.  You may also want to create one or more of the configuration files as
listed in config.h (See Section III.B.).


III. Usage

Once you have compiled uwatch, you can execute it and it will put itself into
the background and inform you whenever anyone logs in or out of the system.
For some users, this will be the desired behavior, however, there are some
optional features that can be configured to customize what uwatch does and how
it looks.  There are two ways to configure uwatch: configuration files and
command-line arguments.

A. Command-line arguments

You execute uwatch as uwatch [arguments] [user [user ...]] where
[user [user ...]] is a list of users for which to watch, and [arguments] are
zero of more of the following:

  -c <file>     Use <file> as a configuration file.
  -d            Run in debug mode, (do not put into the background).
  -e <program>  Execute <program> when a user logs in.  The <program> string
                may contain the special % values as described in Section III.C.
  -f <file>     Read a list of user names from <file> for which to watch.
                This file should consist of a list of user names seperated
                by white space, (e.g. spaces, new lines, or tabs).  Comments
                may be inserted in this file by starting them with the #
                character.  Anything after the # character and to the end of
                the line is ignored.
  -i <string>   Use <string> as the format string for printing "in" messages.
                The <string> may contain the special % values as described in
                Section III.C.
  -o <string>   Use <string> as the format string for printing "out" messages.
                The <string> may contain the special % values as described in
                Section III.C.
  -q            Quick mode, (print a list of users currently online and exit).
  -s            Silent mode, (do not print anything to the screen).
  -w <seconds>  Wait <seconds> seconds between checks of the system for
                users that have logged in or out.
  -x <program>  Execute <program> when a user logs out.  The <program> string
                may contain the special % values as described in Section III.C.

B. Configuration Files

Configuration files are plain text files where each line may contain a
configuration option in the form <option> [value].  Comments may be inserted
into the configuration file by starting them with the # character in which
case everything after to # until the end of the line is ignored.  Blank lines
are also ignored.  The <option> value may be any of the following:

  watch_list <file>      Like the -f command-line argument.
  in_message <string>    Like the -i command-line argument.
  out_message <string>   Like the -o command-line argument.
  in_program <program>   Like the -e command-line argument.
  out_program <program>  Like the -x command-line argument.
  norunprogram           Do not allow users to specify an in_ or out_program.
  runprogram             Allow users to specify an in_ or out_program.
  sleep <seconds>        Like the -w command-line argument.
  nokillonexit           Like the -k command-line argument.
  killonexit             Kills the program when the invoking user logs out.
  quiet                  Like the -s command-line argument.
  quick                  Like the -q command-line argument.
  debug                  Like the -d command-line argument.

There are three configuration files--the names and locations of which are
defined in config.h.  First, the system configuration file is parsed.  Next,
the user configuration file is parsed followed by the command-line arguments.
Finally, the secure system configuration file is parsed.  If an option is
defined in more than one configuration file, the last instance of the
declaration is used.

C. Format Strings

You can specify the format of the messages that uwatch displays by using the
in_message or out_message directives in your configuration file, (-i or -o
command-line arguments).  You may also specify programs to execute when a
user logs in or out, (in_program or out_program directives in a configuration
file, and the -e or -x command-line options).  These options accept strings
as arguments.  These strings recgonize the following special sequences:

  %%  Print the % character.
  %b  Print a bell character.
  %e  Print the escape character.
  %h  Print the local host name.
  %n  Print a new line.
  %p  Print the port on which the user is logging in or out.
  %r  Print the remote host from which the user is logging in or out.
  %t  Print the current system time.
  %u  Print the name of the user logging in or out.

A field width may be specified for the %h, %p, %t, and %u sequences by placing
an integer value after the % and before the command.  For example, %10u would
print the user name in a field width of 10.  If the string length is less than
the field length, then the string is printed starting at the left side of the
field and then the appropiate number of spaces are appended.  If the string
length is greater than the field length, then only the part of the string that
fits in the field is printed.

IV. Contact Information

All comments, questions, and bug reports can be sent to Karyl F. Stein via
E-Mail to xenon@xenos.net.  If you are submitting a bug report, please be sure
to include the operating system and compiler being used as well as all error
messages; the more details the better.
