usr/src/man/man1m/zonecfg.1m

'\" te
.\" Copyright (c) 2004, 2009 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2013 Joyent, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ZONECFG 1M "Feb 28, 2014"
.SH NAME
zonecfg \- set up zone configuration
.SH SYNOPSIS
.LP
.nf
\fBzonecfg\fR \fB-z\fR \fIzonename\fR
.fi

.LP
.nf
\fBzonecfg\fR \fB-z\fR \fIzonename\fR \fIsubcommand\fR
.fi

.LP
.nf
\fBzonecfg\fR \fB-z\fR \fIzonename\fR \fB-f\fR \fIcommand_file\fR
.fi

.LP
.nf
\fBzonecfg\fR help
.fi

.SH DESCRIPTION
.sp
.LP
The \fBzonecfg\fR utility creates and modifies the configuration of a zone.
Zone configuration consists of a number of resources and properties.
.sp
.LP
To simplify the user interface, \fBzonecfg\fR uses the concept of a scope. The
default scope is global.
.sp
.LP
The following synopsis of the \fBzonecfg\fR command is for interactive usage:
.sp
.in +2
.nf
zonecfg \fB-z\fR \fIzonename subcommand\fR
.fi
.in -2
.sp

.sp
.LP
Parameters changed through \fBzonecfg\fR do not affect a running zone. The zone
must be rebooted for the changes to take effect.
.sp
.LP
In addition to creating and modifying a zone, the \fBzonecfg\fR utility can
also be used to persistently specify the resource management settings for the
global zone.
.sp
.LP
In the following text, "rctl" is used as an abbreviation for "resource
control". See \fBresource_controls\fR(5).
.sp
.LP
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 \fBzonecfg\fR properties and resources. See the brand-specific man page for
more details on each brand. For an overview of brands, see the \fBbrands\fR(5)
man page.
.SS "Resources"
.sp
.LP
The following resource types are supported:
.sp
.ne 2
.na
\fB\fBattr\fR\fR
.ad
.sp .6
.RS 4n
Generic attribute.
.RE

.sp
.ne 2
.na
\fB\fBcapped-cpu\fR\fR
.ad
.sp .6
.RS 4n
Limits for CPU usage.
.RE

.sp
.ne 2
.na
\fB\fBcapped-memory\fR\fR
.ad
.sp .6
.RS 4n
Limits for physical, swap, and locked memory.
.RE

.sp
.ne 2
.na
\fB\fBdataset\fR\fR
.ad
.sp .6
.RS 4n
\fBZFS\fR dataset.
.RE

.sp
.ne 2
.na
\fB\fBdedicated-cpu\fR\fR
.ad
.sp .6
.RS 4n
Subset of the system's processors dedicated to this zone while it is running.
.RE

.sp
.ne 2
.na
\fB\fBdevice\fR\fR
.ad
.sp .6
.RS 4n
Device.
.RE

.sp
.ne 2
.na
\fB\fBfs\fR\fR
.ad
.sp .6
.RS 4n
file-system
.RE

.sp
.ne 2
.na
\fB\fBnet\fR\fR
.ad
.sp .6
.RS 4n
Network interface.
.RE

.sp
.ne 2
.na
\fB\fBrctl\fR\fR
.ad
.sp .6
.RS 4n
Resource control.
.RE

.SS "Properties"
.sp
.LP
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.
.sp
.LP
The following properties are supported:
.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBzonename\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBzonepath\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBautoboot\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBbootargs\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBpool\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBlimitpriv\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBbrand\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBcpu-shares\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBhostid\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBmax-lwps\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBmax-msg-ids\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBmax-sem-ids\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBmax-shm-ids\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBmax-shm-memory\fR
.RE

.sp
.ne 2
.na
\fB(global)\fR
.ad
.sp .6
.RS 4n
\fBscheduling-class\fR
.RE

.sp
.ne 2
.na
.B (global)
.ad
.sp .6
.RS 4n
.B fs-allowed
.RE

.sp
.ne 2
.na
\fB\fBfs\fR\fR
.ad
.sp .6
.RS 4n
\fBdir\fR, \fBspecial\fR, \fBraw\fR, \fBtype\fR, \fBoptions\fR
.RE

.sp
.ne 2
.na
\fB\fBnet\fR\fR
.ad
.sp .6
.RS 4n
\fBaddress\fR, \fBphysical\fR, \fBdefrouter\fR
.RE

.sp
.ne 2
.na
\fB\fBdevice\fR\fR
.ad
.sp .6
.RS 4n
\fBmatch\fR
.RE

.sp
.ne 2
.na
\fB\fBrctl\fR\fR
.ad
.sp .6
.RS 4n
\fBname\fR, \fBvalue\fR
.RE

.sp
.ne 2
.na
\fB\fBattr\fR\fR
.ad
.sp .6
.RS 4n
\fBname\fR, \fBtype\fR, \fBvalue\fR
.RE

.sp
.ne 2
.na
\fB\fBdataset\fR\fR
.ad
.sp .6
.RS 4n
\fBname\fR
.RE

.sp
.ne 2
.na
\fB\fBdedicated-cpu\fR\fR
.ad
.sp .6
.RS 4n
\fBncpus\fR, \fBimportance\fR
.RE

