tyler/proxmox-backup
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: add certificate-management.rst

Browse Source 
the file certificate-managment.rst is generated from the pmg-docs repo

by running:
```
asciidoc -b $(pwd)/asciidoc/pmg-docbook \
-f asciidoc/asciidoc-pmg.conf -o - pmg-ssl-certificate.adoc | \
pandoc -f docbook -t rst --shift-heading-level-by=1 \
-o certificate-mangement-auto.rst

sed -ri 's/__/_/' certificate-mangement-auto.rst
sed -ri 's/\{pmg\}/`Proxmox Backup`_/g' certificate-mangement-auto.rst
sed -ri 's/\{PMG\}/`Proxmox Backup`_/g' certificate-mangement-auto.rst
sed -ri 's/Proxmox Mail Gateway/`Proxmox Backup`_/g' \
certificate-mangement-auto.rst
sed -ri 's/pmg-([a-zA-Z0-9_-]*).png/pbs-\1.png/g' \
certificate-mangement-auto.rst
sed -ri 's/pmgproxy/proxmox-backup-proxy/g' \
certificate-mangement-auto.rst
sed -ri 's/pmgconfig/proxmox-backup-manager/g' \
certificate-mangement-auto.rst
sed -ri 's/pmg-daily/proxmox-backup-daily-update/g' \
certificate-mangement-auto.rst
sed -ri 's/\/etc\/pmg\/node.conf/\/etc\/proxmox-backup\/node.cfg/g' \
certificate-mangement-auto.rst
sed -ri 's/\/etc\/pmg\/acme/\/etc\/proxmox-backup\/acme/g' \
certificate-mangement-auto.rst
sed -ri \
's/\/etc\/pmg\/pmg-api.pem/\/etc\/proxmox-backup\/proxy.pem/g' \
certificate-mangement-auto.rst
sed -ri 's/screenshot/screenshots/g' certificate-mangement-auto.rst

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
This commit is contained in:
Stoiko Ivanov 2022-05-16 16:27:31 +00:00 committed by Thomas Lamprecht
parent c2add820a4
commit 6189b956b6
3 changed files with 362 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

359
docs/certificate-management.rst Normal file
View File

@ -0,0 +1,359 @@
.. _sysadmin_certificate_management:
Certificate Management
----------------------
Access to the web-based administration interface is always encrypted
through ``https``. Each `Proxmox Backup`_ host creates by default its
own (self-signed) certificate. This certificate is used for encrypted
communication with the host’s ``proxmox-backup-proxy`` service, for any API call
between a user and the web-interface or between nodes in a cluster.
Certificate verification in a `Proxmox Backup`_ cluster is done based
on pinning the certificate fingerprints in the cluster configuration and
verifying that they match on connection.
.. _sysadmin_certs_api_gui:
Certificates for the API and SMTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Proxmox Backup`_ uses two different certificates:
- ``/etc/proxmox-backup/proxy.pem``: the required certificate used for Proxmox
Mail Gateway API requests.
- ``/etc/pmg/pmg-tls.pem``: the optional certificate used for SMTP TLS
connections, see `mailproxy TLS
configuration <#proxmox-backup-manager_mailproxy_tls>`_
`??? <#proxmox-backup-manager_mailproxy_tls>`_ for details.
You have the following options for these certificates:
1. Keep using the default self-signed certificate in
``/etc/proxmox-backup/proxy.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 Proxmox Mail
Gateway API and web interface.
Certificates are managed through the `Proxmox Backup`_
web-interface/API or using the the ``proxmox-backup-manager`` CLI tool.
.. _sysadmin_certs_upload_custom:
Upload Custom Certificate
~~~~~~~~~~~~~~~~~~~~~~~~~
If you already have a certificate which you want to use for a Proxmox
Mail Gateway host, you can simply upload that certificate over the web
interface.
|pbs-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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Proxmox Backup`_ includes an implementation of the **A**\ utomatic
**C**\ ertificate **M**\ anagement **E**\ nvironment (**ACME**)
protocol, allowing `Proxmox Backup`_ 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 `Let’s Encrypt
(LE) <https://letsencrypt.org>`_ 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
`acme.sh <https://acme.sh>`_ does.
.. _sysadmin_certs_acme_account:
ACME Account
^^^^^^^^^^^^
|pbs-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 ``proxmox-backup-manager`` command
line tool.
::
proxmox-backup-manager acme account register <account-name> <mail@example.com>
.. tip::
Because of
`rate-limits <https://letsencrypt.org/docs/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 `Proxmox Backup`_ 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.
|pbs-gui-acme-create-challenge-plugin.png|
`Proxmox Backup`_ 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
``proxmox-backup-manager acme plugin add`` command.
ACME Plugin configurations are stored in ``/etc/proxmox-backup/acme/plugins.cfg``.
A plugin is available for all nodes in the cluster.
.. _domains:
Domains
^^^^^^^
You can add new or manage existing domain entries under
``Certificates``, or using the ``proxmox-backup-manager`` command.
|pbs-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
`automatically <#sysadmin_certs_acme_automatic_renewal>`_ `Automatic
renewal of ACME
certificates <#sysadmin_certs_acme_automatic_renewal>`_.
.. _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
`Proxmox Backup`_ 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
`Proxmox Backup`_ re-uses the DNS plugins developed for the
``acme.sh`` [1]_ 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``).
|pbs-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 `How to use DNS
API <https://github.com/acmesh-official/acme.sh/wiki/dnsapi#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, `Proxmox Backup`_
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:
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 `Proxmox Backup`_ node configuration file ``/etc/proxmox-backup/node.cfg``
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 `DNS
challenge
type <https://letsencrypt.org/docs/challenge-types/#dns-01-challenge>`_.
.. _combination_of_plugins:
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 proxmox-backup-manager or via the web-interface/API), the
certificate will be renewed automatically by the ``proxmox-backup-daily-update.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:
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 `Proxmox Backup`_ via ssh or use the console:
::
openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem
Follow the instructions on the screen, for example:
::
Country Name (2 letter code) [AU]: AT
State or Province Name (full name) [Some-State]:Vienna
Locality Name (eg, city) []:Vienna
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Proxmox GmbH
Organizational Unit Name (eg, section) []:`Proxmox Backup`_
Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com
Email Address []:support@yourdomain.com
Please enter the following 'extra' attributes to be sent with your certificate request
A challenge password []: not necessary
An optional company name []: not necessary
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 Backup`_.
To activate the new certificate, do the following on your Proxmox Mail
Gateway:
::
cat key.pem cert.pem >/etc/proxmox-backup/proxy.pem
Then restart the API servers:
::
systemctl restart proxmox-backup-proxy
Test your new certificate, using your browser.
.. note::
To transfer files to and from your `Proxmox Backup`_, 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:
Change Certificate for Cluster Setups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you change the API certificate of an active cluster node manually,
you also need to update the pinned fingerprint inside the cluster
configuration.
You can do that by executing the following command on the host where the
certificate changed:
::
pmgcm update-fingerprints
Note, this will be done automatically if using the integrated ACME (for
example, through Let’s Encrypt) feature.
.. [1]
acme.sh https://github.com/acmesh-official/acme.sh
.. |pbs-gui-certs-upload-custom.png| image:: images/screenshots/pbs-gui-certs-upload-custom.png
.. |pbs-gui-acme-create-account.png| image:: images/screenshots/pbs-gui-acme-create-account.png
.. |pbs-gui-acme-create-challenge-plugin.png| image:: images/screenshots/pbs-gui-acme-create-challenge-plugin.png
.. |pbs-gui-acme-add-domain.png| image:: images/screenshots/pbs-gui-acme-add-domain.png

1
docs/conf.py
View File

@ -108,6 +108,7 @@ today_fmt = '%A, %d %B %Y'
exclude_patterns = [
'_build', 'Thumbs.db', '.DS_Store',
'*/man1.rst',
'certificate-management.rst',
'config/*/man5.rst',
'epilog.rst',
'pbs-copyright.rst',

2
docs/sysadmin.rst
View File

@ -28,6 +28,8 @@ please refer to the standard Debian documentation.
.. include:: system-booting.rst
.. include:: certificate-management.rst
.. include:: services.rst
.. include:: command-line-tools.rst