System Administration Guide: Virtualization Using the Solaris Operating System
  Search only this book
Download this book in PDF (3140 KB)

Part III Branded Zones

BrandZ provides the framework to create non-global branded zones that contain non-native operating environments. Branded zones are used on the Solaris Operating System to run applications. The first brand available is the lx brand, Solaris Containers for Linux Applications. The lx brand provides a Linux environment for your applications and runs on x86 and x64 machines.

Chapter 29 About Branded Zones and the Linux Branded Zone

The branded zones facility in the SolarisTM Operating System is a simple extension of Solaris Zones. This chapter discusses the branded zones concept and the lx brand, which implements Linux branded zones functionality. Linux branded zones are also known as Solaris Containers for Linux Applications.


Note –

Although you can configure and install branded zones on a Trusted SolarisTM system that has labels enabled, you cannot boot branded zones on this system configuration.


About Using Zones on a Solaris System

See Chapter 16, Introduction to Solaris Zones for general information on the use of zones on a Solaris system.

You should be familiar with the following zones and resource management concepts:

The Glossary provides definitions for terms used with zones and resource management features.

Any additional information required to use branded zones on your system is provided in this part of the guide.


Note –

The following chapters in this guide are not applicable to branded zones:


Branded Zones Technology

The Solaris Zones infrastructure is documented in this manual in Part II, Zones. By default, a non-global zone has the same characteristics as operating system in the global zone, which is running the Solaris 10 Operating System or later Solaris 10 release. These native non-global zones and the global zone share their conformance to standards, runtime behavior, command sets, and performance traits in common. The branded zone (BrandZ) framework extends the zones infrastructure to include the creation of brands, or alternative sets of runtime behaviors. The term brand can refer to a wide range of operating environments. For example, the non-global zone can emulate another version of the Solaris Operating System, or an operating environment such as Linux. Or, it might augment the native brand behaviors with additional characteristics or features. Every zone is configured with an associated brand.

A brand can provide a simple or a complex environment. For example, a simple environment could replace the standard Solaris utilities with their GNU equivalents. A complex environment could provide a complete Linux user space which supports the execution of Linux applications.

The brand defines the operating environment that can be installed in the zone and determines how the system will behave within the zone so that the non-native software installed in the zone functions correctly. In addition, a zone's brand is used to identify the correct application type at application launch time. All branded zone management is performed through extensions to the native zones structure. Most administration procedures are identical for all zones.

You can change the brand of a zone in the configured state. Once a branded zone has been installed, the brand cannot be changed or removed.

BrandZ extends the zones tools in the following ways:

  • The zonecfg command is used to set a zone's brand type when the zone is configured.

  • The zoneadm command is used to report a zone's brand type as well as administer the zone.


Note –

You can change the brand of a zone in the configured state. Once a branded zone has been installed, that brand cannot be changed or removed.


Processes Running in a Branded Zone

Branded zones provide a set of interposition points in the kernel that are only applied to processes executing in a branded zone.

  • These points are found in such paths as the syscall path, the process loading path, and the thread creation path.

  • At each of these points, a brand can choose to supplement or replace the standard Solaris behavior.

A brand can also provide a plug-in library for librtld_db. The plug-in library allows Solaris tools such as the debugger, described in mdb(1), and DTrace, described in dtrace(1M), to access the symbol information of processes running inside a branded zone.

Branded Zone Device Support

The devices supported by each zone are documented in the man pages and other documentation for that brand. Device support is defined by the brand. A brand can choose to disallow the addition of any unsupported or unrecognized devices.

Branded Zone File System Support

The file systems required for a branded zone are defined by the brand.

Privileges in a Branded Zone

The privileges available in a branded zone are defined by the brand. For more information about privileges, see Privileges in a Non-Global Zone and Configurable Privileges in an lx Branded Zone.

About the lx Brand

The lx brand uses the branded zones framework to enable Linux binary applications to run unmodified on a machine with a Solaris Operating System kernel.

The machine must have one of the following supported i686 processor types:

  • Intel

    • Pentium Pro

    • Pentium II

    • Pentium III

    • Celeron

    • Xeon

    • Pentium 4

    • Pentium M

    • Pentium D

    • Pentium Extreme Edition

    • Core

    • Core 2

    AMD

    • Opteron

    • Athlon XP

    • Athlon 64

    • Athlon 64 X2

    • Athlon FX

    • Duron

    • Sempron

    • Turion 64

    • Turion 64 X2

Supported Linux Distributions

The lx brand includes the tools necessary to install a CentOS 3.x or Red Hat Enterprise Linux 3.x distribution inside a non-global zone. Versions 3.5 to 3.8 of each distribution are supported. The brand supports the execution of 32-bit Linux applications on x86 and x64 machines running the Solaris system in either 32-bit or 64-bit mode.

The lx brand emulates the system call interfaces provided by the Linux 2.4.21 kernel, as modified by Red Hat in the RHEL 3.x distributions. This kernel provides the system call interfaces consumed by the glibc version 2.3.2 released by Red Hat.

In addition, the lx brand partially emulates the Linux /dev and /proc interfaces.


Caution – Caution –

Note that you must maintain a supported configuration if you add packages to an lx branded zone. See About Maintaining a Supported Configuration for more information.


Application Support

The Solaris system imposes no limit on the number of Linux applications you can run in an lx branded zone. Sufficient memory must be available. Also see System and Space Requirements.

Regardless of the underlying kernel, only 32-bit Linux applications are able to run.

The lx zone supports only user-level Linux applications. You cannot use Linux device drivers, Linux kernel modules, or Linux file systems from inside an lx zone.

See http://opensolaris.org/os/community/brandz/applications for a list of some applications that have been successfully run under the lx brand. See How to Install an Application in an lx Branded Zone for an example of installing an application.

You cannot run Solaris applications inside an lx zone. However, the lx zone enables you to use the Solaris system to develop, test, and deploy Linux applications. For example, you can place a Linux application in an lx zone and analyze it using Solaris tools run from the global zone. You can then make improvements and deploy the tuned application on a native Linux system.

Debugging Tools

Solaris debugging tools such as DTrace and mdb can be applied to Linux processes executing inside the zone, but the tools themselves must be running in the global zone. Any core files generated are produced in the Solaris format and can only be debugged with Solaris tools.

DTrace is enabled for Linux applications by the DTrace lxsyscall dynamic tracing provider. The provider acts like the DTrace syscall provider. The lxsyscall provider provides probes that fire whenever a thread enters or returns from a Linux system call entry point.

For more information on debugging options, see the Solaris Dynamic Tracing Guide, and the dtrace(1M) and mdb(1) man pages. The Solaris Dynamic Tracing Guide describes the public documented interfaces available for the DTrace facility. The documentation about the syscall provider can be used for the lxsyscall provider.


Note –

Because NFS is dependent on name services, which are zone specific, you cannot access any NFS file system that is mounted outside of the current zone. Thus, you cannot debug NFS-based Linux processes from the global zone.


Commands and Other Interfaces

The commands identified in the following table provide the primary administrative interface to the zones facility.

Table 29–1 Commands and Other Interfaces Used With lx Branded Zones

Command Reference 

Description 

zlogin(1)

Log in to a non-global zone 

zoneadm(1M)

Administers zones on a system 

zonecfg(1M)

Used to set up a zone configuration 

getzoneid(3C)

Used to map between zone ID and name 

brands(5)

Provides description of branded zones facility 

lx(5)

Provides description of Linux branded zones 

zones(5)

Provides description of zones facility 

lx_systrace(7D)

DTrace Linux system call tracing provider 

zcons(7D)

Zone console device driver 

The zoneadmd daemon is the primary process for managing the zone's virtual platform. The man page for the zoneadmd daemon is zoneadmd(1M). The daemon does not constitute a programming interface.


Note –

Table 26–5 covers commands that can be used in the global zone to display information about all non-global zones, including branded zones. Table 26–4 covers commands used with the resource capping daemon.


Setting Up lx Branded Zones on Your System (Task Map)

The following table provides an overview of the tasks that are involved in setting up lx zones on your system for the first time.

Task 

Description 

For Instructions 

Identify each 32–bit Linux application that you would like to run in a zone. 

Assess the system needs of the application. 

Refer to your business goals and to your system documentation if necessary. 

Determine how many zones to configure. 

Assess: 

  • The number of Linux applications you intend to run.

  • The disk space requirements for Linux branded zones.

  • Whether you need to use a script.

See Application Support, System and Space Requirements, Evaluating the Current System Setup, Script to Configure Multiple lx Branded Zones.

Determine whether you will use resource pools with your zone to create a container. 

If you are using resource pools, configure the pools before you configure zones. 

Note that you can add zone-wide resource controls and pool functionality to a zone quickly by using zonecfg properties.

See How to Configure the lx Branded Zone, Chapter 13, Creating and Administering Resource Pools (Tasks).

