System Administration Guide: Virtualization Using the Solaris Operating System

Chapter 22 Moving and Migrating Non-Global Zones (Tasks)

This chapter describes how to:

If the new host has later versions of the zone-dependent packages or the associated patches, using zoneadm attach with the -u option updates those packages within the zone to match the new host. If the new host has a mixture of higher and lower version patches as compared to the source host, then an update during the attach operation is not allowed.

The -u option enables migration between machine classes, such as from sun4u to sun4v.

The -b option can be used to specify patches, either official or Interim Diagnostics/Relief (IDR), to be backed out of the zone before the update. Multiple -b options can be specified. If any of the patches cannot be backed out for any reason, then the attach will fail and none of the patches will be backed out.

This option only applies to zone brands using SVR4 packaging.

For information on moving and migrating lx branded zones, see Chapter 35, Moving and Migrating lx Branded Zones (Tasks).

Moving a Non-Global Zone

This procedure is used to move the zone to a new location on the same system by changing the zonepath. The zone must be halted. The new zonepath must be on a local file system. The normal zonepath criteria described in Resource and Property Types apply.

ProcedureHow to Move a Zone

You must be the global administrator in the global zone to perform this procedure.

  1. Become superuser, or assume the Primary Administrator role.

    To create the role and assign the role to a user, see Using the Solaris Management Tools With RBAC (Task Map) in System Administration Guide: Basic Administration.

  2. Halt the zone to be moved, db-zone in this procedure.


    global# zoneadm -z db-zone halt
    
  3. Use the zoneadm command with the move subcommand to move the zone to a new zonepath, /export/zones/db-zone.


    global# zoneadm -z db-zone move /export/zones/db-zone
    
  4. Verify the path.


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     -  my-zone  installed    /export/home/my-zone           native     shared
     -  db-zone  installed    /export/zones/db-zone          native     shared

Migrating a Non-Global Zone to a Different Machine

Note that you can do a trial run of a zone migration before you actually move the zone to a different machine. For more information, see About Validating a Zone Migration Before the Migration Is Performed.

About Migrating a Zone

The zonecfg and zoneadm commands can be used to migrate an existing non-global zone from one system to another. The zone is halted and detached from its current host. The zonepath is moved to the target host, where it is attached.

The following requirements apply to zone migration:

To verify the Solaris release and the machine architecture, type:


#uname -m

The zoneadm detach process creates the information necessary to attach the zone on a different system. The zoneadm attach process verifies that the target machine has the correct configuration to host the zone.

Because there are several ways to make the zonepath available on the new host, the actual movement of the zonepath from one system to another is a manual process that is performed by the global administrator.

When attached to the new system, the zone is in the installed state.

ProcedureHow to Migrate A Non-Global Zone

You must be the global administrator in the global zone to perform this procedure.

  1. Become superuser, or assume the Primary Administrator role.

    To create the role and assign the role to a user, see Using the Solaris Management Tools With RBAC (Task Map) in System Administration Guide: Basic Administration.

  2. Halt the zone to be migrated, my-zone in this procedure.


    host1# zoneadm -z my-zone halt
    
  3. Detach the zone.


    host1# zoneadm -z my-zone detach
    

    The detached zone is now in the configured state.

  4. Move the zonepath for my-zone to the new host.

    See How to Move the zonepath to a new Host for more information.

  5. On the new host, configure the zone.


    host2# zonecfg -z my-zone
    

    You will see the following system message:


    my-zone: No such zone configured
    Use 'create' to begin configuring a new zone.
  6. To create the zone my-zone on the new host, use the zonecfg command with the -a option and the zonepath on the new host.


    zonecfg:my-zone> create -a /export/zones/my-zone
    
  7. (Optional) View the configuration.


    zonecfg:my-zone> info
    zonename: my-zone
    zonepath: /export/zones/my-zone
    autoboot: false
    pool:
    inherit-pkg-dir:
             dir: /lib
    inherit-pkg-dir:
             dir: /platform
    inherit-pkg-dir:
             dir: /sbin
    inherit-pkg-dir:
             dir: /usr
    net:
             address: 192.168.0.90
             physical: bge0
  8. Make any required adjustments to the configuration.

    For example, the network physical device is different on the new host, or devices that are part of the configuration might have different names on the new host.


    zonecfg:my-zone> select net physical=bge0
    zonecfg:my-zone:net> set physical=e1000g0
    zonecfg:my-zone:net> end
    
  9. Commit the configuration and exit.


    zonecfg:my-zone> commit
    zonecfg:my-zone> exit
    
  10. Attach the zone on the new host using one of the following methods.

    • Attach the zone with a validation check.


      host2# zoneadm -z my-zone attach
      

      The system administrator is notified of required actions to be taken if either or both of the following conditions are present:

      • Required packages and patches are not present on the new machine.

      • The software levels are different between machines.

    • Attach the zone with a validation check and update the zone to match a host running later versions of the dependent packages or having a different machine class upon attach.


      host2# zoneadm -z my-zone attach -u
      

      Tip –

      If the source system is running an older version of the Solaris system, it might not generate a correct list of packages when the zone is detached. To ensure that the correct package list is generated on the destination, you can remove the SUNWdetached.xml file from the zonepath. Removing this file will cause a new package list to be generated by the destination system.


    • Also use the -b option to back out specified patches, either official or IDR, before the update.


      host2# zoneadm -z my-zone attach -u -b IDR246802-01 -b 123456-08
      

      Note that you can use the -b option independently of the -u option.

    • Force the attach operation without performing the validation.


      host2# zoneadm -z my-zone attach -F
      

      Caution – Caution –

      The -F option allows you to force the attach with no validation performed. This is useful in certain cases, such as in a clustered environment or for backup and restore operations, but it does require that the system be properly configured to host the zone. An incorrect configuration could result in undefined behavior later.


