System Administration Guide: Oracle Solaris Containers-Resource Management and Oracle Solaris Zones

Chapter 20 Installing, Booting, Halting, Uninstalling, and Cloning Non-Global Zones (Tasks)

This chapter describes how to install and boot a non-global zone. A method for using cloning to install a zone on the same system is also provided. Other tasks associated with installation, such as halting, rebooting, and uninstalling zones, are also addressed. The procedure to completely delete a zone from a system is also provided.

For general information about zone installation and related operations, see Chapter 19, About Installing, Halting, Cloning, and Uninstalling Non-Global Zones (Overview).

For information about lx branded zone installation and cloning, see Chapter 34, About Installing, Booting, Halting, Cloning, and Uninstalling lx Branded Zones (Overview) and Chapter 35, Installing, Booting, Halting, Uninstalling and Cloning lx Branded Zones (Tasks).

Zone Installation (Task Map)

Task 

Description 

For Instructions 

(Optional) Verify a configured zone prior to installing the zone. 

Ensure that a zone meets the requirements for installation. If you skip this procedure, the verification is performed automatically when you install the zone. 

(Optional) How to Verify a Configured Zone Before It Is Installed

Install a configured zone. 

Install a zone that is in the configured state. 

How to Install a Configured Zone

Solaris 8/07: Obtain the universally unique identifier (UUID) for the zone. 

This separate identifier, assigned when the zone is installed, is an alternate way to identify a zone. 

Solaris 10 8/07: How to Obtain the UUID of an Installed Non-Global Zone

(Optional) Transition an installed zone to the ready state. 

You can skip this procedure if you want to boot the zone and use it immediately. 

(Optional) How to Transition the Installed Zone to the Ready State

Boot a zone. 

Booting a zone places the zone in the running state. A zone can be booted from the ready state or from the installed state. Note that you must perform the internal zone configuration when you log in to the zone after booting it for the first time. 

How to Boot a Zone, Internal Zone Configuration, Performing the Initial Internal Zone Configuration

Boot a zone in single-user mode. 

Boots only to milestone svc:/milestone/single-user:default. This milestone is equivalent to init level s. See the init(1M) and svc.startd(1M) man pages.

How to Boot a Zone in Single-User Mode

Installing and Booting Zones

Use the zoneadm command described in the zoneadm(1M) man page to perform installation tasks for a non-global zone. You must be the global administrator to perform the zone installation. The examples in this chapter use the zone name and zone path established in Configuring, Verifying, and Committing a Zone.

Procedure(Optional) How to Verify a Configured Zone Before It Is Installed

You can verify a zone prior to installing it. If you skip this procedure, the verification is performed automatically when you install the 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. Verify a configured zone named my-zone by using the -z option with the name of the zone and the verify subcommand.


    global# zoneadm -z my-zone verify
    

    This message regarding verification of the zone path will be displayed:


    Warning: /export/home/my-zone does not exist, so it cannot be verified.
    When 'zoneadm install' is run, 'install' will try to create
    /export/home1/my-zone, and 'verify' will be tried again,
    but the 'verify' may fail if:
    the parent directory of /export/home/my-zone is group- or other-writable
    or
    /export/home1/my-zone overlaps with any other installed zones.

    However, if an error message is displayed and the zone fails to verify, make the corrections specified in the message and try the command again.

    If no error messages are displayed, you can install the zone.

ProcedureHow to Install a Configured 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. Install the configured zone my-zone by using the zoneadm command with the -z install option.


    global# zoneadm -z my-zone install
    

    You will see various messages as the files and directories needed for the zone's root file system are installed under the zone's root path.

  3. (Optional) If an error message is displayed and the zone fails to install, type the following to get the zone state:


    global# zoneadm -z my-zone list -v
    
    • If the state is listed as configured, make the corrections specified in the message and try the zoneadm install command again.

    • If the state is listed as incomplete, first execute this command:


      global# zoneadm -z my-zone uninstall
      

      Then make the corrections specified in the message, and try the zoneadm install command again.

  4. When the installation completes, use the list subcommand with the -i and -v options to list the installed zones and verify the status.


    global# zoneadm list -iv
    

    You will see a display that is similar to the following:


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