Perform the preconfiguration tasks. 

Determine the zone name and the zone path for each zone. If network connectivity is required, obtain IP addresses. Determine the scheduling class for the zone. Determine the set of privileges that processes inside the zone should be limited to, if the standard default set is not sufficient. 

For information on the zone name, zone path, IP addresses, and scheduling class, see lx Branded Zone Configuration Components. For a listing of default privileges and privileges that can be configured in a non-global zone, see Privileges in a Non-Global Zone.

For information on resource pool association, see How Zones Work and How to Configure the lx Branded Zone.

Develop configurations. 

Configure non-global zones. 

See Configuring, Verifying, and Committing a Zone and the zonecfg(1M) man page.

As global administrator, verify and install configured zones. 

Zones must be verified and installed prior to booting the zone. You must obtain a Linux distribution before you install a Linux branded zone. 

See Chapter 32, About Installing, Booting, Halting, Cloning, and Uninstalling lx Branded Zones (Overview) and Chapter 33, Installing, Booting, Halting, Uninstalling and Cloning lx Branded Zones (Tasks).

As global administrator, boot the non-global zones. 

Boot each zone to place the zone in the running state. 

See Chapter 33, Installing, Booting, Halting, Uninstalling and Cloning lx Branded Zones (Tasks).

Prepare the new zone for production use. 

Create user accounts, add additional software, and customize the zone's configuration using standard Linux system administration tools and methodologies from within the zone. 

Refer to the documentation you use to set up a newly installed machine and install applications. Special considerations applicable to a system with zones installed are covered in this guide. 

Chapter 30 Planning the lx Branded Zone Configuration (Overview)

This chapter describes what you need to do before you can configure an lx branded zone on your x64 or x86 based system. This chapter also describes how to use the zonecfg command.

System and Space Requirements

The following primary machine considerations are associated with the use of lx branded zones.

  • The machine must be either x64 or x86 based.

  • Sufficient disk space to hold the files that are unique within each lx zone must be available. The disk space requirements for an lx zone are determined by the size and number of RPMs, or Linux packages, that are installed.

  • The lx brand supports only the whole root model, so each installed zone will have its own copy of every file.

There are no limits on how much disk space can be consumed by a zone. The global administrator is responsible for space restriction. The global administrator must ensure that local storage is sufficient to hold a non-global zone's root file system. Given sufficient storage, even a small uniprocessor system can support a number of zones running simultaneously.

Restricting the Size of the Branded Zone

The following options can be used to restrict zone size:

  • You can place the zone on a lofi-mounted partition. This action will limit the amount of space consumed by the zone to that of the file used by lofi. For more information, see the lofiadm(1M) and lofi(7D) man pages.

  • You can use soft partitions to divide disk slices or logical volumes into partitions. You can use these partitions as zone roots, and thus limit per-zone disk consumption. The soft partition limit is 8192 partitions. For more information, see Chapter 12, Soft Partitions (Overview), in Solaris Volume Manager Administration Guide.

  • You can use the standard partitions of a disk for zone roots, and thus limit per-zone disk consumption.

Branded Zone Network Address

Each zone that requires network connectivity has one or more unique IP addresses. IPv4 addresses are supported. You must assign an IPv4 address for the zone. For more information, see Branded Zone Network Address.

lx Branded Zone Configuration Process

The zonecfg command is used to:

  • Set the brand for the zone

  • Create the configuration for the lx zone

  • Verify the configuration to determine whether the specified resources and properties are legal and internally consistent on a hypothetical x86 or x64 based system

  • Perform a brand-specific verification. The verification ensures the following:

    • The zone cannot have any inherited package directories, ZFS datasets, or added devices.

    • If the zone is configured to use audio, the specified devices (if any) must be none, default, or a single digit.

The check performed by the zonecfg verify command for a given configuration verifies the following:

  • Ensures that a zone path is specified

  • Ensures that all of the required properties for each resource are specified

  • Ensures that brand requirements are met

For more information about the zonecfg command, see the zonecfg(1M) man page.

lx Branded Zone Configuration Components

This section covers the following components:

  • Zone resources and properties that can be configured using the zonecfg command

  • Resources included in the configuration by default

Zone Name and Zone Path in an lx Branded Zone

You must choose a name and a path for your zone.

Zone Autoboot in an lx Branded Zone

The autoboot property setting determines whether the zone is automatically booted when the global zone is booted.

Resource Pool Association in an lx Branded Zone

If you have configured resource pools on your system as described in Chapter 13, Creating and Administering Resource Pools (Tasks), you can use the pool property to associate the zone with one of the resource pools when you configure the zone.

If you do not have resource pools configured, you can still specify that a subset of the system's processors be dedicated to a non-global zone while it is running by using the dedicated-cpu resource. The system will dynamically create a temporary pool for use while the zone is running.


Note –

A zone configuration using a persistent pool set through the pool property is incompatible with a temporary pool configured through the dedicated-cpu resource. You can set only one of these two properties.


Specifying the dedicated-cpu Resource

The dedicated-cpu resource specifies that a subset of the system's processors should be dedicated to a non-global zone while it is running. When the zone boots, the system will dynamically create a temporary pool for use while the zone is running.

Note that with specification in zonecfg, pool settings propagate during migrations.

The dedicated-cpu resource sets limits for ncpus, and optionally, importance.

ncpus

Specify the number of CPUs or specify a range, such as 2–4 CPUs. If you specify a range because you want dynamic resource pool behavior, also do the following:

importance

If you are using a CPU range to achieve dynamic behavior, also set the importance property, The importance property, which is optional, defines the relative importance of the pool. This property is only needed when you specify a range for ncpus and are using dynamic resource pools managed by poold. If poold is not running, then importance is ignored. If poold is running and importance is not set, importance defaults to 1. For more information, see pool.importance Property Constraint.


Caution – Caution –

The cpu-shares rctl and the dedicated-cpu resource are incompatible.


Specifying the capped-cpu Resource

The capped-cpu resource provides an absolute limit on the amount of CPU resources that can be consumed by a project or a zone. The capped-cpu resource has a single ncpus property that is a positive decimal with two digits to the right of the decimal. This property corresponds to units of CPUs. The resource does not accept a range. The resource does accept a decimal number. When specifying ncpus, a value of 1 means 100 percent of a CPU. A value of 1.25 means 125 percent, because 100 percent corresponds to one full CPU on the system.


Note –

The capped-cpu resource and the dedicated-cpu resource are incompatible.


Scheduling Class in a Zone

You can use the fair share scheduler (FSS) to control the allocation of available CPU resources among zones, based on the importance of the workloads in the zone. This importance is expressed by the number of shares of CPU resources that you assign to each zone. Even if you are not using FSS to manage CPU resource allocation between zones, you can set the zone's scheduling-class to use FSS so that you can set shares on projects within the zone.

When you explicitly set the cpu-shares property, the fair share scheduler (FSS) will be used as the scheduling class for that zone. However, the preferred way to use FSS in this case is to set FSS to be the system default scheduling class with the dispadmin command. That way, all zones will benefit from getting a fair share of the system CPU resources. If cpu-shares is not set for a zone, the zone will use the system default scheduling class. The following actions set the scheduling class for a zone:

  • You can use the scheduling-class property in zonecfg to set the scheduling class for the zone.

  • You can set the scheduling class for a zone through the resource pools facility. If the zone is associated with a pool that has its pool.scheduler property set to a valid scheduling class, then processes running in the zone run in that scheduling class by default. See Introduction to Resource Pools and How to Associate a Pool With a Scheduling Class.

  • If the cpu-shares rctl is set and FSS has not been set as the scheduling class for the zone through another action, zoneadmd sets the scheduling class to FSS when the zone boots.

  • If the scheduling class is not set through any other action, the zone inherits the system default scheduling class.

Note that you can use the priocntl described in the priocntl(1) man page to move running processes into a different scheduling class without changing the default scheduling class and rebooting.

capped-memory Resource

The capped-memory resource sets limits for physical, swap, and locked memory. Each limit is optional, but at least one must be set.

  • Determine values for this resource if you plan to cap memory for the zone by using rcapd from the global zone. The physical property of the capped-memory resource is used by rcapd as the max-rss value for the zone.

  • The swap property of the capped-memory resource is the preferred way to set the zone.max-swap resource control.

  • The locked property of the capped-memory resource is the preferred way to set the zone.max-locked-memory resource control.

For more information, see Chapter 10, Physical Memory Control Using the Resource Capping Daemon (Overview), Chapter 11, Administering the Resource Capping Daemon (Tasks), and How to Configure the lx Branded Zone.

Zone Network Interfaces in an lx Branded Zone

Only the shared-IP network configuration is supported in an lx branded zone.

Each zone that requires network connectivity must have one or more dedicated IP addresses. These addresses are associated with logical network interfaces. Network interfaces configured by the zonecfg command will automatically be set up and placed in the zone when it is booted.

