'\" t
.\"     Title: cockpit-tls
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/15/2024
.\"    Manual: cockpit-tls
.\"    Source: cockpit
.\"  Language: English
.\"
.TH "COCKPIT\-TLS" "8" "02/15/2024" "cockpit" "cockpit-tls"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cockpit-tls \- TLS proxy for Cockpit web service
.SH "SYNOPSIS"
.HP \w'\fBcockpit\-tls\fR\ 'u
\fBcockpit\-tls\fR [\fB\-\-help\fR] [\fB\-\-port\fR\ \fIPORT\fR] [\fB\-\-no\-tls\fR] [\fB\-\-idle\-timeout\fR\ \fISECONDS\fR]
.SH "DESCRIPTION"
.PP
The
\fBcockpit\-tls\fR
program is a TLS terminating HTTP proxy for
\fBcockpit-ws\fR(8)\&. It manages a set of isolated cockpit\-ws instances, one per TLS client certificate, plus one for TLS without a client certificate, and one for unencrypted HTTP\&. With that, one session cannot tamper with another one through possible security vulnerability exploits\&.
.PP
Users or administrators should never need to start this program as it automatically started by
\fBsystemd\fR(1)
via socket activation\&.
.SH "TRANSPORT SECURITY"
.PP
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
\m[blue]\fBcockpit\&.conf\fR\m[]\&\s-2\u[1]\d\s+2)\&. If there are multiple files in this directory, then the highest priority one is chosen after sorting\&.
.PP
The
\&.cert
file should contain at least two OpenSSL style PEM blocks\&. First one or more
BEGIN CERTIFICATE
blocks for the server certificate and intermediate certificate authorities and a second one containing a
BEGIN PRIVATE KEY
or similar\&. The key must not be encrypted\&.
.PP
If there is no TLS certificate, a self\-signed certificate is automatically generated using
\fBsscg\fR
(if available) or
\fBopenssl\fR
and stored in the
0\-self\-signed\&.cert
file\&.
.PP
When enrolling into a FreeIPA domain, an SSL certificate is requested from the IPA server and stored in
10\-ipa\&.cert\&.
.PP
To check which certificate
\fBcockpit\-ws\fR
will use, run the following command\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sudo /usr/libexec/cockpit\-certificate\-ensure \-\-check
.fi
.if n \{\
.RE
.\}
.PP
Or, on Debian\-based systems:
.sp
.if n \{\
.RS 4
.\}
.nf
$ sudo /usr/lib/cockpit/cockpit\-certificate\-ensure \-\-check
.fi
.if n \{\
.RE
.\}
.PP
If using
certmonger
to manage certificates, following command can be used to generate a certificate/key pair:
.sp
.if n \{\
.RS 4
.\}
.nf
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)
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.PP
\fB\-\-help\fR
.RS 4
Show help options\&.
.RE
.PP
\fB\-\-port\fR \fIPORT\fR
.RS 4
Serve HTTP requests on
\fIPORT\fR
instead of port 9090\&. Usually Cockpit is started on demand by
\fBsystemd\fR
socket activation, and this option has no effect\&. Update the
ListenStream
directive
cockpit\&.socket
file in the usual
\fBsystemd\fR
manner\&.
.RE
.PP
\fB\-\-no\-tls\fR
.RS 4
Don\*(Aqt use TLS\&. Certificates will not be read, and https connections denied\&. Then
\fBcockpit\-tls\fR
will only manage a single cockpit\-ws instance, and thus not do anything different than running
\fBcockpit\-ws \-\-no\-tls\fR
directly\&. Only use this for debugging or testing\&.
.RE
.PP
\fB\-\-idle\-timeout\fR \fISECONDS\fR
.RS 4
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\&.
.RE
.SH "ENVIRONMENT"
.PP
The
\fBcockpit\-tls\fR
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 is running\&. This contains the Unix sockets for communicating with the
\fBcockpit\-ws\fR
instances, and in the future, state information about client certificates\&. This variable is normally set by the
cockpit\&.service
systemd unit\&.
.PP
In addition,
\fBcockpit\-tls\fR
will use the
XDG_CONFIG_DIRS
environment variable from the
\m[blue]\fBXDG basedir spec\fR\m[]\&\s-2\u[2]\d\s+2
to find its certificates and the
\fBcockpit.conf\fR(5)
configuration file\&.
.SH "BUGS"
.PP
Please send bug reports to either the distribution bug tracker or the
\m[blue]\fBupstream bug tracker\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "AUTHOR"
.PP
Cockpit has been written by many
\m[blue]\fBcontributors\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SH "SEE ALSO"
.PP
\fBcockpit-ws\fR(8)
,
\fBcockpit.conf\fR(5)
,
\fBsystemd\fR(1)
.SH "NOTES"
.IP " 1." 4
cockpit.conf
.RS 4
\%[set $man.base.url.for.relative.links]/./cockpit.conf.5.html
.RE
.IP " 2." 4
XDG basedir spec
.RS 4
\%https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
.RE
.IP " 3." 4
upstream bug tracker
.RS 4
\%https://github.com/cockpit-project/cockpit/issues/new
.RE
.IP " 4." 4
contributors
.RS 4
\%https://github.com/cockpit-project/cockpit/graphs/contributors
.RE