    
    
    
                            WATCHER User's Guide
    
                              Matthew Madison
                  Center for Interactive Computer Graphics
                      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 certain terminals.  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 log logout notifications, and if 
    so, whether they should go to a file, to an operator class, 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: under versions V4.6 and V4.7 
    of VAX/VMS, 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,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.  You 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]

    
    Restrictions, Known Bugs, Etc.
    
           1.  The WCFG program has several limitations.  For example, there 
          is no way to edit an existing configuration; each configur
          ation 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.  Although the WCFG HELP command is present, the help library 
          has not been written.  If you want to write HELP for WCFG, you 
          should put the resultant library in SYS$HELP and call it 
          WCFG_HELPLIB.HLB (or define a logical name WCFG_HELPLIB 
          pointing elsewhere).
    
           4.  WATCHER configurations cannot be changed "on the fly" -- you 
          must stop and re-start WATCHER for a new configuration to take 
          effect.
    
           5.  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.
    
           6.  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 WATCHER can be directed 
    to the author via electronic mail at one of the following addresses:
    
    Internet: madison@cicgj.rpi.edu
    BITNET:   madison@rpicicge
    
    
    Copyright Notice
    
    COPYRIGHT © 1988, RENSSELAER POLYTECHNIC INSTITUTE.  ALL RIGHTS 
    RESERVED.  Permission is given to redistribute this software for 
    non-commercial purposes provided no there is no charge for the 
    distribution beyond handling and materials costs.
    
    DISCLAIMER: This software is provided "as is".  Neither the author 
    nor Rensselaer Polytechnic Institute makes any guarantee as to the 
    suitability, usefulness, performance, or security of the software.
