zoneadm(1M) - administer zones
-
System Administration Commands zoneadm(1M) 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 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. SECURITY 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. zoneadm 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. Once a process has been placed in a zone other than zone 0, neither that process nor any of its children can 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] [-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 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 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. -x force-zpool-create -x force-zpool-create-all Specify -x 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 con- fig name property. These options are only available for archive-based attach usage. See brands(5) for the information which brands support archive-based attach. 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. -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 non-read only root zones. -x storage-create-missing Specify this option to create storage, if needed. 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(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] [-x extended_options] [brand-specific options] 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. Note, this is the default (and only supported) clone method for zones that have a rootzpool resource configured. -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. -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 con- fig name property. -x storage-create-missing Specify this option to create storage, if needed. The source zone must be halted before this subcommand can be used. For force creation of the root zpool of a kernel zone use -x force- zpool-create=<root_pool_name> command, where root_pool_name is the name of the root zpool in the source zone. Kernel zones do not sup- port -x force-zpool-create-all. detach [-F | -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. The -F option can be used to forcefully detach the zone without per- forming 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 manu- ally 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 tar- get host. 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 spec- ified, only the value of that variable is displayed. The get-prom subcommand is only supported by the solaris-kz(5) brand on SPARC. set-prom variable=[value] set-prom -c variable In the first form, the set-prom subcommand sets the specified Open- Boot 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 indi- cates 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(5) brand on SPARC. It may only be used when the zone is in the installed state. 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. help [subcommand] Display general help. If you specify subcommand, displays help on subcommand. install [-x extended_options] [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. -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 con- fig name property. -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(5) for specific brand information. For force creation of the root zpool of a kernel zone use -x force- zpool-create=<root_pool_name> command, 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. 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:\ r/w:file-mac-profile 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. apply [-n] [-q] [-x extended_options] The apply subcommand reconfigures a running zone to match persis- tent configuration of a zone maintained through zonecfg(1M) and prints out performed actions. Applied configuration takes effect immediately and does not require reboot of the zone. The apply com- mand is available only for running zones. See respective brand man page for details on resources supported by the live zone reconfigu- ration. The following options are supported: -n Runs the reconfiguration in a dry run mode that does not change the configu- ration of a running zone. The dry run mode acts the same way as the real reconfiguration, but leaves the run- ning zone intact. Use the dry run mode to review actions that would be per- formed 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. 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 com- mand can be useful in cases where administrative changes on the system have rendered a zone permanently unusable or inconsis- tent. This change cannot be undone, except by uninstalling the zone. unavailable Change the state of an installed zone to unavailable. This com- mand can be useful in cases where administrative changes or failures on the system have rendered a zone temporarily unus- able. This change can be undone with the attach subcommand. migrate [-nq] [-c cipher] ssh|rads|rad://user@host:port Live-migrate the zone to the given destination host. The zone will continue running on the source host until the final stage of migra- tion. After a migration, any zlogin sessions will be terminated. However, network connections to the zone are maintained. 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(1M)) that is accessible by both hosts. The zone can be configured on the destination host prior to migra- tion; 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 miss- ing), an error will be returned. If the zone is not configured on the destination, live 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(1M)). The scheme defaults to 'rads', 'user' defaults to the current user, and 'port' defaults to the standard RAD port. To receive migrating zones, the RAD service mentioned must be run- ning. In addition, the 'kz-migr' service under inetd must be enabled. 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 run- ning. -q Quiet: does not report status during migration. -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 speci- fied, a cipher will be automatically chosen based on the source and destination capabilities. 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. Note, for zones configured with a rootzpool resource only the zonepath will be renamed but the zone itself will not move out of its containing zpool. 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. 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. rename new_zonename Rename the zone. This subcommand may be used for configured and installed zones. The installed zone must be halted before this sub- command 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 sub- command. shutdown [-k] [-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 suc- cessfully 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. savecore [-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 opera- tion. If -k is specified then the core dump is placed in the location configured by coreadm(1M) for kernel zone core dumps. suspend Suspend a running solaris-kz brand zone to disk. The zone is sus- pended to an image file contained within the zone path. The zone can be resumed through zoneadm boot. 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 con- fig name property. 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 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. 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. 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 Live Migrating to a New Host The following command illustrates how to migrate to a new host. # zoneadm -z myzone migrate 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. 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 ALSO read(1), svcs(1), zlogin(1), zonename(1), init(1M), kernel(1M), svcadm(1M), zpool(1M), svc.startd(1M), svc.startd(1M), zonecfg(1M), libuuid(3LIB), attributes(5), brands(5), mwac(5), smf(5), zones(5), zfs(7FS), suri(5), solaris-kz(5), rad(1M) OpenBoot 4.x Command Reference Manual 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. 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 dis- abled. Care must be taken that the zone is otherwise protected. SunOS 5.11 2 Jun 2015 zoneadm(1M)
© Lightnetics 2024