unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

auditon(2)                       System Calls                       auditon(2)



NAME
       auditon - manipulate auditing

SYNOPSIS
       cc [ flag... ] file... -lbsm -lsocket -lnsl -lintl [ library... ]
       #include <sys/param.h>
       #include <bsm/libbsm.h>

       int auditon(int cmd, caddr_t data, int length);

DESCRIPTION
       The  auditon() function performs various audit subsystem control opera-
       tions. The cmd argument designates the particular  audit  control  com-
       mand.  The  data  argument  is  a pointer to command-specific data. The
       length argument is the length in bytes of the command-specific data.

       The following commands are supported:

       A_GETCOND

           Return the system audit on/off/disabled condition  in  the  integer
           long  pointed to by data. The following values may be returned:

           AUC_AUDITING    Auditing has been turned on.




           AUC_DISABLED    Auditing system has not been enabled.



           AUC_NOAUDIT     Auditing has been turned off.



           AUC_NOSPACE     Auditing  has blocked due to lack of space in audit
                           partition.




       A_SETCOND

           Set the system's audit on/off condition to the value in  the  inte-
           ger  long pointed to by  data. The BSM audit module must be enabled
           by bsmconv(1M) before auditing can  be  turned  on.  The  following
           audit states may be set:

           AUC_AUDITING    Turns on audit record generation.




           AUC_NOAUDIT     Turns off audit record generation.




       A_GETCLASS

           Return  the  event to class mapping for the designated audit event.
           The  data argument points to the au_evclass_map structure  contain-
           ing  the  event number. The preselection class mask  is returned in
           the same structure.



       A_SETCLASS

           Set the event class preselection  mask  for  the  designated  audit
           event.  The   data  argument points to the au_evclass_map structure
           containing the event number and class mask.



       A_GETKMASK

           Return the kernel  preselection  mask  in  the   au_mask  structure
           pointed  to by data. This is the mask used to preselect non-attrib-
           utable audit events.



       A_SETKMASK

           Set the kernel preselection mask. The data argument points  to  the
           au_mask  structure containing the class mask. This is the mask used
           to preselect non-attributable audit events.



       A_GETPINFO

           Return the audit  ID, preselection mask,  terminal  ID  and   audit
           session  ID  of  the  specified process in the auditpinfo structure
           pointed to by data.

           Note that A_GETPINFO may fail if the termial ID contains a  network
           address longer than 32 bits. In this case, the A_GETPINFO_ADDR com-
           mand should be used.



       A_GETPINFO_ADDR

           Returns the audit ID, preselection mask,  terminal  ID  and   audit
           session  ID  of the specified process in the auditpinfo_addr struc-
           ture pointed to by data.



       A_SETPMASK

           Set the preselection mask of the specified process. The  data argu-
           ment  points to the  auditpinfo structure containing the process ID
           and the preselection mask. The other fields of  the  structure  are
           ignored and should be set to NULL.



       A_SETUMASK

           Set  the  preselection  mask  for  all processes with the specified
           audit ID. The data argument points to the auditinfo structure  con-
           taining the audit ID and the preselection mask. The other fields of
           the structure are ignored and should be set to NULL.



       A_SETSMASK

           Set the preselection mask for  all  processes  with  the  specified
           audit  session  ID.   The  data  argument  points to the  auditinfo
           structure containing the audit  session  ID  and  the  preselection
           mask.  The  other fields of the structure are ignored and should be
           set to NULL.



       A_GETQCTRL

           Return the kernel audit queue control parameters. These control the
           high  and low water marks of the number of audit records allowed in
           the audit queue. The high water mark is the maximum allowed  number
           of  undelivered  audit  records. The low water mark determines when
           threads blocked on the queue are wakened.  Another  parameter  con-
           trols the size of the data buffer used by auditsvc(2) to write data
           to the audit trail. There is also a parameter that specifies a max-
           imum  delay  before  data  is  attempted to be written to the audit
           trail. The audit queue parameters  are  returned  in  the  au_qctrl
           structure pointed to bydata.



       A_SETQCTRL

           Set the kernel audit queue control parameters as described above in
           the A_GETQCTRL command. The data argument points  to  the  au_qctrl
           structure  containing  the  audit  queue  control  parameters.  The
           default and maximum values 'A/B' for the audit queue control param-
           eters are:

           high water      100/10000 (audit records)




           low water       10/1024 (audit records)



           output buffer si1024/1048576 (bytes)



           delay           20/20000 (hundredths second)




       A_GETCWD

           Return  the  current working directory as kept by the audit subsys-
           tem. This is a path anchored on the real root, rather than  on  the
           active  root.  The  data argument points to a buffer into which the
           path is copied. The length argument is the length of the buffer.



       A_GETCAR

           Return the current active root as kept by the audit subsystem. This
           path may be used to anchor an absolute path for a path token gener-
           ated by an application. The data argument points to a  buffer  into
           which  the path is copied. The length argument is the length of the
           buffer.



       A_GETSTAT

           Return the system audit  statistics  in  the  audit_stat  structure
           pointed to by data.



       A_SETSTAT

           Reset  system  audit statistics values. The kernel statistics value
           is reset if the corresponding field  in  the  statistics  structure
           pointed to by the data argument is CLEAR_VAL.  Otherwise, the value
           is not changed.



       A_SETFSIZE

           Set the maximum size of an audit trail file. When  the  audit  file
           reaches  the  designated size, it is closed and a new file started.
           If the maximum size is unset, the audit  trail  file  generated  by
           auditsvc() will grow to the size of the file system. The data argu-
           ment points to the  au_fstat_t  structure  containing  the  maximum
           audit file size in bytes. The size can not be set less than 0x80000
           bytes.



       A_GETFSIZE

           Return the maximum audit file size and current  file  size  in  the
           au_fstat_t structure pointed to by the data argument.



       A_GETPOLICY

           Return  the  audit  policy  flags in the integer long pointed to by
           data.



       A_SETPOLICY

           Set the audit policy flags  to  the  values  in  the  integer  long
           pointed to by  data. The following policy flags are recognized:

           AUDIT_CNT

               Do not suspend processes when audit storage is full or inacces-
               sible. The default action is to suspend processes until storage
               becomes available.




           AUDIT_AHLT

               Halt  the  machine when a non-attributable audit record can not
               be delivered. The default action is  to  count  the  number  of
               events that could not be recorded.



           AUDIT_ARGV

               Include  in  the audit record the argument list for a member of
               the exec(2) family of functions. The default action is  not  to
               include this information.



           AUDIT_ARGE

               Include the environment variables for the  execv(2) function in
               the audit record. The default action is  not  to  include  this
               information.



           AUDIT_SEQ

               Add  a  sequence token to each audit record. The default action
               is not to include it.



           AUDIT_TRAIL

               Append a  trailer token  to  each  audit  record.  The  default
               action is not to include it.



           AUDIT_GROUP

               Include  the  supplementary  groups  list in audit records. The
               default action is not to include it.



           AUDIT_PATH

               Include secondary paths in audit records. Examples of secondary
               paths   are  dynamically  loaded shared library modules and the
               command shell  path for executable scripts. The default  action
               is to include only the primary path from the system call.



           AUDIT_PERZONE

               Enable  auditing for each local zone. If not set, audit records
               from all zones are collected in a single log accessible in  the
               global  zone  and certain auditconfig(1M) operations are disal-
               lowed. This policy can be set only from the global zone.



           AUDIT_ZONENAME

               Generate a zone ID token with each audit record.




