diff --git a/images/screenshot/pmg-gui-acme-add-domain.png b/images/screenshot/pmg-gui-acme-add-domain.png new file mode 100644 index 0000000..3255e2e Binary files /dev/null and b/images/screenshot/pmg-gui-acme-add-domain.png differ diff --git a/images/screenshot/pmg-gui-acme-create-account.png b/images/screenshot/pmg-gui-acme-create-account.png new file mode 100644 index 0000000..bd20b0e Binary files /dev/null and b/images/screenshot/pmg-gui-acme-create-account.png differ diff --git a/images/screenshot/pmg-gui-acme-create-challenge-plugin.png b/images/screenshot/pmg-gui-acme-create-challenge-plugin.png new file mode 100644 index 0000000..7a58ece Binary files /dev/null and b/images/screenshot/pmg-gui-acme-create-challenge-plugin.png differ diff --git a/images/screenshot/pmg-gui-certs-upload-custom.png b/images/screenshot/pmg-gui-certs-upload-custom.png new file mode 100644 index 0000000..37eef2e Binary files /dev/null and b/images/screenshot/pmg-gui-certs-upload-custom.png differ diff --git a/pmg-admin-guide.adoc b/pmg-admin-guide.adoc index 15ca793..043b94a 100644 --- a/pmg-admin-guide.adoc +++ b/pmg-admin-guide.adoc @@ -96,10 +96,6 @@ include::pmg-bibliography.adoc[] :leveloffset: 0 -[appendix] -include::pmg-ssl-certificate.adoc[] - - [appendix] Command Line Interface ---------------------- diff --git a/pmg-ssl-certificate.adoc b/pmg-ssl-certificate.adoc index 2afc814..7824f22 100644 --- a/pmg-ssl-certificate.adoc +++ b/pmg-ssl-certificate.adoc @@ -1,9 +1,215 @@ -SSL certificate ---------------- +[[sysadmin_certificate_management]] +Certificate Management +---------------------- -Access to the administration web interface is always done via -`https`. The default certificate is never valid for your browser and -you always get warnings. +Access to the administration web-interface is always encrypted through `https`. +Each {pmg} host creates by default its own (self-signed) Certificate Authority +(CA) and generates a certificate for the node which gets signed by the +aforementioned CA. +These certificates are used for encrypted communication with +the cluster's `pmgproxy` service for any API call, between an user and the +web-interface or between nodes in a cluster. + +[[sysadmin_certs_api_gui]] +Certificates for the API and SMTP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +{pmg} knows two different certificates: + +* `/etc/pmg/pmg-api.pem`: the required certificate used for {pmg} API requests. +* `/etc/pmg/pmg-tls.pem`: the optional certificate used for SMTP TLS + connections, see xref:pmgconfig_mailproxy_tls[mailproxy TLS configuration] + for details. + +You have the following options for those certificates: + +1. keep using the default self-signed certificate in `/etc/pmg/pmg-api.pem`. +2. use an externally provided certificate (for example, signed by a commercial +Certificate Authority (CA)). +3. use an ACME provider like Let's Encrypt to get a trusted certificate with +automatic renewal, this is also integrated in the {pmg} API and Webinterface. + +Certificates are managed through the {pmg} web-interface/API or using the +the `pmgconfig` CLI tool. + +[[sysadmin_certs_upload_custom]] +Upload Custom Certificate +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you already have a certificate which you want to use for a {pmg} host, you +can upload that certificate simply over the web interface. + +[thumbnail="pmg-gui-certs-upload-custom.png"] + +Note that any certificates key file must not be password protected. + +[[sysadmin_certs_get_trusted_acme_cert]] +Trusted certificates via Let's Encrypt (ACME) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +{PMG} includes an implementation of the **A**utomatic **C**ertificate +**M**anagement **E**nvironment **ACME** protocol, allowing {pmg} admins to +interface with Let's Encrypt for easy setup of trusted TLS certificates which +are accepted out of the box on most modern operating systems and browsers. + +Currently the two ACME endpoints implemented are the +https://letsencrypt.org[Let's Encrypt (LE)] production and its staging +environment. Our ACME client supports validation of `http-01` challenges using +a built-in webserver and validation of `dns-01` challenges using a DNS plugin +supporting all the DNS API endpoints https://acme.sh[acme.sh] does. + +[[sysadmin_certs_acme_account]] +ACME Account +^^^^^^^^^^^^ + +[thumbnail="pmg-gui-acme-create-account.png"] + +You need to register an ACME account per cluster with the endpoint you want to +use. The email address used for that account will server as contact point for +renewal-due or similar notifications from the ACME endpoint. + +You can register or deactivate ACME accounts over the web interface +`Certificates -> ACME Accounts` or using the `pmgconfig` command line tool. +---- + pmgconfig acme account register +---- + +TIP: Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you +should use LE `staging` for experiments or if you use ACME for the very first +time until all is working there, and only then switch over to the production +directory. + +[[sysadmin_certs_acme_plugins]] +ACME Plugins +^^^^^^^^^^^^ + +The ACME plugins task is to provide automatic verification that you, and thus +the {pmg} cluster under your operation, are the real owner of a domain. This is +the basis building block for automatic certificate management. + +The ACME protocol specifies different types of challenges, for example the +`http-01` where a webserver provides a file with a certain value to prove that +it controls a domain. Sometimes this isn't possible, either because of +technical limitations or if the address a domain points to is not reachable +from the public internet. For such cases, one could use the `dns-01` challenge. +This challenge also provides a certain value, but through a DNS record on the +authority name server of the domain, rather than over a text file. + +[thumbnail="pmg-gui-acme-create-challenge-plugin.png"] + +{pve} supports both of those challenge types out of the box, you can configure +plugins either over the web interface under `Datacenter -> ACME`, or using the +`pvenode acme plugin add` command. + +ACME Plugin configurations are stored in `/etc/pve/priv/acme/plugins.cfg`. +A plugin is available for all nodes in the cluster. + +Domains +^^^^^^^ + +You can add new or manage existing domain entries under `Certificates`, or +using the `pmgconfig` command. + +[thumbnail="pmg-gui-acme-add-domain.png"] + +After configuring the desired domain(s) for a node and ensuring that the +desired ACME account is selected, you can order your new certificate over the +web-interface. On success the interface will reload after circa 10 seconds. + +Renewal will happen xref:sysadmin_certs_acme_automatic_renewal[automatically]. + +[[sysadmin_certs_acme_http_challenge]] +ACME HTTP Challenge Plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There is always an implicitly configured `standalone` plugin for validating +`http-01` challenges via the built-in webserver spawned on port 80. + +NOTE: The name `standalone` means that it can provide the validation on it's +own, without any third party service. So, this plugin works also for cluster +nodes. + +There are a few prerequisites to use it for certificate management with Let's +Encrypts ACME. + +* You have to accept the ToS of Let's Encrypt to register an account. +* **Port 80** of the node needs to be reachable from the internet. +* There **must** be no other listener on port 80. +* The requested (sub)domain needs to resolve to a public IP of the {pmg} host. + + +[[sysadmin_certs_acme_dns_challenge]] +ACME DNS API Challenge Plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On systems where external access for validation via the `http-01` method is +not possible or desired, it is possible to use the `dns-01` validation method. +This validation method requires a DNS server that allows provisioning of `TXT` +records via an API. + +[[sysadmin_certs_acme_dns_api_config]] +Configuring ACME DNS APIs for validation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +{PVE} re-uses the DNS plugins developed for the `acme.sh` +footnote:[acme.sh https://github.com/acmesh-official/acme.sh] +project, please refer to its documentation for details on configuration of +specific APIs. + +The easiest way to configure a new plugin with the DNS API is using the web +interface (`Certificates -> ACME Accounts/Challenges`). + +[thumbnail="pmg-gui-acme-create-challenge-plugin.png"] + +Add a new challenge plugin, here you can select your API provider, enter the +credential data to access your account over their API. + +TIP: See the acme.sh +https://github.com/acmesh-official/acme.sh/wiki/dnsapi#how-to-use-dns-api[How to use DNS API] +wiki for more detailed information about getting API credentials for your +provider. Configuration values do not need to be quoted with single or double +quotes, for some plugins that is even an error. + +As there are many DNS providers and API endpoints {pmg} autogenerates the form +for the credentials, but not all providers are annotated yet. For those you +will see a bigger text area, simply copy all the credentials `KEY`=`VALUE` +pairs in there. + +DNS Validation through CNAME Alias +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A special `alias` mode can be used to handle the validation on a different +domain/DNS server, in case your primary/real DNS does not support provisioning +via an API. Manually set up a permanent `CNAME` record for +`_acme-challenge.domain1.example` pointing to `_acme-challenge.domain2.example` +and set the `alias` property in the {pmg} node configuration file +`/etc/pmg/node.conf` to `domain2.example` to allow the DNS server of +`domain2.example` to validate all challenges for `domain1.example`. + + +Combination of Plugins +^^^^^^^^^^^^^^^^^^^^^^ + +Combining `http-01` and `dns-01` validation is possible in case your node is +reachable via multiple domains with different requirements / DNS provisioning +capabilities. Mixing DNS APIs from multiple providers or instances is also +possible by specifying different plugin instances per domain. + +TIP: Accessing the same service over multiple domains increases complexity and +should be avoided if possible. + +[[sysadmin_certs_acme_automatic_renewal]] +Automatic renewal of ACME certificates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a node has been successfully configured with an ACME-provided certificate +(either via pmgconfig or via the web-interface/API), the certificate will be +automatically renewed by the `pmg-daily.service`. Currently, renewal is +triggered if the certificate either already expired or if it will expire in the +next 30 days. + +Manually Change Certificate over Command-Line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to get rid of these warnings, you have to generate a valid certificate for your server. @@ -49,21 +255,22 @@ systemctl restart pmgproxy Test your new certificate by using your browser. -NOTE: To transfer files from and to your {pmg}, you can use secure -copy: If you desktop is Linux, you can use the `scp` command line -tool. If your desktop PC is windows, please use a scp client like -WinSCP (see https://winscp.net/). - +NOTE: To transfer files from and to your {pmg}, you can use secure copy: If you +desktop is Linux, you can use the `scp` command line tool. If your desktop PC +is windows, please use a scp client like WinSCP (see https://winscp.net/). Change Certificate for Cluster Setups ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you change the API certificate of an active cluster node, you also -need to update the fingerprint inside the cluster configuration file -`cluster.conf`. It is best to edit that file on the master node. +If you change the API certificate of an active cluster node manually, you also +need to update the pinned fingerprint inside the cluster configuration. -To show the actual fingerprint use: +You can do that by executing the following command on the host where the +certificate changed: ---- -openssl x509 -in /etc/pmg/pmg-api.pem -noout -fingerprint -sha256 +pmgcm update-fingerprints ---- + +Note, this will be done automatically if using the integrated ACME (for +example, through Let's Encrypt) feature. diff --git a/pmgconfig.adoc b/pmgconfig.adoc index 8697b3b..d43d5af 100644 --- a/pmgconfig.adoc +++ b/pmgconfig.adoc @@ -288,6 +288,8 @@ using the following configuration keys: include::pmg.admin-conf-opts.adoc[] +include::pmg-ssl-certificate.adoc[] + Mail Proxy Configuration ------------------------