certificate-management.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} cluster creates its own (self-signed) Certificate Authority (CA) and
  13 generates a certificate for each node which gets signed by the aforementioned
  14 CA. These certificates are used for encrypted communication with the cluster's
  15 `pveproxy` service and the Shell/Console feature if SPICE is used.
  16
  17 The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)].
  18
  19 Certificates for API and web GUI
  20 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  21
  22 The REST API and web GUI are provided by the `pveproxy` service, which runs on
  23 each node.
  24
  25 You have the following options for the certificate used by `pveproxy`:
  26
  27 1. By default the node-specific certificate in
  28 `/etc/pve/nodes/NODENAME/pve-ssl.pem` is used. This certificate is signed by
  29 the cluster CA and therefore not trusted by browsers and operating systems by
  30 default.
  31 2. use an externally provided certificate (e.g. signed by a commercial CA).
  32 3. use ACME (e.g., Let's Encrypt) to get a trusted certificate with automatic renewal.
  33
  34 For options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
  35 `/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used.
  36
  37 Certificates are managed with the {PVE} Node management command
  38 (see the `pvenode(1)` manpage).
  39
  40 WARNING: Do not replace or manually modify the automatically generated node
  41 certificate files in `/etc/pve/local/pve-ssl.pem` and
  42 `/etc/pve/local/pve-ssl.key` or the cluster CA files in
  43 `/etc/pve/pve-root-ca.pem` and `/etc/pve/priv/pve-root-ca.key`.
  44 Also keep in mind that `/etc/pve/local` is a symlink to
  45 `/etc/pve/nodes/NODENAME`.
  46
  47 Getting trusted certificates via ACME
  48 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  49 {PVE} includes an implementation of the **A**utomatic **C**ertificate
  50 **M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to
  51 interface with Let's Encrypt for easy setup of trusted TLS certificates which
  52 are accepted out of the box on most modern operating systems and browsers.
  53
  54 Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its
  55 staging environment (see https://letsencrypt.org), both using the standalone
  56 HTTP challenge.
  57
  58 Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use
  59 LE `staging` for experiments.
  60
  61 There are a few prerequisites to use Let's Encrypt:
  62
  63 1. **Port 80** of the node needs to be reachable from the internet.
  64 2. There **must** be no other listener on port 80.
  65 3. The requested (sub)domain needs to resolve to a public IP of the Node.
  66 4. You have to accept the ToS of Let's Encrypt.
  67
  68 At the moment the GUI uses only the default ACME account.
  69
  70 .Example: Sample `pvenode` invocation for using Let's Encrypt certificates
  71
  72 ----
  73 root@proxmox:~# pvenode acme account register default mail@example.invalid
  74 Directory endpoints:
  75 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
  76 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
  77 2) Custom
  78 Enter selection:
  79 1
  80
  81 Attempting to fetch Terms of Service from 'https://acme-staging-v02.api.letsencrypt.org/directory'..
  82 Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
  83 Do you agree to the above terms? [y|N]y
  84
  85 Attempting to register account with 'https://acme-staging-v02.api.letsencrypt.org/directory'..
  86 Generating ACME account key..
  87 Registering ACME account..
  88 Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx'
  89 Task OK
  90 root@proxmox:~# pvenode acme account list
  91 default
  92 root@proxmox:~# pvenode config set --acme domains=example.invalid
  93 root@proxmox:~# pvenode acme cert order
  94 Loading ACME account details
  95 Placing ACME order
  96 Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx
  97
  98 Getting authorization details from
  99 'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx'
 100 ... pending!
 101 Setting up webserver
 102 Triggering validation
 103 Sleeping for 5 seconds
 104 Status is 'valid'!
 105
 106 All domains validated!
 107
 108 Creating CSR
 109 Finalizing order
 110 Checking order status
 111 valid!
 112
 113 Downloading certificate
 114 Setting pveproxy certificate and key
 115 Restarting pveproxy
 116 Task OK
 117 ----
 118
 119 Switching from the `staging` to the regular ACME directory
 120 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 121
 122 Changing the ACME directory for an account is unsupported. If you want to switch
 123 an account from the `staging` ACME directory to the regular, trusted, one you
 124 need to deactivate it and recreate it.
 125
 126 This procedure is also needed to change the default ACME account used in the GUI.
 127
 128 .Example: Changing the `default` ACME account from the `staging` to the regular directory
 129
 130 ----
 131 root@proxmox:~# pvenode acme account info default
 132 Directory URL: https://acme-staging-v02.api.letsencrypt.org/directory
 133 Account URL: https://acme-staging-v02.api.letsencrypt.org/acme/acct/6332194
 134 Terms Of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
 135
 136 Account information:
 137 ID: xxxxxxx
 138 Contact:
 139         - mailto:example@proxmox.com
 140 Creation date: 2018-07-31T08:41:44.54196435Z
 141 Initial IP: 192.0.2.1
 142 Status: valid
 143
 144 root@proxmox:~# pvenode acme account deactivate default
 145 Renaming account file from '/etc/pve/priv/acme/default' to '/etc/pve/priv/acme/_deactivated_default_4'
 146 Task OK
 147
 148 root@proxmox:~# pvenode acme account register default example@proxmox.com
 149 Directory endpoints:
 150 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
 151 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
 152 2) Custom
 153 Enter selection:
 154 0
 155
 156 Attempting to fetch Terms of Service from 'https://acme-v02.api.letsencrypt.org/directory'..
 157 Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
 158 Do you agree to the above terms? [y|N]y
 159
 160 Attempting to register account with 'https://acme-v02.api.letsencrypt.org/directory'..
 161 Generating ACME account key..
 162 Registering ACME account..
 163 Registration successful, account URL: 'https://acme-v02.api.letsencrypt.org/acme/acct/39335247'
 164 Task OK
 165 ----
 166
 167 Automatic renewal of ACME certificates
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 If a node has been successfully configured with an ACME-provided certificate
 171 (either via pvenode or via the GUI), the certificate will be automatically
 172 renewed by the pve-daily-update.service. Currently, renewal will be attempted
 173 if the certificate has expired or will expire in the next 30 days.