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