ProcedureHow to Move the zonepath to a new Host

There are many ways to create an archive of the zonepath. For example, you can use the cpio or pax commands described in the cpio(1)) and pax(1) man pages.

There are also several ways to transfer the archive to the new host. The mechanism used to transfer the zonepath from the source host to the destination depends on the local configuration. In some cases, such as a SAN, the zonepath data might not actually move. The SAN might simply be reconfigured so the zonepath is visible on the new host. In other cases, the zonepath might be written to tape, and the tape mailed to a new site.

For these reasons, this step is not automated. The system administrator must choose the most appropriate technique to move the zonepath to the new host.

  1. Become superuser, or assume the Primary Administrator role.

    To create the role and assign the role to a user, see Using the Solaris Management Tools With RBAC (Task Map) in System Administration Guide: Basic Administration.

  2. Move the zonepath to the new host. You can use the method described in this procedure, or use another method of your choice.


Example 22–1 Archiving and Moving the zonepath Using the tar Command

  1. Create a tar file of the zonepath on host1 and transfer it to host2 by using the sftp command.


    host1# cd /export/zones
    host1# tar cf my-zone.tar my-zone
    host1# sftp host2
    Connecting to host2...
    Password:
    sftp> cd /export/zones
    sftp> put my-zone.tar
    Uploading my-zone.tar to /export/zones/my-zone.tar
    sftp> quit
    
  2. On host2, unpack the tar file.


    host2# cd /export/zones
    host2# tar xf my-zone.tar
    

For more information, see sftp(1) and tar(1).


Troubleshooting

See Resolving Problems With a zoneadm attach Operation for troubleshooting information on the following:

Next Steps

If you have copied the data instead of reconfiguring a SAN, then the zonepath data will still be visible on the source host even though the zone is now in the configured state. You can either manually remove the zonepath from the source host after you have finished moving the data to the new host, or you can reattach the zone to the source host and use the zoneadm uninstall command to remove the zonepath.

About Validating a Zone Migration Before the Migration Is Performed

You can perform a trial run before the zone is moved to the new machine by using the “no execute” option,-n.

The zoneadm detach subcommand is used with the -n option to generate a manifest on a running zone without actually detaching the zone. The state of the zone on the originating system is not changed. The zone manifest is sent to stdout. The global administrator can direct this output to a file or pipe it to a remote command to be immediately validated on the target host. The zoneadm attach subcommand is used with the -n option to read this manifest and verify that the target machine has the correct configuration to host the zone without actually doing an attach.

The zone on the target system does not have to be configured on the new host before doing a trial-run attach.

ProcedureHow to Validate a Zone Migration Before the Migration Is Performed

You must be the global administrator in the global zone to perform this procedure.

  1. Become superuser, or assume the Primary Administrator role.

    To create the role and assign the role to a user, see Using the Solaris Management Tools With RBAC (Task Map) in System Administration Guide: Basic Administration.

  2. Use one of the following methods.

    • Generate the manifest on a source host named my-zone and pipe the output to a remote command that will immediately validate the target host:


      global# zoneadm -z my-zone detach -n | ssh remotehost zoneadm attach -n -
      

      The hyphen () at the end of the line specifies stdin for the path.

    • Generate the manifest on a source host named my-zone and direct the output to a file:


      global# zoneadm -z my-zone detach -n 
      

      Copy the manifest to the new host system as described in How to Move the zonepath to a new Host, and perform the validation:


      global# zoneadm attach -n path_to_manifest
      

      The path can be to specify stdin.

Migrating a Zone From a Machine That Is not Usable

A machine that hosts a native Solaris zone can become unusable. However, if the storage the zone lives on, such as a SAN, is still usable, it might still be possible to migrate the zone to a new host successfully. You can move the zonepath for the zone to the new host. In some cases, such as a SAN, the zonepath data might not actually move. The SAN might simply be re-configured so the zonepath is visible on the new host. Since the zone was not properly detached, you will have to first create the zone on the new host using the zonecfg command. Once this has been done, attach the zone on the new host. Although the new host will tell you the zone was not properly detached, the system will attempt the attach anyway.

The procedure for this task is described in steps 4 through 8 of How to Migrate A Non-Global Zone. Also see How to Move the zonepath to a new Host.