contrib/openbsm/man/auditon.2

   1 .\"-
   2 .\" Copyright (c) 2005 Robert N. M. Watson
   3 .\" Copyright (c) 2005 Tom Rhodes
   4 .\" Copyright (c) 2005 Wayne J. Salamon
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $P4: //depot/projects/trustedbsd/openbsm/man/auditon.2#8 $
  29 .\"
  30 .Dd April 19, 2005
  31 .Dt AUDITON 2
  32 .Os
  33 .Sh NAME
  34 .Nm auditon
  35 .Nd "Configure system audit parameters"
  36 .Sh SYNOPSIS
  37 .In bsm/audit.h
  38 .Ft int
  39 .Fn auditon "int cmd" "void *data" "u_int length"
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 system call is used to manipulate various audit control operations.
  44 .Ft *data
  45 should point to a structure whose type depends on the command.
  46 .Ft length
  47 specifies the size of the
  48 .Em data
  49 in bytes.
  50 .Ft cmd
  51 may be any of the following:
  52 .Bl -tag -width ".It Dv A_GETPINFO_ADDR"
  53 .It Dv A_SETPOLICY
  54 Set audit policy flags.
  55 .Ft *data
  56 must point to a long value set to one of the audit
  57 policy control values defined in
  58 .Pa audit.h .
  59 Currently, only
  60 .Dv AUDIT_CNT
  61 and
  62 .Dv AUDIT_AHLT
  63 are implemented.
  64 In the
  65 .Dv AUDIT_CNT
  66 case, the action will continue regardless if
  67 an event will not be audited.
  68 In the
  69 .Dv AUDIT_AHLT
  70 case, a
  71 .Xr panic 9
  72 will result if an event will not be written to the
  73 audit log file.
  74 .It Dv A_SETKAUDIT
  75 Return
  76 .Er ENOSYS .
  77 .It Dv A_SETKMASK
  78 Set the kernel preselection masks (success and failure).
  79 .Ft *data
  80 must point to a
  81 .Ft au_mask_t
  82 structure containing the mask values.
  83 These masks are used for non-attributable audit event preselection.
  84 .It Dv A_SETQCTRL
  85 Set kernel audit queue parameters.
  86 .Ft *data
  87 must point to a
  88 .Ft au_qctrl_t
  89 structure containing the
  90 kernel audit queue control settings:
  91 .Va high water ,
  92 .Va low water ,
  93 .Va output buffer size ,
  94 .Va percent min free disk space ,
  95 and
  96 .Em delay
  97 (not currently used).
  98 .It Dv A_SETSTAT
  99 Return
 100 .Er ENOSYS .
 101 .It Dv A_SETUMASK
 102 Return
 103 .Er ENOSYS .
 104 .It Dv A_SETSMASK
 105 Return
 106 .Er ENOSYS .
 107 .It Dv A_SETCOND
 108 Set the current auditing condition.
 109 .Ft *data
 110 must point to a long value containing the new
 111 audit condition, one of
 112 .Dv AUC_AUDITING ,
 113 .Dv AUC_NOAUDIT ,
 114 or
 115 .Dv AUC_DISABLED .
 116 .It Dv A_SETCLASS
 117 Set the event class preselection mask for an audit event.
 118 .Ft *data
 119 must point to a
 120 .Ft au_evclass_map_t
 121 structure containing the audit event and mask.
 122 .It Dv A_SETPMASK
 123 Set the preselection masks for a process.
 124 .Ft *data
 125 must point to a
 126 .Ft auditpinfo_t
 127 structure that contains the given process's audit
 128 preselection masks for both success and failure.
 129 .It Dv A_SETFSIZE
 130 Set the maximum size of the audit log file.
 131 .Ft *data
 132 must point to a
 133 .Ft au_fstat_t
 134 structure with the
 135 .Ft af_filesz
 136 field set to the maximum audit log file size. A value of 0
 137 indicates no limit to the size.
 138 .It Dv A_SETKAUDIT
 139 Return
 140 .Er ENOSYS .
 141 .It Dv A_GETCLASS
 142 Return the event to class mapping for the designated audit event.
 143 .Ft *data
 144 must point to a
 145 .Ft au_evclass_map_t
 146 structure.
 147 .It Dv A_GETKAUDIT
 148 Return
 149 .Er ENOSYS .
 150 .It Dv A_GETPINFO
 151 Return the audit settings for a process.
 152 .Ft *data
 153 must point to a
 154 .Ft auditpinfo_t
 155 structure which will be set to contain
 156 the audit ID, preselection mask, terminal ID, and audit session
 157 ID of the given process.
 158 .It Dv A_GETPINFO_ADDR
 159 Return
 160 .Er ENOSYS .
 161 .It Dv A_GETKMASK
 162 Return the current kernel preselection masks.
 163 .Ft *data
 164 must point to a
 165 .Ft au_mask_t
 166 structure which will be set to
 167 the current kernel preselection masks for non-attributable events.
 168 .It Dv A_GETPOLICY
 169 Return the current audit policy setting.
 170 .Ft *data
 171 must point to a long value which will be set to
 172 one of the current audit policy flags.
 173 Currently, only
 174 .Dv AUDIT_CNT
 175 and
 176 .Dv AUDIT_AHLT
 177 are implemented.
 178 .It Dv A_GETQCTRL
 179 Return the current kernel audit queue control parameters.
 180 .Ft *data
 181 must point to a
 182 .Ft au_qctrl_t
 183 structure which will be set to the current
 184 kernel audit queue control parameters.
 185 .It Dv A_GETFSIZE
 186 Returns the maximum size of the audit log file.
 187 .Ft *data
 188 must point to a
 189 .Ft au_fstat_t
 190 structure. The
 191 .Ft af_filesz
 192 field will be set to the maximum audit log file size.
 193 A value of 0 indicates no limit to the size.
 194 The
 195 .Ft af_currsz
 196 will be set to the current audit log file size.
 197 .It Dv A_GETCWD
 198 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 199 .\" Return the current working directory as stored in the audit subsystem.
 200 Return
 201 .Er ENOSYS .
 202 .It Dv A_GETCAR
 203 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 204 .\"Stores and returns the current active root as stored in the audit
 205 .\"subsystem.
 206 Return
 207 .Er ENOSYS .
 208 .It Dv A_GETSTAT
 209 .\" [COMMENTED OUT]: Valid description, not yet implemented.
 210 .\"Return the statistics stored in the audit system.
 211 Return
 212 .Er ENOSYS .
 213 .It Dv A_GETCOND
 214 Return the current auditing condition.
 215 .Ft *data
 216 must point to a long value which will be set to
 217 the current audit condition, either
 218 .Dv AUC_AUDITING
 219 or
 220 .Dv AUC_NOAUDIT .
 221 .It Dv A_SENDTRIGGER
 222 Send a trigger to the audit daemon.
 223 .Fr *data
 224 must point to a long value set to one of the acceptable
 225 trigger values:
 226 .Dv AUDIT_TRIGGER_LOW_SPACE
 227 (low disk space where the audit log resides),
 228 .Dv AUDIT_TRIGGER_OPEN_NEW
 229 (open a new audit log file),
 230 .Dv AUDIT_TRIGGER_READ_FILE
 231 (read the
 232 .Pa audit_control
 233 file),
 234 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
 235 (close the current log file and exit),
 236 or
 237 .Dv AUDIT_TRIGGER_NO_SPACE
 238 (no disk space left for audit log file).
 239 .El
 240 .Sh RETURN VALUES
 241 .Rv -std
 242 .Sh ERRORS
 243 The
 244 .Fn auditon
 245 function will fail if:
 246 .Bl -tag -width Er
 247 .It Bq Er ENOSYS
 248 Returned by options not yet implemented.
 249 .It Bq Er EFAULT
 250 A failure occurred while data transferred to or from
 251 the kernel failed.
 252 .It Bq Er EINVAL
 253 Illegal argument was passed by a system call.
 254 .It Bq Er EPERM
 255 The process does not have sufficient permission to complete
 256 the operation.
 257 .El
 258 .Pp
 259 The
 260 .Dv A_SENDTRIGGER
 261 command is specific to the
 262 .Fx
 263 and Mac OS X implementations, and is not present in Solaris.
 264 .Sh SEE ALSO
 265 .Xr audit 2 ,
 266 .Xr auditctl 2 ,
 267 .Xr getauid 2 ,
 268 .Xr setauid 2 ,
 269 .Xr getaudit 2 ,
 270 .Xr setaudit 2 ,
 271 .Xr getaudit_addr 2 ,
 272 .Xr setaudit_addr 2 ,
 273 .Xr libbsm 3
 274 .Sh AUTHORS
 275 This software was created by McAfee Research, the security research division
 276 of McAfee, Inc., under contract to Apple Computer Inc.
 277 Additional authors include Wayne Salamon, Robert Watson, and SPARTA Inc.
 278 .Pp
 279 The Basic Security Module (BSM) interface to audit records and audit event
 280 stream format were defined by Sun Microsystems.
 281 .Pp
 282 This manual page was written by
 283 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
 284 .An Robert Watson Aq rwatson@FreeBSD.org ,
 285 and
 286 .An Wayne Salamon Aq wsalamon@FreeBSD.org .
 287 .Sh HISTORY
 288 The OpenBSM implementation was created by McAfee Research, the security
 289 division of McAfee Inc., under contract to Apple Computer Inc. in 2003.
 290 It was subsequently adopted by the TrustedBSD Project as the foundation for
 291 the OpenBSM distribution.