Mounted File Systems in an lx Branded Zone

Generally, the file systems mounted in a zone include the following:

  • The set of file systems mounted when the virtual platform is initialized

  • The set of file systems mounted from within the zone itself

This can include, for example, the following file systems:

  • automount-triggered mounts

  • Mounts explicitly performed by a zone administrator

Certain restrictions are placed on mounts performed from within the application environment. These restrictions prevent the zone administrator from denying service to the rest of the system, or otherwise negatively impacting other zones.

There are security restrictions associated with mounting certain file systems from within a zone. Other file systems exhibit special behavior when mounted in a zone. See File Systems and Non-Global Zones for more information.

Zone-Wide Resource Controls in an lx Branded Zone

The preferred, simpler method for setting a zone-wide resource control is to use the property name instead of the rctl resource. These limits are specified for both the global and non-global zones.

The global administrator can also set privileged zone-wide resource controls for a zone by using the rctl resource.

Zone-wide resource controls limit the total resource usage of all process entities within a zone. These limits are specified for both the global and non-global zones by using the zonecfg command. For instructions, see How to Configure the lx Branded Zone.

The following resource controls are currently available:

Table 30–1 Zone-Wide Resource Controls

Control Name 

Global Property Name 

Description 

Default Unit 

Value Used For 

zone.cpu-cap

 

Absolute limit on the amount of CPU resources for this zone. A value of 100 means 100 percent of one CPU as the project.cpu-cap setting. A value of 125 is 125 percent, because 100 percent corresponds to one full CPU on the system when using CPU caps.

Quantity (number of CPUs) 

 

zone.cpu-shares

cpu-shares

Number of fair share scheduler (FSS) CPU shares for this zone. 

Quantity (shares) 

 

zone.max-locked-memory.

Total amount of physical locked memory available to a zone. 

If the privilege priv_proc_lock_memory is assigned to a zone, consider setting this resource control as well, to prevent that zone from locking all memory.

Size (bytes) 

locked property of capped-memory

zone.max-lwps

max-lwps

Maximum number of LWPs simultaneously available to this zone. 

Quantity (LWPs) 

 

zone.max-msg-ids

max-msg-ids

Maximum number of message queue IDs allowed for this zone. 

Quantity (message queue IDs) 

 

zone.max-sem-ids

max-sem-ids

Maximum number of semaphore IDs allowed for this zone. 

Quantity (semaphore IDs) 

 

zone.max-shm-ids

max-shm-ids

Maximum number of shared memory IDs allowed for this zone. 

Quantity (shared memory IDs) 

 

zone.max-shm-memory

max-shm-memory

Total amount of System V shared memory allowed for this zone. 

Size (bytes) 

 

zone.max-swap

Total amount of swap that can be consumed by user process address space mappings and tmpfs mounts for this zone.

Size (bytes) 

swap property of capped-memory

Configurable Privileges in an lx Branded Zone

The limitpriv property is used to specify a privilege mask other than the predefined default set. When a zone is booted, a default set of privileges is included in the brand configuration. These privileges are considered safe because they prevent a privileged process in the zone from affecting processes in other non-global zones on the system or in the global zone. You can use the limitpriv property to do the following:

  • Add to the default set of privileges, understanding that such changes might allow processes in one zone to affect processes in other zones by being able to control a global resource.

  • Remove from the default set of privileges, understanding that such changes might prevent some processes from operating correctly if they require those privileges to run.


Note –

There are a few privileges that cannot be removed from the zone's default privilege set, and there are also a few privileges that cannot be added to the set at this time.


For more information, see Privileges Defined in lx Branded Zones, Privileges in a Non-Global Zone and privileges(5).

attr Resource in an lx Branded Zone

You can use the attr resource type to enable access to an audio device present in the global zone. For instructions, see Step 12 of How to Configure, Verify, and Commit the lx Branded Zone.

You can also add a comment for a zone by using the attr resource type.

Resources Included in the Configuration by Default

Configured Devices in lx Branded Zones

The devices supported by each zone are documented in the man pages and other documentation for that brand. The lx zone does not allow the addition of any unsupported or unrecognized devices. The framework detects any attempt to add an unsupported device. An error message is issued that indicates the zone configuration cannot be verified.

Note that access to an audio device running in the global zone can be added through the attr resource property as shown in Step 12 of How to Configure, Verify, and Commit the lx Branded Zone.

File Systems Defined in lx Branded Zones

The file systems that are required for a branded zone are defined in the brand. You can add additional Solaris file systems to an lx branded zone by using the fs resource property as shown in Step 9 of How to Configure, Verify, and Commit the lx Branded Zone.


Note –

Adding local Linux file systems is not supported. You can NFS mount file systems from a Linux server.


Privileges Defined in lx Branded Zones

Processes are restricted to a subset of privileges. Privilege restriction prevents a zone from performing operations that might affect other zones. The set of privileges limits the capabilities of privileged users within the zone.

Default, required default, optional, and prohibited privileges are defined by each brand. You can also add or remove certain privileges by using the limitpriv property as shown in Step 8 of How to Configure, Verify, and Commit the lx Branded Zone. The table Table 26–1 lists all of the Solaris privileges and the status of each privilege with respect to zones.

For more information about privileges, see the ppriv(1) man page and System Administration Guide: Security Services.

Using the zonecfg Command to Create an lx Branded Zone

The zonecfg command, which is described in the zonecfg(1M) man page, is used to configure a zone.

The zonecfg command can also be used to persistently specify the resource management settings for the global zone. For example, you can use the command to configure the global zone to use a dedicated CPU by using the dedicated-cpu resource.

The zonecfg command can be used in interactive mode, in command-line mode, or in command-file mode. The following operations can be performed using this command:

  • Create or delete (destroy) a zone configuration

  • Add resources to a particular configuration

  • Set properties for resources added to a configuration

  • Remove resources from a particular configuration

  • Query or verify a configuration

  • Commit to a configuration

  • Revert to a previous configuration

  • Rename a zone

  • Exit from a zonecfg session

The zonecfg prompt is of the following form:


zonecfg:zonename>

When you are configuring a specific resource type, such as a file system, that resource type is also included in the prompt:


zonecfg:zonename:fs>

For more information, including procedures that show how to use the various zonecfg components described in this chapter, see How to Configure the lx Branded Zone.

zonecfg Modes

The concept of a scope is used for the user interface. The scope can be either global or resource specific. The default scope is global.

In the global scope, the add subcommand and the select subcommand are used to select a specific resource. The scope then changes to that resource type.

  • For the add subcommand, the end or cancel subcommands are used to complete the resource specification.

  • For the select subcommand, the end or cancel subcommands are used to complete the resource modification.

The scope then reverts back to global.

Certain subcommands, such as add, remove, and set, have different semantics in each scope.

zonecfg Interactive Mode

In interactive mode, the following subcommands are supported. For detailed information about semantics and options used with the subcommands, see the zonecfg(1M) man page for options. For any subcommand that could result in destructive actions or loss of work, the system requests user confirmation before proceeding. You can use the -F (force) option to bypass this confirmation.

help

Print general help, or display help about a given resource.


zonecfg:lx-zone:net> help
create

Begin configuring an in-memory configuration for the specified new branded zone.

  • With the -t template option, to create a configuration that is identical to the specified template. The zone name is changed from the template name to the new zone name. To create a Linux branded zone, use:


    zonecfg:lx-zone> create -t SUNWlx
    
  • With the -b option, to create a blank configuration for which you can set the brand.


    zonecfg:lx-zone> create -b
    zonecfg:lx-zone> set brand=lx
    
  • With the -F option, to overwrite an existing configuration.

export

Print the configuration to standard output, or to the output file specified, in a form that can be used in a command file.

add

In the global scope, add the specified resource type to the configuration.

In the resource scope, add a property of the given name with the given value.

See How to Configure the lx Branded Zone and the zonecfg(1M) man page for more information.

set

Set a given property name to the given property value. Note that some properties, such as zonepath, are global, while others are resource specific. Thus, this command is applicable in both the global and resource scopes.

select

Applicable only in the global scope. Select the resource of the given type that matches the given property name-property value pair criteria for modification. The scope is changed to that resource type. You must specify a sufficient number of property name-value pairs for the resource to be uniquely identified.

clear

Clear the value for optional settings. Required settings cannot be cleared. However, some required settings can be changed by assigning a new value.

remove

In the global scope, remove the specified resource type. You must specify a sufficient number of property name-value pairs for the resource type to be uniquely identified. If no property name-value pairs are specified, all instances will be removed. If more than one exists, a confirmation is required unless the -F option is used.

In the resource scope, remove the specified property name-property value from the current resource.

end

Applicable only in the resource scope. End the resource specification.

