fedora.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

None.

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:
    - fedora.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.