diff options
Diffstat (limited to 'static/freebsd/man4/auditpipe.4 3.html')
| -rw-r--r-- | static/freebsd/man4/auditpipe.4 3.html | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/static/freebsd/man4/auditpipe.4 3.html b/static/freebsd/man4/auditpipe.4 3.html new file mode 100644 index 00000000..b388b82c --- /dev/null +++ b/static/freebsd/man4/auditpipe.4 3.html @@ -0,0 +1,219 @@ +<table class="head"> + <tr> + <td class="head-ltitle">AUDITPIPE(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">AUDITPIPE(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">auditpipe</code> — + <span class="Nd">pseudo-device for live audit event tracking</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">options AUDIT</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">While audit trail files generated with <a class="Xr">audit(4)</a> + and maintained by <a class="Xr">auditd(8)</a> 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.</p> +<p class="Pp">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, <span class="Pa">/dev/auditpipe</span>, 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.</p> +<p class="Pp">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 <code class="Dv">SIGIO</code>, and polled operation via + <a class="Xr">select(2)</a> and <a class="Xr">poll(2)</a>.</p> +<p class="Pp">Applications may choose to track the global audit trail, or + configure local preselection parameters independent of the global audit + trail parameters.</p> +<section class="Ss"> +<h2 class="Ss" id="Audit_Pipe_Queue_Ioctls"><a class="permalink" href="#Audit_Pipe_Queue_Ioctls">Audit + Pipe Queue Ioctls</a></h2> +<p class="Pp">The following ioctls retrieve and set various audit pipe record + queue properties:</p> +<dl class="Bl-tag"> + <dt id="AUDITPIPE_GET_QLEN"><a class="permalink" href="#AUDITPIPE_GET_QLEN"><code class="Dv">AUDITPIPE_GET_QLEN</code></a></dt> + <dd>Query the current number of records available for reading on the + pipe.</dd> + <dt id="AUDITPIPE_GET_QLIMIT"><a class="permalink" href="#AUDITPIPE_GET_QLIMIT"><code class="Dv">AUDITPIPE_GET_QLIMIT</code></a></dt> + <dd>Retrieve the current maximum number of records that may be queued for + reading on the pipe.</dd> + <dt id="AUDITPIPE_SET_QLIMIT"><a class="permalink" href="#AUDITPIPE_SET_QLIMIT"><code class="Dv">AUDITPIPE_SET_QLIMIT</code></a></dt> + <dd>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.</dd> + <dt id="AUDITPIPE_GET_QLIMIT_MIN"><a class="permalink" href="#AUDITPIPE_GET_QLIMIT_MIN"><code class="Dv">AUDITPIPE_GET_QLIMIT_MIN</code></a></dt> + <dd>Query the lowest possible maximum number of records that may be queued for + reading on the pipe.</dd> + <dt id="AUDITPIPE_GET_QLIMIT_MAX"><a class="permalink" href="#AUDITPIPE_GET_QLIMIT_MAX"><code class="Dv">AUDITPIPE_GET_QLIMIT_MAX</code></a></dt> + <dd>Query the highest possible maximum number of records that may be queued + for reading on the pipe.</dd> + <dt id="AUDITPIPE_FLUSH"><a class="permalink" href="#AUDITPIPE_FLUSH"><code class="Dv">AUDITPIPE_FLUSH</code></a></dt> + <dd>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.</dd> + <dt id="AUDITPIPE_GET_MAXAUDITDATA"><a class="permalink" href="#AUDITPIPE_GET_MAXAUDITDATA"><code class="Dv">AUDITPIPE_GET_MAXAUDITDATA</code></a></dt> + <dd>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.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Audit_Pipe_Preselection_Mode_Ioctls"><a class="permalink" href="#Audit_Pipe_Preselection_Mode_Ioctls">Audit + Pipe Preselection Mode Ioctls</a></h2> +<p class="Pp">By default, the audit pipe facility configures pipes to present + records matched by the system-wide audit trail, configured by + <a class="Xr">auditd(8)</a>. 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.</p> +<p class="Pp">The following ioctls configure the preselection mode on an audit + pipe:</p> +<dl class="Bl-tag"> + <dt id="AUDITPIPE_GET_PRESELECT_MODE"><a class="permalink" href="#AUDITPIPE_GET_PRESELECT_MODE"><code class="Dv">AUDITPIPE_GET_PRESELECT_MODE</code></a></dt> + <dd>Return the current preselect mode on the audit pipe. The ioctl argument + should be of type <var class="Vt">int</var>.</dd> + <dt id="AUDITPIPE_SET_PRESELECT_MODE"><a class="permalink" href="#AUDITPIPE_SET_PRESELECT_MODE"><code class="Dv">AUDITPIPE_SET_PRESELECT_MODE</code></a></dt> + <dd>Set the current preselection mode on the audit pipe. The ioctl argument + should be of type <var class="Vt">int</var>.</dd> +</dl> +<p class="Pp">Possible preselection mode values are:</p> +<dl class="Bl-tag"> + <dt id="AUDITPIPE_PRESELECT_MODE_TRAIL"><a class="permalink" href="#AUDITPIPE_PRESELECT_MODE_TRAIL"><code class="Dv">AUDITPIPE_PRESELECT_MODE_TRAIL</code></a></dt> + <dd>Use the global audit trail preselection parameters to select records for + the audit pipe.</dd> + <dt id="AUDITPIPE_PRESELECT_MODE_LOCAL"><a class="permalink" href="#AUDITPIPE_PRESELECT_MODE_LOCAL"><code class="Dv">AUDITPIPE_PRESELECT_MODE_LOCAL</code></a></dt> + <dd>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.</dd> +</dl> +<p class="Pp">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.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Audit_Pipe_Local_Preselection_Mode_Ioctls"><a class="permalink" href="#Audit_Pipe_Local_Preselection_Mode_Ioctls">Audit + Pipe Local Preselection Mode Ioctls</a></h2> +<p class="Pp">The following ioctls configure the preselection parameters used + when an audit pipe is configured for the + <code class="Dv">AUDITPIPE_PRESELECT_MODE_LOCAL</code> preselection + mode.</p> +<dl class="Bl-tag"> + <dt id="AUDITPIPE_GET_PRESELECT_FLAGS"><a class="permalink" href="#AUDITPIPE_GET_PRESELECT_FLAGS"><code class="Dv">AUDITPIPE_GET_PRESELECT_FLAGS</code></a></dt> + <dd>Retrieve the current default preselection flags for attributable events on + the pipe. These flags correspond to the <var class="Va">flags</var> field + in <a class="Xr">audit_control(5)</a>. The ioctl argument should be of + type <var class="Vt">au_mask_t</var>.</dd> + <dt id="AUDITPIPE_SET_PRESELECT_FLAGS"><a class="permalink" href="#AUDITPIPE_SET_PRESELECT_FLAGS"><code class="Dv">AUDITPIPE_SET_PRESELECT_FLAGS</code></a></dt> + <dd>Set the current default preselection flags for attributable events on the + pipe. These flags correspond to the <var class="Va">flags</var> field in + <a class="Xr">audit_control(5)</a>. The ioctl argument should be of type + <var class="Vt">au_mask_t</var>.</dd> + <dt id="AUDITPIPE_GET_PRESELECT_NAFLAGS"><a class="permalink" href="#AUDITPIPE_GET_PRESELECT_NAFLAGS"><code class="Dv">AUDITPIPE_GET_PRESELECT_NAFLAGS</code></a></dt> + <dd>Retrieve the current default preselection flags for non-attributable + events on the pipe. These flags correspond to the + <var class="Va">naflags</var> field in <a class="Xr">audit_control(5)</a>. + The ioctl argument should be of type <var class="Vt">au_mask_t</var>.</dd> + <dt id="AUDITPIPE_SET_PRESELECT_NAFLAGS"><a class="permalink" href="#AUDITPIPE_SET_PRESELECT_NAFLAGS"><code class="Dv">AUDITPIPE_SET_PRESELECT_NAFLAGS</code></a></dt> + <dd>Set the current default preselection flags for non-attributable events on + the pipe. These flags correspond to the <var class="Va">naflags</var> + field in <a class="Xr">audit_control(5)</a>. The ioctl argument should be + of type <var class="Vt">au_mask_t</var>.</dd> + <dt id="AUDITPIPE_GET_PRESELECT_AUID"><a class="permalink" href="#AUDITPIPE_GET_PRESELECT_AUID"><code class="Dv">AUDITPIPE_GET_PRESELECT_AUID</code></a></dt> + <dd>Query the current preselection masks for a specific auid on the pipe. The + ioctl argument should be of type <var class="Vt">struct + auditpipe_ioctl_preselect</var>. The auid to query is specified via the + <var class="Va">ap_auid</var> field of type <var class="Vt">au_id_t</var>; + the mask will be returned via <var class="Va">ap_mask</var> of type + <var class="Vt">au_mask_t</var>.</dd> + <dt id="AUDITPIPE_SET_PRESELECT_AUID"><a class="permalink" href="#AUDITPIPE_SET_PRESELECT_AUID"><code class="Dv">AUDITPIPE_SET_PRESELECT_AUID</code></a></dt> + <dd>Set the current preselection masks for a specific auid on the pipe. + Arguments are identical to + <code class="Dv">AUDITPIPE_GET_PRESELECT_AUID</code>, except that the + caller should properly initialize the <var class="Va">ap_mask</var> field + to hold the desired preselection mask.</dd> + <dt id="AUDITPIPE_DELETE_PRESELECT_AUID"><a class="permalink" href="#AUDITPIPE_DELETE_PRESELECT_AUID"><code class="Dv">AUDITPIPE_DELETE_PRESELECT_AUID</code></a></dt> + <dd>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 + <var class="Vt">au_id_t</var>.</dd> + <dt id="AUDITPIPE_FLUSH_PRESELECT_AUID"><a class="permalink" href="#AUDITPIPE_FLUSH_PRESELECT_AUID"><code class="Dv">AUDITPIPE_FLUSH_PRESELECT_AUID</code></a></dt> + <dd>Delete all auid specific preselection specifications.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The <a class="Xr">praudit(1)</a> utility may be directly executed + on <span class="Pa">/dev/auditpipe</span> to review the default audit + trail.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">poll(2)</a>, <a class="Xr">select(2)</a>, + <a class="Xr">audit(4)</a>, <a class="Xr">dtaudit(4)</a>, + <a class="Xr">audit_control(5)</a>, <a class="Xr">audit(8)</a>, + <a class="Xr">auditd(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">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.</p> +<p class="Pp">Support for kernel audit first appeared in + <span class="Ux">FreeBSD 6.2</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The audit pipe facility was designed and implemented by + <span class="An">Robert Watson</span> + <<a class="Mt" href="mailto:rwatson@FreeBSD.org">rwatson@FreeBSD.org</a>>.</p> +<p class="Pp">The Basic Security Module (BSM) interface to audit records and + audit event stream format were defined by Sun Microsystems.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">See the <a class="Xr">audit(4)</a> manual page for information on + audit-related bugs and limitations.</p> +<p class="Pp">The configurable preselection mechanism mirrors the selection + model present for the global audit trail. It might be desirable to provide a + more flexible selection model.</p> +<p class="Pp">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.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 28, 2019</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |