contrib/openbsm/man/auditon.2

   1 .\"-
   2 .\" Copyright (c) 2005 Robert N. M. Watson
   3 .\" Copyright (c) 2005 Tom Rhodes
   4 .\" Copyright (c) 2005 Wayne J. Salamon
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $P4: //depot/projects/trustedbsd/openbsm/man/auditon.2#11 $
  29 .\"
  30 .Dd April 19, 2005
  31 .Dt AUDITON 2
  32 .Os
  33 .Sh NAME
  34 .Nm auditon
  35 .Nd "configure system audit parameters"
  36 .Sh SYNOPSIS
  37 .In bsm/audit.h
  38 .Ft int
  39 .Fn auditon "int cmd" "void *data" "u_int length"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn auditon
  43 system call is used to manipulate various audit control operations.
  44 The
  45 .Fa data
  46 argument
  47 should point to a structure whose type depends on the command.
  48 The
  49 .Fa length
  50 argument
  51 specifies the size of
  52 .Fa *data
  53 in bytes.
  54 The
  55 .Fa cmd
  56 argument
  57 may be any of the following:
  58 .Bl -tag -width ".It Dv A_GETPINFO_ADDR"
  59 .It Dv A_SETPOLICY
  60 Set audit policy flags.
  61 The
  62 .Fa data
  63 argument
  64 must point to a
  65 .Vt long
  66 value set to one of the audit
  67 policy control values defined in
  68 .In bsm/audit.h .
  69 Currently, only
  70 .Dv AUDIT_CNT
  71 and
  72 .Dv AUDIT_AHLT
  73 are implemented.
  74 In the
  75 .Dv AUDIT_CNT
  76 case, the action will continue regardless if
  77 an event will not be audited.
  78 In the
  79 .Dv AUDIT_AHLT
  80 case, a
  81 .Xr panic 9
  82 will result if an event will not be written to the
  83 audit log file.
  84 .It Dv A_SETKAUDIT
  85 Return
  86 .Er ENOSYS .
  87 .It Dv A_SETKMASK
  88 Set the kernel preselection masks (success and failure).
  89 The
  90 .Fa data
  91 argument
  92 must point to a
  93 .Vt au_mask_t
  94 structure containing the mask values.
  95 These masks are used for non-attributable audit event preselection.
  96 .It Dv A_SETQCTRL
  97 Set kernel audit queue parameters.
  98 The
  99 .Fa data
 100 argument
 101 must point to a
 102 .Vt au_qctrl_t
 103 structure containing the
 104 kernel audit queue control settings:
 105 .Dq "high water" ,
 106 .Dq "low water" ,
 107 .Dq "output buffer size" ,
 108 .Dq "percent min free disk space" ,
 109 and
 110 .Dq delay
 111 (not currently used).
 112 .It Dv A_SETSTAT
 113 Return
 114 .Er ENOSYS .
 115 .It Dv A_SETUMASK
 116 Return
 117 .Er ENOSYS .
 118 .It Dv A_SETSMASK
 119 Return
 120 .Er ENOSYS .
 121 .It Dv A_SETCOND
 122 Set the current auditing condition.
 123 The
 124 .Fa data
 125 argument
 126 must point to a
 127 .Vt long
 128 value containing the new
 129 audit condition, one of
 130 .Dv AUC_AUDITING ,
 131 .Dv AUC_NOAUDIT ,
 132 or
 133 .Dv AUC_DISABLED .
 134 .It Dv A_SETCLASS
 135 Set the event class preselection mask for an audit event.
 136 The
 137 .Fa data
 138 argument
 139 must point to a
 140 .Vt au_evclass_map_t
 141 structure containing the audit event and mask.
 142 .It Dv A_SETPMASK
 143 Set the preselection masks for a process.
 144 The
 145 .Fa data
 146 argument
 147 must point to a
 148 .Vt auditpinfo_t
 149 structure that contains the given process's audit
 150 preselection masks for both success and failure.
 151 .It Dv A_SETFSIZE
 152 Set the maximum size of the audit log file.
 153 The
 154 .Fa data
 155 argument
 156 must point to a
 157 .Vt au_fstat_t
 158 structure with the
 159 .Va af_filesz
 160 field set to the maximum audit log file size.
 161 A value of 0
 162 indicates no limit to the size.
 163 .It Dv A_SETKAUDIT
 164 Return
 165 .Er ENOSYS .
 166 .It Dv A_GETCLASS
 167 Return the event to class mapping for the designated audit event.
 168 The
 169 .Fa data
 170 argument
 171 must point to a
 172 .Vt au_evclass_map_t
 173 structure.
 174 .It Dv A_GETKAUDIT
 175 Return
 176 .Er ENOSYS .
 177 .It Dv A_GETPINFO
 178 Return the audit settings for a process.
 179 The
 180 .Fa data
 181 argument
 182 must point to a
 183 .Vt auditpinfo_t
 184 structure which will be set to contain
 185 the audit ID, preselection mask, terminal ID, and audit session
 186 ID of the given process.
 187 .It Dv A_GETPINFO_ADDR
 188 Return
 189 .Er ENOSYS .
 190 .It Dv A_GETKMASK
 191 Return the current kernel preselection masks.
 192 The
 193 .Fa data
 194 argument
 195 must point to a
 196 .Vt au_mask_t
 197 structure which will be set to
 198 the current kernel preselection masks for non-attributable events.
 199 .It Dv A_GETPOLICY
 200 Return the current audit policy setting.
 201 The
 202 .Fa data
 203 argument
 204 must point to a
 205 .Vt long
 206 value which will be set to
 207 one of the current audit policy flags.
 208 Currently, only
 209 .Dv AUDIT_CNT
 210 and
 211 .Dv AUDIT_AHLT
 212 are implemented.
 213 .It Dv A_GETQCTRL
 214 Return the current kernel audit queue control parameters.
 215 The
 216 .Fa data
 217 argument
 218 must point to a
 219 .Vt au_qctrl_t
 220 structure which will be set to the current
 221 kernel audit queue control parameters.
 222 .It Dv A_GETFSIZE
 223 Returns the maximum size of the audit log file.
 224 The
 225 .Fa data
 226 argument
 227 must point to a
 228 .Vt au_fstat_t
 229 structure.
 230 The
 231 .Va af_filesz
 232 field will be set to the maximum audit log file size.
 233 A value of 0 indicates no limit to the size.
 234 The
 235 .Va af_currsz
 236 field
 237 will be set to the current audit log file size.
 238 .It Dv A_GETCWD
 239 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 240 .\" Return the current working directory as stored in the audit subsystem.
 241 Return
 242 .Er ENOSYS .
 243 .It Dv A_GETCAR
 244 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 245 .\"Stores and returns the current active root as stored in the audit
 246 .\"subsystem.
 247 Return
 248 .Er ENOSYS .
 249 .It Dv A_GETSTAT
 250 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 251 .\"Return the statistics stored in the audit system.
 252 Return
 253 .Er ENOSYS .
 254 .It Dv A_GETCOND
 255 Return the current auditing condition.
 256 The
 257 .Fa data
 258 argument
 259 must point to a
 260 .Vt long
 261 value which will be set to
 262 the current audit condition, either
 263 .Dv AUC_AUDITING
 264 or
 265 .Dv AUC_NOAUDIT .
 266 .It Dv A_SENDTRIGGER
 267 Send a trigger to the audit daemon.
 268 The
 269 .Fa data
 270 argument
 271 must point to a
 272 .Vt long
 273 value set to one of the acceptable
 274 trigger values:
 275 .Dv AUDIT_TRIGGER_LOW_SPACE
 276 (low disk space where the audit log resides),
 277 .Dv AUDIT_TRIGGER_OPEN_NEW
 278 (open a new audit log file),
 279 .Dv AUDIT_TRIGGER_READ_FILE
 280 (read the
 281 .Pa audit_control
 282 file),
 283 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
 284 (close the current log file and exit),
 285 or
 286 .Dv AUDIT_TRIGGER_NO_SPACE
 287 (no disk space left for audit log file).
 288 .El
 289 .Sh RETURN VALUES
 290 .Rv -std
 291 .Sh ERRORS
 292 The
 293 .Fn auditon
 294 function will fail if:
 295 .Bl -tag -width Er
 296 .It Bq Er ENOSYS
 297 Returned by options not yet implemented.
 298 .It Bq Er EFAULT
 299 A failure occurred while data transferred to or from
 300 the kernel failed.
 301 .It Bq Er EINVAL
 302 Illegal argument was passed by a system call.
 303 .It Bq Er EPERM
 304 The process does not have sufficient permission to complete
 305 the operation.
 306 .El
 307 .Pp
 308 The
 309 .Dv A_SENDTRIGGER
 310 command is specific to the
 311 .Fx
 312 and Mac OS X implementations, and is not present in Solaris.
 313 .Sh SEE ALSO
 314 .Xr audit 2 ,
 315 .Xr auditctl 2 ,
 316 .Xr getaudit 2 ,
 317 .Xr getaudit_addr 2 ,
 318 .Xr getauid 2 ,
 319 .Xr setaudit 2 ,
 320 .Xr setaudit_addr 2 ,
 321 .Xr setauid 2 ,
 322 .Xr libbsm 3
 323 .Sh HISTORY
 324 The OpenBSM implementation was created by McAfee Research, the security
 325 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 326 It was subsequently adopted by the TrustedBSD Project as the foundation for
 327 the OpenBSM distribution.
 328 .Sh AUTHORS
 329 .An -nosplit
 330 This software was created by McAfee Research, the security research division
 331 of McAfee, Inc., under contract to Apple Computer Inc.
 332 Additional authors include
 333 .An Wayne Salamon ,
 334 .An Robert Watson ,
 335 and SPARTA Inc.
 336 .Pp
 337 The Basic Security Module (BSM) interface to audit records and audit event
 338 stream format were defined by Sun Microsystems.
 339 .Pp
 340 This manual page was written by
 341 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
 342 .An Robert Watson Aq rwatson@FreeBSD.org ,
 343 and
 344 .An Wayne Salamon Aq wsalamon@FreeBSD.org .