1COCKPIT-TLS(8) cockpit-tls COCKPIT-TLS(8)
2
3
4
6 cockpit-tls - TLS proxy for Cockpit web service
7
9 cockpit-tls [--help] [--port PORT] [--no-tls] [--idle-timeout SECONDS]
10
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
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. If there are multiple files in this directory, then the
25 highest priority one is chosen after sorting.
26
27 The .cert file should contain at least two OpenSSL style PEM blocks.
28 First one or more BEGIN CERTIFICATE blocks for the server certificate
29 and intermediate certificate authorities and a second one containing a
30 BEGIN PRIVATE KEY or similar. The key must not be encrypted.
31
32 If there is no TLS certificate, a self-signed certificate is
33 automatically generated using sscg (if available) or openssl and stored
34 in the 0-self-signed.cert file.
35
36 When enrolling into a FreeIPA domain, an SSL certificate is requested
37 from the IPA server and stored in 10-ipa.cert.
38
39 To check which certificate cockpit-ws will use, run the following
40 command.
41
42 $ sudo /usr/libexec/cockpit-certificate-ensure --check
43
44 Or, on Debian-based systems:
45
46 $ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check
47
48 If using certmonger to manage certificates, following command can be
49 used to generate a certificate/key pair:
50
51 CERT_FILE=/etc/cockpit/ws-certs.d/50-certmonger.crt
52 KEY_FILE=/etc/cockpit/ws-certs.d/50-certmonger.key
53
54 getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn)
55
57 --help
58 Show help options.
59
60 --port PORT
61 Serve HTTP requests on PORT instead of port 9090. Usually Cockpit
62 is started on demand by systemd socket activation, and this option
63 has no effect. Update the ListenStream directive cockpit.socket
64 file in the usual systemd manner.
65
66 --no-tls
67 Don't use TLS. Certificates will not be read, and https connections
68 denied. Then cockpit-tls will only manage a single cockpit-ws
69 instance, and thus not do anything different than running
70 cockpit-ws --no-tls directly. Only use this for debugging or
71 testing.
72
73 --idle-timeout SECONDS
74 If greater than 0, exit if no connections have happened for the
75 given number of seconds, i. e. the server is idle. If not given,
76 the default is 90.
77
79 The cockpit-tls program expects the RUNTIME_DIRECTORY environment
80 variable to be set to an empty directory (preferably in /run/) that is
81 only accessible by the system user under which it is running. This
82 contains the Unix sockets for communicating with the cockpit-ws
83 instances, and in the future, state information about client
84 certificates. This variable is normally set by the cockpit.service
85 systemd unit.
86
87 In addition, cockpit-tls will use the XDG_CONFIG_DIRS environment
88 variable from the XDG basedir spec[1] to find its certificates and the
89 cockpit.conf(5) configuration file.
90
92 Please send bug reports to either the distribution bug tracker or the
93 upstream bug tracker[2].
94
96 Cockpit has been written by many contributors[3].
97
99 cockpit-ws(8) , cockpit.conf(5) , systemd(1)
100
102 1. XDG basedir spec
103 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
104
105 2. upstream bug tracker
106 https://github.com/cockpit-project/cockpit/issues/new
107
108 3. contributors
109 https://github.com/cockpit-project/cockpit/graphs/contributors
110
111
112
113cockpit 06/23/2022 COCKPIT-TLS(8)