zoneadm -z zonename [-u uuid-match] subcommand
[subcommand_options]
zoneadm [-R root] [-z zonename] [-u uuid-match] list
[list_options]
zoneadm [-R root] -z zonename [-u uuid-match] mark incomplete
The zoneadm utility is used to administer system zones. A zone is an application container that is maintained by the operating system runtime.
Once a process has been placed in a zone other than zone 0, the process or any of its children cannot change zones.
Except for simple listing and help functions, only a user operating in the global system zone can use zoneadm, and it must be executed with an effective user ID of root. In addition, the user must be authorized to execute specific subcommands.
zoneadm checks for authorization strings that optionally include the specified zonename as a suffix, preceded by the slash character. When omitted, the authorization matches any zone.
Subcommands that only provide information, for example, help or list, do not require any authorizations. All other subcommands require the authorization solaris.zone.manage/zonename.
Once a process has been placed in a zone other than zone 0, neither that process nor any of its children can change zones.
The following options are supported:
Specify an alternate root (boot environment). This option can only be used in conjunction with the “list” and “mark” subcommands.
Unique identifier for a zone, as assigned by libuuid(3LIB). If this option is present and the argument is a non-empty string, then the zone matching the UUID is selected instead of the one named by the –z option, if such a zone is present.
String identifier for a zone.
Subcommands which can result in destructive actions or loss of work have a –F flag to force the action. If input is from a terminal device, the user is prompted if such a command is given without the –F flag; otherwise, if such a command is given without the – F flag, the action is disallowed, with a diagnostic message written to standard error. If a zone installation or uninstallation is interrupted, the zone is left in the incomplete state. Use uninstall to reset such a zone back to the configured state.
The following subcommands are supported:
The attach subcommand takes a zone that has been detached from one system and attaches the zone onto a new system. Therefore, it is advised (though not required) that the detach subcommand should be run before the “attach” takes place. Once you have the new zone in the configured state, use the attach subcommand to set up the zone root instead of installing the zone as a new zone.
The attach subcommand is also used to transition a zone from the unavailable state to the installed state. If the attach subcommand is unable to perform such a transition, the zone will remain in the unavailable state.
The –F option can be used to force the zone into the “installed” state with no validation. This option should be used with care since it can leave the zone in an unsupportable state if it was moved from a source system to a target system that is unable to properly host the zone. The –n option can be used to perform a “dry run” of the attach subcommand. It uses the output of the “detach –n” subcommand as input and is useful to identify any conflicting issues, such as the network device being incompatible, and can also determine whether the host is capable of supporting the zone. The path can be “-”, to read the input from standard input.
The zone's brand may include additional options that govern how the zone will be attached. See brands(5) for specific brand information.
The zone being attached must first be configured using the zonecfg (see zonecfg(1M)) command. This does not apply when running “ attach –n”.
Use the following command to attach a zone:
# zoneadm -z my-zone attach
Use the following command to attach and update a zone:
# zoneadm -z my-zone attach -u
In the absence of –n (as above), the source zone must be halted before this subcommand can be used.
Read the zone manifest and verify that the target machine has the correct configuration to host the zone without actually performing an attach. The zone on the target system does not have to be configured on the new host before doing a trial-run attach.
Update the attached zone.
Specify this option to forcibly reuse existing zpool resources that may appear to be in in-use.
Specify –x with force-zpool-create-all to forcibly create all zpool resources.
Use –x with force-zpool-create, with the syntax:
-x force-zpool-create=zpoolname{,zpoolname,zpoolname,...}
...to limit this option to a specific set of zpool resources. To name a rootzpool zpool resource, use rpool. For a zpool resource, use the name specified in the corresponding zone config name property.
These options are only available for archive-based attach usage. See brands(5) for the information which brands support archive-based attach.
Boot (or activate) the specified zones.
The boot subcommand has the following mutually exclusive options:
If the zone has been suspended, this option will force a new boot rather than a resume of the suspended zone state. This should be used carefully, as a suspended zone may contain intermediate file system state and so on, that could cause issues if abandoned.
Boots the zone with a writable root, effectively overriding the file-mac-profile setting in the zone's configuration. This option is in effect for this boot-cycle only: a subsequent reboot will boot the zone with a file-mac-profile in effect again.
Boots the zone in transient r/w mode; when the zone completes self-assembly, the zone will reboot in read-only mode. Has no effect non-read only root zones.
The following boot_options are supported:
The smf_options include two categories of options to control booting behavior of the service management facility: recovery options and messages options.
Message options determine the type and amount of messages that smf(5) displays during boot. Service options determine the services which are used to boot the system. See kernel(1M) for a listing of the –m suboptions.
Boots only to milestone svc:/milestone/single-user:default. This milestone is equivalent to init level s. See svc.startd(1M) and init(1M).
Install a zone by copying an existing installed zone. This subcommand is an alternative way to install the zone.
Force the clone to be a copy, even if a “ZFS clone” is possible.
Note, this is the default (and only supported) clone method for zones that have a rootzpool resource configured.
Specify the name of a ZFS snapshot to use as the source of the clone. The snapshot must be a snapshot of the source zone taken from a previous “zoneadm clone” installation.
Specify the –x option with force-zpool-import to forcibly reuse existing zpool resources that may appear to be in use.
Specify the –x option with force-zpool-create-all to forcibly create all zpool resources.
Use –x with force-zpool-create, with the syntax:
-x force-zpool-create=zpoolname{,zpoolname,zpoolname,...}
...to limit this option to a specific set of zpool resources. To name a rootzpool zpool resource, use rpool. For a zpool resource, use the name specified in the corresponding zone config name property.
The source zone must be halted before this subcommand can be used.
Detach the specified zone. Detaching a zone is the first step in moving a zone from one system to another. The full procedure to migrate a zone is that the zone is detached, the zonepath directory is moved to the new host, and then the zone is attached on the new host. Once the zone is detached, it is left in the configured state. If you try to install or clone to a configured zone that has been detached, you will receive an error message and the install or clone subcommand will not be allowed to proceed. The –n option can be used to perform a “dry run” of the detach subcommand. This generates the information needed for running the “attach –n” subcommand, which is useful to identify any conflicting issues, such as the network device being incompatible or if the host is capable of supporting the zone. The information is sent to standard output and can be saved to a file or piped to the “attach –n” subcommand. The –F option can be used to forcefully detach the zone without performing verification checks on the existing zonepath.
Use the following command to detach a zone:
# zoneadm -z my-zone detach
Unless the –n option is used, the source zone must be halted before this subcommand can be used.
Forcefully detach the zone without performing verification checks on the zone's storage. This option is typically used if the storage for the zonepath is no longer accessible to this host. Such a scenario is normally encountered when the zone's storage has been failed over to an alternate host, either manually or as part of a cluster.
Generate a zone manifest on a running zone without actually detaching the zone. The state of the zone on the originating system is not changed. The zone manifest is sent to stdout. The global administrator can direct this output to a file or pipe it to a remote command to be immediately validated on the target host.
The get-prom subcommand displays OpenBoot configuration variables. If no variable is specified, all configuration variables and their values are displayed in variable=value form. If a variable is specified, only the value of that variable is displayed.
The get-prom subcommand is only supported by the solaris-kz (5) brand on SPARC.
In the first form, the set-prom subcommand sets the specified OpenBoot configuration variable to the specified value. If value is not specified (that is, it is a zero-length string) the variable is set to a zero-length string. In the second form, the –c option indicates that the variable should be cleared, allowing OpenBoot's default value to take effect.
The set-prom subcommand is only supported by the solaris-kz (5) brand on SPARC. It may only be used when the zone is in the installed state.
Halt the specified zones. halt bypasses running the shutdown scripts inside the zone. It also removes run time resources of the zone.
See also the shutdown subcommand, below.
Display general help. If you specify subcommand, displays help on subcommand.
Install the specified zone on the system. This subcommand automatically attempts to verify first. It refuses to install if the verify step fails. See the verify subcommand.
Specify the –x option with force-zpool-import to forcibly reuse existing zpool resources that may appear to be in use.
Specify the –x option with force-zpool-create-all to forcibly create all zpool resources.
Use –x with force-zpool-create, with the syntax:
-x force-zpool-create=zpoolname{,zpoolname,zpoolname,...}
...to limit this option to a specific set of zpool resources. To name a rootzpool zpool resource, use rpool. For a zpool resource, use the name specified in the corresponding zone config name property.
The zone's brand may include additional options that govern how the software will be installed in the zone. See brands(5) for specific brand information.
Display the name of the current zones, or the specified zone if indicated.
By default, all running zones are listed. If you use this subcommand with the zoneadm –z zonename option, it lists only the specified zone, regardless of its state. In this case, the –i and –c options are disallowed.
If neither the –i or –c options are given, all running zones are listed.
The following list_options are supported:
Display all configured zones. This option overides the –i option.
Expand the display to all installed zones.
Request machine parsable output. The output format is a list of lines, one per zone, with colon- delimited fields. These fields are:
zoneid:zonename:state:zonepath:uuid:brand:ip-type:\ r/w:file-mac-profile
If the zonepath contains embedded colons, they can be escaped by a backslash (“\:”), which is parsable by using the shell read(1) function with the environmental variable IFS. The uuid value is assigned by libuuid(3LIB) when the zone is installed, and is useful for identifying the same zone when present (or renamed) on alternate boot environments. Any software that parses the output of the “zoneadm list -p” command must be able to handle any fields that may be added in the future.
The –v and –p options are mutually exclusive. If neither –v nor –p is used, just the zone name is listed.
Display verbose information, including zone name, id, current state, root directory, brand type, ip-type, and options.
The –v and –p options are mutually exclusive. If neither –v nor –p is used, just the zone name is listed.
Change the state of a zone. Only a subset of the zone states are supported, as described below.
Change the state of an installed zone to incomplete. This command can be useful in cases where administrative changes on the system have rendered a zone permanently unusable or inconsistent. This change cannot be undone, except by uninstalling the zone.
Change the state of an installed zone to unavailable. This command can be useful in cases where administrative changes or failures on the system have rendered a zone temporarily unusable. This change can be undone with the attach subcommand.
Move the zonepath to new_zonepath. The zone must be halted before this subcommand can be used. The new_zonepath must be a local file system and normal restrictions for zonepath apply.
Note, for zones configured with a rootzpool resource only the zonepath will be renamed but the zone itself will not move out of its containing zpool.
Prepares a zone for running applications but does not start any user processes in the zone.
Restart the zone. This is equivalent to a halt boot sequence (shutdown scripts are not run).
See the boot subcommand for supported boot options.
Rename the zone. This subcommand may be used for configured and installed zones. The installed zone must be halted before this subcommand can be used. Use the following command to rename a zone:
# zoneadm -z my-zone rename new-zone
The rename support for zone configurations using templates with the %{zonename} token is limited to the zonename property and zpool resource name property. The rename subcommand is not supported for the solaris-kz brand.
Cleanly shut down the zone (equivalent to running /usr/sbin/init 0 in the zone). The shutdown subcommand waits until the zone is successfully shut down; a zoneadm halt can be used to forcibly halt the zone, if the shutdown process takes a long time.
If –r is specified, reboot the zone. See the boot subcommand for supported boot options.
Save a core dump of a running solaris-kz brand to the global zone (by default, kzcore.X in the current directory). This core dump file can be debugged through mdb (1) .
If –L is specified, the zone is not paused during the dump operation.
Suspend a running solaris-kz brand zone to disk. The zone is suspended to an image file contained within the zone path. The zone can be resumed through zoneadm boot.
Uninstall the specified zone from the system. Use this subcommand with caution. It removes all of the files under the zonepath of the zone in question. You can use the –F flag to force the action.
The –x option with force-zpool-destroy-all option can be used to destroy all zpools.
Use –x with force-zpool-destroy, with the syntax:
-x force-zpool-destroy=zpoolname{,zpoolname,zpoolname,...}
...to limit this option to a specific set of zpool resources. To name a rootzpool zpool resource, use rpool. For a zpool resource, use the name specified in the corresponding zone config name property.
Check to make sure the configuration of the specified zone can safely be installed on the machine. Following is a breakdown of the checks by resource/property type:
zonepath and its parent directory exist and are owned by root with appropriate modes . The appropriate modes are that zonepath is 700, its parent is not group or world-writable and so forth. zonepath is not over an NFS mount. A sub-directory of the zonepath named “root” does not exist.
If zonepath does not exist, the verify does not fail, but merely warns that a subsequent install will attempt to create it with proper permissions. A verify subsequent to that might fail should anything go wrong.
zonepath cannot be a symbolic link.
Any fs resources have their type value checked. An error is reported if the value is one of proc, mntfs, autofs, or nfs or the filesystem does not have an associated mount binary at /usr/lib/fs/<fstype>/mount.
It is an error for the directory to be a relative path.
It is an error for the path specified by raw to be a relative path or if there is no fsck binary for a given filesystem type at /usr/lib/fs/<fstype>/fsck. It is also an error if a corresponding fsck binary exists but a raw path is not specified.
All physical network interfaces exist. All network address resources are 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 hostnames that resolve to IPv6 addresses are not supported.
The physical interface name is the network interface name.
A zone can be configured to be either exclusive-IP or shared-IP. For a shared-IP zone, both the physical and address properties must be set. For an exclusive-IP zone, the physical property must be set and the address property cannot be set.
It verifies that the lower-link, over which the VNIC will be automatically created, exists.
It also verifies that any defined resource control values are valid on the current machine. This means that the privilege level is privileged, the limit is lower than the currently defined system value, and that the defined action agrees with the actions that are valid for the given resource control.
All zpools configured are online on the system for a zone in the installed state.
For a zone in configured state, it verifies that none of the configured zpool resources are already online on the system.
The following command illustrates the use of the –m option.
# zoneadm -z myzone boot -- -m verboseExample 2 Using the –s Option
The following command illustrates the use of the –s option.
# zoneadm -z myzone boot -- -sExample 3 Modifying an OpenBoot Configuration Variable
The following commands illustrate setting, getting, and clearing an OpenBoot configuration variable.
# zoneadm -z zone1 get-prom # zoneadm -z zone1 set-prom auto-boot?=false # zoneadm -z zone1 get-prom auto-boot?=false # zoneadm -z zone1 set-prom -c auto-boot? # zoneadm -z zone1 get-prom auto-boot? auto-boot?: not set
The output of the last command, is printed to stderr, and the exit value from zoneadm is non-zero.
The following exit values are returned:
Successful completion.
An error occurred.
Invalid usage.
See attributes(5) for descriptions of the following attributes:
|
read(1), svcs (1) , zlogin (1) , zonename (1) , init(1M), kernel(1M), svcadm(1M), zpool(1M), svc.startd(1M), svc.startd(1M), zonecfg(1M), libuuid (3LIB) , attributes (5) , brands (5) , mwac(5), smf (5) , zones (5) , zfs(7FS), suri (5) , solaris-kz (5) , rad(1M)
OpenBoot 4.x Command Reference Manual
The zones(5) service is managed by the service management facility, smf (5), under the service identifier:
svc:/system/zones:default
Administrative actions on this service, such as enabling, disabling, or requesting restart, can be performed using svcadm(1M). The service's status can be queried using the svcs(1) command.
For the first boot after a read-only zone is installed or upgraded, or when the zone is booted with –w/–W, the write-only protection is disabled. Care must be taken that the zone is otherwise protected.