Manpages - sudo_logsrvd.conf.5

The

file is used to configure the

log server. It uses an INI-style format made up of sections in square brackets and

pairs specific to each section below the section name. Depending on the key, values may be integers, booleans or strings. Section and key names are not case sensitive, but values are.

The pound sign

is used to indicate a comment. Both the comment character and any text after it, up to the end of the line, are ignored. Lines beginning with a semi-colon

are also ignored.

Long lines can be continued with a backslash

as the last character on the line. Note that leading white space is removed from the beginning of lines even when the continuation character is used.

The

section contains a copy of the default

file.

The following configuration sections are recognized:

server

relay

iolog

eventlog

syslog

logfile

Each section is described in detail below.

The

section configures the address and port the server will listen on. The following keys are recognized:

The host name or IP address, optional port to listen on and an optional Transport Layer Security (TLS) flag in parentheses.

The host may be a host name, an IPv4 address, an IPv6 address in square brackets or the wild card entry

A host setting of

will cause

to listen on all configured network interfaces.

If the optional tls flag is present,

will secure the connection with TLS version 1.2 or 1.3. Versions of TLS prior to 1.2 are not supported. See

for details on generating TLS keys and certificates.

If a port is specified, it may either be a port number or a known service name as defined by the system service name database. If no port is specified, port 30343 will be used for plaintext connections and port 30344 will be used for TLS connections.

The default value is:

listen_address = *:30343 listen_address = *:30344(tls)

which will listen on all configured network interfaces for both plaintext and TLS connections. Multiple

lines may be specified to listen on more than one port or interface.

Where to log server warning and error messages. Supported values are

or a path name beginning with the

character. Note that a value of

is only effective when used in conjunction with the

option. The default value is

The path to the file containing the process ID of the running

If set to an empty value, or if

is run with the

option, no

will be created. If

refers to a symbolic link, it will be ignored. The default value is

If true,

will enable the TCP keepalive socket option on the client connection. This enables the periodic transmission of keepalive messages to the client. If the client does not respond to a message in time, the connection will be closed. Defaults to true.

The amount of time, in seconds,

will wait for the client to respond. A value of 0 will disable the timeout. The default value is 30.

The path to a certificate authority bundle file, in PEM format, to use instead of the system’s default certificate authority database when authenticating clients. The default is to use

if it exists, otherwise the system’s default certificate authority database is used.

The path to the server’s certificate file, in PEM format. The default value is

If true, client certificates will be validated by

clients without a valid certificate will be unable to connect. If false, no validation of client certificates will be performed. It true and client certificates are created using a private certificate authority, the

setting must be set to a CA bundle that contains the CA certificate used to generate the client certificate. The default value is

A list of ciphers to use for connections secured by TLS version 1.2 only, separated by a colon

See the

section in

for full details. The default value is

which consists of encryption cipher suites with key lengths larger than 128 bits, and some cipher suites with 128-bit keys. Cipher suites that offer no authentication are excluded.

A list of ciphers to use for connections secured by TLS version 1.3 only, separated by a colon

Supported cipher suites depend on the version of OpenSSL used, but should include the following:

The default cipher suite is TLS_AES_256_GCM_SHA384.

The path to a file containing custom Diffie-Hellman parameters in PEM format. This file can be created with the following command:

openssl dhparam -out /etc/sudo_logsrvd_dhparams.pem 2048

By default,

will use the OpenSSL defaults for Diffie-Hellman key generation.

The path to the server’s private key file, in PEM format. The default value is

If true,

will validate its own certificate at startup time or when the configuration is changed. If false, no verification is performed of the server certificate. When using self-signed certificates without a certificate authority, this setting should be set to false. The default value is true.

The

section configures the optional logsrv relay host and port the server will connect to. The TLS configuration keys are optional, by default the corresponding keys in the

section will be used. They are only present in this section to make it possible for the relay connection to use a different set of TLS parameters from the client-facing server. The following keys are recognized:

The amount of time, in seconds,

will wait for the connection to a

(see below) to complete. Once the connection is complete, the

setting controls the amount of time

will wait for the relay to respond. A value of 0 will disable the timeout. The default value is 30.

