summaryrefslogtreecommitdiffstats
path: root/docs/sudo_logsrvd.mdoc.in
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/sudo_logsrvd.mdoc.in435
1 files changed, 435 insertions, 0 deletions
diff --git a/docs/sudo_logsrvd.mdoc.in b/docs/sudo_logsrvd.mdoc.in
new file mode 100644
index 0000000..bde5ff6
--- /dev/null
+++ b/docs/sudo_logsrvd.mdoc.in
@@ -0,0 +1,435 @@
+.\"
+.\" SPDX-License-Identifier: ISC
+.\"
+.\" Copyright (c) 2019-2023 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 January 16, 2023
+.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 Widgits 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 Widgits 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_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 submit a bug report at https://bugzilla.sudo.ws/
+.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.