audit-userspace: the daemon behind the Linux audit trail

What the audit system is for, and where auditd sits in it

The Linux Audit System is designed to make Linux compliant with the requirements from Common Criteria, PCI-DSS and other security standards, by intercepting system calls and serializing audit log entries from privileged user space applications. The framework allows the configured events to be recorded to disk and distributed to plugins in realtime. Each audit event contains the date and time of the event, the type of event, the subject identity, the object acted upon, and the result of the action, success or fail, if applicable.

That description tells you the two halves of the system. The kernel intercepts the syscalls and knows what happened, and the userspace side takes those events, serialises them, stores them and fans them out.

The architecture section places auditd in the middle. It interfaces with the kernel to receive events, writes them to the audit logs, and also distributes events in realtime to audisp plugins. The kernel does the heavy lifting to generate the events: in the case of a trusted application such as shadow-utils, the kernel receives the event, adds origin information, timestamps it, and queues it for delivery to the audit daemon.

So the event enrichment happens in the kernel, where the process context is known, and the daemon's job is transport and storage. The repository listing shows the scale of that job: src/ for the daemon itself, audisp/ for the plugin system, auparse/ for parsing log files, auplugin/ for the plugin utilities, autls/ for the TLS support, common/, lib/, rules/, tools/, contrib/, init.d/ and bindings/.

The bindings/ directory is worth a note. The optional dependencies include python3-devel with swig, and golang, and openldap-devel for what the documentation calls zos-remote logging. The project is a C codebase that ships language bindings generated from a single implementation, which is why SWIG appears in the build list.

The licence is GPL-2.0, with both COPYING and COPYING.LIB present, which is the standard pairing for a project that mixes GPL code with library code.

The rule loading path changed in 4.0, and the tools moved with it

The architecture description in the README is also a change log, and the version markers in it are the useful part.

To load rules on a 3.x audit system, you use the augenrules program. As of audit-4.0, you would use the audit-rules.service with systemctl, which in turn uses auditctl to load rules into the kernel.

That is a real operational difference between an older host and a current one, and it is the kind of thing that catches people during a distribution upgrade. On 3.x, augenrules is a generator that merges the rule files in the rules/ directory into a single binary blob and hands it to the kernel. On 4.0 and later, the systemd unit does that job, and the rules directory in this repository is still there to be merged by the new path.

The description of auditctl itself is a good summary of what the control tool does. It is used to create, load and delete rules, to configure the kernel's backlog and other parameters, and to gather status about the audit system. The backlog is worth understanding, because it is the queue between the kernel and the daemon, and a daemon that cannot keep up fills the backlog and then loses events, which for a compliance system is the failure that matters.

The three tools therefore divide cleanly. augenrules and audit-rules.service are the two ways of getting rules into the kernel, auditctl is the interactive control surface, and auditd is the daemon that consumes the resulting events.

The auparse/ directory exists for reading the logs back, which is what you need when an auditor asks a question about what happened six months ago, and the auplugin/ directory is the plugin management side of audisp.

The disk space rules, which are a compliance requirement in disguise

The daemon considerations section starts with disk full, and it is the most practically important part of the README for anyone running this in production.

Almost all security standards are concerned about what happens when logging space fills up. Because of this, the audit daemon keeps careful track of free space and emits warnings at admin defined levels called space left and admin space left. The former is considered a low disk space warning which should give the admin time to do something. The latter is more serious because you are just about out.

Two configurable thresholds, and the distinction between them is a deadline rather than a severity. space left is the early warning, admin space left is the point at which the daemon is about to take a defensive action.

The recommendation that follows is the part that changes how you provision a machine. To get an accurate reading, the audit daemon should log to a disk partition that is reserved only for the audit daemon. This way someone using the logger command cannot suddenly fill up the audit space and trigger an admin defined action. It is recommended to set aside a partition, /var/log/audit, for exclusive use by the audit daemon, and the size of it depends on your audit retention policy.

The reasoning is about who else can write to the disk. A shared /var/log means any process, including a compromised one, can consume the space that the audit daemon needs, and then the daemon takes its emergency action, which is typically to stop logging. At that point the audit trail has a gap, and the gap is exactly the thing the compliance requirement exists to prevent.

So a dedicated partition is not a performance tweak, it is a control. It is also the reason the retention policy and the partition size have to be decided together rather than independently.

systemd-analyze security will break auditd, and the README says so

The systemd security section is a warning, and it is unusual enough that it is worth reading twice.

The audit daemon is started by systemd. Some people run the systemd-analyze security command, and it tells you all sorts of things to do to protect your system from auditd. However, doing the things it suggests places auditd in namespaces. When that happens, the audit rules may not trigger correctly and auditd may not be able to access trusted databases.

