contrib/openbsm/bin/auditdistd/auditdistd.conf.5

   1 .\" Copyright (c) 2012 The FreeBSD Foundation
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd July 1, 2015
  31 .Dt AUDITDISTD.CONF 5
  32 .Os
  33 .Sh NAME
  34 .Nm auditdistd.conf
  35 .Nd configuration file for the
  36 .Xr auditdistd 8
  37 daemon.
  38 .Sh DESCRIPTION
  39 Note: the configuration file may contain passwords.
  40 Care should be taken to configure proper permissions for this file
  41 .Li ( e.g., 0600 ) .
  42 .Pp
  43 Every line starting with
  44 .Li #
  45 gets treated as a comment and is ignored.
  46 .Sh CONFIGURATION FILE SYNTAX
  47 The general syntax of the
  48 .Nm
  49 file is as follows:
  50 .Bd -literal
  51 ## Global section.
  52
  53 # Our name.
  54 # The default is the first part of the hostname.
  55 name "<name>"
  56
  57 # Connection timeout.
  58 # The default is 5.
  59 timeout <seconds>
  60
  61 # Path to pidfile.
  62 # The default is "/var/run/auditdistd.pid".
  63 pidfile "<path>"
  64
  65 sender {
  66         ## Sender section.
  67
  68         # Source address for connections.
  69         # Optional.
  70         source "<addr>"
  71
  72         # Directory with audit trail files managed by auditdistd.
  73         # The default is /var/audit/dist.
  74         directory "<dir>"
  75 .\"
  76 .\"     # Checksum algorithm for data sent over the wire.
  77 .\"     # The default is none.
  78 .\"     checksum "<algorithm>"
  79 .\"
  80 .\"     # Compression algorithm for data sent over the wire.
  81 .\"     # The default is none.
  82 .\"     compression "<algorithm>"
  83
  84         # Configuration for the target system we want to send audit trail
  85         # files to.
  86         host "<name>" {
  87                 # Source address for connections.
  88                 # Optional.
  89                 source "<addr>"
  90
  91                 # Address of the auditdistd receiver.
  92                 # No default. Obligatory.
  93                 remote "<addr>"
  94
  95                 # Directory with audit trail files managed by auditdistd.
  96                 # The default is /var/audit/dist.
  97                 directory "<dir>"
  98
  99                 # Fingerprint of the receiver's public key when using TLS
 100                 # for connections.
 101                 # Example fingerprint:
 102                 # SHA256=8F:0A:FC:8A:3D:09:80:AF:D9:AA:38:CC:8A:86:53:E6:8F:B6:1C:55:30:14:D7:F9:AA:8B:3E:73:CD:F5:76:2B
 103                 fingerprint "<algorithm=hash>"
 104
 105                 # Password used to authenticate in front of the receiver.
 106                 password "<password>"
 107 .\"
 108 .\"             # Checksum algorithm for data sent over the wire.
 109 .\"             # The default is none.
 110 .\"             checksum "<algorithm>"
 111 .\"
 112 .\"             # Compression algorithm for data sent over the wire.
 113 .\"             # The default is none.
 114 .\"             compression "<algorithm>"
 115         }
 116
 117         # Currently local audit trail files can be sent only to one remote
 118         # auditdistd receiver, but this can change in the future.
 119 }
 120
 121 receiver {
 122         ## Receiver section.
 123
 124         # Address to listen on. Multiple listen addresses may be specified.
 125         # The defaults are "tcp4://0.0.0.0:7878" and "tcp6://[::]:7878".
 126         listen "<addr>"
 127
 128         # Base directory.
 129         # If the directory in the host section is not absolute, it will be
 130         # concatenated with this base directory.
 131         # The default is "/var/audit/remote".
 132         directory "<basedir>"
 133
 134         # Path to the receiver's certificate file.
 135         # The default is "/etc/security/auditdistd.cert.pem".
 136         certfile "<path>"
 137
 138         # Path to the receiver's private key file.
 139         # The default is "/etc/security/auditdistd.key.pem".
 140         keyfile "<path>"
 141
 142         # Configuration for a source system we want to receive audit trail
 143         # files from.
 144         host "<name>" {
 145                 # Sender address.
 146                 # No default. Obligatory.
 147                 remote "<addr>"
 148
 149                 # Directory where to store audit trail files received
 150                 # from system <name>.
 151                 # The default is "<basedir>/<name>".
 152                 directory "<dir>"
 153
 154                 # Password used by the sender to authenticate.
 155                 password "<password>"
 156         }
 157
 158         # Multiple hosts to receive from can be configured.
 159 }
 160 .Ed
 161 .Pp
 162 Most of the various available configuration parameters are optional.
 163 If a parameter is not defined in the particular section, it will be
 164 inherited from the parent section if possible.
 165 For example, if the
 166 .Ic source
 167 parameter is not defined in the
 168 .Ic host
 169 section, it will be inherited from the
 170 .Ic sender
 171 section.
 172 In case the
 173 .Ic global
 174 section does not define the
 175 .Ic source
 176 parameter at all, the default value will be used.
 177 .Sh CONFIGURATION OPTION DESCRIPTION
 178 The following statements are available:
 179 .Bl -tag -width ".Ic xxxx"
 180 .It Ic name Aq name
 181 .Pp
 182 This host's name.
 183 It is sent to the receiver, so it can properly recognize us if there are
 184 multiple senders coming from the same IP address.
 185 .It Ic timeout Aq seconds
 186 .Pp
 187 Connection timeout in seconds.
 188 The default value is
 189 .Va 5 .
 190 .It Ic pidfile Aq path
 191 .Pp
 192 File in which to store the process ID of the main
 193 .Xr auditdistd 8
 194 process.
 195 .Pp
 196 The default value is
 197 .Pa /var/run/auditdistd.pid .
 198 .It Ic source Aq addr
 199 .Pp
 200 Local address to bind to before connecting to the remote
 201 .Nm auditdistd
 202 daemon.
 203 The format is the same as for the
 204 .Ic listen
 205 statement.
 206 .It Ic directory Aq path
 207 .Pp
 208 The directory where to look for audit trail files in case of sender mode, or
 209 the directory where to store received audit trail files.
 210 The provided path has to be an absolute path.
 211 The only exception is when the directory is provided in the
 212 .Ic receiver
 213 section; then the path provided in the
 214 .Ic host
 215 subsections can be relative to the directory in the
 216 .Ic receiver
 217 section.
 218 The default value is
 219 .Pa /var/audit/dist
 220 for the entire
 221 .Ic sender
 222 section,
 223 .Pa /var/audit/remote
 224 for the non-host
 225 .Ic receiver
 226 section and
 227 .Pa /var/audit/remote/<name>
 228 for the
 229 .Ic host
 230 subsections in the
 231 .Ic receiver
 232 section where
 233 .Aq name
 234 is the host's name.
 235 .\".It Ic checksum Aq algorithm
 236 .\".Pp
 237 .\"Checksum algorithm should be one of the following:
 238 .\".Bl -tag -width ".Ic sha256"
 239 .\".It Ic none
 240 .\"No checksum will be calculated for the data being sent over the network.
 241 .\"This is the default setting.
 242 .\".It Ic crc32
 243 .\"CRC32 checksum will be calculated.
 244 .\".It Ic sha256
 245 .\"SHA256 checksum will be calculated.
 246 .\".El
 247 .\".It Ic compression Aq algorithm
 248 .\".Pp
 249 .\"Compression algorithm should be one of the following:
 250 .\".Bl -tag -width ".Ic none"
 251 .\".It Ic none
 252 .\"Data sent over the network will not be compressed.
 253 .\"This is the default setting.
 254 .\".It Ic lzf
 255 .\"The
 256 .\".Nm LZF
 257 .\"algorithm by
 258 .\".An Marc Alexander Lehmann
 259 .\"will be used to compress the data sent over the network.
 260 .\".Nm LZF
 261 .\"is a very fast, general purpose compression algorithm.
 262 .\".El
 263 .It Ic remote Aq addr
 264 .Pp
 265 Address of the remote
 266 .Nm auditdistd
 267 daemon.
 268 The format is the same as for the
 269 .Ic listen
 270 statement.
 271 When operating in
 272 .Ic sender
 273 mode this address will be used to connect to the
 274 .Ic receiver .
 275 When operating in
 276 .Ic receiver
 277 mode only connections from this address will be accepted.
 278 .It Ic listen Aq addr
 279 .Pp
 280 Address to listen on in form of:
 281 .Bd -literal -offset indent
 282 protocol://protocol-specific-address
 283 .Ed
 284 .Pp
 285 Each of the following examples defines the same listen address:
 286 .Bd -literal -offset indent
 287 0.0.0.0
 288 0.0.0.0:7878
 289 tcp://0.0.0.0
 290 tcp://0.0.0.0:7878
 291 tcp4://0.0.0.0
 292 tcp4://0.0.0.0:7878
 293 .Ed
 294 .Pp
 295 Multiple listen addresses can be specified.
 296 By default
 297 .Nm auditdistd
 298 listens on
 299 .Pa tcp4://0.0.0.0:7878
 300 and
 301 .Pa tcp6://[::]:7878 ,
 302 if the kernel supports IPv4 and IPv6 respectively.
 303 .It Ic keyfile Aq path
 304 .Pp
 305 Path to a file that contains the private key for TLS communication.
 306 .It Ic certfile Aq path
 307 .Pp
 308 Path to a file that contains the certificate for TLS communication.
 309 .It Ic fingerprint Aq algo=hash
 310 .Pp
 311 Fingerprint of the receiver's public key.
 312 Currently only the SHA256 algorithm is supported.
 313 The certificate public key's fingerprint ready to be pasted into the
 314 .Nm auditdistd
 315 configuration file can be obtained by running:
 316 .Bd -literal
 317 # openssl x509 -in /etc/security/auditdistd.cert.pem -noout -fingerprint -sha256 | awk -F '[ =]' '{printf("%s=%s\\n", $1, $3)}'
 318 .Ed
 319 .It Ic password Aq password
 320 .Pp
 321 Password used to authenticate the sender in front of the receiver.
 322 .El
 323 .Sh FILES
 324 .Bl -tag -width ".Pa /etc/security/auditdistd.conf" -compact
 325 .It Pa /etc/security/auditdistd.conf
 326 The default
 327 .Nm auditdistd
 328 configuration file.
 329 .El
 330 .Sh EXAMPLES
 331 The example configuration files can look as follows.
 332 .Pp
 333 Web server:
 334 .Bd -literal -offset indent
 335 sender {
 336         host backup {
 337                 remote 10.0.0.4
 338         }
 339 }
 340 .Ed
 341 .Pp
 342 Audit backup server:
 343 .Bd -literal -offset indent
 344 receiver {
 345         host webserv {
 346                 remote 10.0.0.1
 347         }
 348         host mailserv {
 349                 remote 10.0.0.2
 350         }
 351         host dnsserv {
 352                 remote 10.0.0.3
 353         }
 354 }
 355 .Ed
 356 .Sh SEE ALSO
 357 .Xr audit 4 ,
 358 .Xr auditdistd 8
 359 .Sh AUTHORS
 360 The
 361 .Nm auditdistd
 362 daemon was developed by
 363 .An Pawel Jakub Dawidek Aq pawel@dawidek.net
 364 under sponsorship of the FreeBSD Foundation.