The zonecfg command then verifies that the current resource is fully specified.

  • If the resource is fully specified, it is added to the in-memory configuration and the scope will revert back to global.

  • If the specification is incomplete, the system displays an error message that describes what needs to be done.

cancel

Applicable only in the resource scope. End the resource specification and reset the scope to global. Any partially specified resources are not retained.

delete

Destroy the specified configuration. Delete the configuration both from memory and from stable storage. You must use the -F (force) option with delete.


Caution – Caution –

This action is instantaneous. No commit is required, and a deleted zone cannot be reverted.


info

Display information about the current configuration or the global resource properties zonepath, autoboot, and pool. If a resource type is specified, display information only about resources of that type. In the resource scope, this subcommand applies only to the resource being added or modified.

verify

Verify current configuration for correctness. Ensure that all resources have all of their required properties specified.

commit

Commit current configuration from memory to stable storage. Until the in-memory configuration is committed, changes can be removed with the revert subcommand. A configuration must be committed to be used by zoneadm. This operation is attempted automatically when you complete a zonecfg session. Because only a correct configuration can be committed, the commit operation automatically does a verify.

revert

Revert configuration back to the last committed state.

exit

Exit the zonecfg session. You can use the -F (force) option with exit.

A commit is automatically attempted if needed. Note that an EOF character can also be used to exit the session.

zonecfg Command-File Mode

In command-file mode, input is taken from a file. The export subcommand described in zonecfg Interactive Mode is used to produce this file. The configuration can be printed to standard output, or the -f option can be used to specify an output file.

Branded Zone Configuration Data

Zone configuration data consists of two kinds of entities: resources and properties. Each resource has a type, and each resource can also have a set of one or more properties. The properties have names and values. The set of properties is dependent on the resource type.

Resource and Property Types

The resource and property types are described as follows:

Zone name

The zone name identifies the zone to the configuration utility. The following rules apply to zone names:

  • Each zone must have a unique name.

  • A zone name is case-sensitive.

  • A zone name must begin with an alphanumeric character.

    The name can contain alphanumeric characters, underbars (_), hyphens (-), and periods (.).

  • The name cannot be longer than 64 characters.

  • The name global and all names beginning with SUNW are reserved and cannot be used.

zonepath

The zonepath property is the path to the zone root. Each zone has a path to its root directory that is relative to the global zone's root directory. At installation time, the global zone directory is required to have restricted visibility. It must be owned by root with the mode 700.

The non-global zone's root path is one level lower. The zone's root directory has the same ownership and permissions as the root directory (/) in the global zone. The zone directory must be owned by root with the mode 755. These directories are created automatically with the correct permissions, and do not need to be verified by the zone administrator. This hierarchy ensures that unprivileged users in the global zone are prevented from traversing a non-global zone's file system.

Path 

Description 

/home/export/lx-zone

zonecfg zonepath

/home/export/lx-zone/root

Root of the zone 

/home/export/lx-zone/root/dev

Devices created for the zone 

See Traversing File Systems for a further discussion of this issue.


Note –

You can move a zone to another location on the same system by specifying a new, full zonepath with the move subcommand of zoneadm. See Moving a Non-Global Zone for instructions.


autoboot

If this property is set to true, the zone is automatically booted when the global zone is booted. Note that if the zones service, svc:/system/zones:default is disabled, the zone will not autoboot, regardless of the setting of this property. You can enable the zones service with the svcadm command described in the svcadm(1M) man page:


global# svcadm enable zones
bootargs

This property is used to set a boot argument for the zone. The boot argument is applied unless overridden by the reboot, zoneadm boot, or zoneadm reboot commands. See Branded Zone Boot Arguments.

pool

This property is used to associate the zone with a specific resource pool on the system. Multiple zones can share the resources of one pool. Also see Specifying the dedicated-cpu Resource.

limitpriv

This property is used to specify a privilege mask other than the default. See Privileges in a Non-Global Zone.

Privileges are added by specifying the privilege name, with or without the leading priv_. Privileges are excluded by preceding the name with a dash (-) or an exclamation mark (!). The privilege values are separated by commas and placed within quotation marks ().

As described in priv_str_to_set(3C), the special privilege sets of none, all, and basic expand to their normal definitions. Because zone configuration takes place from the global zone, the special privilege set zone cannot be used. Because a common use is to alter the default privilege set by adding or removing certain privileges, the special set default maps to the default, set of privileges. When default appears at the beginning of the limitpriv property, it expands to the default set.

The following entry adds the ability to set the system clock and removes the ability to send raw Internet Control Message Protocol (ICMP) packets:


global# zonecfg -z userzone
zonecfg:userzone> set limitpriv="default,sys_time,!net_icmpaccess"

If the zone's privilege set contains a disallowed privilege, is missing a required privilege, or includes an unknown privilege, an attempt to verify, ready, or boot the zone will fail with an error message.

scheduling-class

This property sets the scheduling class for the zone. See Scheduling Class in a Zone for additional information and tips.

dedicated-cpu

This resource dedicates a subset of the system's processors to the zone while it is running. The dedicated-cpu resource provides limits for ncpus and, optionally, importance. For more information, seeSpecifying the dedicated-cpu Resource.

capped-cpu

This resource establishes an absolute limit on the number of CPUs for this zone. The capped-cpu resource provides limits for ncpus. For more information, seeSpecifying the capped-cpu Resource.

capped-memory

This resource groups the properties used when capping memory for the zone. The capped-memory resource provides limits for physical, swap, and locked memory. At least one of these properties must be specified.

fs

Each zone can have various file systems that are mounted when the zone transitions from the installed state to the ready state. The file system resource specifies the path to the file system mount point. For more information about the use of file systems in zones, see File Systems and Non-Global Zones.

net

The network interface resource is the interface name. Each zone can have network interfaces that are be set up when the zone transitions from the installed state to the ready state.

Only the shared-IP network configuration is supported in an lx branded zone

rctl

The rctl resource is used for zone-wide resource controls. The controls are enabled when the zone transitions from the installed state to the ready state.


Note –

To configure zone-wide controls using the set global_property_name subcommand of zonefig instead of the rctl resource, see How to Configure the lx Branded Zone.


attr

This generic attribute can be used for user comments or by other subsystems. The name property of an attr must begin with an alphanumeric character. The name property can contain alphanumeric characters, hyphens (-), and periods (.). Attribute names beginning with zone. are reserved for use by the system.

Resource Type Properties in the lx Branded Zone

Resources also have properties to configure. The following properties are associated with the resource types shown.

dedicated-cpu

ncpus, importance

Specify the number of CPUs and, optionally, the relative importance of the pool. The following example specifies a CPU range for use by the zone lx-zone. importance is also set.


zonecfg:lx-zone> add dedicated-cpu
zonecfg:lx-zone:dedicated-cpu> set ncpus=1-3
zonecfg:lx-zone:dedicated-cpu> set importance=2
zonecfg:lx-zone:dedicated-cpu> end
capped-cpu

ncpus

Specify the number of CPUs. The following example specifies a CPU limit of 3.5 CPUs for use by the zone lx-zone.


zonecfg:lx-zone> add capped-cpu
zonecfg:lx-zone:capped-cpu> set ncpus=3.5
zonecfg:lx-zone:capped-cpu> end
capped-memory

physical, swap, locked

This resource groups the properties used when capping memory for the zone. The following example specifies the memory limits for the zone lx-zone. Each limit is optional, but at least one must be set.


zonecfg:my-zone> add capped-memory
zonecfg:lx-zone:capped-memory> set =50m
zonecfg:lx-zone:capped-memory> set swap=100m
zonecfg:lx-zone:capped-memory> set locked=30m
zonecfg:lx-zone:capped-memory> end
fs

dir, special, raw, type, options

The lines in the following example add read-only access to CD or DVD media in a non-global zone. The file system is loopback mounted with the options ro,nodevices (read-only and no devices) in the non-global zone.


zonecfg:lx-zone> add fs
zonecfg:lx-zone:fs> set dir=/cdrom
zonecfg:lx-zone:fs> set special=/cdrom
zonecfg:lx-zone:fs> set type=lofs
zonecfg:lx-zone:fs> add options [ro,nodevices]
zonecfg:lx-zone:fs> end

Note that section 1M man pages are available for mount options that are unique to a specific file system. The names of these man pages have the form mount_filesystem.

net

address, physical

In the following example, IP address 192.168.0.1 is added to a zone. An bge0 card is used for the physical interface.


zonecfg:lx-zone> add net
zonecfg:lx-zone:net> set physical=bge0
zonecfg:lx-zone:net> set address=192.168.0.1
zonecfg:lx-zone:net> end

Note –

To determine which physical interface to use, type ifconfig -a on your system. Each line of the output, other than loopback driver lines, begins with the name of a card installed on your system. Lines that contain LOOPBACK in the descriptions do not apply to cards.


rctl

