-
Notifications
You must be signed in to change notification settings - Fork 228
/
Copy pathhttps.html
92 lines (92 loc) · 5.17 KB
/
https.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
---
layout: guide
---
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SSL/TLS Usage</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Cockpit Guide">
<link rel="up" href="guide.html" title="Part I. Deployment Guide">
<link rel="prev" href="cockpit-bridge.1.html" title="cockpit-bridge">
<link rel="next" href="listen.html" title="TCP Port and Address">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="cockpit-bridge.1.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="guide.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cockpit Guide</th>
<td><a accesskey="n" href="listen.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="https"></a>SSL/TLS Usage</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="https.html#https-required">HTTPS Requirement</a></span></dt>
<dt><span class="section"><a href="https.html#https-certificates">Certificates</a></span></dt>
</dl></div>
<p>Cockpit usually requires that web browsers communicate with it using HTTPS,
for security reasons.</p>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="https-required"></a>HTTPS Requirement</h2></div></div></div>
<p>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:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>If an HTTP connection comes from <code class="code">localhost</code> (<code class="code">127.0.0.1</code> or
<code class="code">::1</code>, then Cockpit will allow communication without redirecting to HTTPS.</p></li>
<li class="listitem"><p>Certain URLs, like <code class="code">/ping</code> are not required to use
HTTPS.</p></li>
</ul></div>
<p>This behavior can be overridden by setting the
<code class="code">AllowUnencrypted</code> option in <code class="code">cockpit.conf</code>.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="https-certificates"></a>Certificates</h2></div></div></div>
<p>Cockpit will load a certificate from the <code class="code">/etc/cockpit/ws-certs.d</code>,
directory, or below <code class="code">$XDG_CONFIG_DIRS</code> if set (see
<a class="ulink" href="./cockpit.conf.5.html" target="_top">cockpit.conf</a>).
It will use the last file with a <code class="code">.cert</code> or <code class="code">.crt</code>
extension in alphabetical order. The file should contain one or more OpenSSL
style <code class="literal">BEGIN CERTIFICATE</code> blocks for the server certificate and
the intermediate certificate authorities.</p>
<p>
The private key must be contained in a separate file with the same name as the
certificate, but with a <code class="code">.key</code> suffix instead. The key must not be
encrypted.</p>
<p>If no certificate is found, a self-signed certificate is created and
stored in the <code class="filename">0-self-signed.cert</code> file. On some
platforms, Cockpit will also generate a ca.crt in that directory, which
may be safely imported into client browsers.</p>
<p>Cockpit will read the files as root, so they can have tight
permissions.</p>
<p>To check which certificate <code class="code">cockpit-ws</code> will use run
the following command.</p>
<pre class="programlisting">
$ sudo /usr/libexec/cockpit-certificate-ensure --check
</pre>
<p>Or, on Debian-based systems:</p>
<pre class="programlisting">
$ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check
</pre>
<p>If using <code class="code">certmonger</code> to manage certificates, following command can
be used to automatically prepare a certificate/key file pair:</p>
<pre class="programlisting">
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=...]</pre>
<p>This will not work on Red Hat Enterprise Linux 8 by default. Adjust the SELinux type of the certificate directory to <code class="code">cert_t</code> to allow certmonger to write its certificates there:</p>
<pre class="programlisting">
semanage fcontext -a -t cert_t '/etc/cockpit/ws-certs\.d(/.*)?'
restorecon -v /etc/cockpit/ws-certs.d</pre>
</div>
</div>
<div class="footer"><hr></div>
</body>
</html>