The directory in which log messages are temporarily stored before they are sent to the relay host. Messages are stored in the wire format specified by

The default value is

The relay host name or IP address, optional port to connect to and an optional Transport Layer Security (TLS) flag in parentheses. The syntax is identical to

in the

section with one exception: the wild card

syntax is not supported.

When this setting is enabled, messages from the client will be forwarded to one of the specified relay hosts instead of being stored locally. The

could be running an instance of

or another server that supports the

protocol.

If multiple

lines are specified, the first available relay host will be used.

The number of seconds to wait after a connection error before making a new attempt to forward a message to a relay host. The default value is 30 seconds.

If true,

will store logs locally before relaying them. Once the log is complete, a connection to the relay host is opened and the log is relayed. If the network connection is interrupted before the log can be fully transferred, it will be retransmitted later. The default is to relay logs in real-time.

If true,

will enable the TCP keepalive socket option on the relay connection. This enables the periodic transmission of keepalive messages to the relay server. If the relay does not respond to a message in time, the connection will be closed.

The amount of time, in seconds,

will wait for the relay server to respond after a connection has succeeded. A value of 0 will disable the timeout. The default value is 30.

The path to a certificate authority bundle file, in PEM format, to use instead of the system’s default certificate authority database when authenticating clients. The default is to use the value specified in the

section, or the system’s default certificate authority database if no value is set.

The path to the server’s certificate file, in PEM format. The default is to use the value specified in the

section.

If true, the relay host’s certificate will be validated by

connections to a relay without a valid certificate will fail. If false, no validation of relay certificates will be performed. It true and relay certificates are created using a private certificate authority, the

setting must be set to a CA bundle that contains the CA certificate used to generate the relay certificate. The default is to use the value specified in the

section.

A list of ciphers to use for connections secured by TLS version 1.2 only, separated by a colon

See the

section in

for full details. The default is to use the value specified in the

section.

A list of ciphers to use for connections secured by TLS version 1.3 only, separated by a colon

Supported cipher suites depend on the version of OpenSSL used, see the

section for more information. The default is to use the value specified in the

section.

The path to a file containing custom Diffie-Hellman parameters in PEM format. The default is to use the value specified in the

section.

The path to the server’s private key file, in PEM format. The default is to use the value specified in the

section.

If true, the server’s certificate used for relaying will be verified at startup. If false, no verification is performed of the server certificate. When using self-signed certificates without a certificate authority, this setting should be set to false. The default is to use the value specified in the

section.

The

section configures I/O log parameters. These settings are identical to the I/O configuration in

The following keys are recognized:

If set, I/O logs will be compressed using

Enabling compression can make it harder to view the logs in real-time as the program is executing due to buffering. The default value is

The top-level directory to use when constructing the path name for the I/O log directory. The session sequence number, if any, is stored in the directory. The default value is

The following percent

escape sequences are supported:

expanded to a monotonically increasing base-36 sequence number, such as 0100A5, where every two digits are used to form a new directory, e.g.,

expanded to the invoking user’s login name

expanded to the name of the invoking user’s real group-ID

expanded to the login name of the user the command will be run as (e.g., root)

expanded to the group name of the user the command will be run as (e.g., wheel)

expanded to the local host name without the domain name

expanded to the base name of the command being run

In addition, any escape sequences supported by the system’s

function will be expanded.

To include a literal

character, the string

should be used.

The path name, relative to

in which to store I/O logs. Note that

may contain directory components. The default value is

See the

setting above for a list of supported percent

escape sequences.

In addition to the escape sequences, path names that end in six or more

will have the

replaced with a unique combination of digits and letters, similar to the

function.

If the path created by concatenating

and

already exists, the existing I/O log file will be truncated and overwritten unless

ends in six or more

If set, I/O log data is flushed to disk after each write instead of buffering it. This makes it possible to view the logs in real-time as the program is executing but may significantly reduce the effectiveness of I/O log compression. The default value is

The group name to look up when setting the group-ID on new I/O log files and directories. If

is not set, the primary group-ID of the user specified by

If neither

nor

are set, I/O log files and directories are created with group-ID 0.

