VMSSPI for VSI OpenVMS User Guide

The SYSTEM module is activated at regular time intervals (usually, every minute) and reports on the items summarised in the following list:

The function of the PERFORMANCE module is to monitor resource usage and system/process performance. More specifically, the module reports on the following parameters:

The AUDIT_SERVER process records security-relevant activity as it occurs on the system, that is, any activity related to user access to the system or a protected object within the system, including the following:

The AUDIT_SERVER usually writes security event messages to the following locations:

The VMSSPI SECURITY module allows you to monitor security events in a continuous but simplified manner. System managers can quickly detect suspicious security events, which they can then examine further using the ANALYZE/AUDIT utility.

The operator terminal and the security audit log file are the primary destinations for security event messages. An additional feature of the security auditing facility is a listener mailbox, which you can create to receive a binary copy of all security-auditing messages.

The SECURITY module does the following:

The messages written to the listener mailbox are the ones that result from entering the SET AUDIT/ALARM and/or SET AUDIT/AUDIT commands. VSI recommends that certain security events be enabled for auditing, for example:

$ SET AUDIT/AUDIT/ENABLE=(ACL, - 
            AUTHORIZATION, - 
            BREAKIN:(ALL), - 
            LOGFAILURE:(ALL), - 
            FILE_ACCESS:FAILURE:(READ,WRITE,EXECUTE,DELETE,CONTROL), - 
            LOGIN:(DIALUP)) 

Use the SHOW AUDIT command to check the security events that are enabled for monitoring on your system.

In order to install and use VMSSPI on VSI OpenVMS Alpha, IA64, and x86-64, the following software products and versions are required:

In addition to these requirements, installing VSI VMSSPI for VSI OpenVMS on an ODS-5 formatted file system is recommended.

The kit is provided as an OpenVMS PCSI kit that can be installed by a suitably privileged user using the following command:

$ PRODUCT INSTALL VMSSPI 

The installation will then proceed as follows. Note that output may differ slightly from that shown depending on platform, product version, and various other factors.

Performing product kit validation of signed kits ...

The following product has been selected:
    VSI AXPVMS VMSSPI V9.0-22               Layered Product

Do you want to continue? [YES]

Configuration phase starting ...

You will be asked to choose options, if any, for each selected product and for any products that may be installed to satisfy software dependency requirements.

Configuring VSI AXPVMS VMSSPI V9.0-22: VSI OpenVMS SPI for VSI OpenVMS

    © VMS Software Inc., 2023. All rights reserved.

    VMS Software Inc.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
    VSI AXPVMS VMSSPI V9.0-22               DISK$FUNYET_SYS:[VMS$COMMON.]

Portion done: 0%...10%...20%...30%...50%...60%...80%...90%...100%

The following product has been installed:
    VSI AXPVMS VMSSPI V9.0-22               Layered Product

VSI AXPVMS VMSSPI V9.0-22: VSI OpenVMS SPI for VSI OpenVMS

    Post-installation tasks are required.

    To start VMSSPI at system boot time, add the following lines to
    SYS$MANAGER:SYSTARTUP_VMS.COM:

        $ file := SYS$STARTUP:VMSSPI$STARTUP.COM
        $ if f$search("''file'") .nes. "" then @'file'

    To shutdown VMSSPI at system shutdown, add the following lines
    to SYS$MANAGER:SYSHUTDWN.COM:

        $ file := SYS$STARTUP:VMSSPI$SHUTDOWN.COM
        $ if f$search("''file'") .nes. "" then @'file'

The logical name VMSSPI$DATA is used by VMSSPI to specify the location of the configuration and messages files. For OpenVMS clusters with multiple system disks, place the configuration file in a directory that all cluster members can access.

Follow these steps to create define the VMSSPI$DATA logical name for this scenario:

VMSSPI usually runs on every member in an OpenVMS cluster. Only one of the instances performs clusterwide monitoring, which includes clusterwide processes, clusterwide mounted disks and shadow sets, and anything related to queues. The cluster member where the VMSSPI performs this clusterwide monitoring can be any node in the cluster, and is determined by VMSSPI process in the cluster that exclusively holds the VMSSPI$CLUSTER_LOCK lock.

