1.\"-
2.\" Copyright (c) 2005 Robert N. M. Watson
3.\" Copyright (c) 2005 Tom Rhodes
4.\" Copyright (c) 2005 Wayne J. Salamon
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
| 1.\"-
2.\" Copyright (c) 2005 Robert N. M. Watson
3.\" Copyright (c) 2005 Tom Rhodes
4.\" Copyright (c) 2005 Wayne J. Salamon
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
|
28.\" $P4: //depot/projects/trustedbsd/openbsm/man/auditon.2#6 $
| 28.\" $P4: //depot/projects/trustedbsd/openbsm/man/auditon.2#7 $
|
29.\"
30.Dd April 19, 2005
31.Dt AUDITON 2
32.Os
33.Sh NAME
34.Nm auditon
35.Nd "Configure system audit parameters"
36.Sh SYNOPSIS
37.In bsm/audit.h
38.Ft int
39.Fn auditon "int cmd" "void *data" "u_int length"
40.Sh DESCRIPTION
41The
42.Nm
43system call is used to manipulate various audit control operations.
44.Ft *data
45should point to a structure whose type depends on the command.
46.Ft length
47specifies the size of the
48.Em data
49in bytes.
50.Ft cmd
51may be any of the following:
52.Bl -tag -width ".It Dv A_GETPINFO_ADDR"
53.It Dv A_SETPOLICY
54Set audit policy flags.
55.Ft *data
| 29.\"
30.Dd April 19, 2005
31.Dt AUDITON 2
32.Os
33.Sh NAME
34.Nm auditon
35.Nd "Configure system audit parameters"
36.Sh SYNOPSIS
37.In bsm/audit.h
38.Ft int
39.Fn auditon "int cmd" "void *data" "u_int length"
40.Sh DESCRIPTION
41The
42.Nm
43system call is used to manipulate various audit control operations.
44.Ft *data
45should point to a structure whose type depends on the command.
46.Ft length
47specifies the size of the
48.Em data
49in bytes.
50.Ft cmd
51may be any of the following:
52.Bl -tag -width ".It Dv A_GETPINFO_ADDR"
53.It Dv A_SETPOLICY
54Set audit policy flags.
55.Ft *data
|
56must point to an long value set to one of the audit
57policy control values defined in audit.h.
| 56must point to a long value set to one of the audit
57policy control values defined in
58.Pa audit.h .
|
58Currently, only
59.Dv AUDIT_CNT
60and
61.Dv AUDIT_AHLT
62are implemented.
63In the
64.Dv AUDIT_CNT
65case, the action will continue regardless if
66an event will not be audited.
67In the
68.Dv AUDIT_AHLT
69case, a
70.Xr panic 9
71will result if an event will not be written to the
72audit log file.
73.It Dv A_SETKAUDIT
74Return
75.Er ENOSYS .
76.It Dv A_SETKMASK
77Set the kernel preselection masks (success and failure).
78.Ft *data
79must point to a
80.Ft au_mask_t
81structure containing the mask values.
82These masks are used for non-attributable audit event preselection.
83.It Dv A_SETQCTRL
84Set kernel audit queue parameters.
85.Ft *data
| 59Currently, only
60.Dv AUDIT_CNT
61and
62.Dv AUDIT_AHLT
63are implemented.
64In the
65.Dv AUDIT_CNT
66case, the action will continue regardless if
67an event will not be audited.
68In the
69.Dv AUDIT_AHLT
70case, a
71.Xr panic 9
72will result if an event will not be written to the
73audit log file.
74.It Dv A_SETKAUDIT
75Return
76.Er ENOSYS .
77.It Dv A_SETKMASK
78Set the kernel preselection masks (success and failure).
79.Ft *data
80must point to a
81.Ft au_mask_t
82structure containing the mask values.
83These masks are used for non-attributable audit event preselection.
84.It Dv A_SETQCTRL
85Set kernel audit queue parameters.
86.Ft *data
|
86must point to a
| 87must point to a
|
87.Ft au_qctrl_t
88structure containing the
89kernel audit queue control settings:
90.Va high water ,
91.Va low water ,
92.Va output buffer size ,
93.Va percent min free disk space ,
94and
95.Em delay
96(not currently used).
97.It Dv A_SETSTAT
98Return
99.Er ENOSYS .
100.It Dv A_SETUMASK
101Return
102.Er ENOSYS .
103.It Dv A_SETSMASK
104Return
105.Er ENOSYS .
106.It Dv A_SETCOND
107Set the current auditing condition.
108.Ft *data
| 88.Ft au_qctrl_t
89structure containing the
90kernel audit queue control settings:
91.Va high water ,
92.Va low water ,
93.Va output buffer size ,
94.Va percent min free disk space ,
95and
96.Em delay
97(not currently used).
98.It Dv A_SETSTAT
99Return
100.Er ENOSYS .
101.It Dv A_SETUMASK
102Return
103.Er ENOSYS .
104.It Dv A_SETSMASK
105Return
106.Er ENOSYS .
107.It Dv A_SETCOND
108Set the current auditing condition.
109.Ft *data
|
109must point to an long value containing the new
| 110must point to a long value containing the new
|
110audit condition, one of
111.Dv AUC_AUDITING ,
112.Dv AUC_NOAUDIT ,
113or
114.Dv AUC_DISABLED .
115.It Dv A_SETCLASS
116Set the event class preselection mask for an audit event.
117.Ft *data
| 111audit condition, one of
112.Dv AUC_AUDITING ,
113.Dv AUC_NOAUDIT ,
114or
115.Dv AUC_DISABLED .
116.It Dv A_SETCLASS
117Set the event class preselection mask for an audit event.
118.Ft *data
|
118must point to a
| 119must point to a
|
119.Ft au_evclass_map_t
120structure containing the audit event and mask.
121.It Dv A_SETPMASK
122Set the preselection masks for a process.
123.Ft *data
| 120.Ft au_evclass_map_t
121structure containing the audit event and mask.
122.It Dv A_SETPMASK
123Set the preselection masks for a process.
124.Ft *data
|
124must point to a
| 125must point to a
|
125.Ft auditpinfo_t
126structure that contains the given process's audit
127preselection masks for both success and failure.
128.It Dv A_SETFSIZE
129Set the maximum size of the audit log file.
130.Ft *data
131must point to a
132.Ft au_fstat_t
133structure with the
134.Ft af_filesz
135field set to the maximum audit log file size. A value of 0
136indicates no limit to the size.
137.It Dv A_SETKAUDIT
138Return
139.Er ENOSYS .
140.It Dv A_GETCLASS
141Return the event to class mapping for the designated audit event.
142.Ft *data
143must point to a
144.Ft au_evclass_map_t
145structure.
146.It Dv A_GETKAUDIT
147Return
148.Er ENOSYS .
149.It Dv A_GETPINFO
150Return the audit settings for a process.
151.Ft *data
152must point to a
153.Ft auditpinfo_t
154structure which will be set to contain
155the audit ID, preselection mask, terminal ID, and audit session
156ID of the given process.
157.It Dv A_GETPINFO_ADDR
158Return
159.Er ENOSYS .
160.It Dv A_GETKMASK
161Return the current kernel preselection masks.
162.Ft *data
163must point to a
164.Ft au_mask_t
165structure which will be set to
166the current kernel preselection masks for non-attributable events.
167.It Dv A_GETPOLICY
168Return the current audit policy setting.
169.Ft *data
| 126.Ft auditpinfo_t
127structure that contains the given process's audit
128preselection masks for both success and failure.
129.It Dv A_SETFSIZE
130Set the maximum size of the audit log file.
131.Ft *data
132must point to a
133.Ft au_fstat_t
134structure with the
135.Ft af_filesz
136field set to the maximum audit log file size. A value of 0
137indicates no limit to the size.
138.It Dv A_SETKAUDIT
139Return
140.Er ENOSYS .
141.It Dv A_GETCLASS
142Return the event to class mapping for the designated audit event.
143.Ft *data
144must point to a
145.Ft au_evclass_map_t
146structure.
147.It Dv A_GETKAUDIT
148Return
149.Er ENOSYS .
150.It Dv A_GETPINFO
151Return the audit settings for a process.
152.Ft *data
153must point to a
154.Ft auditpinfo_t
155structure which will be set to contain
156the audit ID, preselection mask, terminal ID, and audit session
157ID of the given process.
158.It Dv A_GETPINFO_ADDR
159Return
160.Er ENOSYS .
161.It Dv A_GETKMASK
162Return the current kernel preselection masks.
163.Ft *data
164must point to a
165.Ft au_mask_t
166structure which will be set to
167the current kernel preselection masks for non-attributable events.
168.It Dv A_GETPOLICY
169Return the current audit policy setting.
170.Ft *data
|
170must point to an long value which will be set to
| 171must point to a long value which will be set to
|
171one of the current audit policy flags.
172Currently, only
173.Dv AUDIT_CNT
174and
175.Dv AUDIT_AHLT
176are implemented.
177.It Dv A_GETQCTRL
178Return the current kernel audit queue control parameters.
179.Ft *data
180must point to a
181.Ft au_qctrl_t
182structure which will be set to the current
183kernel audit queue control parameters.
184.It Dv A_GETFSIZE
185Returns the maximum size of the audit log file.
186.Ft *data
187must point to a
188.Ft au_fstat_t
189structure. The
190.Ft af_filesz
| 172one of the current audit policy flags.
173Currently, only
174.Dv AUDIT_CNT
175and
176.Dv AUDIT_AHLT
177are implemented.
178.It Dv A_GETQCTRL
179Return the current kernel audit queue control parameters.
180.Ft *data
181must point to a
182.Ft au_qctrl_t
183structure which will be set to the current
184kernel audit queue control parameters.
185.It Dv A_GETFSIZE
186Returns the maximum size of the audit log file.
187.Ft *data
188must point to a
189.Ft au_fstat_t
190structure. The
191.Ft af_filesz
|
191field will set to the maximum audit log file size. A value of 0
192indicates no limit to the size.
| 192field will be set to the maximum audit log file size.
193A value of 0 indicates no limit to the size.
|
193The
194.Ft af_filesz
195will be set to the current audit log file size.
196.It Dv A_GETCWD
197.\" [COMMENTED OUT]: Valid description, not yet implemented.
198.\" Return the current working directory as stored in the audit subsystem.
199Return
200.Er ENOSYS .
201.It Dv A_GETCAR
202.\" [COMMENTED OUT]: Valid description, not yet implemented.
203.\"Stores and returns the current active root as stored in the audit
204.\"subsystem.
205Return
206.Er ENOSYS .
207.It Dv A_GETSTAT
208.\" [COMMENTED OUT]: Valid description, not yet implemented.
209.\"Return the statistics stored in the audit system.
210Return
211.Er ENOSYS .
212.It Dv A_GETCOND
213Return the current auditing condition.
214.Ft *data
215must point to a long value which will be set to
216the current audit condition, either
217.Dv AUC_AUDITING
218or
219.Dv AUC_NOAUDIT .
220.It Dv A_SENDTRIGGER
221Send a trigger to the audit daemon.
222.Fr *data
223must point to a long value set to one of the acceptable
224trigger values:
225.Dv AUDIT_TRIGGER_LOW_SPACE
226(low disk space where the audit log resides),
227.Dv AUDIT_TRIGGER_OPEN_NEW
228(open a new audit log file),
229.Dv AUDIT_TRIGGER_READ_FILE
| 194The
195.Ft af_filesz
196will be set to the current audit log file size.
197.It Dv A_GETCWD
198.\" [COMMENTED OUT]: Valid description, not yet implemented.
199.\" Return the current working directory as stored in the audit subsystem.
200Return
201.Er ENOSYS .
202.It Dv A_GETCAR
203.\" [COMMENTED OUT]: Valid description, not yet implemented.
204.\"Stores and returns the current active root as stored in the audit
205.\"subsystem.
206Return
207.Er ENOSYS .
208.It Dv A_GETSTAT
209.\" [COMMENTED OUT]: Valid description, not yet implemented.
210.\"Return the statistics stored in the audit system.
211Return
212.Er ENOSYS .
213.It Dv A_GETCOND
214Return the current auditing condition.
215.Ft *data
216must point to a long value which will be set to
217the current audit condition, either
218.Dv AUC_AUDITING
219or
220.Dv AUC_NOAUDIT .
221.It Dv A_SENDTRIGGER
222Send a trigger to the audit daemon.
223.Fr *data
224must point to a long value set to one of the acceptable
225trigger values:
226.Dv AUDIT_TRIGGER_LOW_SPACE
227(low disk space where the audit log resides),
228.Dv AUDIT_TRIGGER_OPEN_NEW
229(open a new audit log file),
230.Dv AUDIT_TRIGGER_READ_FILE
|
230(read the audit_control file),
| 231(read the
232.Pa audit_control
233file),
|
231.Dv AUDIT_TRIGGER_CLOSE_AND_DIE
232(close the current log file and exit),
233or
234.Dv AUDIT_TRIGGER_NO_SPACE
235(no disk space left for audit log file).
236.El
237.Sh RETURN VALUES
238.Rv -std
239.Sh ERRORS
240The
241.Fn auditon
242function will fail if:
243.Bl -tag -width Er
244.It Bq Er ENOSYS
245Returned by options not yet implemented.
246.It Bq Er EFAULT
247A failure occurred while data transferred to or from
248the kernel failed.
249.It Bq Er EINVAL
250Illegal argument was passed by a system call.
251.It Bq Er EPERM
252The process does not have sufficient permission to complete
253the operation.
254.El
255.Pp
256The
257.Dv A_SENDTRIGGER
258command is specific to the
259.Fx
260and Mac OS X implementations, and is not present in Solaris.
261.Sh SEE ALSO
262.Xr audit 2 ,
263.Xr auditctl 2 ,
264.Xr getauid 2 ,
265.Xr setauid 2 ,
266.Xr getaudit 2 ,
267.Xr setaudit 2 ,
268.Xr getaudit_addr 2 ,
269.Xr setaudit_addr 2 ,
270.Xr libbsm 3
271.Sh AUTHORS
272This software was created by McAfee Research, the security research division
273of McAfee, Inc., under contract to Apple Computer Inc.
274Additional authors include Wayne Salamon, Robert Watson, and SPARTA Inc.
275.Pp
276The Basic Security Module (BSM) interface to audit records and audit event
277stream format were defined by Sun Microsystems.
278.Pp
279This manual page was written by
280.An Tom Rhodes Aq trhodes@FreeBSD.org ,
281.An Robert Watson Aq rwatson@FreeBSD.org ,
282and
283.An Wayne Salamon Aq wsalamon@FreeBSD.org .
284.Sh HISTORY
285The OpenBSM implementation was created by McAfee Research, the security
286division of McAfee Inc., under contract to Apple Computer Inc. in 2003.
287It was subsequently adopted by the TrustedBSD Project as the foundation for
288the OpenBSM distribution.
| 234.Dv AUDIT_TRIGGER_CLOSE_AND_DIE
235(close the current log file and exit),
236or
237.Dv AUDIT_TRIGGER_NO_SPACE
238(no disk space left for audit log file).
239.El
240.Sh RETURN VALUES
241.Rv -std
242.Sh ERRORS
243The
244.Fn auditon
245function will fail if:
246.Bl -tag -width Er
247.It Bq Er ENOSYS
248Returned by options not yet implemented.
249.It Bq Er EFAULT
250A failure occurred while data transferred to or from
251the kernel failed.
252.It Bq Er EINVAL
253Illegal argument was passed by a system call.
254.It Bq Er EPERM
255The process does not have sufficient permission to complete
256the operation.
257.El
258.Pp
259The
260.Dv A_SENDTRIGGER
261command is specific to the
262.Fx
263and Mac OS X implementations, and is not present in Solaris.
264.Sh SEE ALSO
265.Xr audit 2 ,
266.Xr auditctl 2 ,
267.Xr getauid 2 ,
268.Xr setauid 2 ,
269.Xr getaudit 2 ,
270.Xr setaudit 2 ,
271.Xr getaudit_addr 2 ,
272.Xr setaudit_addr 2 ,
273.Xr libbsm 3
274.Sh AUTHORS
275This software was created by McAfee Research, the security research division
276of McAfee, Inc., under contract to Apple Computer Inc.
277Additional authors include Wayne Salamon, Robert Watson, and SPARTA Inc.
278.Pp
279The Basic Security Module (BSM) interface to audit records and audit event
280stream format were defined by Sun Microsystems.
281.Pp
282This manual page was written by
283.An Tom Rhodes Aq trhodes@FreeBSD.org ,
284.An Robert Watson Aq rwatson@FreeBSD.org ,
285and
286.An Wayne Salamon Aq wsalamon@FreeBSD.org .
287.Sh HISTORY
288The OpenBSM implementation was created by McAfee Research, the security
289division of McAfee Inc., under contract to Apple Computer Inc. in 2003.
290It was subsequently adopted by the TrustedBSD Project as the foundation for
291the OpenBSM distribution.
|