[PATCH 7/8][v2] audisp-racf plugin - manual pages
Klaus Heinrich Kiwi
klausk at br.ibm.com
Wed Oct 10 14:30:36 UTC 2007
This patch brings the audisp-racf(8) and racf.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/audisp-racf.8 audit-1.6.2_racf/docs/audisp-racf.8
--- audit-1.6.2/docs/audisp-racf.8 1969-12-31 21:00:00.000000000 -0300
+++ audit-1.6.2_racf/docs/audisp-racf.8 2007-10-10 10:26:18.000000000 -0300
@@ -0,0 +1,183 @@
+.\" 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
+audisp-racf \- audit plugin for remote z/OS RACF auditing
+.SH SYNOPSIS
+.B audisp-racf [
+.I config-file
+.B ]
+.SH DESCRIPTION
+.BR audisp-racf
+is a remote-auditing plugin for the audit subsystem. It should be started by the
+.BR audispd(8)
+daemon and will forward incoming audit events to RACF, via an IBM z/OS server running ITDS with Remote Auditing enabled.
+
+.BR audispd(8)
+must be configured to start the plugin. This is done by a configuration file usually located at
+.I /etc/audisp/plugins.d/audisp-racf.conf
+, but multiple instances can be spawned by other files in
+.I /etc/audisp/plugins.d
+directory (see
+.BR audispd(8) ).
+
+Each instance needs a configuration file, located by default at
+.IR /etc/audisp/racf.conf .
+Check
+.BR racf.conf(5)
+for details about the plugin configuration.
+
+.SH OPTIONS
+.IP config-file
+Use an alternate configuration file instead of
+.IR /etc/audisp/racf.conf .
+
+.SH SIGNALS
+.BR audisp-racf
+reacts to SIGTERM and SIGHUP signals (according to the
+.BR audispd(8)
+spefi):
+.TP
+.B SIGHUP
+Instructs the
+.B audisp-racf
+plugin to re-read it's configuration and flush existing network connections.
+.TP
+.B SIGTERM
+Performs a clean exit.
+.B audisp-racf
+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 Auditing. 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 Enable user ID to perform Remote Audit requests
+A z/OS user ID is needed for the user of the Remote Audit service. This is the user ID that must be configured in the
+.BR racf.conf(5)
+file. This user 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
+The
+.B audisp-racf
+plugin uses
+.B @LINUX
+as
+.I Class
+and the audit record type (eg.:
+.BR SYSCALL ,
+.BR AVC ,
+.BR PATH ...)
+as
+.IR Resource ,
+so 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 ERRORS
+Errors and warnings are reported to syslog (under DAEMON facility). In situations where the event was submitted but the RACF 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 user ID used to perform Remote Audit requests (as configured in
+.BR racf.conf(5) )
+doesn'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 RACF server cannot be contacted or if the event submission fails.
+
+.SH FILES
+/etc/audisp/plugins.d/audisp-racf.conf
+/etc/audisp/racf.conf
+.SH "SEE ALSO"
+.BR auditd (8),
+.BR racf.conf (5).
+.SH AUTHOR
+Klaus Heinrich Kiwi <klausk at br.ibm.com>
diff -purN audit-1.6.2/docs/Makefile.am audit-1.6.2_racf/docs/Makefile.am
--- audit-1.6.2/docs/Makefile.am 2007-09-18 12:31:41.000000000 -0300
+++ audit-1.6.2_racf/docs/Makefile.am 2007-10-10 10:26:18.000000000 -0300
@@ -46,5 +46,5 @@ auparse_node_compare.3 auparse_reset.3 a
aureport.8 ausearch.8 ausearch_add_item.3 ausearch_add_regex.3 \
ausearch_clear.3 ausearch_next_event.3 ausearch_set_stop.3 \
autrace.8 get_auditfail_action.3 set_aumessage_mode.3 \
-audispd.8 audispd.conf.5
+audispd.8 audispd.conf.5 audisp-racf.8 racf.conf.5
diff -purN audit-1.6.2/docs/racf.conf.5 audit-1.6.2_racf/docs/racf.conf.5
--- audit-1.6.2/docs/racf.conf.5 1969-12-31 21:00:00.000000000 -0300
+++ audit-1.6.2_racf/docs/racf.conf.5 2007-10-10 10:26:18.000000000 -0300
@@ -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 RACF.CONF 8 "Oct 2007" "IBM" "System Administration Utilities"
+.SH NAME
+racf.conf \- the audisp-racf plugin configuration file
+.SH DESCRIPTION
+.B racf.conf
+controls the configuration for the
+.BR audisp-racf(8)
+audit plugin. The default location for this file is
+.IR /etc/audisp/racf.conf ,
+however, a different file can be specified as the first argument to the
+.B audisp-racf
+plugin. See
+.BR audisp-racf(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 user ID which the audisp-racf plugin will use to perform Remote Audit requests. This user needs READ access to FACILITY Class resource IRR.LDAP.REMOTE.AUDIT (See
+.BR audisp-racf(8) ).
+.TP
+.I password
+The password associated the the z/OS user ID configured above.
+.TP
+.I timeout
+The number in seconds that
+.B audisp-racf
+plugin will wait before giving up in connection attemps and event submissions. The default value is 15
+.TP
+.I q_depth
+The
+.B audisp-racf
+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 audisp-racf
+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 ( audisp-racf
+will log this to syslog).
+.SH "SEE ALSO"
+.BR audisp-racf (8)
+.SH AUTHOR
+Klaus Heinrich Kiwi <klausk at br.ibm.com>
More information about the Linux-audit
mailing list