In some situations, you might not want to perform clusterwide monitoring on one particular cluster member, which is the case with the quorum system of a multisite disaster-tolerant cluster. This quorum system usually does not mount any cross-data centre shadow sets and does not have access to the queue file. In a situation like this, disable the clusterwide monitoring on this node by entering the following command prior to starting VMSSPI:

$ DEFINE/SYSTEM VMSSPI$NO_CLUSTER_CHECKS TRUE 

$ DEFINE/SYSTEM VMSSPI$IGNORE PROC_NAME_1,PROC_NAME_2 

This facility is intended to provide a mechanism for administrators to temporarily disable monitoring of one or more processes while non-scheduled maintenance operations are performed.

It must be emphasised that this facility applies only to processes explicitly configured for monitoring in the configuration file and not to all processes that might be running on the system.

It should be noted that while monitoring is disabled for processes in this way, VMSSPI will write log entries for the processes in question stating that monitoring is currently disabled. Such log entries will be written for each monitoring cycle until VMSSPI$IGNORE is de-assigned or the process name in question has been removed from the list of process names to be ignored.

This logical name can be used to define a default value for the re-raise interval associated with certain specific alerts. For these alerts, if a re-raise interval is defined and a fault condition persists for longer than is time, the alert will be re-raised, and this behaviour will continue until such time as the fault is corrected. The value specified for VMSSPI$RERAISE_INTERVAL must be an integer value between 0 and 360, where the value represents the number of minutes that a relevant fault condition can remain un-cleared before VMSSPI will re-raise the alert. A value of 0 means that alerts will not be re-raised (unless a specific re-raise interval is otherwise specified in the VMSSPI configuration file for the entity being monitored), and if the specified value is less than or equal to the VMSSPI scan interval, the value will be adjusted to be twice the VMSSPI scan interval (as logically it makes no sense for the re-raise interval to be less than the VMSSPI scan frequency). The VMSSPI$RERAISE_INTERVAL logical name should be defined at SYSTEM level.

The specific alerts that can currently be re-raised in this manner are:

Note that it is possible to override the default re-raise interval defined using this logical name or to specify a specific interval using the /RERAISE qualifier with the PROCESS, JOB, and BATCHQUEUE commands. The integer value specified with this qualifier is the number of minutes for the interval and the supplied value must conform to the same rules as those described above for the VMSSPI$RERAISE_INTERVAL logical name.

The logical name TCPIP$SMTP_FROM (as used by VSI TCP/IP Services) can be used to specify an outbound alias that is applied to email messages sent by the VMSSPI SMTP client (all email messages sent be VMSSPI will appear to originate from this address). This facility can be useful in situations where there are constraints imposed by email gateways around where emails can originate and/or from whom. Be aware that this logical name may also be defined for other purposes and care should be taken to ensure that any system-level definition for VMSSPI does not conflict with an existing definition that is relied upon by users or other applications running on the system.

You can easily generate an initial version of the VMSSPI configuration file by running the utility VMSSPI$ROOT:[BIN]VMSSPI$CONFIGURE_SYSTEM.EXE. When you run this utility, a configuration file is generated based on the currently present processes, mounted disks and shadow sets, batch and print queues, and batch jobs.

The generated configuration file allows out-of-the-box monitoring of the OpenVMS environment. To obtain optimal results, however, the system manager will generally need to edit this file.

It is also possible to define a foreign command for VMSSPI$CONFIGURE_SYSTEM.EXE and to run this command with various qualifiers as described below to generate configuration details for specific sub-systems and to write these configuration details to specified files that can then be used to update VMSSPI$DATA:VMSSPI$CONFIGURATION.DAT as necessary with new or changed information. For example, the following commands define a foreign command for VMSSPI$CONFIGURE_SYSTEM.EXE and generate configuration data for shadow sets only, with the resultant output being written to the file SHADOW.DAT:

