--- name: "auditon" section: "2" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd", "macos"] url: "https://new.carta.tech/auditon" --- # auditon(2) configure system audit parameters ## NAME **auditon** – configure system audit parameters ## SYNOPSIS **#include \** *int*\ **auditon**(*int cmd*, *void \*data*, *u\_int length*); ## DESCRIPTION The **auditon**() system call is used to manipulate various audit control operations. The *data* argument should point to a structure whose type depends on the command. The *length* argument specifies the size of *\*data* in bytes. The *cmd* argument may be any of the following: - A\_SETPOLICY Set audit policy flags. The *data* argument must point to a *int* value set to one or more the following audit policy control values bitwise OR'ed together: AUDIT\_CNT, AUDIT\_AHLT, AUDIT\_ARGV, and AUDIT\_ARGE. If AUDIT\_CNT is set, the system will continue even if it becomes low on space and discontinue logging events until the low space condition is remedied. If it is not set, audited events will block until the low space condition is remedied. Unaudited events, however, are unaffected. If AUDIT\_AHLT is set, a [panic(9)](/panic/9.md) if it cannot write an event to the global audit log file. If AUDIT\_ARGV is set, then the argument list passed to the [execve(2)](/execve/2.md) system call will be audited. If AUDIT\_ARGE is set, then the environment variables passed to the [execve(2)](/execve/2.md) system call will be audited. The default policy is none of the audit policy control flags set. - A\_SETKAUDIT Set the host information. The *data* argument must point to a *auditinfo\_addr\_t* structure containing the host IP address information. After setting, audit records that are created as a result of kernel events will contain this information. - A\_SETKMASK Set the kernel preselection masks (success and failure). The *data* argument must point to a *au\_mask\_t* structure containing the mask values as defined in ⟨bsm/audit.h⟩. These masks are used for non-attributable audit event preselection. The field *am\_success* specifies which classes of successful audit events are to be logged to the audit trail. The field *am\_failure* specifies which classes of failed audit events are to be logged. The value of both fields is the bitwise OR'ing of the audit event classes specified in *bsm/audit.h*. The various audit classes are described more fully in [audit\_class(5)](/audit_class/5.md). - A\_SETQCTRL Set kernel audit queue parameters. The *data* argument must point to a *au\_qctrl\_t* structure (defined in ⟨bsm/audit.h⟩) containing the kernel audit queue control settings: *aq\_hiwater*, *aq\_lowater*, *aq\_bufsz*, *aq\_delay*, and *aq\_minfree*. The field *aq\_hiwater* defines the maximum number of audit record entries in the queue used to store the audit records ready for delivery to disk. New records are inserted at the tail of the queue and removed from the head. For new records which would exceed the high water mark, the calling thread is inserted into the wait queue, waiting for the audit queue to have enough space available as defined with the field *aq\_lowater*. The field *aq\_bufsz* defines the maximum length of the audit record that can be supplied with [audit(2)](/audit/2.md). The field *aq\_delay* is unused. The field *aq\_minfree* specifies the minimum amount of free blocks on the disk device used to store audit records. If the value of free blocks falls below the configured minimum amount, the kernel informs the audit daemon about low disk space. The value is to be specified in percent of free file system blocks. A value of 0 results in a disabling of the check. The default and maximum values (default/maximum) for the audit queue control parameters are: | | | | --- | --- | | aq\_hiwater | 100/10000 (audit records) | | aq\_lowater | 10/aq\_hiwater (audit records) | | aq\_bufsz | 32767/1048576 (bytes) | | aq\_delay | (Not currently used.) | - A\_SETSTAT Return ENOSYS. (Not implemented.) - A\_SETUMASK Return ENOSYS. (Not implemented.) - A\_SETSMASK Return ENOSYS. (Not implemented.) - A\_SETCOND Set the current auditing condition. The *data* argument must point to a *int* value containing the new audit condition, one of AUC\_AUDITING, AUC\_NOAUDIT, or AUC\_DISABLED. If AUC\_NOAUDIT is set, then auditing is temporarily suspended. If AUC\_AUDITING is set, auditing is resumed. If AUC\_DISABLED is set, the auditing system will shutdown, draining all audit records and closing out the audit trail file. - A\_SETCLASS Set the event class preselection mask for an audit event. The *data* argument must point to a *au\_evclass\_map\_t* structure containing the audit event and mask. The field *ec\_number* is the audit event and *ec\_class* is the audit class mask. See [audit\_event(5)](/audit_event/5.md) for more information on audit event to class mapping. - A\_SETPMASK Set the preselection masks for a process. The *data* argument must point to a *auditpinfo\_t* structure that contains the given process's audit preselection masks for both success and failure. The field *ap\_pid* is the process id of the target process. The field *ap\_mask* must point to a *au\_mask\_t* structure which holds the preselection masks as described in the A\_SETKMASK section above. - A\_SETFSIZE Set the maximum size of the audit log file. The *data* argument must point to a *au\_fstat\_t* structure with the *af\_filesz* field set to the maximum audit log file size. A value of 0 indicates no limit to the size. - A\_GETCLASS Return the event to class mapping for the designated audit event. The *data* argument must point to a *au\_evclass\_map\_t* structure. See the A\_SETCLASS section above for more information. - A\_GETKAUDIT Get the current host information. The *data* argument must point to a *auditinfo\_addr\_t* structure. - A\_GETPINFO Return the audit settings for a process. The *data* argument must point to a *auditpinfo\_t* structure which will be set to contain *ap\_auid* (the audit ID), *ap\_mask* (the preselection mask), *ap\_termid* (the terminal ID), and *ap\_asid* (the audit session ID) of the given target process. The process ID of the target process is passed into the kernel using the *ap\_pid* field. See the section A\_SETPMASK above and [getaudit(2)](/getaudit/2.md) for more information. - A\_GETPINFO\_ADDR Return the extended audit settings for a process. The *data* argument must point to a *auditpinfo\_addr\_t* structure which is similar to the *auditpinfo\_t* structure described above. The exception is the *ap\_termid* (the terminal ID) field which points to a *au\_tid\_addr\_t* structure can hold much a larger terminal address and an address type. The process ID of the target process is passed into the kernel using the *ap\_pid* field. See the section A\_SETPMASK above and [getaudit(2)](/getaudit/2.md) for more information. - A\_GETSINFO\_ADDR Return the extended audit settings for a session. The *data* argument must point to a *auditinfo\_addr\_t* structure. The audit session ID of the target session is passed into the kernel using the *ai\_asid* field. See [getaudit\_addr(2)](/getaudit_addr/2.md) for more information about the *auditinfo\_addr\_t* structure. - A\_GETKMASK Return the current kernel preselection masks. The *data* argument must point to a *au\_mask\_t* structure which will be set to the current kernel preselection masks for non-attributable events. - A\_GETPOLICY Return the current audit policy setting. The *data* argument must point to a *int* value which will be set to one of the current audit policy flags. The audit policy flags are described in the A\_SETPOLICY section above. - A\_GETQCTRL Return the current kernel audit queue control parameters. The *data* argument must point to a *au\_qctrl\_t* structure which will be set to the current kernel audit queue control parameters. See the A\_SETQCTL section above for more information. - A\_GETFSIZE Returns the maximum size of the audit log file. The *data* argument must point to a *au\_fstat\_t* structure. The *af\_filesz* field will be set to the maximum audit log file size. A value of 0 indicates no limit to the size. The *af\_currsz* field will be set to the current audit log file size. - A\_GETCWD Return ENOSYS. (Not implemented.) - A\_GETCAR Return ENOSYS. (Not implemented.) - A\_GETSTAT Return ENOSYS. (Not implemented.) - A\_GETCOND Return the current auditing condition. The *data* argument must point to a *int* value which will be set to the current audit condition, one of AUC\_AUDITING, AUC\_NOAUDIT or AUC\_DISABLED. See the A\_SETCOND section above for more information. - A\_SENDTRIGGER Send a trigger to the audit daemon. The *data* argument must point to a *int* value set to one of the acceptable trigger values: AUDIT\_TRIGGER\_LOW\_SPACE (low disk space where the audit log resides), AUDIT\_TRIGGER\_OPEN\_NEW (open a new audit log file), AUDIT\_TRIGGER\_READ\_FILE (read the *audit\_control* file), AUDIT\_TRIGGER\_CLOSE\_AND\_DIE (close the current log file and exit), AUDIT\_TRIGGER\_NO\_SPACE (no disk space left for audit log file). AUDIT\_TRIGGER\_ROTATE\_USER (request audit log file rotation). AUDIT\_TRIGGER\_INITIALIZE (initialize audit subsystem for Mac OS X only). or AUDIT\_TRIGGER\_EXPIRE\_TRAILS (request audit log file expiration). ## RETURN VALUES The **auditon()** function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. ## ERRORS The **auditon**() function will fail if: - \[ENOSYS\] Returned by options not yet implemented. - \[EFAULT\] A failure occurred while data transferred to or from the kernel failed. - \[EINVAL\] Illegal argument was passed by a system call. - \[EPERM\] The process does not have sufficient permission to complete the operation. The A\_SENDTRIGGER command is specific to the FreeBSD and Mac OS X implementations, and is not present in Solaris. ## SEE ALSO [audit(2)](/audit/2.md), [auditctl(2)](/auditctl/2.md), [getaudit(2)](/getaudit/2.md), [getaudit\_addr(2)](/getaudit_addr/2.md), [getauid(2)](/getauid/2.md), [setaudit(2)](/setaudit/2.md), [setaudit\_addr(2)](/setaudit_addr/2.md), [setauid(2)](/setauid/2.md), [libbsm(3)](/libbsm/3.md) ## 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. ## AUTHORS This software was created by McAfee Research, the security research division of McAfee, Inc., under contract to Apple Computer Inc. Additional authors include Wayne Salamon, Robert Watson, and SPARTA Inc. The Basic Security Module (BSM) interface to audit records and audit event stream format were defined by Sun Microsystems. This manual page was written by Tom Rhodes ⟨trhodes@FreeBSD.org⟩, Robert Watson ⟨rwatson@FreeBSD.org⟩, and Wayne Salamon ⟨wsalamon@FreeBSD.org⟩.