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.

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:

• Set the importance property.

• Enable the dynamic resource pool service as described in Enabling and Disabling the Pools Facility

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.

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.

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.

Applications generally do not lock significant amounts of memory, but you might decide to set locked memory if the zone's applications are known to lock memory. If zone trust is a concern, you can also consider setting the locked memory cap to 10 percent of the system's physical memory, or 10 percent of the zone's physical memory cap.

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:

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.

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.

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 –

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.