$ VMSSPICFG :== $VMSSPI$ROOT:[BIN]VMSSPI$CONFIGURE_SYSTEM.EXE 
$ VMSSPICFG/SHADOW_SETS/OUTPUT=SHADOW.DAT 

Using your preferred editor, the contents of SHADOW.DAT can then be used as required to update information in VMSSPI$DATA:VMSSPI$CONFIGURATION.DAT.

Permitted qualifiers are summarised in the following table. Note that the /BATCH_QUEUES and /BATCH_JOBS qualifiers must be specified in full (they cannot be abbreviated).

If changes are made to the VMSSPI$CONFIGURATION.DAT file, the VMSSPI SYSTEM module automatically registers these changes. New items that are added to this file are monitored, and removed items are no longer monitored. However, any such changes will not take effect until the next ALWAYS/NEVER window (midnight by default). To force modifications to the configuration file to take effect immediately, it is necessary to restart VMSSPI.

The PERFORMANCE and SECURITY modules must be restarted for the configuration file changes to take effect.

In the configuration file, you need to add entries for the following:

These configuration file entries are explained in the following sections.

CLUSTERNAME clustername 

INTERVAL value 

PERIOD name_of_period –
    /MONDAY=(BEGIN=hour,END=hour) -
    /TUESDAY=(BEGIN=hour,END=hour) -
    /WEDNESDAY=(BEGIN=hour,END=hour) -
    /THURSDAY=(BEGIN=hour,END=hour) -
    /FRIDAY=(BEGIN=hour,END=hour) -
    /SATURDAY=(BEGIN=hour,END=hour) -
    /SUNDAY=(BEGIN=hour,END=hour) -
    /WORKDAY=(BEGIN=hour,END=hour) -
    /EVERYDAY=(BEGIN=hour,END=hour) -
    /WEEKEND=(BEGIN=hour,END=hour)

PERIOD workhours -
    /WORKDAY=(BEGIN=08:30,END=12:00) -
    /WORKDAY=(BEGIN=13:00,END=17:15) -
    /SATURDAY=(BEGIN=09:00,END=12:30)

PROCESS "process_name" –
[/UIC="uic"] -
[/PERIOD=period] - 
[/OCCURRENCES=n] - 
[/CLUSTER_WIDE] - 
[/NODES=(...)] –
[/ACTION=”action”] -
[/RERAISE=n]

PROCESS ERRFMT /UIC="[1,6]" /PERIOD=ALWAYS 
PROCESS ORA* /UIC=ORACLE8 /OCCURRENCES=10 
PROCESS QUEUE_MANAGER /UIC=SYSTEM /CLUSTER_WIDE

DISK disk_name [/PERIOD=period] - 
[/CRITICAL=threshold] - 
[/MAJOR=threshold] - 
[/MINOR=threshold] - 
[/WARNING=threshold] - 
[/DIO] - 
[/QUEUE_LENGTH] - 
[/HOTFILES] - 
[/NODES=(...)] 

PARAMETER HOTFILE_INTERVAL/VALUE="00:05:00" 

PARAMETER HOTFILE_TOPDIO/VALUE=5 

BATCHQUEUE queue-name - 
[/STARTED_PERIOD=period] - 
[/STOPPED_PERIOD=period] - 
[/[NO]PENDING_THRESHOLD=...] - 
[/[NO]RETAINED_THRESHOLD=...] - 
[/NODES=(node...)] – 
[/ACTION=”action”] - 
[/RERAISE=n] 

BATCHQUEUE SYS$BATCH 

PRINTQUEUE queue-name [/PERIOD=time_period] - 
[/[NO]PENDING_THRESHOLD=...] - 
[/[NO]RETAINED_THRESHOLD=...] - 
[/NODES=(node...)]

PRINTQUEUE SYS$LTA* /PERIOD=WORKHOURS 

JOB job-name [/USERNAME=username] - 
[/QUEUE=queuename] - 
[/PERIOD=time_period] - 
[/NODES=(...)] - 
[/RERAISE]

