utility creates and modifies the configuration of a zone. Zone configuration consists of a number of resources and properties.
uses the concept of a scope. The default scope is global.
do not affect a running zone. The zone must be rebooted for the changes to take effect.
utility can also be used to persistently specify the resource management settings for the global zone.
In the following text, "rctl" is used as an abbreviation for "resource control". See
(5).
Every zone is configured with an associated brand. The brand determines the user-level environment used within the zone, as well as various behaviors for the zone when it is installed, boots, or is shutdown. Once a zone has been installed the brand cannot be changed. The default brand is determined by the installed distribution in the global zone. Some brands do not support all of the
properties and resources. See the brand-specific man page for more details on each brand. For an overview of brands, see the
(5) man page.
Properties
Each resource type has one or more properties. There are also some global properties, that is, properties of the configuration as a whole, rather than of some particular resource.
The following properties are supported:
(global)
zonename
(global)
zonepath
(global)
autoboot
(global)
bootargs
(global)
pool
(global)
limitpriv
(global)
brand
(global)
cpu-shares
(global)
hostid
(global)
max-lwps
(global)
max-msg-ids
(global)
max-sem-ids
(global)
max-shm-ids
(global)
max-shm-memory
(global)
scheduling-class
(global)
fs-allowed
fs
dir, special, raw, type, options
net
address, physical, defrouter
device
match
rctl
name, value
attr
name, type, value
dataset
name
dedicated-cpu
ncpus, importance
capped-memory
physical, swap, locked
capped-cpu
ncpus
security-flags
lower, default, upper.
As for the property values which are paired with these names, they are either simple, complex, or lists. The type allowed is property-specific. Simple values are strings, optionally enclosed within quotation marks. Complex values have the syntax:
(<
name>=<
value>,<
name>=<
value>,...)
where each <
value> is simple, and the <
name> strings are unique within a given property. Lists have the syntax:
[<
value>,...]
where each <
value> is either simple or complex. A list of a single value (either simple or complex) is equivalent to specifying that value without the list syntax. That is, "foo" is equivalent to "[foo]". A list can be empty (denoted by "[]").
In interpreting property values,
zonecfg accepts regular expressions as specified in
fnmatch(5). See
EXAMPLES.
The property types are described as follows:
global: zonename
The name of the zone.
global: zonepath
Path to zone's file system.
global: autoboot
Boolean indicating that a zone should be booted automatically at system boot. Note that if the zones service is disabled, the zone will not autoboot, regardless of the setting of this property. You enable the zones service with a
svcadm command, such as:
#
svcadm enable svc:/system/zones:default
Replace
enable with
disable to disable the zones service. See
svcadm(1M).
global: bootargs
Arguments (options) to be passed to the zone bootup, unless options are supplied to the " zoneadm boot" command, in which case those take precedence. The valid arguments are described in zoneadm(1M).
global: pool
Name of the resource pool that this zone must be bound to when booted. This property is incompatible with the dedicated-cpu resource.
global: limitpriv
The maximum set of privileges any process in this zone can obtain. The property should consist of a comma-separated privilege set specification as described in
priv_str_to_set(3C). Privileges can be excluded from the resulting set by preceding their names with a dash (-) or an exclamation point (!). The special privilege string "zone" is not supported in this context. If the special string "default" occurs as the first token in the property, it expands into a safe set of privileges that preserve the resource and security isolation described in
zones(5). A missing or empty property is equivalent to this same set of safe privileges.
The system administrator must take extreme care when configuring privileges for a zone. Some privileges cannot be excluded through this mechanism as they are required in order to boot a zone. In addition, there are certain privileges which cannot be given to a zone as doing so would allow processes inside a zone to unduly affect processes in other zones.
zoneadm(1M) indicates when an invalid privilege has been added or removed from a zone's privilege set when an attempt is made to either "boot" or "ready" the zone.
See
privileges(5) for a description of privileges. The command "
ppriv -l" (see
ppriv(1)) produces a list of all Solaris privileges. You can specify privileges as they are displayed by
ppriv. In
privileges(5), privileges are listed in the form PRIV_
privilege_name. For example, the privilege
sys_time, as you would specify it in this property, is listed in
privileges(5) as
PRIV_SYS_TIME.
global: brand
The zone's brand type.
global: ip-type
A zone can either share the IP instance with the global zone, which is the default, or have its own exclusive instance of IP.
This property takes the values
shared and
exclusive.
global: hostid
A zone can emulate a 32-bit host identifier to ease system consolidation. A zone's hostid property is empty by default, meaning that the zone does not emulate a host identifier. Zone host identifiers must be hexadecimal values between 0 and FFFFFFFE. A 0x or 0X prefix is optional. Both uppercase and lowercase hexadecimal digits are acceptable.
fs: dir, special, raw, type, options
Values needed to determine how, where, and so forth to mount file systems. See mount(1M), mount(2), fsck(1M), and vfstab(4).
net: address, physical, defrouter
The network address and physical interface name of the network interface. The network address is one of:
-
o
-
a valid IPv4 address, optionally followed by "/" and a prefix length;
-
o
-
a valid IPv6 address, which must be followed by "/" and a prefix length;
-
o
-
a host name which resolves to an IPv4 address.
Note that host names that resolve to IPv6 addresses are not supported.
The physical interface name is the network interface name.
The default router is specified similarly to the network address except that it must not be followed by a
/ (slash) and a network prefix length.
A zone can be configured to be either exclusive-IP or shared-IP. For a shared-IP zone, you must set both the physical and address properties; setting the default router is optional. The interface specified in the physical property must be plumbed in the global zone prior to booting the non-global zone. However, if the interface is not used by the global zone, it should be configured
down in the global zone, and the default router for the interface should be specified here.
For an exclusive-IP zone, the physical property must be set and the address and default router properties cannot be set.
device: match
Device name to match.
rctl: name, value
The name and priv/limit/action triple of a resource control. See prctl(1) and rctladm(1M). The preferred way to set rctl values is to use the global property name associated with a specific rctl.
attr: name, type, value
The name, type and value of a generic attribute. The type must be one of int, uint, boolean or string, and the value must be of that type. uint means unsigned , that is, a non-negative integer.
dataset: name
The name of a ZFS dataset to be accessed from within the zone. See zfs(1M).
global: cpu-shares
The number of Fair Share Scheduler (FSS) shares to allocate to this zone. This property is incompatible with the dedicated-cpu resource. This property is the preferred way to set the zone.cpu-shares rctl.
global: max-lwps
The maximum number of LWPs simultaneously available to this zone. This property is the preferred way to set the zone.max-lwps rctl.
global: max-msg-ids
The maximum number of message queue IDs allowed for this zone. This property is the preferred way to set the zone.max-msg-ids rctl.
global: max-sem-ids
The maximum number of semaphore IDs allowed for this zone. This property is the preferred way to set the zone.max-sem-ids rctl.
global: max-shm-ids
The maximum number of shared memory IDs allowed for this zone. This property is the preferred way to set the zone.max-shm-ids rctl.
global: max-shm-memory
The maximum amount of shared memory allowed for this zone. This property is the preferred way to set the zone.max-shm-memory rctl. A scale (K, M, G, T) can be applied to the value for this number (for example, 1M is one megabyte).
global: scheduling-class
Specifies the scheduling class used for processes running in a zone. When this property is not specified, the scheduling class is established as follows:
-
o
-
If the cpu-shares property or equivalent rctl is set, the scheduling class FSS is used.
-
o
-
If neither cpu-shares nor the equivalent rctl is set and the zone's pool property references a pool that has a default scheduling class, that class is used.
-
o
-
Under any other conditions, the system default scheduling class is used.
dedicated-cpu: ncpus, importance
The number of CPUs that should be assigned for this zone's exclusive use. The zone will create a pool and processor set when it boots. See pooladm(1M) and poolcfg(1M) for more information on resource pools. The ncpu property can specify a single value or a range (for example, 1-4) of processors. The importance property is optional; if set, it will specify the pset.importance value for use by poold(1M). If this resource is used, there must be enough free processors to allocate to this zone when it boots or the zone will not boot. The processors assigned to this zone will not be available for the use of the global zone or other zones. This resource is incompatible with both the pool and cpu-shares properties. Only a single instance of this resource can be added to the zone.
capped-memory: physical, swap, locked
The caps on the memory that can be used by this zone. A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte). Each of these properties is optional but at least one property must be set when adding this resource. Only a single instance of this resource can be added to the zone. The physical property sets the max-rss for this zone. This will be enforced by rcapd(1M) running in the global zone. The swap property is the preferred way to set the zone.max-swap rctl. The locked property is the preferred way to set the zone.max-locked-memory rctl.
capped-cpu: ncpus
Sets a limit on the amount of CPU time that can be used by a zone. The unit used translates to the percentage of a single CPU that can be used by all user threads in a zone, expressed as a fraction (for example,
.75) or a mixed number (whole number and fraction, for example,
1.25). An
ncpu value of
1 means 100% of a CPU, a value of
1.25 means 125%,
.75 mean 75%, and so forth. When projects within a capped zone have their own caps, the minimum value takes precedence.
The
capped-cpu property is an alias for
zone.cpu-cap resource control and is related to the
zone.cpu-cap resource control. See
resource_controls(5).
security-flags: lower, default, upper
Set the process security flags associated with the zone. The lower and upper fields set the limits, the default field is set of flags all zone processes inherit.
global: fs-allowed
A comma-separated list of additional filesystems that may be mounted within the zone; for example "ufs,pcfs". By default, only hsfs(7fs) and network filesystems can be mounted. If the first entry in the list is "-" then that disables all of the default filesystems. If any filesystems are listed after "-" then only those filesystems can be mounted.
This property does not apply to filesystems mounted into the zone via "add fs" or "add dataset".
WARNING: allowing filesystem mounts other than the default may allow the zone administrator to compromise the system with a malicious filesystem image, and is not supported.
The following table summarizes resources, property-names, and types:
resource property-name type
(global) zonename simple
(global) zonepath simple
(global) autoboot simple
(global) bootargs simple
(global) pool simple
(global) limitpriv simple
(global) brand simple
(global) ip-type simple
(global) hostid simple
(global) cpu-shares simple
(global) max-lwps simple
(global) max-msg-ids simple
(global) max-sem-ids simple
(global) max-shm-ids simple
(global) max-shm-memory simple
(global) scheduling-class simple
fs dir simple
special simple
raw simple
type simple
options list of simple
net address simple
physical simple
device match simple
rctl name simple
value list of complex
attr name simple
type simple
value simple
dataset name simple
dedicated-cpu ncpus simple or range
importance simple
capped-memory physical simple with scale
swap simple with scale
locked simple with scale
capped-cpu ncpus simple
security-flags lower simple
default simple
upper simple
To further specify things, the breakdown of the complex property "value" of the "rctl" resource type, it consists of three name/value pairs, the names being "priv", "limit" and "action", each of which takes a simple value. The "name" property of an "attr" resource is syntactically restricted in a fashion similar but not identical to zone names: it must begin with an alphanumeric, and can contain alphanumerics plus the hyphen (
-), underscore (
_), and dot (
.) characters. Attribute names beginning with "zone" are reserved for use by the system. Finally, the "autoboot" global property must have a value of "true" or "false".
Using Kernel Statistics to Monitor CPU Caps
Using the kernel statistics (
kstat(3KSTAT)) module
caps, the system maintains information for all capped projects and zones. You can access this information by reading kernel statistics (
kstat(3KSTAT)), specifying
caps as the
kstat module name. The following command displays kernel statistics for all active CPU caps:
#
kstat caps::'/cpucaps/'
A
kstat(1M) command running in a zone displays only CPU caps relevant for that zone and for projects in that zone. See
EXAMPLES.
The following are cap-related arguments for use with
kstat(1M):
caps
The kstat module.
project_caps or
zone_caps
kstat class, for use with the kstat -c option.
cpucaps_project_id or
cpucaps_zone_id
kstat name, for use with the kstat -n option. id is the project or zone identifier.
The following fields are displayed in response to a
kstat(1M) command requesting statistics for all CPU caps.
module
In this usage of kstat, this field will have the value caps.
name
As described above, cpucaps_project_id or cpucaps_zone_id
above_sec
Total time, in seconds, spent above the cap.
below_sec
Total time, in seconds, spent below the cap.
maxusage
Maximum observed CPU usage.
nwait
Number of threads on cap wait queue.
usage
Current aggregated CPU usage for all threads belonging to a capped project or zone, in terms of a percentage of a single CPU.
value
The cap value, in terms of a percentage of a single CPU.
zonename
Name of the zone for which statistics are displayed.
See
EXAMPLES for sample output from a
kstat command.