.sp
.ne 2
.na
\fB\fBcapped-memory\fR\fR
.ad
.sp .6
.RS 4n
\fBphysical\fR, \fBswap\fR, \fBlocked\fR
.RE

.sp
.ne 2
.na
\fB\fBcapped-cpu\fR\fR
.ad
.sp .6
.RS 4n
\fBncpus\fR
.RE

.sp
.LP
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:
.sp
.in +2
.nf
(<\fIname\fR>=<\fIvalue\fR>,<\fIname\fR>=<\fIvalue\fR>,...)
.fi
.in -2
.sp

.sp
.LP
where each <\fIvalue\fR> is simple, and the <\fIname\fR> strings are unique
within a given property. Lists have the syntax:
.sp
.in +2
.nf
[<\fIvalue\fR>,...]
.fi
.in -2
.sp

.sp
.LP
where each <\fIvalue\fR> 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 "[]").
.sp
.LP
In interpreting property values, \fBzonecfg\fR accepts regular expressions as
specified in \fBfnmatch\fR(5). See \fBEXAMPLES\fR.
.sp
.LP
The property types are described as follows:
.sp
.ne 2
.na
\fBglobal: \fBzonename\fR\fR
.ad
.sp .6
.RS 4n
The name of the zone.
.RE

.sp
.ne 2
.na
\fBglobal: \fBzonepath\fR\fR
.ad
.sp .6
.RS 4n
Path to zone's file system.
.RE

.sp
.ne 2
.na
\fBglobal: \fBautoboot\fR\fR
.ad
.sp .6
.RS 4n
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
\fBsvcadm\fR command, such as:
.sp
.in +2
.nf
# \fBsvcadm enable svc:/system/zones:default\fR
.fi
.in -2
.sp

Replace \fBenable\fR with \fBdisable\fR to disable the zones service. See
\fBsvcadm\fR(1M).
.RE

.sp
.ne 2
.na
\fBglobal: \fBbootargs\fR\fR
.ad
.sp .6
.RS 4n
Arguments (options) to be passed to the zone bootup, unless options are
supplied to the "\fBzoneadm boot\fR" command, in which case those take
precedence. The valid arguments are described in \fBzoneadm\fR(1M).
.RE

.sp
.ne 2
.na
\fBglobal: \fBpool\fR\fR
.ad
.sp .6
.RS 4n
Name of the resource pool that this zone must be bound to when booted. This
property is incompatible with the \fBdedicated-cpu\fR resource.
.RE

