


                            WATCHER User's Guide

                              Matthew Madison
                       Engineering Computing Services
                      Rensselaer Polytechnic Institute
                               Troy, New York


    Introduction

    One of the first things that a VAX/VMS system manager needs is a way
    to stop idle interactive processes.  There are many out there, some
    very basic, and some that do much more than simple stop idle
    processes.

    When I first looked into an idle process killer, I couldn't find one
    that did exactly what I wanted, so I wrote one myself.  Of course, I
    later changed my mind about how to decide when a job is idle, so I
    rewrote the program.  Then workstations came in, which had to
    handled differently.  Also, I wanted to build in exceptions to the
    rules, and so on.  Thus WATCHER was created.

    WATCHER lets you watch only the terminals you want watched.  It lets
    you decide what it should measure (terminal I/O, CPU use, process
    I/O) when determining which processes are idle, how long they can
    remain idle before logout, and whether or not to give a warning
    before logout, all of which can be different for different
    terminals.  WATCHER lets you exclude certain users from being
    watched, based on userid, UIC, identifiers held, privileges,
    terminal, and/or time of day.  You can also decide whether WATCHER
    should record logout notifications, and if so, whether they should
    go to a file, to operators or both.  Last but not least, you can
    decide the granularity of WATCHER's decisions by setting WATCHER's
    wakeup interval.

    WATCHER knows all about LAT terminals: WATCHER can obtain LAT port
    information and use that to determine the actual location of a terminal.

    On VAXstations, WATCHER has special code to handle VWS help windows.
    Normally created under the SYSTEM userid (which I generally exclude
    from being watched), WATCHER internally substitutes a fictitious
    userid called UIS_HELP for VWS help windows to allow you to treat
    them as if they were created by a normal interactive user.


    Installing WATCHER

    WATCHER is broken up into two programs: the WATCHER program itself,
    and a program called WCFG, which builds WATCHER configuration files.

    The files WATCHER.EXE and WCFG.EXE can be located in any directory,
    but the simplest place to put them is in the directory
    SYS$SYSROOT:[WATCHER] (or SYS$COMMON:[WATCHER] for homogeneous
    clusters).

    WATCHER runs as a detached process. The following command should be
    added to the system startup sequence to start WATCHER:

    	 $ RUN/DETACHED/OUTPUT=NL:/PROCESS="Watcher"-
    	 /PRIV=(NOSAME,TMPMBX,NETMBX,OPER,WORLD,SHARE,CMKRNL)-
    	 device:[directory]WATCHER

    If you do not run WATCHER under system UIC, you should add SYSPRV to
    the list of privileges.  WATCHER automatically looks for a
    configuration file called:

    	 SYS$SYSROOT:[WATCHER]WATCHER_CONFIG.WCFG

    You may define a system-wide logical name WCATCHER_CONFIG to point
    to a different file if you'd like.


    Configuring WATCHER

    The WCFG program is used to create configuration files for WATCHER.
    A configuration file must be created in advance; it is read once
    when WATCHER starts and cannot be changed "on the fly".

    Start WCFG with the command

    	 $ RUN SYS$SYSROOT:[WATCHER]WCFG

    (assuming you installed it there).

    There are three types of information that make up a WATCHER
    configuration: watch records, exclusion records, and the general or
    "global" information WATCHER.

    An important part of WATCHER configuration records is the terminal
    device name.  A terminal device name can have one of three forms:

    	 scsnode$device	     For a VAXcluster configuration, this
                             identifies a terminal device on a
                             particular node.

    	 device		     Identifies a device on a node that has no
                             SCSNODE defined (i.e., is not part of a
                             cluster).

    	 server::port	     Identifies an LAT terminal server port.

    Terminal device names never include a trailing colon when used with
    WATCHER.

    A watch record describes a terminal or group of terminals to be
    watched for inactivity.  Besides identifying the terminal(s) to be
    watched, a watch record identifies the counters that should be
    measured to determine whether a terminal is "active" and indicates
    whether or not an inactive process should be warned or logged out,
    and if so, how long a period should elapse before a warning or
    logout occurs.

    An exclusion record describes a set of criteria about a user or
    group of users.  When a user meets the specified criteria, that user
    is exempt from being affected by WATCHER.  Criteria include
    username, privilege, identifiers held, UIC, time of day and day of
    week, and terminal.

    WATCHER global information includes the wakeup interval and event
    logging settings.


    WCFG Commands

    The following pages describe the commands available in WCFG.  They
    are given in order of usefulness.


    WATCH

    The WATCH command defines a watch record that identifies a terminal
    or set of terminals to be watched.

    Syntax:

    	 WCFG> WATCH device
    	 	   /MEASURE=(measure-kwd[,...])
    	 	   /[NO]WARN[=warn-time]
    	 	   /[NO]LOGOUT[=logout-time]

    device	   a terminal device name, possibly containing wildcard
                   characters (as used by STR$MATCH_WILD).

    /MEASURE	   indicates what items (CPU, TERMINAL_IO, PROCESS_IO)
                   should be measured when determining whether or not
                   the process using that terminal is idle.  If omitted,
                   TERMINAL_IO is used.  If you specify more than one
                   measurement, a change in any one of the specified
                   measurements indicates that the terminal is active.

    /WARN	   specifies the amount of idle time that should elapse
                   before a warning is displayed on the idle terminal.
                   Specify "warn-time" as a VMS delta-time value.
                   /NOWARN indicates that no warning should be
                   displayed.  If omitted, the default WARN setting is
                   used -- see the SET WARN description for more
                   information.

    /LOGOUT	   specifies the amount of idle time that should elapse
                   before the idle process is stopped.  If omitted, the
                   default LOGOUT setting is used -- see the SET LOGOUT
                   description for more information.

    When using wildcards with the WATCH command, bear in mind that
    WATCHER searches watch records sequentially, in the order that you
    enter them when you configure.  The first watch record that matches
    the device that WATCHER is examining is the watch record used in
    conjunction with that device.  Thus, you should probably enter more
    specific WATCH commands before entering more general ones.


    EXCLUDE

    The EXCLUDE command defines WATCHER exclusion records.  An exclusion
    record identifies a user or group of users to be excluded from idle
    job termination.

    Syntax:

    	 WCFG> EXCLUDE user
    	 	   /PRIVILEGES=(privilege[,...])
    	 	   /HOLDING=identifier
    	 	   /UIC=uic
    	 	   /TERMINAL=device
    	 	   /DURING=(day-time[,...])

    user	   Username of user to be excluded.  This may contain
                   wildcard characters.

    /PRIVILEGES	   indicates that the user should be eligible for
                   exclusion only when holding the (process) privileges
                   specified.  If omitted, privilege checking is not
                   performed.

    /HOLDING	   indicates that the user should be eligible for
                   exclusion only when holding the specified identifier.
                   The identifier may contain wildcard charcters.  If
                   omitted, identifier checking is not performed.

    /UIC	   indicates that the user should be eligible for
                   exclusion only when the process UIC matches the
                   specified UIC code.  The UIC code can be in
                   alphanumeric or octal format, and may contain an
                   asterisk for the member part to indicate a group
                   identifier.  If omitted, UIC checking is not
                   performed.

    /TERMINAL	   indicates that the user should be eligible for
                   exclusion only when the terminal being used matches
                   the terminal device name specified.  The terminal
                   device name may contain wildcard charcters.  If
                   omitted, terminal checking is not performed.

    /DURING	   indicates that the user is only eligible for
                   exclusion during the specified times on the specified
                   days.  The "day-time" specifications are of the form:

    		   	     day:hour-range    or
    		   	     day:(hour-range[,...])

    		   where "day" may be the name of a day of the week or
                   the PRIMARY or SECONDARY (see the description of SET
                   DAYS for more information on these), and an
                   "hour-range" can be a single hour number (0 through
                   23) or two hour numbers separated by a hyphen,
                   indicating an inclusive range of hours.  If the
                   /DURING qualifier is omitted, WATCHER performs no
                   time-of-day checking.

    In order for a user to be excluded from being watched by WATCHER,
    all of the criteria specified on the EXCLUDE command must be met.
    Just as for watch records, exclusion records are scanned
    sequentially by WATCHER in the order you specify; thus, you should
    usually enter your more general exclusion records after your more
    specific ones.


    SET LOGOUT
    SET WARN

    The SET LOGOUT and SET WARN commands are used to define default
    warning and logout settings for subsequent WATCH commands.

    Syntax:

    	 WCFG> SET LOGOUT=delta-time
    	 WCFG> SET NOLOGOUT
    	 WCFG> SET WARN=delta-time
    	 WCFG> SET NOWARN

    A subsequent WATCH command without a /LOGOUT qualifier inherit the
    setting from the SET LOGOUT command.  Likewise, WATCH commands
    without a /WARN qualifier will inherit the setting from SET WARN.
    If not set by you, the default logout setting is LOGOUT=00:30:00 and
    the default warn setting is WARN=00:25:00.


    SET DAYS

    The SET DAYS command defines which days are considered "primary" and
    "secondary" for subsequent EXCLUDE commands.

    Syntax:

    	 WCFG> SET DAYS
    	 	   /PRIMARY=(day[,...])
    	 	   /SECONDARY=(day[,...])

    The default settings when starting WCFG are Monday-Friday as primary
    and Saturday and Sunday as secondary.  You can use the SET
    DAYS/PRIMARY command to move a day from the secondary grouping to
    the primary grouping, and vice-versa for SET DAYS/SECONDARY.  These
    groupings are mainly a convenience when entering several EXCLUDE
    commands that use day/time criteria.


    SET INTERVAL

    The SET INTERVAL command defines the wakeup interval for WATCHER.

    Syntax:

    	 WCFG> SET INTERVAL=delta-time

    The default interval is 00:01:00.  WATCHER hibernates for this
    length of time between searches through the system process list.
    Note that for best operation, the logout and warning times in watch
    records should be multiples of the wakeup interval.  How large an
    interval you should choose depends on how accurate you want your
    logouts to be vs. how much CPU time you can spare.  Usually a
    five-minute interval provides reasonable accuracy for half-hour
    idle-time logouts while not consuming an inordinate amount of CPU
    time on a system averaging 8-16 simultaneous users.  Your actual
    mileage may vary, and you may need to tweak the interval in order to
    achieve the accuracy and low CPU use you desire.


    SET EVENT_LOG

    The SET EVENT_LOG command specifies how WATCHER should record its
    logout events.

    Syntax:

    	 WCFG> SET EVENT_LOG
    	 	   /OPERATOR=(oper-class[,...])
    	 	   /NOOPERATOR
    	 	   /FILE=file-spec
    	 	   /NOFILE
    	 WCFG> SET NOEVENT_LOG

    You may specify one or operator classes that should receive an OPCOM
    message each time WATCHER stops a process, and/or a file to which
    WATCHER should log such events.  Or, you may disable event logging
    altogether.  The default if you do not set any event logging is for
    log messages to be sent to operator class CENTRAL.


    SHOW

    The SHOW command displays watch records, exclusion records, and
    settings for warning and logout defaults, event logging, and wakeup
    interval.

    Syntax:

    	 WCFG> SHOW ALL
    	 	    WATCHES
    	 	    EXCLUSIONS
    	 	    DEFAULTS

    Watch records and exclusion records are displayed in reverse order
    from the way they will be processed by WATCHER; this is mainly due
    to laziness on the part of the author.  Other information may not be
    displayed in the prettiest of fashions, for the same reason.


    SAVE

    The save command saves a configuration.

    Syntax:

    	 WCFG> SAVE [file-spec]

    If you omit a file-spec, WCFG prompts you for one, selecting a
    suitable default.


    EXIT

    The EXIT command leaves WCFG, optionally saving the configuration on
    exit.

    Syntax:

    	 WCFG> EXIT [file-spec]
    	 	   /[NO]SAVE

    A file-spec should be specified only with EXIT/SAVE.  If you EXIT
    and do not specify /SAVE or /NOSAVE, you are asked if you really
    want to exit without saving the configuration.


    HELP

    This should be self-explanatory.

    Syntax:

    	 WCFG> HELP [topic]




    Bugs Fixed Since Last Version

           1.  When measuring terminal I/O's on non-LAT terminals, warnings
          sent out by WCH_WARN would cause a terminal to become
          non-idle.

           2.  The OPER privilege was omitted from the RUN command in the
          documentation.

           3.  Subprocess information was not being merged correctly with
          master process information.

           4.  A null exclusion list was treated as an error in the
          configuration file.


    Restrictions, Known Bugs, Etc.

           1.  The WCFG program has several limitations.  For example, there
          is no way to edit an existing configuration; each configuration
    	  must be built from scratch.

           2.  The best way to create a configuration is to create a command
          file that invokes WCFG and has all the WCFG commands in it to
          create the configuration.  There is no way from within WCFG to
          obtain commands from a location other than SYS$INPUT.

           3.  WATCHER configurations cannot be changed "on the fly" -- you
          must stop and re-start WATCHER for a new configuration to take
          effect.

           4.  WATCHER always obtains all process and device information that
          might be needed for comparison to a watch record or exclusion
          record.  This behaviour might be a bit greedy on systems that
          only want minimal checking performed.

           5.  Occasionally, WATCHER would log a spurious logout event in
          which user "<login>" would be logged out, as if an incomplete
          login were logged out.  Being difficult to reproduce, a fix
          was applied for this "in the dark", and it is as yet unknown
          whether it has actually been fixed.


    A Sample Configuration

    The following is a command file that creates a typical WATCHER
    configuration for a VAXcluster.

    $ RUN SYS$SYSROOT:[WATCHER]WCFG
    SET INTERVAL=00:05:00
    SET WARNING=00:25:00
    SET LOGOUT=00:30:00
    SET EVENT/OPER=CENTRAL
    WATCH *
    EXCLUDE BACKUP
    EXCLUDE SYSTEM
    EXCLUDE FIELD/TERMINAL=*$OPA0
    EXCLUDE OPERATOR/TERMINAL=*$OPA0
    EXCLUDE MADISON/DURING=(PRIMARY:8-17)  ! I'm excluded while at work
    EXCLUDE */UIC=[OP,*]/TERMINAL=(LAT02::PORT_1) ! operator's terminal
    SHOW ALL
    SAVE RPI$ROOT:[WATCHER]WATCHER_CONFIG
    EXIT
    $ EXIT


    Configuration Hints

    Normally, I like to encourage terminal use for interactive sessions
    only.  So I usually stick with WATCHER's default of measuring only
    terminal I/O's to determine activity.  This encourages people to use
    batch jobs when running programs that run for more than half an hour
    without terminal activity.

    One exception to the rule is the VAXstation.  When a user starts up
    a graphics application on a VAXstation, no more "terminal I/O's" are
    recorded on the user's terminal window, even though the application
    is interactive (due to the nature of graphics I/O).  Therefore, I
    use the process I/O measurement on all WT and TK terminal devices.

    Of course, not everyone agrees with my philosophy about terminal
    use.  Therefore, you can try using the CPU measurement, possibly
    coupled with the I/O measurements.  The effectiveness of WATCHER's
    CPU measurement code, however, is untested.

--------------------------------------------------------------------------------
CONTACTING THE AUTHOR

Comments, suggestions, and questions about this software can be directed to
the author at one of the following addresses:

Mail:	Matthew Madison
    	Engineering Computing Services
    	Rensselaer Polytechnic Institute
    	Troy, New York 12180-3590

Phone:	(518) 276-2606

E-Mail:	(Internet)  madison@vms.ecs.rpi.edu
    	(BITNET)    MADISON@RPIECS

COPYRIGHT NOTICE

This software is COPYRIGHT © 1988, 1989 RENSSELAER POLYTECHNIC INSTITUTE.
ALL RIGHTS RESERVED.  Permission is granted for non-profit redistribution and
use.

DISCLAIMER

This software is provided "AS IS".  Neither the author nor Rensselaer
Polytechnic Institute make any guarantee as to the usefulness, suitability,
performance, or security of the software.
