Post installation, a system administrator can optionally add a restrict.txt file in $gtm_dist to restrict the use of certain GT.M facilities to a group-name. The owner and group for $gtm_dist/restrict.txt can be different from those used to install GT.M. The file may contain zero or more of the following case-insensitive lines in any order:
APD_ENABLE:[comma-separated-list-of-options]:{path-to-sock-file|host:port}[:tls-id]
BREAK[:<group-name>]
HALT[:<group-name>]
ZBREAK[:<group-name>]
ZCMDLINE[:<group-name>]
ZEDIT[:<group-name>]
ZHALT[:<group-nam>]
ZSYSTEM[:<group-name>]
CENABLE[:<group-name>]
PIPE_OPEN[:<group-name>]
DIRECT_MODE[:<group-name>]
DSE[:<group-name>]
TRIGGER_MOD[:<group-name>]If the file $gtm_dist/restrict.txt does not exist, GT.M does not restrict any facilities.
Any non-empty lines that do not match the above format cause processes with read-only permission to behave as if they could not read the file, and GT.M enforces all restrictions.
Restrictions apply as follows:
|
GT.M facility |
Behavior |
|---|---|
|
APD_ENABLE |
GT.M supports the ability to log actions initiated from a principal device including MUMPS commands typed interactively, or piped in by a script or redirect, from the principal device ($PRINCIPAL) and / or any information entered in response to a READ from $PRINCIPAL. An action initiated from $PRINCIPAL executes as usual when Audit Principal Device is disabled, which it is by default. However, when Audit Principal Device is enabled, GT.M attempts to send the action out for logging before acting on it. Additionally, the $ZAUDIT Intrinsic Special Variable (ISV) provides a Boolean value that indicates whether Audit Principal Device is enabled. Please see the Audit Principal Device section below for details. |
|
BREAK |
GT.M ignores any BREAK command |
|
HALT |
any HALT produces a RESTRICTEDOP error |
|
ZBREAK |
any ZBREAK produces a RESTRICTEDOP error |
|
ZCMDLINE |
GT.M returns an empty string for all references to $ZCMDLINE |
|
ZEDIT |
any ZEDIT produces a RESTRICTEDOP error |
|
ZHALT |
any ZHALT produces a RESTRICTEDOP error |
|
ZSYSTEM |
any ZSYSTEM produces a RESTRICTEDOP error |
|
CENABLE |
the process acts like $gtm_nocenable is TRUE and ignores any CENABLE deviceparameter |
|
PIPE_OPEN |
any OPEN of a PIPE device produces a RESTRICTEDOP error |
|
DIRECT_MODE |
|
|
DSE |
terminates immediately with a RESTRICTEDOP error |
|
TRIGGER_MOD |
any $ZTRIGGER() or MUPIP TRIGGER that attempts a change or delete produces a RESTRICTEDOP error; in addition, while executing code within a trigger, ZBREAK results in a RESTRICTEDOP error, and both ZBREAK and ZSTEP actions are ignored |
If the file exists, a process:
that has write authorization to restrict.txt has no restrictions
that has no read access to restrict.txt is restricted from all facilities for which GT.M supports a restriction (currently the above list)
that has read-only access to restrict.txt is restricted from any listed facility unless it is a member of the group specified in the optional group-id following the facility name
Note that restricting $ZCMDLINE prevents things like: mumps -run %XCMD 'for read x xecute x' which can act as substitutes for Direct Mode.
In order to limit pathological looping from restricted HALT or ZHALT, if A GT.M process issues a second occurrence of the restricted command within half a second, the process terminates after sending a fatal error to both the principal device and the syslog, and also producing a GTM_FATAL* context file, but no core file. With these restrictions in place, a process should terminate with, for example: ZGOTO 0. Note that, with or without a restriction, executing these commands as part triggered logic on a replicating instance may cause the Update Server to terminate and thereby stop replication.
The GT.M restriction mechanism recognizes the following lines:
ZSYSTEM_FILTER[:M labelref]
PIPE_FILTER[:M labelref]
The labelref must include a routine name. If a process is restricted by a ZSYSTEM or PIPE_OPEN line in the restrictions file that restriction takes precedence over the corresponding filter restriction. Otherwise when a process is subject to these restrictions, GT.M inserts an invocation of the labelref prior to the restricted command, passing a string containing the argument to the ZSYSTEM command or the command deviceparameter of the PIPE OPEN. The path to the filter routine must be included in $zroutines. FIS recommends that the filter routine is placed in a location with restricted access such as $gtm_dist. If the filter invocation return is -1,GT.M produces a RESTRICTEDOP error, otherwise it executes the command using the returned string via output parameters as a, possibly identical, replacement for the original string. Since GT.M uses the call-ins mechanism to execute the filters, a filter invocation inside a TP transaction in call-ins produces a CITPNESTED error. Note that because ZSYSTEM and OPEN are not Isolated actions FIS recommends against their use within a TP transaction. Filters will also increment the nested level of call-ins. A recursive filter invocation produces a NOFILTERNEST error. GT.M reports all filter errors to the operator log accompanied by a COMMFILTERERR.
An example restrict file for this:
cat $gtm_dist/restrict.txt ZSYSTEM_FILTER:^filterzsy PIPE_FILTER:^filterzsy
The actual filter routine:
filterzsy(inarg,outarg); if ""=inarg set outarg="-1;must provide a command" quit for i=1:1 set arg=$piece(inarg,";",i) quit:""=arg do quit:$data(outarg) . for quit:$zchar(9,32)'[$extract(arg) set arg=$extract(arg,2,9999) . set cmd=$piece(arg," ") . for restrict="sudo","cd" if cmd=restrict set outarg="-1;command "_restrict_" not permitted" quit . quit:$data(outarg) . if "echo"=cmd set $piece(arg," ")="echo #",$piece(inarg,";",i)=arg ;example of modification set:'$data(outarg) outarg=inarg quit +outarg
Filter execution starts with $STACK=1 ($ZLEVEL=2).
Following are the GT.M commands, Intrinsic Special Variables, and functions whose behavior changes in the context of a filter invocation.
ZGOTO 0 (zero) returns to the processing of the restricted command as does ZGOTO 1 (one) with no entryref, while ZGOTO 1:entryref replaces the originally invoked filter and continues filter execution.
$ZTRAP/$ETRAP NEW'd at level 1.
$ZLEVEL initializes to one (1) in GTM$CI, and increments for every new stack level.
$STACK initializes to zero (0) in GTM$CI frame, and increments for every new stack level.
$ESTACK NEW'd at level one (1) in GTM$CI frame.
$ECODE/$STACK() initialized to the empty string at level one (1) in GTM$CI frame.
After the filter completes, GT.M restores the above to their values at the invocation of the filter.
The "APD_ENABLE" entry in a restrictions definition file turns on APD and enables the logging of all code entered from Direct Mode and optionally any input entered on the principal device ($PRINCIPAL). To enable APD, add a line with the following format to the restriction file:
APD_ENABLE:[comma-separated-list-of-options]:{path-to-sock-file|host:port}[:tls-id]The optional "comma-separated-list-of-options" can consist of zero or more of these options:
TLS - Enables TLS connectivity between GT.M and the logger; this option requires the host information (e.g. IP/port or hostname/port)
RD - Enables logging of all responses READ from $PRINCIPAL in addition to that entered at the Direct Mode prompt. This option is more comprehensive and captures input that might be XECUTEd, but depending on your application architecture may significantly increase the amount of logged information.
The "path-to-sock-file" is the absolute path of the UNIX domain socket file for connecting to the logger.
The "host" is the hostname or numeric IPv4/IPv6 address of the logger; numeric IP addresses must be enclosed in square brackets (i.e. '[' and ']').
The "port" is the port number the logger listens on.
The optional "tls-id" is the label of the section within the GT.M configuration file that contains TLS options and/or certificates for GT.M to use; APD ignores any "tls-id" if the "TLS" option is not specified.
If parsing the "APD_ENABLE" line in restriction file or initializing logger information fails, GT.M enforces all restrictions (default restriction file behavior).
Examples:
APD_ENABLE::/path/to/sock/file/audit.sock
Adding this line to the restriction file enables APD. GT.M connects with the logger via UNIX domain socket using the domain socket file "/path/to/sock/file/audit.sock" and sends all Direct Mode activity from $PRINCIPAL to logger.
APD_ENABLE:RD:[123.456.789.100]:12345
Adding this line to the restriction file enables APD. GT.M connects with the logger (listening on port 12345 at the IPv4 address 1enable23.456.789.100) via TCP socket and sends all Direct Mode and READ activities from $PRINCIPAL to logger.
APD_ENABLE::loggerhost:56789
Adding this line to the restriction file enables APD. GT.M connects with the logger (listening on port 56789 at the hostname "loggerhost") using a TCP socket and sends all Direct Mode activities from $PRINCIPAL to logger.
APD_ENABLE:TLS,RD:[1234:5678:910a:bcde::f:]:12345:clicert
Adding this line to the restriction file enables APD. GT.M connects with the logger (listening on port 12345 at the IPv6 address 1234:5678:910a:bcde::f:) via TLS socket. GT.M configures its TLS options for APD based on the contents within the section of the configuration file labeled "clicert". GT.M sends all Direct Mode and READ activities from $PRINCIPAL to logger.
The "logger" is a separate server-like program responsible for receiving the to-be-logged information from GT.M and logging it. This separate program must be introduced by the user, either running in foreground or background, in order for logging to actually work. GT.M distributions include basic example logger programs.
The six fields in the message, separated by semicolons (';'), contain information on the to-be-logged activity. Each to-be-logged message sent to the logger from GT.M has the following format:
dist=<path>; src={0|1|2}; uid=<uid>; euid=<euid>; pid=<pid>; command=<text>The "dist" field, shows the path to location of the sender/user's $gtm_dist (GT.M executables).
The "src" field shows zero (0) for input from unknown source, one (1) for Direct Mode input, or two (2) for READ input from $PRINCIPAL.
The next three fields ("uid", "euid", and "pid") show (respectively) decimal representations of the user ID, effective user ID, and process ID of the process that sent the message.
The "command" field is the input provided on the GT.M side.
Examples:
dist=/path/to/gtm_dist; src=1; uid=112233445; euid=112233445; pid=987654; command=write "Hello world",! dist=/usr/library/V123/dbg; src=2; uid=998877665; euid=998877665; pid=123456; command=set a=789
Click on 
to download sample listener programs. You can also download dm_audit_listener.zip from http://tinco.pair.com/bhaskar/gtm/doc/books/ao/UNIX_manual/downloadables/dm_audit_listener.zip.
