1.\" Copyright (c) 2006 Robert N. M. Watson
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
--- 8 unchanged lines hidden (view full) ---
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/share/man/man4/auditpipe.4 161646 2006-08-26 17:59:31Z rwatson $
26.\"
27.Dd May 5, 2006
28.Os
29.Dt AUDITPIPE 4
30.Sh NAME
31.Nm auditpipe
32.Nd Pseudo-device for live audit event tracking
33.Sh SYNOPSIS
34.Cd "options AUDIT"
35.Sh DESCRIPTION
36While audit trail files
37generated with
38.Xr audit 4
39and maintained by
40.Xr auditd 8
--- 4 unchanged lines hidden (view full) ---
45For example, the log may be cycled and new records written to a new file
46without notice to applications that may be accessing the file.
47.Pp
48The audit facility provides an audit pipe facility for applications requiring
49direct access to live BSM audit data for the purposes of real-time
50monitoring.
51Audit pipes are available via a clonable special device,
52.Pa /dev/auditpipe ,
53subject to the permissions on the device node, and provide a
54.Qq tee
55of the audit event stream.
56As the device is clonable, more than one instance of the device may be opened
57at a time; each device instance will provide independent access to all
58records.
59.Pp
60The audit pipe device provides discrete BSM audit records; if the read buffer
61passed by the application is too small to hold the next record in the
62sequence, it will be dropped.
63Unlike audit data written to the audit trail, the reliability of record
64delivery is not guaranteed.
65In particular, when an audit pipe queue fills, records will be dropped.
66Audit pipe devices are blocking by default, but support non-blocking I/O,
67asynchronous I/O using SIGIO, and polled operation via
68.Xr select 2
69and
70.Xr poll 2 .
71.Pp
72Applications may choose to track the global audit trail, or configure local
73preselection parameters independent of the global audit trail parameters.
74.Ss Audit Pipe Queue Ioctls
75The following ioctls retrieve and set various audit pipe record queue
76properties:
77.Bl -tag -width AUDITPIPE_GET_MAXAUDITDATA
78.It AUDITPIPE_GET_QLEN
79Query the current number of records available for reading on the pipe.
80.It AUDITPIPE_GET_QLIMIT
81Retrieve the current maximum number of records that may be queued for reading
82on the pipe.
83.It AUDITPIPE_SET_QLIMIT
84Set the current maximum number of records that may be queued for reading on
85the pipe.
86The new limit must fall between the queue limit minimum and queue limit
87maximum queryable using the following two ioctls.
88.It AUDITPIPE_GET_QLIMIT_MIN
89Query the lowest possible maximum number of records that may be queued for
90reading on the pipe.
91.It AUDITPIPE_GET_QLIMIT_MAX
92Query the highest possible maximum number of records that may be queued for
93reading on the pipe.
94.It AUDITPIPE_FLUSH
95Flush all outstanding records on the audit pipe; useful after setting initial
96preselection properties to delete records queued during the configuration
97process which may not match the interests of the user process.
98.It AUDITPIPE_GET_MAXAUDITDATA
99Query the maximum size of an audit record, which is a useful minimum size for
100a user space buffer intended to hold audit records read from the audit pipe.
101.El
102.Ss Audit Pipe Preselection Mode Ioctls
103By default, the audit pipe facility configures pipes to present records
104matched by the system-wide audit trail, configured by
105.Xr auditd 8 .
106However, the preselection mechanism for audit pipes can be configured using
107alternative criteria, including pipe-local flags and naflags settings, as
108well as auid-specific selection masks.
109This allows applications to track events not captured in the global audit
110trail, as well as limit records presented to those of specific interest to
111the application.
112.Pp
113The following ioctls configure the preselection mode on an audit pipe:
114.Bl -tag -width AUDITPIPE_GET_PRESELECT_MODE
115.It AUDITPIPE_GET_PRESELECT_MODE
116Return the current preselect mode on the audit pipe.
117The ioctl argument should be of type
118.Vt int .
119.It AUDITPIPE_SET_PRESELECT_MODE
120Set the current preselection mode on the audit pipe.
121The ioctl argument should be of type
122.Vt int .
123.El
124.Pp
125Possible preselection mode values are:
126.Bl -tag -width AUDITPIPE_PRESELECT_MODE_TRAIL
127.It AUDITPIPE_PRESELECT_MODE_TRAIL
128Use the global audit trail preselection parameters to select records for the
129audit pipe.
130.It AUDITPIPE_PRESELECT_MODE_LOCAL
131Use local audit pipe preselection; this model is similar to the global audit
132trail configuration model, consisting of global flags and naflags parameters,
133as well as a set of per-auid masks.
134These parameters are configured using further ioctls.
135.El
136.Pp
137After changing the audit pipe preselection mode, records selected under
138earlier preselection configuration may still be in the audit pipe queue.
139The application may flush the current record queue after changing the
140configuration to remove possibly undesired records.
141.Ss Audit Pipe Local Preselection Mode Ioctls
142The following ioctls configure the preselection parameters used when an audit
143pipe is configured for the
144.Dv AUDITPIPE_PRESELECT_MODE_LOCAL
145preselection mode.
146.Bl -tag -width AUDITPIPE_GET_PRESELECT_NAFLAGS
147.It AUDITPIPE_GET_PRESELECT_FLAGS
148Retrieve the current default preselection flags for attributable events on
149the pipe.
150These flags correspond to the
151.Dv flags
152field in
153.Xr audit_control 5 .
154The ioctl argument should be of type
155.Vt u_int .
156.It AUDITPIPE_SET_PRESELECT_FLAGS
157Set the current default preselection flags for attributable events on the
158pipe.
159These flags correspond to the
160.Dv flags
161field in
162.Xr audit_control 5 .
163The ioctl argument should be of type
164.Vt u_int .
165.It AUDITPIPE_GET_PRESELECT_NAFLAGS
166Retrieve the current default preselection flags for non-attributable events
167on the pipe.
168These flags correspond to the
169.Dv naflags
170field in
171.Xr audit_control 5 .
172The ioctl argument should be of type
173.Vt u_int .
174.It AUDITPIPE_SET_PRESELECT_NAFLAGS
175Set the current default preselection flags for non-attributable events on the
176pipe.
177These flags correspond to the
178.Dv naflags
179field in
180.Xr audit_control 5 .
181The ioctl argument should be of type
182.Vt u_int .
183.It AUDITPIPE_GET_PRESELECT_AUID
184Query the current preselection masks for a specific auid on the pipe.
185The ioctl argument should be of type
186.Vt struct auditpipe_preselect .
187The auid to query is specified via the
188.Va ap_auid
189field of type
190.Vt au_id_t ;
191the mask will be returned via
192.Va ap_mask
193of type
194.Vt au_mask_t .
195.It AUDITPIPE_SET_PRESELECT_AUID
196Set the current preselection masks for a specific auid on the pipe.
197Arguments are identical to
198.Dv AUDITPIPE_GET_PRESELECT_AUID,
199except that the caller should properly initialize the
200.Va ap_mask
201field to hold the desired preselection mask.
202.It AUDITPIPE_DELETE_PRESELECT_AUID
203Delete the current preselection mask for a specific auid on the pipe.
204Once called, events associated with the specified auid will use the default
205flags mask.
206The ioctl argument should be of type
207.Vt au_id_t .
208.It AUDITPIPE_FLUSH_PRESELECT_AUID
209Delete all auid specific preselection specifications.
210.El
211.Sh EXAMPLES
212.Xr praudit 1
213may be directly executed on
214.Pa /dev/auditpipe
215to review the default audit trail.
216.Sh SEE ALSO
217.Xr poll 2 ,
218.Xr select 2 ,
219.Xr audit 4 ,
220.Xr audit_control 5 ,
221.Xr audit 8 ,
222.Xr auditd 8
223.Sh AUTHORS
224The audit pipe facility was designed and implemented by
225.An Robert Watson Aq rwatson@FreeBSD.org .
226.Pp
227The Basic Security Module (BSM) interface to audit records and audit event
228stream format were defined by Sun Microsystems.
229.Sh HISTORY
230The OpenBSM implementation was created by McAfee Research, the security
231division of McAfee Inc., under contract to Apple Computer Inc. in 2004.
232It was subsequently adopted by the TrustedBSD Project as the foundation for
233the OpenBSM distribution.
234.Pp
235Support for kernel audit first appeared in
236.Fx 6.2 .
237.Sh BUGS
238See the
239.Xr audit 4
240manual page for information on audit-related bugs and limitations.
241.Pp
242The configurable preselection mechanism mirrors the selection model present
243for the global audit trail.
244It might be desirable to provided a more flexible selection model.
245.Pp
246The per-pipe audit event queue is fifo, with drops occuring if either the
247user thread provides in sufficient for the record on the queue head, or on
248enqueue if there is insufficient room.
249It might be desirable to support partial reads of records, which would be
250more compatible with buffered I/O as implemented in system libraries, and to
251allow applications to select which records are dropped, possibly in the style
252of preselection.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
--- 8 unchanged lines hidden (view full) ---
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/share/man/man4/auditpipe.4 161646 2006-08-26 17:59:31Z rwatson $
26.\"
27.Dd May 5, 2006
28.Os
29.Dt AUDITPIPE 4
30.Sh NAME
31.Nm auditpipe
32.Nd Pseudo-device for live audit event tracking
33.Sh SYNOPSIS
34.Cd "options AUDIT"
35.Sh DESCRIPTION
36While audit trail files
37generated with
38.Xr audit 4
39and maintained by
40.Xr auditd 8
--- 4 unchanged lines hidden (view full) ---
45For example, the log may be cycled and new records written to a new file
46without notice to applications that may be accessing the file.
47.Pp
48The audit facility provides an audit pipe facility for applications requiring
49direct access to live BSM audit data for the purposes of real-time
50monitoring.
51Audit pipes are available via a clonable special device,
52.Pa /dev/auditpipe ,
53subject to the permissions on the device node, and provide a
54.Qq tee
55of the audit event stream.
56As the device is clonable, more than one instance of the device may be opened
57at a time; each device instance will provide independent access to all
58records.
59.Pp
60The audit pipe device provides discrete BSM audit records; if the read buffer
61passed by the application is too small to hold the next record in the
62sequence, it will be dropped.
63Unlike audit data written to the audit trail, the reliability of record
64delivery is not guaranteed.
65In particular, when an audit pipe queue fills, records will be dropped.
66Audit pipe devices are blocking by default, but support non-blocking I/O,
67asynchronous I/O using SIGIO, and polled operation via
68.Xr select 2
69and
70.Xr poll 2 .
71.Pp
72Applications may choose to track the global audit trail, or configure local
73preselection parameters independent of the global audit trail parameters.
74.Ss Audit Pipe Queue Ioctls
75The following ioctls retrieve and set various audit pipe record queue
76properties:
77.Bl -tag -width AUDITPIPE_GET_MAXAUDITDATA
78.It AUDITPIPE_GET_QLEN
79Query the current number of records available for reading on the pipe.
80.It AUDITPIPE_GET_QLIMIT
81Retrieve the current maximum number of records that may be queued for reading
82on the pipe.
83.It AUDITPIPE_SET_QLIMIT
84Set the current maximum number of records that may be queued for reading on
85the pipe.
86The new limit must fall between the queue limit minimum and queue limit
87maximum queryable using the following two ioctls.
88.It AUDITPIPE_GET_QLIMIT_MIN
89Query the lowest possible maximum number of records that may be queued for
90reading on the pipe.
91.It AUDITPIPE_GET_QLIMIT_MAX
92Query the highest possible maximum number of records that may be queued for
93reading on the pipe.
94.It AUDITPIPE_FLUSH
95Flush all outstanding records on the audit pipe; useful after setting initial
96preselection properties to delete records queued during the configuration
97process which may not match the interests of the user process.
98.It AUDITPIPE_GET_MAXAUDITDATA
99Query the maximum size of an audit record, which is a useful minimum size for
100a user space buffer intended to hold audit records read from the audit pipe.
101.El
102.Ss Audit Pipe Preselection Mode Ioctls
103By default, the audit pipe facility configures pipes to present records
104matched by the system-wide audit trail, configured by
105.Xr auditd 8 .
106However, the preselection mechanism for audit pipes can be configured using
107alternative criteria, including pipe-local flags and naflags settings, as
108well as auid-specific selection masks.
109This allows applications to track events not captured in the global audit
110trail, as well as limit records presented to those of specific interest to
111the application.
112.Pp
113The following ioctls configure the preselection mode on an audit pipe:
114.Bl -tag -width AUDITPIPE_GET_PRESELECT_MODE
115.It AUDITPIPE_GET_PRESELECT_MODE
116Return the current preselect mode on the audit pipe.
117The ioctl argument should be of type
118.Vt int .
119.It AUDITPIPE_SET_PRESELECT_MODE
120Set the current preselection mode on the audit pipe.
121The ioctl argument should be of type
122.Vt int .
123.El
124.Pp
125Possible preselection mode values are:
126.Bl -tag -width AUDITPIPE_PRESELECT_MODE_TRAIL
127.It AUDITPIPE_PRESELECT_MODE_TRAIL
128Use the global audit trail preselection parameters to select records for the
129audit pipe.
130.It AUDITPIPE_PRESELECT_MODE_LOCAL
131Use local audit pipe preselection; this model is similar to the global audit
132trail configuration model, consisting of global flags and naflags parameters,
133as well as a set of per-auid masks.
134These parameters are configured using further ioctls.
135.El
136.Pp
137After changing the audit pipe preselection mode, records selected under
138earlier preselection configuration may still be in the audit pipe queue.
139The application may flush the current record queue after changing the
140configuration to remove possibly undesired records.
141.Ss Audit Pipe Local Preselection Mode Ioctls
142The following ioctls configure the preselection parameters used when an audit
143pipe is configured for the
144.Dv AUDITPIPE_PRESELECT_MODE_LOCAL
145preselection mode.
146.Bl -tag -width AUDITPIPE_GET_PRESELECT_NAFLAGS
147.It AUDITPIPE_GET_PRESELECT_FLAGS
148Retrieve the current default preselection flags for attributable events on
149the pipe.
150These flags correspond to the
151.Dv flags
152field in
153.Xr audit_control 5 .
154The ioctl argument should be of type
155.Vt u_int .
156.It AUDITPIPE_SET_PRESELECT_FLAGS
157Set the current default preselection flags for attributable events on the
158pipe.
159These flags correspond to the
160.Dv flags
161field in
162.Xr audit_control 5 .
163The ioctl argument should be of type
164.Vt u_int .
165.It AUDITPIPE_GET_PRESELECT_NAFLAGS
166Retrieve the current default preselection flags for non-attributable events
167on the pipe.
168These flags correspond to the
169.Dv naflags
170field in
171.Xr audit_control 5 .
172The ioctl argument should be of type
173.Vt u_int .
174.It AUDITPIPE_SET_PRESELECT_NAFLAGS
175Set the current default preselection flags for non-attributable events on the
176pipe.
177These flags correspond to the
178.Dv naflags
179field in
180.Xr audit_control 5 .
181The ioctl argument should be of type
182.Vt u_int .
183.It AUDITPIPE_GET_PRESELECT_AUID
184Query the current preselection masks for a specific auid on the pipe.
185The ioctl argument should be of type
186.Vt struct auditpipe_preselect .
187The auid to query is specified via the
188.Va ap_auid
189field of type
190.Vt au_id_t ;
191the mask will be returned via
192.Va ap_mask
193of type
194.Vt au_mask_t .
195.It AUDITPIPE_SET_PRESELECT_AUID
196Set the current preselection masks for a specific auid on the pipe.
197Arguments are identical to
198.Dv AUDITPIPE_GET_PRESELECT_AUID,
199except that the caller should properly initialize the
200.Va ap_mask
201field to hold the desired preselection mask.
202.It AUDITPIPE_DELETE_PRESELECT_AUID
203Delete the current preselection mask for a specific auid on the pipe.
204Once called, events associated with the specified auid will use the default
205flags mask.
206The ioctl argument should be of type
207.Vt au_id_t .
208.It AUDITPIPE_FLUSH_PRESELECT_AUID
209Delete all auid specific preselection specifications.
210.El
211.Sh EXAMPLES
212.Xr praudit 1
213may be directly executed on
214.Pa /dev/auditpipe
215to review the default audit trail.
216.Sh SEE ALSO
217.Xr poll 2 ,
218.Xr select 2 ,
219.Xr audit 4 ,
220.Xr audit_control 5 ,
221.Xr audit 8 ,
222.Xr auditd 8
223.Sh AUTHORS
224The audit pipe facility was designed and implemented by
225.An Robert Watson Aq rwatson@FreeBSD.org .
226.Pp
227The Basic Security Module (BSM) interface to audit records and audit event
228stream format were defined by Sun Microsystems.
229.Sh HISTORY
230The OpenBSM implementation was created by McAfee Research, the security
231division of McAfee Inc., under contract to Apple Computer Inc. in 2004.
232It was subsequently adopted by the TrustedBSD Project as the foundation for
233the OpenBSM distribution.
234.Pp
235Support for kernel audit first appeared in
236.Fx 6.2 .
237.Sh BUGS
238See the
239.Xr audit 4
240manual page for information on audit-related bugs and limitations.
241.Pp
242The configurable preselection mechanism mirrors the selection model present
243for the global audit trail.
244It might be desirable to provided a more flexible selection model.
245.Pp
246The per-pipe audit event queue is fifo, with drops occuring if either the
247user thread provides in sufficient for the record on the queue head, or on
248enqueue if there is insufficient room.
249It might be desirable to support partial reads of records, which would be
250more compatible with buffered I/O as implemented in system libraries, and to
251allow applications to select which records are dropped, possibly in the style
252of preselection.