RETURN VALUES
       Upon successful completion,  auditon()  returns  0.  Otherwise,  -1  is
       returned and errno is set to indicate the error.

ERRORS
       The auditon() function will fail if:

       E2BIG           The  length field for the command was too small to hold
                       the returned value.



       EFAULT          The copy of data to/from the kernel failed.



       EINVAL          One of the arguments was  illegal,  BSM  has  not  been
                       installed,  or  the operation is not valid from a local
                       zone.



       EPERM           The {PRIV_SYS_ACCT} privilege is not  asserted  in  the
                       effective set of the calling process.

                       Neither  the {PRIV_PROC_AUDIT} nor the {PRIV_SYS_AUDIT}
                       privilege is asserted in the effective set of the call-
                       ing  process and the command is one of A_GETCAR, A_GET-
                       CLASS, A_GETCOND, A_GETCWD, A_GETPINFO, A_GETPOLICY.



USAGE
       The auditon() function can be invoked only by processes with  appropri-
       ate privileges.

       The  use of auditon() to change system audit state is permitted only in
       the global zone. From any other zone auditon() returns  -1  with  errno
       set  to  EPERM.  The following auditon() commands are permitted only in
       the global zone: A_SETCOND, A_SETCLASS, A_SETKMASK, A_SETQCTRL,  A_SET-
       STAT,  A_SETFSIZE,  and  A_SETPOLICY.  All other auditon() commands are
       valid from any zone.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStable
       MT-LevelMT-Safe


SEE ALSO
       auditconfig(1M),  auditd(1M),   bsmconv(1M),   audit(2),   auditsvc(2),
       exec(2), audit.log(4), attributes(5), privileges(5)

NOTES
       The  functionality  described in this man page is available only if the
       Basic Security Module (BSM) has been enabled.  See bsmconv(1M) for more
       information.

       The  auditon  options  that modify or display process-based information
       are not affected by the "perzone" audit policy. Those that modify  sys-
       tem  audit  data such as the terminal ID and audit queue parameters are
       valid only in the global zone unless the "perzone" policy is set.   The
       "get" options for system audit data reflect the local zone if "perzone"
       is set; otherwise they reflects the settings of the global zone.



SunOS 5.10                        9 Jun 2004                        auditon(2)