AUDISP-REMOTE.CONF(5)

📦
version 4.2.1 · 3 versions
, in arch rolling, centos-stream 10, fedora 43, fedora 44, nixpkgs unstable

✨ NAME ✨

audisp-remote.conf — it's the audisp-remote configuration file, bestie. Yes, this is that manual page, and we're getting through it together 💖

💖 DESCRIPTION 💖

audisp-remote.conf is the file that controls the configuration of the audit remote logging subsystem. It's basically the settings sheet that tells the remote-logging plugin how to behave, and the options you can put in it are, in order, these ones:

  • remote_server — a one word character string holding the hostname or address of the remote server this plugin sends log info to. It can be a numeric address, or a hostname that actually resolves. Either is fine 🦋
  • port — an unsigned integer that says which port to connect to on the remote machine.
  • local_port — an unsigned integer that says which local port to connect from on the local machine. If you don't specify it (that's the default) or you set it to the word any, then any available unprivileged port gets used. Here's the tea though: this is a security mechanism to stop untrusted user space apps from injecting events into the audit daemon. You should set it to an unused port < 1024 so that only privileged users can bind to that port. And then you also set the tcp_client_ports in the aggregating auditd.conf file to match the ports the clients are sending from. Coordinated, like a group chat 🫶
  • transport — this one tells the remote logging app how to send events over to the remote system. Valid options are TCP, TLS, and KRB5.
    • Set it to TCP and the remote logging app just makes a normal clear text connection to the remote system. No vibes, no encryption, just talking.
    • Set it to TLS and the connection gets encrypted using TLS 1.3 with post-quantum hybrid key exchange ✨. This requires a pre-shared key (tls_psk_file) to be configured. Also note: TLS transport requires format=managed — the ascii format does not support TLS encryption, periodt.
    • Set it to KRB5 and Kerberos 5 handles authentication and encryption.
    • The default value is TCP.
  • mode — tells the remote logging app what strategy to use getting records to the remote system. Valid values are immediate and forward.
    • immediate means it tries to send events immediately after getting them.
    • forward means it stores the events to disk and then attempts to send the records. If the connection can't be made, it queues records until it can connect to the remote system. How deep that queue goes is controlled by the queue_depth option.
  • queue_file — the path of a file used for the event queue when mode is set to forward. The default is /var/spool/audit/remote.log.
  • queue_depth — an unsigned integer that determines how many records can be buffered to disk or in memory before it's considered a failure sending. This parameter affects the forward mode of the mode option, plus the internal queueing for temporary network outages. The default depth is 2048.
  • format — tells the remote logging app what data format gets used for the messages sent over the network. The default is managed, which adds some overhead to make sure each message is properly handled on the remote end, and to receive status messages from the remote server. If ascii is given instead, each message is a simple ASCII text line with no overhead at all. Heads up though: the ascii format is a very simplistic protocol. If there are any network problems, it will cause audisp-remote to exit. Auditd may or may not restart it on next event 😭. If you need something more robust, use the managed format. And if mode is set to forward, then format must be managed.
  • network_retry_time — the time, in seconds, between retries when a network error is detected. Note that this pause applies starting after the second attempt, so as to avoid unneeded delays if a reconnect is sufficient to fix the problem. The default is 1 second.
  • max_tries_per_record — the maximum number of times an attempt is made to deliver each message. The minimum value is one, because even a completely successful delivery requires at least one try (obvi 💅). If too many attempts are made, the network_failure_action action is performed. The default is 3.
  • max_time_per_record — the maximum amount of time, in seconds, spent attempting to deliver each message. Note that both this and max_tries_per_record should be set, since each try may take a long time to time out. The default value is 5 seconds. If too much time is used on a message, the network_failure_action action is performed.
  • heartbeat_timeout — determines how often, in seconds, the client should send a heartbeat event to the remote server. This is used to let both the client and server know that each end is alive and hasn't terminated in a way that it didn't shut the connection down uncleanly. This value must be coordinated with the server's tcp_client_max_idle setting. The default value is 0, which disables sending a heartbeat.
  • network_failure_action — tells the system what action to take whenever there's an error detected when sending audit events to the remote system. Valid values are ignore, syslog, exec, warn_once, suspend, single, halt, and stop.
    • ignore → the remote logging app does nothing. If an event was sent, it's dequeued.
    • syslog → it will issue a warning to syslog. If an event was sent, it's dequeued. This is the default.
    • exec /path-to-script → will execute the script. You cannot pass parameters to the script. If an event was sent, it's dequeued.
    • warn_once_continue is like syslog except that only one message is put in syslog until an event is successfully transferred.
    • warn_once is like warn_once_continue except that the event is not dequeued.
    • suspend → causes the remote logging app to stop sending records to the remote system. The logging app will still be alive. If an event was sent, it is not dequeued.
    • single → causes the remote logging app to put the computer system in single user mode. If an event was sent, it is not dequeued.
    • stop → causes the remote logging app to exit, but leaves other plugins running. If an event was sent, it is not dequeued.
    • halt → causes the remote logging app to shutdown the computer system. If an event was sent, it is not dequeued.
    • The default is to stop.
  • disk_low_action — likewise, this parameter tells the system what action to take if the remote end signals a disk low error. The default is ignore.
  • disk_full_action — likewise, this parameter tells the system what action to take if the remote end signals a disk full error. The default is warn_once.
  • disk_error_action — likewise, this parameter tells the system what action to take if the remote end signals a disk error. The default is warn_once.
  • remote_ending_action — likewise, this parameter tells the system what action to take if the network connection is lost. This action has one additional option, reconnect, which tells the remote plugin to attempt to reconnect to the server upon receipt of the next audit record. If an event was being sent when something triggered this action, it is not dequeued. If it is unsuccessful in reconnecting, the audit record could be lost 😬. The default is to reconnect.
  • generic_error_action — likewise, this parameter tells the system what action to take if the remote end signals an error we don't recognize. The default is to log it to syslog.
  • generic_warning_action — likewise, this parameter tells the system what action to take if the remote end signals a warning we don't recognize. The default is to log it to syslog.
  • queue_error_action — likewise, this parameter tells the system what action to take if there is a problem working with a local record queue. The default is stop.
  • overflow_action — tells the system what action to take if the internal event queue overflows. Valid values are ignore, syslog, suspend, single, and halt.
    • ignore → the remote logging app does nothing.
    • syslog → it will issue a warning to syslog. This is the default.
    • suspend → causes the remote logging app to stop sending records to the remote system. The logging app will still be alive.
    • single → causes the remote logging app to put the computer system in single user mode.
    • halt → causes the remote logging app to shutdown the computer system.
  • startup_failure_action — tells the system what action to take whenever there's an error connecting to the remote system during startup. Typically this is benign, since the plugin's default behavior is to attempt reconnecting until it succeeds. But there may be times when you want to do something different. Valid values are ignore, syslog, exec, warn_once, and warn_once_continue.
    • ignore → the remote logging app does nothing.
    • syslog → it will issue a warning to syslog.
    • exec /path-to-script → will execute the script. You cannot pass parameters to the script.
    • warn_once is like syslog except that only one message is put in syslog until an event is successfully transferred.
    • warn_once_continue is like warn_once except it ignores the problem. This is the default.
  • enable_krb5 — ⚠️ this option is deprecated. Use the transport option to enable Kerberos support. If this option follows the transport configuration option, it will override the transport setting — that's the normal expected behavior for backwards compatibility. If set to yes, Kerberos 5 will be used for authentication and encryption. Default is no. Note that encryption can only be used with managed connections, not plain ASCII.
  • krb5_principal — if specified, this is the expected principal for the server. The client and server will use the specified principal to negotiate the encryption. The format for the krb5_principal is like somename/hostname — see the auditd.conf man page for details. If not specified, the krb5_client_name and remote_server values are used.
