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_GETCLASS
 247 Return the event to class mapping for the designated audit event.
 248 The
 249 .Fa data
 250 argument
 251 must point to a
 252 .Vt au_evclass_map_t
 253 structure. See the
 254 .Dv A_SETCLASS
 255 section above for more information.
 256 .It Dv A_GETKAUDIT
 257 Get the current host information.
 258 The
 259 .Fa data
 260 argument
 261 must point to a
 262 .Vt auditinfo_addr_t
 263 structure.
 264 .It Dv A_GETPINFO
 265 Return the audit settings for a process.
 266 The
 267 .Fa data
 268 argument
 269 must point to a
 270 .Vt auditpinfo_t
 271 structure which will be set to contain
 272 .Fa ap_auid
 273 (the audit ID),
 274 .Fa ap_mask
 275 (the preselection mask),
 276 .Fa ap_termid
 277 (the terminal ID), and
 278 .Fa ap_asid
 279 (the audit session ID)
 280 of the given target process.
 281 The process ID of the target process is passed
 282 into the kernel using the
 283 .Fa ap_pid
 284 field.
 285 See the section
 286 .Dv A_SETPMASK
 287 above and
 288 .Xr getaudit 2
 289 for more information.
 290 .It Dv A_GETPINFO_ADDR
 291 Return the extended audit settings for a process.
 292 The
 293 .Fa data
 294 argument
 295 must point to a
 296 .Vt auditpinfo_addr_t
 297 structure which is similar to the
 298 .Vt auditpinfo_addr_t
 299 structure described above.
 300 The exception is the
 301 .Fa ap_termid
 302 (the terminal ID) field which points to a
 303 .Vt au_tid_addr_t
 304 structure can hold much a larger terminal address and an address type.
 305 The process ID of the target process is passed into the kernel using the
 306 .Fa ap_pid
 307 field.
 308 See the section
 309 .Dv A_SETPMASK
 310 above and
 311 .Xr getaudit 2
 312 for more information.
 313 .It Dv A_GETSINFO_ADDR
 314 Return the extended audit settings for a session.
 315 The
 316 .Fa data
 317 argument
 318 must point to a
 319 .Vt auditinfo_addr_t
 320 structure.
 321 The audit session ID of the target session is passed
 322 into the kernel using the
 323 .Fa ai_asid
 324 field.  See
 325 .Xr getaudit_addr 2
 326 for more information about the
 327 .Vt auditinfo_addr_t
 328 structure.
 329 .It Dv A_GETKMASK
 330 Return the current kernel preselection masks.
 331 The
 332 .Fa data
 333 argument
 334 must point to a
 335 .Vt au_mask_t
 336 structure which will be set to
 337 the current kernel preselection masks for non-attributable events.
 338 .It Dv A_GETPOLICY
 339 Return the current audit policy setting.
 340 The
 341 .Fa data
 342 argument
 343 must point to a
 344 .Vt int
 345 value which will be set to
 346 one of the current audit policy flags.
 347 The audit policy flags are
 348 described in the
 349 .Dv A_SETPOLICY
 350 section above.
 351 .It Dv A_GETQCTRL
 352 Return the current kernel audit queue control parameters.
 353 The
 354 .Fa data
 355 argument
 356 must point to a
 357 .Vt au_qctrl_t
 358 structure which will be set to the current
 359 kernel audit queue control parameters.
 360 See the
 361 .Dv A_SETQCTL
 362 section above for more information.
 363 .It Dv A_GETFSIZE
 364 Returns the maximum size of the audit log file.
 365 The
 366 .Fa data
 367 argument
 368 must point to a
 369 .Vt au_fstat_t
 370 structure.
 371 The
 372 .Va af_filesz
 373 field will be set to the maximum audit log file size.
 374 A value of 0 indicates no limit to the size.
 375 The
 376 .Va af_currsz
 377 field
 378 will be set to the current audit log file size.
 379 .It Dv A_GETCWD
 380 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 381 .\" Return the current working directory as stored in the audit subsystem.
 382 Return
 383 .Er ENOSYS .
 384 (Not implemented.)
 385 .It Dv A_GETCAR
 386 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 387 .\"Stores and returns the current active root as stored in the audit
 388 .\"subsystem.
 389 Return
 390 .Er ENOSYS .
 391 (Not implemented.)
 392 .It Dv A_GETSTAT
 393 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 394 .\"Return the statistics stored in the audit system.
 395 Return
 396 .Er ENOSYS .
 397 (Not implemented.)
 398 .It Dv A_GETCOND
 399 Return the current auditing condition.
 400 The
 401 .Fa data
 402 argument
 403 must point to a
 404 .Vt int
 405 value which will be set to
 406 the current audit condition, one of
 407 .Dv AUC_AUDITING ,
 408 .Dv AUC_NOAUDIT
 409 or
 410 .Dv AUC_DISABLED .
 411 See the
 412 .Dv A_SETCOND
 413 section above for more information.
 414 .It Dv A_SENDTRIGGER
 415 Send a trigger to the audit daemon.
 416 The
 417 .Fa data
 418 argument
 419 must point to a
 420 .Vt int
 421 value set to one of the acceptable
 422 trigger values:
 423 .Dv AUDIT_TRIGGER_LOW_SPACE
 424 (low disk space where the audit log resides),
 425 .Dv AUDIT_TRIGGER_OPEN_NEW
 426 (open a new audit log file),
 427 .Dv AUDIT_TRIGGER_READ_FILE
 428 (read the
 429 .Pa audit_control
 430 file),
 431 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
 432 (close the current log file and exit),
 433 .Dv AUDIT_TRIGGER_NO_SPACE
 434 (no disk space left for audit log file).
 435 .Dv AUDIT_TRIGGER_ROTATE_USER
 436 (request audit log file rotation).
 437 .Dv AUDIT_TRIGGER_INITIALIZE
 438 (initialize audit subsystem for Mac OS X only).
 439 or
 440 .Dv AUDIT_TRIGGER_EXPIRE_TRAILS
 441 (request audit log file expiration).
 442 .El
 443 .Sh RETURN VALUES
 444 .Rv -std
 445 .Sh ERRORS
 446 The
 447 .Fn auditon
 448 function will fail if:
 449 .Bl -tag -width Er
 450 .It Bq Er ENOSYS
 451 Returned by options not yet implemented.
 452 .It Bq Er EFAULT
 453 A failure occurred while data transferred to or from
 454 the kernel failed.
 455 .It Bq Er EINVAL
 456 Illegal argument was passed by a system call.
 457 .It Bq Er EPERM
 458 The process does not have sufficient permission to complete
 459 the operation.
 460 .El
 461 .Pp
 462 The
 463 .Dv A_SENDTRIGGER
 464 command is specific to the
 465 .Fx
 466 and Mac OS X implementations, and is not present in Solaris.
 467 .Sh SEE ALSO
 468 .Xr audit 2 ,
 469 .Xr auditctl 2 ,
 470 .Xr getaudit 2 ,
 471 .Xr getaudit_addr 2 ,
 472 .Xr getauid 2 ,
 473 .Xr setaudit 2 ,
 474 .Xr setaudit_addr 2 ,
 475 .Xr setauid 2 ,
 476 .Xr libbsm 3
 477 .Sh HISTORY
 478 The OpenBSM implementation was created by McAfee Research, the security
 479 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 480 It was subsequently adopted by the TrustedBSD Project as the foundation for
 481 the OpenBSM distribution.
 482 .Sh AUTHORS
 483 .An -nosplit
 484 This software was created by McAfee Research, the security research division
 485 of McAfee, Inc., under contract to Apple Computer Inc.
 486 Additional authors include
 487 .An Wayne Salamon ,
 488 .An Robert Watson ,
 489 and SPARTA Inc.
 490 .Pp
 491 The Basic Security Module (BSM) interface to audit records and audit event
 492 stream format were defined by Sun Microsystems.
 493 .Pp
 494 This manual page was written by
 495 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
 496 .An Robert Watson Aq rwatson@FreeBSD.org ,
 497 and
 498 .An Wayne Salamon Aq wsalamon@FreeBSD.org .