JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
man pages section 1M: System Administration Commands     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

Introduction

System Administration Commands - Part 1

System Administration Commands - Part 2

System Administration Commands - Part 3

umount_smbfs(1M)

unlink(1M)

unshare(1M)

unshareall(1M)

unshare_nfs(1M)

update_drv(1M)

useradd(1M)

userdel(1M)

usermod(1M)

utmp2wtmp(1M)

utmpd(1M)

uucheck(1M)

uucico(1M)

uucleanup(1M)

uucpd(1M)

uusched(1M)

Uutry(1M)

uutry(1M)

uuxqt(1M)

vbiosd(1M)

vdiskadm(1M)

vdpd(1M)

virt-convert(1M)

virtinfo(1M)

vmstat(1M)

vmtasks(1M)

vntsd(1M)

volcopy(1M)

volcopy_ufs(1M)

vrrpadm(1M)

vrrpd(1M)

vscanadm(1M)

vscand(1M)

vtdaemon(1M)

wall(1M)

wanboot_keygen(1M)

wanboot_keymgmt(1M)

wanboot_p12split(1M)

wanbootutil(1M)

wbemadmin(1M)

wbemconfig(1M)

wbemlogviewer(1M)

wcadmin(1M)

whodo(1M)

wpad(1M)

wracct(1M)

wtmpfix(1M)

wusbadm(1M)

ypbind(1M)

ypinit(1M)

ypmake(1M)

ypmap2src(1M)

yppasswdd(1M)

yppoll(1M)

yppush(1M)

ypserv(1M)

ypserv_resolv(1M)

ypset(1M)

ypstart(1M)

ypstop(1M)

ypupdated(1M)

ypxfr(1M)

ypxfr_1perday(1M)

ypxfr_1perhour(1M)

ypxfr_2perday(1M)

ypxfrd(1M)

zdb(1M)

zdump(1M)

zfs(1M)

zfs_allow(1M)

zfs_encrypt(1M)

zfs_share(1M)

zic(1M)

zoneadm(1M)

zoneadmd(1M)

zonecfg(1M)

zonep2vchk(1M)

zonestatd(1M)

zpool(1M)

zstreamdump(1M)

zonecfg

- set up zone configuration

Synopsis

zonecfg -z zonename
zonecfg -z zonename subcommand
zonecfg -z zonename -f command_file
zonecfg help

Description

The zonecfg utility creates, modifies, and lists the configuration of a zone. The creation and modification functions are only available to authorized users and require that the process is executed with an effective user ID of root. Otherwise it runs in read-only mode.

A zone's configuration consists of a number of resources and properties.

To simplify the user interface, zonecfg uses the concept of a scope. The default scope is global.

The following synopsis of the zonecfg command is for interactive usage:

zonecfg -z zonename subcommand

Parameters changed through zonecfg do not affect a running zone. The zone must be rebooted for the changes to take effect.

