Proxmox Backup Server - User contributions [en]

Upgrade from 3 to 4

2025-09-19T08:08:18Z

S.ivanov: /* Add the Proxmox Backup Server 4 Package Repository */

= Introduction =

Proxmox Backup Server 4 is based on Debian 13 Trixie, a new major release, and introduces several new major features and changes.
You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively.
Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process.
You can test the backup beforehand, for example, in a (virtualized) test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Trixie.

= In-place Upgrade =

== Prerequisites ==

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Backup Server 3.4, see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 3.4
** Verify version: The command <code>proxmox-backup-manager versions</code> should print:
**:<code>proxmox-backup-server 3.4.2-1 running version: 3.4.2</code> (or higher)
** If you do not get updates check correct [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories package repository] configuration.

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs3-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. Basic familiarity with APT is required to proceed with this upgrade mechanism.

=== Installed alongside Proxmox VE ===

For systems with Proxmox VE and Proxmox Backup Server installed together, you should also read the [https://pve.proxmox.com/wiki/Upgrade_from_8_to_9 Proxmox VE upgrade from 8 to 9 how-to] carefully.

You can upgrade both in one go, by syncing the steps in which the APT repositories are changed.

== Actions Step-by-Step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 3.x host is up-to-date.

=== Continuously use the pbs3to4 checklist script ===

A small checklist program named pbs3to4 is included in the latest Proxmox Backup Server 3.4 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pbs3to4

To run it with all checks enabled, execute:

pbs3to4 --full

Make sure to run the full checks at least once before the upgrade.

This script only checks and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed. You should keep in mind that Proxmox Backup Server can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== Optional: Enable Maintenance Mode ===

Enabling the read-only [https://pbs.proxmox.com/docs/maintenance.html#maintenance-mode maintenance mode] on all datastores ensures that no new backup can be started during the upgrade, while keeping existing ones available to read.
The read-only maintenance mode allows you to enforce a known and stable datastore state and reduces the I/O and general load of the Proxmox Backup Server during the upgrade, making that faster.

You can enable and disable the maintenance mode either via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):
# enable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --maintenance-mode read-only
# disable read-only mode
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Update the Configured APT Repositories ===

First, make sure that the system is using the latest Proxmox Backup Server 3.4 packages:

apt update
apt dist-upgrade
proxmox-backup-manager versions

The last command should report at least <code>3.4.2-1</code> or newer.

==== Update Debian Base Repositories to Trixie ====

Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. You can place a <code>#</code> symbol at the start of the respective line to comment such a repository out, disabling it.
Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pbs-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file.
See [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories] section in the reference docs for the correct Proxmox Backup Server 4 / Debian Trixie repositories.

==== Add the Proxmox Backup Server 4 Package Repository ====

Update the enterprise repository to Trixie in the new deb822 format with the following command:

cat > /etc/apt/sources.list.d/pbs-enterprise.sources << EOF
Types: deb
URIs: https://enterprise.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

After you added the new enterprise repository as above, check that <code>apt</code> picks it up correctly. You can do so by first running <code>apt update</code> followed by <code>apt policy</code>. Make sure that no errors are shown and that <code>apt policy</code> only outputs the desired repositories. Then you can remove the old <code>/etc/apt/sources.list.d/pbs-enterprise.list</code> file. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
If using the no-subscription repository, see [[Package Repositories]]. You should be able to add the Proxmox Backup Server 4 no-subscription repository with this command:
cat > /etc/apt/sources.list.d/proxmox.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

As with the enterprise repository, make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Backup Server 3 no-subscription repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pbs-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: no</code> to any stanza you want to disable.

Make sure to check that all the <code>.list</code> files you added in /etc/apt/sources.list.d/ got switched over to Trixie correctly.

After you checked that all repositories get picked up correctly with <code>apt policy</code>, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Upgrade the System ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example logging in as system user in the <code>pam</code> realm)|reminder}}

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you will be asked to approve changes to configuration files and some service restarts, where the default config has been updated by their respective package.

You may also be shown the output of <code>apt-listchanges</code>, you can simply exit there by pressing "q". If you get prompted for your default keyboard selection, simply use the arrow keys to navigate to the one applicable in your case and hit enter.

For questions about service restarts (like <code>Restart services during package upgrades without asking?</code>) use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.

For questions about (default) configuration changes, it's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Backup Server will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

=== Check Result & Reboot Into Updated Kernel ===

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

Please note that you should reboot even if you already used the 6.2 kernel previously, through the opt-in package on Proxmox Backup Server 3.

== Following the Proxmox Backup Server upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Check Status of Services ===

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

=== Optional: Disable Maintenance Mode Again ===

If you enabled the maintenance mode before the upgrade, don't forget to disable it again.
You can do it via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):

# disable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

= Potential Issues =

