System Administration Commands zonecfg(1M) NAME 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 and modifies the configuration of a zone. Zone configuration consists of a number of resources and properties. To simplify the user interface, zonecfg utilizes 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. Resources The following resource types are supported: fs file-system inherit-pkg-dir Directory inherited from the global zone. Software packages whose contents have been SunOS 5.11 Last change: 19 Sep 2006 1 System Administration Commands zonecfg(1M) transferred into that directory are inher- ited in read-only mode by the non-global zone and the non-global zone's packaging database is updated to reflect those pack- ages. Such resources are not modifiable or removable once a zone has been installed with zoneadm. net Network interface. device Device. rctl Resource control. attr Generic attribute. dataset ZFS dataset. npiv Virtual FC Adapter. Properties Each resource type has one or more properties. There are also some global properties, that is, properties of the con- figuration as a whole, rather than of some particular resource. The following properties are supported: (global) zonename SunOS 5.11 Last change: 19 Sep 2006 2 System Administration Commands zonecfg(1M) (global) zonepath (global) autoboot (global) bootargs (global) pool (global) limitpriv (global) brand fs dir, special, raw, type, options inherit-pkg-dir dir net address, physical device match rctl name, value npiv vpwwn, vnwwn, ppwwn SunOS 5.11 Last change: 19 Sep 2006 3 System Administration Commands zonecfg(1M) attr name, type, value dataset name 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: (=,=,...) where each is simple, and the strings are unique within a given property. Lists have the syntax: [,...] where each 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 "[]"). The property types are described as follows: global: zonename The name of the zone. SunOS 5.11 Last change: 19 Sep 2006 4 System Administration Commands zonecfg(1M) global: zonepath Path to zone's file system. global: autoboot Boolean indicating that a zone should be booted automat- ically 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 ser- vice. See svcadm(1M). global: bootargs Arguments (options) to be passed to the zone bootup, unless options are supplied to the "zoneadm boot" com- mand, 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. global: limitpriv SunOS 5.11 Last change: 19 Sep 2006 5 System Administration Commands zonecfg(1M) 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 can- not 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 pro- perty, is listed in privileges(5) as PRIV_SYS_TIME. global: brand The zone's brand type. A zone that is not assigned a brand is considered a "native" zone. fs: dir, special, raw, type, options Values needed to determine how, where, and so forth to SunOS 5.11 Last change: 19 Sep 2006 6 System Administration Commands zonecfg(1M) mount file systems. See mount(1M), mount(2), fsck(1M), and vfstab(4). inherit-pkg-dir: dir The directory path. net: address, physical The network address and physical interface name of the network interface. The network address is one of: o a valid IPv4 address, optionally followed by "/" and a prefix length; o a valid IPv6 address, which must be followed by "/" and a prefix length; o a host name which resolves to an IPv4 address. Note that hostnames that resolve to IPv6 addresses are not supported. device: match Device name to match. SunOS 5.11 Last change: 19 Sep 2006 7 System Administration Commands zonecfg(1M) rctl: name, value The name and priv/limit/action triple of a resource con- trol. See prctl(1) and rctladm(1M). attr: name, type, value The name, type and value of a generic attribute. The type must be one of int, uint, boolean or string, and the value must be of that type. uint means unsigned , that is, a non-negative integer. dataset: name The name of a ZFS dataset to be accessed from within the zone. See zfs(1M). npiv: vpwwn, vnwwn, ppwwn The port WWN, node WWN of the virtual FC adapter and the physical port WWN where the virtual FC adapter will be created on. 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 fs dir simple special simple raw simple type simple options list of simple inherit-pkg-dir dir simple net address simple physical simple device match simple rctl name simple SunOS 5.11 Last change: 19 Sep 2006 8 System Administration Commands zonecfg(1M) value list of complex attr name simple type simple value simple dataset name simple To further specify things, the breakdown of the complex pro- perty "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 alphanumer- ics plus the hyphen (-), underscore (_), and dot (.) charac- ters. Attribute names beginning with "zone" are reserved for use by the system. Finally, the "autoboot" global pro- perty must have a value of "true" or "false". OPTIONS The following options are supported: -f command_file Specify the name of zonecfg command file. command_file is a text file of zonecfg sub- commands, 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 SUNW 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 com- plete 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. SunOS 5.11 Last change: 19 Sep 2006 9 System Administration Commands zonecfg(1M) 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 appropri- ate if such a command is given without the -F option other- wise, 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 glo- bal. Abandons any partially specified resources. cancel is only applicable in the resource scope. 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 commit- ted, you can remove changes with the revert subcommand. The commit operation is attempted automatically upon SunOS 5.11 Last change: 19 Sep 2006 10 System Administration Commands zonecfg(1M) completion of a zonecfg session. Since a configuration must be correct to be committed, this operation automat- ically 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. 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 config- ured, 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 Sun default set- tings. 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. SunOS 5.11 Last change: 19 Sep 2006 11 System Administration Commands zonecfg(1M) 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 com- mit 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 | lim- itpriv 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 informa- tion 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. SunOS 5.11 Last change: 19 Sep 2006 12 System Administration Commands zonecfg(1M) remove resource-type{property-name=property-value}(global scope) remove property-name property-value (resource scope) In the global scope, removes the specified resource. The {} syntax means 1 or more of whatever is inside the curly braces. You must specify enough property-namevalue pairs for the resource to be uniquely identified. In the resource scope, removes the given property name from the current resource. 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 pro- perty -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 pro- perties (for example, zonename and zonepath) are global while others are resource-specific. This subcommand is applicable in both the global and resource scopes. verify Verify the current configuration for correctness: SunOS 5.11 Last change: 19 Sep 2006 13 System Administration Commands zonecfg(1M) o All resources have all of their required pro- perties specified. o A zonepath is specified. 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. npiv-attach Discovers storage devices from the virtual FC adapter and attach them to the zone being configured. 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 glo- bal zone into /opt/local. /opt/sfw 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 rctl resource type. The example also shows how to select a given resource for modif- ication. example# zonecfg -z my-zone3 my-zone3: No such zone configured Use 'create' to begin configuring a new zone. zonecfg:my-zone3> create SunOS 5.11 Last change: 19 Sep 2006 14 System Administration Commands zonecfg(1M) zonecfg:my-zone3> set zonepath=/export/home/my-zone3 zonecfg:my-zone3> set autoboot=true zonecfg:my-zone3> add fs zonecfg:my-zone3:fs> set dir=/usr/local zonecfg:my-zone3:fs> set special=/opt/local zonecfg:my-zone3:fs> set type=lofs zonecfg:my-zone3:fs> add options [ro,nodevices] zonecfg:my-zone3:fs> end zonecfg:my-zone3> add fs zonecfg:my-zone3:fs> set dir=/mnt zonecfg:my-zone3:fs> set special=/dev/dsk/c0t0d0s7 zonecfg:my-zone3:fs> set raw=/dev/rdsk/c0t0d0s7 zonecfg:my-zone3:fs> set type=ufs zonecfg:my-zone3:fs> end zonecfg:my-zone3> add inherit-pkg-dir zonecfg:my-zone3:inherit-pkg-dir> set dir=/opt/sfw zonecfg:my-zone3:inherit-pkg-dir> end zonecfg:my-zone3> add net zonecfg:my-zone3:net> set address=192.168.0.1/24 zonecfg:my-zone3:net> set physical=eri0 zonecfg:my-zone3:net> end zonecfg:my-zone3> add net zonecfg:my-zone3:net> set address=192.168.1.2/24 zonecfg:my-zone3:net> set physical=eri0 zonecfg:my-zone3:net> end zonecfg:my-zone3> add net zonecfg:my-zone3:net> set address=192.168.2.3/24 zonecfg:my-zone3:net> set physical=eri0 zonecfg:my-zone3:net> end zonecfg:my-zone3> add rctl zonecfg:my-zone3:rctl> set name=zone.cpu-shares zonecfg:my-zone3:rctl> add value (priv=privileged,limit=5,action=none) zonecfg:my-zone3:rctl> end zonecfg:my-zone3> select rctl name=zone.cpu-shares zonecfg:my-zone3:rctl> remove value (priv=privileged,limit=5,action=none) zonecfg:my-zone3:rctl> add value (priv=privileged,limit=10,action=none) zonecfg:my-zone3:rctl> end zonecfg:my-zone3> exit Example 2 Creating a Non-Native Zone The following example creates a new Linux zone: example# zonecfg -z lxzone lxzone: No such zone configured Use 'create' to begin configuring a new zone zonecfg:lxzone> create -t SUNWlx zonecfg:lxzone> set zonepath=/export/zones/lxzone SunOS 5.11 Last change: 19 Sep 2006 15 System Administration Commands zonecfg(1M) zonecfg:lxzone> set autoboot=true zonecfg:lxzone> exit Example 3 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 4 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 5 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 SunOS 5.11 Last change: 19 Sep 2006 16 System Administration Commands zonecfg(1M) 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 attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWzoneu | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| SEE ALSO ppriv(1), prctl(1), zlogin(1), mount(1M), pooladm(1M), poolcfg(1M), rctladm(1M), svcadm(1M), zfs(1M), zoneadm(1M), priv_str_to_set(3C), vfstab(4), attributes(5), brands(5), lx(5), privileges(5), zones(5) NOTES All character data used by zonecfg must be in US-ASCII encoding. SunOS 5.11 Last change: 19 Sep 2006 17