How to upgrade to BalaBit Shell Control Box 3 F2

1. Preface

Welcome to BalaBit Shell Control Box (SCB) version 3 F2 and thank you for choosing our product. This document describes the process to upgrade existing SCB installations to SCB 3 F2. The main aim of this paper is to aid system administrators in planning the migration to the new version of SCB.

	Warning
	Read the entire document thoroughly before starting the upgrade.

This document covers the BalaBit Shell Control Box 3 F2 and Audit Player 2011.3 products.

2. Prerequisites to upgrading to SCB

This section describes the requirements and steps to perform before starting the SCB upgrade process.

Warning

Starting with SCB version 3.2, the usergroups of Channel Policies are treated separately on the client side (Gateway group) and the server side (Remote group). Before starting the upgrade to SCB 3.2, you might have to adjust your configuration. For details, see Section 3, Gateway groups and remote groups.
Starting with SCB version 3.2, SSH connections that use Usermapping Policies must use gateway authentication as well. If you have any SSH Connection Policies that have a Usermapping Policy set but do not require gateway authentication (either inband or outband), adjust these Connection Policies to require gateway authentication.
SCB has supported compression in RDP connections since version 3.0. However, it was found that enabling compression in certain RDP channels causes problems: most notably, files copied in disk redirection channels can become corrupt in certain situations. Therefore, although compression support for RDP connections is enabled by default in SCB version 3.2, it can be disabled by unchecking the RDP Control > Settings > Enable compression option.

Note that disabling compression significantly increases the network load of RDP connections. The exact ratio of the increase depends on the content of the connections, but on the average the network load can be expected to increase by 500%.

You must have a valid software subscription to be able to download the new version of SCB, and also the new license file.
You will need a MyBalaBit account to download the required firmware files and the license. If you have not done so yet, sign up for a MyBalaBit account at http://www.balabit.com/mybalabit/. Note that the registration is not automatic, and might require up to two working days to process.

2.1. Notes and warnings about the upgrade

The following is a list of important notes and warnings about the upgrade process and changes in SCB 3 F2.

Warning

It is possible to import a configuration exported from SCB 3.0.x into SCB 3 F2, but it is not possible to restore a 3.0.x backup into 3 F2.

If the connection database is large and contains information about several thousands of sessions, the upgrade process can take about 15-20 minutes or more, depending on the actual hardware.

	Note
It is strongly recommended to have IPMI (ILOM) or console access to the SCB appliance during the upgrade process. During the upgrade, SCB displays information about the progress of the upgrade and any possible problems to the console. If for some reason you are reinstalling SCB with version 3.2 instead of upgrading, note that appliances based on Sun Fire X4140 hardware must be restarted after the Welcome Wizard is completed.

Note

It is strongly recommended to have IPMI (ILOM) or console access to the SCB appliance during the upgrade process. During the upgrade, SCB displays information about the progress of the upgrade and any possible problems to the console.

If for some reason you are reinstalling SCB with version 3.2 instead of upgrading, note that appliances based on Sun Fire X4140 hardware must be restarted after the Welcome Wizard is completed.

2.2. Updating to the latest version

Upgrading to SCB 3 F2 is supported only from version 3.1.0 or later. To perform the upgrade, complete the following steps:

Download the latest SCB core and boot firmwares from http://www.balabit.com/network-security/scb/download/shell-control-box/
Update the firmwares of your SCB. For details, see Section 4.5.3, Upgrading SCB in BalaBit Shell Control Box 3 F2 Administrator Guide.

3. Gateway groups and remote groups

Starting with SCB version 3 F2, usergroup memberships of Channel Policies can be specified separately on the client side (Gateway group) and the server side (Remote group). Upgrading to SCB version 3 F2 modifies the Channel Policies as follows:

If the Group option of the Channel Policy is not set, the Channel Policy is not modified.
If the Group option of the Channel Policy is set, and the Channel Policy is used only in Connection Policies that do not require gateway authentication, the Group option of the Channel Policy is converted to Remote Group.
If the Group option of the Channel Policy is set, and the Channel Policy is used only in Connection Policies that require gateway authentication, the Group option of the Channel Policy is converted to Gateway Group.
If the Group option of the Channel Policy is set, and some of the Connection Policies require gateway authentication, while some of them do not, upgrading to SCB version 3.2 fails. SCB automatically reverts to the original firmware version. To resolve the situation, create a new Channel Policy and use it in the Connection Policies that require gateway authentication, then restart the upgrade.

4. Upgrading to SCB 3 F2

