contrib/openbsm/man/auditon.2

   1 .\"-
   2 .\" Copyright (c) 2008-2009 Apple Inc.
   3 .\" Copyright (c) 2005 Robert N. M. Watson
   4 .\" Copyright (c) 2005 Tom Rhodes
   5 .\" Copyright (c) 2005 Wayne J. Salamon
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $P4: //depot/projects/trustedbsd/openbsm/man/auditon.2#18 $
  30 .\"
  31 .Dd January 29, 2009
  32 .Dt AUDITON 2
  33 .Os
  34 .Sh NAME
  35 .Nm auditon
  36 .Nd "configure system audit parameters"
  37 .Sh SYNOPSIS
  38 .In bsm/audit.h
  39 .Ft int
  40 .Fn auditon "int cmd" "void *data" "u_int length"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn auditon
  44 system call is used to manipulate various audit control operations.
  45 The
  46 .Fa data
  47 argument
  48 should point to a structure whose type depends on the command.
  49 The
  50 .Fa length
  51 argument
  52 specifies the size of
  53 .Fa *data
  54 in bytes.
  55 The
  56 .Fa cmd
  57 argument
  58 may be any of the following:
  59 .Bl -tag -width ".It Dv A_GETPINFO_ADDR"
  60 .It Dv A_SETPOLICY
  61 Set audit policy flags.
  62 The
  63 .Fa data
  64 argument
  65 must point to a
  66 .Vt int
  67 value set to one or more the following audit
  68 policy control values bitwise OR'ed together:
  69 .Dv AUDIT_CNT ,
  70 .Dv AUDIT_AHLT ,
  71 .Dv AUDIT_ARGV ,
  72 and
  73 .Dv AUDIT_ARGE .
  74 If
  75 .Dv AUDIT_CNT is set, the system will continue even if it becomes low
  76 on space and discontinue logging events until the low space condition is
  77 remedied.
  78 If it is not set, audited events will block until the low space
  79 condition is remedied.
  80 Unaudited events, however, are unaffected.
  81 If
  82 .Dv AUDIT_AHLT is set, a
  83 .Xr panic 9
  84 if it cannot write an event to the global audit log file.
  85 If
  86 .Dv AUDIT_ARGV
  87 is set, then the argument list passed to the
  88 .Xr execve 2
  89 system call will be audited.  If
  90 .Dv AUDIT_ARGE
  91 is set, then the environment variables passed to the
  92 .Xr execve 2
  93 system call will be audited.  The default policy is none of the audit policy
  94 control flags set.
  95 .It Dv A_SETKAUDIT
  96 Set the host information.
  97 The
  98 .Fa data
  99 argument
 100 must point to a
 101 .Vt auditinfo_addr_t
 102 structure containing the host IP address information.
 103 After setting, audit records
 104 that are created as a result of kernel events will contain
 105 this information.
 106 .It Dv A_SETKMASK
 107 Set the kernel preselection masks (success and failure).
 108 The
 109 .Fa data
 110 argument
 111 must point to a
 112 .Vt au_mask_t
 113 structure containing the mask values as defined in
 114 .In bsm/audit.h .
 115 These masks are used for non-attributable audit event preselection.
 116 The field
 117 .Fa am_success
 118 specifies which classes of successful audit events are to be logged to the
 119 audit trail. The field
 120 .Fa am_failure
 121 specifies which classes of failed audit events are to be logged. The value of
 122 both fields is the bitwise OR'ing of the audit event classes specified in
 123 .Fa bsm/audit.h .
 124 The various audit classes are described more fully in
 125 .Xr audit_class 5 .
 126 .It Dv A_SETQCTRL
 127 Set kernel audit queue parameters.
 128 The
 129 .Fa data
 130 argument
 131 must point to a
 132 .Vt au_qctrl_t
 133 structure (defined in
 134 .In bsm/audit.h )
 135 containing the kernel audit queue control settings:
 136 .Fa aq_hiwater ,
 137 .Fa aq_lowater ,
 138 .Fa aq_bufsz ,
 139 .Fa aq_delay ,
 140 and
 141 .Fa aq_minfree .
 142 The field
 143 .Fa aq_hiwater
 144 defines the maximum number of audit record entries in the queue used to store
 145 the audit records ready for delivery to disk.
 146 New records are inserted at the tail of the queue and removed from the head.
 147 For new records which would exceed the
 148 high water mark, the calling thread is inserted into the wait queue, waiting
 149 for the audit queue to have enough space available as defined with the field
 150 .Fa aq_lowater .
 151 The field
 152 .Fa aq_bufsz
 153 defines the maximum length of the audit record that can be supplied with
 154 .Xr audit 2 .
 155 The field
 156 .Fa aq_delay
 157 is unused.
 158 The field
 159 .Fa aq_minfree
 160 specifies the minimum amount of free blocks on the disk device used to store
 161 audit records.
 162 If the value of free blocks falls below the configured
 163 minimum amount, the kernel informs the audit daemon about low disk space.
 164 The value is to be specified in percent of free file system blocks.
 165 A value of 0 results in a disabling of the check.
 166 The default and maximum values (default/maximum) for the
 167 audit queue control parameters are:
 168 .Pp
 169 .Bl -column aq_hiwater -offset indent -compact
 170 .It aq_hiwater Ta 100/10000 (audit records)
 171 .It aq_lowater Ta 10/aq_hiwater (audit records)
 172 .It aq_bufsz Ta 32767/1048576 (bytes)
 173 .It aq_delay Ta (Not currently used.)
 174 .El
 175 .It Dv A_SETSTAT
 176 Return
 177 .Er ENOSYS .
 178 (Not implemented.)
 179 .It Dv A_SETUMASK
 180 Return
 181 .Er ENOSYS .
 182 (Not implemented.)
 183 .It Dv A_SETSMASK
 184 Return
 185 .Er ENOSYS .
 186 (Not implemented.)
 187 .It Dv A_SETCOND
 188 Set the current auditing condition.
 189 The
 190 .Fa data
 191 argument
 192 must point to a
 193 .Vt int
 194 value containing the new
 195 audit condition, one of
 196 .Dv AUC_AUDITING ,
 197 .Dv AUC_NOAUDIT ,
 198 or
 199 .Dv AUC_DISABLED .
 200 If
 201 .Dv AUC_NOAUDIT
 202 is set, then auditing is temporarily suspended. If
 203 .Dv AUC_AUDITING
 204 is set, auditing is resumed. If
 205 .Dv AUC_DISABLED
 206 is set, the auditing system will
 207 shutdown, draining all audit records and closing out the audit trail file.
 208 .It Dv A_SETCLASS
 209 Set the event class preselection mask for an audit event.
 210 The
 211 .Fa data
 212 argument
 213 must point to a
 214 .Vt au_evclass_map_t
 215 structure containing the audit event and mask.
 216 The field
 217 .Fa ec_number
 218 is the audit event and
 219 .Fa ec_class
 220 is the audit class mask. See
 221 .Xr audit_event 5
 222 for more information on audit event to class mapping.
 223 .It Dv A_SETPMASK
 224 Set the preselection masks for a process.
 225 The
 226 .Fa data
 227 argument
 228 must point to a
 229 .Vt auditpinfo_t
 230 structure that contains the given process's audit
 231 preselection masks for both success and failure.
 232 The field
 233 .Fa ap_pid
 234 is the process id of the target process.
 235 The field
 236 .Fa ap_mask
 237 must point to a
 238 .Fa au_mask_t
 239 structure which holds the preselection masks as described in the
 240 .Dv A_SETKMASK
 241 section above.
 242 .It Dv A_SETFSIZE
 243 Set the maximum size of the audit log file.
 244 The
 245 .Fa data
 246 argument
 247 must point to a
 248 .Vt au_fstat_t
 249 structure with the
 250 .Va af_filesz
 251 field set to the maximum audit log file size.
 252 A value of 0
 253 indicates no limit to the size.
 254 .It Dv A_GETCLASS
 255 Return the event to class mapping for the designated audit event.
 256 The
 257 .Fa data
 258 argument
 259 must point to a
 260 .Vt au_evclass_map_t
 261 structure. See the
 262 .Dv A_SETCLASS
 263 section above for more information.
 264 .It Dv A_GETKAUDIT
 265 Get the current host information.
 266 The
 267 .Fa data
 268 argument
 269 must point to a
 270 .Vt auditinfo_addr_t
 271 structure.
 272 .It Dv A_GETPINFO
 273 Return the audit settings for a process.
 274 The
 275 .Fa data
 276 argument
 277 must point to a
 278 .Vt auditpinfo_t
 279 structure which will be set to contain
 280 .Fa ap_auid
 281 (the audit ID),
 282 .Fa ap_mask
 283 (the preselection mask),
 284 .Fa ap_termid
 285 (the terminal ID), and
 286 .Fa ap_asid
 287 (the audit session ID)
 288 of the given target process.
 289 The process ID of the target process is passed
 290 into the kernel using the
 291 .Fa ap_pid
 292 field.
 293 See the section
 294 .Dv A_SETPMASK
 295 above and
 296 .Xr getaudit 2
 297 for more information.
 298 .It Dv A_GETPINFO_ADDR
 299 Return the extended audit settings for a process.
 300 The
 301 .Fa data
 302 argument
 303 must point to a
 304 .Vt auditpinfo_addr_t
 305 structure which is similar to the
 306 .Vt auditpinfo_addr_t
 307 structure described above.
 308 The exception is the
 309 .Fa ap_termid
 310 (the terminal ID) field which points to a
 311 .Vt au_tid_addr_t
 312 structure can hold much a larger terminal address and an address type.
 313 The process ID of the target process is passed into the kernel using the
 314 .Fa ap_pid
 315 field.
 316 See the section
 317 .Dv A_SETPMASK
 318 above and
 319 .Xr getaudit 2
 320 for more information.
 321 .It Dv A_GETSINFO_ADDR
 322 Return the extended audit settings for a session.
 323 The
 324 .Fa data
 325 argument
 326 must point to a
 327 .Vt auditinfo_addr_t
 328 structure.
 329 The audit session ID of the target session is passed
 330 into the kernel using the
 331 .Fa ai_asid
 332 field.  See
 333 .Xr getaudit_addr 2
 334 for more information about the
 335 .Vt auditinfo_addr_t
 336 structure.
 337 .It Dv A_GETKMASK
 338 Return the current kernel preselection masks.
 339 The
 340 .Fa data
 341 argument
 342 must point to a
 343 .Vt au_mask_t
 344 structure which will be set to
 345 the current kernel preselection masks for non-attributable events.
 346 .It Dv A_GETPOLICY
 347 Return the current audit policy setting.
 348 The
 349 .Fa data
 350 argument
 351 must point to a
 352 .Vt int
 353 value which will be set to
 354 one of the current audit policy flags.
 355 The audit policy flags are
 356 described in the
 357 .Dv A_SETPOLICY
 358 section above.
 359 .It Dv A_GETQCTRL
 360 Return the current kernel audit queue control parameters.
 361 The
 362 .Fa data
 363 argument
 364 must point to a
 365 .Vt au_qctrl_t
 366 structure which will be set to the current
 367 kernel audit queue control parameters.
 368 See the
 369 .Dv A_SETQCTL
 370 section above for more information.
 371 .It Dv A_GETFSIZE
 372 Returns the maximum size of the audit log file.
 373 The
 374 .Fa data
 375 argument
 376 must point to a
 377 .Vt au_fstat_t
 378 structure.
 379 The
 380 .Va af_filesz
 381 field will be set to the maximum audit log file size.
 382 A value of 0 indicates no limit to the size.
 383 The
 384 .Va af_currsz
 385 field
 386 will be set to the current audit log file size.
 387 .It Dv A_GETCWD
 388 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 389 .\" Return the current working directory as stored in the audit subsystem.
 390 Return
 391 .Er ENOSYS .
 392 (Not implemented.)
 393 .It Dv A_GETCAR
 394 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 395 .\"Stores and returns the current active root as stored in the audit
 396 .\"subsystem.
 397 Return
 398 .Er ENOSYS .
 399 (Not implemented.)
 400 .It Dv A_GETSTAT
 401 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 402 .\"Return the statistics stored in the audit system.
 403 Return
 404 .Er ENOSYS .
 405 (Not implemented.)
 406 .It Dv A_GETCOND
 407 Return the current auditing condition.
 408 The
 409 .Fa data
 410 argument
 411 must point to a
 412 .Vt int
 413 value which will be set to
 414 the current audit condition, one of
 415 .Dv AUC_AUDITING ,
 416 .Dv AUC_NOAUDIT
 417 or
 418 .Dv AUC_DISABLED .
 419 See the
 420 .Dv A_SETCOND
 421 section above for more information.
 422 .It Dv A_SENDTRIGGER
 423 Send a trigger to the audit daemon.
 424 The
 425 .Fa data
 426 argument
 427 must point to a
 428 .Vt int
 429 value set to one of the acceptable
 430 trigger values:
 431 .Dv AUDIT_TRIGGER_LOW_SPACE
 432 (low disk space where the audit log resides),
 433 .Dv AUDIT_TRIGGER_OPEN_NEW
 434 (open a new audit log file),
 435 .Dv AUDIT_TRIGGER_READ_FILE
 436 (read the
 437 .Pa audit_control
 438 file),
 439 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
 440 (close the current log file and exit),
 441 .Dv AUDIT_TRIGGER_NO_SPACE
 442 (no disk space left for audit log file).
 443 .Dv AUDIT_TRIGGER_ROTATE_USER
 444 (request audit log file rotation).
 445 .Dv AUDIT_TRIGGER_INITIALIZE
 446 (initialize audit subsystem for Mac OS X only).
 447 or
 448 .Dv AUDIT_TRIGGER_EXPIRE_TRAILS
 449 (request audit log file expiration).
 450 .El
 451 .Sh RETURN VALUES
 452 .Rv -std
 453 .Sh ERRORS
 454 The
 455 .Fn auditon
 456 function will fail if:
 457 .Bl -tag -width Er
 458 .It Bq Er ENOSYS
 459 Returned by options not yet implemented.
 460 .It Bq Er EFAULT
 461 A failure occurred while data transferred to or from
 462 the kernel failed.
 463 .It Bq Er EINVAL
 464 Illegal argument was passed by a system call.
 465 .It Bq Er EPERM
 466 The process does not have sufficient permission to complete
 467 the operation.
 468 .El
 469 .Pp
 470 The
 471 .Dv A_SENDTRIGGER
 472 command is specific to the
 473 .Fx
 474 and Mac OS X implementations, and is not present in Solaris.
 475 .Sh SEE ALSO
 476 .Xr audit 2 ,
 477 .Xr auditctl 2 ,
 478 .Xr getaudit 2 ,
 479 .Xr getaudit_addr 2 ,
 480 .Xr getauid 2 ,
 481 .Xr setaudit 2 ,
 482 .Xr setaudit_addr 2 ,
 483 .Xr setauid 2 ,
 484 .Xr libbsm 3
 485 .Sh HISTORY
 486 The OpenBSM implementation was created by McAfee Research, the security
 487 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 488 It was subsequently adopted by the TrustedBSD Project as the foundation for
 489 the OpenBSM distribution.
 490 .Sh AUTHORS
 491 .An -nosplit
 492 This software was created by McAfee Research, the security research division
 493 of McAfee, Inc., under contract to Apple Computer Inc.
 494 Additional authors include
 495 .An Wayne Salamon ,
 496 .An Robert Watson ,
 497 and SPARTA Inc.
 498 .Pp
 499 The Basic Security Module (BSM) interface to audit records and audit event
 500 stream format were defined by Sun Microsystems.
 501 .Pp
 502 This manual page was written by
 503 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
 504 .An Robert Watson Aq rwatson@FreeBSD.org ,
 505 and
 506 .An Wayne Salamon Aq wsalamon@FreeBSD.org .