Guide to Installing and Using WATCHER March, 1991 This manual describes the installation, configuration, and operation of WATCHER, an idle terminal monitor for VMS systems. Revision/Update Information: This is a revised manual. Operating System and Version: VMS V5.0 or later Software Version: WATCHER V2.6 Engineering Computing Services Rensselaer Polytechnic Institute Troy, New York ________________________ 22 March 1991 Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by Rensselaer Polytechnic Institute. Rensselaer assumes no responsibility for any errors that may appear in this document. DISCLAIMER: The software described in this document is provided "as is". The author and Rensselaer Polytechnic Institute disclaim all warranties on the software, including without limitation, all implied warranties of merchantability and fitness. __________ Copyright ©1989, 1990, 1991 Rensselaer Polytechnic Institute. All rights reserved. _______________________________________________________ Contents _________________________________________________ PREFACE v _______________________________________________________ CHAPTER 1 INSTALLING WATCHER 1-1 _________________________________________________ 1.1 REQUIRED LOGICAL NAMES 1-2 1.1.1 Logical Name for Help Library _ 1-2 _________________________________________________ 1.2 PRIVILEGES REQUIRED 1-2 _________________________________________________ 1.3 OTHER REQUIREMENTS 1-3 _______________________________________________________ CHAPTER 2 CONFIGURING WATCHER 2-1 _________________________________________________ 2.1 SETTING UP WATCH RULES 2-1 2.1.1 Identifying Terminals _________ 2-2 2.1.2 WATCH Criteria ________________ 2-2 2.1.3 Terminal Groupings ____________ 2-3 _________________________________________________ 2.2 EXCLUSIONS AND OVERRIDES 2-4 _________________________________________________ 2.3 SAVING CONFIGURATIONS 2-4 2.3.1 VAXcluster Environments _______ 2-5 2.3.2 Editing Configurations ________ 2-5 iii Contents _________________________________________________ 2.4 DECWINDOWS SUPPORT 2-6 _______________________________________________________ CHAPTER 3 TROUBLESHOOTING WATCHER 3-1 _________________________________________________ 3.1 FORCING WAKEUPS 3-2 _______________________________________________________ PART II COMMAND DESCRIPTIONS WCP CMD-3 @ (REDIRECT COMMAND INPUT) CMD-5 EXCLUDE CMD-6 EXIT CMD-9 HELP CMD-10 OVERRIDE CMD-11 QUIT CMD-16 RESET CMD-17 SAVE CMD-18 SET BELL CMD-19 SET DAYS CMD-20 SET DEBUG CMD-21 SET DECWINDOWS CMD-22 SET EVENT_LOG CMD-23 SET INTERVAL CMD-24 SET MULTIWARN CMD-25 SET VERIFY CMD-26 SET WATCH_DEFAULT CMD-27 SHOW CMD-30 SHUTDOWN CMD-32 WATCH CMD-33 iv _______________________________________________________ Preface One of the first programs a new VMS system manager usually needs is an "idle terminal monitor" (ITM). That is, a program to monitor terminal activity and logout those users whose terminals remain inactive for an extended period of time. An ITM helps ensure that system resources are not wasted and helps reduce the possibility of intruders using unattended terminals as a means of entry into the system. Unfortunately, an ITM can also be an annoyance to system users. A simple ITM can victimize legitimate users who may need to remain logged in but idle while they are at work. This can lead to clever users devising "hacks" to evade the ITM, defeating the purpose of using the ITM in the first place. WATCHER has a high degree of flexibility, allowing system managers to decide how to accommodate users' needs while still addressing operational and security issues. WATCHER is fully configurable, providing the following features: o You can tell WATCHER which terminals to watch, and on a per-terminal basis, what measurements (CPU use, process I/O count, terminal I/O count) to use as criteria for determining idleness, and how long a terminal should be idle before the user should be forced off. o Users can be excluded from interference by WATCHER based on any combination of username, UIC, a held identifier, privileges, terminal device and/or port name, and time-of-day/day-of-week. o You can override or modify the watch criteria and/or idle times for any user based on any combination of username, UIC, a held identifier, v Preface privileges, terminal device and/or port name, and time-of-day/day-of-week. Through the use of these features, the system manager should be able to configure WATCHER to handle most types of terminals and accommodate most users. __________________________________________________________________ Intended Audience This manual is intended for the system manager or other person responsible for installing and configuring WATCHER. __________________________________________________________________ Document Structure This document consists of two parts. The first describes the installation and use of WATCHER. The second describes all of the WATCHER Control Program (WCP) commands in detail. __________________________________________________________________ Contacting the Author There is no formal support for WATCHER. If you have electronic mail capability, however, you can send your questions and comments to the author at madison@vms.ecs.rpi.edu (Internet) or MADISON@RPIECSVX (BITNET). The author is also available on DECUServe as user MADISON. If you cannot send electronic mail, you can contact the author by post, telephone, or facsimile at: Matthew Madison Engineering Computing Services Rensselaer Polytechnic Institute vi Preface Troy, New York 12180-3590 USA Phone: +1 518 276 2606 Fax: +1 518 276 4860 vii _______________________________________________________ 1 Installing WATCHER To use WATCHER, you need the following files: WATCHER.EXE The main WATCHER image WCP.EXE The WATCHER Control Program WCP_HELPLIB.HLB Help library for WCP DECW_STARTLOGIN.COM Part of DECwindows support WATCHER_CONFIG.WCFG You create this file with WCP WATCHER_STARTUP.COM Sample startup command procedure WATCHER_SHUTDOWN.COM Sample shutdown command procedure SAMPLE_CONFIG.WCP Sample configuration commands The package comes with the object code files and libraries and a command procedure called LINK.COM, for creating the two images. It is easiest to simply place all of the files in the distribution in one directory, run LINK.COM to create the images, then edit WATCHER_STARTUP.COM and the sample configuration commands in SAMPLE_CONFIG.WCP as needed for your system. Then all you need to do is to run WCP, execute the WCP command file you created from the sample, which in turn creates a WATCHER_ 1-1 Installing WATCHER CONFIG.WCFG file, then execute WATCHER_STARTUP.COM to start the Watcher process. __________________________________________________________________ 1.1 Required Logical Names The three system-wide logical names WATCHER requires are: WATCHER_DIR Should point to location of images and command procedures WATCHER_CONFIG Configuration file to be used WATCHER_TRACE Trace file; use NL: if debug disabled They should all be defined in executive mode. ___________________________ 1.1.1 Logical Name for Help Library The help library for WCP may be placed in SYS$HELP, or, if you define the logical name WCP_HELPLIB to be the full path name of the file, anywhere else on the system. __________________________________________________________________ 1.2 Privileges Required The account that is used for the WATCHER process requires the following privileges: CMKRNL Required for DECwindows support and disconnects PRMMBX For defining the command mailbox PSWAPM Required for disconnects 1-2 Installing WATCHER SHARE For sending warning messages to other users' terminals SYSNAM For defining the command mailbox SYSPRV (optional) to ensure access to appropriate files WORLD For getting information about and killing processes SYSPRV is not needed if you make sure that WATCHER has enough access to read its configuration files and the system rightslist (if using identifiers as an exclusion criterion), and write its log and trace files (if used). Both CMKRNL and SYSPRV are required for DECwindows support. CMKRNL and PSWAPM are required to perform virtual terminal disconnections. __________________________________________________________________ 1.3 Other Requirements The RUN command in WATCHER_STARTUP.COM should provide the WATCHER process with sufficient quotas to operate on most systems. CPU and memory requirements will vary depending on the number of rules in the WATCHER configuration, peak number of interactive users, and peak number of watched users. You may wish to refer to the following table in computing expected memory resources needed by the WATCHER process: Memory required per WATCH rule 206 bytes Memory required per EXCLUDE or OVERRIDE 250 bytes rule Memory required per interactive process 208 bytes 1-3 Installing WATCHER Memory required per watched process 254 bytes Size of WATCHER code (approximate) 15K bytes Allow a small increase in CPU, memory, and I/O requirements if identifiers are used as an exclusion mechanism, since WATCHER will require access to the rightslist database for each interactive process. DECwindows support also requires additional overhead for access to the job logical name table of all interactive and detached processes on the system. 1-4 _______________________________________________________ 2 Configuring WATCHER The WATCHER Control Program (WCP) is used to create WATCHER configurations. WCP is designed to be executed as a VMS foreign command. To set up the foreign command, define the symbol $WCP :== $WATCHER_DIR:WCP or, if you want to have the current configuration loaded automatically each time you invoke WCP, define the symbol as $WCP :== $WATCHER_DIR:WCP/FILE=WATCHER_CONFIG Once the symbol is set up, you can invoke WCP with the command: $WCP __________________________________________________________________ 2.1 Setting up WATCH Rules The WATCH command sets up rules that determine which terminals get watched, how to determine whether the terminals are active, and how long terminals must be inactive before a user can be forced off. For example: WCP>WATCH *$RT*/MEASURE=PROCESS_IO/LOGOUT=00:15:00 This command sets up a rule for watching all DECnet remote logins, using changes in total process I/O (buffered plus direct) to determine process activity, and causing logouts to occur after 15 minutes of activity. Note: You must have at least one WATCH command in your configuration. 2-1 Configuring WATCHER ___________________________ 2.1.1 Identifying Terminals WATCH commands take any wildcard pattern. All terminal device names that match the specified pattern are watched. The device names used by WATCHER are the physical device names of terminals; if the system is part of a VAXcluster, SCS node name is prefixed to the device name, as is normally done by VMS with cluster-accessible devices. If the terminal device driver supports remote port identification, as does the LTDRIVER for LAT terminals, the remote port information can also be used as a match criterion by using the /ACCPORNAM qualifier. The port name can be specified as a wildcard pattern. For example: WCP>WATCH *$LT*/ACCPORNAM="TRMSRV/*" This command would cause the terminals attached to terminal server TRMSRV to be watched. ___________________________ 2.1.2 WATCH Criteria WATCHER gives you the choice of using one or more of the following measurements as criteria for judging whether a terminal or user is active: TERMINAL_IO the I/O operation count on the terminal device CPU The total CPU time used by the process owning the terminal plus all of its subprocesses, in centiseconds 2-2 Configuring WATCHER PROCESS_IO the sum of the buffered and direct I/O counts of the process owning the terminal plus all of its subprocesses The TERMINAL_IO measurement is useful for conventional terminals but cannot be used for workstations (running either VWS or DECwindows) due to the nature of workstation activity. PROCESS_IO is recommended for use on workstation terminal devices. For any of these measurements you can specify a minimum threshold value. When WATCHER performs a comparison, the difference between the current measured value and the last measured value must be greater than the specified threshold to be counted as activity. The default threshold value is zero, so that any difference at all counts as activity. ___________________________ 2.1.3 Terminal Groupings You can group WATCH rules together by using the /GROUP qualifier. When WATCHER applies its rules for determining terminal activity, activity on one terminal in the group counts as activity for all the terminals in the group. The main use for this feature is with multi-windowed terminals and workstations running VWS (DECwindows workstations are handled in this manner automatically). For example, the following rules handle all the workstation terminal types on a standalone VWS workstation: WCP>WATCH WTA*/GROUP=VWS ! normal VT200-series windows WCP>WATCH TKA*/GROUP=VWS ! Tek 4010 emulation windows WCP>WATCH TJA*/GROUP=VWS ! Tek 4125 emulation windows The user can then create any number of any type of terminal window, and as long as one of them is active, they will all remain logged in. 2-3 Configuring WATCHER __________________________________________________________________ 2.2 Exclusions and Overrides WATCHER's behaviour towards a terminal or user can be modified through the definition of exclusion and override rules. Exclusions and overrides can be based on any combination of username, terminal/port name, UIC, privileges, a held identifier, and time of day. Exclusion rules prevent WATCHER from taking any action towards a user, while override rules merely modify how the terminal is watched (i.e., the activity criteria and inactivity periods). For example (taken from a VAXcluster system): WCP>EXCLUDE SYSTEM/TERMINAL=*$OPA0: WCP>OVERRIDE JONES/TERMINAL=NODE1$TXA3:/DURING=(PRIMARY:8-16)- _WCP> /LOGOUT=02:00:00 The first command prevents WATCHER from taking any action against the SYSTEM account while it is logged into the system console. The second command extends the logout inactivity period to two hours for user JONES weekdays from 8 am to 4:59 pm, while JONES is logged into the terminal in her office, which is on port TXA3 on system NODE1. __________________________________________________________________ 2.3 Saving Configurations Once you have established the rules you need for your configuration, you should create the configuration file with the SAVE command: WCP>SAVE WATCHER_CONFIG If WATCHER is currently running, you can have the new configuration take effect immediately with the RESET command, which will cause the WATCHER process to reload its configuration information from the file. 2-4 Configuring WATCHER ___________________________ 2.3.1 VAXcluster Environments For mainly homogeneous VAXcluster environments, you should be able to use one configuration file for all nodes in the cluster. If you have a mix of nodes, however, it may be easier to create multiple configuration files and define the WATCHER_CONFIG logical name differently depending on the system. ___________________________ 2.3.2 Editing Configurations You can make changes to the current configuration by invoking WCP with the /FILE qualifier: $WCP/FILE=WATCHER_CONFIG The WATCH, EXCLUDE, and OVERRIDE commands all have a /DELETE to allow you to remove rules from the database, and you can add rules as well. However, you cannot control the order of the new rules (order is important because WATCHER searches the rule lists in the order you enter them until one matches). To assist in making complex changes to the configuration, the SHOW command has a /COMMAND qualifier that causes the configuration information to be displayed as commands you would enter to build the configuration: WCP>SHOW/COMMAND/OUTPUT=CONFIG.WCP ALL Once you dump the commands to the command file, you can edit the command file as needed and create a new configuration with the commands: $WCP WCP>@CONFIG WCP>SAVE WATCHER_CONFIG Instead of editing the configuration, it may be easier just to maintain a WCP command file with the necessary commands in it and build a new configuration each time you need to make a change. 2-5 Configuring WATCHER __________________________________________________________________ 2.4 DECwindows Support The VMS DECwindows implementation makes it difficult for a WATCHER-type program to properly identify, warn, and logout DECwindows sessions. However, WATCHER does provide limited support for watching DECwindows sessions, enabled with the following commands: WCP>SET DECWINDOWS WCP>WATCH *WSA*/MEASURE=PROCESS_IO/NOWARNING Note that you cannot use TERMINAL_IO as a measurement when watching DECwindows sessions, nor can WATCHER give warnings to idle DECwindows sessions. WATCHER identifies DECwindows sessions by searching the job logical name table for each interactive process for the logical name DECW$DISPLAY, defined in executive mode. Each interactive job related to a single DECwindows session will have the same value for DECW$DISPLAY. WATCHER immediately changes the terminal device name it uses to the WSA device name (even for DECterm sessions) and also sets the group name to the WSA device name. In this way, activity in any of the DECwindows jobs will be counted as activity for all jobs related to that session. The DECwindows window manager and DECterm controller processes are detached processes that are also needed by WATCHER (when forcing off a DECwindows session). To identify these processes, WATCHER searches for detached processes with DECW$DISPLAY defined in user mode. WATCHER tracks these processes, but does not use them in activity determination (it calls them "fake" processes in debug/trace logs). When WATCHER identifies a DECwindows session to be forced off, it looks for all processes (including the detached processes, which are important) with a matching WSA device name and forces them off. This should destroy all the windows on the workstation and return it to a blank, background screen. It then 2-6 Configuring WATCHER creates a detached process that executes the DECW_ STARTLOGIN command procedure (which must be WATCHER_ DIR:), which, after waiting a few seconds for other activity to die down, restarts the login process on the affected WSA device. WATCHER cannot be used to watch DECwindows jobs that are started on remote systems, with the local workstation being used only as a display. There must be at least some jobs running on the workstation with some activity to prevent WATCHER from logging out the DECwindows session. This technique should be effective for VMS DECwindows implementations under VMS V5.1 through V5.3-1, even with VT1xxx X terminals. It may not work with future DECwindows implementations. 2-7 _______________________________________________________ 3 Troubleshooting WATCHER If WATCHER is not behaving as expected, there may be a problem with your WATCHER configuration. There is debug/trace code built into WATCHER to allow you to monitor three categories of activities: the mainline WATCHER code, the exclusion-checking code, and the override-checking code. Through the use of the SET DEBUG command, you can turn on tracing for any or all of these debugging categories. If WATCHER is already running, the best way to set up a test configuration is with the following command sequence: $SET PROCESS/PRIVILEGE=(SYSNAM,SYSPRV) $WCP/FILE=WATCHER_CONFIG WCP>SET DEBUG=n WCP>SAVE WATCHER_DIR:TEST_CONFIG WCP>EXIT $DEFINE/SYSTEM/EXEC WATCHER_CONFIG WATCHER_DIR:TEST_CONFIG $DEFINE/SYSTEM/EXEC WATCHER_TRACE trace-file-spec $WCP RESET The debug level n is described in the SET DEBUG command description, but usually will be 1 (just mainline) or 31 (full). You can direct the trace information to any file accessible to WATCHER, or to an unowned terminal. Subsequent WCP RESET commands will cause the trace file to be closed and a new version created, so you can easily view past trace information. To go back to "production" mode, just redefine WATCHER_CONFIG back to the name of the real configuration file, define 3-1 Troubleshooting WATCHER WATCHER_TRACE to be NL:, and issue another WCP RESET command. __________________________________________________________________ 3.1 Forcing Wakeups To assist in debugging, you may want to have WATCHER wake up more often than normal. You can do this by setting a shorter wakeup interval in the test configuration, or you can force a wakeup to occur by writing to the WATCHER control mailbox. From a suitably privileged account (SYSPRV), you can use the commands: $OPEN/WRITE WMBOX WATCHER_MBOX: $WRITE WMBOX "" $CLOSE WMBOX Each WRITE command will trigger a wakeup, and WATCHER will go through its processing sequence. 3-2 _______________________________________________________ Part II Command Descriptions Command Descriptions WCP _______________________________________________________ WCP Executes the WATCHER Control Program. _______________________________________________________ FORMAT WCP [command] _______________________________________________________ Command Qualifiers Defaults /FILE=file-spec _______________________________________________________ PARAMETERS [command] Any WCP command except the input redirection operator (@). The specified command is executed and control is returned to DCL immediately thereafter. _______________________________________________________ DESCRIPTION WCP is intended to be used as a DCL "foreign" command. To use it as a foreign command, you must define a symbol as follows: $WCP :== $WATCHER_EXE:WCP Defining the symbol in this way allows you to use the /FILE qualifier and specify "one-shot" commands on the command line. If you want to have the currently active configuration loaded each time you invoke WCP, you should define the WCP symbol as: $WCP :== $WATCHER_EXE:WCP/FILE=WATCHER_CONFIG CMD-3 Command Descriptions WCP This presumes that the logical name WATCHER_CONFIG is defined in the system logical name table. _______________________________________________________ QUALIFIERS /FILE=file-spec Loads the specified WATCHER configuration file for editing. If not specified, no configuration information is loaded. The default file type is WCFG. CMD-4 Command Descriptions @ (Redirect Command Input) _______________________________________________________ @ (Redirect Command Input) Executes WCP commands read from a file. _______________________________________________________ FORMAT @ file-spec _______________________________________________________ PARAMETERS file-spec Name of the file containing WCP commands. If omitted, the default file type is WCP. _______________________________________________________ DESCRIPTION Use this command to have WCP take further command input from the specified file. There is no built-in limit on the number of levels of nesting of command files, so be careful when using input redirection from within a command file. Commands read from command files are not displayed unless you SET VERIFY. Command redirection can only be used at the WCP command prompt, not as a "one-shot" WCP command. To have a file be used for input for an entire WCP session, use the following sequence of DCL commands. $DEFINE/USER SYS$INPUT file-spec $WCP CMD-5 Command Descriptions EXCLUDE _______________________________________________________ EXCLUDE Defines an exclusion rule. _______________________________________________________ FORMAT EXCLUDE username-pat _______________________________________________________ Command Qualifiers Defaults /ACCPORNAM=port-pat /ACCPORNAM=* /DELETE /DURING=daytim-list (all the time) /HOLDING=identifier (ignored) /PRIVILEGES=priv-list (ignored) /TERMINAL=dev-pat /TERMINAL=* /UIC=uic /UIC=[*,*] _______________________________________________________ PARAMETERS username-pat A VMS username or pattern containing wildcards, identifying the user to be excluded. _______________________________________________________ DESCRIPTION This command is used to add or remove (with /DELETE) an exclusion rule to the WATCHER configuration. When WATCHER is running, any process that matches all of the specified criteria is not watched. Omitted criteria are not used or always match. CMD-6 Command Descriptions EXCLUDE _______________________________________________________ QUALIFIERS /ACCPORNAM=port-pat Port name or pattern containing wildcards, identifying the terminal port (for terminal servers and other devices using port names) on which the user must be logged in to be excluded. The default is any port. /DELETE Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. /DURING=daytim-list Specifies a list of days and times during which the user is to be excluded from watching. The day/time specifications are of the form day:(hour-range[,...]) where day is a day of the week or the word PRIMARY or SECONDARY, identifying the primary and secondary days set with SET DAYS, and hour-range is either a single hour number (0 through 23) or two hour numbers separated by a hyphen. Multiple hour ranges may be specified per day. /HOLDING=identifier Specifies that the user should be excluded if holding the specified identifier. The identifier is converted to binary format before being stored in the configuration, so you must create the configuration file on the target system, or on a node with the same RIGHTSLIST database as the target system, to prevent misinterpretation of the identifier. If you are running VMS V5.4 or later, WATCHER obtains the identifiers held by the process directly (using $GETJPI), and thus can check identifiers that are granted dynamically. Prior to V5.4, WATCHER uses the $FIND_HELD system service to scan the system rightslist for identifiers held by the user that owns CMD-7 Command Descriptions EXCLUDE each process; dynamically granted identifiers cannot be checked in this case. Note that if you do not use /HOLDING on any EXCLUDE or OVERRIDE command, the rights identifier information is not collected by WATCHER, resulting in some savings in processing time. /PRIVILEGES=priv-list Specifies that the user is to be excluded only when holding the specified privilege or privileges. If omitted, privileges are not used as a criterion. /TERMINAL=dev-pat Specifies a terminal device name or pattern containing wildcards. The user must be logged into a matching terminal to be excluded. /UIC=uic Specifies a UIC or UIC pattern. A process is excluded only when owned by a matching UIC. You may use an asterisk for the member part of the UIC to have all UIC's in a group match. If omitted, any UIC will match. CMD-8 Command Descriptions EXIT _______________________________________________________ EXIT Ends a WCP session. _______________________________________________________ FORMAT EXIT _______________________________________________________ DESCRIPTION Ends the current WCP session and returns control to DCL. If you have modified the configuration, EXIT will ask for a file name for saving the configuration before exiting. CMD-9 Command Descriptions HELP _______________________________________________________ HELP Displays help information. _______________________________________________________ FORMAT HELP [topic...] _______________________________________________________ PARAMETERS topic The name of a topic in the help library. If omitted, a list of topics is displayed. _______________________________________________________ DESCRIPTION This command is pretty straightforward. CMD-10 Command Descriptions OVERRIDE _______________________________________________________ OVERRIDE Defines an override rule. _______________________________________________________ FORMAT OVERRIDE username-pat _______________________________________________________ Command Qualifiers Defaults /ACCPORNAM=port-pat /ACCPORNAM=* /DELETE /DURING=daytim-list (all the time) /HOLDING=identifier (ignored) /PRIVILEGES=priv-list (ignored) /TERMINAL=dev-pat /TERMINAL=* /UIC=uic /UIC=[*,*] /[NO]DISCONNECT[=deltatime] /[NO]LOGOUT[=deltatime] /MEASURE=(measurement[,...]) /[NO]WARNING[=deltatime] _______________________________________________________ PARAMETERS username-pat A VMS username or pattern containing wildcards, identifying the user for which the override is to take effect. _______________________________________________________ DESCRIPTION This command is used to add or remove (with /DELETE) an override rule to the WATCHER configuration. When WATCHER is running, any process that matches all of the specified criteria will have the warning, logout, CMD-11 Command Descriptions OVERRIDE and measurement information, if specified, taken from the override rule instead of the WATCH rule. _______________________________________________________ QUALIFIERS /ACCPORNAM=port-pat Port name or pattern containing wildcards, identifying the terminal port (for terminal servers and other devices using port names) on which the user must be logged in to be excluded. The default is any port. /DELETE Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. /DURING=daytim-list Specifies a list of days and times during which the user is to be excluded from watching. The day/time specifications are of the form day:(hour-range[,...]) where day is a day of the week or the word PRIMARY or SECONDARY, identifying the primary and secondary days set with SET DAYS, and hour-range is either a single hour number (0 through 23) or two hour numbers separated by a hyphen. Multiple hour ranges may be specified per day. /HOLDING=identifier Specifies that the user should be excluded if holding the specified identifier. The identifier is converted to binary format before being stored in the configuration, so you must create the configuration file on the target system, or on a node with the same RIGHTSLIST database as the target system, to prevent misinterpretation of the identifier. CMD-12 Command Descriptions OVERRIDE If you are running VMS V5.4 or later, WATCHER obtains the identifiers held by the process directly (using $GETJPI), and thus can check identifiers that are granted dynamically. Prior to V5.4, WATCHER uses the $FIND_HELD system service to scan the system rightslist for identifiers held by the user that owns each process; dynamically granted identifiers cannot be checked in this case. Note that if you do not use /HOLDING on any EXCLUDE or OVERRIDE command, the rights identifier information is not collected by WATCHER, resulting in some savings in processing time. /PRIVILEGES=priv-list Specifies that the user is to be excluded only when holding the specified privilege or privileges. If omitted, privileges are not used as a criterion. /TERMINAL=dev-pat Specifies a terminal device name or pattern containing wildcards. The user must be logged into a matching terminal to be excluded. /UIC=uic Specifies a UIC or UIC pattern. A process is excluded only when owned by a matching UIC. You may use an asterisk for the member part of the UIC to have all UIC's in a group match. If omitted, any UIC will match. /[NO]DISCONNECT[=deltatime] Specifies that the logout/disconnect information should be overridden, performing a virtual terminal disconnection instead of deleting the user process. The inactivity interval can be overridden by specifying a deltatime, or logouts/disconnects can be prevented altogether by specifying /NODISCONNECT (although it is more efficient to use EXCLUDE for this). CMD-13 Command Descriptions OVERRIDE /[NO]LOGOUT[=deltatime] Specifies that the logout/disconnect information should be overridden, performing a process deletion instead of a virtual terminal disconnection. The inactivity interval can be overridden by specifying a deltatime, or logouts can be prevented by specifying /NOLOGOUT (although it is more efficient to use EXCLUDE for this). /MEASURE=(measurement[,...]) Specifies that the activity measurements should be overridden. For measurement, specify one of the following: CPU[:threshold] CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If threshold is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active. CMD-14 Command Descriptions OVERRIDE PROCESS_IO[:threshold] Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If threshold is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active. TERMINAL_IO[:threshold] Terminal I/O (the operation count on the terminal device) should be used as a criterion. If threshold is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active. Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, threshold values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). /[NO]WARNING[=deltatime] Specifies that the warning information should be overridden. The warning inactivity interval can be overridden by specifying a deltatime, or warnings can be prevented by specifying /NOWARNING. CMD-15 Command Descriptions QUIT _______________________________________________________ QUIT Quits WCP without saving configuration changes. _______________________________________________________ FORMAT QUIT _______________________________________________________ DESCRIPTION If changes to the configuration have been made, you are asked for confirmation before quitting. CMD-16 Command Descriptions RESET _______________________________________________________ RESET Sends a reset command to the WATCHER process. _______________________________________________________ FORMAT RESET _______________________________________________________ DESCRIPTION This command sends a reset command to the WATCHER process, which causes WATCHER to flush all process and configuration information, close its log and trace files, and read in the configuration again. OPER and SYSPRV privileges are required for this command. CMD-17 Command Descriptions SAVE _______________________________________________________ SAVE Saves a WATCHER configuration. _______________________________________________________ FORMAT SAVE [file-spec] _______________________________________________________ PARAMETERS file-spec Name of the file to which the configuration should be written. If omitted, it defaults to the name of the file read in with the WCP/FILE qualifier (if any). If specified, the default file type is WCFG and the default location is the current default directory. CMD-18 Command Descriptions SET BELL _______________________________________________________ SET BELL Enables or disables the ringing of the terminal bell on warnings and logouts. _______________________________________________________ FORMAT SET [NO]BELL _______________________________________________________ DESCRIPTION By default, the terminal bell is not rung when WATCHER displays a warning or logout message on a terminal. SET BELL will cause WATCHER to send a BEL character with the message to cause the terminal bell to ring. CMD-19 Command Descriptions SET DAYS _______________________________________________________ SET DAYS Establishes the primary and secondary day settings for subsequent commands. _______________________________________________________ FORMAT SET DAYS _______________________________________________________ Command Qualifiers Defaults /PRIMARY=(day-list) /SECONDARY=(day-list) _______________________________________________________ DESCRIPTION This command is used to move one or more days from the primary day list to the secondary day list or vice- versa. These lists are used as shorthand by other commands when you specify PRIMARY or SECONDARY on a /DURING qualifier. CMD-20 Command Descriptions SET DEBUG _______________________________________________________ SET DEBUG Enables or disables debug tracing and sets the level of debug information. _______________________________________________________ FORMAT SET [NO]DEBUG[=mask] _______________________________________________________ DESCRIPTION SET DEBUG turns on debug tracing. WATCHER will send debug output to the file or device identified by the WATCHER_TRACE logical name. For mask, specify a decimal number representing a bitmask indicating which kinds of debugging information you want logged. _______________________________________________________ Value_____Bit_no.___Description________________________ 1 0 main line code 2 1 exclusion checks 4 2 override checks 8 3 measurement checks _16_________4_______process_info_collection____________ The mask value can be any one of the above, or a sum of any of the above values. Use SET NODEBUG to disable debug tracing. CMD-21 Command Descriptions SET DECWINDOWS _______________________________________________________ SET DECWINDOWS Enables or disables extra processing required for DECwindows support. _______________________________________________________ FORMAT SET [NO]DECWINDOWS _______________________________________________________ DESCRIPTION Since the DECwindows support requires additional processing beyond that used for watching normal terminals, it is by default turned off. You should only SET DECWINDOWS when you will be running WATCHER on a DECwindows workstation (or a system with DECwindows terminals). You will also need to include a WATCH rule for WSA terminal devices to watch DECwindows sessions (as described in Section 2.4). CMD-22 Command Descriptions SET EVENT_LOG _______________________________________________________ SET EVENT_LOG Establishes how normal WATCHER events are recorded. _______________________________________________________ FORMAT SET [NO]EVENT_LOG _______________________________________________________ Command Qualifiers Defaults /FILE=file-spec /OPERATOR=oper-list _______________________________________________________ DESCRIPTION This command specifies how normal WATCHER events (startup, shutdown, reset, and logout events) are recorded. By default, WATCHER events are logged to the CENTRAL operator class. _______________________________________________________ QUALIFIERS /FILE=file-spec Directs event logging to the specified file. /OPERATOR=oper-list Specifies a list of one or more operator classes to which WATCHER events should be logged. If more than one operator class name is specified, the list should be comma-separated and surrounded by parentheses. CMD-23 Command Descriptions SET INTERVAL _______________________________________________________ SET INTERVAL Sets the hibernation interval between processing passes. _______________________________________________________ FORMAT SET INTERVAL=delta-time _______________________________________________________ DESCRIPTION This command sets the length of time WATCHER hibernates between processing passes. The default is 5 minutes. The value you should use should be smaller than the warning and logout intervals for all terminals and smaller than the difference between the logout and warning intervals for any single terminal. Too small a value, however, will cause WATCHER to waste CPU time. CMD-24 Command Descriptions SET MULTIWARN _______________________________________________________ SET MULTIWARN Enables or disables multiple warnings. _______________________________________________________ FORMAT SET [NO]MULTIWARN _______________________________________________________ DESCRIPTION By default, WATCHER displays only one warning on terminals, at the time specified on the /WARNING qualifier. SET MULTIWARN enables multiple warnings; one at the /WARNING time and again each time WATCHER makes a processing pass (controlled by SET INTERVAL) until the /LOGOUT or /DISCONNECT time is reached. This is a system-wide setting. CMD-25 Command Descriptions SET VERIFY _______________________________________________________ SET VERIFY Enables or disables echoing of commands in command files. _______________________________________________________ FORMAT SET [NO]VERIFY _______________________________________________________ DESCRIPTION The SET VERIFY command turns on command verification, so that commands read from WCP command files are echoed to the terminal. SET NOVERIFY turns off verification, which is the default. CMD-26 Command Descriptions SET WATCH_DEFAULT _______________________________________________________ SET WATCH_DEFAULT Establishes defaults for subsequent WATCH commands. _______________________________________________________ FORMAT SET WATCH_DEFAULT _______________________________________________________ Command Qualifiers Defaults /[NO]DISCONNECT[=deltatime] /[NO]LOGOUT[=deltatime] /MEASURE=(measurement[,...]) /[NO]WARNING[=deltatime] _______________________________________________________ DESCRIPTION The SET WATCH_DEFAULT command is used to set logout, warning, and measurement defaults for subsequent WATCH commands. The defaults set by this command have effect only for WATCH commands issued in the current WCP session; they are not saved. _______________________________________________________ QUALIFIERS /[NO]DISCONNECT[=deltatime] Sets the default for disconnects, to be used if not specified on subsequent WATCH commands. You may not specify both /DISCONNECT and /LOGOUT. /[NO]LOGOUT[=deltatime] Sets the default for logouts, to be used if not specified on subsequent WATCH commands. You may not specify both /DISCONNECT and /LOGOUT. CMD-27 Command Descriptions SET WATCH_DEFAULT /MEASURE=(measurement[,...]) Sets the default measurements to be used for activity determination if not specified on subsequent WATCH commands. For measurement, specify one of the following: CPU[:threshold] CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If threshold is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active. PROCESS_IO[:threshold] Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If threshold is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active. CMD-28 Command Descriptions SET WATCH_DEFAULT TERMINAL_IO[:threshold] Terminal I/O (the operation count on the terminal device) should be used as a criterion. If threshold is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active. Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, threshold values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). /[NO]WARNING[=deltatime] Sets the defaults for warnings, to be used if not specified on subsequent WATCH commands. CMD-29 Command Descriptions SHOW _______________________________________________________ SHOW Displays all or part of the current configuration. _______________________________________________________ FORMAT { ALL } { BELL } { DAYS } { } { DEBUG } { DEFAULTS } { EVENT_LOG } SHOW { } { EXCLUDE } { FILE } { GLOBALS } { } { INTERVAL } { OVERRIDE } { WATCH } { } _______________________________________________________ Command Qualifiers Defaults /[NO]COMMAND /NOCOMMAND /OUTPUT=file-spec /OUTPUT=SYS$OUTPUT: _______________________________________________________ DESCRIPTION The SHOW command displays information about the current configuration and the WCP default settings. _______________________________________________________ QUALIFIERS /[NO]COMMAND The /COMMAND qualifier indicates that the display should be formatted as the commands that would be entered to create the specified records. Use /COMMAND CMD-30 Command Descriptions SHOW with the /OUTPUT qualifier to create an MCP command file that can be altered with your favorite editor, then read back into MCP to create a new configuration. /OUTPUT=file-spec The /OUTPUT qualifier is used to direct the SHOW result to a file or other device. By default, the result is displayed on the current output device, SYS$OUTPUT. CMD-31 Command Descriptions SHUTDOWN _______________________________________________________ SHUTDOWN Sends a shutdown command to the WATCHER process. _______________________________________________________ FORMAT SHUTDOWN _______________________________________________________ DESCRIPTION This command sends a shutdown command to the WATCHER process, which causes WATCHER to close its log files and exit. OPER and SYSPRV privileges are required for this command. CMD-32 Command Descriptions WATCH _______________________________________________________ WATCH Defines a watch rule. _______________________________________________________ FORMAT WATCH device-pat _______________________________________________________ Command Qualifiers Defaults /ACCPORNAM=port-pat /ACCPORNAM=* /DELETE /[NO]DISCONNECT[=deltatime] /[NO]LOGOUT[=deltatime] /MEASURE=(measurement[,...]) /[NO]WARNING[=deltatime] _______________________________________________________ PARAMETERS device-pat A terminal device name or pattern containing wildcards, to identify the terminal(s) to be watched. _______________________________________________________ DESCRIPTION This command is used to add or remove (with /DELETE) a watch rule to the WATCHER configuration. When WATCHER is running, a process running on any terminal matching the specified criteria will be watched for inactivity, using the specified parameters. _______________________________________________________ QUALIFIERS /ACCPORNAM=port-pat Port name or pattern containing wildcards, identifying the terminal port(s) (for terminal servers and other CMD-33 Command Descriptions WATCH devices using port names) to be watched. The default is any port. /DELETE Specifies that the rule should be deleted from the configuration. All criteria must match exactly for the rule to be deleted. /[NO]DISCONNECT[=deltatime] For systems with virtual terminals enabled, this qualifier specifies whether the terminal should be disconnected from the system, and if so, how long the terminal should be inactive before the disconnection occurs. If virtual terminals are not enabled, or the terminal to be forced off is not connected through a virtual terminal, the process is logged out (the same effect as for the /LOGOUT qualifier). If both this qualifier and /LOGOUT are omitted, the disconnect/logout default is taken from the current SET WATCH_DEFAULT setting. The /DISCONNECT and /LOGOUT qualifiers are mutually exclusive. /[NO]LOGOUT[=deltatime] Specifies whether the terminal should be logged out, and if so, how long the terminal should be inactive before logout occurs. If this qualifier and /DISCONNECT are omitted, the logout/disconnect default is taken from the current SET WATCH_DEFAULT setting. The /DISCONNECT and /LOGOUT qualifiers are mutually exclusive. /MEASURE=(measurement[,...]) Specifies the measurements that should be used for activity determination. For measurement, specify one of the following: CMD-34 Command Descriptions WATCH CPU[:threshold] CPU time (the sum of the CPU time used by the process and all its subprocesses, in centiseconds) should be used as a criterion. If threshold is specified, the difference in CPU time between passes must exceed the specified threshold for a process to be considered active. PROCESS_IO[:threshold] Process I/O (the sum of the buffered and direct I/O counts for the process and all its subprocesses) should be used as a criterion. If threshold is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active. TERMINAL_IO[:threshold] Terminal I/O (the operation count on the terminal device) should be used as a criterion. If threshold is specified, the difference in I/O counts between passes must exceed the specified threshold for a process to be considered active. CMD-35 Command Descriptions WATCH Any combination of PROCESS_IO, CPU, and TERMINAL_IO is permitted. If omitted, threshold values default to zero. Note that threshold values should be chosen as a function of the wakeup interval (defined with SET INTERVAL). If no /MEASUREMENT qualifier is specified, the measurement settings are taken from the SET WATCH_ DEFAULT settings. /[NO]WARNING[=deltatime] Specifies whether the terminal should be warned about inactivity, and if so, how long the terminal should be inactive before warning is sent. The warning interval should be less than the logout interval. If omitted, the default is taken from the current SET WATCH_ DEFAULT setting. CMD-36