bsd/man/man2/auditon.2

   1 .\"
   2 .\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .Dd January 29, 2009
  24 .Dt AUDITON 2
  25 .Os
  26 .Sh NAME
  27 .Nm auditon
  28 .Nd "configure system audit parameters"
  29 .Sh SYNOPSIS
  30 .In bsm/audit.h
  31 .Ft int
  32 .Fn auditon "int cmd" "void *data" "u_int length"
  33 .Sh DESCRIPTION
  34 The
  35 .Fn auditon
  36 system call is used to manipulate various audit control operations.
  37 The
  38 .Fa data
  39 argument
  40 should point to a structure whose type depends on the command.
  41 The
  42 .Fa length
  43 argument
  44 specifies the size of
  45 .Fa *data
  46 in bytes.
  47 The
  48 .Fa cmd
  49 argument
  50 may be any of the following:
  51 .Bl -tag -width ".It Dv A_GETPINFO_ADDR"
  52 .It Dv A_SETPOLICY
  53 Set audit policy flags.
  54 The
  55 .Fa data
  56 argument
  57 must point to a
  58 .Vt int
  59 value set to one or more the following audit
  60 policy control values bitwise OR'ed together:
  61 .Dv AUDIT_CNT ,
  62 .Dv AUDIT_AHLT ,
  63 .Dv AUDIT_ARGV ,
  64 and
  65 .Dv AUDIT_ARGE .
  66 If
  67 .Dv AUDIT_CNT is set, the system will continue even if it becomes low
  68 on space and discontinue logging events until the low space condition is
  69 remedied.
  70 If it is not set, audited events will block until the low space
  71 condition is remedied.
  72 Unaudited events, however, are unaffected.
  73 If
  74 .Dv AUDIT_AHLT is set, a
  75 .Xr panic 9
  76 if it cannot write an event to the global audit log file.
  77 If
  78 .Dv AUDIT_ARGV
  79 is set, then the argument list passed to the
  80 .Xr execve 2
  81 system call will be audited.  If
  82 .Dv AUDIT_ARGE
  83 is set, then the environment variables passed to the
  84 .Xr execve 2
  85 system call will be audited.  The default policy is none of the audit policy
  86 control flags set.
  87 .It Dv A_SETKAUDIT
  88 Set the host information.
  89 The
  90 .Fa data
  91 argument
  92 must point to a
  93 .Vt auditinfo_addr_t
  94 structure containing the host IP address information.
  95 After setting, audit records
  96 that are created as a result of kernel events will contain
  97 this information.
  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 The default and maximum values (default/maximum) for the
 159 audit queue control parameters are:
 160 .Pp
 161 .Bl -column aq_hiwater -offset indent -compact
 162 .It aq_hiwater Ta 100/10000 (audit records)
 163 .It aq_lowater Ta 10/aq_hiwater (audit records)
 164 .It aq_bufsz Ta 32767/1048576 (bytes)
 165 .It aq_delay Ta (Not currently used.)
 166 .El
 167 .It Dv A_SETSTAT
 168 Return
 169 .Er ENOSYS .
 170 (Not implemented.)
 171 .It Dv A_SETUMASK
 172 Return
 173 .Er ENOSYS .
 174 (Not implemented.)
 175 .It Dv A_SETSMASK
 176 Return
 177 .Er ENOSYS .
 178 (Not implemented.)
 179 .It Dv A_SETCOND
 180 Set the current auditing condition.
 181 The
 182 .Fa data
 183 argument
 184 must point to a
 185 .Vt int
 186 value containing the new
 187 audit condition, one of
 188 .Dv AUC_AUDITING ,
 189 .Dv AUC_NOAUDIT ,
 190 or
 191 .Dv AUC_DISABLED .
 192 If
 193 .Dv AUC_NOAUDIT
 194 is set, then auditing is temporarily suspended. If
 195 .Dv AUC_AUDITING
 196 is set, auditing is resumed. If
 197 .Dv AUC_DISABLED
 198 is set, the auditing system will
 199 shutdown, draining all audit records and closing out the audit trail file.
 200 .It Dv A_SETCLASS
 201 Set the event class preselection mask for an audit event.
 202 The
 203 .Fa data
 204 argument
 205 must point to a
 206 .Vt au_evclass_map_t
 207 structure containing the audit event and mask.
 208 The field
 209 .Fa ec_number
 210 is the audit event and
 211 .Fa ec_class
 212 is the audit class mask. See
 213 .Xr audit_event 5
 214 for more information on audit event to class mapping.
 215 .It Dv A_SETPMASK
 216 Set the preselection masks for a process.
 217 The
 218 .Fa data
 219 argument
 220 must point to a
 221 .Vt auditpinfo_t
 222 structure that contains the given process's audit
 223 preselection masks for both success and failure.
 224 The field
 225 .Fa ap_pid
 226 is the process id of the target process.
 227 The field
 228 .Fa ap_mask
 229 must point to a
 230 .Fa au_mask_t
 231 structure which holds the preselection masks as described in the
 232 .Da A_SETKMASK
 233 section above.
 234 .It Dv A_SETFSIZE
 235 Set the maximum size of the audit log file.
 236 The
 237 .Fa data
 238 argument
 239 must point to a
 240 .Vt au_fstat_t
 241 structure with the
 242 .Va af_filesz
 243 field set to the maximum audit log file size.
 244 A value of 0
 245 indicates no limit to the size.
 246 .It Dv A_SETSFLAGS
 247 Set the audit sessions flags for the current session.
 248 The
 249 .Fa data
 250 argument must point to an
 251 .Vt au_asflgs_t
 252 value containing the new audit session flags.
 253 Audit session flags may be updated only according to local
 254 access control policy.
 255 .It Dv A_GETCLASS
 256 Return the event to class mapping for the designated audit event.
 257 The
 258 .Fa data
 259 argument
 260 must point to a
 261 .Vt au_evclass_map_t
 262 structure. See the
 263 .Dv A_SETCLASS
 264 section above for more information.
 265 .It Dv A_GETKAUDIT
 266 Get the current host information.
 267 The
 268 .Fa data
 269 argument
 270 must point to a
 271 .Vt auditinfo_addr_t
 272 structure.
 273 .It Dv A_GETPINFO
 274 Return the audit settings for a process.
 275 The
 276 .Fa data
 277 argument
 278 must point to a
 279 .Vt auditpinfo_t
 280 structure which will be set to contain
 281 .Fa ap_auid
 282 (the audit ID),
 283 .Fa ap_mask
 284 (the preselection mask),
 285 .Fa ap_termid
 286 (the terminal ID), and
 287 .Fa ap_asid
 288 (the audit session ID)
 289 of the given target process.
 290 The process ID of the target process is passed
 291 into the kernel using the
 292 .Fa ap_pid
 293 field.
 294 See the section
 295 .Dv A_SETPMASK
 296 above and
 297 .Xr getaudit 2
 298 for more information.
 299 .It Dv A_GETPINFO_ADDR
 300 Return the extended audit settings for a process.
 301 The
 302 .Fa data
 303 argument
 304 must point to a
 305 .Vt auditpinfo_addr_t
 306 structure which is similar to the
 307 .Vt auditpinfo_addr_t
 308 structure described above.
 309 The exception is the
 310 .Fa ap_termid
 311 (the terminal ID) field which points to a
 312 .Vt au_tid_addr_t
 313 structure can hold much a larger terminal address and an address type.
 314 The process ID of the target process is passed into the kernel using the
 315 .Fa ap_pid
 316 field.
 317 See the section
 318 .Dv A_SETPMASK
 319 above and
 320 .Xr getaudit 2
 321 for more information.
 322 .It Dv A_GETSINFO_ADDR
 323 Return the extended audit settings for a session.
 324 The
 325 .Fa data
 326 argument
 327 must point to a
 328 .Vt auditinfo_addr_t
 329 structure.
 330 The audit session ID of the target session is passed
 331 into the kernel using the
 332 .Fa ai_asid
 333 field.  See
 334 .Xr getaudit_addr 2
 335 for more information about the
 336 .Vt auditinfo_addr_t
 337 structure.
 338 .It Dv A_GETKMASK
 339 Return the current kernel preselection masks.
 340 The
 341 .Fa data
 342 argument
 343 must point to a
 344 .Vt au_mask_t
 345 structure which will be set to
 346 the current kernel preselection masks for non-attributable events.
 347 .It Dv A_GETPOLICY
 348 Return the current audit policy setting.
 349 The
 350 .Fa data
 351 argument
 352 must point to a
 353 .Vt int
 354 value which will be set to
 355 one of the current audit policy flags.
 356 The audit policy flags are
 357 described in the
 358 .Dv A_SETPOLICY
 359 section above.
 360 .It Dv A_GETQCTRL
 361 Return the current kernel audit queue control parameters.
 362 The
 363 .Fa data
 364 argument
 365 must point to a
 366 .Vt au_qctrl_t
 367 structure which will be set to the current
 368 kernel audit queue control parameters.
 369 See the
 370 .Dv A_SETQCTL
 371 section above for more information.
 372 .It Dv A_GETFSIZE
 373 Returns the maximum size of the audit log file.
 374 The
 375 .Fa data
 376 argument
 377 must point to a
 378 .Vt au_fstat_t
 379 structure.
 380 The
 381 .Va af_filesz
 382 field will be set to the maximum audit log file size.
 383 A value of 0 indicates no limit to the size.
 384 The
 385 .Va af_currsz
 386 field
 387 will be set to the current audit log file size.
 388 .It Dv A_GETSFLAGS
 389 Returns the audit session flags for the current session.
 390 The
 391 .Fa data
 392 argument must point to an
 393 .Vt au_asflgs_t
 394 value which will be set with the current session flags.
 395 .It Dv A_GETCWD
 396 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 397 .\" Return the current working directory as stored in the audit subsystem.
 398 Return
 399 .Er ENOSYS .
 400 (Not implemented.)
 401 .It Dv A_GETCAR
 402 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 403 .\"Stores and returns the current active root as stored in the audit
 404 .\"subsystem.
 405 Return
 406 .Er ENOSYS .
 407 (Not implemented.)
 408 .It Dv A_GETSTAT
 409 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 410 .\"Return the statistics stored in the audit system.
 411 Return
 412 .Er ENOSYS .
 413 (Not implemented.)
 414 .It Dv A_GETCOND
 415 Return the current auditing condition.
 416 The
 417 .Fa data
 418 argument
 419 must point to a
 420 .Vt int
 421 value which will be set to
 422 the current audit condition, one of
 423 .Dv AUC_AUDITING ,
 424 .Dv AUC_NOAUDIT
 425 or
 426 .Dv AUC_DISABLED .
 427 See the
 428 .Dv A_SETCOND
 429 section above for more information.
 430 .It Dv A_SENDTRIGGER
 431 Send a trigger to the audit daemon.
 432 The
 433 .Fa data
 434 argument
 435 must point to a
 436 .Vt int
 437 value set to one of the acceptable
 438 trigger values:
 439 .Dv AUDIT_TRIGGER_LOW_SPACE
 440 (low disk space where the audit log resides),
 441 .Dv AUDIT_TRIGGER_OPEN_NEW
 442 (open a new audit log file),
 443 .Dv AUDIT_TRIGGER_READ_FILE
 444 (read the
 445 .Pa audit_control
 446 file),
 447 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
 448 (close the current log file and exit),
 449 .Dv AUDIT_TRIGGER_NO_SPACE
 450 (no disk space left for audit log file).
 451 .Dv AUDIT_TRIGGER_ROTATE_USER
 452 (request audit log file rotation).
 453 .Dv AUDIT_TRIGGER_INITIALIZE
 454 (initialize audit subsystem for Mac OS X only).
 455 or
 456 .Dv AUDIT_TRIGGER_EXPIRE_TRAILS
 457 (request audit log file expiration).
 458 .El
 459 .Sh RETURN VALUES
 460 .Rv -std
 461 .Sh ERRORS
 462 The
 463 .Fn auditon
 464 function will fail if:
 465 .Bl -tag -width Er
 466 .It Bq Er ENOSYS
 467 Returned by options not yet implemented.
 468 .It Bq Er EFAULT
 469 A failure occurred while data transferred to or from
 470 the kernel failed.
 471 .It Bq Er EINVAL
 472 Illegal argument was passed by a system call.
 473 .It Bq Er EPERM
 474 The process does not have sufficient permission to complete
 475 the operation.
 476 .El
 477 .Pp
 478 The
 479 .Dv A_SENDTRIGGER
 480 command is specific to the
 481 .Fx
 482 and Mac OS X implementations, and is not present in Solaris.
 483 .Sh SEE ALSO
 484 .Xr audit 2 ,
 485 .Xr auditctl 2 ,
 486 .Xr getaudit 2 ,
 487 .Xr getaudit_addr 2 ,
 488 .Xr getauid 2 ,
 489 .Xr setaudit 2 ,
 490 .Xr setaudit_addr 2 ,
 491 .Xr setauid 2 ,
 492 .Xr libbsm 3
 493 .Sh HISTORY
 494 The OpenBSM implementation was created by McAfee Research, the security
 495 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 496 It was subsequently adopted by the TrustedBSD Project as the foundation for
 497 the OpenBSM distribution.
 498 .Sh AUTHORS
 499 .An -nosplit
 500 This software was created by McAfee Research, the security research division
 501 of McAfee, Inc., under contract to Apple Computer Inc.
 502 Additional authors include
 503 .An Wayne Salamon ,
 504 .An Robert Watson ,
 505 and SPARTA Inc.
 506 .Pp
 507 The Basic Security Module (BSM) interface to audit records and audit event
 508 stream format were defined by Sun Microsystems.
 509 .Pp
 510 This manual page was written by
 511 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
 512 .An Robert Watson Aq rwatson@FreeBSD.org ,
 513 and
 514 .An Wayne Salamon Aq wsalamon@FreeBSD.org .