mirror of
git://git.proxmox.com/git/pve-docs.git
synced 2025-01-06 13:17:48 +03:00
add documentation for certificate managment
* new section about certificate management in sysadmin chapter. * adaptation of pveproxy and pvenode documentation Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com> Co-authored-by: René Jochum <r.jochum@proxmox.com>
This commit is contained in:
Stoiko Ivanov
Fabian Grünbichler
parent
f3af3a6d56
commit
aeecd9ea39
116
certificate-managment.adoc
Normal file
116
certificate-managment.adoc
Normal file
@ -0,0 +1,116 @@
|
||||
[[sysadmin_certificate_management]]
|
||||
Certificate Management
|
||||
----------------------
|
||||
ifdef::wiki[]
|
||||
:pve-toplevel:
|
||||
endif::wiki[]
|
||||
|
||||
|
||||
Certificates for communication within the cluster
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Each {PVE} installation creates its own Certificate Authority (CA) and generates
|
||||
certificates for each node. These are used for encrypted communication within
|
||||
the cluster.
|
||||
|
||||
The CA certificate and key are stored in the `pmxcfs` (see the `pmxcfs(8)`
|
||||
manpage).
|
||||
|
||||
Certificates for API and web GUI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The API and web GUI are provided by `pveproxy`.
|
||||
|
||||
You have the following options for the certificate used by `pveproxy`:
|
||||
|
||||
1. By default the node-specific certificate in `/etc/pve/local/pve-ssl.pem` is
|
||||
used. This certificate is signed by the cluster CA and therfore not trusted by
|
||||
browsers and operating systems by default.
|
||||
2. use an externally provided certificate (e.g. signed by an external CA).
|
||||
3. use ACME (Let's Encrypt) to get a trusted certificate with automatic renewal.
|
||||
|
||||
For Options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
|
||||
`/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used.
|
||||
|
||||
Certificates are managed with the {PVE} Node management command
|
||||
(see the `pvenode(1)` manpage).
|
||||
|
||||
WARNING: Do not replace the automatically generated node certificate
|
||||
files in `/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key` or
|
||||
the cluster CA files in `/etc/pve/pve-root-ca.pem` and
|
||||
`/etc/pve/priv/pve-root-ca.key`.
|
||||
|
||||
Getting trusted certificates via ACME
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
{PVE} includes an implementation of the **A**utomatic **C**ertificate
|
||||
**M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to
|
||||
interface with Let's Encrypt, with which trusted certificates can be generated
|
||||
and setup easily.
|
||||
|
||||
This enables you to get a Certificate that is accepted by Browsers for public
|
||||
facing nodes.
|
||||
|
||||
Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its
|
||||
staging environment (see https://letsencrypt.org), both using the standalone
|
||||
HTTP challenge.
|
||||
|
||||
Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use
|
||||
LE `staging` for experiments.
|
||||
|
||||
There are a few prerequisites to use Let's Encrypt:
|
||||
|
||||
1. **Port 80** of the node needs to be reachable from the internet.
|
||||
2. There **must** be no other listener on port 80.
|
||||
3. Your (sub)domain needs to resolve to the public IP of the Node.
|
||||
4. You have to accept the ToS of Let's Encrypt.
|
||||
|
||||
At the moment the GUI uses only the default ACME account.
|
||||
|
||||
.Example: Sample `pvenode` invocation for using Let's Encrypt certificates
|
||||
|
||||
-----------------
|
||||
root@proxmox:~# pvenode acme account register default mail@example.invalid
|
||||
Directory endpoints:
|
||||
0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
|
||||
1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
|
||||
2) Custom
|
||||
Enter selection:
|
||||
1
|
||||
|
||||
Attempting to fetch Terms of Service from 'https://acme-staging-v02.api.letsencrypt.org/directory'..
|
||||
Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
|
||||
Do you agree to the above terms? [y|N]y
|
||||
|
||||
Attempting to register account with 'https://acme-staging-v02.api.letsencrypt.org/directory'..
|
||||
Generating ACME account key..
|
||||
Registering ACME account..
|
||||
Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx'
|
||||
Task OK
|
||||
root@proxmox:~# pvenode acme account list
|
||||
default
|
||||
root@proxmox:~# pvenode config set --acme domains=example.invalid
|
||||
root@proxmox:~# pvenode acme cert order
|
||||
Loading ACME account details
|
||||
Placing ACME order
|
||||
Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx
|
||||
|
||||
Getting authorization details from
|
||||
'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx'
|
||||
... pending!
|
||||
Setting up webserver
|
||||
Triggering validation
|
||||
Sleeping for 5 seconds
|
||||
Status is 'valid'!
|
||||
|
||||
All domains validated!
|
||||
|
||||
Creating CSR
|
||||
Finalizing order
|
||||
Checking order status
|
||||
valid!
|
||||
|
||||
Downloading certificate
|
||||
Setting pveproxy certificate and key
|
||||
Restarting pveproxy
|
||||
Task OK
|
||||
-----------------
|
||||
26
pvenode.adoc
26
pvenode.adoc
@ -6,7 +6,7 @@ pvenode(1)
|
||||
NAME
|
||||
----
|
||||
|
||||
pvenode - Proxmox VE Node Management
|
||||
pvenode - {PVE} Node Management
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
@ -26,11 +26,25 @@ endif::manvolnum[]
|
||||
The {PVE} node management tools (`pvenode`) allows to control node specific
|
||||
settings and resources.
|
||||
|
||||
Currently the `pvenode` tool allows to manage the node's SSL certificates used
|
||||
for API and the web GUI. It includes an implementation of the **A**utomatic
|
||||
**C**ertificate **M**anagement **E**nvironment (ACME) protocol, allowing {pve}
|
||||
admins to interface with Let's Encrypt, with which trusted certificates can be
|
||||
generated and setup easily.
|
||||
Currently `pvenode` allows to set a node's description and to manage
|
||||
the node's SSL certificates used for the API and the web GUI through `pveproxy`.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
`pvenode cert set certificate.crt certificate.key -force`
|
||||
|
||||
Install an externally provided certificate. Both files need to be PEM encoded.
|
||||
`certificate.key` contains the private key and `certificate.crt` contains the
|
||||
whole certificate chain.
|
||||
|
||||
-----
|
||||
pvenode acme account register default mail@example.invalid
|
||||
pvenode config set --acme domains=example.invalid
|
||||
pvenode acme cert order
|
||||
systemctl restart pveproxy
|
||||
-----
|
||||
|
||||
Configure acme to get certificates.
|
||||
|
||||
// TODO: extend and improve chapter!
|
||||
|
||||
|
||||
@ -88,26 +88,15 @@ exchange algorithm is negotiated.
|
||||
Alternative HTTPS certificate
|
||||
-----------------------------
|
||||
|
||||
By default, pveproxy uses the certificate `/etc/pve/local/pve-ssl.pem`
|
||||
(and private key `/etc/pve/local/pve-ssl.key`) for HTTPS connections.
|
||||
This certificate is signed by the cluster CA certificate, and therefor
|
||||
not trusted by browsers and operating systems by default.
|
||||
You can change the certificate used, to an external one or to one obtained via
|
||||
ACME.
|
||||
|
||||
In order to use a different certificate and private key for HTTPS,
|
||||
store the server certificate and any needed intermediate / CA
|
||||
certificates in PEM format in the file `/etc/pve/local/pveproxy-ssl.pem`
|
||||
and the associated private key in PEM format without a password in the
|
||||
file `/etc/pve/local/pveproxy-ssl.key`.
|
||||
pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and
|
||||
`/etc/pve/local/pveproxy-ssl.key`, if present, and falls back to
|
||||
`/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key`.
|
||||
The private key may not use a passphrase.
|
||||
|
||||
WARNING: Do not replace the automatically generated node certificate
|
||||
files in `/etc/pve/local/pve-ssl.pem` and `etc/pve/local/pve-ssl.key` or
|
||||
the cluster CA files in `/etc/pve/pve-root-ca.pem` and
|
||||
`/etc/pve/priv/pve-root-ca.key`.
|
||||
|
||||
NOTE: There is a detailed HOWTO for configuring commercial HTTPS certificates
|
||||
on the {webwiki-url}HTTPS_Certificate_Configuration_(Version_4.x_and_newer)[wiki],
|
||||
including setup instructions for obtaining certificates from the popular free
|
||||
Let's Encrypt certificate authority.
|
||||
See the Host System Administration chapter of the documentation for details.
|
||||
|
||||
ifdef::manvolnum[]
|
||||
include::pve-copyright.adoc[]
|
||||
|
||||
@ -50,6 +50,7 @@ See Also
|
||||
|
||||
* link:/wiki/ZFS_on_Linux[ZFS on Linux]
|
||||
|
||||
* link:/wiki/Certificate_Management[Certificate Managment]
|
||||
endif::wiki[]
|
||||
|
||||
|
||||
@ -71,6 +72,8 @@ include::local-lvm.adoc[]
|
||||
|
||||
include::local-zfs.adoc[]
|
||||
|
||||
include::certificate-managment.adoc[]
|
||||
|
||||
endif::wiki[]
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user