> For the complete documentation index, see [llms.txt](https://docs.storware.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.storware.eu/deployment/upgrade.md).

# Upgrading solution

## Overview

This chapter describes how to upgrade an existing Storware Backup & Recovery installation on RPM-based and Debian-based systems. Complete the preparation steps before upgrading the Server, then upgrade each Node.

Run all commands as `root` or with equivalent administrative privileges.

{% hint style="info" %}
**High availability:** For services managed by Pacemaker, coordinate the upgrade through the cluster. The standalone service commands in this chapter must not be used while Pacemaker is managing those services.
{% endhint %}

## Upgrading solution

### Before You Begin

#### Check the Upgrade Requirements

Review the release notes and installation requirements for the target version. Confirm that your operating system, MariaDB version, and upgrade path are supported. Some upgrades may require intermediate releases or additional steps.

Plan a maintenance window and upgrade the Server and all Nodes to the intended release before resuming scheduled operations.

#### Check Installed Versions

On RPM-based systems:

```bash
rpm -qa | grep -Ei '^(vprotect|mariadb)'
```

On Debian-based systems:

```bash
dpkg -l | grep -Ei '^ii[[:space:]]+(vprotect|mariadb)'
```

On the database host, check the running MariaDB version:

```bash
mariadb -u root -p -e "SELECT VERSION();"
```

If the `mariadb` client command is unavailable, use `mysql` instead. Record these versions before continuing.

#### Prepare the Repositories

On the Server and each Node, configure the Storware repository for the target release and operating system, following the corresponding installation instructions. Keep package signature verification enabled.

RPM repository definitions are stored in `/etc/yum.repos.d/`. Debian repository definitions are typically stored in `/etc/apt/sources.list.d/` as `.list` or `.sources` files.

Refresh repository metadata and review available versions.

For RHEL and compatible systems using DNF:

```bash
dnf makecache --refresh
dnf list --showduplicates vprotect-server vprotect-node
```

For Debian-based systems:

```bash
apt-get update
apt-cache policy vprotect-server vprotect-node
```

The upgrade commands below install the version selected by the package manager. Confirm that it is the intended version before accepting the transaction.

#### Stop Tasks and Services

1. Temporarily disable schedules that could start tasks during the maintenance window. Ensure that other users and external integrations do not submit new tasks.
2. In the web UI, wait for running tasks to finish and resolve any remaining queued tasks.
3. On the Server, stop the service:

   ```bash
   systemctl stop vprotect-server
   ```
4. Check that no task was created immediately before the service stopped:

   ```bash
   mariadb -u root -p -e "SELECT * FROM vprotect.task;"
   ```

   If the query returns rows, start the Server again and resolve the remaining tasks through the application. Stop the Server and repeat the check before continuing. Do not delete task records directly from the database.
5. Stop the Node service on every Node, including a Node installed on the Server host:

   ```bash
   systemctl stop vprotect-node
   ```

Keep schedules disabled until the entire upgrade has been verified.

#### Back Up the Database and Configuration

With application services stopped and MariaDB running, create a database backup on the Server:

```bash
/opt/vprotect/server/scripts/backup_db.sh /path/to/backup/file.sql.gz
```

Replace the example path with an existing, writable location. Confirm that the script completes successfully and retain the backup outside the host being upgraded. You can check the compressed file for corruption with:

```bash
gzip -t /path/to/backup/file.sql.gz
```

This check verifies the compressed file, not whether the database can be restored.

Also back up configuration files, certificates, keystores, and repository definitions. Preserve file ownership and permissions.

For virtual deployments, consider taking a consistent VM snapshot as an additional recovery point. A snapshot does not replace the database backup. If MariaDB is hosted separately, coordinate recovery of the application and database.

### MariaDB Requirements

Confirm that the installed MariaDB version is supported by the target Storware Backup & Recovery release. Do not upgrade MariaDB to an arbitrary newer release as part of the application update.

If a database upgrade is required, complete the applicable MariaDB upgrade procedure while Storware services remain stopped. The procedure depends on the source version, target version, operating system, and package provider.

A major-version upgrade may require repository changes, replacement of database packages, and execution of:

```bash
mariadb-upgrade -u root -p
```

Older installations may provide this utility as `mysql_upgrade`. Follow the instructions for the selected upgrade path; do not use `rpm --nodeps` as a routine upgrade step.

Before continuing, confirm that MariaDB starts successfully and the `vprotect` database is accessible:

```bash
systemctl status mariadb --no-pager
mariadb -u root -p -e "SELECT VERSION(); SHOW DATABASES LIKE 'vprotect';"
```

### Upgrade on RHEL and Compatible Systems

These commands apply to RPM-based systems that use DNF. On supported installations that use YUM, use the corresponding `yum update` commands.

#### Upgrade the Server

On the Server host:

```bash
dnf upgrade vprotect-server
systemctl start vprotect-server
```

Package scripts may restart the service during the upgrade. Allow startup and any database migration to complete before proceeding.

Check the service status and startup messages:

```bash
systemctl status vprotect-server --no-pager
journalctl -u vprotect-server -n 100 --no-pager
```

#### Upgrade Each Node

Repeat on every Node, including any Node installed on the Server host:

```bash
systemctl stop vprotect-node
dnf upgrade vprotect-node
systemctl stop vprotect-node
vprotect-node-configure
systemctl start vprotect-node
```

The second stop ensures that the Node is stopped if the package upgrade started it automatically. The configuration script applies the operating system settings required by the Node. Review its output and complete any required follow-up actions.

Check the service:

```bash
systemctl status vprotect-node --no-pager
```

### Upgrade on Debian-Based Systems

#### Upgrade the Server

On the Server host, with the target repository already configured:

```bash
apt-get update
apt-get install --only-upgrade vprotect-server
systemctl start vprotect-server
```

If prompted about locally modified configuration files, review the differences and preserve the settings required by your deployment.

Allow startup and any database migration to complete, then check the service:

```bash
systemctl status vprotect-server --no-pager
journalctl -u vprotect-server -n 100 --no-pager
```

#### Upgrade Each Node

Repeat on every Node:

```bash
systemctl stop vprotect-node
apt-get update
apt-get install --only-upgrade vprotect-node
systemctl stop vprotect-node
vprotect-node-configure
systemctl start vprotect-node
```

The second stop ensures that configuration runs with the Node stopped even if the package upgrade started it automatically.

Check the service:

```bash
systemctl status vprotect-node --no-pager
```

### Verify the Upgrade

1. Log in to the web UI and confirm the Server version.
2. Confirm that all Nodes are connected and report the intended version.
3. Review service and application logs for startup or database migration errors.
4. Verify access to protected environments and backup destinations.
5. Run a test backup and restore to validate the upgraded environment.
6. Re-enable schedules and confirm that the internal database backup is configured and completes successfully.

If the web UI displays outdated content, perform a hard refresh: **Ctrl+Shift+R** on Windows/Linux or **Command+Shift+R** on macOS in Chrome.

Retain the pre-upgrade database and configuration backups until validation is complete. If recovery is required, restore a matching application and database state; reinstalling older packages alone may not reverse database changes.