COCKPIT-TLS(8)

💖 COCKPIT-TLS 💖

okay bestie, welcome to cockpit-tls(8) — the TLS proxy for the Cockpit web service. this is the whole page, every flag, every file path, no cap. let's get into it 🫶

---

✨ NAME ✨

cockpit-tls — TLS proxy for Cockpit web service

---

📜 SYNOPSIS 📜

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

---

🌸 DESCRIPTION 🌸

so the cockpit-tls program is a TLS terminating HTTP proxy for cockpit-ws(8). it's giving bodyguard energy fr.

here's the vibe: it manages a whole set of isolated cockpit-ws instances —

• one per TLS client certificate 💅
• plus one for TLS with no client certificate
• and one for unencrypted HTTP

and the reason is lowkey iconic: with that setup, one session literally cannot tamper with another one through possible security vulnerability exploits. separation is the whole point, periodt.

bestie, heads up: users or administrators should never need to start this program. it's automatically started by systemd(1) via socket activation. let the machine do its thing. ✨

---

🔐 TRANSPORT SECURITY 🔐

the certificate situation

to specify the TLS certificate the web service should use, simply drop a file with the extension .cert in the /etc/cockpit/ws-certs.d directory, or below $XDG_CONFIG_DIRS if set (see cockpit.conf(5)). super simple, no drama.

if there are multiple files in this directory, then the highest priority one is chosen after sorting. so yeah, the sort order is the ranking. 👑

what goes inside a .cert file

the .cert file should contain at least two OpenSSL style PEM blocks:

1. first, one or more BEGIN CERTIFICATE blocks for the server certificate and intermediate certificate authorities
2. and a second one containing a BEGIN PRIVATE KEY or similar

⚠️ and the key must not be encrypted. noted, bestie, don't do it.

no cert? no problem

if there is no TLS certificate at all, a self-signed certificate is automatically generated using sscg (if available) or openssl and stored in the 0-self-signed.cert file. the girlies always come prepared 💅

FreeIPA girlies

when enrolling into a FreeIPA domain, an SSL certificate is requested from the IPA server and stored in 10-ipa.cert. slay.

checking which cert gets used

to check which certificate cockpit-ws will use, run the following command:

$ sudo /usr/libexec/cockpit-certificate-ensure --check

or, on Debian-based systems:

$ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check

certmonger besties

if using certmonger to manage certificates, the following command can be used to generate a certificate/key pair:

CERT_FILE=/etc/cockpit/ws-certs.d/50-certmonger.crt
KEY_FILE=/etc/cockpit/ws-certs.d/50-certmonger.key

getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn)

---

✨ OPTIONS ✨

okay this is the part you're actually here for. every single one 🎀

• --help — shows the help options. that's it, that's the girl.
• --port PORT — serve HTTP requests on PORT instead of port 9090. but ngl, usually Cockpit is started on demand by systemd socket activation, and this option has no effect in that case. instead, update the ListenStream directive in the cockpit.socket file the usual systemd manner. iykyk.
• --no-tls — don't use TLS. certificates will not be read, and https connections denied. then cockpit-tls will only manage a single cockpit-ws instance, and thus not do anything different than running cockpit-ws --no-tls directly. only use this for debugging or testing. 🙈
• --idle-timeout SECONDS — if greater than 0, exit if no connections have happened for the given number of seconds, i.e. the server is idle. if not given, the default is 90. bye girl, nobody's calling 💀

---

🌈 ENVIRONMENT 🌈

the cockpit-tls program expects the RUNTIME_DIRECTORY environment variable to be set to an empty directory (preferably in /run/) that is only accessible by the system user under which it's running. this contains:

• the Unix sockets for communicating with the cockpit-ws instances, and
• in the future, state information about client certificates

this variable is normally set by the cockpit.service systemd unit. love that for us. 🫶

in addition, cockpit-tls will use the XDG_CONFIG_DIRS environment variable from the XDG basedir spec to find its certificates and the cockpit.conf(5) configuration file.

---

🐛 BUGS 🐛

please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://github.com/cockpit-project/cockpit/issues/new. do not suffer in silence bestie, tell the devs. 💜

---

👑 AUTHOR 👑

Cockpit has been written by many contributors — https://github.com/cockpit-project/cockpit. it's giving collaborative, it's giving community, it's giving iconic ✨

---

🦋 SEE ALSO 🦋

cockpit-ws(8), cockpit.conf(5), systemd(1)

---

and that's the whole page, periodt 💅 this was cockpit version 2026-10-22, straight from the COCKPIT-TLS(8) page. go forth and let systemd handle it, bestie, you deserve the rest 🌸🎀