== General ==
As a Debian based distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, ensure that you read the [https://www.debian.org/releases/trixie/release-notes/issues.en.html upgrade specific issues for Debian Trixie].

Please also check the known issue list from the Proxmox Backup Server 4.0 changelog: https://pbs.proxmox.com/wiki/index.php/Roadmap#4.0-known-issues

== Older Hardware and New 6.14 Kernel ==

Compatibility of old hardware (released >= 10 years ago) is not as thoroughly tested as more recent hardware.
For old hardware we highly recommend testing compatibility of Proxmox Backup Server 4 with identical (or at least similar) hardware before upgrading any production machines.

We will expand this section with potential pitfalls and workarounds once they arise.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

In general, it's recommended to either have an independent remote connection to the Proxmox Backup Server's host console, for example, through IPMI or iKVM, or physical access for managing the server even when its own network doesn't come up after a major upgrade or network change.

The latest version of Proxmox Backup Server 3.4 and 4.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

<div id="sd-boot-warning"></div>
=== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ===
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting),
<code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages
and install systemd-boot as bootloader).
As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.
The package was automatically shipped for systems installed from the PBS 3.0 to PBS 3.4 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pbs3to4</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pbs3to4</code> will warn you accordingly.
The <code>pbs3to4</code> checklist script will change its output depending on the state of the upgrade, and should be [[Upgrade from 3 to 4#Continuously_use_the_pbs3to4_checklist_script|run continuously before and after the upgrade]].
It will print which packages should be removed or added at the appropriate time.
The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.
See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

[[Category: Upgrade]]

Upgrade from 3 to 4

2025-08-08T17:07:21Z

S.ivanov: sync sd-boot changes from pve wiki /* Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled */

= Introduction =

Proxmox Backup Server 4 is based on Debian 13 Trixie, a new major release, and introduces several new major features and changes.
You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively.
Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process.
You can test the backup beforehand, for example, in a (virtualized) test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Trixie.

= In-place Upgrade =

== Prerequisites ==

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Backup Server 3.4, see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 3.4
** Verify version: The command <code>proxmox-backup-manager versions</code> should print:
**:<code>proxmox-backup-server 3.4.2-1 running version: 3.4.2</code> (or higher)
** If you do not get updates check correct [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories package repository] configuration.

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs3-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. Basic familiarity with APT is required to proceed with this upgrade mechanism.

=== Installed alongside Proxmox VE ===

For systems with Proxmox VE and Proxmox Backup Server installed together, you should also read the [https://pve.proxmox.com/wiki/Upgrade_from_8_to_9 Proxmox VE upgrade from 8 to 9 how-to] carefully.

You can upgrade both in one go, by syncing the steps in which the APT repositories are changed.

== Actions Step-by-Step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 3.x host is up-to-date.

=== Continuously use the pbs3to4 checklist script ===

A small checklist program named pbs3to4 is included in the latest Proxmox Backup Server 3.4 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pbs3to4

To run it with all checks enabled, execute:

pbs3to4 --full

Make sure to run the full checks at least once before the upgrade.

This script only checks and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed. You should keep in mind that Proxmox Backup Server can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== Optional: Enable Maintenance Mode ===

Enabling the read-only [https://pbs.proxmox.com/docs/maintenance.html#maintenance-mode maintenance mode] on all datastores ensures that no new backup can be started during the upgrade, while keeping existing ones available to read.
The read-only maintenance mode allows you to enforce a known and stable datastore state and reduces the I/O and general load of the Proxmox Backup Server during the upgrade, making that faster.

You can enable and disable the maintenance mode either via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):
# enable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --maintenance-mode read-only
# disable read-only mode
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Update the Configured APT Repositories ===

First, make sure that the system is using the latest Proxmox Backup Server 3.4 packages:

apt update
apt dist-upgrade
proxmox-backup-manager versions

The last command should report at least <code>3.4.2-1</code> or newer.

==== Update Debian Base Repositories to Trixie ====

Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. You can place a <code>#</code> symbol at the start of the respective line to comment such a repository out, disabling it.
Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pbs-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file.
See [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories] section in the reference docs for the correct Proxmox Backup Server 4 / Debian Trixie repositories.

==== Add the Proxmox Backup Server 4 Package Repository ====

Update the enterprise repository to Trixie in the new deb822 format with the following command:

cat > /etc/apt/sources.list.d/pbs-enterprise.sources << EOF
Types: deb
URIs: https://enterprise.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

After you added the new enterprise repository as above, check that <code>apt</code> picks it up correctly. You can do so by first running <code>apt update</code> followed by <code>apt policy</code>. Make sure that no errors are shown and that <code>apt policy</code> only outputs the desired repositories. Then you can remove the old <code>/etc/apt/sources.list.d/pbs-enterprise.list</code> file. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
If using the no-subscription repository, see [[Package Repositories]]. You should be able to add the Proxmox Backup Server 4 no-subscription repository with this command:
cat > /etc/apt/sources.list.d/proxmox.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

As with the enterprise repository, make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Backup Server 8 no-subscription repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pbs-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

Make sure that <code>apt</code> picks it up correctly with <code>apt policy</code>. Then remove the previous Proxmox Backup Server 3 repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pbs-install-repo.list</code> or any other <code>.list</code> file you may have added it to. You can use apt policy again to make sure the old repository is not being used anymore.

Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.

Make sure to check that all the <code>.list</code> files you added in /etc/apt/sources.list.d/ got switched over to Trixie correctly.

After you checked that all repositories get picked up correctly with <code>apt policy</code>, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Upgrade the System ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example logging in as system user in the <code>pam</code> realm)|reminder}}

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you will be asked to approve changes to configuration files and some service restarts, where the default config has been updated by their respective package.

You may also be shown the output of <code>apt-listchanges</code>, you can simply exit there by pressing "q". If you get prompted for your default keyboard selection, simply use the arrow keys to navigate to the one applicable in your case and hit enter.

For questions about service restarts (like <code>Restart services during package upgrades without asking?</code>) use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.

For questions about (default) configuration changes, it's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Backup Server will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

=== Check Result & Reboot Into Updated Kernel ===

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