JOB DAILY_CLEANUP /USERNAME=SYSTEM /QUEUE=SYS$BATCH 

SHADOWSET shadow-name /MEMBERS=(member1,[member2],[member3]) - 
[/PERIOD=period] - 
[/NODES=(...)] 

SHADOWSET DSA1 /MEMBERS=($1$DGA1000,$1$DGA2000) 

INCLUDE=rules-file-name 

INCLUDE=SYS$MANAGER:DISK$CONFIGURATION.DAT 

INTRUDERS 

INTRUDERS/INCLUDE=SUSPECTS/THRESHOLD=n 

INTRUDERS/INCLUDE=SUSPECTS/THRESHOLD=3 

LAN device-name/NODE=node-name 

LAN EWAO: /NODE=SWELL 

!DISABLE AUDIT 
!DISABLE BREAKIN 
!DISABLE INSTALL 
!DISABLE LOGFAIR 
!DISABLE LOGIN 
!DISABLE MOUNT 
!DISABLE NETPROXY 
!DISABLE SYSUAF 
!DISABLE RIGHTSDB 
!DISABLE SYSTIME 
!DISABLE SYSGEN 
!DISABLE OBJ_CREATE 
!DISABLE OBJ_DELETE 
!DISABLE OBJ_ACCESS 
!DISABLE CONNECTION 
!DISABLE NCP 
!DISABLE PROCESS 

In order to use the DataDog interface module it is first necessary to create an API key that can be used by the interface module to communicate with the DataDog service. API keys can be created within the DataDog web UI by navigating to “Organization settings”, then clicking the “API keys link”. Once you have the API key (a 32-character hexadecimal string), the module can be configured in MESSAGES.TXT as follows, where <api-key> should be replaced with the newly created key.

use interface module "vmsspi$root:[lib]vmsspi$datadog_shr.exe"
"https://api.datadoghq.com/api/v1/events?api_key=<api-key>";

Alternatively, the endpoint URI may be specified using the logical name VMSSPI$DATADOG_URI. If the endpoint is specified in MESSAGES.TXT as "" (an empty string) the module will attempt to determine the endpoint using the logical name VMSSPI$DATADOG_URI. If this logical name is not defined and the endpoint in MESSAGES.TXT is empty then VMSSPI will fail to start.

The logical name VMSSPI$DATADOG_DEBUG can be defined (to any value) to enable additional operational logging by the DataDog interface module. Note that this additional logging is verbose and includes detailed information of all interactions with DataDog. It is therefore recommended that this logical name should only be defined for debugging purposes and should not be routinely defined.

The Dynatrace interface module uses the Dynatrace v2 API to send alerts and optionally for log ingestion. In order to use the interface it is necessary to first create a Dynatrace API v2 access token with scopes "ingest events", "ingest logs", and "ingest metrics". This is done via the "Access tokens" link under "Manage" on the Dynatrace UI main menu. Strictly speaking, only "ingest events" is mandatory, with "ingest logs" required only if event details are to be published to the Dynatrace log facility in addition to raising an alert, and the "ingest metrics" scope may be required by future VMSSPI versions?.

Once the access token has been created, it is a simple matter of specifying the following details in MESSAGES.TXT, where <access-token> is the access token created as described above, and <instance> is the name of the Dynatrace service host. Note that <access-token> is some 90+ characters in length, and to improve readability it is typically desirable to split the use statement across multiple lines as shown.

use interface module "vmsspi$root:[lib]vmsspi$dynatrace_shr.exe"
"https://<instance>.live.dynatrace.com/api/v2/events/ingest
<access-token>";

If log ingestion is to be performed then the log ingestion endpoint should be added to the “use” command string command as shown below:

use interface module "vmsspi$root:[lib]vmsspi$dynatrace_shr.exe"
"https://<instance>.live.dynatrace.com/api/v2/events/ingest
<access-token>
https://<instance>.live.dynatrace.com/api/v2/logs/ingest";

