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

Chapter 35 Installing, Booting, Halting, Uninstalling and Cloning lx Branded Zones (Tasks)

This chapter describes how to install and boot an lx branded zone. The following other tasks are also addressed:

lx Branded Zone Installation (Task Map)

Task 

Description 

For Instructions 

Obtain the Linux achives. 

Before you can install the lx branded zone, you must first obtain the Linux archives.

How to Obtain the Linux Archives

Install a configured lx branded zone.

Install a zone that is in the configured state. 

How to Install an lx Branded Zone

(Optional) Install a subset of the available packages. 

When installing from CD or ISO images, you can install a subset of the packages on the install media. 

How to Install a Subset of the Packages

(Optional) Enable networking in the zone. 

Networking is disabled by default and must be enabled if you want this functionality. 

How to Enable Networking in an lx Branded Zone

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. 

How to Obtain the UUID of an Installed Branded 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) Placing an Installed lxBranded Zone in the Ready State

Boot an lx branded 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.  

How to Boot an lx Branded Zone

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 lx Branded Zones

Use the zoneadm command described in the zoneadm(1M) man page to perform installation tasks for a non-global zone.

ProcedureHow to Obtain the Linux Archives

Before you can install the lx branded zone, you must first obtain the Linux archives. The archives are distributed in the following forms:

  1. Obtain the Linux distribution using one of the following methods:

ProcedureHow to Install an lx Branded Zone

This procedure is used to install a configured lx branded zone. Once the zone is installed, all software configuration and management has to be done by the zone administrator using Linux tools from inside the zone.

See Example 35–1, Example 35–2, and Example 35–3 for examples of zone installation command lines using the different distribution paths. If you install from discs or from an ISO image, you must specify Sun package cluster categories. See lx Branded Zone Installation Methods for information on package cluster categories.

Note that you can verify a zone prior to installing it. If you skip this procedure, the verification is performed automatically when you install the zone. The procedure is documented in (Optional) How to Verify a Configured Zone Before It Is Installed.

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


Note –

In Step 3, if the zonepath is on ZFS, the zoneadm install command automatically creates a ZFS file system (dataset) for the zonepath when the zone is installed. You can block this action by including the -x nodataset parameter.


  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. (Optional) If you intend to install from DVD or CD, enable volfs on your system and verify that it is running.


    global# svcadm enable svc:/system/filesystem/volfs:default
    

    global# svcs | grep volfs
    

    You will see a display similar to the following:


    online  17:30 svc:/system/filesystem/volfs:default
  3. Install the configured zone lx-zone by using the zoneadm command with the install option and the path to the archive.

    • Install the zone, automatically creating a ZFS file system if the zonepath is on ZFS.


      global# zoneadm -z lx-zone install -d archive_path
      

      The system will display:


      A ZFS file system has been created for this zone.
    • Install the zone that has a zonepath on ZFS, but do not automatically create the ZFS file system.


      global# zoneadm -z lx-zone install -x nodataset -d archive_path
      

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


    Note –

    If you do not specify archive_path, the default is CD.


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


    global# zoneadm -z lx-zone list -iv
    
    • 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 lx-zone uninstall
      

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

  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      /                              native     shared
     -  lx-zone  installed    /export/home/lx-zone           lx         shared

Example 35–1 Install Command Using a CentOS Compressed tar Archive


global# zoneadm -z lx-zone install -d /export/centos_fs_image.tar.bz2


Example 35–2 Install Command Using CentOS CDs

For CD or DVD installation, volfs must be enabled on your system. You must specify a software cluster package. For example, use development to install a full environment, or type the names of particular clusters. If you do not specify a cluster package, desktop is installed by default. The CD device is /cdrom/cdrom0.


global# zoneadm -z lx-zone install -d /cdrom/cdrom0 development


Example 35–3 Install Command Using CentOS ISO Images

You must specify a software cluster package. Use development to install a full environment, or specify particular clusters. If you do not specify a cluster package, desktop is installed by default. The CentOS ISO images reside in the directory /export/centos_3.7.


global# zoneadm -z lx-zone install -d /export/centos_3.7 development

See Also

For more information on datasets, see Oracle Solaris ZFS Administration Guide

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.

ProcedureHow to Install a Subset of the Packages

When installing from CD or ISO images, you can install a subset of the packages on the install media. The available subsets are core, server, desktop, developer, and all.

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 only the server package:


    global# zoneadm -z lx-zone install -d archive_path server
    

ProcedureHow to Enable Networking in an lx Branded Zone

When you install an lx branded zone, networking is disabled. Use a procedure such as this one to enable networking.

You must be the zone administrator to perform this procedure.

  1. Edit the /etc/sysconfig/network file in the zone.


    NETWORKING=yes
    HOSTNAME=your.hostname
  2. To set up a NIS domain, add a line similar to the following:


    NISDOMAIN=domain.Sun.COM
Configuring Networking and Naming Services

For more information on configuring networking or naming services, consult the documentation for your Linux distribution.