Please note that you should reboot even if you already used the 6.2 kernel previously, through the opt-in package on Proxmox Backup Server 3.

== Following the Proxmox Backup Server upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Check Status of Services ===

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

=== Optional: Disable Maintenance Mode Again ===

If you enabled the maintenance mode before the upgrade, don't forget to disable it again.
You can do it via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):

# disable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

= Potential Issues =

== General ==
As a Debian based distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, ensure that you read the [https://www.debian.org/releases/trixie/release-notes/issues.en.html upgrade specific issues for Debian Trixie].

Please also check the known issue list from the Proxmox Backup Server 4.0 changelog: https://pbs.proxmox.com/wiki/index.php/Roadmap#4.0-known-issues

== Older Hardware and New 6.14 Kernel ==

Compatibility of old hardware (released >= 10 years ago) is not as thoroughly tested as more recent hardware.
For old hardware we highly recommend testing compatibility of Proxmox Backup Server 4 with identical (or at least similar) hardware before upgrading any production machines.

We will expand this section with potential pitfalls and workarounds once they arise.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

In general, it's recommended to either have an independent remote connection to the Proxmox Backup Server's host console, for example, through IPMI or iKVM, or physical access for managing the server even when its own network doesn't come up after a major upgrade or network change.

The latest version of Proxmox Backup Server 3.4 and 4.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

<div id="sd-boot-warning"></div>
=== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ===
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting),
<code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages
and install systemd-boot as bootloader).
As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.
The package was automatically shipped for systems installed from the PBS 3.0 to PBS 3.4 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pbs3to4</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pbs8to9</code> will warn you accordingly.
The <code>pbs3to4</code> checklist script will change its output depending on the state of the upgrade, and should be [[Upgrade from 3 to 4#Continuously_use_the_pbs3to4_checklist_script|run continuously before and after the upgrade]].
It will print which packages should be removed or added at the appropriate time.
The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.
See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

[[Category: Upgrade]]

Upgrade from 3 to 4

2025-08-06T17:57:20Z

S.ivanov: /* Update the Configured APT Repositories */

= Introduction =

Proxmox Backup Server 4 is based on Debian 13 Trixie, a new major release, and introduces several new major features and changes.
You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively.
Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process.
You can test the backup beforehand, for example, in a (virtualized) test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Trixie.

= In-place Upgrade =

== Prerequisites ==

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Backup Server 3.4, see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 3.4
** Verify version: The command <code>proxmox-backup-manager versions</code> should print:
**:<code>proxmox-backup-server 3.4.2-1 running version: 3.4.2</code> (or higher)
** If you do not get updates check correct [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories package repository] configuration.

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs3-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. Basic familiarity with APT is required to proceed with this upgrade mechanism.

=== Installed alongside Proxmox VE ===

For systems with Proxmox VE and Proxmox Backup Server installed together, you should also read the [https://pve.proxmox.com/wiki/Upgrade_from_8_to_9 Proxmox VE upgrade from 8 to 9 how-to] carefully.

You can upgrade both in one go, by syncing the steps in which the APT repositories are changed.

== Actions Step-by-Step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 3.x host is up-to-date.

=== Continuously use the pbs3to4 checklist script ===

A small checklist program named pbs3to4 is included in the latest Proxmox Backup Server 3.4 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pbs3to4

To run it with all checks enabled, execute:

pbs3to4 --full

Make sure to run the full checks at least once before the upgrade.

This script only checks and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed. You should keep in mind that Proxmox Backup Server can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== Optional: Enable Maintenance Mode ===

Enabling the read-only [https://pbs.proxmox.com/docs/maintenance.html#maintenance-mode maintenance mode] on all datastores ensures that no new backup can be started during the upgrade, while keeping existing ones available to read.
The read-only maintenance mode allows you to enforce a known and stable datastore state and reduces the I/O and general load of the Proxmox Backup Server during the upgrade, making that faster.

You can enable and disable the maintenance mode either via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):
# enable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --maintenance-mode read-only
# disable read-only mode
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Update the Configured APT Repositories ===

First, make sure that the system is using the latest Proxmox Backup Server 3.4 packages:

apt update
apt dist-upgrade
proxmox-backup-manager versions

The last command should report at least <code>3.4.2-1</code> or newer.

==== Update Debian Base Repositories to Trixie ====

Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. You can place a <code>#</code> symbol at the start of the respective line to comment such a repository out, disabling it.
Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pbs-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file.
See [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories] section in the reference docs for the correct Proxmox Backup Server 4 / Debian Trixie repositories.

==== Add the Proxmox Backup Server 4 Package Repository ====

Update the enterprise repository to Trixie in the new deb822 format with the following command:

cat > /etc/apt/sources.list.d/pbs-enterprise.sources << EOF
Types: deb
URIs: https://enterprise.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

After you added the new enterprise repository as above, check that <code>apt</code> picks it up correctly. You can do so by first running <code>apt update</code> followed by <code>apt policy</code>. Make sure that no errors are shown and that <code>apt policy</code> only outputs the desired repositories. Then you can remove the old <code>/etc/apt/sources.list.d/pbs-enterprise.list</code> file. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
If using the no-subscription repository, see [[Package Repositories]]. You should be able to add the Proxmox Backup Server 4 no-subscription repository with this command:
cat > /etc/apt/sources.list.d/proxmox.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

As with the enterprise repository, make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Backup Server 8 no-subscription repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pbs-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

Make sure that <code>apt</code> picks it up correctly with <code>apt policy</code>. Then remove the previous Proxmox Backup Server 3 repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pbs-install-repo.list</code> or any other <code>.list</code> file you may have added it to. You can use apt policy again to make sure the old repository is not being used anymore.

Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.

Make sure to check that all the <code>.list</code> files you added in /etc/apt/sources.list.d/ got switched over to Trixie correctly.

After you checked that all repositories get picked up correctly with <code>apt policy</code>, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Upgrade the System ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example logging in as system user in the <code>pam</code> realm)|reminder}}

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you will be asked to approve changes to configuration files and some service restarts, where the default config has been updated by their respective package.

