System Administration Commands zoneadm(1M)
NAME
zoneadm - administer zones
SYNOPSIS
zoneadm -z zonename [-u uuid-match] subcommand
[subcommandoptions]
zoneadm [-R root] [-z zonename] [-u uuid-match] list
[listoptions]
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 runtime.
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 argu-
ment is a non-empty string, then the zone matching the
UID is selected instead of the one named by the -z
option, if such a zone is present.
-z zonename
String identifier for a zone.
SUBCOMANDS
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
SunOS 5.11 Last change: 13 Feb 2009 1
System Administration Commands zoneadm(1M)
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 ins-
tallation 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 sub-
command, without executing the command. It uses the out-
put 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 [-- bootoptions]
Boot (or activate) the specified zones.
SunOS 5.11 Last change: 13 Feb 2009 2
System Administration Commands zoneadm(1M)
The following bootoptions are supported:
-i altinit
Select an alternative executable to be the primor-
dial Process. altinit is a valid path to an execut-
able. The default primordial process is init(1M).
-m smfoptions
The smfoptions 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 zfssnapshot] sourcezone
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 zfssnapshot
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.
SunOS 5.11 Last change: 13 Feb 2009 3
System Administration Commands zoneadm(1M)
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 con-
flicting issues, such as the network device being incom-
patible 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" subcom-
mand.
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.
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.
SunOS 5.11 Last change: 13 Feb 2009 4
System Administration Commands zoneadm(1M)
install [-x nodataset] [brand-specific options]
Install the specified zone on the system. This subcom-
mand automatically attempts to verify first. It refuses
to install if the verify step fails. See the verify sub-
command.
-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 [listoptions]
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 listoptions 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- delim-
ited fields. These fields are:
zoneid:zonename:state:zonepath:uuid:brand:ip-type
If the zonepath contains embedded colons, they can
SunOS 5.11 Last change: 13 Feb 2009 5
System Administration Commands zoneadm(1M)
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 newzonepath
Move the zonepath to newzonepath. The zone must be
halted before this subcommand can be used. The
newzonepath must be a local file system and normal res-
trictions for zonepath apply.
ready
Prepares a zone for running applications but does not
start any user processes in the zone.
reboot
SunOS 5.11 Last change: 13 Feb 2009 6
System Administration Commands zoneadm(1M)
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 appropri-
ate 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//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//fsck.
It is also an error if a corresponding fsck binary
SunOS 5.11 Last change: 13 Feb 2009 7
System Administration Commands zoneadm(1M)
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 fol-
lowed 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 physi-
cal 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.
EXAMPLES
Example 1 Using the -m Option
The following command illustrates the use of the -m option.
# zoneadm boot -- -m verbose
SunOS 5.11 Last change: 13 Feb 2009 8
System Administration Commands zoneadm(1M)
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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 13 Feb 2009 9
System Administration Commands zoneadm(1M)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWzoneu
Interface Stability Committed
SEE ALSO
read(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 ins-
tallation of the Solaris operating system. A new installa-
tion 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 pack-
age that contains a request script is added to the global
zone only. See pkgadd(1M).
SunOS 5.11 Last change: 13 Feb 2009 10
|