The reasoning is straightforward once you see it. Namespace isolation works by giving a process a restricted view of the filesystem, which is exactly what a security tool wants and exactly what a kernel-level audit consumer does not want. The audit rules are evaluated in the kernel against events the kernel generates, and the daemon has to be able to reach the system databases that describe the audited objects. Put it in a namespace and one of those two things breaks, silently, in a way that looks like the rules are simply not matching.

The auditd.service file is described as the result of trial and error based on well intentioned patches gone wrong. You can lock auditd down more, but it likely will not work as intended.

That is a good example of a project documenting a trap it has already hit, and the practical advice is simply to leave the unit alone.

The starting and stopping section covers the same ground from the other end. The systemctl application was designed to interact with systemd to control system services, using dbus to talk to systemd, which then works to carry out the command if the user is authorized to do so. This can create a problem on shutdown, and the section goes on to explain the Common Criteria requirement about recording anyone's interaction with the audit trail, including who stopped the daemon.

Building it, and the flags that decide what you get

The build section is a configure invocation with a set of flags that map directly onto the optional dependency list, and it is the clearest indicator of what the project expects you to enable.

cd audit
autoreconf -f --install
./configure --with-python3=yes --enable-gssapi-krb5=yes --with-arm \
    --with-aarch64 --with-libcap-ng=yes --without-golang --with-io_uring \
    --enable-tls
make
make install

The flags are readable if you map them to the dependency table. --with-python3=yes turns on the Python bindings, which needs python3-devel and swig. --enable-gssapi-krb5=yes turns on remote logging over Kerberos, which needs krb5-devel. --with-libcap-ng=yes enables dropping capabilities, which needs libcap-ng-devel. --enable-tls turns on TLS remote logging, which needs openssl. --with-arm and --with-aarch64 enable the ARM architectures, and --without-golang explicitly disables the Go bindings.

--with-io_uring is the one worth understanding on its own, because it is a kernel interface rather than a library. It means the daemon can use the io_uring asynchronous I/O path where the kernel supports it, which is a performance choice on a machine that is doing a lot of log writes.

Two notes on how to install it. If you are packaging this, you probably want to do make dist instead and use the resulting tar file with your package building framework, and a spec file is included in the git repo as an example of packaging it using rpm, with the explicit caveat that it is not known to be the official spec file used by any distribution.

The runtime requirements are a kernel of 5.15 or newer, systemd, coreutils and initscripts-service as a recommended soft requirement, and the build-time requirements are gcc or clang, make, kernel-headers of 5.15 or newer and systemd. The additional build-time dependencies for working from the git sources are autoconf, automake and libtool, which is what the autoreconf line above is for.

The moratorium on new platforms, and why the mail list matters

The supported architectures list is long, and then the note under it is the most consequential paragraph in the README.

There is a moratorium on adding support for any new platforms. Syscalls and other lookup tables get updated frequently. Without an active community maintaining the code, it is not sustainable to add more.

The mechanism is also specified. If you would like to see more platforms supported, you are asked to consider working on bugs and code cleanups and then maybe they can add more. Any submitted pull requests adding a new platform will be marked with a wont_fix label, and it will be left available in case anyone wants to use it, but it is unsupported.

The reasoning is sound and it is worth understanding. The userspace daemon has to know about kernel interfaces that change, and the syscall tables and the lookup tables behind them are maintained by hand. A platform that is not being tested is a platform whose tables are quietly wrong, and a compliance tool with wrong tables is worse than no tool, because it logs with confidence and gets the answer wrong.

So the policy is not a rejection of new architectures, it is a requirement that someone take responsibility for each one. The supported list is AARCH64, ARM for some versions, PPC and PPCLE, riscv32 and riscv64, s390 and s390x, and x86_64 and i386.

The cross compiling section says the same thing from a different angle. Cross compiling is not officially supported, there have been people who submitted patches to make it work, but it is not documented how, and it is likely that you have to override CC, CXX, RANLIB, AR, LD and NM when running configure. If you have patches that fix any problems, they will be merged.

For questions, the project points at a mail list rather than the issue tracker, and explains why: it is the best place to ask questions because the mail archive is searchable and therefore discoverable. For a project where the answer is likely to be in a three-year-old thread, that is the right call.

The release history supports the maintenance picture. Version 4.2.1 was published on 2026-07-29, 4.2 on 2026-07-23 and 4.1.4 on 2026-03-23, with the last push to the repository on 2026-10-10, and the repository is not archived.

Editorial conclusion

Adopt this repository if you are building a Linux system that has to satisfy a compliance standard, since the audit daemon is a compliance component rather than a monitoring convenience, and this is the code that implements it. Do not expect it to be cross-compilable or to gain new platform support, because the project states that cross compiling is not officially supported and that there is a moratorium on adding platforms. Before you deploy, set aside a dedicated partition for the audit logs, and read the systemd security notes, because hardening auditd with systemd-analyze breaks the rules that the compliance requirement depends on.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. linux-audit/audit-userspace on GitHub
4. README
5. Releases