name, value

Available zone-wide resource controls are described in Zone-Wide Resource Controls in an lx Branded Zone.


zonecfg:lx-zone> add rctl
zonecfg:lx-zone:rctl> set name=zone.cpu-shares
zonecfg:lx-zone:rctl> add value (priv=privileged,limit=10,action=none)
zonecfg:lx-zone:rctl> end

zonecfg:lx-zone> add rctl
zonecfg:lx-zone:rctl> set name=zone.max-lwps
zonecfg:lx-zone:rctl> add value (priv=privileged,limit=100,action=deny)
zonecfg:lx-zone:rctl> end
attr

name, type, value

In the following example, a comment about a zone is added.


zonecfg:lx-zone> add attr
zonecfg:lx-zone:attr> set name=comment
zonecfg:lx-zone:attr> set type=string
zonecfg:lx-zone:attr> set value="Production zone"
zonecfg:lx-zone:attr> end

You can use the export subcommand to print a zone configuration to standard output. The configuration is saved in a form that can be used in a command file.

Chapter 31 Configuring the lx Branded Zone (Tasks)

This chapter describes how to configure an lx branded zone on your x64 or x86 based system. The process is basically the same as the procedure to configure a Solaris Zone. A few of the properties are not needed to configure a branded zone.

Planning and Configuring an lx Branded Zone (Task Map)

Before you set up your system to use zones, you must first collect information and make decisions about how to configure the zones. The following task map summarizes how to plan and configure an lx zone.

Task 

Description 

For Instructions 

Plan your zone strategy. 

  • Determine which applications you want to run in zones.

  • Assess the availability of disk space to hold the files in the zone.

  • If you are also using resource management features, determine how to align the zone with the resource management boundaries.

  • If you are using resource pools, configure the pools if necessary.

See System and Space Requirements and Resource Pools Used in Zones.

Determine the name and the path for the zone. 

Decide what to call the zone based on the naming conventions. A path on a Zetabyte File System (ZFS) is recommended. 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.

See Resource and Property Types and Solaris ZFS Administration Guide.

Obtain or configure IP addresses for the zone. 

Depending on your configuration, you must obtain at least one IP address for each non-global zone that you want to have network access. 

See Determine the Zone Host Name and Obtain the Network Address and System Administration Guide: IP Services.

Determine if you want to mount file systems in the zone. 

Review your application requirements. 

See File Systems Mounted in Zones for more information.

Determine which network interfaces should be made available in the zone. 

Review your application requirements. 

See Shared-IP Network Interfaces for more information.

Determine whether you must alter the default set of non-global zone permissions. 

Check the set of privileges: default, privileges that can be added and removed, and privileges that cannot be used at this time. 

See Resource and Property Types and Privileges in a Non-Global Zone.

Configure the zone. 

Use zonecfg to create a configuration for the zone.

See How to Configure, Verify, and Commit the lx Branded Zone.

Verify and commit the configured zone. 

Determine whether the resources and properties specified are valid on a hypothetical system. 

See How to Configure, Verify, and Commit the lx Branded Zone.

How to Configure the lx Branded Zone

You use the zonecfg command described in the zonecfg(1M) man page to perform the following actions.

  • Create the zone configuration

  • Verify that all required information is present

  • Commit the non-global zone configuration


Tip –

If you know you will be using CDs or DVDs to install applications in an lx branded zone, use add fs to add read-only access to CD or DVD media in the global zone when you initially configure the branded zone. A CD or DVD can then be used to install a product in the branded zone.


While configuring a zone with the zonecfg utility, you can use the revert subcommand to undo the setting for a resource. See How to Revert a Zone Configuration.

A script to configure multiple zones on your system is provided in Script to Configure Multiple lx Branded Zones.

To display a non-global zone's configuration, see How to Display the Configuration of a Branded Zone.


Tip –

After you have configured the branded zone, it is a good idea to make a copy of the zone's configuration. You can use this backup to restore the zone in the future. As superuser or Primary Administrator, print the configuration for the zone lx-zone to a file. This example uses a file named lx-zone.config.


global# zonecfg -z lx-zone export > lx-zone.config

See How to Restore an Individual Non-Global Zone for more information.


ProcedureHow to Configure, Verify, and Commit the lx Branded Zone

Note that you cannot use lx branded zones on a Trusted Solaris system where labels are enabled. The zoneadm command will not verify the configuration.

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. Set up a zone configuration with the zone name you have chosen.

    The name lx-zone is used in this example procedure.


    global# zonecfg -z lx-zone
    

    If this is the first time you have configured this zone, you will see the following system message:


    lx-zone: No such zone configured
    Use 'create' to begin configuring a new zone.
  3. Create the new lx zone configuration by using the SUNWlx template.


    zonecfg:lx-zone> create -t SUNWlx
    

    Alternatively, you can create a blank zone and explicitly set the brand:


    zonecfg:lx-zone> create -b
    zonecfg:lx-zone> set brand=lx
    
  4. Set the zone path, /export/home/lx-zone in this procedure.


    zonecfg:lx-zone> set zonepath=/export/home/lx-zone
    
  5. Set the autoboot value.

    If set to true, the zone is automatically booted when the global zone is booted. Note that for the zones to autoboot, the zones service svc:/system/zones:default must also be enabled. The default value is false.


    zonecfg:lx-zone> set autoboot=true
    
  6. Set persistent boot arguments for a zone.


    zonecfg:lx-zone> set bootargs="-i=altinit"
    
  7. If resource pools are enabled on your system, associate a pool with the zone.

    This example uses the default pool, named pool_default.


    zonecfg:lx-zone> set pool=pool_default
    

    Because a resource pool can have an optional scheduling class assignment, you can use the pools facility to set a default scheduler other than the system default for a non-global zone. For instructions, see How to Associate a Pool With a Scheduling Class and Creating the Configuration.

  8. Revise the default set of privileges.


    zonecfg:lx-zone> set limitpriv="default,proc_priocntl"
    

    The proc_priocntl privilege is used to run processes in the real-time class.

  9. Set five CPU shares.


    zonecfg:lx-zone> set cpu-shares=5
    
  10. Add a memory cap.


    zonecfg:lx-zone> add capped-memory
    
    1. Set the memory cap.


      zonecfg:lx-zone:capped-memory> set =50m
      
    2. Set the swap memory cap.


      zonecfg:lx-zone:capped-memory> set swap=100m
      
    3. Set the locked memory cap.


      zonecfg:lx-zone:capped-memory> set locked=30m
      
    4. End the specification.


      zonecfg:lx-zone:capped-memory> end
      
  11. Add a file system.


    zonecfg:lx-zone> add fs
    
    1. Set the mount point for the file system, /export/linux/local in this procedure.


      zonecfg:lx-zone:fs> set dir=/export/linux/local
      
    2. Specify that /opt/local in the global zone is to be mounted as /usr/local in the zone being configured.


      zonecfg:lx-zone:fs> set special=/opt/local
      

      In the non-global zone, the /usr/local file system will be readable and writable.

    3. Specify the file system type, lofs in this procedure.


      zonecfg:lx-zone:fs> set type=lofs
      

      The type indicates how the kernel interacts with the file system.

    4. End the file system specification.


      zonecfg:lx-zone:fs> end
      

    This step can be performed more than once to add more than one file system.

  12. Add a network interface.


    zonecfg:lx-zone> add net
    
    1. Set the IP address in the form ip address of zone/netmask. In this procedure, 10.6.10.233/24 is used.


      zonecfg:lx-zone:net> set address=10.6.10.233/24
      
    2. Set the physical device type for the network interface, the bge device in this procedure.


      zonecfg:lx-zone:net> set physical=bge0
      
    3. (Optional) Set the default router for the network interface, in this procedure.


      zonecfg:my-zone:net> set defrouter=10.0.0.1
      
    4. End the specification.


      zonecfg:lx-zone:net> end
      

    This step can be performed more than once to add more than one network interface.

  13. Enable an audio device present in the global zone in this zone by using the attr resource type.


    zonecfg:lx-zone> add attr
    
    1. Set the name to audio.


      zonecfg:lx-zone:attr> set name=audio
      
    2. Set the type to boolean.


      zonecfg:lx-zone:attr> set type=boolean
      
    3. Set the value to true.


      zonecfg:lx-zone:attr> set value=true
      
    4. End the attr resource type specification.


      zonecfg:lx-zone:attr> end
      
  14. Verify the zone configuration for the zone.


    zonecfg:lx-zone> verify
    
  15. Commit the zone configuration for the zone.


    zonecfg:lx-zone> commit
    
  16. Exit the zonecfg command.


    zonecfg:lx-zone> exit
    

    Note that even if you did not explicitly type commit at the prompt, a commit is automatically attempted when you type exit or an EOF occurs.

Using Multiple Subcommands From the Command Line

Tip –

