sudo/docs/sudo_logsrvd.mdoc.in

.\"
.\" SPDX-License-Identifier: ISC
.\"
.\" Copyright (c) 2019-2024 Todd C. Miller <Todd.Miller@sudo.ws>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd July 14, 2024
.Dt SUDO_LOGSRVD @mansectsu@
.Os Sudo @PACKAGE_VERSION@
.Sh NAME
.Nm sudo_logsrvd
.Nd sudo event and I/O log server
.Sh SYNOPSIS
.Nm sudo_logsrvd
.Op Fl hnV
.Op Fl f Ar file
.Op Fl R Ar percentage
.Sh DESCRIPTION
.Nm
is a high-performance log server that accepts event and I/O logs from
.Nm sudo .
It can be used to implement centralized logging of
.Nm sudo
logs.
The server has two modes of operation: local and relay.
By default,
.Nm
stores the logs locally but it can also be configured to
relay them to another server that supports the
.Xr sudo_logsrv.proto @mansectform@
protocol.
.Pp
When not relaying, event log entries may be logged either via
.Xr syslog 3
or to a local file.
I/O Logs stored locally by
.Nm
can be replayed via the
.Xr sudoreplay @mansectsu@
utility in the same way as logs generated directly by the
.Nm sudoers
plugin.
.Pp
The server also supports restarting interrupted log transfers.
To distinguish completed I/O logs from incomplete ones, the
I/O log timing file is set to be read-only when the log is complete.
.Pp
Configuration parameters for
.Nm
may be specified in the
.Xr sudo_logsrvd.conf @mansectform@
file or the file specified via the
.Fl f
option.
.Pp
.Nm
rereads its configuration file when it receives SIGHUP and writes server
state to the debug file (if one is configured) when it receives SIGUSR1.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl f Ar file , Fl -file Ns = Ns Ar file
Read configuration from
.Ar file
instead of the default,
.Pa @sysconfdir@/sudo_logsrvd.conf .
.It Fl h , -help
Display a short help message to the standard output and exit.
.It Fl n , -no-fork
Run
.Nm
in the foreground instead of detaching from the terminal and becoming
a daemon.
.It Fl R Ar percentage , Fl -random-drop Ns = Ns Ar percentage
For each message, there is a
.Ar percentage
chance that the server will drop the connection.
This is only intended for debugging the ability of a
client to restart a connection.
.It Fl V , -version
Print the
.Nm
version and exit.
.El
.Ss Securing server connections
The I/O log data sent to
.Nm
may contain sensitive information such as passwords and should be
secured using Transport Layer Security (TLS).
Doing so requires having a signed certificate on the server and, if
.Em tls_checkpeer
is enabled in
.Xr sudo_logsrvd.conf @mansectform@ ,
a signed certificate on the client as well.
.Pp
The certificates can either be signed by a well-known Certificate
Authority (CA), or a private CA can be used.
Instructions for creating a private CA are included below in the
.Sx EXAMPLES
section.
.Ss Debugging sudo_logsrvd
.Nm
supports a flexible debugging framework that is configured via
.Em Debug
lines in the
.Xr sudo.conf @mansectform@
file.
.Pp
For more information on configuring
.Xr sudo.conf @mansectform@ ,
refer to its manual.
.Sh FILES
.Bl -tag -width 24n
.It Pa @sysconfdir@/sudo.conf
Sudo front-end configuration
.It Pa @sysconfdir@/sudo_logsrvd.conf
Sudo log server configuration file
.It Pa @relay_dir@/incoming
Directory where new journals are stored when the
.Em store_first relay
setting is enabled.
.It Pa @relay_dir@/outgoing
Directory where completed journals are stored when the
.Em store_first relay
setting is enabled.
.It Pa @iolog_dir@
Default I/O log file location
.It Pa @rundir@/sudo_logsrvd.pid
Process ID file for
.Nm
.El
.Sh EXAMPLES
.Ss Creating self-signed certificates
Unless you are using certificates signed by a well-known Certificate
Authority (or a local enterprise CA), you will need to create your
own CA that can sign the certificates used by
.Nm ,
.Nm sudo_sendlog ,
and the
.Nm sudoers
plugin.
The following steps use the
.Xr openssl 1
command to create keys and certificates.
.Ss Initial setup
First, we need to create a directory structure to store the
files for the CA.
We'll create a new directory hierarchy in
.Pa /etc/ssl/sudo
for this purpose.
.Bd -literal -offset 4n
# mkdir /etc/ssl/sudo
# cd /etc/ssl/sudo
# mkdir certs csr newcerts private
# chmod 700 private
# touch index.txt
# echo 1000 > serial
.Ed
.Pp
The serial and index.txt files are used to keep track of signed certificates.
.Pp
Next, we need to make a copy of the openssl.conf file and customize
it for our new CA.
The path to openssl.cnf is system-dependent but
.Pa /etc/ssl/openssl.cnf
is the most common location.
You will need to adjust the example below if it has a different location on
your system.
.Bd -literal -offset 4n
# cp /etc/ssl/openssl.cnf .
.Ed
.Pp
Now edit the
.Pa openssl.cnf
file in the current directory and make sure it contains
.Dq ca ,
.Dq CA_default ,
.Dq v3_ca ,
and
.Dq usr_cert
sections.
Those sections should include at least the following settings:
.Bd -literal -offset 4n
[ ca ]
default_ca              = CA_default

