Virtual Server Appliance User manual (Version 3.0.0)  

A System and data disk migration

These migration notes cover the configuration and the files that can be administered with HELIOS tools, e.g. HELIOS Configuration Assistant and HELIOS Admin.

This chapter describes the migration from a VSA 1.0/​2.0 to a VSA 3.0.


If the customer has changed other configuration or files, it is their responsibility to migrate these from VSA 1.0/​2.0 to 3.0.

A.1 Migration overview


The configuration migration from VSA 1.0/​2.0 to 3.0 should be performed upon the initial deployment of the new VSA. It is best to migrate user and group configurations before any new users/​groups are added, to avoid conflicts when the VSA 1.0/​2.0 user/​group IDs are migrated.

A.2 Migrate the system and data disks

Back up system and data disks

Make sure to back up your VSA 1.0/​2.0 system and data disks prior to the migration. After successful migration, non-system data can be restored from a backup, e.g. “/home” directories and spool or volume directories.

If you still have user home directories on “rootvg”, consider transferring them to “datavg” prior to the migration. The same applies to volumes and spool queues still being on “rootvg”.

Profiles & settings

In case you have added files or directories to the following HELIOS volumes, or modified them there, copy these files to an AFP or SMB HELIOS client for later migration to VSA 3.0.

At this point the HELIOS services must be running so that clients can access these volumes:

Stop HELIOS services

It is recommended that you list and record the ownership and permissions of the files you are copying so that these can be set correctly when migrating to VSA 3.0.


Now stop the HELIOS services to prevent any changes during the migration process:

# cd /usr/local/helios
# bin/stop-helios now
Choose migration storage location for configuration files

Choose one of the logical volumes of “datavg” to back up the configuration. The mount point (path) for that volume can be ascertained via the Configuration Assistant menu Storage setup > List logical volumes.

We assume that the logical volume “data” from the volume group “datavg” was mounted at “/data”.

Save configuration information to the subdirectory

Then create a subdirectory “vsa1-migration” and use this as the location to back up all configuration files from your VSA 1.0/​2.0 installation.


Write down the entry of this “datavg” from your “/etc/fstab”, to use for later mounting that migration volume on the new VSA 3.0, e.g.:

/dev/mapper/datavg-data	/data  btrfs  defaults	0 2

Write down all settings from the following configuration menus:

  • General setup

    • Set keyboard layout

    • Set time and time zone

  • Network setup

    • Show network summary


Back up the HELIOS configuration files from the directories:

  • HELIOSDIR/var/conf

  • HELIOSDIR/var/spool

  • HELIOSDIR/var/run/WebShare_User_Settings

  • HELIOSDIR/public/WebShare/.Proof-Profiles

“var/spool” mostly contains configuration information but it is also the parent directory of the default “hold” and “error” queues.

If these default directories, or additional “real” spool directories in this location, are still in use it would be best to remove unneeded spooled jobs from these queues to minimize the amount of data to be migrated.


To collect the configuration information from these directories, change into the HELIOS installation directory and run the following “htar” command line (using the path to your “migration” directory):

# cd /usr/local/helios
# bin/htar -czvf /data/vsa1-migration/helios-var.tgz \
  var/conf var/spool var/run/WebShare_User_Settings \

Verify the output of “htar” that the files could be collected without errors.

In case there is not yet a “WebShare_User_Settings” or “.Proof-Profiles” directory, you can ignore the warning:

> htar: Warning: Cannot archive ...: 
> No such file or directory 

Copy the files “passwd”, “group”, “shadow” and “fstab” from the “/etc” directory to “/​data/​vsa1-migration”, e.g.:

# cd /etc
# cp -p passwd group shadow fstab /data/vsa1-migration
Shut down VSA 1.0/​2.0 and detach VSA 1.0/​2.0 data disks

Shut down the VSA 1.0/​2.0 Linux system.


In your VM administration detach the VSA 1.0/​2.0 data disks.

Deploy new VSA 3.0

Deploy the new VSA 3.0 as a separate VM using your VM administration program.

If the data disk images (most likely VMDK or VHD) are stored with the VSA 1.0/​2.0 VM, e.g. in the same folder (which is the default for most hypervisors), move the images to the new VSA 3.0 VM folder.

Attach data disks to VSA 3.0 and boot system

In your VM administration attach the data disks to the VSA 3.0 and boot it.


If additional HELIOS services were installed in VSA 1.0/​2.0 install the identical products on VSA 3.0.


On VSA 3.0 mount the logical volume where the migration configuration is stored, e.g.:

