usr/src/man/man2/auditon.2

   1 '\" te
   2 .\" Copyright (c) 2017 Peter Tribble
   3 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH AUDITON 2 "Mar 6, 2017"
   8 .SH NAME
   9 auditon \- manipulate auditing
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... \fB-lbsm\fR \fB -lsocket \fR \fB -lnsl \fR [ \fIlibrary\fR... ]
  14 #include <sys/param.h>
  15 #include <bsm/libbsm.h>
  16
  17 \fBint\fR \fBauditon\fR(\fBint\fR \fIcmd\fR, \fBcaddr_t\fR \fIdata\fR, \fBint\fR \fIlength\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .LP
  22 The \fBauditon()\fR function performs various audit subsystem control
  23 operations. The \fIcmd\fR argument designates the particular audit control
  24 command. The \fIdata\fR argument is a pointer to command-specific data. The
  25 \fIlength\fR argument is the length in bytes of the command-specific data.
  26 .sp
  27 .LP
  28 The following commands are supported:
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fBA_GETCOND\fR\fR
  33 .ad
  34 .sp .6
  35 .RS 4n
  36 Return the system audit condition in the integer pointed to by
  37 \fIdata\fR. The following values can be returned:
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fBAUC_AUDITING\fR\fR
  42 .ad
  43 .RS 16n
  44 Audit daemon is active.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fBAUC_INIT_AUDIT\fR\fR
  51 .ad
  52 .RS 16n
  53 Audit is ready but auditd has not run.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBAUC_NOAUDIT\fR\fR
  60 .ad
  61 .RS 16n
  62 Audit daemon is not active.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBAUC_NOSPACE\fR\fR
  69 .ad
  70 .RS 16n
  71 Auditing has blocked due to lack of space in audit partition.
  72 .RE
  73
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBA_SETCOND\fR\fR
  80 .ad
  81 .sp .6
  82 .RS 4n
  83 Set the system's audit on/off condition to the value in the integer pointed to
  84 by \fIdata\fR. The following audit states can be set:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBAUC_AUDITING\fR\fR
  89 .ad
  90 .RS 16n
  91 Turns on audit record generation.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBAUC_NOAUDIT\fR\fR
  98 .ad
  99 .RS 16n
 100 Turns off audit record generation.
 101 .RE
 102
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBA_GETCLASS\fR\fR
 109 .ad
 110 .sp .6
 111 .RS 4n
 112 Return the event to class mapping for the designated audit event. The
 113 \fIdata\fR argument points to the \fBau_evclass_map\fR structure containing the
 114 event number. The preselection class mask is returned in the same structure.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBA_SETCLASS\fR\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Set the event class preselection mask for the designated audit event. The
 125 \fIdata\fR argument points to the \fBau_evclass_map\fR structure containing the
 126 event number and class mask.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBA_GETKMASK\fR\fR
 133 .ad
 134 .sp .6
 135 .RS 4n
 136 Return the kernel preselection mask in the \fBau_mask\fR structure pointed to
 137 by \fIdata\fR. This is the mask used to preselect non-attributable audit
 138 events.
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBA_SETKMASK\fR\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 Set the kernel preselection mask. The \fIdata\fR argument points to the
 149 \fBau_mask\fR structure containing the class mask. This is the mask used to
 150 preselect non-attributable audit events.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBA_GETPINFO\fR\fR
 157 .ad
 158 .sp .6
 159 .RS 4n
 160 Return the audit ID, preselection mask, terminal ID and audit session ID of the
 161 specified process in the \fBauditpinfo\fR structure pointed to by \fIdata\fR.
 162 .sp
 163 Note that \fBA_GETPINFO\fR can fail if the terminal ID contains a network
 164 address longer than 32 bits. In this case, the \fBA_GETPINFO_ADDR\fR command
 165 should be used.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBA_GETPINFO_ADDR\fR\fR
 172 .ad
 173 .sp .6
 174 .RS 4n
 175 Returns the audit ID, preselection mask, terminal ID and audit session ID of
 176 the specified process in the \fBauditpinfo_addr\fR structure pointed to by
 177 \fIdata\fR.
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBA_SETPMASK\fR\fR
 184 .ad
 185 .sp .6
 186 .RS 4n
 187 Set the preselection mask of the specified process. The \fIdata\fR argument
 188 points to the \fBauditpinfo\fR structure containing the process ID and the
 189 preselection mask. The other fields of the structure are ignored and should be
 190 set to \fINULL\fR.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBA_SETUMASK\fR\fR
 197 .ad
 198 .sp .6
 199 .RS 4n
 200 Set the preselection mask for all processes with the specified audit ID. The
 201 \fIdata\fR argument points to the \fBauditinfo\fR structure containing the
 202 audit ID and the preselection mask. The other fields of the structure are
 203 ignored and should be set to \fINULL\fR.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBA_SETSMASK\fR\fR
 210 .ad
 211 .sp .6
 212 .RS 4n
 213 Set the preselection mask for all processes with the specified audit session
 214 ID. The \fIdata\fR argument points to the \fBauditinfo\fR structure containing
 215 the audit session \fBID\fR and the preselection mask. The other fields of the
 216 structure are ignored and should be set to \fINULL.\fR
 217 .RE
 218
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fBA_GETQCTRL\fR\fR
 223 .ad
 224 .sp .6
 225 .RS 4n
 226 Return the kernel audit queue control parameters. These control the high and
 227 low water marks of the number of audit records allowed in the audit queue. The
 228 high water mark is the maximum allowed number of undelivered audit records. The
 229 low water mark determines when threads blocked on the queue are wakened.
 230 Another parameter controls the size of the data buffer used to write data to
 231 the audit trail. There is also a parameter that specifies a maximum delay
 232 before data is attempted to be written to the audit trail. The audit queue
 233 parameters are returned in the \fBau_qctrl\fR structure pointed to by
 234 \fIdata\fR.
 235 .RE
 236
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBA_SETQCTRL\fR\fR
 241 .ad
 242 .sp .6
 243 .RS 4n
 244 Set the kernel audit queue control parameters as described above in the
 245 \fBA_GETQCTRL\fR command. The \fIdata\fR argument points to the \fBau_qctrl\fR
 246 structure containing the audit queue control parameters. The default and
 247 maximum values 'A/B' for the audit queue control parameters are:
 248 .sp
 249 .ne 2
 250 .na
 251 \fBhigh water\fR
 252 .ad
 253 .RS 22n
 254 \fB100/10000\fR (audit records)
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fBlow water\fR
 261 .ad
 262 .RS 22n
 263 \fB10/1024\fR (audit records)
 264 .RE
 265
 266 .sp
 267 .ne 2
 268 .na
 269 \fBoutput buffer size\fR
 270 .ad
 271 .RS 22n
 272 \fB1024/1048576\fR (bytes)
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fBdelay\fR
 279 .ad
 280 .RS 22n
 281 \fB20/20000\fR (hundredths second)
 282 .RE
 283
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBA_GETCWD\fR\fR
 290 .ad
 291 .sp .6
 292 .RS 4n
 293 Return the current working directory as kept by the audit subsystem. This is a
 294 path anchored on the real root, rather than on the active root. The \fIdata\fR
 295 argument points to a buffer into which the path is copied. The \fIlength\fR
 296 argument is the length of the buffer.
 297 .RE
 298
 299 .sp
 300 .ne 2
 301 .na
 302 \fB\fBA_GETCAR\fR\fR
 303 .ad
 304 .sp .6
 305 .RS 4n
 306 Return the current active root as kept by the audit subsystem. This path can be
 307 used to anchor an absolute path for a path token generated by an application.
 308 The \fIdata\fR argument points to a buffer into which the path is copied. The
 309 \fIlength\fR argument is the length of the buffer.
 310 .RE
 311
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBA_GETSTAT\fR\fR
 316 .ad
 317 .sp .6
 318 .RS 4n
 319 Return the system audit statistics in the \fBaudit_stat\fR structure pointed to
 320 by \fIdata\fR.
 321 .RE
 322
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fBA_SETSTAT\fR\fR
 327 .ad
 328 .sp .6
 329 .RS 4n
 330 Reset system audit statistics values. The kernel statistics value is reset if
 331 the corresponding field in the statistics structure pointed to by the
 332 \fIdata\fR argument is \fBCLEAR_VAL\fR. Otherwise, the value is not changed.
 333 .RE
 334
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fBA_GETPOLICY\fR\fR
 339 .ad
 340 .sp .6
 341 .RS 4n
 342 Return the audit policy flags in the integer pointed to by \fIdata\fR.
 343 .RE
 344
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBA_SETPOLICY\fR\fR
 349 .ad
 350 .sp .6
 351 .RS 4n
 352 Set the audit policy flags to the values in the integer pointed to by
 353 \fIdata\fR. The following policy flags are recognized:
 354 .sp
 355 .ne 2
 356 .na
 357 \fB\fBAUDIT_CNT\fR\fR
 358 .ad
 359 .sp .6
 360 .RS 4n
 361 Do not suspend processes when audit storage is full or inaccessible. The
 362 default action is to suspend processes until storage becomes available.
 363 .RE
 364
 365 .sp
 366 .ne 2
 367 .na
 368 \fB\fBAUDIT_AHLT\fR\fR
 369 .ad
 370 .sp .6
 371 .RS 4n
 372 Halt the machine when a non-attributable audit record can not be delivered. The
 373 default action is to count the number of events that could not be recorded.
 374 .RE
 375
 376 .sp
 377 .ne 2
 378 .na
 379 \fB\fBAUDIT_ARGV\fR\fR
 380 .ad
 381 .sp .6
 382 .RS 4n
 383 Include in the audit record the argument list for a member of the \fBexec\fR(2)
 384 family of functions. The default action is not to include this information.
 385 .RE
 386
 387 .sp
 388 .ne 2
 389 .na
 390 \fB\fBAUDIT_ARGE\fR\fR
 391 .ad
 392 .sp .6
 393 .RS 4n
 394 Include the environment variables for the \fBexecv\fR(2) function in the audit
 395 record. The default action is not to include this information.
 396 .RE
 397
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fBAUDIT_SEQ\fR\fR
 402 .ad
 403 .sp .6
 404 .RS 4n
 405 Add a \fIsequence\fR token to each audit record. The default action is not to
 406 include it.
 407 .RE
 408
 409 .sp
 410 .ne 2
 411 .na
 412 \fB\fBAUDIT_TRAIL\fR\fR
 413 .ad
 414 .sp .6
 415 .RS 4n
 416 Append a \fItrailer\fR token to each audit record. The default action is not to
 417 include it.
 418 .RE
 419
 420 .sp
 421 .ne 2
 422 .na
 423 \fB\fBAUDIT_GROUP\fR\fR
 424 .ad
 425 .sp .6
 426 .RS 4n
 427 Include the supplementary groups list in audit records. The default action is
 428 not to include it.
 429 .RE
 430
 431 .sp
 432 .ne 2
 433 .na
 434 \fB\fBAUDIT_PATH\fR\fR
 435 .ad
 436 .sp .6
 437 .RS 4n
 438 Include secondary paths in audit records. Examples of secondary paths are
 439 dynamically loaded shared library modules and the command shell path for
 440 executable scripts. The default action is to include only the primary path from
 441 the system call.
 442 .RE
 443
 444 .sp
 445 .ne 2
 446 .na
 447 \fB\fBAUDIT_WINDATA_DOWN\fR\fR
 448 .ad
 449 .sp .6
 450 .RS 4n
 451 Include in an audit record any downgraded data moved between windows. This
 452 policy is available only if the system is configured with Trusted Extensions.
 453 By default, this information is not included.
 454 .RE
 455
 456 .sp
 457 .ne 2
 458 .na
 459 \fB\fBAUDIT_WINDATA_UP\fR\fR
 460 .ad
 461 .sp .6
 462 .RS 4n
 463 Include in an audit record any upgraded data moved between windows. This policy
 464 is available only if the system is configured with Trusted Extensions. By
 465 default, this information is not included.
 466 .RE
 467
 468 .sp
 469 .ne 2
 470 .na
 471 \fB\fBAUDIT_PERZONE\fR\fR
 472 .ad
 473 .sp .6
 474 .RS 4n
 475 Enable auditing for each local zone. If not set, audit records from all zones
 476 are collected in a single log accessible in the global zone and certain
 477 \fBauditconfig\fR(1M) operations are disallowed. This policy can be set only
 478 from the global zone.
 479 .RE
 480
 481 .sp
 482 .ne 2
 483 .na
 484 \fB\fBAUDIT_ZONENAME\fR\fR
 485 .ad
 486 .sp .6
 487 .RS 4n
 488 Generate a zone ID token with each audit record.
 489 .RE
 490
 491 .RE
 492
 493 .SH RETURN VALUES
 494 .LP
 495 Upon successful completion, \fBauditon()\fR returns \fB0\fR. Otherwise, \(mi1
 496 is returned and \fBerrno\fR is set to indicate the error.
 497 .SH ERRORS
 498 .LP
 499 The \fBauditon()\fR function will fail if:
 500 .sp
 501 .ne 2
 502 .na
 503 \fB\fBE2BIG\fR\fR
 504 .ad
 505 .RS 10n
 506 The \fIlength\fR field for the command was too small to hold the returned
 507 value.
 508 .RE
 509
 510 .sp
 511 .ne 2
 512 .na
 513 \fB\fBEFAULT\fR\fR
 514 .ad
 515 .RS 10n
 516 The copy of data to/from the kernel failed.
 517 .RE
 518
 519 .sp
 520 .ne 2
 521 .na
 522 \fB\fBEINVAL\fR\fR
 523 .ad
 524 .RS 10n
 525 One of the arguments was illegal, Audit has not been installed, or the
 526 operation is not valid from a local zone.
 527 .RE
 528
 529 .sp
 530 .ne 2
 531 .na
 532 \fB\fBEPERM\fR\fR
 533 .ad
 534 .RS 10n
 535 The {\fBPRIV_SYS_AUDIT\fR} privilege is not asserted in the effective set of
 536 the calling process.
 537 .sp
 538 Neither the {\fBPRIV_PROC_AUDIT\fR} nor the {\fBPRIV_SYS_AUDIT\fR} privilege is
 539 asserted in the effective set of the calling process and the command is one of
 540 \fBA_GETCAR\fR, \fBA_GETCLASS\fR, \fBA_GETCOND\fR, \fBA_GETCWD\fR,
 541 \fBA_GETPINFO\fR, \fBA_GETPOLICY\fR.
 542 .RE
 543
 544 .SH USAGE
 545 .LP
 546 The \fBauditon()\fR function can be invoked only by processes with appropriate
 547 privileges.
 548 .sp
 549 .LP
 550 The use of \fBauditon()\fR to change system audit state is permitted only in
 551 the global zone. From any other zone \fBauditon()\fR returns \(mi1 with
 552 \fBerrno\fR set to \fBEPERM\fR. The following \fBauditon()\fR commands are
 553 permitted only in the global zone: \fBA_SETCOND\fR, \fBA_SETCLASS\fR,
 554 \fBA_SETKMASK\fR, \fBA_SETQCTRL\fR, \fBA_SETSTAT\fR, \fBA_SETFSIZE\fR, and
 555 \fBA_SETPOLICY\fR. All other \fBauditon()\fR commands are valid from any zone.
 556 .SH ATTRIBUTES
 557 .LP
 558 See \fBattributes\fR(5) for descriptions of the following attributes:
 559 .sp
 560
 561 .sp
 562 .TS
 563 box;
 564 c | c
 565 l | l .
 566 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 567 _
 568 Interface Stability     Committed
 569 _
 570 MT-Level        MT-Safe
 571 .TE
 572
 573 .SH SEE ALSO
 574 .LP
 575 \fBauditconfig\fR(1M), \fBauditd\fR(1M), \fBaudit\fR(2),
 576 \fBexec\fR(2), \fBaudit.log\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5)
 577 .SH NOTES
 578 .LP
 579 The auditon options that modify or display process-based information are not
 580 affected by the "perzone" audit policy. Those that modify system audit data
 581 such as the terminal ID and audit queue parameters are valid only in the global
 582 zone unless the "perzone" policy is set. The "get" options for system audit
 583 data reflect the local zone if "perzone" is set; otherwise they reflects the
 584 settings of the global zone.