The logical name VMSSPI$DYNATRACE_DEBUG can be defined (to any value) to enable additional operational logging by the Dynatrace interface module, and the logical name VMSSPI$HTTP_PROXY can be used to specify an HTTP proxy if the OpenVMS system running VMSSPI does not have direct access to the Dynatrace service endpoint(s). These logical names may be defined at the system or the process level; however it is generally recommended to define them at the system level in the file SYS$MANAGER:VMSSPI$LOGICALS.COM to ensure that they are visible to all VMSSPI processes.

It should be noted that the additional logging performed by the module when the logical name VMSSPI$DYNATRACE_DEBUG is defined is verbose and includes detailed information of all interactions with the Dynatrace service. It is therefore recommended that this logical name should only be defined for debugging purposes and should not be routinely defined.

The file module simply logs alert details to the output file for the VMSSPI process in question, as specified in SYS$STARTUP:VMSSPI$STARTUP.COM (for details, see Section 8). From a configuration perspective, the file module takes no parameters and is enabled in MESSAGES.TXT as follows:

use interface module "vmsspi$root:[lib]vmsspi$file_shr.exe" ""; 

The MQTT alerting module (VMSSPI$MQTT_SHR.EXE) can be used to publish alerts to an MQTT-compliant message broker, whereupon alert messages can be consumed by subscribing applications and actioned as necessary. The simplest way to configure this module in MESSAGES.TXT is to specify a "use" command as follows, where <hostname> and <port> are the host name (or TCP/IP address) of the server on which the broker is running and the port number on which the broker is listening, respectively. Note that it is possible to specify additional details in the URI connect string, including username and password details, if credentials are required in order to connect to the broker.

use interface module "vmsspi$root:[lib]vmsspi$mqtt_shr.exe"
"tcp://<hostname>:<port>";

If the address of the broker is specified in MESSAGES.TXT as "" (an empty string) the module will attempt to determine the address using the logical name VMSSPI$MQTT_URI. If this logical name is not defined and the broker address in MESSAGES.TXT is empty then VMSSPI will fail to start.

Specifying the connect string (URI) as described above is all that is required in order to start using the MQTT module; however, there are a number of optional configuration parameters for the MQTT module that can be specified using the logical names described below. These logical names may be defined at the system or process level; however it is generally recommended to define them at the system level in the file SYS$MANAGER:VMSSPI$LOGICALS.COM to ensure that they are visible to all VMSSPI processes.

Topics created by the MQTT module when publishing alerts are used the following form, where <org-id> the organization code as specified in MESSAGES.TXT, <node-name> is the OpenVMS node name of the server on which VMSSPI is running, and <severity> is the severity level of the alert (critical, minor, major, normal, unknown, warning, or none).

vmsspi/<org-id>/<node-name>/<severity> 

As noted above, an alternative topic prefix (other than “vmsspi”) may be defined using the logical name VMSSPI$MQTT_TOPIC_PREFIX.

Using this scheme for topic creation it is readily possible for consumers to consume exactly the messages that they are interested in. For example, a particular consumer may only be interested in critical alerts raised by a particular node.

As its name suggests, the null alerting module (VMSSPI$NULL_SHR.EXE) does nothing, and is generally used in situations where it is only necessary to receive alert notifications via email. This is also the default module configured in VMSSPI$DATA:MESSAGES.TXT when VMSSPI is first installed.

From a configuration perspective, the null module takes no parameters, and is enabled as follows in MESSAGES.TXT:

use interface module "vmsspi$root:[lib]vmsspi$null_shr.exe" ""; 

From the VMSSPI perspective, configuring the PagerDuty interface is straightforward; however before this can be done it is first necessary to define a new service in PagerDuty, to add an integration to this service, and to create an API access key that can be used by VMSSPI to publish alerts to the newly defined service. Other configuration work will typically also be required to define how PagerDuty should handle the various alerts that it can receive from VMSSPI. A detailed description of this configuration work is beyond the scope of this document, and the reader should refer to the online PagerDuty documentation for more detailed information; however with regard to the requirements of the VMSSPI interface module, the following points should be noted:

