diff options
Diffstat (limited to 'docs/sudo_logsrvd.mdoc.in')
| -rw-r--r-- | docs/sudo_logsrvd.mdoc.in | 435 |
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. |