You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

172 line
6.4KB

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