cockpit-tls(8)

1COCKPIT-TLS(8)                    cockpit-tls                   COCKPIT-TLS(8)
2
3
4

NAME

6       cockpit-tls - TLS proxy for Cockpit web service
7

SYNOPSIS

9       cockpit-tls [--help] [--port PORT] [--no-tls] [--idle-timeout SECONDS]
10

DESCRIPTION

12       The cockpit-tls program is a TLS terminating HTTP proxy for cockpit-
13       ws(8). It manages a set of isolated cockpit-ws instances, one per TLS
14       client certificate, plus one for TLS without a client certificate, and
15       one for unencrypted HTTP. With that, one session cannot tamper with
16       another one through possible security vulnerability exploits.
17
18       Users or administrators should never need to start this program as it
19       automatically started by systemd(1) via socket activation.
20

TRANSPORT SECURITY

22       To specify the TLS certificate the web service should use, simply drop
23       a file with the extension .cert in the /etc/cockpit/ws-certs.d
24       directory, or below $XDG_CONFIG_DIRS if set (see cockpit.conf[1]). If
25       there are multiple files in this directory, then the highest priority
26       one is chosen after sorting.
27
28       The .cert file should contain at least two OpenSSL style PEM blocks.
29       First one or more BEGIN CERTIFICATE blocks for the server certificate
30       and intermediate certificate authorities and a second one containing a
31       BEGIN PRIVATE KEY or similar. The key must not be encrypted.
32
33       If there is no TLS certificate, a self-signed certificate is
34       automatically generated using sscg (if available) or openssl and stored
35       in the 0-self-signed.cert file.
36
37       When enrolling into a FreeIPA domain, an SSL certificate is requested
38       from the IPA server and stored in 10-ipa.cert.
39
40       To check which certificate cockpit-ws will use, run the following
41       command.
42
43           $ sudo /usr/libexec/cockpit-certificate-ensure --check
44
45       Or, on Debian-based systems:
46
47           $ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check
48
49       If using certmonger to manage certificates, following command can be
50       used to generate a certificate/key pair:
51
52           CERT_FILE=/etc/cockpit/ws-certs.d/50-certmonger.crt
53           KEY_FILE=/etc/cockpit/ws-certs.d/50-certmonger.key
54
55           getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn)
56

OPTIONS

58       --help
59           Show help options.
60
61       --port PORT
62           Serve HTTP requests on PORT instead of port 9090. Usually Cockpit
63           is started on demand by systemd socket activation, and this option
64           has no effect. Update the ListenStream directive cockpit.socket
65           file in the usual systemd manner.
66
67       --no-tls
68           Don't use TLS. Certificates will not be read, and https connections
69           denied. Then cockpit-tls will only manage a single cockpit-ws
70           instance, and thus not do anything different than running
71           cockpit-ws --no-tls directly. Only use this for debugging or
72           testing.
73
74       --idle-timeout SECONDS
75           If greater than 0, exit if no connections have happened for the
76           given number of seconds, i. e. the server is idle. If not given,
77           the default is 90.
78

ENVIRONMENT

80       The cockpit-tls program expects the RUNTIME_DIRECTORY environment
81       variable to be set to an empty directory (preferably in /run/) that is
82       only accessible by the system user under which it is running. This
83       contains the Unix sockets for communicating with the cockpit-ws
84       instances, and in the future, state information about client
85       certificates. This variable is normally set by the cockpit.service
86       systemd unit.
87
88       In addition, cockpit-tls will use the XDG_CONFIG_DIRS environment
89       variable from the XDG basedir spec[2] to find its certificates and the
90       cockpit.conf(5) configuration file.
91

BUGS

93       Please send bug reports to either the distribution bug tracker or the
94       upstream bug tracker[3].
95

AUTHOR

97       Cockpit has been written by many contributors[4].
98

NOTES

103        1. cockpit.conf
104           [set $man.base.url.for.relative.links]/./cockpit.conf.5.html
105
106        2. XDG basedir spec
107           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
108
109        3. upstream bug tracker
110           https://github.com/cockpit-project/cockpit/issues/new
111
112        4. contributors
113           https://github.com/cockpit-project/cockpit/graphs/contributors
114
115
116
117cockpit                           12/15/2023                    COCKPIT-TLS(8)