| auditpipe.4 (161646) | auditpipe.4 (162871) |
|---|---|
| 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.\" | 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 $ | 25.\" $FreeBSD: head/share/man/man4/auditpipe.4 162871 2006-09-30 15:14:49Z ru $ |
| 26.\" 27.Dd May 5, 2006 28.Os 29.Dt AUDITPIPE 4 30.Sh NAME 31.Nm auditpipe | 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 | 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 , | 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 | 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, | 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 | 67asynchronous I/O using 68.Dv SIGIO , 69and 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: | 70.Xr select 2 71and 72.Xr poll 2 . 73.Pp 74Applications may choose to track the global audit trail, or configure local 75preselection parameters independent of the global audit trail parameters. 76.Ss Audit Pipe Queue Ioctls 77The following ioctls retrieve and set various audit pipe record queue 78properties: |
| 77.Bl -tag -width AUDITPIPE_GET_MAXAUDITDATA 78.It AUDITPIPE_GET_QLEN | 79.Bl -tag -width ".Dv AUDITPIPE_GET_MAXAUDITDATA" 80.It Dv AUDITPIPE_GET_QLEN |
| 79Query the current number of records available for reading on the pipe. | 81Query the current number of records available for reading on the pipe. |
| 80.It AUDITPIPE_GET_QLIMIT | 82.It Dv AUDITPIPE_GET_QLIMIT |
| 81Retrieve the current maximum number of records that may be queued for reading 82on the pipe. | 83Retrieve the current maximum number of records that may be queued for reading 84on the pipe. |
| 83.It AUDITPIPE_SET_QLIMIT | 85.It Dv 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. | 86Set the current maximum number of records that may be queued for reading on 87the pipe. 88The new limit must fall between the queue limit minimum and queue limit 89maximum queryable using the following two ioctls. |
| 88.It AUDITPIPE_GET_QLIMIT_MIN | 90.It Dv AUDITPIPE_GET_QLIMIT_MIN |
| 89Query the lowest possible maximum number of records that may be queued for 90reading on the pipe. | 91Query the lowest possible maximum number of records that may be queued for 92reading on the pipe. |
| 91.It AUDITPIPE_GET_QLIMIT_MAX | 93.It Dv AUDITPIPE_GET_QLIMIT_MAX |
| 92Query the highest possible maximum number of records that may be queued for 93reading on the pipe. | 94Query the highest possible maximum number of records that may be queued for 95reading on the pipe. |
| 94.It AUDITPIPE_FLUSH | 96.It Dv 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. | 97Flush all outstanding records on the audit pipe; useful after setting initial 98preselection properties to delete records queued during the configuration 99process which may not match the interests of the user process. |
| 98.It AUDITPIPE_GET_MAXAUDITDATA | 100.It Dv 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: | 101Query the maximum size of an audit record, which is a useful minimum size for 102a user space buffer intended to hold audit records read from the audit pipe. 103.El 104.Ss Audit Pipe Preselection Mode Ioctls 105By default, the audit pipe facility configures pipes to present records 106matched by the system-wide audit trail, configured by 107.Xr auditd 8 . 108However, the preselection mechanism for audit pipes can be configured using 109alternative criteria, including pipe-local flags and naflags settings, as 110well as auid-specific selection masks. 111This allows applications to track events not captured in the global audit 112trail, as well as limit records presented to those of specific interest to 113the application. 114.Pp 115The following ioctls configure the preselection mode on an audit pipe: |
| 114.Bl -tag -width AUDITPIPE_GET_PRESELECT_MODE 115.It AUDITPIPE_GET_PRESELECT_MODE | 116.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_MODE" 117.It Dv AUDITPIPE_GET_PRESELECT_MODE |
| 116Return the current preselect mode on the audit pipe. 117The ioctl argument should be of type 118.Vt int . | 118Return the current preselect mode on the audit pipe. 119The ioctl argument should be of type 120.Vt int . |
| 119.It AUDITPIPE_SET_PRESELECT_MODE | 121.It Dv 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: | 122Set the current preselection mode on the audit pipe. 123The ioctl argument should be of type 124.Vt int . 125.El 126.Pp 127Possible preselection mode values are: |
| 126.Bl -tag -width AUDITPIPE_PRESELECT_MODE_TRAIL 127.It AUDITPIPE_PRESELECT_MODE_TRAIL | 128.Bl -tag -width ".Dv AUDITPIPE_PRESELECT_MODE_TRAIL" 129.It Dv AUDITPIPE_PRESELECT_MODE_TRAIL |
| 128Use the global audit trail preselection parameters to select records for the 129audit pipe. | 130Use the global audit trail preselection parameters to select records for the 131audit pipe. |
| 130.It AUDITPIPE_PRESELECT_MODE_LOCAL | 132.It Dv 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. | 133Use local audit pipe preselection; this model is similar to the global audit 134trail configuration model, consisting of global flags and naflags parameters, 135as well as a set of per-auid masks. 136These parameters are configured using further ioctls. 137.El 138.Pp 139After changing the audit pipe preselection mode, records selected under 140earlier preselection configuration may still be in the audit pipe queue. 141The application may flush the current record queue after changing the 142configuration to remove possibly undesired records. 143.Ss Audit Pipe Local Preselection Mode Ioctls 144The following ioctls configure the preselection parameters used when an audit 145pipe is configured for the 146.Dv AUDITPIPE_PRESELECT_MODE_LOCAL 147preselection mode. |
| 146.Bl -tag -width AUDITPIPE_GET_PRESELECT_NAFLAGS 147.It AUDITPIPE_GET_PRESELECT_FLAGS | 148.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_NAFLAGS" 149.It Dv AUDITPIPE_GET_PRESELECT_FLAGS |
| 148Retrieve the current default preselection flags for attributable events on 149the pipe. 150These flags correspond to the | 150Retrieve the current default preselection flags for attributable events on 151the pipe. 152These flags correspond to the |
| 151.Dv flags | 153.Va flags |
| 152field in 153.Xr audit_control 5 . 154The ioctl argument should be of type 155.Vt u_int . | 154field in 155.Xr audit_control 5 . 156The ioctl argument should be of type 157.Vt u_int . |
| 156.It AUDITPIPE_SET_PRESELECT_FLAGS | 158.It Dv AUDITPIPE_SET_PRESELECT_FLAGS |
| 157Set the current default preselection flags for attributable events on the 158pipe. 159These flags correspond to the | 159Set the current default preselection flags for attributable events on the 160pipe. 161These flags correspond to the |
| 160.Dv flags | 162.Va flags |
| 161field in 162.Xr audit_control 5 . 163The ioctl argument should be of type 164.Vt u_int . | 163field in 164.Xr audit_control 5 . 165The ioctl argument should be of type 166.Vt u_int . |
| 165.It AUDITPIPE_GET_PRESELECT_NAFLAGS | 167.It Dv AUDITPIPE_GET_PRESELECT_NAFLAGS |
| 166Retrieve the current default preselection flags for non-attributable events 167on the pipe. 168These flags correspond to the | 168Retrieve the current default preselection flags for non-attributable events 169on the pipe. 170These flags correspond to the |
| 169.Dv naflags | 171.Va naflags |
| 170field in 171.Xr audit_control 5 . 172The ioctl argument should be of type 173.Vt u_int . | 172field in 173.Xr audit_control 5 . 174The ioctl argument should be of type 175.Vt u_int . |
| 174.It AUDITPIPE_SET_PRESELECT_NAFLAGS | 176.It Dv AUDITPIPE_SET_PRESELECT_NAFLAGS |
| 175Set the current default preselection flags for non-attributable events on the 176pipe. 177These flags correspond to the | 177Set the current default preselection flags for non-attributable events on the 178pipe. 179These flags correspond to the |
| 178.Dv naflags | 180.Va naflags |
| 179field in 180.Xr audit_control 5 . 181The ioctl argument should be of type 182.Vt u_int . | 181field in 182.Xr audit_control 5 . 183The ioctl argument should be of type 184.Vt u_int . |
| 183.It AUDITPIPE_GET_PRESELECT_AUID | 185.It Dv AUDITPIPE_GET_PRESELECT_AUID |
| 184Query the current preselection masks for a specific auid on the pipe. 185The ioctl argument should be of type | 186Query the current preselection masks for a specific auid on the pipe. 187The ioctl argument should be of type |
| 186.Vt struct auditpipe_preselect . | 188.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 . | 189The auid to query is specified via the 190.Va ap_auid 191field of type 192.Vt au_id_t ; 193the mask will be returned via 194.Va ap_mask 195of type 196.Vt au_mask_t . |
| 195.It AUDITPIPE_SET_PRESELECT_AUID | 197.It Dv AUDITPIPE_SET_PRESELECT_AUID |
| 196Set the current preselection masks for a specific auid on the pipe. 197Arguments are identical to | 198Set the current preselection masks for a specific auid on the pipe. 199Arguments are identical to |
| 198.Dv AUDITPIPE_GET_PRESELECT_AUID, | 200.Dv AUDITPIPE_GET_PRESELECT_AUID , |
| 199except that the caller should properly initialize the 200.Va ap_mask 201field to hold the desired preselection mask. | 201except that the caller should properly initialize the 202.Va ap_mask 203field to hold the desired preselection mask. |
| 202.It AUDITPIPE_DELETE_PRESELECT_AUID | 204.It Dv 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 . | 205Delete the current preselection mask for a specific auid on the pipe. 206Once called, events associated with the specified auid will use the default 207flags mask. 208The ioctl argument should be of type 209.Vt au_id_t . |
| 208.It AUDITPIPE_FLUSH_PRESELECT_AUID | 210.It Dv AUDITPIPE_FLUSH_PRESELECT_AUID |
| 209Delete all auid specific preselection specifications. 210.El 211.Sh EXAMPLES | 211Delete all auid specific preselection specifications. 212.El 213.Sh EXAMPLES |
| 214The |
|
| 212.Xr praudit 1 | 215.Xr praudit 1 |
| 216utility |
|
| 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 | 217may be directly executed on 218.Pa /dev/auditpipe 219to review the default audit trail. 220.Sh SEE ALSO 221.Xr poll 2 , 222.Xr select 2 , 223.Xr audit 4 , 224.Xr audit_control 5 , 225.Xr audit 8 , 226.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 | 227.Sh HISTORY 228The OpenBSM implementation was created by McAfee Research, the security |
| 231division of McAfee Inc., under contract to Apple Computer Inc. in 2004. | 229division 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 . | 230It was subsequently adopted by the TrustedBSD Project as the foundation for 231the OpenBSM distribution. 232.Pp 233Support for kernel audit first appeared in 234.Fx 6.2 . |
| 235.Sh AUTHORS 236The audit pipe facility was designed and implemented by 237.An Robert Watson Aq rwatson@FreeBSD.org . 238.Pp 239The Basic Security Module (BSM) interface to audit records and audit event 240stream format were defined by Sun Microsystems. |
|
| 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. | 241.Sh BUGS 242See the 243.Xr audit 4 244manual page for information on audit-related bugs and limitations. 245.Pp 246The configurable preselection mechanism mirrors the selection model present 247for the global audit trail. 248It might be desirable to provided a more flexible selection model. 249.Pp 250The per-pipe audit event queue is fifo, with drops occuring if either the 251user thread provides in sufficient for the record on the queue head, or on 252enqueue if there is insufficient room. 253It might be desirable to support partial reads of records, which would be 254more compatible with buffered I/O as implemented in system libraries, and to 255allow applications to select which records are dropped, possibly in the style 256of preselection. |