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