Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
AUDITPIPE(4)           FreeBSD Kernel Interfaces Manual           AUDITPIPE(4)

NAME
     auditpipe - pseudo-device for live audit event tracking

SYNOPSIS
     options AUDIT

DESCRIPTION
     While audit trail files generated with audit(4) and maintained by
     auditd(8) provide a reliable long-term store for audit log information,
     current log files are owned by the audit daemon until terminated making
     them somewhat unwieldy for live monitoring applications such as host-
     based intrusion detection.  For example, the log may be cycled and new
     records written to a new file without notice to applications that may be
     accessing the file.

     The audit facility provides an audit pipe facility for applications
     requiring direct access to live BSM audit data for the purposes of real-
     time monitoring.  Audit pipes are available via a clonable special
     device, /dev/auditpipe, subject to the permissions on the device node,
     and provide a "tee" of the audit event stream.  As the device is
     clonable, more than one instance of the device may be opened at a time;
     each device instance will provide independent access to all records.

     The audit pipe device provides discrete BSM audit records; if the read
     buffer passed by the application is too small to hold the next record in
     the sequence, it will be dropped.  Unlike audit data written to the audit
     trail, the reliability of record delivery is not guaranteed.  In
     particular, when an audit pipe queue fills, records will be dropped.
     Audit pipe devices are blocking by default, but support non-blocking I/O,
     asynchronous I/O using SIGIO, and polled operation via select(2) and
     poll(2).

     Applications may choose to track the global audit trail, or configure
     local preselection parameters independent of the global audit trail
     parameters.

   Audit Pipe Queue Ioctls
     The following ioctls retrieve and set various audit pipe record queue
     properties:

     AUDITPIPE_GET_QLEN              Query the current number of records
                                     available for reading on the pipe.

     AUDITPIPE_GET_QLIMIT            Retrieve the current maximum number of
                                     records that may be queued for reading on
                                     the pipe.

     AUDITPIPE_SET_QLIMIT            Set the current maximum number of records
                                     that may be queued for reading on the
                                     pipe.  The new limit must fall between
                                     the queue limit minimum and queue limit
                                     maximum queryable using the following two
                                     ioctls.

     AUDITPIPE_GET_QLIMIT_MIN        Query the lowest possible maximum number
                                     of records that may be queued for reading
                                     on the pipe.

     AUDITPIPE_GET_QLIMIT_MAX        Query the highest possible maximum number
                                     of records that may be queued for reading
                                     on the pipe.

     AUDITPIPE_FLUSH                 Flush all outstanding records on the
                                     audit pipe; useful after setting initial
                                     preselection properties to delete records
                                     queued during the configuration process
                                     which may not match the interests of the
                                     user process.

     AUDITPIPE_GET_MAXAUDITDATA      Query the maximum size of an audit
                                     record, which is a useful minimum size
                                     for a user space buffer intended to hold
                                     audit records read from the audit pipe.

   Audit Pipe Preselection Mode Ioctls
     By default, the audit pipe facility configures pipes to present records
     matched by the system-wide audit trail, configured by auditd(8).
     However, the preselection mechanism for audit pipes can be configured
     using alternative criteria, including pipe-local flags and naflags
     settings, as well as auid-specific selection masks.  This allows
     applications to track events not captured in the global audit trail, as
     well as limit records presented to those of specific interest to the
     application.

     The following ioctls configure the preselection mode on an audit pipe:

     AUDITPIPE_GET_PRESELECT_MODE      Return the current preselect mode on
                                       the audit pipe.  The ioctl argument
                                       should be of type int.

     AUDITPIPE_SET_PRESELECT_MODE      Set the current preselection mode on
                                       the audit pipe.  The ioctl argument
                                       should be of type int.

     Possible preselection mode values are:

     AUDITPIPE_PRESELECT_MODE_TRAIL      Use the global audit trail
                                         preselection parameters to select
                                         records for the audit pipe.

     AUDITPIPE_PRESELECT_MODE_LOCAL      Use local audit pipe preselection;
                                         this model is similar to the global
                                         audit trail configuration model,
                                         consisting of global flags and
                                         naflags parameters, as well as a set
                                         of per-auid masks.  These parameters
                                         are configured using further ioctls.

     After changing the audit pipe preselection mode, records selected under
     earlier preselection configuration may still be in the audit pipe queue.
     The application may flush the current record queue after changing the
     configuration to remove possibly undesired records.

   Audit Pipe Local Preselection Mode Ioctls
     The following ioctls configure the preselection parameters used when an
     audit pipe is configured for the AUDITPIPE_PRESELECT_MODE_LOCAL
     preselection mode.

     AUDITPIPE_GET_PRESELECT_FLAGS        Retrieve the current default
                                          preselection flags for attributable
                                          events on the pipe.  These flags
                                          correspond to the flags field in
                                          audit_control(5).  The ioctl
                                          argument should be of type u_int.

     AUDITPIPE_SET_PRESELECT_FLAGS        Set the current default preselection
                                          flags for attributable events on the
                                          pipe.  These flags correspond to the
                                          flags field in audit_control(5).
                                          The ioctl argument should be of type
                                          u_int.

     AUDITPIPE_GET_PRESELECT_NAFLAGS      Retrieve the current default
                                          preselection flags for non-
                                          attributable events on the pipe.
                                          These flags correspond to the
                                          naflags field in audit_control(5).
                                          The ioctl argument should be of type
                                          u_int.

     AUDITPIPE_SET_PRESELECT_NAFLAGS      Set the current default preselection
                                          flags for non-attributable events on
                                          the pipe.  These flags correspond to
                                          the naflags field in
                                          audit_control(5).  The ioctl
                                          argument should be of type u_int.

     AUDITPIPE_GET_PRESELECT_AUID         Query the current preselection masks
                                          for a specific auid on the pipe.
                                          The ioctl argument should be of type
                                          struct auditpipe_ioctl_preselect.
                                          The auid to query is specified via
                                          the ap_auid field of type au_id_t;
                                          the mask will be returned via
                                          ap_mask of type au_mask_t.

     AUDITPIPE_SET_PRESELECT_AUID         Set the current preselection masks
                                          for a specific auid on the pipe.
                                          Arguments are identical to
                                          AUDITPIPE_GET_PRESELECT_AUID, except
                                          that the caller should properly
                                          initialize the ap_mask field to hold
                                          the desired preselection mask.

     AUDITPIPE_DELETE_PRESELECT_AUID      Delete the current preselection mask
                                          for a specific auid on the pipe.
                                          Once called, events associated with
                                          the specified auid will use the
                                          default flags mask.  The ioctl
                                          argument should be of type au_id_t.

     AUDITPIPE_FLUSH_PRESELECT_AUID       Delete all auid specific
                                          preselection specifications.

