certificate-managment.adoc

   1 [[sysadmin_certificate_management]]
   2 Certificate Management
   3 ----------------------
   4 ifdef::wiki[]
   5 :pve-toplevel:
   6 endif::wiki[]
   7
   8
   9 Certificates for communication within the cluster
  10 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  11
  12 Each {PVE} installation creates its own Certificate Authority (CA) and generates
  13 certificates for each node. These are used for encrypted communication within
  14 the cluster.
  15
  16 The CA certificate and key are stored in the `pmxcfs` (see the `pmxcfs(8)`
  17 manpage).
  18
  19 Certificates for API and web GUI
  20 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  21
  22 The API and web GUI are provided by `pveproxy`.
  23
  24 You have the following options for the certificate used by `pveproxy`:
  25
  26 1. By default the node-specific certificate in `/etc/pve/local/pve-ssl.pem` is
  27 used. This certificate is signed by the cluster CA and therfore not trusted by
  28 browsers and operating systems by default.
  29 2. use an externally provided certificate (e.g. signed by an external CA).
  30 3. use ACME (Let's Encrypt) to get a trusted certificate with automatic renewal.
  31
  32 For Options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
  33 `/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used.
  34
  35 Certificates are managed with the {PVE} Node management command
  36 (see the `pvenode(1)` manpage).
  37
  38 WARNING: Do not replace the automatically generated node certificate
  39 files in `/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key` or
  40 the cluster CA files in `/etc/pve/pve-root-ca.pem` and
  41 `/etc/pve/priv/pve-root-ca.key`.
  42
  43 Getting trusted certificates via ACME
  44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  45 {PVE} includes an implementation of the **A**utomatic **C**ertificate
  46 **M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to
  47 interface with Let's Encrypt, with which trusted certificates can be generated
  48 and setup easily.
  49
  50 This enables you to get a Certificate that is accepted by Browsers for public
  51 facing nodes.
  52
  53 Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its
  54 staging environment (see https://letsencrypt.org), both using the standalone
  55 HTTP challenge.
  56
  57 Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use
  58 LE `staging` for experiments.
  59
  60 There are a few prerequisites to use Let's Encrypt:
  61
  62 1. **Port 80** of the node needs to be reachable from the internet.
  63 2. There **must** be no other listener on port 80.
  64 3. Your (sub)domain needs to resolve to the public IP of the Node.
  65 4. You have to accept the ToS of Let's Encrypt.
  66
  67 At the moment the GUI uses only the default ACME account.
  68
  69 .Example: Sample `pvenode` invocation for using Let's Encrypt certificates
  70
  71 -----------------
  72 root@proxmox:~# pvenode acme account register default mail@example.invalid
  73 Directory endpoints:
  74 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
  75 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
  76 2) Custom
  77 Enter selection:
  78 1
  79
  80 Attempting to fetch Terms of Service from 'https://acme-staging-v02.api.letsencrypt.org/directory'..
  81 Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
  82 Do you agree to the above terms? [y|N]y
  83
  84 Attempting to register account with 'https://acme-staging-v02.api.letsencrypt.org/directory'..
  85 Generating ACME account key..
  86 Registering ACME account..
  87 Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx'
  88 Task OK
  89 root@proxmox:~# pvenode acme account list
  90 default
  91 root@proxmox:~# pvenode config set --acme domains=example.invalid
  92 root@proxmox:~# pvenode acme cert order
  93 Loading ACME account details
  94 Placing ACME order
  95 Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx
  96
  97 Getting authorization details from
  98 'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx'
  99 ... pending!
 100 Setting up webserver
 101 Triggering validation
 102 Sleeping for 5 seconds
 103 Status is 'valid'!
 104
 105 All domains validated!
 106
 107 Creating CSR
 108 Finalizing order
 109 Checking order status
 110 valid!
 111
 112 Downloading certificate
 113 Setting pveproxy certificate and key
 114 Restarting pveproxy
 115 Task OK
 116 -----------------