Skip to content

Upgrade or Downgrade

Upgrade GateKeeper

As a prerequisite to upgrading your version of Blackwall's GateKeeper, you must have Debian (version 12) installed cleanly on your system. Upgrade to Debian version 12 if you are currently on version 11. Then you must add the default recommended Blackwall GateKeeper Debian repository and install packages, as described in the following steps:

Need to install from the Early Access / Test repository?

For step-by-step instructions on this type of installation, see the FAQ entry How do I get Beta / Early-Access to GateKeeper?

  1. Import the Blackwall package digital signature key by executing the following two commands:

    apt-get update && apt install -y sudo curl gpg ca-certificates lsb-release apt-utils apt-transport-https

    curl -fsSL https://repo.botguard.net/botguard.gpg | gpg --dearmor > /usr/share/keyrings/botguard.gpg

  2. Add the Blackwall production repository to your system repositories by executing this command:

    echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian $(lsb_release -cs) gatekeeper" | tee /etc/apt/sources.list.d/botguard-gatekeeper.list
    3. Install the latest version of Blackwall's GateKeeper v1.6.X by executing the following two commands in sequence:

    apt update

    apt install botguard-gatekeeper

  3. Reboot your server to apply the changes to your operating system.

Downgrade GateKeeper to a Earlier Version

In some cases, you may need to roll back GateKeeper following an upgrade to version 1.6.X from an earlier version. For example, you may need to perform a rollback if you experience an installation issue, compatibility issue, or bug after upgrading. This procedure rolls back the GateKeeper packages from version 1.6 to 1.5.3-4.

Warning

Only perform a rollback if advised by Blackwall Support, or if you need to restore service after an upgrade issue. If you are unsure whether rollback is required, contact Blackwall Support before continuing.

Prerequisites

Before rolling back to a previous version, confirm that:

  1. The Blackwall GateKeeper repository is already configured.
  2. You have sudo or root access to the server.
  3. You have confirmed that version 1.5.3-4 is available from the configured repository.
  4. You have recorded any relevant error messages, logs, or symptoms from the failed upgrade (important).

Note

The rollback command uses --allow-downgrades because the package manager normally prevents older package versions from replacing newer installed versions.

Downgrading

To downgrade from version 1.6 to 1.5.3-4, perform the following steps:

  1. Update the local package list so that the server has the latest repository metadata:

    sudo apt update
    2. Run the following command to downgrade the GateKeeper packages to version 1.5.3-4:

    sudo apt install --allow-downgrades \
botguard-gatekeeper=1.5.3-4 \
botguard-gatekeeper-config=1.5.3-4 \
botguard-apiserver=1.5.3-4 \
botguard-certmanager=1.5.3-4 \
botguard-controller=1.5.3-4 \
botguard-firewall=1.5.3-4 \
botguard-webapp=1.5.3-4

  2. Review the package changes when prompted, then confirm the installation.

  3. If short-term service downtime is not problematic, we recommend performing a reboot of your server to ensure that all services and operating system changes are applied correctly:

    sudo reboot

  4. After the server has restarted, verify that the GateKeeper packages were downgraded successfully. Run the following command and then confirm that the relevant packages show version 1.5.3-4.

    dpkg -l | grep botguard

  5. Check that all GateKeeper services are running correctly:

    sudo systemctl status botguard-*

Troubleshooting

If the rollback does not complete successfully:

  1. Confirm that version 1.5.3-4 is available from the repository:

    apt-cache policy botguard-gatekeeper

  2. Check for package dependency errors in the terminal output.

  3. Review the service logs for any failed services:

    journalctl -u botguard-gatekeeper -n 100 --no-pager

  4. Contact Blackwall Support and provide:

    • The installed GateKeeper version before rollback.
    • The rollback command output.
    • Any package dependency errors.
    • Relevant service logs.
    • The affected domain or Zone.
    • Any relevant error messages, logs, or symptoms from the failed upgrade (important).
Feedback