You may also be shown the output of <code>apt-listchanges</code>, you can simply exit there by pressing "q". If you get prompted for your default keyboard selection, simply use the arrow keys to navigate to the one applicable in your case and hit enter.

For questions about service restarts (like <code>Restart services during package upgrades without asking?</code>) use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.

For questions about (default) configuration changes, it's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Backup Server will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

=== Check Result & Reboot Into Updated Kernel ===

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

Please note that you should reboot even if you already used the 6.2 kernel previously, through the opt-in package on Proxmox Backup Server 3.

== Following the Proxmox Backup Server upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Check Status of Services ===

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

=== Optional: Disable Maintenance Mode Again ===

If you enabled the maintenance mode before the upgrade, don't forget to disable it again.
You can do it via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):

# disable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

= Potential Issues =

== General ==
As a Debian based distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, ensure that you read the [https://www.debian.org/releases/trixie/release-notes/issues.en.html upgrade specific issues for Debian Trixie].

Please also check the known issue list from the Proxmox Backup Server 4.0 changelog: https://pbs.proxmox.com/wiki/index.php/Roadmap#4.0-known-issues

== Older Hardware and New 6.14 Kernel ==

Compatibility of old hardware (released >= 10 years ago) is not as thoroughly tested as more recent hardware.
For old hardware we highly recommend testing compatibility of Proxmox Backup Server 4 with identical (or at least similar) hardware before upgrading any production machines.

We will expand this section with potential pitfalls and workarounds once they arise.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

In general, it's recommended to either have an independent remote connection to the Proxmox Backup Server's host console, for example, through IPMI or iKVM, or physical access for managing the server even when its own network doesn't come up after a major upgrade or network change.

The latest version of Proxmox Backup Server 3.4 and 4.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

=== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ===

With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting),
<code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages
and install systemd-boot as bootloader).

As Proxmox Systems usually handle the installation of <code>systemd-boot</code> as bootloader using <code>proxmox-boot-tool</code> the meta-package should be removed.
The package was automatically shipped for systems installed from the Proxmox Backup Server 3.1 to Proxmox Backup Server 3.4 ISOs, as it contained <code>bootctl</code> in bookworm.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 bug for systemd-boot]

[[Category: Upgrade]]

Upgrade from 3 to 4

2025-08-06T14:19:09Z

S.ivanov:

= Introduction =

Proxmox Backup Server 4 is based on Debian 13 Trixie, a new major release, and introduces several new major features and changes.
You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively.
Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process.
You can test the backup beforehand, for example, in a (virtualized) test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Trixie.

= In-place Upgrade =

== Prerequisites ==

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Backup Server 3.4, see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 3.4
** Verify version: The command <code>proxmox-backup-manager versions</code> should print:
**:<code>proxmox-backup-server 3.4.2-1 running version: 3.4.2</code> (or higher)
** If you do not get updates check correct [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories package repository] configuration.

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs3-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. Basic familiarity with APT is required to proceed with this upgrade mechanism.

=== Installed alongside Proxmox VE ===

For systems with Proxmox VE and Proxmox Backup Server installed together, you should also read the [https://pve.proxmox.com/wiki/Upgrade_from_8_to_9 Proxmox VE upgrade from 8 to 9 how-to] carefully.

You can upgrade both in one go, by syncing the steps in which the APT repositories are changed.

== Actions Step-by-Step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 3.x host is up-to-date.

=== Continuously use the pbs3to4 checklist script ===

A small checklist program named pbs3to4 is included in the latest Proxmox Backup Server 3.4 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pbs3to4

To run it with all checks enabled, execute:

pbs3to4 --full

Make sure to run the full checks at least once before the upgrade.

This script only checks and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed. You should keep in mind that Proxmox Backup Server can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== Optional: Enable Maintenance Mode ===

Enabling the read-only [https://pbs.proxmox.com/docs/maintenance.html#maintenance-mode maintenance mode] on all datastores ensures that no new backup can be started during the upgrade, while keeping existing ones available to read.
The read-only maintenance mode allows you to enforce a known and stable datastore state and reduces the I/O and general load of the Proxmox Backup Server during the upgrade, making that faster.

You can enable and disable the maintenance mode either via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):
# enable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --maintenance-mode read-only
# disable read-only mode
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Update the Configured APT Repositories ===

First, make sure that the system is using the latest Proxmox Backup Server 3.4 packages:

apt update
apt dist-upgrade
proxmox-backup-manager versions

The last command should report at least <code>3.4.2-1</code> or newer.

==== Update Debian Base Repositories to Trixie ====

Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. You can place a <code>#</code> symbol at the start of the respective line to comment such a repository out, disabling it.
Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pbs-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file.
See [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories] section in the reference docs for the correct Proxmox Backup Server 4 / Debian Trixie repositories.

==== Add the Proxmox Backup Server 4 Package Repository ====

Update the enterprise repository to Trixie in the new deb822 format with the following command:

cat > /etc/apt/sources.list.d/pbs-enterprise.sources << EOF
Types: deb
URIs: https://enterprise.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

After you added the new enterprise repository as above, check that <code>apt</code> picks it up correctly. You can do so by first running <code>apt update</code> followed by <code>apt policy</code>. Make sure that no errors are shown and that <code>apt policy</code> only outputs the desired repositories. Then you can remove the old <code>/etc/apt/sources.list.d/pve-enterprise.list</code> file. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
If using the no-subscription repository, see [[Package Repositories]]. You should be able to add the Proxmox Backup Server 4 no-subscription repository with this command:
cat > /etc/apt/sources.list.d/proxmox.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

As with the enterprise repository, make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Backup Server 8 no-subscription repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pve-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

Make sure that <code>apt</code> picks it up correctly with <code>apt policy</code>. Then remove the previous Proxmox Backup Server 3 repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pbs-install-repo.list</code> or any other <code>.list</code> file you may have added it to. You can use apt policy again to make sure the old repository is not being used anymore.

Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.

Make sure to check that all the <code>.list</code> files you added in /etc/apt/sources.list.d/ got switched over to Trixie correctly.

After you checked that all repositories get picked up correctly with <code>apt policy</code>, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Upgrade the System ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example logging in as system user in the <code>pam</code> realm)|reminder}}

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you will be asked to approve changes to configuration files and some service restarts, where the default config has been updated by their respective package.

