1AUDISP-REMOTE.CONF(5)   System Administration Utilities  AUDISP-REMOTE.CONF(5)
2
3
4

NAME

6       audisp-remote.conf - the audisp-remote configuration file
7

DESCRIPTION

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
13
14       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
19       port   This  option  is an unsigned integer that indicates what port to
20              connect to on the remote machine.
21
22       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
33       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
41       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
50       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
54       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
61       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
73       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
79       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
86       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
94       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
103       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
127       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
131       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
136       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
140       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
149       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
154       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
159       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
164       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
176       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
191       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
200       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
208       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
217       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
222
223

NOTES

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
229       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
238       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
245

SEE ALSO

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

AUTHOR

250       Steve Grubb
251
252
253
254
255Red Hat                            Jul 2022              AUDISP-REMOTE.CONF(5)
Impressum