[PATCH, v3 7/8] audispd-zos-remote plugin - manual pages

Thu Dec 13 15:49:44 UTC 2007

This patch brings the audispd-zos-remote(8) and zos-remote.conf(5)
manual pages.
Those also bring some information on how to configure an IBM z/OS server
running ITDS to enable Remote Auditing processing, as well as how to
configure the required @LINUX class.

Signed-off-by: Klaus Heinrich Kiwi <klausk at br.ibm.com>

diff -purN audit-1.6.2/docs/audispd-zos-remote.8 audit-1.6.2_zos-remote/docs/audispd-zos-remote.8

--- audit-1.6.2/docs/audispd-zos-remote.8	1969-12-31 21:00:00.000000000 -0300
+++ audit-1.6.2_zos-remote/docs/audispd-zos-remote.8	2007-12-04 14:44:22.000000000 -0200
@@ -0,0 +1,239 @@
+.\" Copyright (c) International Business Machines  Corp., 2007
+.\"
+.\" This program is free software;  you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY;  without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+.\" the GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program;  if not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+.\" MA 02111-1307 USA
+.\"
+.\" Changelog:
+.\" 2007-10-06, created by Klaus Heinrich Kiwi <klausk at br.ibm.com>
+.\"
+.TH AUDISP-RACF 8 "Oct 2007" "IBM" "System Administration Utilities"
+.SH NAME
+audispd-zos-remote \- z/OS Remote-services Audit dispatcher plugin
+.SH SYNOPSIS
+.B audispd-zos-remote [
+.I config-file
+.B ]
+.SH DESCRIPTION
+.BR audispd-zos-remote
+is a remote-auditing plugin for the Audit subsystem. It should be started by the
+.BR audispd(8)
+daemon and will forward all incoming audit events, as they happen, to a configured z/OS SMF (Service Management Facility) database, through an IBM Tivoli Directory Server (ITDS) set for Remote Audit service.
+See
+.B SMF MAPPING
+section below for more information about the resulting SMF record format.
+
+.BR audispd(8)
+must be configured to start the plugin. This is done by a configuration file usually located at
+.IR /etc/audisp/plugins.d/audispd-zos-remote.conf ,
+but multiple instances can be spawned by having multiple configuration files in
+.I /etc/audisp/plugins.d
+for the same plugin executable (see
+.BR audispd(8) ).
+
+Each instance needs a configuration file, located by default at
+.IR /etc/audisp/zos-remote.conf .
+Check
+.BR zos-remote.conf(5)
+for details about the plugin configuration.
+
+.SH OPTIONS
+.IP config-file
+Use an alternate configuration file instead of
+.IR /etc/audisp/zos-remote.conf .
+
+.SH SIGNALS
+.BR audispd-zos-remote
+reacts to SIGTERM and SIGHUP signals (according to the
+.BR audispd(8)
+specification):
+.TP
+.B SIGHUP
+Instructs the
+.B audispd-zos-remote
+plugin to re-read it's configuration and flush existing network connections.
+.TP
+.B SIGTERM
+Performs a clean exit.
+.B audispd-zos-remote
+will wait up to 10 seconds if there are queued events to be delivered, dropping any remaining queued events after that time.
+
+.SH IBM z/OS ITDS Server and RACF configuration
+In order to use this plugin, you must have an IBM z/OS v1R8 (or higher) server with IBM Tivoli Directory Server (ITDS) configured for Remote Audit service. For more detailed information about how to configure the z/OS server for Remote Auditing, refer to
+.B z/OS V1R8.0-9.0 Intergrated Security Services Enterprise Identity Mapping (EIM) Guide and Reference
+.RI ( http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/FRAMESET/EIMA1140/CCONTENTS?DT=20070827115119 ),
+chapter "2.0 - Working with remote services".
+
+.SS Enable ITDS to process Remote Audit requests
+To enable ITSD to process Remote Audit requests, the user ID associated with ITDS must be granted READ access to the IRR.AUDITX FACILITY Class profile (the profile used to protect the R_Auditx service). This user ID can usually be found in the STARTED Class profile for the ITDS started procedure. If the identity associated with ITDS is
+.IR ITDSUSER ,
+the administrator can configure RACF to grant Remote Auditing processing to ITDS with the following TSO commands:
+.TP
+.I TSO Commands: Grant ITDSUSER READ access to IRR.AUDITX FACILITY Class profile
+.nf
+rdefine FACILITY IRR.RAUDITX uacc(none)
+permit IRR.RAUDITX class(FACILITY) id(ITDSUSER) access(READ)
+.fi
+
+.SS Create/enable RACF user ID to perform Remote Audit requests
+A z/OS RACF user ID is needed by the plugin - Every Audit request performed by the plugin will use a RACF user ID, as configured in the plugin configuration (
+.BR zos-remote.conf(5) ).
+This user ID needs READ access to FACILITY Class resource IRR.LDAP.REMOTE.AUDIT. If the user ID is
+.IR BINDUSER ,
+the administrator can configure RACF to enable this user to perform Remote Auditing requests with the following TSO commands:
+.TP
+.I TSO Commands: Enable BINDUSER to perform Remote Audit requests
+.nf
+rdefine FACILITY IRR.LDAP.REMOTE.AUDIT uacc(none)
+permit IRR.LDAP.REMOTE.AUDIT class(FACILITY) id(BINDUSER) access(READ)
+.fi
+
+.SS Add @LINUX Class to RACF
+When performing remote auditing requests, the
+.B audispd-zos-remote
+plugin will use the special
+.B @LINUX 
+.I CDT Class 
+and the audit record type (eg.:
+.BR SYSCALL ,
+.BR AVC ,
+.BR PATH ...)
+as the 
+.R CDT Resource Class
+for all events processed.
+To make sure events are logged, the RACF server must be configured with a Dynamic CDT Class named
+.B @LINUX
+with correct sizes and attributes. The following TSO commands can be used to add this class:
+.TP
+.I TSO Commands: Add @LINUX CDT Class
+.nf
+rdefine cdt @LINUX cdtinfo(posit(493) FIRST(alpha,national,numeric,special) OTHER(alpha,national,numeric,special) RACLIST(REQUIRED) case(asis) generic(allowed) defaultuacc(none) maxlength(246))
+setr classact(cdt)
+setr raclist(cdt)
+setr raclist(cdt) refresh
+setr classact(@LINUX)
+setr raclist(@LINUX)
+setr generic(@LINUX)
+.fi
+
+.SS Add profiles to the @LINUX Class
+Once the CDT Class has been defined, you can add profiles to it, specifying resources (wildcards allowed) to log or ignore. The following are examples:
+.TP
+.I  TSO Commands: Log only AVC records (One generic and one discrete profile):
+.nf
+rdefine @LINUX * uacc(none) audit(none(read)) 
+rdefine @LINUX AVC uacc(none) audit(all(read)) 
+setr raclist(@LINUX) refresh
+.fi
+
+.TP
+.I TSO Commands: Log everything (One generic profile):
+.nf
+rdefine @LINUX * uacc(none) audit(all(read))
+setr raclist(@LINUX) refresh
+.fi
+
+.P
+Resources always match the single profile with the
+.I best
+match.
+
+There are many other ways to define logging in RACF. Please refer to the server documentation for more details.
+
+.SH SMF Mapping
+The ITDS Remote Audit service will cut SMF records of type 83 subtype 4 everytime it processes a request. This plugin will issue a remote audit request for every incoming Linux Audit record (meaning that one Linux record will map to one SMF record), and fill this type's records with the following:
+.SS Link Value
+The Linux event serial number, encoded in network-byte order hexadecimal representation. Records within the same Event share the same Link Value.
+.SS Violation
+Always zero (0) -
+.I False
+.SS Event Code
+Always two (2) -
+.I Authorization
+event
+.SS Event Qualifier
+Zero (0) -
+.IR Success ,
+if the event reported
+.B success=yes
+or
+.BR res=success ,
+Three (3) -
+.IR Fail ,
+if the event reported
+.B success=no
+or
+.BR res=failed ,
+or One (1) -
+.I Info
+otherwise.
+.SS Class
+Always
+.I @LINUX
+.SS Resource
+The Linux record type for the processed record. e.g.:
+.IR SYSCALL , AVC , PATH , CWD
+etc.
+.SS Log String
+Textual message bringing the RACF user ID used to perform the request, plus the Linux hostname and the record type for the first record in the processed event. e.g.:
+.I Remote audit request from RACFUSER. Linux (hostname.localdomain):USER_AUTH 
+.SS Data Field List
+Also known as
+.IR relocates ,
+this list will bring all the field names and values in a
+.B fieldname=value
+format, as a type 114
+.RB ( "Appication specific Data" )
+relocate. The plug-in will try to interpret those fields (i.e.: use human-readable username
+.B root
+instead of numeric userid
+.BR 0 ) 
+whenever possible. Currently, this plugin will also add a relocate type 113
+.RB ( "Date And Time Security Event Occurred" )
+with the Event Timestamp in the format as returned by
+.BR ctime(3) .
+
+.SH ERRORS
+Errors and warnings are reported to syslog (under DAEMON facility). In situations where the event was submitted but the z/OS server returned an error condition, the logged message brings a name followed by a human-readable description. Below are some common errors conditions:
+
+.TP
+.B NOTREQ - No logging required
+Resource (audit record type) is not set to be logged in the RACF server - The @LINUX Class profile governing this audit record type is set to ignore. See
+.B IBM z/OS RACF Server configuration
+.TP
+.B UNDETERMINED - Undetermined result
+No profile found for specified resource. There is no @LINUX Class configured or no @LINUX Class profile associated with this audit record type. See
+.B IBM z/OS RACF Server configuration
+.TP
+.B UNAUTHORIZED - The user does not have authority the R_auditx service
+The user ID associated with the ITDS doesn't have READ access to the IRR.AUDITX FACILITY Class profile. See
+.B IBM z/OS RACF Server configuration
+.TP
+.B UNSUF_AUTH - The user has unsuficient authority for the requested function
+The RACF user ID used to perform Remote Audit requests (as configured in
+.BR zos-remote.conf(5) )
+don't have access to the IRR.LDAP.REMOTE.AUDIT FACILITY Class profile. See
+.B IBM z/OS RACF Server configuration
+
+.SH BUGS
+The plugin currently does remote auditing in a best-effort basis, and will dischard events in case the z/OS server cannot be contacted (network failures) or in any other case that event submission fails. 
+
+.SH FILES
+/etc/audisp/plugins.d/audispd-zos-remote.conf
+/etc/audisp/zos-remote.conf
+.SH "SEE ALSO"
+.BR auditd (8),
+.BR zos-remote.conf (5).
+.SH AUTHOR
+Klaus Heinrich Kiwi <klausk at br.ibm.com>
diff -purN audit-1.6.2/docs/zos-remote.conf.5 audit-1.6.2_zos-remote/docs/zos-remote.conf.5
--- audit-1.6.2/docs/zos-remote.conf.5	1969-12-31 21:00:00.000000000 -0300
+++ audit-1.6.2_zos-remote/docs/zos-remote.conf.5	2007-12-04 14:50:54.000000000 -0200
@@ -0,0 +1,69 @@
+.\" Copyright (c) International Business Machines  Corp., 2007
+.\"
+.\" This program is free software;  you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY;  without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+.\" the GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program;  if not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+.\" MA 02111-1307 USA
+.\"
+.\" Changelog:
+.\" 2007-10-06, created by Klaus Heinrich Kiwi <klausk at br.ibm.com>
+.\"
+.TH ZOS\-REMOTE.CONF 8 "Oct 2007" "IBM" "System Administration Utilities"
+.SH NAME
+zos\-remote.conf \- the audisp-racf plugin configuration file
+.SH DESCRIPTION
+.B zos-remote.conf
+controls the configuration for the
+.BR audispd-zos-remote(8)
+Audit dispatcher plugin. The default location for this file is
+.IR /etc/audisp/zos-remote.conf ,
+however, a different file can be specified as the first argument to the
+.B audispd-zos-remote
+plugin. See
+.BR audispd-zos-remote(8)
+and
+.BR auditd(8) .
+The options available are as follows:
+.TP
+.I server
+This is the IBM z/OS ITDS server hostname or IP address
+.TP
+.I port
+The port number where ITDS is running on the z/OS server. Default is 389 (ldap port)
+.TP
+.I user
+The z/OS RACF user ID which the audispd-zos-remote plugin will use to perform Remote Audit requests. This user needs READ access to FACILITY Class resource IRR.LDAP.REMOTE.AUDIT (See
+.BR audispd-zos-remote(8) ).
+.TP
+.I password
+The password associated the the z/OS user ID configured above.
+.TP
+.I timeout
+The number in seconds that
+.B audispd-zos-remote
+plugin will wait before giving up in connection attemps and event submissions. The default value is 15
+.TP
+.I q_depth
+The
+.B audispd-zos-remote
+plugin will queue inputed events to the maximum of
+.I q_depth
+events while trying to submit those remotely. This can handle burst of events or in case of a slow network connection. However, the
+.B audispd-zos-remote
+plugin will drop events in case the queue is full. The default queue depth is 64 - Increase this value in case you are experiencing event drop due to full queue
+.RB ( audispd-zos-remote
+will log this to syslog).
+.SH "SEE ALSO"
+.BR audispd-zos-remote (8)
+.SH AUTHOR
+Klaus Heinrich Kiwi <klausk at br.ibm.com>

-- 
Klaus Heinrich Kiwi <klausk at linux.vnet.ibm.com>
IBM STG, Linux Technology Center


