-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 get always warnings.
+Access to the web-based administration interface is always encrypted through
+`https`. Each {pmg} host creates by default its own (self-signed) certificate.
+This certificate is used for encrypted communication with the host's `pmgproxy`
+service, for any API call between a user and the web-interface or between nodes
+in a cluster.
-If you want to get rid of these warnings, you have to generate a valid
-certificate for your server.
+Certificate verification in a {pmg} cluster is done based on pinning the
+certificate fingerprints in the cluster configuration and verifying that they
+match on connection.
-Login to your Proxmox via ssh or use the console:
+[[sysadmin_certs_api_gui]]
+Certificates for the API and SMTP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+{pmg} uses 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 these 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 web interface.
+
+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 simply upload that certificate over the web interface.
+
+[thumbnail="pmg-gui-certs-upload-custom.png"]
+
+Note that any certificate key files 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
+use an ACME provider like Let's Encrypt for easy setup of TLS certificates,
+which are accepted and trusted by modern operating systems and web browsers
+out of the box.
+
+Currently, the two ACME endpoints implemented are the
+https://letsencrypt.org[Let's Encrypt (LE)] production and staging
+environments. Our ACME client supports validation of `http-01` challenges using
+a built-in web server 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 serve as the 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 <account-name> <mail@example.com>
+----
+
+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 plugin's role 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 basic building block of automatic certificate management.
+
+The ACME protocol specifies different types of challenges, for example the
+`http-01`, where a web server provides a file with a specific token to prove
+that it controls a domain. Sometimes this isn't possible, either because of
+technical limitations or if the address of a record is not reachable from the
+public internet. The `dns-01` challenge can be used in such cases. This
+challenge is fulfilled by creating a certain DNS record in the domain's zone.
+
+[thumbnail="pmg-gui-acme-create-challenge-plugin.png"]
+
+{pmg} supports both of those challenge types out of the box, you can configure
+plugins either over the web interface under `Certificates -> ACME Challenges`,
+or using the `pmgconfig acme plugin add` command.
+
+ACME Plugin configurations are stored in `/etc/pmg/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 roughly 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 web server spawned on port 80.
+
+NOTE: The name `standalone` means that it can provide the validation on its
+own, without any third party service. So this plugin also works for cluster
+nodes.
+
+There are a few prerequisites to use this 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+{pmg} 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"]
+
+Here you can add a new challenge plugin by selecting your API provider and
+entering 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} automatically generates
+the form for the credentials, but not all providers are annotated yet. For those
+you will see a bigger text area, into which you simply need to copy all the
+credential's `KEY`=`VALUE` pairs.
+
+DNS Validation through CNAME Alias
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A special `alias` mode can be used to handle 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`.
+
+[[sysadmin_certs_acme_dns_wildcard]]
+Wildcard Certificates
+^^^^^^^^^^^^^^^^^^^^^
+
+Wildcard DNS names start with a `*.` prefix and are considered valid for all
+(one-level) subdomain names of the verified domain. So a certificate for
+`*.domain.example` is valid for `foo.domain.example` and
+`bar.domain.example`, but not for `baz.foo.domain.example`.
+
+Currently, you can only create wildcard certificates with the
+https://letsencrypt.org/docs/challenge-types/#dns-01-challenge[DNS challenge type].
+
+
+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
+renewed automatically by the `pmg-daily.service`. Currently, renewal is
+triggered if the certificate either has 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 certificate verification warnings, you have to
+generate a valid certificate for your server.
+
+Log in to your {pmg} via ssh or use the console:
----
openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem
----
-Follow the instructions on the screen, see this example:
+Follow the instructions on the screen, for example:
----
Country Name (2 letter code) [AU]: AT
An optional company name []: not necessary
----
-After you finished this certificate request you have to send the file
+After you have finished the certificate request, you have to send the file
`req.pem` to your Certification Authority (CA). The CA will issue the
-certificate (BASE64 encoded) based on your request – save this file as
-`cert.pem` to your Proxmox.
+certificate (BASE64 encoded), based on your request – save this file as
+`cert.pem` to your {pmg}.
-To activate the new certificate, do the following on your Proxmox:
+To activate the new certificate, do the following on your {pmg}:
----
cat key.pem cert.pem >/etc/pmg/pmg-api.pem
----
-The restart the API servers
+Then restart the API servers:
----
systemctl restart pmgproxy
----
-Test your new certificate by using your browser.
-
-NOTE: To transfer files from and to your Proxmox, 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 http://winscp.net/).
+Test your new certificate, using your browser.
+NOTE: To transfer files to and from your {pmg}, you can use secure copy: If your
+desktop runs Linux, you can use the `scp` command line tool. If your desktop PC
+runs windows, please use an 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.
projects / pmg-docs.git / blobdiff