Skip to content

Upgrading to 1.5

Read this before updating to 1.5

This page lists what changes for existing installations with 1.5. The update dialog lists all behaviour changes before you install, and the release notes on GitHub describe the whole release. Coming from 1.4.0, the behaviour changes of 1.4.1 apply as well (see the release notes); coming from 1.3.x or older, read Upgrading to 1.4 too.

The first start of 1.5 encrypts the database on more kinds of install, and several changes refuse something that worked before, on purpose. Take a backup before you update, and read Going back to 1.4.1 before you need it.

Before you start

Take a backup. Stop PegaProx (sudo systemctl stop pegaprox, or stop the container) and copy its config directory: /opt/PegaProx/config on a deploy.sh install, /var/lib/pegaprox/config on the Debian package (also the VM and LXC appliances), the config volume (/app/config) on Docker. It holds the databases (pegaprox.db, syslog.db) and the key file .pegaprox.key. If your install has a /etc/pegaprox/secret.key, copy it as well. Keep the key copies apart from the database copy: a backup that holds both gives whoever gets it every stored credential.

The first start encrypts the database

1.5 encrypts the whole database with SQLCipher on more platforms (#1226). The first start after the update encrypts pegaprox.db and syslog.db on:

  • the Debian package on amd64,
  • pip and deploy.sh installs on aarch64 Linux, macOS and Windows,
  • the arm64 Docker image.

Installs on Linux x86_64 with pip, deploy.sh or the Docker image encrypted the database before 1.5 already. On arm64, the Debian package of the repository in the README stays on plain SQLite with a warning in the log, and so does 32-bit ARM. Sensitive fields are encrypted with AES-256-GCM on every platform either way.

  1. A plain copy stays for one hour. The start that encrypts keeps a plain copy next to the database, pegaprox.db.plain.bak.<timestamp> (and syslog.db.plain.bak.<timestamp>). It holds every stored credential in the clear, so it is not kept for long: it stays until PegaProx starts again an hour or more later, and that start shreds it. PEGAPROX_PLAIN_BACKUP_RETENTION_S changes the window, see Environment Variables. If you want a longer way back, copy it somewhere safe right after the update and delete that copy yourself.
  2. The Debian package keeps the key in /etc/pegaprox/secret.key (0640 root:pegaprox) and puts it there before every start. It keeps an existing key and copies the key of an already encrypted database instead of making a new one. A key that others can read or write, an encrypted database no known key opens, or a database file it cannot read stops the start with the reason in the journal. Keep config/.pegaprox.key: older field values are still read with it.
  3. An encrypted database without a working SQLCipher module stops the start with [FATAL] [DBCRYPTO] and the reason, instead of starting and failing at the first query. pegaprox_multi_cluster.py --keystore-status only reads and shows which key PegaProx uses and which databases are encrypted.

Going back to 1.4.1

Once encrypted, the database opens in 1.4.1 only while SQLCipher is installed: python3-sqlcipher3 on the Debian package, the sqlcipher3 Python package on pip and deploy.sh installs.

  1. Debian package: keep the SQLCipher packages. Run this before the downgrade:

    sudo apt-mark manual python3-sqlcipher3 libsqlcipher1 sqlcipher

    The 1.4.1 package does not depend on them. Without this step apt counts them as no longer needed, apt autoremove removes them, and 1.4.1 can no longer open the database.

  2. Without SQLCipher, only the plain copy goes back. The arm64 Docker image of 1.4.1, for example, has no SQLCipher. Stop PegaProx and put pegaprox.db.plain.bak.<timestamp> back as pegaprox.db (and syslog.db.plain.bak.<timestamp> as syslog.db) while the copy is still there, so before PegaProx starts again an hour or more after the update. The copy holds the database as it was before the update: changes made under 1.5 are not in it. Once it is gone, restore the backup you took before the update.

  3. LDAP with a pasted CA certificate. If you pasted a CA certificate into Settings > LDAP under 1.5, turn off Verify TLS Certificate there, or put the directory's CA into the system trust store of the PegaProx host, before you go back. 1.4.1 ignores the pasted CA, so a directory certificate from a CA outside the system trust store fails its check and LDAP sign-ins stop working.
  4. Password expiry. With password expiry on, 1.4.1 shows local accounts as expired again, and its first user save sets the stored dates back to the time of the first 1.5 start.

What changes

These are the behaviour changes most installations notice. The update dialog lists all of them.

  1. Portal-only accounts are held to the Client Portal by the server, not only by the UI. Outside the portal's sign-in, SSO, 2FA enrolment, plugin API and console, the API, the live streams and the consoles answer 403 PORTAL_ONLY, also for their API tokens. Per guest they get what an ACL row or a pool grant names, not the role-wide grant, and a portal account that opens the main address is sent to /portal.
  2. Accounts confined to some guests by a pool grant or a VM ACL see only the nodes their guests run on, and get 403 or a reduced answer for host and datacenter reads: node disks, SMART, LVM and ZFS, network config, sensors, hardware, certificates, the subscription key, the datacenter firewall, SDN, cluster and join info, PCI and USB mappings, HA groups, config export, the cluster-wide storage and Ceph reads and similar. Scripts that need these reads have to run as an unconfined account.
  3. Backup servers and confined accounts: the reads of a PBS server itself (status, syslog, network, disks, jobs, datastore settings and usage, updates) answer 403 to an account confined on any cluster the PBS backs up, also to an operator when the PBS backs up another tenant's cluster too. The account still browses its own guests' backups. A PBS linked to no cluster counts as backing up every connected cluster: link each PBS to its clusters.
  4. Affinity rules: an account confined to some guests sees only the rules whose guests it may all see, on /api/affinity-rules as on the cluster route. A rule without a cluster is listed to administrators only.
  5. Failed Proxmox reads answer 502 or 503. Node and storage reads (network, time, system log, certificates, tasks, subscription, LVM, LVM-Thin, ZFS, PCI devices, storage content, Ceph) answer 502 PVE_READ_FAILED or 503 PVE_UNREACHABLE when Proxmox refuses or does not answer, where they used to answer 200 with an empty list or zeros. The datacenter status, the node DNS read and the HA resources answer 502 with an error but without that code (the datacenter status 503 when the cluster is unreachable), and PBS refusals of GC, verify, prune, snapshot delete and job runs answer 502 with the reason. API clients that read an empty answer as no data have to check the status.
  6. HTTP redirects are no longer followed by the Proxmox VE, PBS and ESXi connections, the console logins and the websocket upgrades, and a webhook or ntfy alert that gets a redirect counts as not delivered. A host or reverse proxy that answers with a redirect (for example from http to https) now ends in an error: configure the final address.
  7. Credentials typed again: moving the SMTP host or port, the LDAP server or port, a SIEM endpoint, the URL or fingerprint of an SDN IPAM or PowerDNS entry, or an address in a plugin config needs the password, token or key typed again in the same save (CREDENTIAL_REQUIRED). Plugin credentials (the ntfy token, Apprise URLs and the like), the SDN IPAM and DNS tokens and SIEM headers with key-like names are no longer shown in clear: to change one, type a new value.
  8. Password expiry counts from the update. Users now keep the date of their last password change. With password expiry on, existing local accounts count from the moment of the update, so they all expire on the same day, one expiry period after the update, unless they change their password before. The warning mails go out ahead of that day. LDAP, OIDC and Entra ID accounts are not affected.
  9. SSH user: every SSH login PegaProx makes to a Proxmox VE node on its own (sensors, in-band BMC, HA, backup restore, node commands and others) uses the cluster's SSH user, root when none is set, where some paths used the name of the API user. A cluster whose nodes accept its key only for the API user's name needs that name in the new SSH User field of the cluster dialog. Node commands, the node shell and Remove Node use the cluster's SSH port.
  10. OIDC and Entra ID accounts stay bound to their subject, in the Automatic username mode as well, not only with a picked username claim. A sign-in from another subject with the same name gets "This sign-in could not be matched to a PegaProx account" instead of the account and its role, and an email the identity provider marks as not verified no longer names an account. An account with no subject stored is bound by its next sign-in whose name is exactly its key (letter case aside). After a move to another identity provider, or a change of the subject ids it issues, reset each account's binding: User Management, edit the account, Reset sign-in binding (or DELETE /api/users/<username>/oidc-binding). The next sign-in binds it again.
  11. New LDAP setups start with STARTTLS and the certificate check on, and the LDAP settings take the directory's CA certificate (CA Certificate (PEM)). A directory that only offers plain LDAP, or whose certificate comes from a CA outside the system trust store, needs its CA certificate pasted into Settings > LDAP, or the options changed, before the first sign-in. Existing installs keep their LDAP settings; while they run in plain text or without the certificate check, the LDAP tab shows a note. With the check on, referrals are no longer followed: use the Global Catalog port (3268, or 3269 with LDAPS) or a base DN inside the domain.
  12. Classic Corporate is deprecated and only gets fixes. The first-login choice, My Profile and the interface lock offer Modern, Corporate Redesigned and Cloud; classic Corporate shows there only to an account still on it, and in the lock only while it is pinned. Its users see a bar with Switch now and Dismiss. Nobody is moved to Corporate Redesigned automatically, and an account that leaves classic Corporate cannot pick it again in the interface.
  13. Plain HTTP on the HTTPS port is answered with a redirect to https (301), also with http_redirect_port at -1, and ACME HTTP-01 tokens are answered there. X-Forwarded-Proto and X-Forwarded-Port are taken only from a trusted proxy.

The update dialog and the release notes on GitHub list the others, among them stricter ID token checks at the SSO sign-in, scheduled rolling updates that pause and wait like manual ones, containers created through the API that need a root password or an SSH key, the Client Portal's ISO routes that are off by default, and /i18n/<lang>.json, which a reverse proxy or IP allowlist that passes only chosen paths must let through like /.