linux-system-roles.auditd

This role installs the audit subsystem packages, renders /etc/audit/auditd.conf from variables (defaults follow clear_config() in audit-userspace auditd-config.c), and optionally manages rules.d/custom.rules. Option semantics and allowed values are described in auditd.conf(5).

This role is heavily based on ansible-role-auditd

This role contains a substantial amount of code generated by Claude opus-4.6

Requirements

See below.

Collection requirements

To manage rpm-ostree systems, install collections on the control node:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Role variables

Unless noted, keywords are case-insensitive in auditd.conf (this role writes the values you set) but all UPPERCASE is preferred and is used below. Boolean role variables for yes/no daemon options are rendered as the strings yes or no in the config file. Validation is enforced by meta/argument_specs.yml and tasks/assert_role_vars.yml using the same limits as the audit-userspace parsers (for example num_logs <= 999).

auditd_local_events

Default: true

Type: bool

Whether local audit events are processed.

auditd_write_logs

Default: true

Type: bool

Whether auditd writes logs.

auditd_log_file

Default: /var/log/audit/audit.log

Type: str (path)

Path to the audit log file.

auditd_log_format

Default: ENRICHED

Type: str

Log format. Allowed: RAW, NOLOG, ENRICHED.

auditd_log_group

Default: root

Type: str

Group of the audit log file (name or numeric GID).

auditd_flush

Default: INCREMENTAL_ASYNC

Type: str

Flush technique. Allowed: NONE, INCREMENTAL, INCREMENTAL_ASYNC, DATA, SYNC.

auditd_freq

Default: 50

Type: int

Flush frequency in records (digits only; must be <= INT_MAX). If auditd_flush is INCREMENTAL or INCREMENTAL_ASYNC, this must be greater than zero.

auditd_num_logs

Default: 5

Type: int

Number of log files to keep when rotating; digits only, 0–999.

auditd_name_format

Default: NONE

Type: str

How the node name is determined. Allowed: NONE, HOSTNAME, FQD, NUMERIC, USER.

auditd_name

Default: ""

Type: str

Node name; required when auditd_name_format is USER. When empty, the line is omitted from the config.

auditd_max_log_file

Default: 8

Type: int

Maximum log file size in megabytes (digits only).

auditd_max_log_file_action

Default: ROTATE

Type: str

Action when the size limit is reached. Allowed: IGNORE, SYSLOG, EXEC, SUSPEND, ROTATE, KEEP_LOGS. For EXEC, set auditd_max_log_file_action_exe to an absolute executable path.

auditd_max_log_file_action_exe

Default: ""

Type: str

Absolute path to the executable used when auditd_max_log_file_action is EXEC.

auditd_space_left

Default: "75"

Type: str

Free space threshold: megabytes as a number, or a percentage such as 25% (must be < 100%). Value must be greater than auditd_admin_space_left.

auditd_space_left_action

Default: SYSLOG

Type: str

Action when free space drops below auditd_space_left. Allowed: IGNORE, SYSLOG, ROTATE, EMAIL, EXEC, SUSPEND, SINGLE. (HALT is not accepted by auditd for this key.) For EXEC, set auditd_space_left_action_exe.

auditd_space_left_action_exe

Default: ""

Type: str

Absolute path for EXEC with auditd_space_left_action.

auditd_action_mail_acct

Default: root

Type: str

Account for mail actions.

auditd_verify_email

Default: true

Type: bool

Whether to validate mail account format when possible.

auditd_admin_space_left

Default: "50"

Type: str

Admin free-space threshold (MiB or N% as for auditd_space_left). Value must be less than auditd_space_left.

auditd_admin_space_left_action

Default: SUSPEND

Type: str

Action when admin threshold is crossed. Same keyword set as other failure actions; for EXEC set auditd_admin_space_left_action_exe.

auditd_admin_space_left_action_exe

Default: ""

Type: str

Absolute path for EXEC with auditd_admin_space_left_action.

auditd_disk_full_action

Default: SUSPEND

Type: str

