Roxy-WI update guide

YUM

If you installed Roxy-WI using RPM or DEB, run the following command:

If your Roxy-WI server uses a proxy to connect to the Internet, add the proxy settings to the yum.conf file:

Update Roxy-WI via the Web Interface

Before updating Roxy-Wi via Web Interface, add the Apache user to the sudoers file:

Add permissions for the Apache user:

If your Roxy-WI server uses a proxy to connect to the Internet, add the proxy settings to yum.conf:

All information concerning RPM packages can be found here .

Migrate to Checker 5, Metrics 4 and Socket 2

Checker 5, Metrics 4 and Socket 2 are long-running services that communicate with Roxy-WI through RabbitMQ. The old checker_master.py, metrics_master.py and per-target subprocess model is no longer used. Existing monitoring selections are converted into durable assignments by the Roxy-WI scheduler.

These managed services require an active User plan or higher. Update Roxy-WI before updating the workers so the database migration, command scheduler and service-event consumer are available.

Before the update:

Back up the Roxy-WI database, /etc/roxy-wi/roxy-wi.cfg and /var/lib/roxy-wi/keys.
Install and configure RabbitMQ. All Roxy-WI instances and workers must use the same host, port and virtual host; credentials may be shared or service-specific.
Make every monitored server address and statistics endpoint reachable from the worker hosts. A remote worker cannot use 127.0.0.1 to reach another server.

RPM-based installation on the Roxy-WI host:

sudo dnf upgrade --refresh roxy-wi
sudo dnf install roxy-wi-checker roxy-wi-metrics roxy-wi-socket
sudo systemctl enable --now roxy-wi-scheduler roxy-wi-service-events
sudo systemctl enable --now roxy-wi-checker roxy-wi-metrics roxy-wi-socket

DEB-based installation on the Roxy-WI host:

sudo apt update
sudo apt install --only-upgrade roxy-wi
sudo apt install roxy-wi-checker roxy-wi-metrics roxy-wi-socket
sudo systemctl enable --now roxy-wi-scheduler roxy-wi-service-events
sudo systemctl enable --now roxy-wi-checker roxy-wi-metrics roxy-wi-socket

Package upgrades preserve the service environment files and replace the legacy master processes. Do not start the removed master scripts manually. Packages no longer require Roxy-WI on the same host. The default auto mode reuses the local Roxy-WI RabbitMQ settings when available; on a worker-only host set *_USE_ROXYWI_RABBITMQ_SETTINGS=0 and configure *_RABBITMQ_* in the service env-file before starting it.

On a standalone worker host, install only the required service package. A fresh standalone package is enabled but is not started until you configure its env-file. After saving the RabbitMQ settings, run systemctl enable --now roxy-wi-checker, roxy-wi-metrics or roxy-wi-socket as appropriate.

Moving package services to containers:

Prepare the container environment files and persistent databases first.
Stop the package units to prevent duplicate worker identities and a Socket port conflict.
Pull and start the pinned container versions with Compose or your Kubernetes deployment.

sudo systemctl disable --now roxy-wi-checker roxy-wi-metrics roxy-wi-socket
docker compose pull
docker compose up -d

Use ghcr.io/roxy-wi/roxy-wi-checker:5.0.0, ghcr.io/roxy-wi/roxy-wi-metrics:4.0.0 and ghcr.io/roxy-wi/roxy-wi-socket:2.0.0. Pin exact versions in production. Checker and Metrics may use SQLite with one replica; two or more replicas must share their own MySQL/MariaDB database. The Checker, Metrics and Roxy-WI schemas must remain separate.

Package-installed services can still be updated from Admin area => Update. Container and Kubernetes deployments are updated by changing the image tag and performing a Compose or Kubernetes rollout; Roxy-WI does not replace those images itself.

Verification:

systemctl status roxy-wi-scheduler roxy-wi-service-events
systemctl status roxy-wi-checker roxy-wi-metrics roxy-wi-socket
# or, for containers:
docker ps --filter name=roxy-wi

Within approximately one minute, the workers and their active assignment counts must appear on Overview and Admin area => Tools. Checker incidents remain available in Checker history, and Metrics samples continue to feed the existing graphs.

Updating from 4.2.2 and earlier to later versions

Due to the new version of Python, there is a conflict between two packages: the newer package python36-mod_wsgi conflicts with the older python35u-mod_wsgi. To update to version 4.2.3, you should first remove the old package:

Once you have removed the old package, you can proceed with the update either manually or through Roxy-WI:

Updating from version 4.4.1 to 4.4.2

You can only update from version 4.4.1 to 4.4.2 manually.

You must be logged into Roxy-WI to perform any actions, or you must have an admin user in the All group.

First, update Roxy-WI by running the following command:

This action will reset the settings to their default values.

You should also re-create all your groups. If you re-create the groups in the same order as they were originally created, it will not affect your users or servers.

Updating to 5.1.4

With our project rebranding to Roxy-WI, the packages will also be renamed.

First, delete the old repository: haproxy-wi-release-7.

Then, install a new repository:

You will need to remove all installed services:

haproxy-wi-checker
haproxy-wi-smon
haproxy-wi-metrics
haproxy-wi-checker
haproxy-wi-portscanner
haproxy-wi-keep_alive

and reinstall them using the new names:

roxy-wi-checker
roxy-wi-smon
roxy-wi-metrics
roxy-wi-checker
roxy-wi-portscanner
roxy-wi-keep_alive

Updating from 5.1.4 to 5.2.0 version

In the next step, install the new Roxy-WI packages and rename the database and configuration file. If you are using RPM installation, run the following commands:

If you are not using RPM, simply skip the step with yum.

Updating from 5.4.3 to 5.5.0 version

In version 5.5.0, the processes for sending notifications and alerts have been significantly enhanced. All notifications are now sent to users through a new service called Socket, which utilizes RabbitMQ as a message broker. All services publish notifications to RabbitMQ, and the Socket service retrieves them to send to users. To update to version 5.5.0, you need to install RabbitMQ and the Socket service. After that, update all previously installed services and add the following lines to the Apache configuration file:

Once you have updated to version 5.5.0, all services will utilize the new logging system based on Rsyslog.

Updating from 5.5 to 6.0 version

Starting with version 6.0, Roxy-WI displays information about subscriptions. To ensure proper functionality, you must log out and then log back in after the update. This will allow Roxy-WI to refresh its internal information.

The group All has been renamed to Default. You may need to update your scripts accordingly

Updating to 6.1.1 version

Starting with version 6.1.1, Roxy-WI stores keys, lists, configurations, and its SQLite database in a new folder: /var/lib/roxy-wi. This change enhances security and simplifies the process of updating the Docker container.

Additionally, the Roxy-WI configuration file (roxy-wi.cfg) has been moved to the /etc/roxy-wi folder.

To move all the necessary folders to their new location, follow these steps:

If you get errors after the update, check the default configuration and add any missing parameters.

Updating to 6.2.0 version

Starting with version 6.2.0, Roxy-WI log files have been moved to the /var/log/roxy-wi folder. You will need to make some manual changes to continue using Roxy-WI.

First, run the following commands to move your log files:

Then, update your roxy-wi.cfg file according to the exemple:

Updating to 7.0.0 version

Starting with version 7.0.0, Roxy-WI has begun using Flask. If you installed the packages, please delete the following Roxy-WI tools via the terminal:

roxy-wi-metrics
roxy-wi-checker
roxy-wi-smon
roxy-wi-keep_alive
roxy-wi-socket
roxy-wi-portscanner
roxy-wi-prometheus-exporter

Then, update Roxy-WI and reinstall the tools.

Also check the configuration file at /etc/roxy-wi/roxy-wi.cfg:

Also, check the Apache2 (httpd) configuration. It should look like this (example for EL):

Updating to 7.1.0 version

Starting with version 7.1.0, Roxy-WI has introduced a new approach to working with HA clusters. If you are using Keepalived and wish to manage it through Roxy-WI, please follow these steps:

Open the Admin area => Servers page and select No slave in the Slave for dropdown.
Open the HA cluster page.
Click Create high availability cluster.
Create a new HA cluster according to your configuration.
Click Save.
Add an additional VIP if necessary.
Add an extra virtual server if needed.
If you would like to reconfigure your cluster according to HA cluster settings, click Edit on the cluster you wish to reconfigure. In the opened window, click Next, and then Apply.

Updating to 7.2.0 version

Starting with version 7.2.0.0, Roxy-WI encrypts SSH passwords and passphrases. As a result, these values must be encrypted since the Roxy-WI configuration now includes a salt. Please add the following parameter to your configuration:

Use the following command to generate the salt:

Reload your Apache server. If you have used passwords for SSH access, please re-enter the passwords, as Roxy-WI will encrypt them.

Updating to version 8

Starting with version 8, Roxy-WI uses the latest versions of Python 3. Therefore, you must update Python 3 before updating Roxy-WI.

For EL, it must be Python 3.11:

                                rpm -e --nodeps python3-mod_wsgi ansible-collection-community-general ansible ansible-core
                                yum install python3.11-mod_wsgi

For Ubuntu, Python 3 must be at least version 3.9.

After updating Roxy-WI, you need to create keys for JWT tokens:

                                ssh-keygen -t rsa -b 4096 -m pem -f /var/lib/roxy-wi/keys/roxy-wi-key -C "Roxy-WI JWT KEY. DO NOT DELETE IT!" -P ""
                                
                                For EL:
                                chown apache:apache /var/lib/roxy-wi/keys/* -R
                                systemctl reload httpd
                                
                                For Ubuntu:
                                chown www-data:www-data /var/lib/roxy-wi/keys/* -R
                                systemctl reload apache2

If you encounter an internal error or cannot log in, download the update file to /var/www/haproxy-wi/app and run it:

                                cd /var/www/haproxy-wi/app
                                
                                For EL:
                                python3.11 update_db_to_v8.py
                                systemctl reload httpd
                                
                                For Ubuntu:
                                python3 update_db_to_v8.py
                                
                                systemctl reload apache2

Updating to version 8.1.4

Starting with version 8.1.4, Roxy-WI starts to keep SSH keys in the DB. You have to upload again your keys.

Update guide