The zonecfg command also supports multiple subcommands, quoted and separated by semicolons, from the same shell invocation.


global# zonecfg -z lx-zone "create -t SUNWlx; set zonepath=/export/home/lx-zone"

Where to Go From Here

See Installing and Booting lx Branded ZonesInstalling and Booting Zones to install your committed zone configuration.

Script to Configure Multiple lx Branded Zones

You can use this script to configure and boot multiple zones on your system. The script takes the following parameters:

  • The number of zones to be created

  • The zonename prefix

  • The directory to use as the base directory

You must be the global administrator in the global zone to execute the script. The global administrator has superuser privileges in the global zone or assumes the Primary Administrator role.


#!/bin/ksh
#
# Copyright 2006 Sun Microsystems, Inc. All rights reserved.
# Use is subject to license terms.
#
#ident	"%Z%%M%   %I%    %E% SMI"
if [[ -z "$1" || -z "$2" || -z "$3" || -z "$4" ]]; then
    echo "usage: $0 <#-of-zones> <zonename-prefix> <basedir> <template zone>"
    exit 2
fi
if [[ ! -d $3 ]]; then
    echo "$3 is not a directory"
    exit 1
fi
state=`zoneadm -z $4 list -p 2>/dev/null | cut -f 3 -d ":"`
if [[ -z "$state" || $state != "installed" ]]; then
    echo "$4 must be an installed, halted zone"
    exit 1
fi

template_zone=$4

nprocs=`psrinfo | wc -l`
nzones=$1
prefix=$2
dir=$3

ip_addrs_per_if=`ndd /dev/ip ip_addrs_per_if`
if [ $ip_addrs_per_if -lt $nzones ]; then
	    echo "ndd parameter ip_addrs_per_if is too low ($ip_addrs_per_if)"
	    echo "set it higher with 'ndd -set /dev/ip ip_addrs_per_if <num>"
	    exit 1
fi

i=1
while [ $i -le $nzones ]; do
	zoneadm -z $prefix$i clone $template_zone > /dev/null 2>&1
	if [ $? != 0 ]; then
		echo configuring $prefix$i
		F=$dir/$prefix$i.config
		rm -f $F
		echo "create -t SUNWlx" > $F
		echo "set zonepath=$dir/$prefix$i" >> $F
		zonecfg -z $prefix$i -f $dir/$prefix$i.config 2>&1 | \
		    sed 's/^/    /g' 
	else
		echo "skipping $prefix$i, already configured"
	fi
	i=`expr $i + 1`
done

i=1
while [ $i -le $nzones ]; do
	j=1
	while [ $j -le $nprocs ]; do
		if [ $i -le $nzones ]; then
			if [ `zoneadm -z $prefix$i list -p | \
			    cut -d':' -f 3` != "configured" ]; then
				echo "skipping $prefix$i, already installed"
			else
				echo installing $prefix$i
				mkdir -pm 0700 $dir/$prefix$i
				chmod 700 $dir/$prefix$i
				zoneadm -z $prefix$i install -s -d /path/to/ISOs > /dev/null 2>&1 &
				sleep 1	# spread things out just a tad
			fi
		fi
		i=`expr $i + 1`
		j=`expr $j + 1`
	done
	wait
done

i=1
para=`expr $nprocs \* 2`
while [ $i -le $nzones ]; do
	date
	j=1
	while [ $j -le $para ]; do
		if [ $i -le $nzones ]; then
			echo booting $prefix$i
			zoneadm -z $prefix$i boot &
		fi
		j=`expr $j + 1`
		i=`expr $i + 1`
	done
	wait
done

ProcedureHow to Display the Configuration of a 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. Display the configuration of a zone.


    global# zonecfg -z zonename info
    

Modifying, Reverting, or Removing Zone Configurations

The following sections contain procedures for modifying, reverting, or removing a zone configuration.

Chapter 32 About Installing, Booting, Halting, Cloning, and Uninstalling lx Branded Zones (Overview)

This chapter discusses the following topics:

  • Installing an lx zone on your system

  • Cloning a zone on your system

  • Halting, rebooting, and uninstalling zones

Branded Zone Installation and Administration Concepts

The zoneadm command described in the zoneadm(1M) man page is the primary tool used to install and administer non-global zones. Operations using the zoneadm command must be run from the global zone. The following tasks can be performed using the zoneadm command:

  • Verify a zone

  • Install a zone

  • Boot a zone

  • Display information about a running zone

  • Halt a zone

  • Reboot a zone

  • Uninstall a zone

  • Relocate a zone from one point on a system to another point on the same system

  • Provision a new zone based on the configuration of an existing zone on the same system

  • Migrate a zone, used with the zonecfg command

For zone installation and verification procedures, see Chapter 33, Installing, Booting, Halting, Uninstalling and Cloning lx Branded Zones (Tasks) and the zoneadm(1M) man page. Also refer to the zoneadm(1M) man page for supported options to the zoneadm list command. For zone configuration procedures, see Chapter 31, Configuring the lx Branded Zone (Tasks), and the zonecfg(1M) man page. Zone states are described in Non-Global Zone State Model.

If you plan to produce Solaris auditing records for zones, read Using Solaris Auditing in Zones before you install non-global zones.


Note –

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.


lx Branded Zone Installation Methods

You can install an lx branded zone by using a tarball, CD-ROM or DVD discs, or an ISO image. If you install from discs or from an ISO image, you can specify Sun package cluster categories. The categories are cumulative. If you do not specify a cluster, the default is desktop.

Table 32–1 Package Cluster Categories

Sun Category 

Contents 

core

The minimum set of packages needed to construct a zone. 

server

core plus server-oriented packages, such as httpd, mailman, imapd, and spam-assassin.

desktop

server plus user-oriented packages, such as evolution, gimp, mozilla, and openoffice

developer

desktop plus developer packages, such as bison, emacs, gcc, vim-X11, and many library development packages

all

Everything on the install media that is known not to interfere with the zone's operation. Certain packages might not function in a Linux zone. 

To install configured lx branded zones, see How to Install an lx Branded Zone.

lx Branded Zone Construction

This section applies to only to initial zone construction, and not to the cloning of existing zones.

After you have configured a non-global zone, you should verify that the zone can be installed safely on your system's configuration. You can then install the zone. The files needed for the zone's root file system are installed by the system under the zone's root path. The Linux zone will be populated from CD, ISO images, or a tarball, as described in How to Install an lx Branded Zone.

The resources specified in the configuration file are added when the zone transitions from installed to ready. A unique zone ID is assigned by the system. File systems are mounted, network interfaces are set up, and devices are configured. Transitioning into the ready state prepares the virtual platform to begin running user processes.

A zone in the ready state does not have any user processes executing in it. The primary difference between a ready zone and a running zone is that at least one process is executing in a running zone. See the init(1M) man page for more information.

In the ready state, the zsched and zoneadmd processes are started to manage the virtual platform.

zoneadmd Zones Administration Daemon

The zones administration daemon, zoneadmd, is the primary process for managing the zone's virtual platform. For more information, see The zoneadmd Daemon.

zsched Zone Scheduling Process

The process that manages the application environment, zsched, is described in The zsched Zone Scheduler.

Branded Zone Application Environment

The zoneadm command is used to create the zone application environment.

All additional configuration is done by the zone administrator using Linux tools from within the zone.

Passwords

Note that the root (superuser) password will be root when the zone is installed from the Sun tarball. The root (superuser) password will be unset (blank) when the zone is installed from ISO images or a CD.

About Halting, Rebooting, Uninstalling, and Cloning lx Branded Zones

This section provides an overview of the procedures for halting, rebooting, uninstalling, and cloning zones.

Halting a Branded Zone

The zoneadm halt command is used to remove both the application environment and the virtual platform for a zone. The zone is then brought back to the installed state. All processes are killed, devices are unconfigured, network interfaces are destroyed, file systems are unmounted, and the kernel data structures are destroyed.

The halt command does not run any shutdown scripts within the zone. To shut down a zone, see How to Use zlogin to Shut Down a Zone.

If the halt operation fails, see Zone Does Not Halt.

Rebooting a Branded Zone

The zoneadm reboot command is used to reboot a zone. The zone is halted and then booted again. The zone ID will change when the zone is rebooted.

Branded Zone Boot Arguments

Zones support the following boot arguments used with the zoneadm boot and reboot commands:

  • -i altinit

  • -s

The following definitions apply:

-i altinit

Selects an alternative executable to be the first process. altinit must be a valid path to an executable. The default first process is described in init(1M).

-s

Boots the zone to init level s.

For usage examples, see How to Boot an lx Branded Zone and How to Boot an lx Branded Zone in Single-User Mode.

For information on the init command, see init(1M).

Branded Zone autoboot

If you set the autoboot resource property in a zone's configuration to true, that zone is automatically booted when the global zone is booted. The default setting is false.