Action when the partition is full. EMAIL is not allowed. For EXEC, set auditd_disk_full_action_exe.

auditd_disk_full_action_exe

Default: ""

Type: str

Absolute path for EXEC with auditd_disk_full_action.

auditd_disk_error_action

Default: SUSPEND

Type: str

Action on disk I/O errors. EMAIL and ROTATE are not allowed. For EXEC, set auditd_disk_error_action_exe.

auditd_disk_error_action_exe

Default: ""

Type: str

Absolute path for EXEC with auditd_disk_error_action.

auditd_priority_boost

Default: 4

Type: int

Non-negative integer, <= INT_MAX.

auditd_tcp_listen_port

Default: 0

Type: int

Listen port (0–65535). The value of 0 means this parameter is omitted from auditd.conf, and the listener is disabled (the default).

auditd_tcp_listen_queue

Default: 5

Type: int

Queue depth (0–65535).

auditd_tcp_max_per_addr

Default: 1

Type: int

Maximum parallel connections per address (1–1024).

auditd_use_libwrap

Default: true

Type: bool

Use libwrap.

auditd_tcp_client_ports

Default: 0

Type: str

Client port range, either LOW or LOW-HIGH (digits only). The max value is 65535. The value 0 means to omit this setting from auditd.conf.

auditd_tcp_client_max_idle

Default: 0

Type: int

Idle time in seconds (0–INT_MAX).

auditd_transport

Default: TCP

Type: str

Allowed: TCP, KRB5 (Kerberos only if auditd was built with GSSAPI). If you set auditd_enable_krb5: true then the KRB5 transport will be used. If you want to use auditd_transport to set the transport, ensure auditd_enable_krb5 is unset.

auditd_enable_krb5

Default: false

Type: bool

If true, enables KRB5 transport when supported. If false or unset, the value of auditd_transport will be used. It is recommended to use auditd_transport instead of this parameter to set the transport.

auditd_krb5_principal

Default: auditd

Type: str

Kerberos principal name.

auditd_krb5_key_file

Default: ""

Type: str

Path to Kerberos keytab; if empty, the krb5_key_file line is omitted.

auditd_distribute_network

Default: false

Type: bool

If true, distribute network originating events to the audit dispatcher for processing.

auditd_q_depth

Default: 2000

Type: int

Size of internal queue for the audit event dispatcher; 0–99999.

auditd_overflow_action

Default: SYSLOG

Type: str

Allowed: IGNORE, SYSLOG, SUSPEND, SINGLE, HALT.

auditd_max_restarts

Default: 10

Type: int

Maximum plugin restarts (0–INT_MAX).

auditd_plugin_dir

Default: /etc/audit/plugins.d

Type: str (path)

Plugin directory; you probably won't need to change this.

auditd_end_of_event_timeout

Default: 2

Type: int

End-of-event timeout in seconds.

auditd_report_interval

Default: "0"

Type: str

Interval string accepted by time_string_to_seconds (see auditd.conf(5)); must not exceed 40 days in auditd.

auditd_buffer_size

Default: 32768

Type: int

Audit rules: buffer size (-b). Must be a positive number.

auditd_fail_mode

Default: 1

Type: int

Audit rules: failure mode flag (-f). Valid values are:

• 0 - silent
• 1 - printk
• 2 - panic - most secure option

auditd_maximum_rate

Default: 0

Type: int

Audit rules: maximum messages per second (-r).

auditd_backlog_wait_time

Default: 60000

Type: int

Audit rules: backlog wait time.

auditd_enable_flag

Default: 1

Type: int

Audit rules: audit enable flag (-e). Valid values are:

• 0 - disable auditing
• 1 - enable auditing
• 2 - lock configuration

auditd_loginuid_immutable

Default: false

Type: bool

If true, make loginuids unchangeable once they are set. Once the kernel has this active (loginuid_immutable 1 in auditctl -s), it cannot be cleared without a reboot. If you set this role parameter to false while the kernel still reports immutable, the role sets the exported variable auditd_reboot_required to true unless auditd_reboot_ok is true, in which case the role reboots the host and then continues.

