| 1 |
.\" Copyright (c) International Business Machines Corp., 2007 |
| 2 |
.\" |
| 3 |
.\" This program is free software; you can redistribute it and/or |
| 4 |
.\" modify it under the terms of the GNU General Public License as |
| 5 |
.\" published by the Free Software Foundation; either version 2 of |
| 6 |
.\" the License, or (at your option) any later version. |
| 7 |
.\" |
| 8 |
.\" This program is distributed in the hope that it will be useful, |
| 9 |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 10 |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See |
| 11 |
.\" the GNU General Public License for more details. |
| 12 |
.\" |
| 13 |
.\" You should have received a copy of the GNU General Public License |
| 14 |
.\" along with this program; if not, write to the Free Software |
| 15 |
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
| 16 |
.\" MA 02111-1307 USA |
| 17 |
.\" |
| 18 |
.\" Changelog: |
| 19 |
.\" 2007-10-06, created by Klaus Heinrich Kiwi <[email protected]> |
| 20 |
.\" |
| 21 |
.TH AUDISPD-ZOS-REMOTE 8 "Oct 2007" "IBM" "System Administration Utilities" |
| 22 |
.SH NAME |
| 23 |
audispd\-zos\-remote \- z/OS Remote-services Audit dispatcher plugin |
| 24 |
.SH SYNOPSIS |
| 25 |
.B audispd\-zos\-remote [ |
| 26 |
.I config-file |
| 27 |
.B ] |
| 28 |
.SH DESCRIPTION |
| 29 |
.B audispd\-zos\-remote |
| 30 |
is a remote-auditing plugin for the Audit subsystem. It should be started by the |
| 31 |
.BR auditd (8) |
| 32 |
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. |
| 33 |
See |
| 34 |
.B SMF MAPPING |
| 35 |
section below for more information about the resulting SMF record format. |
| 36 |
|
| 37 |
.BR auditd (8) |
| 38 |
must be configured to start the plugin. This is done by a configuration file usually located at |
| 39 |
.IR /etc/audit/plugins.d/audispd\-zos\-remote.conf , |
| 40 |
but multiple instances can be spawned by having multiple configuration files in |
| 41 |
.I /etc/audit/plugins.d |
| 42 |
for the same plugin executable (see |
| 43 |
.BR auditd (8)). |
| 44 |
|
| 45 |
Each instance needs a configuration file, located by default at |
| 46 |
.IR /etc/audit/zos\-remote.conf . |
| 47 |
Check |
| 48 |
.BR zos\-remote.conf (5) |
| 49 |
for details about the plugin configuration. |
| 50 |
|
| 51 |
.SH OPTIONS |
| 52 |
.IP config-file |
| 53 |
Use an alternate configuration file instead of |
| 54 |
.IR /etc/audit/zos\-remote.conf . |
| 55 |
|
| 56 |
.SH SIGNALS |
| 57 |
.B audispd\-zos\-remote |
| 58 |
reacts to SIGTERM and SIGHUP signals (according to the |
| 59 |
.BR auditd (8) |
| 60 |
specification): |
| 61 |
.TP |
| 62 |
.B SIGHUP |
| 63 |
Instructs the |
| 64 |
.B audispd\-zos\-remote |
| 65 |
plugin to re-read it's configuration and flush existing network connections. |
| 66 |
.TP |
| 67 |
.B SIGTERM |
| 68 |
Performs a clean exit. |
| 69 |
.B audispd\-zos\-remote |
| 70 |
will wait up to 10 seconds if there are queued events to be delivered, dropping any remaining queued events after that time. |
| 71 |
|
| 72 |
.SH IBM z/OS ITDS Server and RACF configuration |
| 73 |
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 |
| 74 |
.B z/OS V1R8.0-9.0 Integrated Security Services Enterprise Identity Mapping (EIM) Guide and Reference |
| 75 |
.nf |
| 76 |
.RI ( http://publibz.boulder.ibm.com/cgi\-bin/bookmgr_OS390/FRAMESET/EIMA1140/CCONTENTS?DT=20070827115119 ), |
| 77 |
chapter "2.0 - Working with remote services". |
| 78 |
.fi |
| 79 |
|
| 80 |
.SS Enable ITDS to process Remote Audit requests |
| 81 |
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 |
| 82 |
.IR ITDSUSER , |
| 83 |
the administrator can configure RACF to grant Remote Auditing processing to ITDS with the following TSO commands: |
| 84 |
.TP |
| 85 |
.I TSO Commands: Grant ITDSUSER READ access to IRR.AUDITX FACILITY Class profile |
| 86 |
.nf |
| 87 |
rdefine FACILITY IRR.RAUDITX uacc(none) |
| 88 |
permit IRR.RAUDITX class(FACILITY) id(ITDSUSER) access(READ) |
| 89 |
.fi |
| 90 |
|
| 91 |
.SS Create/enable RACF user ID to perform Remote Audit requests |
| 92 |
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 |
| 93 |
.BR zos\-remote.conf (5). |
| 94 |
This user ID needs READ access to FACILITY Class resource IRR.LDAP.REMOTE.AUDIT. If the user ID is |
| 95 |
.IR BINDUSER , |
| 96 |
the administrator can configure RACF to enable this user to perform Remote Auditing requests with the following TSO commands: |
| 97 |
.TP |
| 98 |
.I TSO Commands: Enable BINDUSER to perform Remote Audit requests |
| 99 |
.nf |
| 100 |
rdefine FACILITY IRR.LDAP.REMOTE.AUDIT uacc(none) |
| 101 |
permit IRR.LDAP.REMOTE.AUDIT class(FACILITY) id(BINDUSER) access(READ) |
| 102 |
.fi |
| 103 |
|
| 104 |
.SS Add @LINUX Class to RACF |
| 105 |
When performing remote auditing requests, the |
| 106 |
.B audispd\-zos\-remote |
| 107 |
plugin will use the special |
| 108 |
.B @LINUX |
| 109 |
.I CDT Class |
| 110 |
and the audit record type (eg.: |
| 111 |
.BR SYSCALL , |
| 112 |
.BR AVC , |
| 113 |
.BR PATH ...) |
| 114 |
as the |
| 115 |
.I CDT Resource Class |
| 116 |
for all events processed. |
| 117 |
To make sure events are logged, the RACF server must be configured with a Dynamic CDT Class named |
| 118 |
.B @LINUX |
| 119 |
with correct sizes and attributes. The following TSO commands can be used to add this class: |
| 120 |
.TP |
| 121 |
.I TSO Commands: Add @LINUX CDT Class |
| 122 |
.nf |
| 123 |
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)) |
| 124 |
setr classact(cdt) |
| 125 |
setr raclist(cdt) |
| 126 |
setr raclist(cdt) refresh |
| 127 |
setr classact(@LINUX) |
| 128 |
setr raclist(@LINUX) |
| 129 |
setr generic(@LINUX) |
| 130 |
.fi |
| 131 |
|
| 132 |
.SS Add profiles to the @LINUX Class |
| 133 |
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: |
| 134 |
.TP |
| 135 |
.I TSO Commands: Log only AVC records (One generic and one discrete profile): |
| 136 |
.nf |
| 137 |
rdefine @LINUX * uacc(none) audit(none(read)) |
| 138 |
rdefine @LINUX AVC uacc(none) audit(all(read)) |
| 139 |
setr raclist(@LINUX) refresh |
| 140 |
.fi |
| 141 |
|
| 142 |
.TP |
| 143 |
.I TSO Commands: Log everything (One generic profile): |
| 144 |
.nf |
| 145 |
rdefine @LINUX * uacc(none) audit(all(read)) |
| 146 |
setr raclist(@LINUX) refresh |
| 147 |
.fi |
| 148 |
|
| 149 |
.P |
| 150 |
Resources always match the single profile with the |
| 151 |
.I best |
| 152 |
match. |
| 153 |
|
| 154 |
There are many other ways to define logging in RACF. Please refer to the server documentation for more details. |
| 155 |
|
| 156 |
.SH SMF Mapping |
| 157 |
The ITDS Remote Audit service will cut SMF records of type 83 subtype 4 every time 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: |
| 158 |
.SS Link Value |
| 159 |
The Linux event serial number, encoded in network-byte order hexadecimal representation. Records within the same Event share the same Link Value. |
| 160 |
.SS Violation |
| 161 |
Always zero (0) - |
| 162 |
.I False |
| 163 |
.SS Event Code |
| 164 |
Always two (2) - |
| 165 |
.I Authorization |
| 166 |
event |
| 167 |
.SS Event Qualifier |
| 168 |
Zero (0) - |
| 169 |
.IR Success , |
| 170 |
if the event reported |
| 171 |
.B success=yes |
| 172 |
or |
| 173 |
.BR res=success , |
| 174 |
Three (3) - |
| 175 |
.IR Fail , |
| 176 |
if the event reported |
| 177 |
.B success=no |
| 178 |
or |
| 179 |
.BR res=failed , |
| 180 |
or One (1) - |
| 181 |
.I Info |
| 182 |
otherwise. |
| 183 |
.SS Class |
| 184 |
Always |
| 185 |
.I @LINUX |
| 186 |
.SS Resource |
| 187 |
The Linux record type for the processed record. e.g.: |
| 188 |
.IR SYSCALL , AVC , PATH , CWD |
| 189 |
etc. |
| 190 |
.SS Log String |
| 191 |
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.: |
| 192 |
.I Remote audit request from RACFUSER. Linux (hostname.localdomain):USER_AUTH |
| 193 |
.SS Data Field List |
| 194 |
Also known as |
| 195 |
.IR relocates , |
| 196 |
this list will bring all the field names and values in a |
| 197 |
.B fieldname=value |
| 198 |
format, as a type 114 |
| 199 |
.RB ( "Application specific Data" ) |
| 200 |
relocate. The plug-in will try to interpret those fields (i.e.: use human-readable username |
| 201 |
.B root |
| 202 |
instead of numeric userid |
| 203 |
.BR 0 ) |
| 204 |
whenever possible. Currently, this plugin will also add a relocate type 113 |
| 205 |
.RB ( "Date And Time Security Event Occurred" ) |
| 206 |
with the Event Timestamp in the format as returned by |
| 207 |
.BR ctime (3). |
| 208 |
|
| 209 |
.SH ERRORS |
| 210 |
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: |
| 211 |
|
| 212 |
.TP |
| 213 |
.B NOTREQ - No logging required |
| 214 |
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 |
| 215 |
.B IBM z/OS RACF Server configuration |
| 216 |
.TP |
| 217 |
.B UNDETERMINED - Undetermined result |
| 218 |
No profile found for specified resource. There is no @LINUX Class configured or no @LINUX Class profile associated with this audit record type. See |
| 219 |
.B IBM z/OS RACF Server configuration |
| 220 |
.TP |
| 221 |
.B UNAUTHORIZED - The user does not have authority the R_auditx service |
| 222 |
The user ID associated with the ITDS doesn't have READ access to the IRR.AUDITX FACILITY Class profile. See |
| 223 |
.B IBM z/OS RACF Server configuration |
| 224 |
.TP |
| 225 |
.B UNSUF_AUTH - The user has insufficient authority for the requested function |
| 226 |
The RACF user ID used to perform Remote Audit requests (as configured in |
| 227 |
.BR zos-remote.conf (5)) |
| 228 |
don't have access to the IRR.LDAP.REMOTE.AUDIT FACILITY Class profile. See |
| 229 |
.B IBM z/OS RACF Server configuration |
| 230 |
|
| 231 |
.SH BUGS |
| 232 |
The plugin currently does remote auditing in a best-effort basis, and will discard events in case the z/OS server cannot be contacted (network failures) or in any other case that event submission fails. |
| 233 |
|
| 234 |
.SH FILES |
| 235 |
/etc/audit/plugins.d/audispd\-zos\-remote.conf |
| 236 |
/etc/audit/zos\-remote.conf |
| 237 |
.SH "SEE ALSO" |
| 238 |
.BR auditd (8), |
| 239 |
.BR zos\-remote.conf (5). |
| 240 |
.SH AUTHOR |
| 241 |
Klaus Heinrich Kiwi <[email protected]> |