You may also be shown the output of <code>apt-listchanges</code>, you can simply exit there by pressing "q". If you get prompted for your default keyboard selection, simply use the arrow keys to navigate to the one applicable in your case and hit enter.

For questions about service restarts (like <code>Restart services during package upgrades without asking?</code>) use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.

For questions about (default) configuration changes, it's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Backup Server will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

=== Check Result & Reboot Into Updated Kernel ===

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

Please note that you should reboot even if you already used the 6.2 kernel previously, through the opt-in package on Proxmox Backup Server 3.

== Following the Proxmox Backup Server upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Check Status of Services ===

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

=== Optional: Disable Maintenance Mode Again ===

If you enabled the maintenance mode before the upgrade, don't forget to disable it again.
You can do it via the web UI, in the Options tab of each datastore menu entry, or using the command line interface (CLI):

# disable read-only mode (replace DATASTORE-ID with actual value)
proxmox-backup-manager datastore update DATASTORE-ID --delete maintenance-mode

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

= Potential Issues =

== General ==
As a Debian based distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, ensure that you read the [https://www.debian.org/releases/trixie/release-notes/issues.en.html upgrade specific issues for Debian Trixie].

Please also check the known issue list from the Proxmox Backup Server 4.0 changelog: https://pbs.proxmox.com/wiki/index.php/Roadmap#4.0-known-issues

== Older Hardware and New 6.14 Kernel ==

Compatibility of old hardware (released >= 10 years ago) is not as thoroughly tested as more recent hardware.
For old hardware we highly recommend testing compatibility of Proxmox Backup Server 4 with identical (or at least similar) hardware before upgrading any production machines.

We will expand this section with potential pitfalls and workarounds once they arise.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

In general, it's recommended to either have an independent remote connection to the Proxmox Backup Server's host console, for example, through IPMI or iKVM, or physical access for managing the server even when its own network doesn't come up after a major upgrade or network change.

The latest version of Proxmox Backup Server 3.4 and 4.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

=== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ===

With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting),
<code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages
and install systemd-boot as bootloader).

As Proxmox Systems usually handle the installation of <code>systemd-boot</code> as bootloader using <code>proxmox-boot-tool</code> the meta-package should be removed.
The package was automatically shipped for systems installed from the Proxmox Backup Server 3.1 to Proxmox Backup Server 3.4 ISOs, as it contained <code>bootctl</code> in bookworm.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 bug for systemd-boot]

[[Category: Upgrade]]

Fail2ban

2024-05-27T16:19:02Z

S.ivanov: Add initial page - adaptations contributed by Lukas Fülling

