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>]
CENABLE[:<group-name>]
DIRECT_MODE[:<group-name>]
DSE[:<group-name>]
HALT[:<group-name>]
LIBRARY:[<group-name>]
LOGDENIALS:[<group-name>]
PIPE_OPEN[:<group-name>]
TRIGGER_MOD[:<group-name>
ZBREAK[:<group-name>]
ZCMDLINE[:<group-name>]
ZEDIT[:<group-name>]
ZHALT[:<group-nam>]
ZSYSTEM[:<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

CENABLE

the process acts like $gtm_nocenable is TRUE and ignores any CENABLE deviceparameter

DIRECT_MODE

mumps -direct terminates immediately with a RESTRICTEDOP error

DSE

terminates immediately with a RESTRICTEDOP error

HALT

any HALT produces a RESTRICTEDOP error

LIBRARY

any attempt to load an external library produces a RESTRICTEDOP error

Library restrictions apply to third party libraries loaded by GT.M directly and those loaded at the behest of GT.M applications. This restriction allows administrators to control which libraries GT.M is able to load at run-time. To allow library loading, place symbolic links to the desired libraries in $gtm_dist/plugin.

LOGDENIALS

restrict logging when GT.M denies access to a process to the named groups

GT.M supports logging a number of errors related to permissions and access using the syslog() facility. The GT.M restriction LOGDENIALS provides a facility for disabling this loggging on a Unix group basis. If this mechanism is not used the logging takes place for all GT.M processes. If the restriction is used logging takes place for specified groups only.

PIPE_OPEN

any OPEN of a PIPE device produces 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

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

If the file exists, a process:

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]

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>

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 Download dm_audit_listener.zip 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.

There are three different sample logger programs that can be used for logging. The difference amongst the three is the socket connection type used to communicate with GT.M. The dm_audit_unix_listener.c, dm_audit_tcp_listener.c, and dm_audit_tls_listener.c use the UNIX domain, TCP, and TLS socket type respectively to communicate with GT.M. Choose the logger program to use based on desired connection type.

Compiling Logger Program:

  • The UNIX domain logger (dm_audit_unix_listener.c) can be compiled with:

    gcc dm_audit_unix_listener.c -o dm_audit_unix
  • The TCP logger (dm_audit_tcp_listener.c) can be compiled with:

    gcc dm_audit_tcp_listener.c -o dm_audit_tcp
  • To compile the TLS logger (dm_audit_tls_listener.c), you'll need to link the ssl (-lssl) and crypto (-lcrypto) libraries when compiling. Assuming you have OpenSSL development packege installed, the TLS logger can be compiled with:

    gcc dm_audit_tls_listener.c -o dm_audit_tls -lssl -lcrypto

    If you do not have the OpenSSL development package installed, then you will have to install it first.

Running Logger Program:

  • The UNIX domain logger can be ran with:

    ./dm_audit_unix <logfile> <sockfile>
    • The "logfile" field is file path of output audit log.

    • The "sockfile" field is file path of unix domain socket file.

  • The TCP logger can be ran with:

    ./dm_audit_tcp <logfile> <portno>
    • The "logfile" field is file path of output audit log.

    • The "portno" field is port number to listen on.

  • The TLS logger can be ran with:

    ./dm_audit_tls <logfile> <portno> <certfile> <privkeyfile> <passphrase> [-clicert] [-cafile <CAfilepath>] [-capath <CApath>]
    • The "logfile" field is file path of output audit log.

    • The "portno" field is port number to listen on.

    • The "certfile" field is file path of TLS/SSL certificate to use.

    • The "privkeyfile" field is file path of private key to use.

    • The "passphrase" field is password or passphrase for certificate/key.

    • The "clicert" option (optional), if present, then logger requests for client certificate when performing the TLS handshake with GT.M.

    • The "CAfilepath" field (optional) is path to file of CA certificates in PEM format (specifies the locations for SSL context, at which CA certificates for verification purposes are located.)

    • The "CApath" field (optional) is path to directory containing CA certificates in PEM format (specifies the locations for SSL context, at which CA certificates for verification purposes are located.)

loading table of contents...