[PATCH 7/8][v2] audisp-racf plugin - manual pages

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(a)br.ibm.com&gt; 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(a)br.ibm.com&gt; +.\" +.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/CC... ), +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(a)br.ibm.com&gt; 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(a)br.ibm.com&gt; +.\" +.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(a)br.ibm.com&gt;