docs/audispd-zos-remote.8

   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 <klausk@br.ibm.com>
  20 .\"
  21 .TH AUDISP-RACF 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 audispd (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 audispd (8)
  38 must be configured to start the plugin. This is done by a configuration file usually located at
  39 .IR /etc/audisp/plugins.d/audispd\-zos\-remote.conf ,
  40 but multiple instances can be spawned by having multiple configuration files in
  41 .I /etc/audisp/plugins.d
  42 for the same plugin executable (see
  43 .BR audispd (8)).
  44
  45 Each instance needs a configuration file, located by default at
  46 .IR /etc/audisp/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/audisp/zos\-remote.conf .
  55
  56 .SH SIGNALS
  57 .B audispd\-zos\-remote
  58 reacts to SIGTERM and SIGHUP signals (according to the
  59 .BR audispd (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 Intergrated 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 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:
 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 ( "Appication 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 unsuficient 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 dischard 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/audisp/plugins.d/audispd\-zos\-remote.conf
 236 /etc/audisp/zos\-remote.conf
 237 .SH "SEE ALSO"
 238 .BR auditd (8),
 239 .BR zos\-remote.conf (5).
 240 .SH AUTHOR
 241 Klaus Heinrich Kiwi <klausk@br.ibm.com>