Note that for zones to autoboot, the zones service svc:/system/zones:default must also be enabled.

Uninstalling the Branded Zone

The zoneadm uninstall command removes all of the files under the zone's root file system. Before proceeding, the command prompts you to confirm the action, unless the -F (force) option is also used. Use the uninstall command with caution, because the action is irreversible.

About Cloning an lx Branded Zone

Cloning allows you to copy an existing configured and installed zone on your system to rapidly provision a new zone on the same system. For more information about the clone process, see About Cloning Non-Global Zones. To clone an lx branded zone, see Cloning an lx Branded Zone on the Same System.

Booting and Rebooting lx Branded Zones

For procedures to boot and reboot zones, see How to Boot an lx Branded Zone and How to Reboot an lx Branded Zone

Chapter 33 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:

  • Using clone to install a zone on the same system

  • Halting, rebooting, and uninstalling zones

  • Removing a zone from a system

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:

  • A compressed tar archive (a tarball)

  • A set of CD-ROM or DVD discs

  • A group of ISO images

  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 33–1, Example 33–2, and Example 33–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 2, 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 33–1 Install Command Using a CentOS Compressed tar Archive


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


Example 33–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 33–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 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 33–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 33–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 netmasks Warning 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.

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

    If the source zonepath is on a ZFS pool, for example, zeepool, the system displays:


    Cloning snapshot zeepool/zones/lx-zone@SUNWzone1
    Instead of copying, a ZFS clone has been created for this 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          
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:

  • The zoneadm command takes a software inventory.

  • The zoneadm command takes a ZFS snapshot and names it SUNWzoneX, for example, SUNWzone1.

  • The zoneadm command uses ZFS clone to clone the snapshot.

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

Chapter 34 Logging In to lx Branded Zones (Tasks)

This chapter provides the following information:

  • Introductory information about zone login

  • Completing the internal configuration of an installed lx branded zone

  • Logging into the zone from the global zone

  • Shutting down the zone

  • Using the zonename command to print the name of the current zone

zlogin Command Overview

The zlogin command is used to log in from the global zone to any zone that is in the running state or the ready state.


Note –

Only the zlogin command with the -C option can be used to log in to a zone that is not in the running state.


Unless the -C option is used to connect to the zone console, logging in to a zone using zlogin starts a new task. A task cannot span two zones.

As described in How to Use Non-Interactive Mode to Access an lx Branded Zone, you can use the zlogin command in non-interactive mode by supplying a command to run inside a zone. However, the command or any files the command acts upon cannot reside on NFS. The command will fail if any of its open files or any portion of its address space resides on NFS. The address space includes the command executable itself and the command's linked libraries.

The zlogin command can only be used by the global administrator operating in the global zone. See the zlogin(1) man page for more information.

lx Branded Zone Login Methods

An overview of zone console and user login methods is provided in Non-Global Zone Login Methods.

The failsafe mode is used when a login problem occurs that prevents you from using the zlogin command or the zlogin command with the -C option to access the zone. This mode is described in Failsafe Mode

Information on remote login zone is provided in Remote Login

Interactive mode allocates a new pseudo-terminal for use inside the zone. Non-interactive mode is used to run shell-scripts which administer the zone. See Interactive and Non-Interactive Modes for more information.

Login Procedures for Branded Zones (Task Map)

Task 

Description 

For Instructions 

Log in to the zone. 

You can log into a zone through the console, by using interactive mode to allocate a pseudo-terminal, or by supplying a command to be run in the zone. Supplying a command to be run does not allocate a pseudo-terminal. You can also log in by using failsafe mode when a connection to the zone is denied. 

Logging In to an lx Branded Zone

Exit a branded zone. 

Disconnect from a branded zone. 

How to Exit the lx Branded Zone

Shut down a branded zone. 

Shut down a branded zone by using the shutdown utility or a script.

How to Use zlogin to Shut Down an lx Branded Zone

Logging In to an lx Branded Zone

Use the zlogin command to log in from the global zone to any zone that is running or in the ready state. See the zlogin(1) man page for more information.

You can log in to a zone in various ways, as described in the following procedures. You can also log in remotely, as described in Remote Login.

ProcedureHow to Log In to the lx Branded Zone Console

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 zlogin command with the -C option and the name of the zone, for example, lx-zone.


    global# zlogin -C lx-zone
    [Connected to zone 'lx-zone' console]

    Note –

    If you start the zlogin session immediately after issuing the zoneadm boot command, boot messages from the zone will display:


    INIT: version 2.85 booting
    	                Welcome to CentOS
    	                Press 'I' to enter interactive startup.
    	Configuring kernel parameters:  [  OK  ]
    	Setting hostname lx-zone:  [  OK  ]
    	[...]
    	CentOS release 3.6 (Final)
    	Kernel 2.4.21 on an i686

  3. When the zone console displays, log in as root, press Return, and type the root password when prompted.


    lx-zone console login: root
    Password:

    Note –

    Recall that the root (superuser) password is root when the zone is installed from the Sun tarball. The root (superuser) password is unset (blank) when the zone is installed from ISO images or a CD.


ProcedureHow to Use Interactive Mode to Access a Branded Zone

In interactive mode, a new pseudo-terminal is allocated for use inside 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. From the global zone, log in to the zone, for example, lx-zone.


    global# zlogin lx-zone
    

    Information similar to the following will display:


    [Connected to zone 'lx-zone' pts/2]
    Last login: Wed Jul  3 16:25:00 on console
    Sun Microsystems Inc. SunOS 5.10 Generic July 2006
  3. Type exit to close the connection.

    You will see a message similar to the following:


    [Connection to zone 'lx-zone' pts/2 closed]

ProcedureHow to Verify the Running Environment

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. Log in to the zone, for example, lx-zone.


    global# zlogin lx-zone
    
  3. Verify that you are running in a Linux environment under the Solaris Operating System.


    [root@lx-zone root]# uname -a
    

    You will see a display similar to the following:


    Linux lx-zone 2.4.21 BrandZ fake linux i686 i686 i386 GNU/Linux 

ProcedureHow to Use Non-Interactive Mode to Access an lx Branded Zone

Non-interactive mode is enabled when the user supplies a command to be run inside the zone. Non-interactive mode does not allocate a new pseudo-terminal.

Note that the command or any files that the command acts upon cannot reside on NFS.

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. From the global zone, log in to the lx-zone zone and supply a command name.

    Replace command with the name of the command to be run inside the zone.


    global# zlogin lx-zone command
    

Example 34–1 Using the Command uptime in the Zone lx_master


global#  zlogin lx_master uptime
	21:16:01  up  2:39,  0 users,  load average: 0.19, 0.13, 0.11
	fireball#

ProcedureHow to Exit the lx Branded Zone

  1. To disconnect from a non-global zone, use the tilde (~) character and a period:


    zonename# ~.
    

    Your screen will look similar to this:


    [Connection to zone 'lx-zone' pts/6 closed]
    • You can also type exit to exit the zone.

See Also

For more information about zlogin command options, see the zlogin(1) man page.

ProcedureHow to Use Failsafe Mode to Enter an lx Branded Zone

When a connection to the zone is denied, the zlogin command can be used with the -S option to enter a minimal environment in 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. From the global zone, use the zlogin command with the -S option to access the zone, for example, lx-zone.


    global# zlogin -S lx-zone
    

ProcedureHow to Use zlogin to Shut Down an lx Branded Zone


Note –

Running init 0 in the global zone to cleanly shut down a Solaris system also runs init 0 in each of the non-global zones on the system. Note that init 0 does not warn local and remote users to log off before the system is taken down.


Use this procedure to cleanly shut down a zone. To halt a zone without running shutdown scripts, see How to Halt 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. Log in to the zone to be shut down, for example, lx-zone, and specify shutdown as the name of the utility and init 0 as the state.


    global# zlogin lx-zone shutdown -i 0
    

    Your site might have its own shutdown script, tailored for your specific environment.

Using shutdown in Non-Interactive Mode

You cannot use the shutdown command in non-interactive mode to place the zone in single—user state at this time. See 6214427 for more information.

You can use an interactive login as described in How to Use Interactive Mode to Access a Branded Zone.

Chapter 35 Moving and Migrating lx Branded Zones (Tasks)

This chapter describes how to:

  • Move an existing lx branded zone to a new location on the same machine

  • Validate what will happen in an lx branded zone migration before the actual migration is performed.

  • Migrate an existing lx branded zone to a new machine.

Moving an lx Branded Zone

This procedure is used to move a 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

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

    Roles are described in 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.


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

Migrating an lx Branded Zone to a Different Machine

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.

Note that the trial run does not validate the processor type, so you must verify that the target machine is running a supported processor.

