SUBCOMMANDS
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:
attach [
-F] [
-n path] [
brand-specific options]
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
-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 run the
attach subcommand, without executing the command. 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
boot [
-- boot_options]
Boot (or activate) the specified zones.
The following
boot_options are supported:
-i altinit
Select an alternative executable to be the primordial Process. altinit is a valid path to an executable. The default primordial process is init(1M).
-m smf_options
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.
-s
Boots only to milestone svc:/milestone/single-user:default. This milestone is equivalent to init level s. See svc.startd(1M) and init(1M).
clone [
-m copy] [
-s zfs_snapshot]
source_zone
Install a zone by copying an existing installed zone. This subcommand is an alternative way to install the zone.
-m copy
Force the clone to be a copy, even if a "ZFS clone" is possible.
-s zfs_snapshot
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.
The source zone must be halted before this subcommand can be used.
detach [
-n]
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 run the
detach subcommand, without executing the command. 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.
Use the following command to detach a zone:
# zoneadm -z my-zone detach
The source zone must be halted before this subcommand can be used.
halt
Halt the specified zones. halt bypasses running the shutdown scripts inside the zone. It also removes run time resources of the zone.
help [
subcommand]
Display general help. If you specify subcommand, displays help on subcommand.
install [
-x nodataset] [
brand-specific options]
Install the specified zone on the system. This subcommand automatically attempts to verify first, most verification errors are fatal. See the
verify subcommand.
-x nodataset
Do not create a ZFS file system.
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.
list [
list_options]
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:
-c
Display all configured zones. This option overides the -i option.
-i
Expand the display to all installed zones.
-p
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
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.
-v
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.
mark incomplete
Change the state of an installed zone to "incomplete." This command may be useful in cases where administrative changes on the system have rendered a zone unusable or inconsistent. This change cannot be undone (except by uninstalling the zone).
move new_zonepath
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.
ready
Prepares a zone for running applications but does not start any user processes in the zone.
reboot [
-- boot_options]]
Restart the zones. This is equivalent to a halt boot sequence. This subcommand fails if the specified zones are not active. See boot subcommand for the boot options.
shutdown [
-r [
-- boot_options]]
Gracefully shutdown the specified zone. This subcommand waits for all zone processes to finish; the default timeout is SCF_PROPERTY_TIMEOUT value from the SMF service system/zones. If the -r option is specified, reboot the zone. See boot subcommand for the boot options.
uninstall [-F]
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.
verify
Check to make sure the configuration of the specified zone can safely be installed on the machine. Following is a break-down of the checks by
resource/property type:
zonepath
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.
fs
Any
fs resources have their
type value checked. An error is reported if the value is one of
proc,
mntfs,
autofs,
cachefs, 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.
net
All physical network interfaces exist. All network address resources are 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.
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.
rctl
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.
NOTES
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.
The act of installing a new non-global zone is a fresh installation of the Solaris operating system. A new installation of Solaris must not require interaction with the user (that is, it must be "hands off"). Because of this, packages installed in the global zone and all non-global zones cannot contain request scripts (see pkgask(1M)). If a package did have a request script, then the creation of a non-global zone could not be done without user intervention. Any package that contains a request script is added to the global zone only. See pkgadd(1M).