Upgrade Guide from v2.8.1 to v2.9.0

This guide explains how to upgrade from IDSTower v2.8.1 to v2.9.0, to upgrade please follow the below steps.

1. Stop your IDSTower service

$ sudo systemctl stop idstower.service

2. Take a full backup of your current IDSTower database

$ sudo mysqldump -B [DatabseName] -u [DatabaseUsername] -p > IDSTower_backup_`date +%F_%H_%M_%S`.sql

3. Take a backup of your IDSTower directory (including settings)

$ sudo cp -Rp /opt/idstower /opt/idstower_2.8.1_backup_`date +%F_%H_%M_%S`

4. Configure the EncryptionKey setting

   From v2.9.0, IDSTower requires an EncryptionKey to be configured for secure storage of cluster keys. You need to add this to your configuration:

   If using appsettings.json:

   {
   "LicenseKey": "your-license-key",
   "EncryptionKey": "your-secure-random-64-character-hex-string",
   // other settings
   }
   

   If using Docker with environment variables:

   EncryptionKey=your-secure-random-64-character-hex-string
   

   The EncryptionKey should be a 64-character hexadecimal string (32 bytes). You can generate one using:

   $ openssl rand -hex 32
   

Note

Docker deployments only — preserve your cluster SSH keys before starting v2.9.0.

Up to v2.8.1, the SSH keys IDSTower uses to reach the hosts of a cluster were stored as files in the home directory of the account running IDSTower (/home/idstower/.ssh/). From v2.9.0 they live in the database, encrypted with your EncryptionKey, and the migration that moves them runs once, the first time v2.9.0 starts — reading those files.

A package installation (yum / apt, the steps below) upgrades IDSTower in place and keeps that directory, so there is nothing to do. A Docker deployment that upgrades by replacing the container starts with an empty filesystem: the keys are gone before the migration can read them, and IDSTower loses SSH trust to the hosts of every cluster.

Choose one of the two:

• Carry the keys over. Copy them out of the old container and mount them into the new one at the same path, before it starts for the first time:

  $ docker cp <old-container>:/home/idstower/.ssh ./idstower-ssh-keys
  # then add this to the new container's run command:
  #   -v $(pwd)/idstower-ssh-keys:/home/idstower/.ssh
  

  Keep the file ownership as copied — IDSTower runs as the idstower user inside the container and must be able to read the private key.

• Re-establish trust afterwards. Start v2.9.0 without the old keys, then run Cluster Actions → Reset SSH Trust for each cluster. This generates a fresh key pair and deploys the public key to the hosts, and needs the SSH credentials of those hosts.

If you are not sure which applies, check the log after the upgrade: a successful migration logs Successfully migrated and encrypted SSH keys for cluster <id>, and a missed one logs Could not find SSH key file for cluster <id>.

5. Upgrade IDSTower to Version 2.9.0.

on CentOS/RHEL/RockyLinux/AlmaLinux:

$ sudo yum update idstower-2.9.0-1

on Ubuntu/Debian:

$ sudo apt install idstower=2.9.0-1

6. Start the IDSTower service.

$ sudo systemctl daemon-reload
$ sudo systemctl start idstower.service

7. Verify IDSTower service has started correctly and database schema has been migrated

$ sudo systemctl status idstower.service

8. done.

Note: Make sure to keep your EncryptionKey secure and backed up. If you lose it, you won’t be able to decrypt the cluster keys stored in the database, however, you can always reset the cluster keys and re-encrypt them with a new EncryptionKey.