Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, August 8, 2018
 
 

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 -z zonename [-u uuid-match] mark incomplete
zoneadm -z zonename [-u uuid-match] mark unavailable

Description

The zoneadm utility is used to administer system zones. A zone is an operating system 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.

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.

The zoneadm command 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.

For more information on –w flag and its interaction with file-mac-profile, see the –w option under zoneadm boot subcommand.

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.

Sub Commands

Subcommands which can result in destructive actions or loss of work have a –F flag to force the action. If a command is given without the –F flag, then the action is disallowed and a diagnostic message is written to standard error. If an input is from a terminal device, then the user is prompted if such a command is given without the –F flag. 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:

zoneadm attach [–u] [–F] [–x extended-options] [–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 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 software compatibility tests. 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(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

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.

–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

Update the attached zone.

–x force-zpool-import

Specify this option to forcibly reuse existing zpool resources that may appear to be in in-use.

The attach subcommand might fail if the system in maintenance state. For more information on maintenance state, see the sysadm(8) man page.

zoneadm boot [–R] [–w | –W] [–x extended-options] [–- boot-options]

Boot (or activate) the specified zones.

The boot subcommand has the following mutually exclusive options:

–R

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.

–w

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. The zone mentioned here is an immutable zone.

–W

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 on non-read only root zones. The zone mentioned here is an immutable zone.

–x storage-create-missing

Specify this option to create storage, if needed. Storage will be created if the URI type has the property "create-supported" set.

The following boot-options are supported:

–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. For more information, see the svc.startd(8) and init(8) man pages.

The boot subcommand might fail if the system is in maintenance state. For more information on maintenance state, see the sysadm(8) man page.

zoneadm clone [–x extended-options] [brand-specific options] source-zone

Install a zone by copying an existing installed zone. This subcommand is an alternative way to install the zone.

–x force-zpool-import

Specify the –x option with force-zpool-import to forcibly reuse existing zpool resources that may appear to be in use.

–x force-zpool-create
–x force-zpool-create-all

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.

To force creation of the root zpool of a kernel zone, use:

-x force-zpool-create={root-pool-name}

where {root-pool-name} is the name of the root zpool in the source zone. Kernel zones do not support -x force-zpool-create-all.

–x storage-create-missing

Specify this option to create storage, if needed.

The source zone must be halted before this subcommand can be used.

zoneadm detach [–F | –n]

Detach the specified zone. Detaching a zone is the first step in moving a zone from one system to another. Cold migration detaches the zone from the source host and attaches it on the destination 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.

–F

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.

–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 target host.

zoneadm get-prom [variable]

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(7) brand on SPARC. It may only be used when the zone is in the installed state.

zoneadm set-prom variable=[value]
zoneadm set-prom –c variable

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(7) brand on SPARC. It may only be used when the zone is in the installed state.

zoneadm halt

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.

zoneadm help [subcommand]

Display general help. If you specify subcommand, displays help on subcommand.

zoneadm install [–x extended-options ] [brand-specific options]

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.

–x force-zpool-import

Specify the –x option with force-zpool-import to forcibly reuse existing zpool resources that may appear to be in use.

–x force-zpool-create
–x force-zpool-create-all

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.

To force creation of the root zpool of a kernel zone, use:

-x force-zpool-create={root-pool-name}

where {root-pool-name} is the name of the root zpool specified in the AI manifest or "rpool" if no AI manifest is provided. Kernel zones do not support -x force-zpool-create-all.

–x storage-create-missing

Specify this option to create storage, if needed.

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.

zoneadm list [list-options]
zoneadm list [–c] [–i] [[–p] | [–s] | [–v]] [–b brandlist]

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 overrides 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:\
r/w:file-mac-profile:auxstate

If the zonepath contains embedded colons, those are 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.

If zoneid or r/w is not set, their values are printed as a single dash ('-'). Values that are not set are left empty. For example:

# zoneadm -z myzone list -p
-:myzone:incomplete:::::-::no-config

Any new fields that may be added in the future will be printed as empty if not set.

The –s, –v, and –p options are mutually exclusive. If neither –v nor –p is used, just the zone name is listed.

–s

Display the zone name, state, and a comma-separated list of auxiliary states set for a zone. See the relevant brand man page for defined states.

The –s, –p, and –v options are mutually exclusive.

–v

Display verbose information, including zone name, id, current state, root directory, brand type, ip-type, and options.

The –s, –v, and –p options are mutually exclusive.

–b brand[,brand]

Display only the brand(s) specified by this option.

zoneadm apply [–n] [–q] [–x extended-options]

The apply subcommand reconfigures a running zone to match persistent configuration of a zone maintained through zonecfg(8) and prints out performed actions. Applied configuration takes effect immediately and does not require reboot of the zone. The apply command is available only for running zones. See respective brand man page for details on resources supported by the live zone reconfiguration.

The following options are supported:

–n

Runs the reconfiguration in a dry run mode that does not change the configuration of a running zone. The dry run mode acts the same way as the real reconfiguration, but leaves the running zone intact. Use the dry run mode to review actions that would be performed by the real reconfiguration.

–q

Quiet mode. Suppresses all messages and returns a status code only.

–x storage-create-missing

Specify this option to create storage, if needed.

In case of the global zone, no options are allowed. The apply subcommand reconfigures resource controls, pools, and sets the file-mac-profile. If the global zone is configured as an immutable global zone, it immediately makes the zone immutable.

zoneadm mark state

Change the state of a zone. Only a subset of the zone states are supported, as described below.

incomplete

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.

unavailable

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.

zoneadm migrate [–nq] [–t auto] [brand-specific-options] scheme://user@host:port

Migrate an installed or running zone to the given destination host. Supported for solaris and kernel branded zones.

For live migration of a running kernel zone the zone will continue running on the source host until the final stage of migration. After a migration, any zlogin sessions will be terminated. However, network connections to the zone are maintained.

For cold migration of an installed zone, the zone will be migrated to an installed state on the destination host. For a suspended kernel zone, the migrated zone will also be in the suspended auxiliary state.

The zone's brand may include additional options that govern how the zone will be migrated. For specific brand information, see the brands(7) man page.

The zone configuration must be compatible with the destination host's environment, as if you were detaching then attaching the zone. For example, any storage references should use a storage URI (see zonecfg(8)) that is accessible by both hosts. Supported storage URI types for migration are NFS, iscsi, and lu.

The zone can be configured on the destination host prior to migration; in this case, that configuration is used to start the zone on the destination host. If the configuration is incompatible with the current zone configuration (for example, a virtual disk is missing), an error will be returned.

If the zone is not configured on the destination, migration will configure it based on the current zone configuration.

After migration, the zone will be detached from the source zone, but left in a configured state.

The destination host is defined by the given RAD URI (see rad(8)). The scheme defaults to rads, user defaults to the current user, and port defaults to the standard RAD port. Supported values for scheme are rads, rad, and ssh.

To receive migrating zones, the RAD service mentioned must be running. In addition, the 'kz-migr' service under inetd must be enabled for live migration. With the default configuration, therefore, ports 8102 and 12302 must be accessible.

zoneadm migrate takes the following options:

–n

Do a dry-run: checks if the zone could be live migrated to the destination host, but leave it running.

–q

Quiet: does not report status during migration.

–t auto

Specifies the type of migration to perform. Additional options may be available as brand-specific options.

zoneadm move [–p {URI} ... –p {URI}] [–x extended-options] new-zonepath

Move the zone installation to a new location in the local file system or a new ZFS storage pool and/or change current zonepath to new-zonepath.

A zone installation in the local file system (no rootzpool resource) can be moved to a new ZFS storage pool built on device(s) specified by the storage URI(s). A new rootzpool resource is added to the zone configuration.

A zone installation configured with a rootzpool resource may be moved to a new ZFS storage pool build on device(s) specified by the storage URI(s) or out of its containing ZFS storage pool into the local file system.

The move subcommand may also be used to change just the zonepath without otherwise changing the zone installation itself.

The zone must be halted before this subcommand can be used. The zonepath must be a valid pathname and normal restrictions for a zonepath apply.

The move subcommand is not supported for solaris-kz brand.

The following options are supported:

–p {URI}

Use the specified storage URI for the new rootzpool resource. Each storage URI must be specified with a separate –p option. If multiple storage URIs have been specified, a mirrored ZFS storage pool is created by default.

–x remove-rootzpool

Specify this option to move a zone out of its containing ZFS storage pool into the local file system specified by the new-zonepath.

–x force-zpool-destroy=rpool

Specify this option to forcibly destroy the zpool associated with the original rootzpool resource after the zone installation has been moved.

–x force-zpool-import

Specify this option to forcibly reuse the existing zpool as the rootzpool resource.

–x force-zpool-create=rpool

Specify this option to forcibly create the zpool for the rootzpool resource.

–x create-size={storage-size}

Specify this option to create any missing storage device(s), if supported by the storage URI type. A positive number with appropriate scale suffix (K, M, G or T) is expected here to specify the size of an individual storage device.

–x force-storage-destroy-all

Specify this option to destroy storage associated with the original rootzpool resource after the zone has been moved, if supported by the storage URI type.

zoneadm ready [–x extended-options]

Prepares a zone for running applications but does not start any user processes in the zone.

The following option is supported:

–x storage-create-missing

Specify this option to create storage, if needed.

zoneadm reboot [–x extended-options] [–- boot-options]

Restart the zone. This is equivalent to a halt boot sequence (shutdown scripts are not run).

The following option is supported:

–x storage-create-missing

Specify this option to create storage, if needed.

See the boot subcommand for supported boot options.

zoneadm rename new-zonename

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.


Note -  Any console for an installed zone is detached by the rename subcommand.
zoneadm shutdown [–r [-- boot-options]]

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.

zoneadm savecore [–k] [–L] [–f dumpfile]

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.

If –k is specified then the core dump is placed in the location configured by coreadm(8) for kernel zone core dumps.

zoneadm suspend

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.

zoneadm uninstall [–F] [–x extended-options]

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.

–x force-zpool-destroy
–x force-zpool-destroy-all

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.

–x force-storage-destroy-all

Instead of unmapping storage URIs, this option tells zoneadm to destroy all storage objects referenced by such URIs. Not all storage object types support such operation. For example, one can destroy an object referenced by a file URI, but not by an iSCSI or lu URI. The destroy operation will apply to all storage objects referenced by the zone (for rootzpool, zpool, and device resources).

It is strongly advised to be careful while using this option as destroyed storage cannot be recovered and there are no checks to see if the specified storage objects are still referenced by other boot environments.

zoneadm verify

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

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:

  • 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.

anet

It verifies that the lower-link, over which the VNIC will be automatically created, exists.

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.

rootzpool, zpool

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.

solaris Brand-Specific Subcommands

The following solaris brand-specific subcommand options are supported.

attach [–z ZBE] [–u | –U] [–c config_profile.xml | dir] [–x destroy-orphan-zbes | force-zbe-clone | deny-zbe-clone | attach-last-booted-zbe | attach-matched-zbe | attach-last-mounted-zbe]

Attach the specified solaris branded zone image into the zone. zoneadm checks package levels on the machine to which the zone is to be attached. If the packages that the zone depends on from the global zone are different (have different revision numbers) from the dependent packages on the source machine, zoneadm reports these conflicts and does not perform the attach.

If the destination system has only newer dependent packages (higher revision numbers) than those on the source system, you can use the –u or –U option to update the dependent packages to match the revision of the packages that exist on the new system.

When attaching a zone, multiple zone boot environments (ZBEs) can exist and the attach subcommand must determine which one to attach. The selection criteria is as follows, with the first match being used.

  • If the –z option is used to specify a ZBE, it is selected.

  • If the –x attach-last-booted-zbe is used to specify a ZBE, last booted ZBE is selected.

  • If the –x attach-matched-zbe is used, then select the active ZBE associated with the global zone boot environment.

  • If the –x attach-last-mounted-zbe is used, then select the ZBE last mounted on the zone's zonepath. This is the default option.

If the selected ZBE is associated with the currently active global zone boot environment, then the selected ZBE is attached. This behavior can be changed by using –x force-zbe-clone.

If the selected ZBE is associated with another global zone boot environment or, the selected ZBE is not associated with any global zone boot environment (orphaned boot environment), the selected ZBE is cloned and the clone of the selected ZBE is attached. The original ZBE continues to exist. This behavior can be changed by using –x deny-zbe-clone.

To destroy all orphan ZBE during attach, use:

–x destroy-orphan-zbes

To avoid cloning the orphan ZBE, use:

–x deny-zbe-clone

For more details on –x options, see below:

–u

Update the minimal number of packages within the zone to allow the zone's packages to be compatible with the packages installed in the global zone.

–U

Update all packages within the zone to their latest versions which are compatible with the packages installed in the global zone.

–c

Provides a profile or a directory of profiles to apply. For more information, see the sysconfig(8) man page.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

–z ZBE

Attach the specified existing zone boot environment. If the specified zone boot environment is associated with a different global zone, the specified ZBE is cloned and a clone of the ZBE is attached.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

–x destroy-orphan-zbes

Destroys all zone boot environments that are not associated with any global zone.

–x force-zbe-clone

Forces the selected zone boot environment to be cloned. The new cloned boot environment is then selected to be attached to the zone.

–x deny-zbe-clone

Overrides the cloning of selected zone boot environment. This option enforces that the selected zbe should be attached to the zone, without cloning (if default behavior is to clone it). Otherwise it has no effect.

–x attach-last-booted-zbe

Selects the last booted zone boot environment. If the selected zone boot environment is not associated with any global zone, it is cloned.

–x attach-matched-zbe

Selects an active zone boot environment associated with the global zone.

–x attach-last-mounted-zbe

Selects the ZBE last mounted on the zone's zonepath.

clone [–c config_profile.xml | dir]
–c config_profile.xml | dir

Provides a profile or a directory of profiles to apply after installation from the repository.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

install [–m manifest.xml] [–c config_profile.xml | dir]

install –a unified_archive [–z archived_zone] [–x {cert | cacert | key}=path]... [–U] [–p | –u] [–s | –v] [–c config_profile.xml | dir]

The solaris brand installer supports installing the zone from either the software repository or from a Unified Archive.

If the –a option is not specified, the zone is installed from the repository. To install additional packages in a zone the default zone manifest, /usr/share/auto_install/manifest/zone_default.xml, can be copied and edited to include the needed packages. This modified manifest should be specified to install with the –m option.

To install the zone from a Unified Archive, the –a is required. If necessary, the packages from the Unified Archive are automatically updated during the zone installation with the minimal changes required to make them compatible with the global zone's packages.

–a archive

The path or file, http, or https URI of a Unified Archive.

The –z option may be used to select which archived zone is to be installed. If the Unified Archive is on a secure web server (https URI), –x may be used to specify the path to a PEM-encoded certificate, CA certificate, and/or a key. If neither –u nor –p are specified, the default –p is implied if the archive is a recovery archive. Otherwise, –u is implied.

–c config_profile.xml | dir

Provides a profile or a directory of profiles to apply after installation from the repository.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

–m manifest.xml

Manifest file to be specified to the automated installer.

–p

Preserve the system configuration after installing the zone from an archive or a path. If installing from a Unified Archive and the archive is a recovery archive, –p is implied but can be overridden with –u.

If the archive is not a recovery archive, –p will have no effect because the system configuration is not present in the archive.

–s

Install silently.

–u

Unconfigure the system after installing it. If installing from a Unified Archive and the archive is not a recovery archive, this is the default.

–U

Update all packages within the zone to their latest versions which are compatible with the packages installed in the global zone. The –U option may only be used together with the –a option.

–v

Verbose output from the install process.

–x cert=path
–x cacert=path
–x key=path

Use the specified certificate, CA certificate, and/or key when installing from a Unified Archive at a https URI. Only valid with the –a option.

migrate [–t auto] –z ZBE] [–u | –U] [–x destroy-orphan-zbes | force-zbe-clone | deny-zbe-clone | attach-last-booted-zbe | attach-matched-zbe | attach-last-mounted-zbe]

Migrate and attach the specified solaris branded zone image on the destination system. Attach the zone image into the zone using the attach options given to the migrate sub-command.

Migration of a solaris branded zone will fail if:

  • No rootzpool resource has been configured

  • fs or dataset resource is configured

  • Device resource does not have the storage property set

  • The npiv:over-hba property is set and there is no zone config on the destination system

For more information, see the attach sub-command section above for the –z, –u, –U and –x option descriptions and the zbe selection criteria.

–t auto

Specifies the type of migration to perform. For the solaris branded zone the only possible value is auto since live migration is not supported.

solaris-kz Brand-Specific Subcommands

The following solaris-kz brand-specific subcommand options are supported.

attach [–c config_profile.xml | dir] [–x force-takeover | initialize-hostdata]

Attach the specified solaris-kz branded zone image into the zone. The zone's bootable device(s) are assumed to already be populated correctly.

The –c option provides a profile or a directory of profiles to apply. For more information, see the sysconfig(8) man page.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

The -x force-takeover extended option clears state information indicating that the zone is installed or running on another system. Use this option with extreme caution: if the same storage is simultaneously used by two instances of a zone, file system will corrupt.

The -x initialize-hostdata extended option reinitializes the encryption key and host data. As with -x force-takeover, ensure the zone is not in use on another system before using this option.

In addition to disabling in-use checking, this options resets any stored data, such as the zone's time of day. It should only be used for recovery purposes when the encryption key has been lost.

boot [-R] -- [-L -Z bootenv | diskn]

If a zone is suspended, the -R option can be used to ignore the suspended image (which is then deleted), and boot afresh.

The diskn option tells the bootloader to boot from a particular disk. The device ID in zonecfg starts with 0 but, the n in diskn is the number of the disk that is seen by the system starting at 1. It is the device ID in zonecfg incremented by 1. So, to boot from device 0 in zonecfg, you must run the following:

# zoneadm -z zonename boot -- disk1

and not disk0.

The –L option tells the bootloader to list the available boot environments. The BE to boot can be interactively selected.

The –Z option tells the bootloader to boot a particular BE.

clone [–c config_profile.xml | dir]

Provides a profile or a directory of profiles to apply after installation from the repository.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

For zoneadm clone, if storage is automatically created, it will be created as the same size as the disk in the source zone.

Only kernel zones that have been completely booted at least once after the installation are supported. All zone's publishers must be accessible from within the zone.

install [–v] [–a archive [–x no-auto-shutdown] | –m manifest.xml] [–c config_profile.xml | dir] [–C install_profile.xml | dir] [–z archived_zone] [–b /path/to/media.iso [–x no-auto-shutdown]] [–x install-size=size] [–x {cert | cacert | key}=path] ...

Kernel zones can be installed with the global zone's publishers and a default AI manifest, with a custom AI manifest, with an ISO image of Solaris installation media, or with a Unified Archive.

Unless the –a, –b, or –m options are used, the default AI manifest, /usr/share/auto_install/manifest/default.xml, and the global zone's pkg publishers are used to perform the installation. The supported media types are the text installer and the automated installer. This allows any supported Oracle Solaris version to be installed. Oracle Solaris 11.2 is the first version supported in a kernel zone.

If an AI manifest is specified with the –m option, an IPS or Unified Archive installation will be performed, based on the content of the AI manifest. See ai_manifest(5).

If an ISO image of bootable Oracle Solaris installation media is provided with the –b option, the kernel zone is booted from the installation media and the install program is run on the zone's console. A console login session is established during installation, allowing for interaction with and/or observation of the install program.

If a Unified Archive is specified with the –a option, the installation is performed from the Unified Archive. If the Unified Archive contains multiple zones (deployable systems in archiveadm info output), the –z option is used to specify which archived zone to install. Unified archives are created with archiveadm(8).

–a archive

Install from the specified Unified Archive. The archived_zone may be a global zone, a kernel zone, or a solaris brand zone. If the archived zone is a solaris brand zone, a non-global to global pkg image transform is performed. For the transform to be successful, the zone's installation environment must have sufficient network access to allow access to all pkg publishers. This is most easily accomplished by allowing the kernel zone's network to be configured via DHCP.

–b /path/to/media.iso

Boot and install from the given media.

–c config_profile.xml | dir

Provides a profile or a directory of profiles to apply after installation from the repository.

All profiles must have an .xml extension. By default, profiles will be installed in the sysconfig-profile smf layer. If a profile file exists in a subdirectory of dir named enterprise, site, or node, the profile will be applied at the enterprise-profile, site-profile, or node-profile layer. All other profiles will be applied at the sysconfig-profile layer. For more information, see the smf(7) man page.

–C install_profile.xml | dir

Provides a profile or a directory of profiles to apply to the installation environment when booted to AI media to perform the install.

All profiles must have an .xml extension.

–m manifest.xml

Manifest file to be specified to the automated installer.

–x install-size=size

Explicitly set the size of the root file system (default is 16g). The size can be specified with trailing letters such as 't', 'g', 'm', 'k', or 'b', or without any trailing letters to indicate bytes. The maximum size depends on the free space of the rpool.

–x no-auto-shutdown

Leaves the kernel zone login to the console after installation, allowing for interactions with the install system. This option is only valid with the –a or the –b options.

–x cert=path
–x cacert=path
–x key=path

Use the specified certificate, CA certificate, and/or key when installing from a Unified Archive at a https URI. Only valid with the –a option.

–v

Verbose output from the install process.

–z archived_zone

Install the zone using archived_zone from the Unified Archive. See Deployable Systems in the output of archiveadm(8) info command for a list of valid values for a particular Unified Archive. Only valid with the –a option.

migrate [–c cipher] [–t auto | live]
–c cipher

Use the specified cipher to encrypt memory transfer. The value "none" disables encryption. The value "list" may be used to list supported ciphers. If not specified, a cipher will be automatically chosen based on the source and destination capabilities.

–t auto | live

Specifies the type of migration to perform. If a live migration is specified then only a migration of a running zone is supported. If auto is chosen then the zone will be cold migrated for an installed zone or live migrated for a running zone. If no type is given then the default is auto.

solaris10 Brand-Specific Subcommands

The following solaris10 brand-specific subcommand options are supported.

attach [–c sysidcfg]

Attach the specified solaris10 branded zone image into the branded zone.

clone [–c sysidcfg]

Install a zone by copying an existing installed zone. This subcommand is an alternate way to install the zone.

–c sysidcfg

Provides a sysidcfg file to apply after unconfiguration of the cloned zone.

install –a unified_archive [–z archived_zone] [–x {cert | cacert | key}=path] [–p|–u] [–s|–v] [–c sysidcfg]

install <–a archive | –d path> <–p|–u> [–s|–v] [–c sysidcfg]

The solaris10 brand installer supports installing the zone from an image of an installed Solaris 10 system. This can be a Unified Archive, cpio(1), pax(1), xustar, or ZFS archive. The cpio or ZFS archive can be compressed with gzip(1) or bzip2(1). The image can also be a level 0 ufsdump(8), or a path to the top-level of a Solaris 10 system's root directory tree. The zone cannot be installed from standard Solaris 10 distribution media.

To install the zone from a system or zone image, either the –a or –d options is required. If either the –a or –d options is used, either the –u or –p option is also required.

–a archive

The path or file, http, or https URI of a Unified Archive. Alternatively, the path of a cpio(1), pax(1) xustar, ZFS archive, or a level 0 ufsdump(8) of an installed global zone or non-global zone.

If a Unified Archive is specified, the –z option may be used to select which archived zone is to be installed. If the Unified Archive is on a secure web server (https URI), –x may be used to specify the path to a PEM-encoded certificate, CA certificate, and/or a key. When installing from a Unified Archive, if neither –u nor –p are specified, the default –p is implied if the archive is a recovery archive. Otherwise, –u is implied.

If a ZFS archive contains multiple boot environments, the active boot environment are installed. If install is unable to determine which boot environment is the active boot environment, install provides a list of boot environments extracted and suggest an attach command that uses the –z option to attach a specific boot environment.

–c sysidcfg

Provides a sysidcfg file to apply after installation.

–d path

The path to the root directory of an installed Solaris 10 system.

–p

Preserve the system configuration after installing the zone from an archive or a path. If installing from a Unified Archive and the archive is a recovery archive, –p is implied but can be overridden with –u.

–x cert=/path/cert.pem
–x cacert=/path/cacert.pem
–x key=/path/key.pem

Use the specified certificate, CA certificate, and/or key for https access to the Unified Archive.

If the archive is not a recovery archive, –p will have no effect because the system configuration is not present in the archive.

–s

Install silently.

–u

Run sys-unconfig on the zone after installing it. If installing from a Unified Archive and the archive is not a recovery archive, -u is implied.

–v

Verbose output from the install process.

Examples

Example 1 Using the –m Option

The following command illustrates the use of the –m option.

# zoneadm -z myzone boot -- -m verbose
Example 2 Using the –s Option

The following command illustrates the use of the –s option.

# zoneadm -z myzone boot -- -s
Example 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.

Example 4 Applying the Zone Configuration to the Running Zone

The following command illustrates how to apply the zone configuration to a running zone.

# zoneadm -z zone apply
Example 5 Live Migrating to a New Host

The following command illustrates how to live migrate to a new host.

# zoneadm -z myzone migrate -t live ssh://destinationhost
zoneadm: zone 'myzone': Using zone configuration on destination.
zoneadm: zone 'myzone': Attaching zone.
zoneadm: zone 'myzone': Booting zone in 'migrating-in' mode.
zoneadm: zone 'myzone': Checking migration compatibility.
zoneadm: zone 'myzone': Starting migration.
zoneadm: zone 'myzone': Waiting for migration to complete.
zoneadm: zone 'myzone': Migration successful.
zoneadm: zone 'myzone': Halting and detaching zone.
Example 6 Move a Zone to Shared Storage

The following command illustrates how to move a zone installation out of its current location into a new ZFS storage pool on shared storage. The zonepath remains unchanged.

# zoneadm -z myzone move -p \
  iscsi://10.10.10.9/luname.naa.600144f03d70c80000004ea57da10001 -
Example 7 Move a Zone from one Shared Storage to another

The following command illustrates how to move a zone installation already configured using a rootzpool resource to a new ZFS storage pool built on a new shared storage device. The original zpool is destroyed. The zonepath is changed as well.

# zoneadm -z myzone move \
  -p iscsi://10.10.2.9/luname.naa.600144f03d70c60000004ea57dacd122 \
  -x force-zpool-destroy=rpool /system/zones/moved-myzone
Example 8 Move a Zone from Shared Storage to Local Filesystem

The following command illustrates how to move a zone installation configured using a rootzpool resource out of its containing ZFS storage pool into the local file system. The original zpool associated with the rootzpool resource is exported by default and not destroyed.

# zoneadm -z myzone move -x remove-rootzpool -
Example 9 Change zonepath for a Zone

The following command illustrates how to change the zonepath without moving the zone installation.

# zoneadm -z myzone move /system/zones/moved-myzone
Example 10 Cold Migration of Solaris Zone to a New Host

The following command illustrates cold migration of a solaris zone to a new host.

# zoneadm -z myzone migrate ssh://destinationhost
zoneadm: zone 'z1': Importing zone configuration.
zoneadm: zone 'z1': Attaching zone.
zoneadm: zone 'z1': Migration successful.
zoneadm: zone 'z1': Cleaning up.

Exit Status

The following exit values are returned:

0

Successful completion.

1

An error occurred.

2

Invalid usage.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/zones
Interface Stability
Committed

See Also

attributes(7), brands(7), cpio(1), init(8), kernel(8), libuuid(3LIB), mwac(7), pax(1), rad(8), read(1), smf(7), solaris(7), solaris-kz(7), suri(7), svc.startd(8), svc.startd(8), svcadm(8), svcs(1), sysadm(8), sysconfig(8), zfs(4FS), zlogin(1), zonecfg(8), zonename(1), zones(7), zpool(8)

Oracle OpenBoot 4.x Administration Guide

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.

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.