[ CA_default ]
dir                     = /etc/ssl/sudo
certs                   = $dir/certs
database                = $dir/index.txt
certificate             = $dir/cacert.pem
serial                  = $dir/serial

[ v3_ca ]
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid:always,issuer
basicConstraints        = critical,CA:true
keyUsage                = cRLSign, keyCertSign

[ usr_cert ]
basicConstraints        = CA:FALSE
keyUsage                = nonRepudiation, digitalSignature, \e
                          keyEncipherment
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid,issuer
.Ed
.Pp
If your
.Pa openssl.conf
file already has a
.Dq CA_default
section, you may only need to modify the
.Dq dir
setting and enable the
.Dq keyUsage
settings if they are commented out.
.Ss Creating the CA key and certificate
In order to create and sign our own certificates, we need to create
a private key and a certificate for the root of the CA.
First, create the private key and protect it with a pass phrase:
.Bd -literal -offset 4n
# openssl genrsa -aes256 -out private/cakey.pem 4096
# chmod 400 private/cakey.pem
.Ed
.Pp
Next, generate the root certificate, using appropriate values for
the site-specific fields:
.Bd -literal -offset 4n
# openssl req -config openssl.cnf -key private/cakey.pem \e
    -new -x509 -days 7300 -sha256 -extensions v3_ca \e
    -out cacert.pem

Enter pass phrase for private/cakey.pem:
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Colorado
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgets Pty Ltd]:sudo
Organizational Unit Name (eg, section) []:sudo Certificate Authority
Common Name (e.g., server FQDN or YOUR name) []:sudo Root CA
Email Address []:

# chmod 444 cacert.pem
.Ed
.Pp
Finally, verify the root certificate:
.Bd -literal -offset 4n
# openssl x509 -noout -text -in cacert.pem
.Ed
.Ss Creating and signing certificates
The server and client certificates will be signed by the previously
created root CA.
Usually, the root CA is not used to sign server/client certificates
directly.
Instead, intermediate certificates are created and signed with the
root CA and the intermediate certs are used to sign CSRs (Certificate
Signing Request).
In this example we'll skip this part for simplicity's sake and sign the
CSRs with the root CA.
.Pp
First, generate the private key without a pass phrase.
.Bd -literal -offset 4n
# openssl genrsa -out private/logsrvd_key.pem 2048
# chmod 400 private/logsrvd_key.pem
.Ed
.Pp
Next, create a certificate signing request (CSR) for the server's certificate.
The organization name must match the name given in the root certificate.
The common name should be either the server's IP address or a fully
qualified domain name.
.Bd -literal -offset 4n
# openssl req -config openssl.cnf -key private/logsrvd_key.pem -new \e
    -sha256 -out csr/logsrvd_csr.pem

Enter pass phrase for private/logsrvd_key.pem:
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Colorado
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgets Pty Ltd]:sudo
Organizational Unit Name (eg, section) []:sudo log server
Common Name (e.g., server FQDN or YOUR name) []:logserver.example.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
.Ed
.Pp
Now sign the CSR that was just created:
.Bd -literal -offset 4n
# openssl ca -config openssl.cnf -days 375 -notext -md sha256 \e
    -in csr/logsrvd_csr.pem -out certs/logsrvd_cert.pem

