mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-11-03 21:49:50 -09:00
bc62cb3709
Antora uses a dedicated folder structure which we need to adhere to for it to work as it should. Makefiles has moved to `doc/` root to simplify the approach needed with Antora and AsciiDoctor. Existing bundling of documentation with help of AsciiDoctor works as normal and does not interfere with the directory change. Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
73 lines
2.4 KiB
Text
73 lines
2.4 KiB
Text
[[https]]
|
|
= SSL/TLS Usage
|
|
|
|
Cockpit usually requires that web browsers communicate with it using
|
|
HTTPS, for security reasons.
|
|
|
|
[[https-required]]
|
|
== HTTPS Requirement
|
|
|
|
Cockpit listens for both HTTP and HTTPS connections on the same port, by
|
|
default 9090. If an HTTP connection is made, Cockpit will redirect that
|
|
connection to HTTPS. There are some exceptions:
|
|
|
|
* If an HTTP connection comes from `+localhost+` (`+127.0.0.1+` or
|
|
`+::1+`, then Cockpit will allow communication without redirecting to
|
|
HTTPS.
|
|
* Certain URLs, like `+/ping+` are not required to use HTTPS.
|
|
|
|
This behavior can be overridden by setting the `+AllowUnencrypted+`
|
|
option in `+cockpit.conf+`.
|
|
|
|
[[https-certificates]]
|
|
== Certificates
|
|
|
|
Cockpit will load a certificate from the `+/etc/cockpit/ws-certs.d+`,
|
|
directory, or below `+$XDG_CONFIG_DIRS+` if set (see
|
|
link:./cockpit.conf.5.html[cockpit.conf]). It will use the last file
|
|
with a `+.cert+` or `+.crt+` extension in alphabetical order. The file
|
|
should contain one or more OpenSSL style `+BEGIN CERTIFICATE+` blocks
|
|
for the server certificate and the intermediate certificate authorities.
|
|
|
|
The private key must be contained in a separate file with the same name
|
|
as the certificate, but with a `+.key+` suffix instead. The key must not
|
|
be encrypted.
|
|
|
|
If no certificate is found, a self-signed certificate is created and
|
|
stored in the `+0-self-signed.cert+` file. On some platforms, Cockpit
|
|
will also generate a ca.crt in that directory, which may be safely
|
|
imported into client browsers.
|
|
|
|
Cockpit will read the files as root, so they can have tight permissions.
|
|
|
|
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
|
|
....
|
|
|
|
If using `+certmonger+` to manage certificates, following command can be
|
|
used to automatically prepare a certificate/key file pair:
|
|
|
|
....
|
|
getcert request -f /etc/cockpit/ws-certs.d/50-certmonger.cert \
|
|
-k /etc/cockpit/ws-certs.d/50-certmonger.key \
|
|
-D myhostname.example.com \
|
|
[--ca=...]
|
|
....
|
|
|
|
This will not work on Red Hat Enterprise Linux 8 by default. Adjust the
|
|
SELinux type of the certificate directory to `+cert_t+` to allow
|
|
certmonger to write its certificates there:
|
|
|
|
....
|
|
semanage fcontext -a -t cert_t '/etc/cockpit/ws-certs\.d(/.*)?'
|
|
restorecon -v /etc/cockpit/ws-certs.d
|
|
....
|