Migrating an OpenIndiana zone from one system to another

The procedure for migrating an OpenSolaris Zone on a ZFS file system is not adequately documented anywhere in Oracle’s documentation set (which makes a bunch of assumptions about how the systems involved are configured), nor could I find a clearly written blog or guide anywhere on how to do this seemingly simple and straightforward task.

In this post, we are going to migrate a zone from one OpenIndiana oi_148 x86 machine (“Machine 1”) to another running the same build (“Machine 2”). Both systems are configured with a ZFS root filesystem. I’m assuming some prior basic familiarity with creating, installing, and booting zones.

Our example zone is called afterburnerzone-2. It has its zonepath on the source machine at /rpool/zones/zone_roots/afterburnerzone-2.


On Machine 1:

Prepare the zone for migration on the source system

First, halt the zone, then run the detach command:

# zoneadm -z afterburnerzone-2 halt
# zoneadm -z afterburnerzone-2 detach

This creates an XML file in the zone’s zonepath (named SUNWdetached.xml) containing its configuration properties – these properties (physical network interface, IP address and so forth) can be modified later using the zonecfg utility when the zone is attached on the target system.


Make ZFS snapshots of the zone’s filesystems

Recursively snapshot the ZFS filesystems relevant to our zone:

# zfs snapshot -r rpool/zones/zone_roots/afterburnerzone-2@snap1

This create snapshots of the zone’s filesystems, which in this example are:


We can see this in the output of zfs list -t snapshot:

# zfs list -t snapshot
NAME                                                                               USED  AVAIL  REFER  MOUNTPOINT
rpool/zones/zone_roots/afterburnerzone-2@snap1                                        0      -  34.5K  -
rpool/zones/zone_roots/afterburnerzone-2/ROOT@snap1                                   0      -    31K  -
rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe@snap1                               0      -  3.72G  -


Create archives of the snapshots in preparation for sending to the target system

The zfs send command is used to archive a ZFS dataset. We’re going to archive all three snapshots of our detached zone to separate files (these will eventually be restored on the target system):

# zfs send rpool/zones/zone_roots/afterburnerzone-2@snap1 > /export/home/davek/afterburnerzone2.snap1
# zfs send rpool/zones/zone_roots/afterburnerzone-2/ROOT@snap1 > /export/home/davek/afterburnerzone2_root.snap1
# zfs send rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe@snap1 > /export/home/davek/afterburnerzone2_root_zbe.snap1


Copy the archives to the target system

Self explanatory – in my case I simply scp the .snap files to the target system, but copying them via a USB flash drive or whatever will work fine too.


The next steps are all performed on the target system.


On Machine 2:

Import the zone on the target system

We are assuming that our zones are being stored at /rpool/zones/zone_roots on the target system, i.e. the same relative location as on our source system. Before proceeding, make sure that the rpool/zones and rpool/zones/zone_roots ZFS file systems exist – if not, you’ll need to manually create them, e.g.:

# zfs create rpool/zones
# zfs create rpool/zones/zone_roots


Restore the ZFS snapshot archives

Let’s assume we have coped the archives into a user’s home directory at /export/home/davek on the target system. We now use the zfs receive command to the restore the ZFS snapshot archives into the ZFS filesystems specified (which will be created when each command is run):

# zfs receive rpool/zones/zone_roots/afterburnerzone-2 < /export/home/davek/afterburnerzone2.snap1
# zfs receive rpool/zones/zone_roots/afterburnerzone-2/ROOT < /export/home/davek/afterburnerzone2_root.snap1
# zfs receive rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe < /export/home/davek/afterburnerzone2_root_zbe.snap1 

Run zfs list to verify the snapshots have been restored to the correct location:

# zfs list
NAME                                                USED  AVAIL  REFER  MOUNTPOINT
rpool/zones                                        3.72G   213G    32K  /rpool/zones
rpool/zones/zone_roots                             3.72G   213G    32K  /rpool/zones/zone_roots
rpool/zones/zone_roots/afterburnerzone-2           3.72G   213G  35.5K  /rpool/zones/zone_roots/afterburnerzone-2
rpool/zones/zone_roots/afterburnerzone-2/ROOT      3.72G   213G    32K  /rpool/zones/zone_roots/afterburnerzone-2/ROOT
rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe  3.72G   213G  3.72G  /rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe


Change the mountpoint property for ZFS filesystems to legacy

We do this for the following restored filesystems only:


# zfs set mountpoint=legacy rpool/zones/zone_roots/afterburnerzone-2/ROOT
# zfs set mountpoint=legacy rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe


Mount one ZFS filesystem using a legacy mount procedure

We do this for the following filesystem only:


We want to mount it to /rpool/zones/zone_roots/afterburnerzone-2/root:

# mount -F zfs rpool/zones/zone_roots/afterburnerzone-2/ROOT/zbe /rpool/zones/zone_roots/afterburnerzone-2/root


Configure the zone

Using the zonecfg command, we are going to recreate the afterburnerzone-2 zone’s configuration on the target system using the configuration file generated when it was detached.

First, configure the afterburnerzone-2 zone:

# zonecfg -z afterburnerzone-2
afterburnerzone-2: No such zone configured
Use 'create' to begin configuring a new zone.

Note the prompt to create a new zone – we will do this, but point to the XML file migrated across with the zone for our settings:

zonecfg:afterburnerzone-2> create -a /rpool/zones/zone_roots/afterburnerzone-2

If this is successful, you won’t see any confirmation in the positive, only an error if the preexisting zone configuration file cannot be found. By running the info command here, one can check the zone settings and they should match what was originally set on the source machine:

zonename: afterburnerzone-2
zonepath: /rpool/zones/zone_roots/afterburnerzone-2
brand: ipkg
autoboot: true
ip-type: shared
        allowed-address not specified
        physical: rge1
        defrouter not specified

The remaining configuration using zonecfg in this particular example involves checking the zone’s physical network interface and IP address and changing if necessary, for example, if the physical network interfaces are different on the target machine (which in this example are):

zonecfg:afterburnerzone-2> select net physical=rge0
zonecfg:afterburnerzone-2:net> set physical=bge1
zonecfg:afterburnerzone-2:net> set address=
zonecfg:afterburnerzone-2:net> end
zonecfg:afterburnerzone-2> info
zonecfg:afterburnerzone-2> commit
zonecfg:afterburnerzone-2> exit


Attach the zone

Finally, let’s attach the zone to the system:

# zoneadm -z afterburnerzone-2 attach
Log File: /var/tmp/afterburnerzone-2.attach_log.lRayVj

preferred global publisher: openindiana.org
       Global zone version: entire@0.5.11,5.11-0.148:20101125T013212Z
                     Cache: Using /var/pkg/download.
  Updating non-global zone: Output follows
               Packages to install:    16
           Create boot environment:    No
                Evaluation: Packages in zone afterburnerzone-2 are out of sync with the global zone. To proceed, retry with the -u flag.
                    Result: Attach Failed.

Okay – so let’s try again, this time using the -u flag as instructed:

# zoneadm -z afterburnerzone-2 attach -u
Log File: /var/tmp/afterburnerzone-2.attach_log.eWaWok

preferred global publisher: openindiana.org
       Global zone version: entire@0.5.11,5.11-0.148:20101125T013212Z
                     Cache: Using /var/pkg/download.
  Updating non-global zone: Output follows
               Packages to install:    16
           Create boot environment:    No
PHASE                                        ACTIONS
Install Phase                                485/485 

PHASE                                          ITEMS
Package State Update Phase                     16/16 
Image State Update Phase                         2/2 
No updates necessary for this image.
  Updating non-global zone: Zone updated.
                    Result: Attach Succeeded.


Done! We can now proceed to boot and log in to the zone.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s