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 or a user with appropriate authorizations 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.

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

You can verify a zone prior to installing it. One of the checks performed is a check for sufficient disk size. If you skip this procedure, the verification is performed automatically when you install the zone.

You must be the global administrator or a user with appropriate authorizations in the global zone to perform this procedure.

1. Become root or assume an equivalent role.
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: /zones/my-zone does not exist, so it could not be verified.
       When 'zoneadm install' is run, 'install' will try to create
       /zones/my-zone, and 'verify' will be tried again,
       but the 'verify' may fail if:
       the parent directory of /zones/my-zone is group- or other-writable
       or
   
       /zones/my-zone overlaps with any other installed zones
       or
       /zones/my-zone is not a mountpoint for a zfs file system.

   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.

Verifying Zones on Shared Storage

For zones configured on shared storage, zonecfg verify verifies that none of the configured zpool resources are already online on the system, for a zone in the configured state.

For zones configured on shared storage, the zoneadm verify command confirms that all zpools configured as zpool and rootzpool resources are online on the system, for a zone in the installed state. If the resources are not available, the verify fails and information about the failed zpools is displayed.

How to Install a Configured Zone

This procedure is used to install a configured non-global zone. For information on installation options, see How Zones Are Installed.

The zone must reside on its own ZFS dataset. Only ZFS is supported. The zoneadm install command automatically creates a ZFS file system (dataset) for the zonepath when the zone is installed. If a ZFS dataset cannot be created, the zone is not installed.

You must be the global administrator or a user with appropriate authorizations in the global zone to perform this procedure.

1. Become root or assume an equivalent role.
2. Install the configured zone my-zone by using the zoneadm command with the install subcommand, automatically creating a ZFS dataset for the zonepath ZFS. Note that the parent directory of the zone path must also be a dataset, or the file system creation will fail.
   • Install the zone:

     global# zoneadm -z my-zone install

   • Install the zone from the repository:

     global# zoneadm -z my-zone install -m manifest -c [ profile | dir ]

   • Install the zone from an image:

     global# zoneadm -z my-zone install -a archive -s -u

   • Install the zone from a directory:

     global# zoneadm -z my-zone install -d path -p -v

   The system will display that a ZFS file system has been created for this zone.

   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 list -v
   # zoneadm list -cvd
     ID NAME             STATUS      PATH                      BRAND    IP
      0 global           running     /                         solaris  shared
      - my-zone          configured  /zones/my-zone            solaris  excl

   • 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

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

4. (Optional) If a storage object contains any preexisting partitions, zpools, or UFS file systems, the install fails and an error message is displayed.

   The source zone must be in the uninstalled state before the force subcommand can be used:

   zoneadm -z my-zone uninstall

   Then, continue the installation and overwrite any preexisting data by using the -x option to zoneadm install.

   -x force-zpool-import
   -x force-zpool-create=zpoolname
   -x force-zpool-create=zpoolname1,zpoolname2,zpoolname3
   -x force-zpool-create-all

   This option is similar to the zpool create -f command.

   -x force-zpool-create=zpoolname can be used one or more times.

5. 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      /                              solaris    shared
    -  my-zone  installed    /zones/my-zone                 solaris    excl  

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 minimal network configuration described in Chapter 7, Managing Services (Tasks), in Oracle Solaris Administration: Common Tasks by default. You can switch to the open network configuration, or enable or disable individual services, when you log in to the zone. See Enabling a Service for details.

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 -c -p options. The UUID is the fifth field of the display.

• View the UUIDs for zones that have been installed.

  global# zoneadm list -cp

  You will see a display similar to the following:

  0:global:running:/::solaris:shared:-:none
  
  6:my-zone:running:/zones/my-zone:61901255-35cf-40d6-d501-f37dc84eb504:solaris:excl:-:

Example 19-1 How to Use the Zone UUID in a Command

global# zoneadm -z my-zone -u 61901255-35cf-40d6-d501-f37dc84eb504:solaris:excl 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).

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 or a user with appropriate authorizations in the global zone to perform this procedure.

1. Become root or assume an equivalent role.
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      /                              solaris    shared
    -  my-zone  installed    /zones/my-zone                 solaris    excl  
    -  testzone incomplete   /zones/testzone                solaris    excl  

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.

(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 or a user with appropriate authorizations in the global zone to perform this procedure.

1. Become root or assume an equivalent role.
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      /                              solaris    shared
    1  my-zone  ready        /zones/my-zone                 solaris    excl  

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

How 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.

You must be the global administrator or a user with appropriate authorizations in the global zone to perform this procedure.

1. Become root or assume an equivalent role.
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      /                              solaris    shared
    1  my-zone  running      /zones/my-zone                 solaris    excl  

Example 19-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

How to Boot a Zone in Single-User Mode

You must be the global administrator or a user with appropriate authorizations in the global zone to perform this procedure.

1. Become root or assume an equivalent role.
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 20, Non-Global Zone Login (Overview) and Chapter 21, Logging In to Non-Global Zones (Tasks).