If a zone installation is interrupted or fails, the zone is left in the incomplete state. Use uninstall -F to reset the zone to the configured state.

Next Steps

This zone was installed with the open network configuration described in Chapter 19, Managing Services (Tasks), in System Administration Guide: Basic Administration by default. You can switch to the open network configuration, or enable or disable individual services, when you log in to the zone. See Switching the Non-Global Zone to a Different Networking Service Configuration for details.

ProcedureSolaris 10 8/07: How to Obtain the UUID of an Installed Non-Global Zone

A universally unique identifier (UUID) is assigned to a zone when it is installed. The UUID can be obtained by using zoneadm with the list subcommand and the -p option. The UUID is the fifth field of the display.

  1. View the UUIDs for zones that have been installed.


    global# zoneadm list -p
    

    You will see a display similar to the following:


    0:global:running:/:
    6:my-zone:running:/export/home/my-zone:61901255-35cf-40d6-d501-f37dc84eb504

Example 20–1 How to Use the UUID in a Command


global# zoneadm -z my-zone -u 61901255-35cf-40d6-d501-f37dc84eb504 list -v

If both -u uuid-match and -z zonename are present, the match is done based on the UUID first. If a zone with the specified UUID is found, that zone is used, and the -z parameter is ignored. If no zone with the specified UUID is found, then the system searches by the zone name.


About the UUID

Zones can be uninstalled and reinstalled under the same name with different contents. Zones can also be renamed without the contents being changed. For these reasons, the UUID is a more reliable handle than the zone name.

See Also

For more information, see zoneadm(1M) and libuuid(3LIB).

ProcedureSolaris 10 8/07: How to Mark an Installed Non-Global Zone Incomplete

If administrative changes on the system have rendered a zone unusable or inconsistent, it is possible to change the state of an installed zone to incomplete.

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. Mark the zone testzone incomplete.


    global# zoneadm -z testzone mark incomplete
    
  3. Use the list subcommand with the -i and -v options to verify the status.


    global# zoneadm list -iv
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     -  my-zone  installed    /export/home/my-zone           native     shared
     -  testzone incomplete   /export/home/testzone          native     shared
Marking a Zone Incomplete

The -R root option can be used with the mark and list subcommands of zoneadm to specify an alternate boot environment. See zoneadm(1M) for more information.


Note –

Marking a zone incomplete is irreversible. The only action that can be taken on a zone marked incomplete is to uninstall the zone and return it to the configured state. See How to Uninstall a Zone.


Procedure(Optional) How to Transition the Installed Zone to the Ready State

Transitioning into the ready state prepares the virtual platform to begin running user processes. Zones in the ready state do not have any user processes executing in them.

You can skip this procedure if you want to boot the zone and use it immediately. The transition through the ready state is performed automatically when you boot the 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. Use the zoneadm command with the -z option, the name of the zone, which is my-zone, and the ready subcommand to transition the zone to the ready state.


    global# zoneadm -z my-zone ready
    
  3. At the prompt, use the zoneadm list command with the -v option to verify the status.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     1  my-zone  ready        /export/home/my-zone           native     shared

    Note that the unique zone ID 1 has been assigned by the system.

ProcedureHow to Boot a Zone

Booting a zone places the zone in the running state. A zone can be booted from the ready state or from the installed state. A zone in the installed state that is booted transparently transitions through the ready state to the running state. Zone login is allowed for zones in the running state.


Tip –

Note that you perform the internal zone configuration when you log in to the zone for the first time. This is described in Internal Zone Configuration.

If you plan to use an /etc/sysidcfg file to perform initial zone configuration, as described in How to Use an /etc/sysidcfg File to Perform the Initial Zone Configuration, create the sysidcfg file and place it the zone's /etc directory before you boot the 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. Use the zoneadm command with the -z option, the name of the zone, which is my-zone, and the boot subcommand to boot the zone.


    global# zoneadm -z my-zone boot
    
  3. When the boot completes, use the list subcommand with the -v option to verify the status.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


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