Once PagerDuty has been configured as described and you have the integration and API access keys, the VMSSPI PagerDuty module (VMSSPI$PAGERDUTY_SHR.EXE) can be configured as follows, where https://events.pagerduty.com/v2/enqueue is the endpoint for the PagerDuty v2 API, <integration-key> and <access-key> should be replaced with the integration key and access key values, respectively. Note that access and integration keys are many characters in length, and to improve readability it is typically desirable to split the use statement across multiple lines as shown.

use interface module "vmsspi$root:[lib]vmsspi$pagerduty_shr.exe"
"https://events.pagerduty.com/v2/enqueue
<access-key>
<integration-key>";

The logical name VMSSPI$PAGERDUTY_DEBUG can be defined (to any value) to enable additional operational logging by the PagerDuty module, and the logical name VMSSPI$HTTP_PROXY can be used to specify an HTTP proxy if the OpenVMS system running VMSSPI does not have direct access to the PagerDuty service. These logical names may be defined at the system or the process level; however it is generally recommended to define them at the system level in the file SYS$MANAGER:VMSSPI$LOGICALS.COM to ensure that they are visible to all VMSSPI processes.

It should be noted that the additional operational logging performed by the module when the logical name VMSSPI$PAGERDUTY_DEBUG is defined is verbose and includes detailed information of all interactions with the PagerDuty service. It is therefore recommended that this logical name should only be defined for debugging purposes and should not be routinely defined.

The Slack interface module uses the Slack Incoming Webhook mechanism to publish messages directly into a nominated Slack channel. In order to use this facility, your Slack administrator will need to define a Slack application (if you do not already have a suitable one), ensure that web hooks are enable, and create a web hook that can then be used by the VMSSPI Slack interface. A detailed description of this process can be found at https://api.slack.com/messaging/webhooks. Once you have the web hook URI, the VMSSPI Slack module can be configured as shown below, using your web hook URI in place of the dummy value shown.

use interface module "vmsspi$root:[lib]vmsspi$slack_shr.exe"
"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX";

If the web hook URI is "" (an empty string) the module will attempt to determine the web hook URI details using the logical name VMSSPI$SLACK_URI. If this logical name is not defined and the web hook address in messages.txt is empty then VMSSPI will fail to start. Additionally, the logical name VMSSPI$SLACK_DEBUG can be defined (to any value) to enable additional operational logging by the interface module, and the logical name VMSSPI$HTTP_PROXY can be used to specify an HTTP proxy if the OpenVMS system running VMSSPI does not have direct access to the web hook address. These logical names may be defined at the system or the process level; however it is generally recommended to define them at the system level in the file SYS$MANAGER:VMSSPI$LOGICALS.COM to ensure that they are visible to all VMSSPI processes.

Note that your Slack environment may impose various rate limits that could impact the reliable receipt of all alerts (keep in mind that Slack is primarily a communication tool for humans). For this reason, it is recommended that the Slack interface only be used for testing purposes or for situations where there are likely to be few alerts and alerts are generally not of a critical nature. Future versions of VMSSPI may look to use more advanced integration features provided by Slack that do not have such limitations.

The VMSSPI Splunk interface module (VMSSPI$SPLUNK_SHR.EXE) uses the Splunk HEC (HTTP Event Collector) interface to send alerts into Splunk via HTTPS. Assuming that HEC is enabled within your Splunk environment, in order to use the interface it is first necessary to create a HEC token via the Splunk UI. Details for creating and managing HEC tokens can be found at the following URL. It should also be noted that HEC can only be used with the Splunk Cloud Platform and with Splunk Enterprise, as described in this link.

https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector

Once HEC has been enabled within Splunk environment and you have a HEC token, it is simply a matter of specifying the following details in MESSAGES.TXT, where <instance> is the name of the Splunk service host (assuming a Splunk cloud deployment) and <hec-token> is your Splunk HEC token. Note that for Splunk Enterprise deployments, the endpoint specification may be somewhat different.

use interface module "vmsspi$root:[lib]vmsspi$splunk_shr.exe"
"https://<instance>.splunkcloud.com:8088/services/collector/event <hec-token>";

