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