Example 20–2 Specifying Boot Arguments for Zones

Boot a zone using the -m verbose option:


global# zoneadm -z my-zone boot -- -m verbose

Reboot a zone using the -m verbose boot option:


global# zoneadm -z my-zone reboot -- -m verbose

Zone administrator reboot of the zone my-zone, using the -m verbose option:


my-zone# reboot -- -m verbose

Troubleshooting

If a message indicating that the system was unable to find the netmask to be used for the IP address specified in the zone's configuration displays, see netmasksWarning Displayed When Booting Zone. Note that the message is only a warning and the command has succeeded.

ProcedureHow to Boot a Zone in Single-User Mode

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. Boot the zone in single-user mode.


    global# zoneadm -z my-zone boot -s
    

Where to Go From Here

To log in to the zone and perform the initial internal configuration, see Chapter 21, Non-Global Zone Login (Overview) and Chapter 22, Logging In to Non-Global Zones (Tasks).

Halting, Rebooting, Uninstalling, Cloning, and Deleting Non-Global Zones (Task Map)

Task 

Description 

For Instructions 

Halt a zone. 

The halt procedure is used to remove both the application environment and the virtual platform for a zone. The procedure returns a zone in the ready state to the installed state. To cleanly shut down a zone, see How to Use zlogin to Shut Down a Zone.

How to Halt a Zone

Reboot a zone. 

The reboot procedure halts the zone and then boots it again. 

How to Reboot a Zone

Uninstall a zone. 

Removes all of the files in the zone's root file system. Use this procedure with caution. The action is irreversible.

How to Uninstall a Zone

Provision a new non-global zone based on the configuration of an existing zone on the same system. 

Cloning a zone is an alternate, faster method of installing a zone. You must still configure the new zone before you can install it. 

Solaris 10 11/06: Cloning a Non-Global Zone on the Same System

Delete a non-global zone from the system. 

This procedure completely removes a zone from a system. 

Deleting a Non-Global Zone From the System

Halting, Rebooting, and Uninstalling Zones

ProcedureHow to Halt a Zone

The halt procedure is used to remove both the application environment and the virtual platform for a zone. To cleanly shut down a zone, see How to Use zlogin to Shut Down 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. List the zones running on the system.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     1  my-zone  running      /export/home/my-zone           native     shared
  3. Use the zoneadm command with the -z option, the name of the zone, for example, my-zone, and the halt subcommand to halt the given zone.


    global# zoneadm -z my-zone halt
    
  4. List the zones on the system again, to verify that my-zone has been halted.


    global# zoneadm list -iv
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     -  my-zone  installed    /export/home/my-zone           native     shared
  5. Boot the zone if you want to restart it.


    global# zoneadm -z my-zone boot
    
Troubleshooting

If the halt operation fails, see Zone Does not Halt for troubleshooting tips.

ProcedureHow to Reboot 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. List the zones running on the system.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     1  my-zone  running      /export/home/my-zone           native     shared
  3. Use the zoneadm command with the -z reboot option to reboot the zone my-zone.


    global# zoneadm -z my-zone reboot
    
  4. List the zones on the system again to verify that my-zone has been rebooted.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


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

    Tip –

    Note that the zone ID for my-zone has changed. The zone ID generally changes after a reboot.


ProcedureHow to Uninstall a Zone


Caution – Caution –

Use this procedure with caution. The action of removing all of the files in the zone's root file system is irreversible.


The zone cannot be in the running state. The uninstall operation is invalid for running zones.

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. List the zones on the system.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     -  my-zone  installed    /export/home/my-zone           native     shared
  3. Use the zoneadm command with the -z uninstall option to remove the zone my-zone.

    You can also use the -F option to force the action. If this option is not specified, the system will prompt for confirmation.


    global# zoneadm -z my-zone uninstall -F
    
  4. List the zones on the system again, to verify that my-zone is no longer listed.


    global# zoneadm list -v
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
Troubleshooting

If a zone uninstall is interrupted, the zone is left in the incomplete state. Use the zoneadm uninstall command to reset the zone to the configured state.

Use the uninstall command with caution because the action is irreversible.