Here we describe in short how you can set up <code>fail2ban</code> for the Proxmox Backup Server API to block IP addresses (temporarily) if there were too many wrong login attempts submitted through them.
The page is based upon the [https://pve.proxmox.com/wiki/Fail2ban HOWTO for Proxmox VE]

== Install fail2ban ==

Execute the following commands as root in a shell on the Proxmox Backup Server host, for example connected through SSH or via the web console in the Proxmox Backup Server web interface.

apt update
apt install fail2ban

== Setup Base Config ==

We recommend to use the <code>/etc/fail2ban/jail.local</code> file, as settings in this file take precedence over identical settings of <code>jail.conf</code>.

Use <code>jail.conf</code> as a template:

cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

And adapt the settings to your needs in the copied over <code>jail.local</code>.

The main reason for using this separate file is that the original <code>jail.conf</code> could be overwritten by fail2ban package updates, while the copied <code>jail.local</code> will not, so you can better manage updates that way.

== Setup Jail ==

=== Base Config ===
Add the following to the end of the copied over file <code>/etc/fail2ban/jail.local</code>:

<pre>
[proxmox-backup-server]
enabled = true
port = https,http,8007
filter = proxmox-backup-server
logpath = /var/log/proxmox-backup/api/auth.log
maxretry = 3
findtime = 2d
bantime = 1h
</pre>

Tip: Time properties like <code>bantime</code> and <code>findtime</code> also allow combinations like <code>2m 30s</code>. You can test if a value is valid and what the actually resulting ban seconds are using the <code>fail2ban-client --str2sec '1d 12h'</code> command.
See the <code>jail.conf</code> manual page<ref><code>jail.conf</code> manual page https://manpages.debian.org/stable/fail2ban/jail.conf.5.en.html</ref> for description of all options.

=== Filter Config ===
Create the file <code>/etc/fail2ban/filter.d/proxmox-backup-server.conf</code> with the following content:

<pre>
[Definition]
failregex = authentication failure; rhost=\[<HOST>\]:\d+ user=.* msg=.*
ignoreregex =

</pre>

=== Restart Service to Enable Config ===
Use:
systemctl restart fail2ban
to activate the config addition and arm fail2ban for the Proxmox Backup Server API.

== Test fail2ban Config ==
You can test your configuration by trying to log in through the web interface with a wrong password or a wrong user, and then issue the command:

<pre>
fail2ban-regex /var/log/proxmox-backup/api/auth.log /etc/fail2ban/filter.d/proxmox-backup-server.conf
</pre>

You should have *at least* a "Failregex: 1 total" at the top of the "Results" section (and "1 matched" at the bottom)

Note, if you tried too often and got yourself banned (your IP is reported by <code>fail2ban-client get proxmox-backup-server banned</code>) you can use <code>fail2ban-client unban <IP></code> (replace <code><IP></code> with the IP address) to manually unblock yourself.

== Links ==
* [http://www.fail2ban.org/wiki/index.php/Main_Page Fail2Ban ]

[[Category: HOW-TO]]

Upgrade from 1.1 to 2.x

2021-07-13T09:53:56Z

S.ivanov: /* Upgrade the system */

= Introduction =
Proxmox Backup Server 2.x is based on a new major version of Debian. You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively. Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process. Test the backup beforehand in a test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Bullseye.

= In-place Upgrade =

== Preconditions ==

Perform these actions via console or SSH. If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.

Do not carry out the upgrade via the web-interface (GUI) console, as this will get interrupted during the upgrade.

* Upgrade to the latest version of Proxmox Backup Server 1.1:
apt update
apt dist-upgrade
# verify version:
proxmox-backup-manager versions
proxmox-backup-server 1.1.11-1 running version: 1.1.11 (or higher)

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs1-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 4 GiB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. '''Familiarity with APT is required to proceed with this upgrade mechanism. '''

== Actions step-by-step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 1.x host is up-to-date. If you use a Linux bridge setup on your server, please also refer to the [https://pve.proxmox.com/wiki/Upgrade_from_6.x_to_7.0#Check_Linux_Network_Bridge_MAC Proxmox VE Upgrade Guide's] section regarding possible issues.

=== Update the configured APT repositories ===

Change the apt sources to Bullseye - see [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories].
Update all Debian repository entries to Bullseye.

sed -i 's/buster\/updates/bullseye-security/g;s/buster/bullseye/g' /etc/apt/sources.list

Note that for bullseye, Debian changed its security update repository from <code>deb http://security.debian.org buster/updates main</code> to <code>deb http://security.debian.org bullseye-security main</code> for more consistency.
The above command accounts for this change already.

Update the enterprise repository to bullseye:

echo "deb https://enterprise.proxmox.com/debian/pbs bullseye pbs-enterprise" > /etc/apt/sources.list.d/pbs-enterprise.list

If you have other PBS repositories configured, you can run the below command to update them:
sed -i 's/buster/bullseye/g' /etc/apt/sources.list.d/pbs-repo.list

Make sure to also edit all the extra files you added in /etc/apt/sources.list.d/ to Bullseye accordingly.

Finally, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Stop services before upgrade ===

This is only necessary if you use tape backup, as the lock file's path has been changed. Alternatively, you can also ensure that no tape-related backup or restore jobs are running during the upgrade.

Note that stopping the services will abort all running tasks (backup, restore, garbage-collect, etc.), so make sure none is active.

systemctl stop proxmox-backup-proxy.service proxmox-backup.service

=== Upgrade the system ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth. A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in 5 minutes. While the packages are being upgraded certain operations and requests to the API might fail (for example logging in as system user in the <code>pam</code> realm)

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you may be asked to approve some new packages, that want to replace certain configuration files. These are not relevant to the Proxmox Backup Server upgrade, so you can choose what's most appropriate for your setup.

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

== Following the Proxmox Backup Server upgrade ==

Start services again, if you stopped them for the upgrade:

systemctl start proxmox-backup-proxy.service proxmox-backup.service

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

= Potential issues =

== General ==

As a Debian based Distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, make sure to read the [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html Upgrade specific issues for bullseye]

Upgrade from 1.1 to 2.x

2021-07-13T09:53:35Z

S.ivanov: /* Upgrade the system */

= Introduction =
Proxmox Backup Server 2.x is based on a new major version of Debian. You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively. Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process. Test the backup beforehand in a test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Bullseye.

= In-place Upgrade =

== Preconditions ==

Perform these actions via console or SSH. If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.

Do not carry out the upgrade via the web-interface (GUI) console, as this will get interrupted during the upgrade.

* Upgrade to the latest version of Proxmox Backup Server 1.1:
apt update
apt dist-upgrade
# verify version:
proxmox-backup-manager versions
proxmox-backup-server 1.1.11-1 running version: 1.1.11 (or higher)

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs1-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 4 GiB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. '''Familiarity with APT is required to proceed with this upgrade mechanism. '''

== Actions step-by-step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 1.x host is up-to-date. If you use a Linux bridge setup on your server, please also refer to the [https://pve.proxmox.com/wiki/Upgrade_from_6.x_to_7.0#Check_Linux_Network_Bridge_MAC Proxmox VE Upgrade Guide's] section regarding possible issues.

=== Update the configured APT repositories ===

Change the apt sources to Bullseye - see [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories].
Update all Debian repository entries to Bullseye.

sed -i 's/buster\/updates/bullseye-security/g;s/buster/bullseye/g' /etc/apt/sources.list

Note that for bullseye, Debian changed its security update repository from <code>deb http://security.debian.org buster/updates main</code> to <code>deb http://security.debian.org bullseye-security main</code> for more consistency.
The above command accounts for this change already.

Update the enterprise repository to bullseye:

echo "deb https://enterprise.proxmox.com/debian/pbs bullseye pbs-enterprise" > /etc/apt/sources.list.d/pbs-enterprise.list

If you have other PBS repositories configured, you can run the below command to update them:
sed -i 's/buster/bullseye/g' /etc/apt/sources.list.d/pbs-repo.list

Make sure to also edit all the extra files you added in /etc/apt/sources.list.d/ to Bullseye accordingly.

Finally, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Stop services before upgrade ===

This is only necessary if you use tape backup, as the lock file's path has been changed. Alternatively, you can also ensure that no tape-related backup or restore jobs are running during the upgrade.

Note that stopping the services will abort all running tasks (backup, restore, garbage-collect, etc.), so make sure none is active.

systemctl stop proxmox-backup-proxy.service proxmox-backup.service

=== Upgrade the system ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth. A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in 5 minutes. While the packages are being upgraded certain operations and requests to the API might fail (e.g. logging in as system user in the <code>pam</code> realm)

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you may be asked to approve some new packages, that want to replace certain configuration files. These are not relevant to the Proxmox Backup Server upgrade, so you can choose what's most appropriate for your setup.

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

== Following the Proxmox Backup Server upgrade ==

Start services again, if you stopped them for the upgrade:

systemctl start proxmox-backup-proxy.service proxmox-backup.service

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

= Potential issues =

== General ==

As a Debian based Distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, make sure to read the [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html Upgrade specific issues for bullseye]

Upgrade from 1.1 to 2.x

2021-07-13T09:52:22Z

S.ivanov: /* Stop services before upgrade */

= Introduction =
Proxmox Backup Server 2.x is based on a new major version of Debian. You should plan the upgrade carefully, '''make and verify backups''' before beginning, and test extensively. Depending on the existing configuration, several manual steps — including some downtime — may be required.

'''Note:''' A valid and tested backup is ''always'' required before starting the upgrade process. Test the backup beforehand in a test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Bullseye.

= In-place Upgrade =

== Preconditions ==

Perform these actions via console or SSH. If you use SSH, you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.

Do not carry out the upgrade via the web-interface (GUI) console, as this will get interrupted during the upgrade.

* Upgrade to the latest version of Proxmox Backup Server 1.1:
apt update
apt dist-upgrade
# verify version:
proxmox-backup-manager versions
proxmox-backup-server 1.1.11-1 running version: 1.1.11 (or higher)

* Make a backup of <code>/etc/proxmox-backup</code> to ensure that in the worst case, any relevant configuration can be recovered:
tar czf "pbs1-etc-backup-$(date -I).tar.gz" -C "/etc" "proxmox-backup"

* Ensure that you have at least 4 GiB free disk space on the root mount point:
df -h /

In-place upgrades are carried out via APT. '''Familiarity with APT is required to proceed with this upgrade mechanism. '''

== Actions step-by-step ==
Before starting the upgrade process, ensure that your Proxmox Backup Server 1.x host is up-to-date. If you use a Linux bridge setup on your server, please also refer to the [https://pve.proxmox.com/wiki/Upgrade_from_6.x_to_7.0#Check_Linux_Network_Bridge_MAC Proxmox VE Upgrade Guide's] section regarding possible issues.

=== Update the configured APT repositories ===

Change the apt sources to Bullseye - see [https://pbs.proxmox.com/docs/installation.html#debian-package-repositories Package Repositories].
Update all Debian repository entries to Bullseye.

sed -i 's/buster\/updates/bullseye-security/g;s/buster/bullseye/g' /etc/apt/sources.list

Note that for bullseye, Debian changed its security update repository from <code>deb http://security.debian.org buster/updates main</code> to <code>deb http://security.debian.org bullseye-security main</code> for more consistency.
The above command accounts for this change already.

Update the enterprise repository to bullseye:

echo "deb https://enterprise.proxmox.com/debian/pbs bullseye pbs-enterprise" > /etc/apt/sources.list.d/pbs-enterprise.list

If you have other PBS repositories configured, you can run the below command to update them:
sed -i 's/buster/bullseye/g' /etc/apt/sources.list.d/pbs-repo.list

Make sure to also edit all the extra files you added in /etc/apt/sources.list.d/ to Bullseye accordingly.

Finally, update the repositories' package index:
apt update
Note that this command does not start the upgrade itself, it only refreshes the package index and must not return any error.

=== Stop services before upgrade ===

This is only necessary if you use tape backup, as the lock file's path has been changed. Alternatively, you can also ensure that no tape-related backup or restore jobs are running during the upgrade.

Note that stopping the services will abort all running tasks (backup, restore, garbage-collect, etc.), so make sure none is active.

systemctl stop proxmox-backup-proxy.service proxmox-backup.service

=== Upgrade the system ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth. A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the dist-upgrade can be finished in 5 minutes.

To get the initial set of upgraded packages, run:
apt update
apt dist-upgrade

During the above step, you may be asked to approve some new packages, that want to replace certain configuration files. These are not relevant to the Proxmox Backup Server upgrade, so you can choose what's most appropriate for your setup.

If the command exits successfully, you can reboot the system in order to enable the new kernel.
systemctl reboot

== Following the Proxmox Backup Server upgrade ==

Start services again, if you stopped them for the upgrade:

systemctl start proxmox-backup-proxy.service proxmox-backup.service

Check that the statuses of the main services are <code>active (running)</code>

systemctl status proxmox-backup-proxy.service proxmox-backup.service

= Potential issues =

== General ==

As a Debian based Distribution, Proxmox Backup Server is affected by most issues and changes affecting Debian.
Thus, make sure to read the [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html Upgrade specific issues for bullseye]

HTTPS Certificate Configuration

2021-02-11T10:03:41Z

S.ivanov: add section about parallel installations

== Introduction ==

This is a how-to for changing the web server certificate used by Proxmox Backup Server, in order to enable the usage of publicly trusted certificates issued by a CA of your choice (like Let's Encrypt or a commercial CA).

== Important Note ==

Creating a new certificate requires changes the fingerprint a client will see when connecting to the server.
You need to update it for all clients, else they will refuse connecting to the server!

With a trusted certificate clients do not require a fingerprint to verify the server, if your certificate is trusted you should drop the fingerprint from all client configurations to avoid updating it.

== Certificate and Key File ==

The certificate and key, which are used for the TLS encryption by <code>proxmox-backup-proxy</code> are:
* <code>/etc/proxmox-backup/proxy.pem</code> (certificate)
: The pem file contains the certificate, potentially including one or more intermediate certificates
* <code>/etc/proxmox-backup/proxy.key</code> (key)
: The key file contains the private key used for the certificate.

=== File Owner and Permissions ===

Both files need to be owned by the <code>root</code> user and the <code>backup</code> group and should not be readable by others (mode <code>o640</code>):

chown root:backup /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key
chmod 640 /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key

=== Activating Certificate Change ===

Once the certificate and key files are changed you need to reload (avoid restart, they interrupt running (backup) jobs) the proxy daemon:
systemctl reload proxmox-backup-proxy

== Revert to Default Configuration ==

You can always recreate a fresh self-signed certificate and start fresh by running:
proxmox-backup-manager cert update --force
systemctl reload proxmox-backup-proxy

'''WARNING''': Creating a new certificate requires you to update the fingerprint for all clients, else they will refuse connecting to the server!

== Let's Encrypt using acme.sh ==

Until Proxmox Backup Server handles issuing certificates from Let's Encrypt itself you can configure getting and refreshing certificates with external tools.

This how-to shows how to get a publicly trusted certificate from Let's Encrypt using [https://github.com/acmesh-official/acme.sh acme.sh]

The how-to only provides minimal instructions - read up on other options, which might be more fitting in your environment, for example, using the DNS challenge.

=== Download and Installation ===

You can obtain acme.sh directly from GitHub and install it to <code>root</code> account:

git clone https://github.com/acmesh-official/acme.sh.git
cd acme.sh && ./acme.sh --install --accountemail <your-email>

=== Issuing and Configuration ===

To write the files to the appropriate location, with fitting owner and mode for <code>domain.example</code>

acme.sh --issue -d domain.example --standalone \
--cert-file /etc/proxmox-backup/proxy.pem \
--key-file /etc/proxmox-backup/proxy.key \
--fullchain-file /etc/proxmox-backup/proxy.pem \
--reloadcmd "chown root:backup /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key; chmod 640 /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key ; systemctl reload proxmox-backup-proxy"

'''TIP''': With a trusted certificate clients do not require a fingerprint to verify the server. You can drop the fingerprint from all client configurations to avoid the need to update it every two-three months, after a new Let's Encrypt certificate is required.

=== Automatic Renewal ===

In order to automatically refresh the certificates and to reload the proxy service you also need to append the reload command as <code>renew-hook</code> in the generated cronjob (by running <code>crontab -e</code>)
and editing so that the line looks like:

20 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" --renew-hook "chown root:backup /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key; chmod 640 /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key ; systemctl reload proxmox-backup-proxy" > /dev/null

== Using Certificates from Proxmox VE ==

If you have installed Proxmox Backup Server in parallel a system which also runs Proxmox VE, you can use the certificates you created with Proxmox VE's ACME integration also for the Proxmox Backup Server proxy.

You only need to schedule the copying of the certificate and key after each renewal (e.g. by creating an appropriate cronjob or systemd-timer)

The necessary commands for copying are:
NODE=$(hostname)
cp /etc/pve/nodes/${NODE}/pveproxy-ssl.pem /etc/proxmox-backup/proxy.pem
cp /etc/pve/nodes/${NODE}/pveproxy-ssl.key /etc/proxmox-backup/proxy.key
chmod 640 /etc/proxmox-backup/proxy.key /etc/proxmox-backup/proxy.pem
chgrp backup /etc/proxmox-backup/proxy.key /etc/proxmox-backup/proxy.pem
systemctl restart proxmox-backup-proxy.service

[[Category:HOW-TO]]