bsd/man/man2/auditon.2

   1 .\"
   2 .\" Copyright (c) 2007 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 July 30, 2007
  24 .Dt AUDITON 2
  25 .Os Darwin
  26 .Sh NAME
  27 .Nm auditon
  28 .Nd configure the current audit parameters on the system
  29 .Sh SYNOPSIS
  30 .Fd #include <bsm/audit.h>
  31 .Ft int
  32 .Fn auditon "int cmd" "void * data" "int length"
  33 .Sh DESCRIPTION
  34 The
  35 .Fn auditon
  36 function manipulates various audit parameters. The
  37 .Fa data
  38 argument points to the appropriate structure from the header file.
  39 .Fa Length
  40 is the size of the
  41 .Fa data
  42 parameter in bytes. It will typically be the sizeof the the structure.
  43 .Sh PARAMETERS
  44 .Bl -tag -width Er
  45 .It A_GETPOLICY
  46 Get the current audit policy.
  47 .Fa Data
  48 should point to a long. The policy is the bitwise OR'ing of the
  49 appropriate flags from
  50 .Fa bsm/audit.h .
  51 If AUDIT_AHLT is set, the system will kernel panic if it cannot write to the
  52 global audit trail.  If AUDIT_CNT is not set and the system becomes low on
  53 space, audited events will block until the low space condition is remedied.
  54 Unaudited events are unaffected. The other policy flags are not implemented.
  55 .It A_SETPOLICY
  56 Set the current audit policy.
  57 .Fa Data
  58 should point to a long specifying the desired audit policy, as described in
  59 A_GETPOLICY.
  60 .It A_GETKMASK
  61 Get the current value of the audit preselection mask for non-attributable events.
  62 .Fa Data
  63 should point to an
  64 .Fa au_mask_t .
  65 The field
  66 .Fa am_success
  67 specifies which classes of successful audit events are to be logged to the
  68 audit trail. The field
  69 .Fa am_failure
  70 specifies which classes of failed audit events are to be logged. The value of
  71 both fields is the bitwise OR'ing of the event classes specified in
  72 .Fa bsm/audit.h .
  73 The various audit classes are described more fully in
  74 .Xr audit_class 5 .
  75 .It A_SETKMASK
  76 Set the current value of the audit preselection mask for non-attributable events.
  77 .Fa Data
  78 should point to an
  79 .Fa au_mask_t .
  80 The masks are defined as described in A_GETKMASK.
  81 .It A_GETQCTRL
  82 Get the current settings for the audit queue (specifying in kernel buffer size,
  83 percentage of free filesystem blocks, and limits to the number of audit records
  84 allowed).
  85 .Fa Data
  86 should point to an
  87 .Fa au_qctrl_t .
  88 .It A_SETQCTRL
  89 Set the current settings for the audit queue.
  90 .Fa Data
  91 should point to an
  92 .Fa au_qctrl_t .
  93 .\" The following are not yet implemented, but as mentioned in the header file.
  94 .\" .It A_GETCWD
  95 .\" .It A_GETCAR
  96 .\" .It A_GETSTAT
  97 .\" .It A_SETSTAT
  98 .\" .It A_SETUMASK
  99 .\" .It A_SETSMASK
 100 .It A_GETCOND
 101 Gets the current condition of the auditing subsystem. If the value is
 102 AUC_AUDITING, then the audit implementation is currently running. If the
 103 value is AUC_NOAUDIT then the audit implementation is currently turned off.
 104 .Fa Data
 105 should point to a long.
 106 .It A_SETCOND
 107 Sets the condition of the auditing subsystem. If AUC_NOAUDIT is set, then
 108 auditing is temporarily suspended. If AUC_AUDITING is set, auditing is resumed.
 109 If AUC_DISABLED is set, the auditing system will shutdown, draining all audit
 110 records and closing out the audit trail file.
 111 To re-enable auditing, a call to
 112 .Fa auditctl
 113 is required in addition to setting the condition to AUC_AUDITING.
 114 .Fa Data
 115 should point to a long.
 116 .It A_GETCLASS
 117 Returns the audit class for the specified audit event.
 118 .Fa Data
 119 should point to a
 120 .Fa au_evclassmap_t .
 121 .It A_SETCLASS
 122 Sets the audit class for the specified audit event.
 123 .Fa Data
 124 should point to a
 125 .Fa au_evclassmap_t .
 126 .It A_GETPINFO
 127 Returns the audit information stored in the credential for the current process.
 128 .Fa Data
 129 should point to a
 130 .Fa auditpinfo_t .
 131 .It A_SETPMASK
 132 Sets the audit settings for a process. The audit user ID, preselection masks
 133 for both success and failure, and terminal IDs must be set.
 134 .Fa Data
 135 should point to a
 136 .Fa auditpinfo_t
 137 struct.
 138 .It A_SETFSIZE
 139 Set the limit on audit trail file size. File size is in bytes. The file size
 140 specified is treated as an advisory limit. The system will make a best effort
 141 attempt to rotate log files before they exceed the requested maximum size, but
 142 makes no guarantees on log file size
 143 .Fa Data
 144 should point to a
 145 .Fa au_fstat_t
 146 struct. The
 147 .Fa af_filesz
 148 field is used to specify the new file size, which must be greater than
 149 MIN_AUDIT_FILE_SIZE. A value of 0 indicates no limit on the audit trail's size. The
 150 .Fa af_currsz
 151 field is ignored. A errno value of EINVAL indicates a maximum file size that is
 152 too small.
 153 .It A_GETFSIZE
 154 Return the maximum allowable size of the audit trail, and the current size of
 155 the audit trail.
 156 .Fa Data
 157 should point to a
 158 .Fa au_fstat_t
 159 struct.
 160 .It A_GETPINFO_ADDR
 161 Not implemented, returns ENOSYS.
 162 .It A_GETKAUDIT
 163 Not implemented, returns ENOSYS.
 164 .It A_SETKAUDIT
 165 Not implemented, returns ENOSYS.
 166 .El
 167 .Sh RETURN VALUES
 168 Upon successful completion a value of 0 is returned.
 169 Otherwise, a value of -1 is returned and
 170 .Va errno
 171 is set to indicate the error.
 172 .Sh ERRORS
 173 .Bl -tag -width Er
 174 Errors are specific to the operation requested. In addition, rhe
 175 .Fn auditon
 176 system call will fail if:
 177 .\" ===========
 178 .It Bq Er EINVAL
 179 .Fa Length
 180 is less than or equal to zero, or if it is greater than any of the expected structures.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr audit 2 ,
 184 .Xr auditctl 2 ,
 185 .Xr getauid 2 ,
 186 .Xr setauid 2 ,
 187 .Xr getaudit 2 ,
 188 .Xr setaudit 2 ,
 189 .Xr getaudit_addr 2 ,
 190 .Xr setaudit_addr 2 ,
 191 .Xr audit_class 5
 192 .Sh HISTORY
 193 The
 194 .Fn auditon
 195 function call first appeared in Mac OS X 10.3 (Panther).