okay that was a LOT of options and we're only getting started, stay with me bestie, there's more 🧚
  • krb5_client_name — this is the name part of the client's own principal. Leave it blank and the default is "auditd". The rest of the principal gets built from the host's fully qualified domain name plus the default Kerberos realm, so it ends up looking like this: auditd/host14.example.com@EXAMPLE.COM (that's assuming you passed "auditd" as the krb_client_name). Heads up bestie: the client and the server must have the same principal name and realm. no exceptions 💅
  • krb5_key_file — where the key for this client's principal lives. Okay so important: the key file must be owned by root and mode 0400. Default is /etc/audisp/audisp-remote.key.
  • tls_auth — the TLS authentication mode. rn only psk is supported, that's it. Default is psk.
  • tls_crypto_profile — picks the cryptographic profile for TLS. Valid values are compatible, system, and pqc.
    • compatible uses robust classical TLS 1.3 PSK with opportunistic PQC hybrid key exchange.
    • system defers all cipher and group selection to the system crypto policy. For FIPS deployments, configure the host for FIPS mode and use this profile.
    • pqc requires post-quantum hybrid key exchange.
    • Default is compatible. ✨
  • tls_psk_file — path to a file containing a hex-encoded pre-shared key for TLS-PSK authentication. The key must be at least 32 bytes (that's 64 hex characters, bestie). Generate one with: openssl rand -hex 32. And the file must be owned by root and mode 0400.
  • tls_psk_identity — the identity string that gets sent to the server during TLS-PSK authentication. This option is required when tls_psk_file is set. The identity must contain only printable ASCII characters (so no spaces, no control characters) and must not exceed 255 bytes. There is no default.
  • tls_cipher_suites — colon-separated list of TLS 1.3 cipher suites. This overrides the profile default. The default is "TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384".
  • tls_key_exchange — colon-separated list of key exchange groups. Overrides the profile default. PQC hybrid key exchange increases the TLS ClientHello size by approximately 1120 bytes. just so you know 🫶
  • tls_require_pqc — compatibility alias for tls_crypto_profile=pqc. If set to yes, it sets tls_crypto_profile to pqc. If set to no, it has no effect on tls_crypto_profile. New configurations should use tls_crypto_profile directly (the alias is giving legacy, lowkey).

🌸 NOTES 🌸

Changes to the TLS configuration options (tls_psk_file, tls_psk_identity, tls_cipher_suites, tls_key_exchange, tls_require_pqc, tls_auth, tls_crypto_profile) in the configuration file are not re-read on SIGHUP. BUT — and this is the plot twist — SIGHUP destroys the current TLS context and forces a full reconnection with a new context built from the current (unchanged) configuration. And because the PSK key file is re-read from disk during context creation, rotating the key file contents followed by SIGHUP will activate the new key. slay 🔥

Specifying a local port may make it difficult to restart the audit subsystem, because the previous connection is sitting in a TIME_WAIT state — that's when you're reconnecting to and from the same hosts and ports as before. 🙈

The network failure logic works like this: the first attempt to deliver normally "just works". If it doesn't, a second attempt is immediately made, perhaps after reconnecting to the server. If the second attempt also fails, audispd-remote pauses for the configured time and tries again. It keeps pausing and retrying until either too many attempts have been made or the allowed time expires. Note that these times govern the maximum amount of time the remote server is allowed in order to reboot, if you want to maintain logging across a reboot.

It is recommended to set a large q_depth in auditd.conf if using this plugin. Also set an even bigger q_depth in audisp-remote.conf. Also set the heartbeat_timeout to something non-zero, but coordinate it with the server so that it's half the size of the server's tcp_client_max_idle setting. This is required to get retries in a reasonable time if the network has a problem. fr fr don't skip this one.

👀 SEE ALSO 👀

audisp-remote(8), auditd.conf(5).

💜 AUTHOR 💜

Steve Grubb

okay that's the whole page bestie, you're officially an audisp-remote.conf girlie now 💅✨ this icon of a manpage came from Red Hat, dated Jul 2022, and it's the AUDISP-REMOTE.CONF(5) page — go forth and configure responsibly 🎀🦋

📦 where this page comes from