1AUDISP-REMOTE.CONF(5) System Administration Utilities AUDISP-REMOTE.CONF(5)
2
6 audisp-remote.conf - the audisp-remote configuration file
7
9 audisp-remote.conf is the file that controls the configuration of the
10 audit remote logging subsystem. The options that are available are as
11 follows:
12 remote_server
15 This is a one word character string that is the remote server
16 hostname or address that this plugin will send log information
17 to. This can be the numeric address or a resolvable hostname.
18 port This option is an unsigned integer that indicates what port to
20 connect to on the remote machine.
21 local_port
23 This option is an unsigned integer that indicates what local
24 port to connect from on the local machine. If unspecified (the
25 default) or set to the word any then any available unprivileged
26 port is used. This is a security mechanism to prevent untrusted
27 user space apps from injecting events into the audit daemon. You
28 should set it to an unused port < 1024 to ensure that only priv‐
29 ileged users can bind to that port. Then also set the
30 tcp_client_ports in the aggregating auditd.conf file to match
31 the ports that clients are sending from.
32 transport
34 This parameter tells the remote logging app how to send events
35 to the remote system. The valid options are TCP, and KRB5. If
36 set to TCP, the remote logging app will just make a normal clear
37 text connection to the remote system. If its set to KRB5, then
38 Kerberos 5 will be used for authentication and encryption. The
39 default value is TCP.
40 mode This parameter tells the remote logging app what strategy to use
42 getting records to the remote system. Valid values are immedi‐
43 ate, and forward . If set to immediate, the remote logging app
44 will attempt to send events immediately after getting them.
45 forward means that it will store the events to disk and then at‐
46 tempt to send the records. If the connection cannot be made, it
47 will queue records until it can connect to the remote system.
48 The depth of the queue is controlled by the queue_depth option.
49 queue_file
51 Path of a file used for the event queue if mode is set to for‐
52 ward. The default is /var/spool/audit/remote.log.
53 queue_depth
55 This option is an unsigned integer that determines how many
56 records can be buffered to disk or in memory before considering
57 it to be a failure sending. This parameter affects the forward
58 mode of the mode option and internal queueing for temporary net‐
59 work outages. The default depth is 2048.
60 format This parameter tells the remote logging app what data format
62 will be used for the messages sent over the network. The de‐
63 fault is managed which adds some overhead to ensure each message
64 is properly handled on the remote end, and to receive status
65 messages from the remote server. If ascii is given instead,
66 each message is a simple ASCII text line with no overhead at
67 all. The ascii format is a very simplistic protocol. If there
68 are any network problems, it will cause audisp-remote to exit.
69 Auditd may or may not restart it on next event. If something
70 more robust is needed, use the managed format. If mode is set to
71 forward, format must be managed.
72 network_retry_time
74 The time, in seconds, between retries when a network error is
75 detected. Note that this pause applies starting after the sec‐
76 ond attempt, so as to avoid unneeded delays if a reconnect is
77 sufficient to fix the problem. The default is 1 second.
78 max_tries_per_record
80 The maximum number of times an attempt is made to deliver each
81 message. The minimum value is one, as even a completely suc‐
82 cessful delivery requires at least one try. If too many at‐
83 tempts are made, the network_failure_action action is performed.
84 The default is 3.
85 max_time_per_record
87 The maximum amount of time, in seconds, spent attempting to de‐
88 liver each message. Note that both this and
89 max_tries_per_record should be set, as each try may take a long
90 time to time out. The default value is 5 seconds. If too much
91 time is used on a message, the network_failure_action action is
92 performed.
93 heartbeat_timeout
95 This parameter determines how often in seconds the client should
96 send a heartbeat event to the remote server. This is used to let
97 both the client and server know that each end is alive and has
98 not terminated in a way that it did not shutdown the connection
99 uncleanly. This value must be coordinated with the server's
100 tcp_client_max_idle setting. The default value is 0 which dis‐
101 ables sending a heartbeat.
102 network_failure_action
104 This parameter tells the system what action to take whenever
105 there is an error detected when sending audit events to the re‐
106 mote system. Valid values are ignore, syslog, exec, warn_once,
107 suspend, single, halt, and stop. If set to ignore, the remote
108 logging app does nothing. If an event was sent, its dequeued.
109 Syslog means that it will issue a warning to syslog. If an event
110 was sent, its dequeued. This is the default. exec /path-to-
111 script will execute the script. You cannot pass parameters to
112 the script. If an event was sent, its dequeued. warn_once_con‐
113 tinue is like syslog except that only one message is put in sys‐
114 log until an event is successfully transferred. warn_once is
115 like warn_once_continue except that the event is not dequeued.
116 Suspend will cause the remote logging app to stop sending
117 records to the remote system. The logging app will still be
118 alive. If an event was sent, it is not dequeued. The single op‐
119 tion will cause the remote logging app to put the computer sys‐
120 tem in single user mode. If an event was sent, it is not de‐
121 queued. The stop option will cause the remote logging app to
122 exit, but leave other plugins running. If an event was sent, it
123 is not dequeued. The halt option will cause the remote logging
124 app to shutdown the computer system. If an event was sent, it is
125 not dequeued. The default is to stop.
126 disk_low_action
128 Likewise, this parameter tells the system what action to take if
129 the remote end signals a disk low error. The default is ignore.
130 disk_full_action
132 Likewise, this parameter tells the system what action to take if
133 the remote end signals a disk full error. The default is
134 warn_once.
135 disk_error_action
137 Likewise, this parameter tells the system what action to take if
138 the remote end signals a disk error. The default is warn_once.
139 remote_ending_action
141 Likewise, this parameter tells the system what action to take if
142 the network connection is lost. This action has one additional
143 option, reconnect which tells the remote plugin to attempt to
144 reconnect to the server upon receipt of the next audit record.
145 If an event was being sent when something triggered this action,
146 it is not dequeued. If it is unsuccessful in reconnecting, the
147 audit record could be lost. The default is to reconnect.
148 generic_error_action
150 Likewise, this parameter tells the system what action to take if
151 the remote end signals an error we don't recognize. The default
152 is to log it to syslog.
153 generic_warning_action
155 Likewise, this parameter tells the system what action to take if
156 the remote end signals a warning we don't recognize. The de‐
157 fault is to log it to syslog.
158 queue_error_action
160 Likewise, this parameter tells the system what action to take if
161 there is a problem working with a local record queue. The de‐
162 fault is stop.
163 overflow_action
165 This parameter tells the system what action to take if the in‐
166 ternal event queue overflows. Valid values are ignore, syslog,
167 suspend, single, and halt . If set to ignore, the remote log‐
168 ging app does nothing. Syslog means that it will issue a warn‐
169 ing to syslog. This is the default. Suspend will cause the re‐
170 mote logging app to stop sending records to the remote system.
171 The logging app will still be alive. The single option will
172 cause the remote logging app to put the computer system in sin‐
173 gle user mode. The halt option will cause the remote logging app
174 to shutdown the computer system.
175 startup_failure_action
177 This parameter tells the system what action to take whenever
178 there is an error connecting to the remote system during
179 startup. Typically, this is benign as the plugin's default be‐
180 havior is to attempt reconnecting until it succeeds. But there
181 may be times when you want to do something different. Valid val‐
182 ues are ignore, syslog, exec, warn_once, and warn_once_continue
183 . If set to ignore, the remote logging app does nothing. Sys‐
184 log means that it will issue a warning to syslog. exec /path-
185 to-script will execute the script. You cannot pass parameters to
186 the script. warn_once is like syslog except that only one mes‐
187 sage is put in syslog until an event is successfully trans‐
188 ferred. warn_once_continue is like warn_once except it ignores
189 the problem. This is the default.
190 enable_krb5
192 This option is deprecated. Use the transport option to enable
193 Kerberos support. If this option follows the transport configu‐
194 ration option, it will override the transport setting. This
195 would be the normal expected behavior for backwards compatibil‐
196 ity. If set to yes, Kerberos 5 will be used for authentication
197 and encryption. Default is no. Note that encryption can only
198 be used with managed connections, not plain ASCII.
199 krb5_principal
201 If specified, This is the expected principal for the server.
202 The client and server will use the specified principal to nego‐
203 tiate the encryption. The format for the krb5_principal is like
204 somename/hostname, see the auditd.conf man page for details. If
205 not specified, the krb5_client_name and remote_server values are
206 used.
207 krb5_client_name
209 This specifies the name portion of the client's own principal.
210 If unspecified, the default is "auditd". The remainder of the
211 principal will consist of the host's fully qualified domain name
212 and the default Kerberos realm, like this: auditd/host14.exam‐
213 ple.com@EXAMPLE.COM (assuming you gave "auditd" as the
214 krb_client_name). Note that the client and server must have the
215 same principal name and realm.
216 krb5_key_file
218 Location of the key for this client's principal. Note that the
219 key file must be owned by root and mode 0400. The default is
220 /etc/audisp/audisp-remote.key
221
225 Specifying a local port may make it difficult to restart the audit sub‐
226 system due to the previous connection being in a TIME_WAIT state, if
227 you're reconnecting to and from the same hosts and ports as before.
228 The network failure logic works as follows: The first attempt to de‐
230 liver normally "just works". If it doesn't, a second attempt is imme‐
231 diately made, perhaps after reconnecting to the server. If the second
232 attempt also fails, audispd-remote pauses for the configured time and
233 tries again. It continues to pause and retry until either too many at‐
234 tempts have been made or the allowed time expires. Note that these
235 times govern the maximum amount of time the remote server is allowed in
236 order to reboot, if you want to maintain logging across a reboot.
237 It is recommended to set a large q_depth in auditd.conf if using this
239 plugin. Also set an even bigger q_depth in audisp-remote.conf. Also set
240 the heartbeat_timeout to something non-zero but coordinate it with the
241 server so that it's half the size of the server's tcp_client_max_idle
242 setting. This is required to get retries in a reasonable time if the
243 network has a problem.
244
247 audisp-remote(8), auditd.conf(5).
248
250 Steve Grubb
251Red Hat Jul 2022 AUDISP-REMOTE.CONF(5)