EXAMPLES
     The praudit(1) utility may be directly executed on /dev/auditpipe to
     review the default audit trail.

SEE ALSO
     poll(2), select(2), audit(4), audit_control(5), audit(8), auditd(8)

HISTORY
     The OpenBSM implementation was created by McAfee Research, the security
     division of McAfee Inc., under contract to Apple Computer Inc. in 2004.
     It was subsequently adopted by the TrustedBSD Project as the foundation
     for the OpenBSM distribution.

     Support for kernel audit first appeared in FreeBSD 6.2.

AUTHORS
     The audit pipe facility was designed and implemented by Robert Watson
     <rwatson@FreeBSD.org>.

     The Basic Security Module (BSM) interface to audit records and audit
     event stream format were defined by Sun Microsystems.

BUGS
     See the audit(4) manual page for information on audit-related bugs and
     limitations.

     The configurable preselection mechanism mirrors the selection model
     present for the global audit trail.  It might be desirable to provided a
     more flexible selection model.

     The per-pipe audit event queue is fifo, with drops occurring if either
     the user thread provides in sufficient for the record on the queue head,
     or on enqueue if there is insufficient room.  It might be desirable to
     support partial reads of records, which would be more compatible with
     buffered I/O as implemented in system libraries, and to allow
     applications to select which records are dropped, possibly in the style
     of preselection.

FreeBSD 11.0-PRERELEASE           May 5, 2006          FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=auditpipe&sektion=4&manpath=FreeBSD+9.3-RELEASE>

home | help