In addition to creating and modifying a zone, the zonecfg 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 resource_controls(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 zonecfg properties and resources. See the brand-specific man page for more details on each brand. For an overview of brands, see the brands(5) man page.

Resources

The following resource types are supported:

attr

Generic attribute.

capped-cpu

Limits for CPU usage.

capped-memory

Limits for physical, swap, and locked memory.

dataset

ZFS dataset.

dedicated-cpu

Subset of the system's processors dedicated to this zone while it is running.

device

Device.

fs

file-system

net

Network interface.

anet

Automatic network interface.

admin

Delegated administrator.

rctl

Resource control.

rootzpool

Dedicated ZFS zpool for zone installation.

zpool

ZFS zpool delegated to the zone.

Sparse and Whole Root Non-Global Zones

Previous releases of Solaris offered the notion of sparse root zones. This functionality was intimately associated with the SVr4 packaging system and intended to save disk space and reduce administrative effort.

The new packaging system, IPS, provides more flexibility when choosing which packages to install in a zone. This, along with advances in file system technology (notable among which is ZFS deduplication), means that it was most sensible to remove sparse root zones. The benefits of sparse root zones are provided for all zones by means of the combination of IPS packaging and file system advances.

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

(global)

max-sem-ids

(global)

max-shm-ids

(global)

max-shm-memory

(global)

scheduling-class

(global)

fs-allowed

(global)

file-mac-profile

fs

dir, special, raw, type, options

net

address, allowed-address, configure-allowed-address, physical, defrouter

anet

linkname, lower-link, allowed-address, auto-mac-address, configure-allowed-address, defrouter, mac-address, mac-slot, mac-prefix, mtu, maxbw, priority, vlan-id, vsi-typeid, vsi-vers, vsi-mgrid, rxfanout, rxrings, txrings, link-protection, allowed-dhcp-cids, pkey, linkmode, etsbw-lcl, cos

device

match, allow-partition, allow-raw-io

rctl

name, value

attr

name, type, value

dataset

name, alias

dedicated-cpu

ncpus, importance

capped-memory

physical, swap, locked

capped-cpu

ncpus

admin

user, auths

rootzpool

storage

zpool

storage, name

As for the property values that 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 have its own exclusive instance of IP (the default) or share the IP instance with the global zone. In the default zone template, SYSdefault, ip-type is set to exclusive. In the also-supplied SYSdefault-shared-ip template, ip-type is set to shared.

This property takes the values exclusive and shared.

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.

global: fs-allowed

A comma-separated list of additional file systems that can be mounted within the zone; for example, ufs,pcfs. By default, only hsfs(7FS) and network file systems can be mounted.

This property does not apply to file systems mounted into the zone by means of add fs or add dataset.


Caution

Caution - Allowing filesystem mounts other than the default might allow the zone administrator to compromise the system with a bogus filesystem image and is not supported.


global: file-mac-profile

Define which parts of the filesystem are exempted from the read-only policy, that is, which parts of the filesystem the zone is allowed to write to.

There are currently four supported values for this property: none, strict, fixed-configuration, and flexible-configuration.

none makes the zone exactly the same as a normal, r/w zone. strict allows no exceptions to the read-only policy. fixed-configuration allows the zone to write to files in and below /var, except directories containing configuration files:

/var/ld
/var/lib/postrun
/var/pkg
/var/spool/cron,
/var/spool/postrun
/var/svc/manifest
/var/svc/profiles

flexible-configuration is equal to fixed-configuration, but allows writing to files in /etc in addition.

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, allowed-address, configure-allowed-address, physical, defrouter

The net resource represents the assignment of a physical network resource to a zone. The resource must exists in the global zone prior to the assignment.

The network address and physical interface name of the network interface. The network address is one of:

  • a valid IPv4 address, optionally followed by “/” and a prefix length;

  • a valid IPv6 address, which must be followed by “/” and a prefix length;

  • 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 value for the optional default router is specified similarly to the network address except that it must not be followed by a / (slash) and a network prefix length. To enable correct use of the defrouter functionality, the zones that use the property must be on a different subnet from the subnet on which the global zone resides. Also, each zone (or set of zones) that uses a different defrouter setting must be on a different subnet.

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. The allowed-address property cannot be set for a shared-IP zone.

For an exclusive-IP zone, the physical property must be set and the address property must not be set. Optionally, the set of IP addresses that the exclusive-IP zone can use might be constrained by specifying the allowed-address property. If allowed-address has not been specified, then the exclusive-IP zone can use any IP address on the associated physical interface for the net resource. Otherwise, when allowed-address is specified, the exclusive-IP zone cannot use IP addresses that are not in the allowed-address list for the physical address. If configure-allowed-address is set to true, the addresses specified by allowed-address are automatically configured on the interface each time the zone boots. When it is set to false, the allowed-address will not be configured on zone boot. By default, configure-allowed-address is set to true when an allowed-address is specified. In addition, when the allowed-address list has been populated, the defrouter property can also be optionally specified. However, if the defrouter value is specified and configure-allowed-address is set to false, the defrouter value will be ignored and an appropriate warning message will be shown. The interface specified for the physical property must not be in use in the global zone. If an allowed-address and default router are specified by means of zonecfg, these will be applied to the interface when it is enabled by means of ipadm(1M) in the non-global, exclusive-IP zone, typically during zone boot. The non-global exclusive-IP zone will not be able to apply any other addresses to that interface, nor will it be able to transmit packets with a different source address for the specified IP version. A default router set up by means of zonecfg cannot be persistently deleted from within the non-global exclusive-IP zone using the -p flag with route(1M).

Note that a single datalink cannot be shared among multiple exclusive-IP zones.

anet: linkname, lower-link, allowed-address, auto-mac-address, configure-allowed-address, defrouter, mac-address, mac-slot, mac-prefix, mtu, maxbw, priority, vlan-id, vsi-typeid, vsi-vers, vsi-mgrid, rxfanout, rxrings, txrings, link-protection, allowed-dhcp-cids, pkey, linkmode, etsbw-lcl,cos

The anet resource represents the automatic creation of a network resource for an exclusive-IP zone. When zonecfg creates a zone using the default SYSdefault template, an anet resource with the following properties is automatically included in the zone configuration:

linkname=net0
lower-link=auto
mac-address=random
link-protection=mac-nospoof

When such a zone boots, a temporary VNIC or IPoIB datalink is automatically created for the zone. The VNIC or the IPoIB datalink is deleted when the zone halts.

The supported properties are described below. All these properties are optional. Only the global zone is allowed to modify the automatically created VNIC or IPoIB datalink or its properties. If a property set in zonecfg cannot be assigned to the VNIC or IPoIB datalink at its creation time, the zone will fail to boot.

linkname

Specify a name for the automatically created VNIC or IPoIB datalink. By default, this property will be automatically set to the first available name (for the zone) of the form netN, where N is a non-negative integer. For example: net0, net1, and so on. The info subcommand displays the automatically selected linkname.

Multiple zones, including the global zone, can have links with the same name at the same time.

lower-link

Specify the link over which the VNIC or IPoIB will be created. This property has a default value of auto for Ethernet links. If pkey is specified, lower-link must be specified with a valid IPoIB phys class datalink. The administrator may explicitly specify a value upon adding an anet resource. The link can be any link accepted as an argument to dladm create-vnic's -l option or to dladm create-part's -l option (see dladm(1M)). If this property is set to a linkname (other than auto) and that link does not exist, then the zone will fail to boot. When set to auto, the zoneadmd(1M) daemon will automatically choose the link over which the VNIC will be created each time the zone boots. All IPoIB datalinks will will be skipped when selecting the default lower-link for creating the VNIC automatically during boot. A link will be chosen using the following heuristic:

  1. A link aggregation that has a link state of up.

  2. Of the physical Ethernet links that have a link state of up, the one with the alphabetically smallest link name.

  3. If none is up, the datalink named net0 is used if it exists.

If none of the above can be satisfied, the zone will fail to boot.

allowed-address

See the description of the allowed-address property for exclusive-IP zones in the net resource.

auto-mac-address

Holds the value of the randomly generated MAC address when the mac-address property (see below) is set to random or auto, so that the zone reacquires the same address on a persistent basis. To reset the randomly generated address, an administrator needs to clear this property.

configure-allowed-address

See the description of the configure-allowed-address property for exclusive-IP zones in the net resource.

cos

The 802.1p priority associated with the datalink. See dladm(1M) for details on this property.

defrouter

See the description of the defrouter property for exclusive-IP zones in the net resource.

etsbw-lcl

Indicates the ETS bandwidth on the TX side. See dladm(1M) for details on this property.

mac-address

Set the VNIC's MAC address based on the specified value or keyword. If the value is not a keyword, it is interpreted as a unicast MAC address. This property is not supported on IPoIB datalinks. The supported keywords are:

  • factory: Assign a factory MAC address to the VNIC. When a factory MAC address is requested, the mac-slot property can be used to specify the MAC address slot identifier. Otherwise, the next available factory MAC address will be used.

  • random: Assign a random MAC address to the VNIC. Use the mac-prefix property to specify a prefix. Otherwise, a default prefix consisting of a valid IEEE OUI with the local bit set will be used. This is the default value.

  • auto: Try to use a factory MAC address first. If none is available, assign a random MAC address.

If a random MAC address is selected, then the address generated will be preserved across zone boots and zone detach/attach. This will allow zones to retain their DHCP leases by maintaining stable client IDs, and otherwise take advantage of other benefits of having stable MAC addresses.

mac-prefix

Specify the MAC address prefix if a random MAC address is requested. Otherwise this property is ignored. This property is not valid over IPoIB datalinks.

mac-slot

Specify the MAC address slot identifier if the factory MAC address is requested. Otherwise this property is ignored. This property is not valid over IPoIB datalinks.

mtu

The maximum transmission unit of the VNIC in bytes. See mtu property in dladm(1M).

maxbw

Specify the full duplex bandwidth for the VNIC. See maxbw property in dladm(1M). By default, the VNIC will use the maxbw set on the lower-link and if none is set then there is no bandwidth limit.

priority

Specify the relative priority for the VNIC. See the priority property in dladm(1M) for supported values and default.

vlan-id

Enable VLAN tagging for this VNIC and specify a id for the VLAN tag. There is no default value which means if this property is not set then the VNIC does not participate in any VLAN. This property is not supported on IPoIB datalinks.

vsi-typeid

Specify the VSI Type ID associated with a VNIC. See description in dladm(1M).

vsi-vers

Specify the VSI Version associated with a VNIC. See description in dladm(1M).

vsi-mgrid

Specify the VSI Manager ID associated with a VNIC. See description in dladm(1M).

rxfanout

Specify the number of receive-side fanout threads. See description in dladm(1M).

rxrings

Specify the receive rings for the VNIC. See rxrings property in dladm(1M) for supported values and default.

txrings

Specify the transmit rings for the VNIC. See txrings property in dladm(1M) for supported values and default.

link-protection

Enables one or more types of link protection using comma-separated values. See the protection property in dladm(1M) for supported values. It has a default value of mac-nospoof.

Note that adding ip-nospoof to this property will have no effect unless allowed-address is also set. Setting allowed-address will implicitly add ip-nospoof to the set of link-protection, and clearing allowed-address will remove it.

allowed-dhcp-cids

Setting this property will enable dhcp-nospoof on the VNIC. See dladm(1M) for details.

pkey

Specifies the InfiniBand Partition key value in hexadecimal. pkey is always treated as hexadecimal, whether it has the 0x prefix or not. This property is only valid for IPoIB datalinks.

linkmode

Sets the link transport service type on an IB partition datalink. The default value is cm. This property is valid only for IPoIB datalinks. Valid values are:

cm

Connected Mode. This mode uses a default MTU of 65520 and supports a maximum MTU of 65535 bytes. If Connected Mode is not available for a remote node, Unreliable Datagram mode will automatically be used instead.

ud

Unreliable Datagram Mode. This mode uses a default MTU of 2044 and supports a maximum MTU of 4092 bytes.

device: match, allow-partition, allow-raw-io

Device name to match. This can be a pattern to match or an absolute pathname. Note that device resources and aliased datasets can have namespace conflicts in /dev/zvol. See dev(7FS).

Both allow-partition and allow-raw-io can be set to true or false, and default to false. See NOTES.


Note - In general, adding devices to a zone can compromise the security of the system; see NOTES.


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

The name of a ZFS dataset to be accessed from within the zone. See zfs(1M). Each dataset is aliased such that it appears as a virtual ZFS pool in the zone. The alias is the name of this virtual pool. See zpool(1M) for name restrictions that apply to ZFS pool names and as a result also apply to dataset alias values. The alias rpool is reserved from the zone's rpool dataset. Note that aliased datasets and device resources can have namespace conflicts in /dev/zvol. See dev(7FS).

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

The maximum number of process table slots simultaneously available to this zone. This property is the preferred way to set the zone.max-processes rctl. Setting this property will implicitly set the value of the max-lwps property to 10 times the number of process slots unless the max-lwps property has been set explicitly.

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:

  • If the cpu-shares property or equivalent rctl is set, the scheduling class FSS is used.

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

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

admin: user, auths

Delegates zone administrative authorizations to the specified user or role. The user must correspond to a valid local account. The allowed values for auths are:

login

Allows authenticated use of zlogin(1) into this zone.

manage

Allows normal management of the configured zone.

copyfrom

Allows the use of the specified zone as a source from which to clone a new zone.

rootzpool: storage

Defines one or more storage resources to be used exclusively for a dedicated zpool containing the zone installation. The allowed values for storage are defined in suri(5).

zpool: storage, name

Defines one or more storage resources to be used exclusively for a zpool delegated to the zone. The allowed values for storage are defined in suri(5). The allowed values for name are defined in zpool(1M). The name rpool is not permitted.

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
(global)          fs-allowed      list of simple
fs                dir             simple
                  special         simple
                  raw             simple
                  type            simple
                  options         list of simple
net               address         simple
                  allowed-address list of simple
                  configure-allowed-address simple
                  cos             simple
                  defrouter       list of simple
                  etsbw_lcl       simple
                  physical        simple
anet              linkname        simple
                  lower-link      simple
                  allowed-address list of simple
                  auto-mac-address simple
                  configure-allowed-address simple
                  defrouter       list of simple
                  mac-address     simple
                  mac-slot        simple
                  mac-prefix      simple
                  mtu             simple
                  maxbw           simple
                  priority        simple
                  vlan-id         simple
                  vsi-typeid      simple
                  vsi-vers        simple
                  vsi-mgrid       simple
                  rxfanout        simple
                  rxrings         simple
                  txrings         simple
                  link-protection list of simple
                  allowed-dhcp-cids list of simple
                  pkey            simple
                  linkmode        simple
device            match           simple
                  allow-partition simple
                  allow-raw-io    simple
rctl              name            simple
                  value           list of complex
attr              name            simple
                  type            simple
                  value           simple
dataset           name            simple
                  alias           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

admin             user            simple
                  auths           list of simple
rootzpool         storage         simple

zpool             storage         simple
                  name            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.

Options

The following options are supported:

-f command_file

Specify the name of zonecfg command file. command_file is a text file of zonecfg subcommands, one per line.

-z zonename

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 (_) the hyphen (-), and the dot (.). The name global and all names beginning with SYS are reserved and cannot be used.

SUBCOMMANDS

You can use the add and select subcommands to select a specific resource, at which point the scope changes to that resource. The end and cancel subcommands are used to complete the resource specification, at which time the scope is reverted back to global. Certain subcommands, such as add, remove and set, have different semantics in each scope.

zonecfg supports a semicolon-separated list of subcommands. For example:

# zonecfg -z myzone "add net; set physical=myvnic; end"

Subcommands which can result in destructive actions or loss of work have an -F 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 -F option otherwise, if such a command is given without the -F option, the action is disallowed, with a diagnostic message written to standard error.

The following subcommands are supported:

add resource-type (global scope)
add property-name property-value (resource scope)

In the global scope, begin the specification for a given resource type. The scope is changed to that resource type.

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 ([foo,bar,baz]). See PROPERTIES.

cancel

End the resource specification and reset scope to global. Abandons any partially specified resources. cancel is only applicable in the resource scope.

clear property-name

Clear the value for the property.

commit

Commit the current configuration from memory to stable storage. The configuration must be committed to be used by zoneadm. Until the in-memory configuration is committed, you can remove changes with the revert subcommand. The commit operation is attempted automatically upon completion of a zonecfg session. Since a configuration must be correct to be committed, this operation automatically does a verify.

create [-F] [ -a path |-b | -t template]

Create an in-memory configuration for the specified zone. Use create to begin to configure a new zone. See commit for saving this to stable storage.

If you are overwriting an existing configuration, specify the -F option to force the action. Specify the -t template option to create a configuration identical to template, where template is the name of a configured zone.

create uses a default template of SYSdefault. The default template can be changed on a system-wide basis using the default_template SMF property of the svc:/system/zones:default service. An administrator can override the default for this zone using -t (with a specific template) or -b (to use a blank template).

Use the -a path option to facilitate configuring a detached zone on a new host. The path 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 “zoneadm attach” command (see zoneadm(1M)). All validation of the new zone happens during the attach process, not during zone configuration.

Use the -b option to create a blank configuration. Without arguments, create applies the Oracle Sun default settings.

delete [-F]

Delete the specified configuration from memory and stable storage. This action is instantaneous, no commit is necessary. A deleted configuration cannot be reverted.

Specify the -F option to force the action.

end

End the resource specification. This subcommand is only applicable in the resource scope. zonecfg checks to make sure the current resource is completely specified. If so, it is added to the in-memory configuration (see commit for saving this to stable storage) and the scope reverts to global. If the specification is incomplete, it issues an appropriate error message.

export [-f output-file]

Print configuration to standard output. Use the -f option to print the configuration to output-file. This option produces output in a form suitable for use in a command file.

help [usage] [subcommand] [syntax] [command-name]

Print general help or help about given topic.

info zonename | zonepath | autoboot | brand | pool | limitpriv
info [resource-type [property-name=property-value]*]

Display information about the current configuration. If resource-type is specified, displays only information about resources of the relevant type. If any property-name value pairs are specified, displays only information about resources meeting the given criteria. In the resource scope, any arguments are ignored, and info displays information about the resource which is currently being added or modified.

remove resource-type{property-name=property-value}(global scope)

In the global scope, removes the specified resource. The [] 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 -F option.

select resource-type {property-name=property-value}

Select the resource of the given type which matches the given property-name property-value pair criteria, for modification. This subcommand is applicable only in the global scope. The scope is changed to that resource type. The {} syntax means 1 or more of whatever is inside the curly braces. You must specify enough property -name property-value pairs for the resource to be uniquely identified.

set property-name=property-value

Set a given property name to the given value. Some properties (for example, zonename and zonepath) are global while others are resource-specific. This subcommand is applicable in both the global and resource scopes.

verify [-v]

Verify the current configuration for correctness:

  • All resources have all of their required properties specified.

  • A zonepath is specified.

If the -v option is specified, warnings will be issued if there is a potential for devices specified in device resources to conflict with and hide ZFS volumes created within aliased datasets. See dev(7FS).

revert [-F]

Revert the configuration back to the last committed state. The -F option can be used to force the action.

exit [-F]

Exit the zonecfg session. A commit is automatically attempted if needed. You can also use an EOF character to exit zonecfg. The -F option can be used to force the action.

Examples

Example 1 Creating the Environment for a New Zone

In the following example, zonecfg creates the environment for a new zone. /usr/local is loopback mounted from the global zone into /opt/local. /opt/sfw is loopback mounted from the global zone, a VNIC over nxge0 is added to the zone with three IP addresses, and a limit on the number of fair-share scheduler (FSS) CPU shares for a zone is set using the rctl resource type. The example also shows how to select a given resource for modification; in this case, by selecting the anet resource that is automatically created by zonecfg.

example# zonecfg -z myzone3
my-zone3: No such zone configured
Use 'create' to begin configuring a new zone.
zonecfg:myzone3> create
zonecfg:myzone3> set zonepath=/export/home/my-zone3
zonecfg:myzone3> set autoboot=true
zonecfg:myzone3> add fs
zonecfg:myzone3:fs> set dir=/opt/local
zonecfg:myzone3:fs> set special=/usr/local
zonecfg:myzone3:fs> set type=lofs
zonecfg:myzone3:fs> add options [ro,nodevices]
zonecfg:myzone3:fs> end
zonecfg:myzone3> add fs
zonecfg:myzone3:fs> set dir=/mnt
zonecfg:myzone3:fs> set special=/dev/dsk/c0t0d0s7
zonecfg:myzone3:fs> set raw=/dev/rdsk/c0t0d0s7
zonecfg:myzone3:fs> set type=ufs
zonecfg:myzone3:fs> end
zonecfg:myzone3> add fs
zonecfg:myzone3:fs> set dir=/opt/sfw
zonecfg:myzone3:fs> set special=/opt/sfw
zonecfg:myzone3:fs> set type=lofs
zonecfg:myzone3:fs> add options [ro,nodevices]
zonecfg:myzone3:fs> end
zonecfg:myzone3> select anet linkname=net0
zonecfg:myzone3:anet> set lower-link=nxge0
zonecfg:myzone3:anet> set allowed-address="192.168.0.1/24,192.168.1.2/\
           24,192.168.2.3/24"
zonecfg:myzone3:anet> end
zonecfg:my-zone3> set cpu-shares=5
zonecfg:my-zone3> add capped-memory
zonecfg:my-zone3:capped-memory> set physical=50m
zonecfg:my-zone3:capped-memory> set swap=100m
zonecfg:my-zone3:capped-memory> end
zonecfg:myzone3> exit

Example 2 Creating an Exclusive-IP Zone

The following example creates a zone that is assigned a VNIC named net0. The link over which the VNIC is created is automatically determined. The IP addresses and routing are configured inside the new zone using ipadm(1M).

example# zonecfg -z excl
zonecfg:excl> create
zonecfg:excl> set zonepath=/export/zones/excl
zonecfg:excl> exit

Example 3 Creating a Shared-IP Zone

The following example creates a zone that shares an IP stack with the global zone, and is assigned a single IP address and default router.

example# zonecfg -z shared
zonecfg:shared> create -b
zonecfg:shared> set zonepath=/export/zones/shared
zonecfg:shared> set ip-type=shared
zonecfg:shared> add net
zonecfg:shared:net> set physical=nge0
zonecfg:shared:net> set address=192.168.0.3/24
zonecfg:shared:net> set defrouter=192.168.0.1
zonecfg:shared:net> end
zonecfg:shared> exit

Example 4 Associating a Zone with a Resource Pool

The following example shows how to associate an existing zone with an existing resource pool:

example# zonecfg -z myzone
zonecfg:myzone> set pool=mypool
zonecfg:myzone> exit

For more information about resource pools, see pooladm(1M) and poolcfg(1M).

Example 5 Changing the Name of a Zone

The following example shows how to change the name of an existing zone:

example# zonecfg -z myzone
zonecfg:myzone> set zonename=myzone2
zonecfg:myzone2> exit

Example 6 Changing the Privilege Set of a Zone

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:

example# zonecfg -z myzone
zonecfg:myzone> set limitpriv="default,sys_time"
zonecfg:myzone2> exit

Example 7 Setting the zone.cpu-shares Property for the Global Zone

The following command sets the zone.cpu-shares property for the global zone:

example# zonecfg -z global
zonecfg:global> set cpu-shares=5
zonecfg:global> exit

Example 8 Using Pattern Matching

The following commands illustrate zonecfg support for pattern matching. In the zone flexlm, enter:

zonecfg:flexlm> add device
zonecfg:flexlm:device> set match="/dev/cua/a00[2-5]"
zonecfg:flexlm:device> end

In the global zone, enter:

global# ls /dev/cua
a     a000  a001  a002  a003  a004  a005  a006  a007  b

In the zone flexlm, enter:

flexlm# ls /dev/cua
a002  a003  a004  a005

Example 9 Setting a Cap for a Zone to Three CPUs

The following sequence uses the zonecfg command to set the CPU cap for a zone to three CPUs.

zonecfg:myzone> add capped-cpu
zonecfg:myzone>capped-cpu> set ncpus=3
zonecfg:myzone>capped-cpu>capped-cpu> end

The preceding sequence, which uses the capped-cpu property, is equivalent to the following sequence, which makes use of the zone.cpu-cap resource control.

zonecfg:myzone> add rctl
zonecfg:myzone:rctl> set name=zone.cpu-cap
zonecfg:myzone:rctl> add value (priv=privileged,limit=300,action=none)
zonecfg:myzone:rctl> end

Example 10 Using kstat to Monitor CPU Caps

The following command displays information about all CPU caps.

# kstat -n /cpucaps/
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

Example 11 Displaying CPU Caps for a Specific Zone or Project

Using the kstat -c and -i 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.

# kstat -c project_caps

# kstat -c project_caps -i 1

Example 12 Delegating Zone Administrative Rights

The following example shows how to assign administrative rights for the current zone to a role.

example# zonecfg -z myzone
zonecfg:myzone> add admin
zonecfg:myzone:admin> set user=zadmin
zonecfg:myzone:admin> set auths=login,manage
zonecfg:myzone:admin> end
zonecfg:myzone> commit

The result of executing these commands would be an updated entry in the RBAC user_attr(4) database, similar to the following:

zadmin::::type=role;\
auths=solaris.zone.login/myzone,solaris.zone.manage/myzone;profiles=\
Zone Management

Example 13 Creating an Exclusive-IP Zone with Non-Default Properties

The following example creates a zone with an automatically created VNIC over mylink0 with the given MAC address, maximum bandwidth of 100 Mbps, high priority, dedicated hardware rings for RX side, no dedicated hardware rings for the TX side (that is, software-based) and with a VLAN id 2.

example# zonecfg -z excl
excl: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:excl> create -b
zonecfg:excl> set zonepath=/export/zones/excl
zonecfg:excl> add anet
zonecfg:excl:anet> set linkname=mynic0
zonecfg:excl:anet> set lower-link=mylink0
zonecfg:excl:anet> set mac-address=8:0:20:fe:4e:b8
zonecfg:excl:anet> set maxbw=100M
zonecfg:excl:anet> set priority=high
zonecfg:excl:anet> set vlan-id=2
zonecfg:excl:anet> set rxrings=hw
zonecfg:excl:anet> set txrings=sw
zonecfg:excl:anet> end
zonecfg:excl> exit

Example 14 Creating a Read-Only Zone

The following example creates a new zone that has its root filesystem protected against modifications by the zone. Files in /var are writable by virtue of the fixed-configuration profile that is applied.

example# zonecfg -z rozone
rozone: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:rozone> create
zonecfg:rozone> set brand=solaris
zonecfg:rozone> set zonepath=/export/zones/rozone
zonecfg:rozone> set autoboot=true
zonecfg:rozone> set file-mac-profile=fixed-configuration
zonecfg:rozone> set ip-type=exclusive
zonecfg:rozone> add net
zonecfg:rozone:net> set physical=vnic0
zonecfg:rozone:net> end
zonecfg:rozone> exit

Example 15 Creating an Exclusive-IP Zone with an IB Partition

The following example creates a zone with default properties. The zone will automatically create a IPoIB datalink when the zone boots and delete the datalink when the zone halts.

example# zonecfg -z excl
excl: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:excl> create
zonecfg:excl> set zonepath=/export/zones/excl
zonecfg:excl> set ip-type=exclusive
zonecfg:excl> add anet
zonecfg:excl> set linkname=part0
zonecfg:excl> set lower-link=net4
zonecfg:excl> set pkey=ffff
zonecfg:excl:anet> end
zonecfg:excl> exit

Example 16 Creating a Zone Installed into a Dedicated Storage Resource and zpool

The following example creates a new zone with a zpool resource comprised of one storage resource containing the entire zone installation. The zpool will be automatically created or a pre-created zpool will be imported during zone installation. The name will be zoss_rpool.

example# zonecfg -z zoss
zoss: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:zoss> create
zonecfg:zoss> set zonepath=/zoss
zonecfg:zoss> add rootzpool
zonecfg:zoss:rootzpool> add storage iscsi://127.0.0.1/luname.naa.6001\
44f03d70c80000004ea57da10001
zonecfg:zoss:rootzpool> end
zonecfg:zoss> exit

Example 17 Creating a Zone with a Delegated zpool Resource

The following example creates a new zone with a zpool resource delegated to the zone comprised of two storage resources. The zpool will be automatically created or a pre-created zpool will be imported during zone installation. The name will be zoss_mypool.

example# zonecfg -z zoss
zoss: No such zone configured
Use 'create' to begin configuring a new zone
zonecfg:zoss> create
zonecfg:zoss> set zonepath=/zoss
zonecfg:zoss> add zpool
zonecfg:zoss:zpool> set name=mypool
zonecfg:zoss:zpool> add storage dev:/dev/dsk/c0t1d0
zonecfg:zoss:zpool> add storage dev:/dev/dsk/c1t1d0
zonecfg:zoss:zpool> end
zonecfg:zoss> exit

Exit Status

The following exit values are returned:

0

Successful completion.

1

An error occurred.

2

Invalid usage.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/zones
Interface Stability
Volatile

See Also

ppriv(1), prctl(1), zlogin(1), dladm(1M), format(1M), ipadm(1M), kstat(1M), mount(1M), pooladm(1M), poolcfg(1M), poold(1M), rcapd(1M), rctladm(1M), route(1M), suriadm(1M), svcadm(1M), zfs(1M), zoneadm(1M), zpool(1M), priv_str_to_set(3C), kstat(3KSTAT), user_attr(4), vfstab(4), attributes(5), brands(5), fnmatch(5), mwac(5), privileges(5), rbac(5), resource_controls(5), suri(5), zones(5), dev(7FS), hsfs(7FS), zfs(7FS), uscsi(7I)

Oracle Solaris Administration: Oracle Solaris Zones, Oracle Solaris 10 Zones, and Resource Management

Notes

All character data used by zonecfg must be in US-ASCII encoding.

Adding a device to a zone, in general, can allow the zone to adversely affect the security and stability of the system, as not all devices have been audited for secure use inside a zone.

Storage devices using the sd or ssd target driver (this can be checked using prtconf -D /dev/dsk/c2t40d3, for example) can be safely delegated to a zone. This will allow a zone admin to label and partition such devices.

In order to allow disk labelling by means of format(1M), an entire disk/LUN should be delegated to a zone, and the allow-partition property set. For example:

zonecfg:myzone> add device
zonecfg:myzone> set match=/dev/*dsk/c2t40d3*
zonecfg:myzone> set allow-partition=true
zonecfg:myzone> end

While it is not recommended, it is also possible to delegate just a single slice (for example, match=/dev/dsk/c2t40d3s0) of a disk. In order for this to be safe, the allow-partition property must not be true, and the slice or partition must not overlap the disk header of disk labels (these are located within the first two or last two blocks of the partition or disk).

Raw access to storage devices can be enabled by setting the allow-raw-io property to true. This is unsafe, as it allows raw SCSI commands (see uscsi(7I)) to be performed by zone processes.

Inside a zone, device-in-use checking does not work, as the /devices/ tree it relies upon is not present. A future project might address this limitation.