Complete the following steps:

	Warning
	After performing the upgrade, it is not possible to downgrade to version 3.0. Upgrading to SCB 3 F2 is an irreversible process.

	Tip
	It is recommended to test the upgrade process first in VMware. To this, download a VMware image of the latest SCB version, import the configuration of your SCB into this VMware version, and perform the upgrade. If everything is working, perform the upgrade on the production system.

	Warning
	When upgrading to SCB 3.2 within a 32bit VMware environment, it might cause problems at startup. It is recommended to upgrade the processor/system type first to 64bit or upgrade the hardware system with a 64bit capable CPU before performing the upgrade to SCB 3.2

	Warning
	If you have a Sun Fire x4140 hardware (SCB N2500d), and intend to upgrade to SCB 3.2, first, update the BIOS and the service processor firmware before upgrading to SCB 3.2. Failing to do so might result in malfunctioning interfaces. For details, see Sun Fire™ X4140 Server Installation Guide.

4.1. Procedure – Upgrading to SCB 3 F2

Download the SCB 3 F2 core firmware from http://www.balabit.com/network-security/scb/upgrades/
Download the SCB 3 F2 boot firmware from http://www.balabit.com/network-security/scb/upgrades/
Update the firmware of your SCB. Upload and activate both the 3 F2 boot and core firmwares. For details, see Section 4.5.3, Upgrading SCB in BalaBit Shell Control Box 3 F2 Administrator Guide.

Navigate to Basic Settings > System > System control > This node > Reboot to reboot the machine. SCB will start with the new firmwares and upgrade its configuration, database, and other system components. During the upgrade process, SCB displays status information and other data to the local console.

	Warning
	If the connection database is large and contains information about several thousands of sessions, the upgrade process can take about 15-20 minutes or more, depending on the actual hardware.

Login to the SCB web interface.

Warning

In case the SCB web interface is not available within 30 minutes of rebooting SCB, check the information displayed on the local console and contact the BalaBit Support Team.

If you experience any strange behavior of the web interface, first try to reload the page by holding the SHIFT key while clicking the Reload button of your browser to remove any cached version of the page.

	Note
In the unlikely case that SCB encounters a problem during the upgrade process and cannot revert to its original state, SCB performs the following actions: Initializes the network interfaces using the already configured IP addresses. Enables SSH-access to SCB, unless SCB is running in sealed mode. That way it is possible to access the logs of the upgrade process that helps the BalaBit Support Team to diagnose and solve the problem. Note that SSH access will be enabled on every active interface, even if management access has not been enabled for the interface.

Note

In the unlikely case that SCB encounters a problem during the upgrade process and cannot revert to its original state, SCB performs the following actions:

Initializes the network interfaces using the already configured IP addresses.
Enables SSH-access to SCB, unless SCB is running in sealed mode. That way it is possible to access the logs of the upgrade process that helps the BalaBit Support Team to diagnose and solve the problem. Note that SSH access will be enabled on every active interface, even if management access has not been enabled for the interface.

Navigate to Basic Settings > System > Version details and verify that SCB is running version 3 F2 of the core and boot firmware. If not, it means that the upgrade process did not complete properly and SCB performed a rollback to revert to the earlier firmware version. In this case complete the following steps:
1. Navigate to Basic Settings > Troubleshooting > System debug and click Collect and save current system state info.
2. Save the resulting ZIP file.
3. Contact the BalaBit Support Team and send them the file. They will analyze its contents to determine why the upgrade was not completed and assist you in solving the problem.

5. Upgrading the Audit Player

Upgrading the Audit Player application (AP) is only a simple installation process. See the BalaBit Shell Control Box 3 F2 Administrator Guide for details. The Audit Player application can be downloaded from http://www.balabit.com/network-security/scb/upgrades/.

6. Upgrading SCB clusters

If you are running an SCB high-availability cluster, complete the following steps:

6.1. Procedure – Upgrading an SCB cluster to 3 F2

Complete the prerequisites described in Section 2, Prerequisites to upgrading to SCB and upgrade the cluster to SCB version 3.0.1 or later.
Upload the SCB 3 F2 boot and core firmware, and set them to be active After reboot.

Warning

Do NOT reboot any of the SCB nodes at this point.
Navigate to Basic Settings > System > High availability & Nodes > Other node and click Shutdown to power off the slave node.

Warning

Do not power on the slave node.
Select This node > Reboot to reboot the master node.
Power on the slave node.
Login to the SCB web interface.
Test SCB to see if it is functioning properly after the upgrade. If you encounter any problems, contact your support team.

	Warning
	Do not power on the slave node.