usr/src/man/man2/auditon.2

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