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#14 $
  29 .\"
  30 .Dd July 10, 2008
  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 or more the following audit
  67 policy control values bitwise OR'ed together:
  68 .Dv AUDIT_CNT ,
  69 .Dv AUDIT_AHLT ,
  70 .Dv AUDIT_ARGV ,
  71 and
  72 .Dv AUDIT_ARGE .
  73 If
  74 .Dv AUDIT_CNT is set, the system will continue even if it becomes low
  75 on space and discontinue logging events until the low space condition is
  76 remedied.
  77 If it is not set, audited events will block until the low space
  78 condition is remedied.
  79 Unaudited events, however, are unaffected.
  80 If
  81 .Dv AUDIT_AHLT is set, a
  82 .Xr panic 9
  83 if it cannot write an event to the global audit log file.
  84 If
  85 .Dv AUDIT_ARGV
  86 is set, then the argument list passed to the
  87 .Xr execve 2
  88 system call will be audited.  If
  89 .Dv AUDIT_ARGE
  90 is set, then the environment variables passed to the
  91 .Xr execve 2
  92 system call will be audited.  The default policy is none of the audit policy
  93 control flags set.
  94 .It Dv A_SETKAUDIT
  95 Return
  96 .Er ENOSYS .
  97 (Not implemented.)
  98 .It Dv A_SETKMASK
  99 Set the kernel preselection masks (success and failure).
 100 The
 101 .Fa data
 102 argument
 103 must point to a
 104 .Vt au_mask_t
 105 structure containing the mask values as defined in
 106 .In bsm/audit.h .
 107 These masks are used for non-attributable audit event preselection.
 108 The field
 109 .Fa am_success
 110 specifies which classes of successful audit events are to be logged to the
 111 audit trail. The field
 112 .Fa am_failure
 113 specifies which classes of failed audit events are to be logged. The value of
 114 both fields is the bitwise OR'ing of the audit event classes specified in
 115 .Fa bsm/audit.h .
 116 The various audit classes are described more fully in
 117 .Xr audit_class 5 .
 118 .It Dv A_SETQCTRL
 119 Set kernel audit queue parameters.
 120 The
 121 .Fa data
 122 argument
 123 must point to a
 124 .Vt au_qctrl_t
 125 structure (defined in
 126 .In bsm/audit.h )
 127 containing the kernel audit queue control settings:
 128 .Fa aq_hiwater ,
 129 .Fa aq_lowater ,
 130 .Fa aq_bufsz ,
 131 .Fa aq_delay ,
 132 and
 133 .Fa aq_minfree .
 134 The field
 135 .Fa aq_hiwater
 136 defines the maximum number of audit record entries in the queue used to store
 137 the audit records ready for delivery to disk.
 138 New records are inserted at the tail of the queue and removed from the head.
 139 For new records which would exceed the
 140 high water mark, the calling thread is inserted into the wait queue, waiting
 141 for the audit queue to have enough space available as defined with the field
 142 .Fa aq_lowater .
 143 The field
 144 .Fa aq_bufsz
 145 defines the maximum length of the audit record that can be supplied with
 146 .Xr audit 2 .
 147 The field
 148 .Fa aq_delay
 149 is unused.
 150 The field
 151 .Fa aq_minfree
 152 specifies the minimum amount of free blocks on the disk device used to store
 153 audit records.
 154 If the value of free blocks falls below the configured
 155 minimum amount, the kernel informs the audit daemon about low disk space.
 156 The value is to be specified in percent of free file system blocks.
 157 A value of 0 results in a disabling of the check.
 158 .It Dv A_SETSTAT
 159 Return
 160 .Er ENOSYS .
 161 (Not implemented.)
 162 .It Dv A_SETUMASK
 163 Return
 164 .Er ENOSYS .
 165 (Not implemented.)
 166 .It Dv A_SETSMASK
 167 Return
 168 .Er ENOSYS .
 169 (Not implemented.)
 170 .It Dv A_SETCOND
 171 Set the current auditing condition.
 172 The
 173 .Fa data
 174 argument
 175 must point to a
 176 .Vt long
 177 value containing the new
 178 audit condition, one of
 179 .Dv AUC_AUDITING ,
 180 .Dv AUC_NOAUDIT ,
 181 or
 182 .Dv AUC_DISABLED .
 183 If
 184 .Dv AUC_NOAUDIT
 185 is set, then auditing is temporarily suspended. If
 186 .Dv AUC_AUDITING
 187 is set, auditing is resumed. If
 188 .Dv AUC_DISABLED
 189 is set, the auditing system will
 190 shutdown, draining all audit records and closing out the audit trail file.
 191 .It Dv A_SETCLASS
 192 Set the event class preselection mask for an audit event.
 193 The
 194 .Fa data
 195 argument
 196 must point to a
 197 .Vt au_evclass_map_t
 198 structure containing the audit event and mask.
 199 The field
 200 .Fa ec_number
 201 is the audit event and
 202 .Fa ec_class
 203 is the audit class mask. See
 204 .Xr audit_event 5
 205 for more information on audit event to class mapping.
 206 .It Dv A_SETPMASK
 207 Set the preselection masks for a process.
 208 The
 209 .Fa data
 210 argument
 211 must point to a
 212 .Vt auditpinfo_t
 213 structure that contains the given process's audit
 214 preselection masks for both success and failure.
 215 The field
 216 .Fa ap_pid
 217 is the process id of the target process.
 218 The field
 219 .Fa ap_mask
 220 must point to a
 221 .Fa au_mask_t
 222 structure which holds the preselection masks as described in the
 223 .Da A_SETKMASK
 224 section above.
 225 .It Dv A_SETFSIZE
 226 Set the maximum size of the audit log file.
 227 The
 228 .Fa data
 229 argument
 230 must point to a
 231 .Vt au_fstat_t
 232 structure with the
 233 .Va af_filesz
 234 field set to the maximum audit log file size.
 235 A value of 0
 236 indicates no limit to the size.
 237 .It Dv A_SETKAUDIT
 238 Return
 239 .Er ENOSYS .
 240 (Not implemented.)
 241 .It Dv A_GETCLASS
 242 Return the event to class mapping for the designated audit event.
 243 The
 244 .Fa data
 245 argument
 246 must point to a
 247 .Vt au_evclass_map_t
 248 structure. See the
 249 .Dv A_SETCLASS
 250 section above for more information.
 251 .It Dv A_GETKAUDIT
 252 Return
 253 .Er ENOSYS .
 254 (Not implemented.)
 255 .It Dv A_GETPINFO
 256 Return the audit settings for a process.
 257 The
 258 .Fa data
 259 argument
 260 must point to a
 261 .Vt auditpinfo_t
 262 structure which will be set to contain
 263 .Fa ap_auid
 264 (the audit ID),
 265 .Fa ap_mask
 266 (the preselection mask),
 267 .Fa ap_termid
 268 (the terminal ID), and
 269 .Fa ap_asid
 270 (the audit session ID)
 271 of the given target process.
 272 The process ID of the target process is passed
 273 into the kernel using the
 274 .Fa ap_pid
 275 field.
 276 See the section
 277 .Dv A_SETPMASK
 278 above and
 279 .Xr getaudit 2
 280 for more information.
 281 .It Dv A_GETPINFO_ADDR
 282 Return the extended audit settings for a process.
 283 The
 284 .Fa data
 285 argument
 286 must point to a
 287 .Vt auditpinfo_addr_t
 288 structure which is similar to the
 289 .Vt auditpinfo_addr_t
 290 structure described above.
 291 The exception is the
 292 .Fa ap_termid
 293 (the terminal ID) field which points to a
 294 .Vt au_tid_addr_t
 295 structure can hold much a larger terminal address and an address type.
 296 The process ID of the target process is passed into the kernel using the
 297 .Fa ap_pid
 298 field.
 299 See the section
 300 .Dv A_SETPMASK
 301 above and
 302 .Xr getaudit 2
 303 for more information.
 304 .It Dv A_GETKMASK
 305 Return the current kernel preselection masks.
 306 The
 307 .Fa data
 308 argument
 309 must point to a
 310 .Vt au_mask_t
 311 structure which will be set to
 312 the current kernel preselection masks for non-attributable events.
 313 .It Dv A_GETPOLICY
 314 Return the current audit policy setting.
 315 The
 316 .Fa data
 317 argument
 318 must point to a
 319 .Vt long
 320 value which will be set to
 321 one of the current audit policy flags.
 322 The audit policy flags are
 323 described in the
 324 .Dv A_SETPOLICY
 325 section above.
 326 .It Dv A_GETQCTRL
 327 Return the current kernel audit queue control parameters.
 328 The
 329 .Fa data
 330 argument
 331 must point to a
 332 .Vt au_qctrl_t
 333 structure which will be set to the current
 334 kernel audit queue control parameters.
 335 See the
 336 .Dv A_SETQCTL
 337 section above for more information.
 338 .It Dv A_GETFSIZE
 339 Returns the maximum size of the audit log file.
 340 The
 341 .Fa data
 342 argument
 343 must point to a
 344 .Vt au_fstat_t
 345 structure.
 346 The
 347 .Va af_filesz
 348 field will be set to the maximum audit log file size.
 349 A value of 0 indicates no limit to the size.
 350 The
 351 .Va af_currsz
 352 field
 353 will be set to the current audit log file size.
 354 .It Dv A_GETCWD
 355 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 356 .\" Return the current working directory as stored in the audit subsystem.
 357 Return
 358 .Er ENOSYS .
 359 (Not implemented.)
 360 .It Dv A_GETCAR
 361 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 362 .\"Stores and returns the current active root as stored in the audit
 363 .\"subsystem.
 364 Return
 365 .Er ENOSYS .
 366 (Not implemented.)
 367 .It Dv A_GETSTAT
 368 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 369 .\"Return the statistics stored in the audit system.
 370 Return
 371 .Er ENOSYS .
 372 (Not implemented.)
 373 .It Dv A_GETCOND
 374 Return the current auditing condition.
 375 The
 376 .Fa data
 377 argument
 378 must point to a
 379 .Vt long
 380 value which will be set to
 381 the current audit condition, one of
 382 .Dv AUC_AUDITING ,
 383 .Dv AUC_NOAUDIT
 384 or
 385 .Dv AUC_DISABLED .
 386 See the
 387 .Dv A_SETCOND
 388 section above for more information.
 389 .It Dv A_SENDTRIGGER
 390 Send a trigger to the audit daemon.
 391 The
 392 .Fa data
 393 argument
 394 must point to a
 395 .Vt long
 396 value set to one of the acceptable
 397 trigger values:
 398 .Dv AUDIT_TRIGGER_LOW_SPACE
 399 (low disk space where the audit log resides),
 400 .Dv AUDIT_TRIGGER_OPEN_NEW
 401 (open a new audit log file),
 402 .Dv AUDIT_TRIGGER_READ_FILE
 403 (read the
 404 .Pa audit_control
 405 file),
 406 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
 407 (close the current log file and exit),
 408 or
 409 .Dv AUDIT_TRIGGER_NO_SPACE
 410 (no disk space left for audit log file).
 411 .El
 412 .Sh RETURN VALUES
 413 .Rv -std
 414 .Sh ERRORS
 415 The
 416 .Fn auditon
 417 function will fail if:
 418 .Bl -tag -width Er
 419 .It Bq Er ENOSYS
 420 Returned by options not yet implemented.
 421 .It Bq Er EFAULT
 422 A failure occurred while data transferred to or from
 423 the kernel failed.
 424 .It Bq Er EINVAL
 425 Illegal argument was passed by a system call.
 426 .It Bq Er EPERM
 427 The process does not have sufficient permission to complete
 428 the operation.
 429 .El
 430 .Pp
 431 The
 432 .Dv A_SENDTRIGGER
 433 command is specific to the
 434 .Fx
 435 and Mac OS X implementations, and is not present in Solaris.
 436 .Sh SEE ALSO
 437 .Xr audit 2 ,
 438 .Xr auditctl 2 ,
 439 .Xr getaudit 2 ,
 440 .Xr getaudit_addr 2 ,
 441 .Xr getauid 2 ,
 442 .Xr setaudit 2 ,
 443 .Xr setaudit_addr 2 ,
 444 .Xr setauid 2 ,
 445 .Xr libbsm 3
 446 .Sh HISTORY
 447 The OpenBSM implementation was created by McAfee Research, the security
 448 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 449 It was subsequently adopted by the TrustedBSD Project as the foundation for
 450 the OpenBSM distribution.
 451 .Sh AUTHORS
 452 .An -nosplit
 453 This software was created by McAfee Research, the security research division
 454 of McAfee, Inc., under contract to Apple Computer Inc.
 455 Additional authors include
 456 .An Wayne Salamon ,
 457 .An Robert Watson ,
 458 and SPARTA Inc.
 459 .Pp
 460 The Basic Security Module (BSM) interface to audit records and audit event
 461 stream format were defined by Sun Microsystems.
 462 .Pp
 463 This manual page was written by
 464 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
 465 .An Robert Watson Aq rwatson@FreeBSD.org ,
 466 and
 467 .An Wayne Salamon Aq wsalamon@FreeBSD.org .