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