auditd_manage_rules

Default: true

Type: bool

If true, template rules.d/custom.rules. If false, the rules file is not managed.

auditd_purge_rules

Default: false

Type: bool

If true, delete every file under rules.d/ (typically /etc/audit/rules.d) before applying the role's rules. Other fragments are always removed. custom.rules is removed as well unless auditd_manage_rules is true and the file on disk already matches the rendered auditd_rules template (comparison uses the rule body from the first -D line onward, so preamble differences do not force a rewrite). In that matching case the deploy task for custom.rules is skipped so a second run reports changed: false.

auditd_reboot_ok

Default: false

Type: bool

If true, the role may reboot the managed host when auditd_loginuid_immutable is false but the kernel still has loginuid immutability enabled (see auditd_loginuid_immutable). Use only when an immediate reboot is acceptable.

auditd_start_service

Default: true

Type: bool

If true, enable/start auditd and allow rule load handler behavior that requires a running audit stack.

auditd_rules

Default: []

Type: list (elements: dict)

Required keys

Key	Type	Description
action	str	always or never (case-insensitive in validation).
filter	str	One of exclude, exit, filesystem, io_uring, task, user.

• if filter: filesystem then one field entry must be exactly fstype=debugfs or fstype=tracefs.
• if filter: io_uring then arch is not required; omitting arch does not trigger the missing-arch warning.
• filter: io_uring is only available on EL9 and later
• if syscall is set, filter must be exit or io_uring (syscall rules are not valid with other filter types).

Optional keys

Key	Type	Description
arch	str or list of str	CPU architecture for syscall rules (for example b64, b32). Strongly recommended for exit rules; the role emits a warning when it is omitted (except for filter: io_uring). Use the literal nowarn to omit the arch from the rule and silence the warning (i.e. you know what you are doing). If arch is a list, the role emits one rule line per list entry (same action, filter, syscall, path, permission, field, and keyname). arch is not required when using filter: io_uring.
path	str	File path filter. Mutually exclusive with dir. Requires filter: exit. Strongly recommended to use either permission or syscall. Role will warn unless you use permission: nowarn.
dir	str	Directory path filter. Mutually exclusive with path. Requires filter: exit. Strongly recommended to use either permission or syscall. Role will warn unless you use permission: nowarn.
permission	str or list of str	One or more permission tokens mapped to audit perm= letters via read->r, write->w, execute->x, attribute_change->a. Strongly recommended to use this or syscall when path or dir is set. Use permission: nowarn to omit permissions from the rule and silence the warning (i.e. you know what you are doing).
syscall	str, int, or list of str/int	Syscall name(s) or number(s). Requires filter: exit or filter: io_uring.
field	str or list of str	Extra field fragment(s) to filter on (nameOPvalue). OP must be one of =, !=, <, >, <=, >=, &, &=.
keyname	str or list of str	One or more search keys for the rule. Each key must be 31 characters or fewer.

Variables Exported by the Role

auditd_auditctl_settings_previous

These are the settings printed by auditctl -s prior to applying the new settings.

auditd_reboot_required

Type: bool (host variable set by the role)

Set to true when the kernel still has loginuid immutability enabled but the role is configured with auditd_loginuid_immutable: false and auditd_reboot_ok is not true. After a successful reboot triggered by the role to clear that state, or when no reboot is needed, this is false.

Example playbook

- name: Manage auditd
  hosts: all
  vars:
    auditd_num_logs: 5
    auditd_flush: incremental_async
    auditd_freq: 50
    auditd_rules:
      - action: always
        filter: exit
        arch: [b32, b64]
        path: /etc/passwd
        permission: write
        filter:
          - auid>=1000
          - auid!=unset
        keyname:
          - etc_passwd
          - invalid_write
  roles:
    - linux-system-roles.auditd

More examples are under examples/.

rpm-ostree

See README-ostree.md.

License

MIT.

Author Information

Maintained as part of Linux System Roles.