ProcedureHow to Obtain the UUID of an Installed Branded 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:/::native
        1:centos38:running:/zones/centos38:27fabdc8-d8ce-e8aa-9921-ad1ea23ab063:lx

Example 35–4 How to Use the UUID in a Command


global# zoneadm -z lx-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).

ProcedureHow to Mark an Installed lx Branded 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
    -   testzone   incomplete    /export/home/testzone   lx         shared
Marking a Zone Incomplete

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 Branded Zone.


(Optional) Placing an Installed lxBranded Zone in 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.

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

ProcedureHow to Boot an lx Branded 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 in the global zone to perform this procedure.


Tip –

Note that you cannot boot a branded zone on a Trusted Solaris system that has labels enabled.


  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 lx-zone, and the boot subcommand to boot the zone.


    global# zoneadm -z lx-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  lx-zone  running      /export/home/lx-zone  lx         shared

Example 35–5 Specifying Boot Arguments for Zones

Boot a zone using the -i altinit option:


global# zoneadm -z lx-zone boot -- -i /path/to/process

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 an lx Branded 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 lx-zone boot -- -s
    

Where to Go From Here

To log in to the zone, see configuration, see Logging In to an lx Branded Zone.

Halting, Rebooting, Uninstalling, Cloning, and Deleting lx Branded 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 an lx Branded Zone.

How to Halt an lx Branded Zone

Reboot a zone. 

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

How to Reboot an lx Branded Zone

Uninstall a zone. 

This procedure 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 Branded 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. 

Cloning an lx Branded Zone on the Same System

Delete a non-global zone from the system. 

This procedure completely removes a zone from a system. 

Deleting an lx Branded Zone From the System

Halting, Rebooting, and Uninstalling lx Branded Zones

ProcedureHow to Halt an lx Branded Zone

The halt procedure is used to remove both the application environment and the virtual platform for an lx branded zone. To cleanly shut down a zone, see How to Use zlogin to Shut Down an lx Branded 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  lx-zone  running      /export/home/lx-zone  lx         shared
  3. Use the zoneadm command with the -z option, the name of the zone, for example, lx-zone, and the halt subcommand to halt the given zone.


    global# zoneadm -z lx-zone halt
    
  4. List the zones on the system again, to verify that lx-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
    -  lx-zone    installed     /export/home/lx-zone  lx         shared
  5. Boot the zone if you want to restart it.


    global# zoneadm -z lx-zone boot
    
Troubleshooting

If the zone does not halt properly, see Zone Does not Halt for troubleshooting tips.

ProcedureHow to Reboot an lx Branded 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  lx-zone  running      /export/home/lx-zone  lx         shared
  3. Use the zoneadm command with the -z reboot option to reboot the zone lx-zone.


    global# zoneadm -z lx-zone reboot
    
  4. List the zones on the system again to verify that lx-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  lx-zone  running      /export/home/lx-zone  lx         shared

    Tip –

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


ProcedureHow to Uninstall a Branded Zone


Caution – Caution –

This procedure removes all of the files in the zone's root file system. The action 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
    -  lx-zone    installed     /export/home/lx-zone  lx         shared
  3. Use the zoneadm command with the -z uninstall option to remove the zone lx-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 lx-zone uninstall -F
    

    Note that when you uninstall a zone that has its own ZFS file system for the zonepath, the ZFS file system is destroyed.

  4. List the zones on the system again, to verify that lx-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.

Cloning an lx Branded 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.

ProcedureHow to Clone an lx Branded 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 lx-zone in this procedure.


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


    global# zonecfg -z lx-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. At a minimum, you must set a different zonepath and IP address for the new zone.

  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 lx-zone.


    global# zoneadm -z zone1 clone lx-zone
    

    The system displays:


    Cloning zonepath /export/home/lx-zone...
  7. List the zones on the system.


    global# zoneadm list -iv
      ID  NAME          STATUS          PATH                   BRAND      IP
       0  global        running         /                      native     shared
       -  lx-zone       installed       /export/home/lx-zone   lx         shared
       -  zone1         installed       /export/home/zone1     lx         shared          

ProcedureHow 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/lx-zone@SUNWzone1 lx-zone
    

    The system displays:


    Cloning snapshot zeepool/zones/lx-zone@SUNWzone1

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

  4. List the zones on the system.


    global# zoneadm list -iv
      ID NAME             STATUS         PATH                    BRAND      IP
       0 global           running        /                       native     shared
       - lx-zone          installed      /zeepool/zones/lx-zone  lx         shared
       - zone1            installed      /zeepool/zones/zone1    lx         shared
       - zone2            installed      /zeepool/zones/zone1    lx         shared

ProcedureHow 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 lx-zone
    

Deleting an lx Branded Zone From the System

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

ProcedureHow to Remove an lx Branded Zone

  1. Shut down the zone lx-zone.


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


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


    global# zonecfg -z lx-zone delete -F
    
  4. List the zones on the system, to verify that lx-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