Solaris 10 11/06: Cloning a Non-Global Zone on the Same System

Cloning is used to provision a new zone on a system by copying the data from a source zonepath to a target zonepath.

Starting with Solaris 10 5/09, when the source zonepath and the target zonepath both reside on ZFS and are in the same pool, the zoneadm clone command automatically uses ZFS to clone the zone. However, you can specify that the ZFS zonepath be copied and not ZFS cloned.

ProcedureHow to Clone a Zone

You must configure the new zone before you can install it. The parameter passed to the zoneadm create subcommand is the name of the zone to clone. This source zone must be halted.

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 source zone to be cloned, which is my-zone in this procedure.


    global# zoneadm -z my-zone halt
    
  3. Start configuring the new zone by exporting the configuration of the source zone my-zone to a file, for example, master.


    global# zonecfg -z my-zone export -f /export/zones/master
    

    Note –

    You can also create the new zone configuration using the procedure How to Configure the Zone instead of modifying an existing configuration. If you use this method, skip ahead to Step 6 after you create the zone.


  4. Edit the file master. Set different properties and resources for the components that cannot be identical for different zones. For example, you must set a new zonepath. For a shared-IP zone, the IP addresses in any net resources must be changed. For an exclusive-IP zone, the physical property of any net resources must be changed.

  5. Create the new zone, zone1, by using the commands in the file master.


    global# zonecfg -z zone1 -f /export/zones/master
    
  6. Install the new zone, zone1, by cloning my-zone.


    global# zoneadm -z zone1 clone my-zone
    

    The system displays:


    Cloning zonepath /export/home/my-zone...

    Starting with Solaris 10 5/09, if the source zonepath is on a ZFS pool, for example, zeepool, the system displays:


    Cloning snapshot zeepool/zones/my-zone@SUNWzone1
    Instead of copying, a ZFS clone has been created for this zone.
  7. List the zones on the system.


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     -  my-zone  installed    /export/home/my-zone           native     shared
     -  zone1    installed    /export/home/zone1             native     shared
Solaris 10 5/09: When a Source zonepath on a ZFS File System Is Cloned

When the zoneadm command clones a source zonepath that is on its own ZFS file system, the following actions are performed:

ProcedureSolaris 10 5/09: How to Clone a Zone from an Existing Snapshot

You can clone a source zone multiple times from an existing snapshot that was originally taken when you cloned 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. Configure the zone zone2.

  3. Specify that an existing snapshot be used to create new-zone2.


    global# zoneadm -z zone2 clone -s zeepool/zones/my-zone@SUNWzone1 my-zone
    

    The system displays:


    Cloning snapshot zeepool/zones/my-zone@SUNWzone1

    The zoneadm command validates the software from the snapshot SUNWzone1, and clones the snapshot.

  4. List the zones on the system.


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared
     -  my-zone  installed    /zeepool/zones/my-zone         native     shared
     -  zone1    installed    /zeepool/zones/zone1           native     shared
     -  zone2    installed    /zeepool/zones/zone2           native     shared

ProcedureSolaris 10 5/09: How to Use Copy Instead of ZFS Clone

Use this procedure to prevent the automatic cloning of a zone on a ZFS file system by specifying that the zonepath should be copied instead.

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. Specify that the zonepath on ZFS be copied and not ZFS cloned.


    global# zoneadm -z zone1 clone -m copy my-zone
    

Deleting a Non-Global Zone From the System

The procedure described in this section completely deletes a zone from a system.

ProcedureHow to Remove a Non-Global Zone

  1. Shut down the zone my-zone.


    global# zlogin my-zone shutdown -y -g0 -i0
    
  2. Remove the root file system for my-zone.


    global# zoneadm -z my-zone uninstall -F
    
  3. Delete the configuration for my-zone.


    global# zonecfg -z my-zone delete -F
    
  4. List the zones on the system, to verify that my-zone is no longer listed.


    global# zoneadm list -iv
    

    You will see a display that is similar to the following:


    ID  NAME     STATUS       PATH                           BRAND      IP
     0  global   running      /                              native     shared