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 March 22, 2011
  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 on this file
  41 .Li ( eg. 0600 ) .
  42 .Pp
  43 Every line starting with # is treated as comment and ignored.
  44 .Sh CONFIGURATION FILE SYNTAX
  45 General syntax of the
  46 .Nm
  47 file is following:
  48 .Bd -literal -offset
  49 ## Global section.
  50
  51 # Our name.
  52 # The default is first part of the hostname.
  53 name "<name>"
  54
  55 # Connection timeout.
  56 # The default is 5.
  57 timeout <seconds>
  58
  59 # Path to pidfile.
  60 # The default is "/var/run/auditdistd.pid".
  61 pidfile "<path>"
  62
  63 sender {
  64         ## Sender section.
  65
  66         # Source address for connections.
  67         # Optional.
  68         source "<addr>"
  69
  70         # Directory with audit trail files managed by auditdistd.
  71         # The default is /var/audit/dist.
  72         directory "<dir>"
  73 .\"
  74 .\"     # Checksum algorithm for data send over the wire.
  75 .\"     # The default is none.
  76 .\"     checksum "<algorithm>"
  77 .\"
  78 .\"     # Compression algorithm for data send over the wire.
  79 .\"     # The default is none.
  80 .\"     compression "<algorithm>"
  81
  82         # Configuration for the target system we want to send audit trail
  83         # files to.
  84         host "<name>" {
  85                 # Source address for connections.
  86                 # Optional.
  87                 source "<addr>"
  88
  89                 # Address of auditdistd receiver.
  90                 # No default. Obligatory.
  91                 remote "<addr>"
  92
  93                 # Directory with audit trail files managed by auditdistd.
  94                 # The default is /var/audit/dist.
  95                 directory "<dir>"
  96
  97                 # Fingerprint of the receiver's public key when using TLS
  98                 # for connection.
  99                 # Example fingerprint:
 100                 # 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
 101                 fingerprint "<algorithm=hash>"
 102
 103                 # Password used to authenticate in front of the receiver.
 104                 password "<password>"
 105 .\"
 106 .\"             # Checksum algorithm for data send over the wire.
 107 .\"             # The default is none.
 108 .\"             checksum "<algorithm>"
 109 .\"
 110 .\"             # Compression algorithm for data send over the wire.
 111 .\"             # The default is none.
 112 .\"             compression "<algorithm>"
 113         }
 114
 115         # Currently local audit trail files can be send only to one remote
 116         # auditdistd receiver, but this can change in the future.
 117 }
 118
 119 receiver {
 120         ## Receiver section.
 121
 122         # Address to listen on. Multiple listen addresses might be specified.
 123         # The defaults are "tcp4://0.0.0.0:7878" and "tcp6://[::]:7878".
 124         listen "<addr>"
 125
 126         # Base directory.
 127         # If directory in host section is no absolute, it will be concatenated
 128         # with this base directory.
 129         # The default is "/var/audit/remote".
 130         directory "<basedir>"
 131
 132         # Path to receiver's certificate file.
 133         # The default is "/etc/security/auditdistd.cert.pem".
 134         certfile "<path>"
 135
 136         # Path to receiver's private key file.
 137         # The default is "/etc/security/auditdistd.key.pem".
 138         keyfile "<path>"
 139
 140         # Configuration for a source system we want to receive audit trail
 141         # files from.
 142         host "<name>" {
 143                 # Sender address.
 144                 # No default. Obligatory.
 145                 remote "<addr>"
 146
 147                 # Directory where to store audit trail files received
 148                 # from system <name>.
 149                 # The default is "<basedir>/<name>".
 150                 directory "<dir>"
 151
 152                 # Password used by the sender to authenticate.
 153                 password "<password>"
 154         }
 155
 156         # Multiple hosts to receive from can be configured.
 157 }
 158 .Ed
 159 .Pp
 160 Most of the various available configuration parameters are optional.
 161 If parameter is not defined in the particular section, it will be
 162 inherited from the parent section if possible.
 163 For example, if the
 164 .Ic source
 165 parameter is not defined in the
 166 .Ic host
 167 section, it will be inherited from the
 168 .Ic sender
 169 section.
 170 In case the
 171 .Ic global
 172 section does not define the
 173 .Ic source
 174 parameter at all, the default value will be used.
 175 .Sh CONFIGURATION FILE DESCRIPTION
 176 The following statements are available:
 177 .Bl -tag -width ".Ic xxxx"
 178 .It Ic name Aq name
 179 .Pp
 180 This host's name.
 181 It is send to the receiver, so it can properly recognize us if there are
 182 more than one sender coming from the same IP address.
 183 .It Ic timeout Aq seconds
 184 .Pp
 185 Connection timeout in seconds.
 186 The default value is
 187 .Va 5 .
 188 .It Ic pidfile Aq path
 189 .Pp
 190 File in which to store the process ID of the main
 191 .Xr auditdistd 8
 192 process.
 193 .Pp
 194 The default value is
 195 .Pa /var/run/auditdistd.pid .
 196 .It Ic source Aq addr
 197 .Pp
 198 Local address to bind to before connecting to the remote
 199 .Nm auditdistd
 200 daemon.
 201 Format is the same as for the
 202 .Ic listen
 203 statement.
 204 .It Ic directory Aq path
 205 .Pp
 206 Directory where to look for audit trail files in case of sender mode or
 207 directory where to store received audit trail files.
 208 The provided path has to be an absolute path.
 209 The only exception is when directory is provided in the
 210 .Ic receiver
 211 section, then path provided in the
 212 .Ic host
 213 subsections can be relative to the directory in the
 214 .Ic receiver
 215 section.
 216 The default value is
 217 .Pa /var/audit/dist
 218 for the entire
 219 .Ic sender
 220 section,
 221 .Pa /var/audit/remote
 222 for the non-host
 223 .Ic receiver
 224 section and
 225 .Pa /var/audit/remote/<name>
 226 for the
 227 .Ic host
 228 subsections in the
 229 .Ic receiver
 230 section where
 231 .Aq name
 232 is host's name.
 233 .\".It Ic checksum Aq algorithm
 234 .\".Pp
 235 .\"Checksum algorithm should be one of the following:
 236 .\".Bl -tag -width ".Ic sha256"
 237 .\".It Ic none
 238 .\"No checksum will be calculated for the data being send over the network.
 239 .\"This is the default setting.
 240 .\".It Ic crc32
 241 .\"CRC32 checksum will be calculated.
 242 .\".It Ic sha256
 243 .\"SHA256 checksum will be calculated.
 244 .\".El
 245 .\".It Ic compression Aq algorithm
 246 .\".Pp
 247 .\"Compression algorithm should be one of the following:
 248 .\".Bl -tag -width ".Ic none"
 249 .\".It Ic none
 250 .\"Data send over the network will not be compressed.
 251 .\"This is the default setting.
 252 .\".It Ic lzf
 253 .\"The
 254 .\".Nm LZF
 255 .\"algorithm by
 256 .\".An Marc Alexander Lehmann
 257 .\"will be used to compress the data send over the network.
 258 .\".Nm LZF
 259 .\"is very fast, general purpose compression algorithm.
 260 .\".El
 261 .It Ic remote Aq addr
 262 .Pp
 263 Address of the remote
 264 .Nm auditdistd
 265 daemon.
 266 Format is the same as for the
 267 .Ic listen
 268 statement.
 269 When operating in the
 270 .Ic sender
 271 mode this address will be used to connect to the
 272 .Ic receiver .
 273 When operating in the
 274 .Ic receiver
 275 mode only connections from this address will be accepted.
 276 .It Ic listen Aq addr
 277 .Pp
 278 Address to listen on in form of:
 279 .Bd -literal -offset indent
 280 protocol://protocol-specific-address
 281 .Ed
 282 .Pp
 283 Each of the following examples defines the same listen address:
 284 .Bd -literal -offset indent
 285 0.0.0.0
 286 0.0.0.0:7878
 287 tcp://0.0.0.0
 288 tcp://0.0.0.0:7878
 289 tcp4://0.0.0.0
 290 tcp4://0.0.0.0:7878
 291 .Ed
 292 .Pp
 293 Multiple listen addresses can be specified.
 294 By default
 295 .Nm auditdistd
 296 listens on
 297 .Pa tcp4://0.0.0.0:7878
 298 and
 299 .Pa tcp6://[::]:7878
 300 if kernel supports IPv4 and IPv6 respectively.
 301 .It Ic keyfile Aq path
 302 .Pp
 303 Path to a file that contains private key for TLS communication.
 304 .It Ic certfile Aq path
 305 .Pp
 306 Path to a file that contains certificate for TLS communication.
 307 .It Ic fingerprint Aq algo=hash
 308 .Pp
 309 Finger print of the receiver's public key.
 310 Currently only SHA256 algorithm is supported.
 311 Certificate public key's fingerprint ready to be pasted into auditdistd
 312 configuration file can be obtained by running:
 313 .Bd -literal -offset
 314 # openssl x509 -in /etc/security/auditdistd.cert.pem -noout -fingerprint -sha256 | awk -F '[ =]' '{printf("%s=%s\\n", $1, $3)}'
 315 .Ed
 316 .It Ic password Aq password
 317 .Pp
 318 Password used to authenticate the sender in front of the receiver.
 319 .El
 320 .Sh FILES
 321 .Bl -tag -width ".Pa /etc/security/auditdistd.conf" -compact
 322 .It Pa /etc/security/auditdistd.conf
 323 The default
 324 .Nm auditdistd
 325 configuration file.
 326 .El
 327 .Sh EXAMPLES
 328 The example configuration files can look as follows.
 329 .Pp
 330 Web server:
 331 .Bd -literal -offset indent
 332 sender {
 333         host backup {
 334                 remote 10.0.0.4
 335         }
 336 }
 337 .Ed
 338 .Pp
 339 Audit backup server:
 340 .Bd -literal -offset indent
 341 receiver {
 342         host webserv {
 343                 remote 10.0.0.1
 344         }
 345         host mailserv {
 346                 remote 10.0.0.2
 347         }
 348         host dnsserv {
 349                 remote 10.0.0.3
 350         }
 351 }
 352 .Ed
 353 .Sh SEE ALSO
 354 .Xr audit 4 ,
 355 .Xr auditdistd 8 .
 356 .Sh AUTHORS
 357 The
 358 .Nm auditdistd
 359 was developed by
 360 .An Pawel Jakub Dawidek Aq pawel@dawidek.net
 361 under sponsorship of the FreeBSD Foundation.