Using configuration from openssl.cnf
Enter pass phrase for ./private/cakey.pem:
Check that the request matches the signature
Signature ok
Certificate Details:
        Serial Number: 4096 (0x1000)
        Validity
            Not Before: Nov 11 14:05:05 2019 GMT
            Not After : Nov 20 14:05:05 2020 GMT
        Subject:
            countryName               = US
            stateOrProvinceName       = Colorado
            organizationName          = sudo
            organizationalUnitName    = sudo log server
            commonName                = logserve.example.com
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            X509v3 Key Usage:
                Digital Signature, Non Repudiation, Key Encipherment
            X509v3 Subject Key Identifier:
                4C:50:F9:D0:BE:1A:4C:B2:AC:90:76:56:C7:9E:16:AE:E6:9E:E5:B5
            X509v3 Authority Key Identifier:
                keyid:D7:91:24:16:B1:03:06:65:1A:7A:6E:CF:51:E9:5C:CB:7A:95:3E:0C

Certificate is to be certified until Nov 20 14:05:05 2020 GMT (375 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
.Ed
.Pp
Finally, verify the new certificate:
.Bd -literal -offset 4n
# openssl verify -CAfile cacert.pem certs/logsrvd_cert.pem
certs/logsrvd_cert.pem: OK
.Ed
.Pp
The
.Pa /etc/ssl/sudo/certs
directory now contains a signed and verified certificate for use with
.Nm sudo_logsrvd .
.Pp
To generate a client certificate, repeat the process above using
a different file name.
.Ss Configuring sudo_logsrvd to use TLS
To use TLS for client/server communication, both
.Nm
and the
.Nm sudoers
plugin need to be configured to use TLS.
Configuring
.Nm
for TLS requires the following settings, assuming the same path
names used earlier:
.Bd -literal -offset 4n
# Listen on port 30344 for TLS connections to any address.
listen_address = *:30344(tls)

# Path to the certificate authority bundle file in PEM format.
tls_cacert = /etc/ssl/sudo/cacert.pem

# Path to the server's certificate file in PEM format.
tls_cert = /etc/ssl/sudo/certs/logsrvd_cert.pem

# Path to the server's private key file in PEM format.
tls_key = /etc/ssl/sudo/private/logsrvd_key.pem
.Ed
.Pp
The root CA cert
.Pq Pa cacert.pem
must be installed on the system running
.Nm .
If peer authentication is enabled on the client, a copy of
.Pa cacert.pem
must be present on the client system too.
.Sh SEE ALSO
.Xr sudo.conf @mansectform@ ,
.Xr sudo_logsrv.proto @mansectform@ ,
.Xr sudo_logsrvd.conf @mansectform@ ,
.Xr sudoers @mansectform@ ,
.Xr sudo @mansectsu@ ,
.Xr sudo_sendlog @mansectsu@ ,
.Xr sudoreplay @mansectsu@
.Sh AUTHORS
Many people have worked on
.Nm sudo
over the years; this version consists of code written primarily by:
.Bd -ragged -offset indent
.An Todd C. Miller
.Ed
.Pp
See the CONTRIBUTORS.md file in the
.Nm sudo
distribution (https://www.sudo.ws/about/contributors/) for an
exhaustive list of people who have contributed to
.Nm sudo .
.Sh BUGS
If you believe you have found a bug in
.Nm ,
you can either file a bug report in the sudo bug database,
https://bugzilla.sudo.ws/, or open an issue at
https://github.com/sudo-project/sudo/issues.
If you would prefer to use email, messages may be sent to the
sudo-workers mailing list,
https://www.sudo.ws/mailman/listinfo/sudo-workers (public)
or <sudo@sudo.ws> (private).
.Pp
Please not report security vulnerabilities through public GitHub
issues, Bugzilla or mailing lists.
Instead, report them via email to <Todd.Miller@sudo.ws>.
You may encrypt your message with PGP if you would like, using
the key found at https://www.sudo.ws/dist/PGPKEYS.
.Sh SUPPORT
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.
.Sh DISCLAIMER
.Nm
is provided
.Dq AS IS
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.md file distributed with
.Nm sudo
or https://www.sudo.ws/about/license/ for complete details.