The file mode to use when creating I/O log files. Mode bits for read and write permissions for owner, group or other are honored, everything else is ignored. The file permissions will always include the owner read and write bits, even if they are not present in the specified mode. When creating I/O log directories, search (execute) bits are added to match the read and write bits specified by

The default value is

The user name to look up when setting the owner of new I/O log files and directories. If

is set, it will be used instead of the user’s primary group-ID. By default, I/O log files and directories are created with user and group-ID 0.

The maximum sequence number that will be substituted for the

escape in the I/O log file (see the

description above for more information). While the value substituted for

is in base 36,

itself should be expressed in decimal. Values larger than 2176782336 (which corresponds to the base 36 sequence number

will be silently truncated to 2176782336. The default value is 2176782336.

The

section configures how (and if) security policy events are logged.

Where to log accept, reject and alert events reported by the policy. Supported values are

and

The default value is

If true,

will log an event when a command exits or is terminated by a signal. Defaults to false.

The event log format. Supported log formats are

for traditional sudo-style logs and

for JSON-format logs. The JSON log entries contain the full contents of the accept, reject, exit and alert messages. The default value is

The

section configures how events are logged via

Syslog facility if syslog is being used for logging. Defaults to

The following syslog facilities are supported:

(if your OS supports it),

and

Syslog priority to use when the user is allowed to run a command and authentication is successful. Defaults to

The following syslog priorities are supported:

and

Setting it to a value of

will disable logging of successful commands.

Syslog priority to use when the user is not allowed to run a command or when authentication is unsuccessful. Defaults to

See

for the list of supported syslog priorities.

Syslog priority to use for event log alert messages received from the client. Defaults to

See

for the list of supported syslog priorities.

On many systems,

has a relatively small log buffer. IETF RFC 5424 states that syslog servers must support messages of at least 480 bytes and should support messages up to 2048 bytes. By default,

creates log messages up to 960 bytes which corresponds to the historic

syslog implementation which used a 1024 byte buffer to store the message, date, hostname and program name.

To prevent syslog messages from being truncated,

will split up sudo-style log messages that are larger than

bytes. When a message is split, additional parts will include the string

after the user name and before the continued command line arguments. JSON-format log entries are never split and are not affected by

Syslog facility if syslog is being used for server warning messages. See above for a list of supported facilities. Defaults to

The

section consists of settings related to logging to a plain file (not syslog).

The path to the file-based event log. This path must be fully-qualified and start with a

character. The default value is

The string used when formatting the date and time for file-based event logs. Formatting is performed via the system’s

function so any escape sequences supported by that function will be expanded. The default value is

which produces dates like

in the C locale.

Sudo log server configuration file

[server] # The host name or IP address and port to listen on with an optional TLS # flag. If no port is specified, port 30343 will be used for plaintext # connections and port 30344 will be used to TLS connections. # The following forms are accepted: # listen_address = hostname(tls) # listen_address = hostname:port(tls) # listen_address = IPv4_address(tls) # listen_address = IPv4_address:port(tls) # listen_address = [IPv6_address](tls) # listen_address = [IPv6_address]:port(tls) # # The (tls) suffix should be omitted for plaintext connections. # # Multiple listen_address settings may be specified. # The default is to listen on all addresses. #listen_address = *:30343 #listen_address = *:30344(tls)

#pid_file = /run/sudo/sudo_logsrvd.pid

#server_log = syslog

is 30. #timeout = 30

Defaults to true. #tls_verify = true

clients without a valid certificate will be unable to connect. # By default, client certs are not checked. #tls_checkpeer = false

instead of the system’s default certificate authority database. #tls_cacert = /etc/ssl/sudo/cacert.pem

TLS connections. #tls_cert = /etc/ssl/sudo/certs/logsrvd_cert.pem

TLS connections. #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem

manual). # NOTE that this setting is only effective if the negotiated protocol # is TLS version 1.2. # The default cipher list is HIGH:!aNULL. #tls_ciphers_v12 = HIGH:!aNULL

default cipher list is TLS_AES_256_GCM_SHA384. #tls_ciphers_v13 = TLS_AES_256_GCM_SHA384

the server will use the OpenSSL defaults. #tls_dhparams = /etc/ssl/sudo/logsrvd_dhparams.pem

