1. No category

How to upgrade to Zorp Professional 3.4 LTS (3.4R2)
March 22, 2013
Copyright © 1996-2013 BalaBit IT Security Ltd.
Table of Contents
1. Preface ............................................................................................................................................. 3
2. Prerequisites to upgrading to Zorp ..................................................................................................... 4
3. Notes and warnings about the upgrade ................................................................................................ 5
4. Main changes of the system resulting from the upgrade ......................................................................... 6
5. Upgrading your Zorp Firewall System to version 3.4 LTS ....................................................................... 6
6. Upgrading Zorp Management Server to version 3.4 LTS ........................................................................ 7
7. Main changes in the Zorp configuration ............................................................................................... 9
8. Upgrading a host to Zorp 3.4 LTS ....................................................................................................... 9
9. Troubleshooting the upgrade ............................................................................................................ 12
10. Upgrading ZAS and ZCV ............................................................................................................... 13
11. Upgrading Zorp clusters ................................................................................................................. 13
12. Migrating a 32-bit Zorp Management Server to a 64-bit operating system ............................................ 14
13. Updating a host to the latest Zorp 3.3 version ................................................................................... 15
www.balabit.com
2
Preface
1. Preface
Welcome to Zorp Professional (Zorp) version 3.4 LTS and thank you for choosing our product. This document
describes the process to upgrade existing Zorp installations to Zorp 3.4 LTS. The main aim of this paper is to aid
system administrators in planning the migration to the new version of Zorp.
Warning
Read the entire document thoroughly before starting the upgrade.
This document covers the Zorp Professional 3.4 LTS product and its related components.
www.balabit.com
3
Prerequisites to upgrading to Zorp
2. Prerequisites to upgrading to Zorp
This section describes the requirements and steps to perform before starting the Zorp upgrade process.
■ You must have a valid software subscription to be able to download the new version of Zorp, and also
the new license file.
■ You will need a MyBalaBit account to download the required 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.
■ Upgrade is only supported for hosts running Zorp 3.3 or Zorp 3.3FR1. Before starting the upgrade
process to Zorp 3.4 LTS, update the operating system of the host to the latest version.
■ It is not possible to run ZMS 3.4 LTS on a 32-bit operating system. Ensure that your hardware running
ZMS supports 64-bit operating systems.
■ Upgrading to Zorp 3.4 LTS is supported only for hosts running the 64-bit version of the ZorpOS operating system. If the host is running the 32-bit version, a simple upgrade is not possible, and a complete
reinstallation is needed.
■ Upgrade is supported only for hosts that are managed using the Zorp Management Server (ZMS). If a
host is managed locally without using ZMS, request help from the BalaBit Support Team for manually
upgrading the configuration files.
■ The host must use the GRUB boot loader — upgrade for hosts running the LILO bootloader is not
supported. Note that ZorpOS uses GRUB by default, and LILO can only appear on a host if it was installed manually.
■ The installed packages of the host must be in a consistent state, that is, the apt-get install -f
must return an empty list.
■ The configuration of every Zorp component must be uploaded and active on the host. Upload and reload
every configuration change from ZMC before starting the upgrade.
www.balabit.com
4
Notes and warnings about the upgrade
3. Notes and warnings about the upgrade
The following is a list of important notes and warnings about the upgrade process and changes in Zorp 3.4 LTS.
Warning
■ Check Section 2, Prerequisites to upgrading to Zorp (p. 4) to verify that your hosts can be upgraded.
■ After starting the upgrade script, it is not possible to stop the upgrade and return to Zorp 3.3. The most important settings are backed up, but no automatic rollback is performed. If you encounter problems during the
upgrade and you must restore the Zorp 3.3 system for some reason, contact your local Zorp Support Team or
directly BalaBit IT Security to help you.
■ Zorp 3.4 LTS requires a new kernel. Do not use the upgrade script if you are using a customized kernel.
Contact your local Zorp Support Team or directly BalaBit IT Security to help you with the upgrade process.
■ If you have manually modified any configuration files (e.g., Postfix configuration file), make sure to create a
backup before starting the upgrade. Configuration files that were modified manually are automatically reset to
their ZorpOS default. Files that were managed using the Freetext ZMC plugin are not affected.
■ Older packages or other third-party packages that are not available in Zorp 3.4 LTS, and packages that do not
have every dependencies available in Zorp 3.4 LTS will be removed.
■ Traffic to and through the host is disabled during the upgrade, only ZMS transfer agent, ZMC, and SSH connections are accepted.
■ It is possible to perform the upgrade remotely using SSH, but it is strongly recommended to have local access
to the upgraded host.
■ If you use a local mirror to update your Zorp firewalls, and not the apt.balabit.com site directly, Zorp
should be upgraded from the CD-ROM.
■ The host must be rebooted at the end of the upgrade process. After rebooting the host, its configuration must
be uploaded and activated from ZMS that has already been upgraded to version 3.4 LTS.
Note
■ Upgrading the software packages on the host is a two-step process, therefore upgrading the same packages is
displayed twice during the process. This is normal.
■ During the upgrade, the host is accessible using SSH on port 9004 on every interface for recovery and
troubleshooting purposes. If the host had SSH access enabled, it is also available on the original port it was
configured. However, the latter will be disabled when the SSH server is upgraded.
■ If the upgrade script encounters an error and stops for some reason, it is possible to resume the upgrade by
running the upgrade script again after the problem has been solved.
www.balabit.com
5
Main changes of the system resulting from the upgrade
4. Main changes of the system resulting from the upgrade
Zorp Professional 3.4 LTS uses the ZorpOS 4 operating system. Compared to ZorpOS 3, the main changes are
the following:
■ The ZorpOS 4 operating system uses the Upstart init system. Therefore during the upgrade certain
software packages may send error messages about not being able to start a certain service. This is normal
and does not affect the upgrade.
As a result of using Upstart, any custom scripts that handles services might have to be updated manually.
■ The ZorpOS 4 operating system uses version 2.6 of the Python script language. Scripts added to the
host manually might have to be manually upgraded as needed. Note that Python 2.6 sends warnings in
much more cases compared to version 2.4.
■ The configuration files (for example, the iptables configuration) of Zorp 3.4 is not compatible with the
earlier versions. The old configuration files are automatically backed up by appending the
.zorpos-upgrade suffix to the files. Upgrading the configuration files is performed by ZMS.
■ The disk devices of the host are renamed from hdx to sdx, for example, hda is renamed to sda.
■ The hostname of the host cannot contain underscore (_) characters in ZorpOS 4. Underscores found
in the hostname will be automatically replaced with hyphens (-).
■ In earlier versions of Zorp, the NTP and BIND services were running in a jailed environment similar
to chroot. By default, these services are not jailed anymore, but use AppArmor instead. Upgrading to
Zorp
3.4
LTS
moves
the
/var/chroot/bind9/etc/bind/named.conf
and
/etc/bind/named.conf.shared automatically to the /etc/bind/ directory. However, you have
to manually copy any other files that you have modified to the /etc/bind/ directory.
Note that it is possible to configure BIND to run in a chroot.
Warning
If you had any local changes to the jails of NTP or BIND, you must manually transfer these changes after the upgrade, as
they are not propagated automatically to the new configuration.
5. Procedure – Upgrading your Zorp Firewall System to version 3.4 LTS
Purpose:
To upgrade every host of a Zorp Firewall System to version 3.4 LTS, complete the following steps. Before starting
the following procedure, read this entire document carefully.
Note
This procedure is a high-level overview of the upgrade process and references detailed procedures that describe the individual
steps.
Steps:
www.balabit.com
6
Main changes of the system resulting from the upgrade
Step 1. Upgrade your Zorp Management Server as described in Procedure 6, Upgrading Zorp Management Server to version
3.4 LTS (p. 7).
Step 2. Upgrade your other hosts as described in Procedure 8, Upgrading a host to Zorp 3.4 LTS (p. 9).
Step 3. Test your environment and check that your Zorp services are operating properly.
Step 4. In case you encounter any problems, refer to the upgrade logs as described in Section 9, Troubleshooting the
upgrade (p. 12), or contact your Zorp Support Team.
6. Procedure – Upgrading Zorp Management Server to version 3.4 LTS
Purpose:
To upgrade a Zorp Firewall System to version 3.4 LTS, first the Zorp Management Server must be upgraded.
Complete the following steps. Before starting the following procedure, read this entire section carefully.
Prerequisites:
Warning
Upgrading ZMS is possible only if ZMS is running on a 64-bit operating system. If your ZMS is using a 32-bit system, refer
to Procedure 12, Migrating a 32-bit Zorp Management Server to a 64-bit operating system (p. 14).
It is not possible to run ZMS 3.4 LTS on a 32-bit operating system.
The configuration of every Zorp component must be uploaded and active on the host. Upload and reload every
configuration change from ZMC before starting the upgrade. Also, check the general prerequisites described in
Section 2, Prerequisites to upgrading to Zorp (p. 4).
Steps:
Warning
After starting to upgrade ZMS, you will not be able to modify the configuration of other hosts until you have
finished upgrading ZMS and the other hosts as well.
Step 1.
Upgrade the operating system of the ZMS host as described in Procedure 8, Upgrading a host to Zorp 3.4
LTS (p. 9).
Step 2. Upgrade Zorp Management Console (ZMC) on your desktop machines. ZMC is available on the Zorp 3.4
LT S
Installation
DVD-ROM
and
on
the
BalaBit
website
at
http://www.balabit.com/network-security/zorp-gateway/support/upgrade/.
Warning
Do not connect to ZMS 3.4 LTS using ZMC 3.3.
www.balabit.com
7
Main changes of the system resulting from the upgrade
Step 3. Connect to your upgraded ZMS host using ZMC 3.4 LTS. When you connect to the upgraded ZMS engine
for the first time with ZMC 3.4 LTS, a warning is displayed that ZMS database must be upgraded. Click
Convert.
Warning
If the hostname of your ZMS host contained underscore (_) characters, the underscores found in the hostname
have been automatically replaced with hyphens (-).
Step 4. ZMC converts the configuration database to the 3.4 LTS format. The main changes in the configuration
are described in Section 7, Main changes in the Zorp configuration (p. 9).
Step 5. Upload and restart the configuration of the ZMS host.
Step 6. Upgrade the other hosts of your Zorp Firewall System.
www.balabit.com
8
Main changes in the Zorp configuration
7. Main changes in the Zorp configuration
The new version of the iptables packet filtering utility includes some important changes that may effect your
packet-filtering rules:
■ The following matches are not supported anymore: mss, cmd-owner, sid-owner, pid-owner.
Upgrading to Zorp 3.4 disables every rule using these matches.
■ The IMQ and MIRROR targets are not supported anymore. Upgrading to Zorp 3.4 disables every rule
using these targets.
■ The tproxy table and the tproxy match is not supported anymore. Upgrading to Zorp 3.4 disables every
rule using the tproxy table or the tproxy match. It is recommended that you move such rules to the
MANGLE table. Note that after you remove the last disabled rule from the tproxy table, the tproxy
table will not be displayed anymore in ZMC.
■ The ttl match has been renamed. Rules using this match are automatically upgraded.
■ The ignore-mark option of the kzorp kernel module is not supported anymore; the kzorp target can be
used instead. Note that by default, Zorp directs every packet to the kzorp target in the mangle table.
Explicitly accepting packets earlier in the iptables rules provides a way to avoid kzorp.
■ Zone matches can be used even in the prerouting chain of the mangle table.
■ Packet-filtering rules using the 0x80000000 MARK iptables target are disabled during the upgrade, because
Zorp 3.4 uses this target for its own purposes. Please do not use the MARK target, and modify your
existing rules to work without the target. In case you need assistance in modifying your rules, contact
your Zorp Support Team. Note that in case you use links or variables to set the parameter of the MARK
target, the rule is disabled.
■ During the ZMS upgrade the upgrade attempts to remove the now obsolete dummy interface from the
configuration. If the dummy interface is referenced somewhere, it cannot be automatically removed,
and a warning about the dummy interface is displayed. This warning can be ignored.
8. Procedure – Upgrading a host to Zorp 3.4 LTS
Purpose:
To upgrade an existing Zorp installation to version 3.4 LTS, complete the following steps. Before starting the following procedure, read this entire section carefully. This procedure describes how to upgrade the operating system
on a host of the Zorp Firewall System to ZorpOS 4.
Prerequisites:
The configuration of every Zorp component must be uploaded and active on the host. Upload and reload every
configuration change from ZMC before starting the upgrade. Also, check the general prerequisites described in
Section 2, Prerequisites to upgrading to Zorp (p. 4).
Steps:
Step 1. Make your new Zorp licenses accessible from the host you want to upgrade. The licenses can be installed
from a local webserver via HTTP, or from a USB drive.
www.balabit.com
9
Main changes in the Zorp configuration
Warning
The directory structure of the webserver, floppy, or USB drive must be identical to the one of the Zorp License
Media you received from BalaBit or your local distributor.
If you fail to install the new licenses during the upgrade, you must copy the license files to the host manually to
the following locations:
■ Zorp Management Server (ZMS): /etc/zms/license.txt
■ Zorp Application Level Firewall (Zorp): /etc/zorp/license.txt
■ Zorp Authentication Server (ZAS): /etc/zas/license.txt
■ Zorp Content Vectoring Server (ZCV): /etc/zcv/license.txt
■ NOD32 Antivirus engine: /etc/nod32/license/
Zorp and its components will not operate without the new license files.
Step 2. Login to the host as root from a local console.
Note
It is possible to perform the upgrade remotely using SSH, but it is strongly recommended to have local access to
the upgraded host.
Step 3. The installed packages of the host must be in a consistent state. Execute the apt-get install -f
command and verify that no errors are reported.
Step 4. Insert the Zorp 3.4 LTS Installation Disk into the DVD drive and issue the following command: mount
/dev/cdrom -o exec; cd /media/cdrom/upgrade.
Step 5. Issue the following command to start the upgrade process: ./upgrade
Warning
After starting the upgrade script, it is not possible to stop the upgrade and return to Zorp 3.3. The most important
settings are backed up, but no automatic rollback is performed. If you encounter problems during the upgrade
and you must restore the Zorp 3.3 system for some reason, contact your local Zorp Support Team or directly
BalaBit IT Security to help you.
Step 6. Select the installation media from which you want to upgrade the Zorp host. You can always use the DVDROM, or you can download the new packages from the official BalaBit website.
Step 7. After the packages are upgraded, reboot the system.
Step 8. During the upgrade, the packages used on the host are updated and configured. Depending on the upgrade
method (DVD or network) and on the actual hardware, this step may take up to an hour. When upgrading
the packages, you may need to answer various configuration questions. These questions are described in
detail in the Zorp 3.4 LTS Installation Guide.
Note
If the configuration files of any software package has been modified locally on the host, the upgrade might ask
how to upgrade the configuration of these packages (for example, keep the old configuration). Select the answer
that best suits your environment.
www.balabit.com
10
Main changes in the Zorp configuration
Step 9. If you are upgrading your ZMS host, return to Procedure 8, Upgrading a host to Zorp 3.4 LTS (p. 9).
Step 10.
Warning
Perform this step only after you have upgraded your Zorp Management Server and Zorp Management Console
application to 3.4 LTS.
Step a. Login to your Zorp Management Server using ZMC.
Step b. Skip this step if you are upgrading to Zorp 3.4 using the 3.4R1b or a newer release.
Select the host in ZMC, then select System logging > Destinations. Edit the Message
template field of your destination drivers to include the $MSGHDR macro (for example,
to $ISODATE $HOST $MSGHDR$MSG\n).
Step c. Upload and reload the configuration of every component of the host.
www.balabit.com
11
Troubleshooting the upgrade
9. Troubleshooting the upgrade
In case an error happens during the upgrade, the following information can be useful to diagnose and solve the
problem:
■ Log files of the upgrade are stored in the /var/log/dist-upgrade/ directory.
■ The upgrade script keeps a journal about which upgrade tasks have been completed. The list of completed
and yet to do tasks are stored in the /var/tmp/zorpos_upgrade/complete and
/var/tmp/zorpos_upgrade/incomplete directories, respectively. If the upgrade script encounters
an error and the upgrade is not completed, restart the upgrade script after solving the problem, and
the upgrade process will continue from the last task.
■ The PostgreSQL database of the host is upgraded as well. The contents of the database are dumped
into the /var/tmp/zorpos_upgrade/pgdump file.
www.balabit.com
12
Upgrading ZAS and ZCV
10. Upgrading ZAS and ZCV
The Zorp Content Vectoring Server (ZCV) and the Zorp Authentication Server (ZAS) are upgraded as part of the
Zorp upgrade.
When running on separate hosts from the Zorp Application Level Gateway, upgrading the ZCV and ZAS host is
identical to upgrading other Zorp hosts Procedure 8, Upgrading a host to Zorp 3.4 LTS (p. 9).
Warning
Content vectoring of the traffic and authentication of the users will not be possible during the upgrade. Perform the upgrade
during maintenance hours, or if that is not an option for you, modify your Zorp policies accordingly for the duration of the
upgrade.
11. Procedure – Upgrading Zorp clusters
Purpose:
To upgrade an existing Zorp cluster to version 3.4 LTS, complete the following steps. Before starting the following
procedure, read this entire section carefully.
Warning
After beginning upgrading the current slave host, the HA functionality will not be available until all nodes are upgraded.
Prerequisites:
The configuration of every Zorp component must be uploaded and active on the hosts of the cluster. Upload and
reload every configuration change from ZMC before starting the upgrade. Also, check the general prerequisites
described in Section 2, Prerequisites to upgrading to Zorp (p. 4).
Before starting to upgrade the cluster, upgrade your ZMS host as described in Procedure 6, Upgrading Zorp Management
Server to version 3.4 LTS (p. 7).
Steps:
Step 1. Upgrade the slave node of the cluster as described in Procedure 8, Upgrading a host to Zorp 3.4 LTS (p. 9).
Warning
When uploading the configuration from ZMC, upload the configuration only to the slave node.
Step 2. Initiate a takeover on the upgraded slave node, and test it for some time. To initiate a takeover, login to
the slave node, and issue the following command: /usr/lib/heartbeat/hb_takeover
www.balabit.com
13
Upgrading ZAS and ZCV
Step 3. If the upgraded slave node is stable under your usual traffic, upgrade the master node. If you encounter
any problems on the upgraded slave node, you can return the traffic to the master node that is running
Zorp 3.3 by issuing the /usr/lib/heartbeat/hb_standby command on the slave node, or issuing
the /usr/lib/heartbeat/hb_takeover command on the master node.
Step 4. Optional step: As of Zorp version 3.3, using resource scripts for the zorp services in not needed for firewall
clusters, as starting the zorp service is handled automatically. Note that if the Bind type option any dispatcher is set to DBSockAddr, you have to change it to DBIface.
12. Procedure – Migrating a 32-bit Zorp Management Server to a 64-bit operating system
Purpose:
To upgrade a ZMS host that is running on a 32-bit operating system to ZMS 3.4 LTS, complete the following steps.
Warning
It is not possible to convert a 32-bit ZMS to 64-bit, therefore the following procedure includes the complete reinstallation of
the ZMS host.
Steps:
Step 1. Create a backup of the ZMS configuration database, and save it to a host other than your ZMS host. If
you do not have a mechanism to automatically copy the ZMS backups to an external server, complete the
following steps:
Step a. Login to the ZMS host from a local console or using SSH as root.
Step b. Issue the following command to stop the ZMS engine: /etc/init.d/zms-engine
stop
Step c. Issue the following commands to create a backup: cd /var/lib/zms/; tar zcf
zms-backup.tar.gz *
Warning
Ensure that you do not overwrite the /var/lib/zms/configdb/zms_database.xml
file.
Step d. Copy the zms-backup.tar.gz file to an external host.
Step e. Issue the following command to start the ZMS engine: /etc/init.d/zms-engine
start
Warning
Hazard of data loss!
Every data stored on the ZMS host will be deleted during the upgrade, therefore it is essential to save the database
backup to a different host.
www.balabit.com
14
Upgrading ZAS and ZCV
Step 2. Install Zorp 3.4 LTS on the host. Make sure to select the Zorp Management Server role during the installation. For details about installing Zorp 3.4 LTS see The Zorp 3.4 LTS Installation Guide.
Step 3. Import the backup configuration to ZMS. Complete the following steps:
Step a. Copy the database backup archive file to the ZMS host.
Step b. As
root,
issue
the
/usr/share/zms/zms-restore.sh
<backup-file-to-restore> command.
Step c. Follow the on-screen instructions of the script.
Step d. Login to ZMS using ZMC. If you have reinstalled ZMS, use the username and password
you have provided during the reinstallation.
Step e. If the restored database has to be upgraded, ZMC displays a list of the components to be
upgraded. Click Convert.
Step f. Select PKI > Distribute Certificates. Note that key distribution will fail on every host
except on the ZMS host. This is normal.
Step g. Upload the configuration of the ZMS host.
Step h. Restart at least the Management Server component on the ZMS host. This will terminate
your ZMC session.
Step i. Relogin with ZMC and check your restored configuration.
Step j. Upload and restart any component as needed. You may also need to redistribute the certificates.
Step 4. Copy the database backup archive file to the ZMS host.
13. Procedure – Updating a host to the latest Zorp 3.3 version
Purpose:
Upgrading to Zorp 3.4 LTS is supported only from stock Zorp 3.3 or 3.3FR1 systems. The system must be up-todate, the upgrading process will automatically stop if not the latest Zorp 3.3 packages are installed on the host.
To update a Zorp host to the latest version of Zorp 3.3 of 3.3FR1, complete the following steps.
Steps:
Step 1. Login to the host as root from a local console or using SSH.
Step 2. Issue the following commands: apt-get update; apt-get -u dist-upgrade
The latest upgrades will be downloaded and installed. The result should state that there are no packages
on the system that have to be updated or modified (that is, the last line of the output should be something
like: 0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded). In order to
perform the upgrade to Zorp 3.4 LTS, any conflict or problem with the existing packages must be solved.
This includes packages that were excluded from previous updates (that is, their version was locked, or on
hold). The upgrade script automatically stops if it finds any packages that are on hold. Note that the above
apt command might occasionally state that a package is on hold (also called "kept back") even if there is
some other problem with a package.
Step 3. Optional step: To remove the hold flag from packages, complete the following steps:
www.balabit.com
15
Upgrading ZAS and ZCV
Step a. Issue the following command to find the packages on hold: dpkg --get-selections|
grep hold > packagesonhold.txt
Step b. Edit the packagesonhold.txt file (for example, using the joe packagesonhold.txt
command) and everywhere change "hold" to "install".
Step c. I s s u e
the
following
command
as
root:
dpkg
--set-selections<packagesonhold.txt
www.balabit.com
16