Migration from SUSE Manager 2.1 to SUSE Manager 3

The migration from SUSE Manager 2.1 to SUSE Manager 3 works quite the same as a migration from Red Hat Satellite to SUSE Manager. There is NO in-place migration! The migration happens from the original machine to a new one. While this has the drawback that you temporarily need two machines, it also has the advantage that the original machine will remain fully functional in case something goes wrong.

The whole process may be tricky, so it is strongly advised that the migration is done by an experienced consultant. Given the complexity of the product, the migration is an "all-or-nothing", this means if something goes wrong you will need to start all over. Error handling is very limited. Nevertheless it should work more or less out of the box if all the steps are carefully executed as documented.

Please note that the migration involves dumping the whole database on the source machine and restoring it on the target machine. This is a very time-consuming process! Also all of the channels and packages need to be copied to the new machine, so expect the whole migration to take several hours!

Prerequisites

The source machine needs to run SUSE Manager 2.1 with all the latest updates applied! Before trying to migrate, please make sure that the machine is up to date and all updates are installed!

Only machines running with the embedded postgresql database may be migrated. For the migration of an Oracle based installation, a two-step migration is required: First the installation needs to get migrated from Oracle to postgresql (by means of a separate tool) and afterwards the migration to SUSE Manager 3 can be performed as documented here.

For the special case of migrating a SUSE Manager server with external Oracle database to SUSE Manager 3 with external Oracle database, please also read this section.

As SUSE Manager 3 does no longer support NCC but only SCC, you can migrate a machine only after it has been switched to SCC. The migration script will check if the installation has already been switched to SCC and will terminate if this is not the case. Switch to SCC on the source machine and repeat the migration.

During migration the database from the source machine needs to get dumped and this dump needs to be temporarily stored on the target system. The dump gets compressed with gzip using the default compression options (maximum compression only yields about 10% of space savings but costs a lot of runtime); so check the disk usage of the database with du -sch /var/lib/pgsql/data and ensure that you have at least 30% of this value available in /var/spacewalk/tmp.

These values from a test migration might help illustrate the space requirements:

This is a small test installation; for bigger installations the ratio might be better (space required for the database dump might be less than 30%).

The dump will be written to the directory /var/spacewalk/tmp, the directory will be created if it does not exist yet. If you want the dump to be stored somewhere else, change the definition of the variable $TMPDIR on the beginning of the script to suit your needs.

Setting up the target machine

After the target system has been installed with SLE12SP1 and the add-on product "SUSE Manager", just run yast2 susemanager_setup as you would do for a normal installation of SUSE Manager.

On the first screen, make sure to check Migrate a SUSE Manager compatible server instead of Set up SUSE Manager from scratch.

On the second screen, enter the name of the source system as Hostname of source SUSE Manager Server as well as the domain name. Also enter the database credentials of the source system.

On the next screen, you will need to specify the IP address of the target system. Normally this value should be pre-set to the correct value and you only should need to press ENTER. Only in the case of multiple IP addresses you might need to specify the one that should be used during migration. Please note that during the migration process, the target system will fake its host name to the one of the source system, because the host name of a SUSE Manager installation is very vital and should be used from the very beginning. So do not get confused when logging in to the systems during migration; they both will present you with the same hostname!

The next screens are the same as for a regular installation: Just specify the database parameters (using the same ones as on the source system is recommended) and your SCC credentials.

After all the data has been gathered, YaST2 will terminate. The actual migration will NOT start automatically but needs to be triggered manually!

Performing the migration

The actual migration is performed by giving the command /usr/lib/susemanager/bin/mgr-setup -m. This will read the data gathered in the previous step, set up SUSE Manager on the new machine and transfer all of the data from the source machine. As it needs to perform several operations on the source machine via ssh, you will be prompted once for the root password of the source machine. A temporary ssh key named "migration-key" is created and installed on the source machine, so you need to give the root password only once. Of course the temporary ssh key will be deleted after successful migration.

Ideally, this is all you will need to do. Depending on the size of the installation, the actual migration will take up to several hours. Once finished, you will be prompted to shutdown the source machine, re-configure the network of the target machine to use the same IP address and host name as the original machine and restart it. It should now be a fully functional replacement for your previous 2.1 installation.

The following numbers illustrate the runtime for dumping and importing the database:

So dumping the database took about five minutes and importing the dump on the target system took about seven minutes. For big installations this can take up to several hours. Additionally account for the time it takes to copy all the package data to the new machine. Depending on your network infrastructure and hardware, this can also take significant time.

Speeding up the migration

Since a lot of data needs to be copied the whole migration can consume a lot of time. The actual migration can be sped up by doing one of the most time consuming task prior to the actual migration: The copying of all the channels, packages, autoinstall images and so on. So the following approach is recommended: Once you gathered all the data via YaST2, run the following command:

mgr-setup -r

This will copy the lion's share of the data from the old server to the new one. This command can be run at any time; the current server remains fully functional during this task. Once the actual migration is started, only the data changed since running above command needs to be transferred which significantly will reduce the downtime.

On huge installations, the transfer of the database (which involves dumping of the database on the source machine and importing the dump on the target system) still can take quite some time. This is unavoidable as we only can dump the whole database. Of course during this time no write operations may happen, therefore the migration script needs to shutdown the SUSE Manager services on the source machine.

Packages on external storage

Some installations might store the package data on external storage (eg. NFS mount on /var/spacewalk/packages). In such a case it is of course pointless to have all this data copied to the new machine. Just edit the script /usr/lib/susemanager/bin/mgr-setup and remove the respective rsync command (around line 345). Make sure to have the storage mounted on the new machine before the first start of the system!

Analogue handling for /srv/www/htdocs/pub if appropriate.

Broken UI after migration

Chances are you will notice a broken user interface after migration. This is not a bug, but a browser caching issue. The new machine has the same hostname and the same IP address as the old machine which can confuse some web browsers. If you are experiencing this issue, just do a forced reload of the page (in Firefox this is accomplished by pressing the key combination ctrl-F5) and everything will be fine.