Tribblix: manual page: zoneadm.8

ZONEADM(8) Maintenance Commands and Procedures ZONEADM(8)

NAME

zoneadm - administer zones

SYNOPSIS

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

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 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 [-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(7) for specific brand
information.

The zone being attached must first be configured using the
zonecfg (see zonecfg(8)) 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(8).

-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(7) displays during boot. Service options determine
the services which are used to boot the system. See kernel(8)
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(8) and init(8).

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(7) 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, -c, or -n options are given, all running zones
are listed.

The following list_options are supported:

-c

Display all configured zones. This option overrides the -i
option.

-i

Expand the display to all installed zones.

-n

Do not include the global zone in the list of zones returned.

-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
the 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, 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.

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

NOTES

The zones(7) service is managed by the service management facility,
smf(7), 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(8). The
service's status can be queried using the svcs(1) command.

February 21, 2023 ZONEADM(8)