Configuring the Restriction facility

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:


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



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.


GT.M ignores any BREAK command


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


mumps -direct terminates immediately with a RESTRICTEDOP error


terminates immediately with a RESTRICTEDOP error


any HALT produces a RESTRICTEDOP error


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.


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.


any OPEN of a PIPE device produces a RESTRICTEDOP error


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


any ZBREAK produces a RESTRICTEDOP error


GT.M returns an empty string for all references to $ZCMDLINE


any ZEDIT produces a RESTRICTEDOP error


any ZHALT produces a RESTRICTEDOP error


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.

ZSYSTEM and PIPE OPEN command restriction facility

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

The actual filter routine:

 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.

Audit Principal Device restriction facility

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:

  • 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).



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.


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.


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.


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.


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 to download sample listener programs. You can also download from

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.)