Provided by: audispd-plugins_4.0.1-1ubuntu2_amd64 
NAME
audisp-remote.conf - the audisp-remote configuration file
DESCRIPTION
audisp-remote.conf is the file that controls the configuration of the audit remote logging
subsystem. The options that are available are as follows:
remote_server
This is a one word character string that is the remote server hostname or address
that this plugin will send log information to. This can be the numeric address or a
resolvable hostname.
port This option is an unsigned integer that indicates what port to connect to on the
remote machine.
local_port
This option is an unsigned integer that indicates what local port to connect from
on the local machine. If unspecified (the default) or set to the word any then any
available unprivileged port is used. This is a security mechanism to prevent
untrusted user space apps from injecting events into the audit daemon. You should
set it to an unused port < 1024 to ensure that only privileged users can bind to
that port. Then also set the tcp_client_ports in the aggregating auditd.conf file
to match the ports that clients are sending from.
transport
This parameter tells the remote logging app how to send events to the remote
system. The valid options are TCP, and KRB5. If set to TCP, the remote logging app
will just make a normal clear text connection to the remote system. If its set to
KRB5, then Kerberos 5 will be used for authentication and encryption. The default
value is TCP.
mode This parameter tells the remote logging app what strategy to use getting records to
the remote system. Valid values are immediate, and forward . If set to immediate,
the remote logging app will attempt to send events immediately after getting them.
forward means that it will store the events to disk and then attempt to send the
records. If the connection cannot be made, it will queue records until it can
connect to the remote system. The depth of the queue is controlled by the
queue_depth option.
queue_file
Path of a file used for the event queue if mode is set to forward. The default is
/var/spool/audit/remote.log.
queue_depth
This option is an unsigned integer that determines how many records can be buffered
to disk or in memory before considering it to be a failure sending. This parameter
affects the forward mode of the mode option and internal queueing for temporary
network outages. The default depth is 2048.
format This parameter tells the remote logging app what data format will be used for the
messages sent over the network. The default is managed which adds some overhead to
ensure 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. 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 something more robust
is needed, use the managed format. If mode is set to forward, 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, as even a completely successful delivery requires at least
one try. 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, as 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
This parameter 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 has not terminated in a way that it did not shutdown the
connection 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
This parameter tells the system what action to take whenever there is an error
detected when sending audit events to the remote system. Valid values are ignore,
syslog, exec, warn_once, suspend, single, halt, and stop. If set to ignore, the
remote logging app does nothing. If an event was sent, its dequeued. Syslog means
that it will issue a warning to syslog. If an event was sent, its 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, its 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 will cause 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. The single option will cause the remote logging app to
put the computer system in single user mode. If an event was sent, it is not
dequeued. The stop option will cause the remote logging app to exit, but leave
other plugins running. If an event was sent, it is not dequeued. The halt option
will cause 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
This parameter tells the system what action to take if the internal event queue
overflows. Valid values are ignore, syslog, suspend, single, and halt . If set to
ignore, the remote logging app does nothing. Syslog means that it will issue a
warning to syslog. This is the default. Suspend will cause the remote logging app
to stop sending records to the remote system. The logging app will still be alive.
The single option will cause the remote logging app to put the computer system in
single user mode. The halt option will cause the remote logging app to shutdown the
computer system.
startup_failure_action
This parameter tells the system what action to take whenever there is an error
connecting to the remote system during startup. Typically, this is benign as 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 . If set to ignore, the remote
logging app does nothing. Syslog means that 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. This would be 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.
krb5_client_name
This specifies the name portion of the client's own principal. If unspecified, the
default is "auditd". The remainder of the principal will consist of the host's
fully qualified domain name and the default Kerberos realm, like this:
auditd/host14.example.com@EXAMPLE.COM (assuming you gave "auditd" as the
krb_client_name). Note that the client and server must have the same principal
name and realm.
krb5_key_file
Location of the key for this client's principal. Note that the key file must be
owned by root and mode 0400. The default is /etc/audisp/audisp-remote.key
NOTES
Specifying a local port may make it difficult to restart the audit subsystem due to the
previous connection being in a TIME_WAIT state, if you're reconnecting to and from the
same hosts and ports as before.
The network failure logic works as follows: 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 continues to pause and retry 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.
SEE ALSO
audisp-remote(8), auditd.conf(5).
AUTHOR
Steve Grubb