[relay] # The host name or IP address and port to send logs to in relay mode. # The syntax is identical to listen_address with the exception of

be relayed to the specified host instead of being stored locally. # This setting is not enabled by default. #relay_host = relayhost.dom.ain #relay_host = relayhost.dom.ain(tls)

timeout. # The default value is 30. #connect_timeout = 30

/var/log/sudo_logsrvd. #relay_dir = /var/log/sudo_logsrvd

a new attempt to forward a message to a relay host. # The default value is 30. #retry_interval = 30

and forward mode. If false, the client connection is immediately # relayed. Defaults to false. #store_first = true

Defaults to true. #tcp_keepalive = true

is 30. #timeout = 30

The default is to use the value in the [server] section. #tls_verify = true

default is to use the value in the [server] section. #tls_checkpeer = false

instead of the system’s default certificate authority database. # The default is to use the value in the [server] section. #tls_cacert = /etc/ssl/sudo/cacert.pem

to use the certificate in the [server] section. #tls_cert = /etc/ssl/sudo/certs/logsrvd_cert.pem

to use the key in the [server] section. #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem

manual). # NOTE that this setting is only effective if the negotiated protocol # is TLS version 1.2. # The default is to use the value in the [server] section. #tls_ciphers_v12 = HIGH:!aNULL

default is to use the value in the [server] section. #tls_ciphers_v13 = TLS_AES_256_GCM_SHA384

is to use the value in the [server] section. #tls_dhparams = /etc/ssl/sudo/logsrvd_dhparams.pem

[iolog] # The top-level directory to use when constructing the path name for the # I/O log directory. The session sequence number, if any, is stored here. #iolog_dir = /var/log/sudo-io

Note that iolog_file may contain directory components. #iolog_file = %{seq}

can # make it harder to view the logs in real-time as the program is executing. #iolog_compress = false

buffering it. This makes it possible to view the logs in real-time # as the program is executing but reduces the effectiveness of compression. #iolog_flush = true

iolog_group is not set, the primary group-ID of the user specified # by iolog_user is used. If neither iolog_group nor iolog_user # are set, I/O log files and directories are created with group-ID 0. #iolog_group = wheel

files and directories. If iolog_group is set, it will be used # instead of the user’s primary group-ID. By default, I/O log files # and directories are created with user and group-ID 0. #iolog_user = root

not present in the specified mode. When creating I/O log directories, # search (execute) bits are added to match the read and write bits # specified by iolog_mode. #iolog_mode = 0600

is in base 36, maxseq itself should be expressed in decimal. Values # larger than 2176782336 (which corresponds to the base 36 sequence # number “ZZZZZZ”) will be silently truncated to 2176782336. #maxseq = 2176782336

[eventlog] # Where to log accept, reject, exit and alert events. # Accepted values are syslog, logfile, or none. # Defaults to syslog #log_type = syslog

signal. # Defaults to false #log_exit = true

supported. #log_format = sudo

[syslog] # The maximum length of a syslog payload. # On many systems, syslog(3) has a relatively small log buffer. # IETF RFC 5424 states that syslog servers must support messages # of at least 480 bytes and should support messages up to 2048 bytes. # Messages larger than this value will be split into multiple messages. #maxlen = 960

syslog facilities are supported: authpriv (if your OS # supports it), auth, daemon, user, local0, local1, local2, local3, # local4, local5, local6, and local7. #facility = authpriv

none. #accept_priority = notice

client. #alert_priority = alert

daemon. #server_facility = daemon

[logfile] # The path to the file-based event log. # This path must be fully-qualified and start with a ’/’ character. #path = /var/log/sudo

file-based event logs. Formatting is performed via strftime(3) so # any format string supported by that function is allowed. #time_format = %h %e %T

See the HISTORY file in the

distribution (https://www.sudo.ws/history.html) for a brief history of sudo.

Many people have worked on

over the years; this version consists of code written primarily by:

See the CONTRIBUTORS file in the

distribution (https://www.sudo.ws/contributors.html) for an exhaustive list of people who have contributed to

If you feel you have found a bug in

please submit a bug report at https://bugzilla.sudo.ws/

Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

is provided

and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE file distributed with

or https://www.sudo.ws/license.html for complete details.