Guide to Installing and Using WATCHER
February, 1993
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: VAX/VMS V5.0 or later,
OpenVMS AXP V1.0 or later
Software Version: WATCHER V2.8
Matthew D. Madison
TGV, Incorporated
Santa Cruz, California
________________________
03 February 1993
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 author and TGV, Inc. make no
| representations or warranties with respect to the
| contents hereof and specifically disclaim any implied
| warranties of merchantability or fitness for any
| particular purpose.
__________
Copyright ©1993 Matthew D. Madison. 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-17
RESET CMD-18
SAVE CMD-19
SET BELL CMD-20
SET DAYS CMD-21
SET DEBUG CMD-22
SET DECWINDOWS CMD-23
SET EVENT_LOG CMD-24
SET INTERVAL CMD-25
SET MULTIWARN CMD-26
SET VERIFY CMD-27
SET WATCH_DEFAULT CMD-28
SHOW CMD-31
SHUTDOWN CMD-33
WATCH CMD-34
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, time-of-day/day-of-week, and name of image
being run.
v
Preface
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,
privileges, terminal device and/or port name, time-
of-day/day-of-week, and name of image being run.
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@tgv.com. 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
TGV, Incorporated
vi
Preface
603 Mission Street
Santa Cruz, CA 95060 USA
Phone: +1 408 427 4366
Fax: +1 408 427 4365
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. The sample WATCHER_STARTUP.COM includes the
necessary DEFINE command to do this for you.
__________________________________________________________________
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
1-2
Installing WATCHER
PSWAPM Required for disconnects
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 on pre-VMS V5.4 systems), 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 507 bytes
rule
1-3
Installing WATCHER
Memory required per interactive process 465 bytes
Memory required per watched process 531 bytes
Size of WATCHER code (approximate) 18K bytes
On pre-VMS V5.4 systems, 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
tables 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
Once the symbol is set up, you can invoke WCP with the
command:
$ WCP
WCP will automatically load the contents of your
defined WATCHER_CONFIG file, if it exists.
__________________________________________________________________
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.
Several samples of WATCH commands with different
criteria and threshold values are provided in SAMPLE_
CONFIG.WCP.
___________________________
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
2-3
Configuring WATCHER
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.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, image being run, 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
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/NOFILE
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 located in
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
V2 (VMS V5.1 through V5.5) and V3 (also known as
DECwindows/Motif V1.0), and should even work with 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 five categories of activities: the
mainline WATCHER code, the exclusion-checking code,
the override-checking code, measurement checks, and
process information collection. 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
WCP> SET DEBUG=n
WCP> SET NOACTION
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.
The SET NOACTION command will prevent WATCHER from
actually logging anyone out or sending warning
messages to terminals.
3-1
Troubleshooting WATCHER
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
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 See description.
_______________________________________________________
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.
CMD-3
Command Descriptions
WCP
_______________________________________________________
QUALIFIERS
/[NO]FILE=file-spec
Loads the specified WATCHER configuration file for
editing. If not specified, the configuration file
pointed to by the logical name WATCHER_CONFIG is
loaded. The default file type is WCFG. If /NOFILE
is specified, no configuration file is loaded.
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)
/IMAGE=fspec-pat /IMAGE=*
/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 (especially on pre-V5.4 systems).
/IMAGE=fspec-pat
Specifies that the user should be excluded if running
an executable image whose name (as returned by the
JPI$_IMAGNAME item from $GETJPI) matches the specified
wildcard pattern. For a job with subprocesses, the
image name that WATCHER uses for matching against
the wildcard pattern is the image currently being run
by the master process in the job, or, if the master
process is not running an image, an image being run
by one of the subprocesses (randomly selected if there
are two or more such subuprocesses).
/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)
/IMAGE=fspec-pat /IMAGE=*
/PRIVILEGES=priv-list (ignored)
/TERMINAL=dev-pat /TERMINAL=*
/UIC=uic /UIC=[*,*]
/[NO]DISCONNECT[=deltatime]
| /[NO]FORCE_EXIT[=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.
CMD-11
Command Descriptions
OVERRIDE
_______________________________________________________
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,
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
CMD-12
Command Descriptions
OVERRIDE
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
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 (especially on pre-VMS V5.4 systems).
/IMAGE=fspec-pat
Specifies that the user should be excluded if running
an executable image whose name (as returned by the
JPI$_IMAGNAME item from $GETJPI) matches the specified
wildcard pattern. For a job with subprocesses, the
image name that WATCHER uses for matching against
the wildcard pattern is the image currently being run
by the master process in the job, or, if the master
process is not running an image, an image being run
by one of the subprocesses (randomly selected if there
are two or more such subuprocesses).
/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.
CMD-13
Command Descriptions
OVERRIDE
/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).
|
| /[NO]FORCE_EXIT[=deltatime]
| Specifies that the logout/disconnect information
| should be overridden, performing a forced image exit
| instead of deleting the process or disconnecting
| the terminal. Only user-mode images are forced; if
| the user is at DCL command level, the forced exit is
| skipped. The inactivity interval can be overridden by
| specifying a deltatime, or exits/logouts/disconnects
| can be prevented altogether by specifying /NOFORCE_
| EXIT (although it is more efficient to use EXCLUDE for
| this).
/[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).
CMD-14
Command Descriptions
OVERRIDE
/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.
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-15
Command Descriptions
OVERRIDE
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-16
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-17
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-18
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-19
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-20
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-21
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-22
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-23
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-24
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-25
Command Descriptions
SET MULTIWARN
_______________________________________________________
SET MULTIWARN
Enables or disables multiple warnings.
_______________________________________________________
FORMAT
SET [NO]MULTIWARN
_______________________________________________________
Command Qualifiers Defaults
/INTERVAL=delta-time /INTERVAL="0 00:05:00"
_______________________________________________________
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 every five minutes
(or whatever interval you specify) until the /LOGOUT
or /DISCONNECT time is reached.
This is a system-wide setting.
_______________________________________________________
QUALIFIERS
/INTERVAL=delta-time
Specifies the interval of time that should occur
between warnings. If omitted, defaults to five
minutes. This value should equal or exceed the wakeup
interval value (specified by SET INTERVAL). The
actual interval between warnings may be longer than
the specified time, since checks are made only at
each processing pass (the interval between which is
controlled by the wakeup interval value).
CMD-26
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-27
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]FORCE_EXIT[=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 are saved between WCP
| sessions.
_______________________________________________________
QUALIFIERS
/[NO]DISCONNECT[=deltatime]
Sets the default for disconnects, to be used if not
| specified on subsequent WATCH commands. /DISCONNECT,
| /FORCE_EXIT, and /LOGOUT are mutually exclusive.
|
| /[NO]FORCE_EXIT[=deltatime]
| Sets the default for forced image exits to be used on
| subsequent WATCH commands. /DISCONNECT, /FORCE_EXIT,
| and /LOGOUT are mutually exclusive.
CMD-28
Command Descriptions
SET WATCH_DEFAULT
/[NO]LOGOUT[=deltatime]
Sets the default for logouts, to be used if not
| specified on subsequent WATCH commands. /DISCONNECT,
| /FORCE_EXIT, and /LOGOUT are mutually exclusive.
/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-29
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-30
Command Descriptions
SHOW
_______________________________________________________
SHOW
Displays all or part of the current configuration.
_______________________________________________________
FORMAT
{ ACTION }
{ ALL }
{ BELL }
{ DAYS }
{ }
{ DEBUG }
{ DEFAULTS }
{ EVENT_LOG }
SHOW { }
{ EXCLUDE }
{ FILE }
{ GLOBALS }
{ }
{ INTERVAL }
{ MULTIWARN }
{ 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.
CMD-31
Command Descriptions
SHOW
_______________________________________________________
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
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-32
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-33
Command Descriptions
WATCH
_______________________________________________________
WATCH
Defines a watch rule.
_______________________________________________________
FORMAT
WATCH device-pat
_______________________________________________________
Command Qualifiers Defaults
/ACCPORNAM=port-pat /ACCPORNAM=*
/DELETE
/[NO]DISCONNECT[=deltatime]
| /[NO]FORCE_EXIT[=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.
CMD-34
Command Descriptions
WATCH
_______________________________________________________
QUALIFIERS
/ACCPORNAM=port-pat
Port name or pattern containing wildcards, identifying
the terminal port(s) (for terminal servers and other
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, /FORCE_EXIT, and /LOGOUT qualifiers
| are mutually exclusive.
|
| /[NO]FORCE_EXIT[=deltatime]
| Specifies that any user-mode image currently running
| at the terminal should be forced to exit, without
| actually logging the user off.
|
| The /DISCONNECT, /FORCE_EXIT, 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
CMD-35
Command Descriptions
WATCH
/DISCONNECT are omitted, the logout/disconnect default
| is taken from the current SET WATCH_DEFAULT setting.
|
| The /DISCONNECT, /FORCE_EXIT, 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:
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-36
Command Descriptions
WATCH
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). 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-37