zoneadm(1M) System Administration Commands zoneadm(1M)NAMEzoneadm - administer zones
SYNOPSISzoneadm-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
DESCRIPTION
The zoneadm utility is used to administer system zones. A zone is an
application container that is maintained by the operating system run‐
time.
SECURITY
Once a process has been placed in a zone other than zone 0, the process
or any of its children cannot change zones.
OPTIONS
The following options are supported:
-R root
Specify an alternate root (boot environment). This option can only
be used in conjunction with the "list" and "mark" subcommands.
-u uuid-match
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.
-z zonename
String identifier for a zone.
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 [-u | -U] [-b patchid]... [-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.
For native zones, zoneadm checks package and patch levels on the
machine to which the zone is to be attached. If the pack‐
ages/patches that the zone depends on from the global zone are dif‐
ferent (have different revision numbers) from the dependent pack‐
ages/patches on the source machine, zoneadm reports these conflicts
and does not perform the attach. If the destination system has only
newer dependent packages/patches (higher revision numbers) than
those on the source system, you can use the -u or -U options. The
-u option updates the minimum number of packages within the
attached zone to match the higher-revision packages and patches
that exist on the new system. The -U option updates all packages
in the attached zone that are also installed in the global zone.
With -u or -U, as in the default behavior, zoneadm does not perform
an attach if outdated packages/patches are found on the target sys‐
tem.
For native zones, one or more -b options can be used to specify a
patch ID for a patch installed in the zone. These patches will be
backed out before the zone is attached or, if -u was also speci‐
fied, updated. If multiple -b options are specified, the patches
will be removed in the order that they appear on the command line.
Patches should be backed out in the reverse order in which they
were installed.
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 informa‐
tion.
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 (or -U)
In the absence of -n (as above), the source zone must be halted
before this subcommand can be used.
-n path
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.
-u or -U
Update the attached zone as described above.
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 primor‐
dial 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 ser‐
vices 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 subcom‐
mand is an alternative way to install the zone.
-m copy
Force the clone to be a copy, even if a "ZFS clone" is possi‐
ble.
-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 perform a "dry run" of the detach subcommand. This gen‐
erates the information needed for running the "attach -n" subcom‐
mand, 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
Unless the -n option is used, the source zone must be halted before
this subcommand can be used.
-n
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 tar‐
get host.
halt
Halt the specified zones. halt bypasses running the shutdown
scripts inside the zone. It also removes run time resources of the
zone.
Use:
zlogin zone shutdown
to cleanly shutdown the zone by running the shutdown scripts.
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 automati‐
cally attempts to verify first. It refuses to install if the verify
step fails. See the verify subcommand.
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.
-x nodataset
Do not create a ZFS file system.
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 subcom‐
mand with the zoneadm-z zonename option, it lists only the speci‐
fied 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
Restart the zones. This is equivalent to a halt boot sequence. This
subcommand fails if the specified zones are not active.
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 corre‐
sponding 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 sup‐
ported.
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 proper‐
ties must be set. For an exclusive-IP zone, the physical prop‐
erty 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.
EXAMPLES
Example 1 Using the -m Option
The following command illustrates the use of the -m option.
# zoneadm boot -- -m verbose
Example 2 Using the -i Option
The following command illustrates the use of the -i option.
# zoneadm boot -- -i /sbin/init
Example 3 Using the -s Option
The following command illustrates the use of the -s option.
# zoneadm boot -- -s
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 │Committed │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOread(1), svcs(1), zlogin(1), zonename(1), init(1M), kernel(1M),
svcadm(1M), svc.startd(1M), svc.startd(1M), zonecfg(1M), libuuid(3LIB),
attributes(5), brands(5), native(5), smf(5), zones(5)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 con‐
tains a request script is added to the global zone only. See
pkgadd(1M).
SunOS 5.10 24 Feb 2011 zoneadm(1M)