# mkdir /data
# mount /dev/mapper/datavg-data /data

Now you have access to the “/data/vsa1-migration” directory.

Add “fstab” entries from VSA 1.0/​2.0

Add the missing “fstab” entries to “/etc/fstab” on VSA 3.0.

The file system layout for the system disks of VSA 1.0/​2.0 and 3.0 is the same.

Therefore you must not change or add the “/”, “/boot”, or “swap” partitions (and, if you still have user home directories on “rootvg”, also “/home”). Make sure that you DO NOT change the VSA 3.0 file system entries for “rootvg”.

These are either listed as “/dev/mapper/rootvg-<name>” entries, e.g.:

/dev/mapper/rootvg-system /  ext4  errors=remount-ro  0  1

or with an “UUID” prefix, e.g.:

UUID=a6c70175-56bf-49af-8fe5-578aa3264459 /boot  ext4  defaults  0  2

The removable media entries must also be left as-is, e.g. cdrom, floppy, etc.

In the initial VSA 3.0 “/etc/fstab” file you will not have any additional “/dev/​mapper” entries.

Here you simply add to “/etc/fstab” the entries from your saved “fstab” which are either:


Make sure that all mount points exist and then issue:

# mount -a

Verify that all of your file systems are available, e.g.:

# df -k
Restore configuration

Re-setup your configuration in the “Network setup” and “General setup” configuration menus according to the notes you took down before the migration.


Restore the HELIOS configuration files inside the “var” subdirectory.

Make sure to issue “stop-helios” first and after the restoration “start-helios -i”, e.g.:

# cd /usr/local/helios
# bin/stop-helios now
# umask 0
# bin/htar -xzvf /data/vsa1-migration/helios-var.tgz
# bin/start-helios -i

This will ensure that the configuration and the environment that the HELIOS services require are properly set-up.


Restore HELIOS spool or volume directories which resided on the VSA 1.0/​2.0 system disk.


Restore added or changed files to the HELIOS volumes “ICC-Profiles”, and “Settings”.

Take over HELIOS users and groups from VSA 1.0/​2.0 to VSA 3.0

To get a list of user and group names to migrate to VSA 3.0, use the HELIOS “passwd” file in “HELIOSDIR/var” (which was just restored from VSA 1.0/​2.0) to identify which user and group names need to be transferred to VSA 3.0.

Apart from system user “root”, it should only contain “real” HELIOS users. For each of the names in the HELIOS “passwd” file, you can use the “grep” command on the “passwd” and “shadow” files of the VSA 1.0/​2.0, to get the lines to add to the “passwd” and “shadow” files of the VSA 3.0.

Before adding VSA 1.0/​2.0 users and groups to the VSA 3.0 “passwd”, “shadow”, and “group” files, it must be verified that certain fields will still contain unique values after the items have been added.


Before adding a line to a certain file, verify that the values in certain fields are not already used (duplicate).

For “passwd” these are the fields:

For “shadow” this is the field:

For “group” these are the fields:

For example, if you have an example user “John Q. Public”, listed in “/etc/passwd” of VSA 1.0/​2.0 with the following line:

johnp:x:8110:8010:John Q Public:/usr/johnp:/bin/sh

you may append this line to “/etc/passwd” of VSA 3.0, provided that it does not contain entries in field:


Apply the same procedure to the file “shadow”.

If there is a conflict, you need to change this field's value of the entry you wish to append. Make sure that the new value also does not conflict.

If the value in the “ID” field does clash, write down the new user or group ID you issued. You will need to adjust files/​folders with this user/​group ID on your file system to the new ID you issued.

To collect the group names from your VSA 1.0/​2.0 “group” file, to which migrated users belong, you can use the “grep” command and redirect it to a temporary file, e.g.:

# cd /data/vsa1-migration
# grep johnp group >> group.migrate

After all migrated user names were processed make the lines in “group.migrate” unique, for example:

# sort < group.migrate | uniq > group.migrate.uniq

Now “group.migrate.uniq” is a sorted list of unique group entries from VSA 1.0/​2.0, which can be compared against the “/etc/group” file from VSA 3.0. Lines can be appended, or group entries extended, as needed on VSA 3.0.

Again, make sure that group name and ID are unique before adding a line to “/etc/group”.

If other user or group names from VSA 1.0/​2.0 should be taken over too, apply the safeguards described above.


Especially do not change VSA 3.0 system users or groups.

HELIOS Website © 2019 HELIOS Software GmbH  
HELIOS Manuals November 19, 2020