About Migrating an lx Branded 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 lx branded zone migration:

  • The global zone on the target system must be running the same Solaris release as the original host.

  • To ensure that the zone will run properly, the target system must have the same versions of the required operating system packages and patches that were installed on the original host.

  • The brand must be the same on the original host and on the target system.

  • The target system must have one of the following supported i686 processor types:

    • Intel

      • Pentium Pro

      • Pentium II

      • Pentium III

      • Celeron

      • Xeon

      • Pentium 4

      • Pentium M

      • Pentium D

      • Pentium Extreme Edition

      • Core

      • Core 2

      AMD

      • Opteron

      • Athlon XP

      • Athlon 64

      • Athlon 64 X2

      • Athlon FX

      • Duron

      • Sempron

      • Turion 64

      • Turion 64 X2

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 an lx Branded Zone

  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, lx-zone in this procedure.


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


    host1# zoneadm -z lx-zone detach
    

    The detached zone is now in the configured state.

  4. Move the zonepath for lx-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 lx-zone
    

    You will see the following system message:


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


    zonecfg:lx-zone> create -a /export/zones/lx-zone
    
  7. View the configuration.


    zonecfg:lx-zone> info
    zonename: lx-zone
    zonepath: /export/zones/lx-zone
    brand: lx
    autoboot: false
    bootargs:
    pool:
    limitpriv:
    net:
             address: 192.168.0.90
             physical: bge0
  8. (Optional) Make any required adjustments to the configuration.

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


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


    zonecfg:lx-zone> commit
    zonecfg:lx-zone> exit
    
  10. Attach the zone on the new host.

    • Attach the zone with a validation check.


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

    • Force the attach operation without performing the validation.


      host2# zoneadm -z lx-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 35–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 lx-zone.tar lx-zone
    host1# sftp host2
    Connecting to host2...
    Password:
    sftp> cd /export/zones
    sftp> put lx-zone.tar
    Uploading lx-zone.tar to /export/zones/lx-zone.tar
    sftp> quit
    
  2. On host2, unpack the tar file.


    host2# cd /export/zones
    host2# tar xf lx-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:

  • Patches and packages are out of sync.

  • Operating system releases do not match.

The user must verify that the processor type in the new machine is supported. See About Migrating an lx Branded Zone for more information.

About Validating an lx Branded 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 an lx Branded 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 lx-zone and pipe the output to a remote command that will immediately validate the target host:


      global# zoneadm -z lx-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 lx-zone and direct the output to a file:


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

Chapter 36 Administering and Running Applications in lx Branded Zones (Tasks)

This chapter contains material on running applications in an lx branded zone.

About Maintaining a Supported Configuration

When you installed a zone with a supported CentOS or Red Hat Enterprise Linux distribution, you created a supported zone. If you add packages from different versions to this zone, it is possible to create a branded zone that cannot be supported.

Upgrading the Distribution and Adding Packages

ProcedureHow to Upgrade a CentOS 3.x Distribution

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

  1. Upgrade a CentOS 3.x distribution to a different version by using yum upgrade or up2date.

    For instructions, see the documentation available at http://www.centos.org.

ProcedureHow to Upgrade a Red Hat 3.x Distribution

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

  1. Update a Red Hat Enterprise Linux 3.x distribution to a different version by using up2date.

    For instructions, see the documentation available at http://www.redhat.com.

ProcedureHow to Upgrade a Package

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

  1. To update a package, use one of the following methods.

    • yum update package_name

    • rpm -U package_name

Using yum and rpm

yum:

  • The document Software Management with Yum includes a chapter on installing software from an isolated package. See http://fedora.redhat.com/docs/yum.

  • yum.conf(5)

  • yum(8)

rpm:

How to Install an Application in an lx Branded Zone

Applications are installed as they are on a Linux system, by mounting the CD and running the installation program. This section covers a typical application installation in an lx branded zone.


Tip –

If you know you will be using CDs or DVDs to install applications in an lx branded zone, add read-only access to CD or DVD media in the global zone when you initially configure the branded zone. See step 7 in How to Install MATLAB 7.2 Using CDs.


About MATLAB

MATLAB is a high-level language and interactive environment that enables you to perform computationally intensive tasks quickly. The product was developed by The MathWorks. See http://www.mathworks.com for more information.

ProcedureHow to Install MATLAB 7.2 Using CDs

  1. Obtain the MATLAB 7.2 CDs .

    There are three CDs in the MATLAB/Simulink package. Only discs 1 and 3 are needed for a simple MATLAB installation.

  2. Create and install an lx branded zone as described in How to Configure, Verify, and Commit the lx Branded Zone and Installing and Booting lx Branded Zones.

  3. If the Volume Management file system is not running in the global zone, start it.


    global# svcadm volfs enable
    
  4. Insert the media.

  5. Check for media in the drive.


    global# volcheck
    
  6. Test whether the CD is automounted.


    global# ls /cdrom
    

    You will see a display similar to the following:


    cdrom   cdrom1   mathworks_2006a1
  7. Loopback mount the file system with the options ro,nodevices (read-only and no devices) in the non-global zone.


    global# zonecfg -z lx-zone
    zonecfg:lx-zone> add fs
    zonecfg:lx-zone:fs> set dir=/cdrom
    zonecfg:lx-zone:fs> set special=/cdrom
    zonecfg:lx-zone:fs> set type=lofs
    zonecfg:lx-zone:fs> add options [ro,nodevices]
    zonecfg:lx-zone:fs> end
    zonecfg:lx-zone> commit
    zonecfg:lx-zone> exit
    
  8. Reboot the non-global zone.


    global# zoneadm -z lx-zone reboot
    
  9. 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  lx-zone  running      /export/home/lx-zone           lx         shared
  10. Log in to the lx zone.


    global# zlogin lx-zone
    
  11. Verify the CD-ROM mount.


    lx-zone# ls /cdrom
    

    You will see a display similar to this:


    cdrom   cdrom1   mathworks_2006a1
  12. Create the license file as described in the MATLAB documentation.

  13. Install the product as described in the product installation guide.


    lx-zone# /mnt/install
    
  14. Exit the zone.


    lx-zone# exit
    

    Tip –

    You might want to retain the /cdrom file system in your non-global zone. The mount will always reflect the current contents of the CD-ROM drive, or an empty directory if the drive is empty.


  15. (Optional) If you want to remove the /cdrom file system from the non-global zone, use the following procedure.


    global# zonecfg -z lx-zone
    zonecfg:lx-zone> remove fs dir=/cdrom
    zonecfg:lx-zone> commit
    zonecfg:lx-zone> exit
    

ProcedureHow to Install MATLAB 7.2 Using ISO Images

Before You Begin

Note that this method consumes considerable disk space.

  1. Obtain the MATLAB 7.2 CDs .

    There are three CDs in the MATLAB/Simulink package. Only discs 1 and 3 are needed for a simple MATLAB installation.

  2. Create and install an lx branded zone as described in How to Configure, Verify, and Commit the lx Branded Zone and Installing and Booting lx Branded Zones.

  3. Copy the data from each CD to a .iso file.


    global# /usr/bin/dd if=/dev/rdsk/c1d0s2 of=disk1.iso
    

    This copies the data from the first CD to the file disk1.iso. Repeat, using a different file name such as disk3.iso, for the third CD.

  4. From the global zone, lofi-mount the first .iso file in the lx zone.


    global# lofiadm -a /zpool/local/disk1.iso
    global# mount -F hsfs /dev/lofi/1 /zones/lx-zone/root/mnt
    
  5. Log in to the lx zone.


    global# zlogin lx-zone
    
  6. Use X forwarding to redirect the display to your desktop:


    lx-zone# ssh -X root@lx-zone
    
  7. Create the license file as described in the MATLAB documentation.

  8. Install the product as described in the product installation guide.


    lx-zone# /mnt/install
    
  9. When prompted to insert CD 3, go back to the global zone terminal window and mount disk3.isofile in place of the first.


    global# umount /zones/lx-zone/root/mnt
    	global# lofiadm -d /dev/lofi/1
    	global# lofiadm -a /zpool/local/disk3.iso
    	global# mount -F hsfs /dev/lofi/1 /zones/lx-zone/root/mnt
    

    The installation will finish.

Backing Up lx Branded Zones

For information on zone backup, see About Backing Up a Solaris System With Zones Installed, Determining What to Back Up in Non-Global Zones, Backing Up a Solaris System With Installed Zones, About Restoring Non-Global Zones, and Restoring a Non-Global Zone.

Features That Are Not Supported in an lx Branded Zone

The exclusive-IP network configuration is not supported in an lx branded zone. Only the shared-IP network configuration is supported.

The chroot command is not supported in a Linux zone. If used on a process, that process would no longer be able to see the Solaris libraries it needs to run.

Although you can configure and install lx branded zones on a Solaris Trusted Extensions system that has labels enabled, you cannot boot lx branded zones on this system configuration.

You cannot add local Linux file systems using the fs resource property of the zonecfg command.