The logical name VMSSPI$SPLUNK_DEBUG can be defined (to any value) to enable additional operational logging by the Splunk module, and the logical name VMSSPI$HTTP_PROXY can be used to specify an HTTP proxy if the OpenVMS system running VMSSPI does not have direct access to the Splunk HEC service endpoint. These logical names may be defined at the system or the process level; however it is generally recommended to define them at the system level in the file SYS$MANAGER:VMSSPI$LOGICALS.COM to ensure that they are visible to all VMSSPI processes.

It should be noted that the additional operational logging performed by the module when the logical name VMSSPI$SPLUNK_DEBUG is defined is verbose and includes detailed information of all interactions with the Splunk HEC service. It is therefore recommended that this logical name should only be defined for debugging purposes and should not be routinely defined.

The VMSSPI$SYSLOG_SHR.EXE module can be used by VMSSPI to send alerts to a central Linux syslog daemon, whereupon the data can be processed as required by tools and services that cannot be used directly within the VSI OpenVMS environment. From the VMSSPI perspective, configuration of the VMSSPI$SYSLOG_SHR.EXE module is straightforward, involving the specification of the following use statement in VMSSPI$DATA:MESSAGES.TXT, where <hostname> and <port> are the host name (or TCP/IP address) of the target Linux system and the port number used by the syslog daemon on that system, respectively. The last two parameters (<sd-id> and <facility>) are optional, but it should be noted that it is not possible to specify a <facility> without also specifying a <sd-id> value. It should be noted that messages will be sent to the central syslog daemon using UDP (not TCP), and the syslog daemon should be configured accordingly.

use interface module "vmsspi$root:[lib]vmsspi$syslog_shr.exe" "<hostname> <port> <sd-id> <facility>"; 

The <sd-id> value specifies a structured data element ID for an RFC 5424 message header. The ID (a name plus possibly @digits) is case-sensitive and uniquely identifies the type and purpose of the element. If no value is specified, VMSSPI will use the default, which is vmsspi@32473; however it is important to note that the value 32473 has been reserved by IANA (the Internet Assigned Numbers Authority) to be used as an example number in documentation, and it is therefore suggested to use another value that is unique within your syslog environment.

The <facility> value can be used to specify how the message is logged by syslog, and is prepended to the message severity to effectively define the priority to be associated with the message. By default VMSSPI uses a value of "user" for the facility, and severity may be "crit", "err", "alert", "info", or "warning", derived from the VMSSPI message severity level.

For more information regarding the specification and function of the <sd-id> and <facility> parameters, see https://www.rfc-editor.org/rfc/rfc5424.

In addition to the actual message text, VMSSPI will also include in the data sent to syslog the RFC 5424 structured data element parameters (name-value pairs) listed in the table below. These parameter names and their values can then be used by tools consuming syslog data (or by syslog itself) for indexing purposes, allowing data to be readily searched or filtered as required.

Note that the VMSSPI$SYSLOG_SHR.EXE module transmits messages to the central Linux-based syslog facility using an OpenVMS implementation of the syslog logger utility, which resides in the directory VMSSPI$ROOT:[BIN]. This is a faithful port of the Linux version, not restricted to being used within the context of VMSSPI. For example, it may be used to transmit to the remote syslog daemon other data such as Apache web server log files. For such operations, a foreign command may be defined as follows to run the logger:

$ logger :== $vmsspi$root:[bin]logger.exe 

Defining the logical name VMSSPI$SYSLOG_DEBUG (to any value) will cause the VMSSPI syslog module to log additional operational details, including details of all logger commands. This logical name can be defined at the process or system level; however it is generally most appropriate to define it in the file SYS$MANAGER:VMSSPI$LOGICALS.COM as a system logical name to ensure that it will be visible to all VMSSPI processes. In general, this logical name should only be defined to help debug problems associated with the syslog interface. Having it always defined may result in large and "noisy" VMSSPI log files, depending upon the number of alerts raised and the frequency with which logs are cycled and purged.