.sp
.ne 2
.na
\fBglobal: \fBlimitpriv\fR\fR
.ad
.sp .6
.RS 4n
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
\fBpriv_str_to_set\fR(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
\fBzones\fR(5). A missing or empty property is equivalent to this same set of
safe privileges.
.sp
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. \fBzoneadm\fR(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.
.sp
See \fBprivileges\fR(5) for a description of privileges. The command "\fBppriv
-l\fR" (see \fBppriv\fR(1)) produces a list of all Solaris privileges. You can
specify privileges as they are displayed by \fBppriv\fR. In
\fBprivileges\fR(5), privileges are listed in the form
PRIV_\fIprivilege_name\fR. For example, the privilege \fIsys_time\fR, as you
would specify it in this property, is listed in \fBprivileges\fR(5) as
\fBPRIV_SYS_TIME\fR.
.RE

.sp
.ne 2
.na
\fBglobal: \fBbrand\fR\fR
.ad
.sp .6
.RS 4n
The zone's brand type.
.RE

.sp
.ne 2
.na
\fBglobal: \fBip-type\fR\fR
.ad
.sp .6
.RS 4n
A zone can either share the IP instance with the global zone, which is the
default, or have its own exclusive instance of IP.
.sp
This property takes the values \fBshared\fR and \fBexclusive\fR.
.RE

.sp
.ne 2
.na
\fBglobal: \fBhostid\fR\fR
.ad
.sp .6
.RS 4n
A zone can emulate a 32-bit host identifier to ease system consolidation. A
zone's \fBhostid\fR 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 \fB0x\fR or \fB0X\fR prefix is optional. Both
uppercase and lowercase hexadecimal digits are acceptable.
.RE

.sp
.ne 2
.na
\fB\fBfs\fR: dir, special, raw, type, options\fR
.ad
.sp .6
.RS 4n
Values needed to determine how, where, and so forth to mount file systems. See
\fBmount\fR(1M), \fBmount\fR(2), \fBfsck\fR(1M), and \fBvfstab\fR(4).
.RE

.sp
.ne 2
.na
\fB\fBnet\fR: address, physical, defrouter\fR
.ad
.sp .6
.RS 4n
The network address and physical interface name of the network interface. The
network address is one of:
.RS +4
.TP
.ie t \(bu
.el o
a valid IPv4 address, optionally followed by "\fB/\fR" and a prefix length;
.RE
.RS +4
.TP
.ie t \(bu
.el o
a valid IPv6 address, which must be followed by "\fB/\fR" and a prefix length;
.RE
.RS +4
.TP
.ie t \(bu
.el o
a host name which resolves to an IPv4 address.
.RE
Note that host names that resolve to IPv6 addresses are not supported.
.sp
The physical interface name is the network interface name.
.sp
The default router is specified similarly to the network address except that it
must not be followed by a \fB/\fR (slash) and a network prefix length.
.sp
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 \fBdown\fR in the global zone, and the default router for the
interface should be specified here.
.sp
For an exclusive-IP zone, the physical property must be set and the address and
default router properties cannot be set.
.RE

.sp
.ne 2
.na
\fB\fBdevice\fR: match\fR
.ad
.sp .6
.RS 4n
Device name to match.
.RE

.sp
.ne 2
.na
\fB\fBrctl\fR: name, value\fR
.ad
.sp .6
.RS 4n
The name and \fIpriv\fR/\fIlimit\fR/\fIaction\fR triple of a resource control.
See \fBprctl\fR(1) and \fBrctladm\fR(1M). The preferred way to set rctl values
is to use the global property name associated with a specific rctl.
.RE

.sp
.ne 2
.na
\fB\fBattr\fR: name, type, value\fR
.ad
.sp .6
.RS 4n
The name, type and value of a generic attribute. The \fBtype\fR must be one of
\fBint\fR, \fBuint\fR, \fBboolean\fR or \fBstring\fR, and the value must be of
that type. \fBuint\fR means unsigned , that is, a non-negative integer.
.RE

.sp
.ne 2
.na
\fB\fBdataset\fR: name\fR
.ad
.sp .6
.RS 4n
The name of a \fBZFS\fR dataset to be accessed from within the zone. See
\fBzfs\fR(1M).
.RE

.sp
.ne 2
.na
\fBglobal: \fBcpu-shares\fR\fR
.ad
.sp .6
.RS 4n
The number of Fair Share Scheduler (FSS) shares to allocate to this zone. This
property is incompatible with the \fBdedicated-cpu\fR resource. This property
is the preferred way to set the \fBzone.cpu-shares\fR rctl.
.RE

.sp
.ne 2
.na
\fBglobal: \fBmax-lwps\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of LWPs simultaneously available to this zone. This property
is the preferred way to set the \fBzone.max-lwps\fR rctl.
.RE

.sp
.ne 2
.na
\fBglobal: \fBmax-msg-ids\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of message queue IDs allowed for this zone. This property is
the preferred way to set the \fBzone.max-msg-ids\fR rctl.
.RE

.sp
.ne 2
.na
\fBglobal: \fBmax-sem-ids\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of semaphore IDs allowed for this zone. This property is the
preferred way to set the \fBzone.max-sem-ids\fR rctl.
.RE

.sp
.ne 2
.na
\fBglobal: \fBmax-shm-ids\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of shared memory IDs allowed for this zone. This property is
the preferred way to set the \fBzone.max-shm-ids\fR rctl.
.RE

.sp
.ne 2
.na
\fBglobal: \fBmax-shm-memory\fR\fR
.ad
.sp .6
.RS 4n
The maximum amount of shared memory allowed for this zone. This property is the
preferred way to set the \fBzone.max-shm-memory\fR rctl. A scale (K, M, G, T)
can be applied to the value for this number (for example, 1M is one megabyte).
.RE

.sp
.ne 2
.na
\fBglobal: \fBscheduling-class\fR\fR
.ad
.sp .6
.RS 4n
Specifies the scheduling class used for processes running in a zone. When this
property is not specified, the scheduling class is established as follows:
.RS +4
.TP
.ie t \(bu
.el o
If the \fBcpu-shares\fR property or equivalent rctl is set, the scheduling
class FSS is used.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If neither \fBcpu-shares\fR 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.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Under any other conditions, the system default scheduling class is used.
.RE
.RE



.sp
.ne 2
.na
\fB\fBdedicated-cpu\fR: ncpus, importance\fR
.ad
.sp .6
.RS 4n
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 \fBpooladm\fR(1M)
and \fBpoolcfg\fR(1M) for more information on resource pools. The \fBncpu\fR
property can specify a single value or a range (for example, 1-4) of
processors. The \fBimportance\fR property is optional; if set, it will specify
the \fBpset.importance\fR value for use by \fBpoold\fR(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 \fBpool\fR and \fBcpu-shares\fR properties. Only a
single instance of this resource can be added to the zone.
.RE

.sp
.ne 2
.na
\fB\fBcapped-memory\fR: physical, swap, locked\fR
.ad
.sp .6
.RS 4n
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 \fBphysical\fR property sets the \fBmax-rss\fR for
this zone. This will be enforced by \fBrcapd\fR(1M) running in the global zone.
The \fBswap\fR property is the preferred way to set the \fBzone.max-swap\fR
rctl. The \fBlocked\fR property is the preferred way to set the
\fBzone.max-locked-memory\fR rctl.
.RE

.sp
.ne 2
.na
\fB\fBcapped-cpu\fR: ncpus\fR
.ad
.sp .6
.RS 4n
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, \fB\&.75\fR) or a
mixed number (whole number and fraction, for example, \fB1.25\fR). An
\fBncpu\fR value of \fB1\fR means 100% of a CPU, a value of \fB1.25\fR means
125%, \fB\&.75\fR mean 75%, and so forth. When projects within a capped zone
have their own caps, the minimum value takes precedence.
.sp
The \fBcapped-cpu\fR property is an alias for \fBzone.cpu-cap\fR resource
control and is related to the \fBzone.cpu-cap\fR resource control. See
\fBresource_controls\fR(5).
.RE

.sp
.ne 2
.na
\fBglobal: \fBfs-allowed\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.LP
The following table summarizes resources, property-names, and types:
.sp
.in +2
.nf
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
.fi
.in -2
.sp

.sp
.LP
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 (\fB-\fR), underscore (\fB_\fR), and dot
(\fB\&.\fR) 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".
.SS "Using Kernel Statistics to Monitor CPU Caps"
.sp
.LP
Using the kernel statistics (\fBkstat\fR(3KSTAT)) module \fBcaps\fR, the system
maintains information for all capped projects and zones. You can access this
information by reading kernel statistics (\fBkstat\fR(3KSTAT)), specifying
\fBcaps\fR as the \fBkstat\fR module name. The following command displays
kernel statistics for all active CPU caps:
.sp
.in +2
.nf
# \fBkstat caps::'/cpucaps/'\fR
.fi
.in -2
.sp

.sp
.LP
A \fBkstat\fR(1M) command running in a zone displays only CPU caps relevant for
that zone and for projects in that zone. See \fBEXAMPLES\fR.
.sp
.LP
The following are cap-related arguments for use with \fBkstat\fR(1M):
.sp
.ne 2
.na
\fB\fBcaps\fR\fR
.ad
.sp .6
.RS 4n
The \fBkstat\fR module.
.RE

.sp
.ne 2
.na
\fB\fBproject_caps\fR or \fBzone_caps\fR\fR
.ad
.sp .6
.RS 4n
\fBkstat\fR class, for use with the \fBkstat\fR \fB-c\fR option.
.RE

.sp
.ne 2
.na
\fB\fBcpucaps_project_\fR\fIid\fR or \fBcpucaps_zone_\fR\fIid\fR\fR
.ad
.sp .6
.RS 4n
\fBkstat\fR name, for use with the \fBkstat\fR \fB-n\fR option. \fIid\fR is the
project or zone identifier.
.RE

.sp
.LP
The following fields are displayed in response to a \fBkstat\fR(1M) command
requesting statistics for all CPU caps.
.sp
.ne 2
.na
\fB\fBmodule\fR\fR
.ad
.sp .6
.RS 4n
In this usage of \fBkstat\fR, this field will have the value \fBcaps\fR.
.RE

.sp
.ne 2
.na
\fB\fBname\fR\fR
.ad
.sp .6
.RS 4n
As described above, \fBcpucaps_project_\fR\fIid\fR or
\fBcpucaps_zone_\fR\fIid\fR
.RE

.sp
.ne 2
.na
\fB\fBabove_sec\fR\fR
.ad
.sp .6
.RS 4n
Total time, in seconds, spent above the cap.
.RE

.sp
.ne 2
.na
\fB\fBbelow_sec\fR\fR
.ad
.sp .6
.RS 4n
Total time, in seconds, spent below the cap.
.RE

.sp
.ne 2
.na
\fB\fBmaxusage\fR\fR
.ad
.sp .6
.RS 4n
Maximum observed CPU usage.
.RE

.sp
.ne 2
.na
\fB\fBnwait\fR\fR
.ad
.sp .6
.RS 4n
Number of threads on cap wait queue.
.RE

.sp
.ne 2
.na
\fB\fBusage\fR\fR
.ad
.sp .6
.RS 4n
Current aggregated CPU usage for all threads belonging to a capped project or
zone, in terms of a percentage of a single CPU.
.RE

.sp
.ne 2
.na
\fB\fBvalue\fR\fR
.ad
.sp .6
.RS 4n
The cap value, in terms of a percentage of a single CPU.
.RE

.sp
.ne 2
.na
\fB\fBzonename\fR\fR
.ad
.sp .6
.RS 4n
Name of the zone for which statistics are displayed.
.RE

.sp
.LP
See \fBEXAMPLES\fR for sample output from a \fBkstat\fR command.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR \fIcommand_file\fR\fR
.ad
.sp .6
.RS 4n
Specify the name of \fBzonecfg\fR command file. \fIcommand_file\fR is a text
file of \fBzonecfg\fR subcommands, one per line.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR \fIzonename\fR\fR
.ad
.sp .6
.RS 4n
Specify the name of a zone. Zone names are case sensitive. Zone names must
begin with an alphanumeric character and can contain alphanumeric characters,
the underscore (\fB_\fR) the hyphen (\fB-\fR), and the dot (\fB\&.\fR). The
name \fBglobal\fR and all names beginning with \fBSUNW\fR are reserved and
cannot be used.
.RE

.SH SUBCOMMANDS
.sp
.LP
You can use the \fBadd\fR and \fBselect\fR subcommands to select a specific
resource, at which point the scope changes to that resource. The \fBend\fR and
\fBcancel\fR subcommands are used to complete the resource specification, at
which time the scope is reverted back to global. Certain subcommands, such as
\fBadd\fR, \fBremove\fR and \fBset\fR, have different semantics in each scope.
.sp
.LP
\fBzonecfg\fR supports a semicolon-separated list of subcommands. For example:
.sp
.in +2
.nf
# \fBzonecfg -z myzone "add net; set physical=myvnic; end"\fR
.fi
.in -2
.sp

.sp
.LP
Subcommands which can result in destructive actions or loss of work have an
\fB-F\fR option to force the action. If input is from a terminal device, the
user is prompted when appropriate if such a command is given without the
\fB-F\fR option otherwise, if such a command is given without the \fB-F\fR
option, the action is disallowed, with a diagnostic message written to standard
error.
.sp
.LP
The following subcommands are supported:
.sp
.ne 2
.na
\fB\fBadd\fR \fIresource-type\fR (global scope)\fR
.ad
.br
.na
\fB\fBadd\fR \fIproperty-name property-value\fR (resource scope)\fR
.ad
.sp .6
.RS 4n
In the global scope, begin the specification for a given resource type. The
scope is changed to that resource type.
.sp
In the resource scope, add a property of the given name with the given value.
The syntax for property values varies with different property types. In
general, it is a simple value or a list of simple values enclosed in square
brackets, separated by commas (\fB[foo,bar,baz]\fR). See \fBPROPERTIES\fR.
.RE

.sp
.ne 2
.na
\fB\fBcancel\fR\fR
.ad
.sp .6
.RS 4n
End the resource specification and reset scope to global. Abandons any
partially specified resources. \fBcancel\fR is only applicable in the resource
scope.
.RE

.sp
.ne 2
.na
\fB\fBclear\fR \fIproperty-name\fR\fR
.ad
.sp .6
.RS 4n
Clear the value for the property.
.RE

.sp
.ne 2
.na
\fB\fBcommit\fR\fR
.ad
.sp .6
.RS 4n
Commit the current configuration from memory to stable storage. The
configuration must be committed to be used by \fBzoneadm\fR. Until the
in-memory configuration is committed, you can remove changes with the
\fBrevert\fR subcommand. The \fBcommit\fR operation is attempted automatically
upon completion of a \fBzonecfg\fR session. Since a configuration must be
correct to be committed, this operation automatically does a verify.
.RE

.sp
.ne 2
.na
\fB\fBcreate [\fR\fB-F\fR\fB] [\fR \fB-a\fR \fIpath\fR |\fB-b\fR \fB|\fR
\fB-t\fR \fItemplate\fR\fB]\fR\fR
.ad
.sp .6
.RS 4n
Create an in-memory configuration for the specified zone. Use \fBcreate\fR to
begin to configure a new zone. See \fBcommit\fR for saving this to stable
storage.
.sp
If you are overwriting an existing configuration, specify the \fB-F\fR option
to force the action. Specify the \fB-t\fR \fItemplate\fR option to create a
configuration identical to \fItemplate\fR, where \fItemplate\fR is the name of
a configured zone.
.sp
Use the \fB-a\fR \fIpath\fR option to facilitate configuring a detached zone on
a new host. The \fIpath\fR parameter is the zonepath location of a detached
zone that has been moved on to this new host. Once the detached zone is
configured, it should be installed using the "\fBzoneadm attach\fR" command
(see \fBzoneadm\fR(1M)). All validation of the new zone happens during the
\fBattach\fR process, not during zone configuration.
.sp
Use the \fB-b\fR option to create a blank configuration. Without arguments,
\fBcreate\fR applies the Sun default settings.
.RE

.sp
.ne 2
.na
\fB\fBdelete [\fR\fB-F\fR\fB]\fR\fR
.ad
.sp .6
.RS 4n
Delete the specified configuration from memory and stable storage. This action
is instantaneous, no commit is necessary. A deleted configuration cannot be
reverted.
.sp
Specify the \fB-F\fR option to force the action.
.RE

.sp
.ne 2
.na
\fB\fBend\fR\fR
.ad
.sp .6
.RS 4n
End the resource specification. This subcommand is only applicable in the
resource scope. \fBzonecfg\fR checks to make sure the current resource is
completely specified. If so, it is added to the in-memory configuration (see
\fBcommit\fR for saving this to stable storage) and the scope reverts to
global. If the specification is incomplete, it issues an appropriate error
message.
.RE

.sp
.ne 2
.na
\fB\fBexport [\fR\fB-f\fR \fIoutput-file\fR\fB]\fR\fR
.ad
.sp .6
.RS 4n
Print configuration to standard output. Use the \fB-f\fR option to print the
configuration to \fIoutput-file\fR. This option produces output in a form
suitable for use in a command file.
.RE

.sp
.ne 2
.na
\fB\fBhelp [usage] [\fIsubcommand\fR] [syntax] [\fR\fIcommand-name\fR\fB]\fR\fR
.ad
.sp .6
.RS 4n
Print general help or help about given topic.
.RE

.sp
.ne 2
.na
\fB\fBinfo zonename | zonepath | autoboot | brand | pool | limitpriv\fR\fR
.ad
.br
.na
\fB\fBinfo [\fR\fIresource-type\fR
\fB[\fR\fIproperty-name\fR\fB=\fR\fIproperty-value\fR\fB]*]\fR\fR
.ad
.sp .6
.RS 4n
Display information about the current configuration. If \fIresource-type\fR is
specified, displays only information about resources of the relevant type. If
any \fIproperty-name\fR value pairs are specified, displays only information
about resources meeting the given criteria. In the resource scope, any
arguments are ignored, and \fBinfo\fR displays information about the resource
which is currently being added or modified.
.RE

.sp
.ne 2
.na
\fB\fBremove\fR \fIresource-type\fR\fB{\fR\fIproperty-name\fR\fB=\fR\fIproperty
-value\fR\fB}\fR(global scope)\fR
.ad
.sp .6
.RS 4n
In the global scope, removes the specified resource. The \fB[]\fR syntax means
0 or more of whatever is inside the square braces. If you want only to remove a
single instance of the resource, you must specify enough property name-value
pairs for the resource to be uniquely identified. If no property name-value
pairs are specified, all instances will be removed. If there is more than one
pair is specified, a confirmation is required, unless you use the \fB-F\fR
option.
.RE

.sp
.ne 2
.na
\fB\fBselect\fR \fIresource-type\fR
\fB{\fR\fIproperty-name\fR\fB=\fR\fIproperty-value\fR\fB}\fR\fR
.ad
.sp .6
.RS 4n
Select the resource of the given type which matches the given
\fIproperty-name\fR \fIproperty-value\fR pair criteria, for modification. This
subcommand is applicable only in the global scope. The scope is changed to that
resource type. The \fB{}\fR syntax means 1 or more of whatever is inside the
curly braces. You must specify enough \fIproperty -name property-value\fR pairs
for the resource to be uniquely identified.
.RE

.sp
.ne 2
.na
\fB\fBset\fR \fIproperty-name\fR\fB=\fR\fIproperty\fR\fB-\fR\fIvalue\fR\fR
.ad
.sp .6
.RS 4n
Set a given property name to the given value. Some properties (for example,
\fBzonename\fR and \fBzonepath\fR) are global while others are
resource-specific. This subcommand is applicable in both the global and
resource scopes.
.RE

.sp
.ne 2
.na
\fB\fBverify\fR\fR
.ad
.sp .6
.RS 4n
Verify the current configuration for correctness:
.RS +4
.TP
.ie t \(bu
.el o
All resources have all of their required properties specified.
.RE
.RS +4
.TP
.ie t \(bu
.el o
A \fBzonepath\fR is specified.
.RE
.RE

.sp
.ne 2
.na
\fB\fBrevert\fR \fB[\fR\fB-F\fR\fB]\fR\fR
.ad
.sp .6
.RS 4n
Revert the configuration back to the last committed state. The \fB-F\fR option
can be used to force the action.
.RE

.sp
.ne 2
.na
\fB\fBexit [\fR\fB-F\fR\fB]\fR\fR
.ad
.sp .6
.RS 4n
Exit the \fBzonecfg\fR session. A commit is automatically attempted if needed.
You can also use an \fBEOF\fR character to exit \fBzonecfg\fR. The \fB-F\fR
option can be used to force the action.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating the Environment for a New Zone
.sp
.LP
In the following example, \fBzonecfg\fR creates the environment for a new zone.
\fB/usr/local\fR is loopback mounted from the global zone into
\fB/opt/local\fR. \fB/opt/sfw\fR is loopback mounted from the global zone,
three logical network interfaces are added, and a limit on the number of
fair-share scheduler (FSS) CPU shares for a zone is set using the \fBrctl\fR
resource type. The example also shows how to select a given resource for
modification.

.sp
.in +2
.nf
example# \fBzonecfg -z myzone3\fR
my-zone3: No such zone configured
Use 'create' to begin configuring a new zone.
zonecfg:myzone3> \fBcreate\fR
zonecfg:myzone3> \fBset zonepath=/export/home/my-zone3\fR
zonecfg:myzone3> \fBset autoboot=true\fR
zonecfg:myzone3> \fBadd fs\fR
zonecfg:myzone3:fs> \fBset dir=/usr/local\fR
zonecfg:myzone3:fs> \fBset special=/opt/local\fR
zonecfg:myzone3:fs> \fBset type=lofs\fR
zonecfg:myzone3:fs> \fBadd options [ro,nodevices]\fR
zonecfg:myzone3:fs> \fBend\fR
zonecfg:myzone3> \fBadd fs\fR
zonecfg:myzone3:fs> \fBset dir=/mnt\fR
zonecfg:myzone3:fs> \fBset special=/dev/dsk/c0t0d0s7\fR
zonecfg:myzone3:fs> \fBset raw=/dev/rdsk/c0t0d0s7\fR
zonecfg:myzone3:fs> \fBset type=ufs\fR
zonecfg:myzone3:fs> \fBend\fR
zonecfg:myzone3> \fBadd net\fR
zonecfg:myzone3:net> \fBset address=192.168.0.1/24\fR
zonecfg:myzone3:net> \fBset physical=eri0\fR
zonecfg:myzone3:net> \fBend\fR
zonecfg:myzone3> \fBadd net\fR
zonecfg:myzone3:net> \fBset address=192.168.1.2/24\fR
zonecfg:myzone3:net> \fBset physical=eri0\fR
zonecfg:myzone3:net> \fBend\fR
zonecfg:myzone3> \fBadd net\fR
zonecfg:myzone3:net> \fBset address=192.168.2.3/24\fR
zonecfg:myzone3:net> \fBset physical=eri0\fR
zonecfg:myzone3:net> \fBend\fR
zonecfg:my-zone3> \fBset cpu-shares=5\fR
zonecfg:my-zone3> \fBadd capped-memory\fR
zonecfg:my-zone3:capped-memory> \fBset physical=50m\fR
zonecfg:my-zone3:capped-memory> \fBset swap=100m\fR
zonecfg:my-zone3:capped-memory> \fBend\fR
zonecfg:myzone3> \fBexit\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreating a Non-Native Zone
.sp
.LP
The following example creates a new Linux zone:

.sp
.in +2
.nf
example# \fBzonecfg -z lxzone\fR
lxzone: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:lxzone> \fBcreate -t SUNWlx\fR
zonecfg:lxzone> \fBset zonepath=/export/zones/lxzone\fR
zonecfg:lxzone> \fBset autoboot=true\fR
zonecfg:lxzone> \fBexit\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCreating an Exclusive-IP Zone
.sp
.LP
The following example creates a zone that is granted exclusive access to
\fBbge1\fR and \fBbge33000\fR and that is isolated at the IP layer from the
other zones configured on the system.

.sp
.LP
The IP addresses and routing is configured inside the new zone using
\fBsysidtool\fR(1M).

.sp
.in +2
.nf
example# \fBzonecfg -z excl\fR
excl: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:excl> \fBcreate\fR
zonecfg:excl> \fBset zonepath=/export/zones/excl\fR
zonecfg:excl> \fBset ip-type=exclusive\fR
zonecfg:excl> \fBadd net\fR
zonecfg:excl:net> \fBset physical=bge1\fR
zonecfg:excl:net> \fBend\fR
zonecfg:excl> \fBadd net\fR
zonecfg:excl:net> \fBset physical=bge33000\fR
zonecfg:excl:net> \fBend\fR
zonecfg:excl> \fBexit\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRAssociating a Zone with a Resource Pool
.sp
.LP
The following example shows how to associate an existing zone with an existing
resource pool:

.sp
.in +2
.nf
example# \fBzonecfg -z myzone\fR
zonecfg:myzone> \fBset pool=mypool\fR
zonecfg:myzone> \fBexit\fR
.fi
.in -2
.sp

.sp
.LP
For more information about resource pools, see \fBpooladm\fR(1M) and
\fBpoolcfg\fR(1M).

.LP
\fBExample 5 \fRChanging the Name of a Zone
.sp
.LP
The following example shows how to change the name of an existing zone:

.sp
.in +2
.nf
example# \fBzonecfg -z myzone\fR
zonecfg:myzone> \fBset zonename=myzone2\fR
zonecfg:myzone2> \fBexit\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRChanging the Privilege Set of a Zone
.sp
.LP
The following example shows how to change the set of privileges an existing
zone's processes will be limited to the next time the zone is booted. In this
particular case, the privilege set will be the standard safe set of privileges
a zone normally has along with the privilege to change the system date and
time:

.sp
.in +2
.nf
example# \fBzonecfg -z myzone\fR
zonecfg:myzone> \fBset limitpriv="default,sys_time"\fR
zonecfg:myzone2> \fBexit\fR
.fi
.in -2
.sp

.LP
\fBExample 7 \fRSetting the \fBzone.cpu-shares\fR Property for the Global Zone
.sp
.LP
The following command sets the \fBzone.cpu-shares\fR property for the global
zone:

.sp
.in +2
.nf
example# \fBzonecfg -z global\fR
zonecfg:global> \fBset cpu-shares=5\fR
zonecfg:global> \fBexit\fR
.fi
.in -2
.sp

.LP
\fBExample 8 \fRUsing Pattern Matching
.sp
.LP
The following commands illustrate \fBzonecfg\fR support for pattern matching.
In the zone \fBflexlm\fR, enter:

.sp
.in +2
.nf
zonecfg:flexlm> \fBadd device\fR
zonecfg:flexlm:device> \fBset match="/dev/cua/a00[2-5]"\fR
zonecfg:flexlm:device> \fBend\fR
.fi
.in -2
.sp

.sp
.LP
In the global zone, enter:

.sp
.in +2
.nf
global# \fBls /dev/cua\fR
a     a000  a001  a002  a003  a004  a005  a006  a007  b
.fi
.in -2
.sp

.sp
.LP
In the zone \fBflexlm\fR, enter:

.sp
.in +2
.nf
flexlm# \fBls /dev/cua\fR
a002  a003  a004  a005
.fi
.in -2
.sp

.LP
\fBExample 9 \fRSetting a Cap for a Zone to Three CPUs
.sp
.LP
The following sequence uses the \fBzonecfg\fR command to set the CPU cap for a
zone to three CPUs.

.sp
.in +2
.nf
zonecfg:myzone> \fBadd capped-cpu\fR
zonecfg:myzone>capped-cpu> \fBset ncpus=3\fR
zonecfg:myzone>capped-cpu>capped-cpu> \fBend\fR
.fi
.in -2
.sp

.sp
.LP
The preceding sequence, which uses the capped-cpu property, is equivalent to
the following sequence, which makes use of the \fBzone.cpu-cap\fR resource
control.

.sp
.in +2
.nf
zonecfg:myzone> \fBadd rctl\fR
zonecfg:myzone:rctl> \fBset name=zone.cpu-cap\fR
zonecfg:myzone:rctl> \fBadd value (priv=privileged,limit=300,action=none)\fR
zonecfg:myzone:rctl> \fBend\fR
.fi
.in -2
.sp

.LP
\fBExample 10 \fRUsing \fBkstat\fR to Monitor CPU Caps
.sp
.LP
The following command displays information about all CPU caps.

.sp
.in +2
.nf
# \fBkstat -n /cpucaps/\fR
module: caps                            instance: 0
name:   cpucaps_project_0               class:    project_caps
        above_sec                       0
        below_sec                       2157
        crtime                          821.048183159
        maxusage                        2
        nwait                           0
        snaptime                        235885.637253027
        usage                           0
        value                           18446743151372347932
        zonename                        global

module: caps                            instance: 0
name:   cpucaps_project_1               class:    project_caps
        above_sec                       0
        below_sec                       0
        crtime                          225339.192787265
        maxusage                        5
        nwait                           0
        snaptime                        235885.637591677
        usage                           5
        value                           18446743151372347932
        zonename                        global

module: caps                            instance: 0
name:   cpucaps_project_201             class:    project_caps
        above_sec                       0
        below_sec                       235105
        crtime                          780.37961782
        maxusage                        100
        nwait                           0
        snaptime                        235885.637789687
        usage                           43
        value                           100
        zonename                        global

module: caps                            instance: 0
name:   cpucaps_project_202             class:    project_caps
        above_sec                       0
        below_sec                       235094
        crtime                          791.72983782
        maxusage                        100
        nwait                           0
        snaptime                        235885.637967512
        usage                           48
        value                           100
        zonename                        global

module: caps                            instance: 0
name:   cpucaps_project_203             class:    project_caps
        above_sec                       0
        below_sec                       235034
        crtime                          852.104401481
        maxusage                        75
        nwait                           0
        snaptime                        235885.638144304
        usage                           47
        value                           100
        zonename                        global

module: caps                            instance: 0
name:   cpucaps_project_86710           class:    project_caps
        above_sec                       22
        below_sec                       235166
        crtime                          698.441717859
        maxusage                        101
        nwait                           0
        snaptime                        235885.638319871
        usage                           54
        value                           100
        zonename                        global

module: caps                            instance: 0
name:   cpucaps_zone_0                  class:    zone_caps
        above_sec                       100733
        below_sec                       134332
        crtime                          821.048177123
        maxusage                        207
        nwait                           2
        snaptime                        235885.638497731
        usage                           199
        value                           200
        zonename                        global

module: caps                            instance: 1
name:   cpucaps_project_0               class:    project_caps
        above_sec                       0
        below_sec                       0
        crtime                          225360.256448422
        maxusage                        7
        nwait                           0
        snaptime                        235885.638714404
        usage                           7
        value                           18446743151372347932
        zonename                        test_001

module: caps                            instance: 1
name:   cpucaps_zone_1                  class:    zone_caps
        above_sec                       2
        below_sec                       10524
        crtime                          225360.256440278
        maxusage                        106
        nwait                           0
        snaptime                        235885.638896443
        usage                           7
        value                           100
        zonename                        test_001
.fi
.in -2
.sp

.LP
\fBExample 11 \fRDisplaying CPU Caps for a Specific Zone or Project
.sp
.LP
Using the \fBkstat\fR \fB-c\fR and \fB-i\fR options, you can display CPU caps
for a specific zone or project, as below. The first command produces a display
for a specific project, the second for the same project within zone 1.

.sp
.in +2
.nf
# \fBkstat -c project_caps\fR

# \fBkstat -c project_caps -i 1\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
Invalid usage.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Volatile
.TE

.SH SEE ALSO
.sp
.LP
\fBppriv\fR(1), \fBprctl\fR(1), \fBzlogin\fR(1), \fBkstat\fR(1M),
\fBmount\fR(1M), \fBpooladm\fR(1M), \fBpoolcfg\fR(1M), \fBpoold\fR(1M),
\fBrcapd\fR(1M), \fBrctladm\fR(1M), \fBsvcadm\fR(1M), \fBsysidtool\fR(1M),
\fBzfs\fR(1M), \fBzoneadm\fR(1M), \fBpriv_str_to_set\fR(3C),
\fBkstat\fR(3KSTAT), \fBvfstab\fR(4), \fBattributes\fR(5), \fBbrands\fR(5),
\fBfnmatch\fR(5), \fBlx\fR(5), \fBprivileges\fR(5), \fBresource_controls\fR(5),
\fBzones\fR(5)
.sp
.LP
\fISystem Administration Guide: Solaris Containers-Resource Management, and
Solaris Zones\fR
.SH NOTES
.sp
.LP
All character data used by \fBzonecfg\fR must be in US-ASCII encoding.