1 ZONEADM(1M)                  Maintenance Commands                  ZONEADM(1M)
   2 
   3 
   4 
   5 NAME
   6        zoneadm - administer zones
   7 
   8 SYNOPSIS
   9        zoneadm -z zonename [-u uuid-match] subcommand
  10             [subcommand_options]
  11 
  12 
  13        zoneadm [-R root] [-z zonename] [-u uuid-match] list
  14             [list_options]
  15 
  16 
  17        zoneadm [-R root] -z zonename [-u uuid-match] mark incomplete
  18 
  19 
  20 DESCRIPTION
  21        The zoneadm utility is used to administer system zones. A zone is an
  22        application container that is maintained by the operating system
  23        runtime.
  24 
  25 SECURITY
  26        Once a process has been placed in a zone other than zone 0, the process
  27        or any of its children cannot change zones.
  28 
  29 OPTIONS
  30        The following options are supported:
  31 
  32        -R root
  33            Specify an alternate root (boot environment). This option can only
  34            be used in conjunction with the "list" and "mark" subcommands.
  35 
  36 
  37        -u uuid-match
  38            Unique identifier for a zone, as assigned by libuuid(3LIB). If this
  39            option is present and the argument is a non-empty string, then the
  40            zone matching the UUID is selected instead of the one named by the
  41            -z option, if such a zone is present.
  42 
  43 
  44        -z zonename
  45            String identifier for a zone.
  46 
  47 
  48 SUBCOMMANDS
  49        Subcommands which can result in destructive actions or loss of work
  50        have a -F flag to force the action. If input is from a terminal device,
  51        the user is prompted if such a command is given without the -F flag;
  52        otherwise, if such a command is given without the -F flag, the action is
  53        disallowed, with a diagnostic message written to standard error. If a
  54        zone installation or uninstallation is interrupted, the zone is left in
  55        the incomplete state. Use uninstall to reset such a zone back to the
  56        configured state.
  57 
  58 
  59        The following subcommands are supported:
  60 
  61        attach [-F] [-n path] [brand-specific options]
  62            The attach subcommand takes a zone that has been detached from one
  63            system and attaches the zone onto a new system. Therefore, it is
  64            advised (though not required) that the detach subcommand should be
  65            run before the "attach" takes place. Once you have the new zone in
  66            the configured state, use the attach subcommand to set up the zone
  67            root instead of installing the zone as a new zone.
  68 
  69            The -F option can be used to force the zone into the "installed"
  70            state with no validation. This option should be used with care
  71            since it can leave the zone in an unsupportable state if it was
  72            moved from a source system to a target system that is unable to
  73            properly host the zone. The -n option can be used to run the attach
  74            subcommand, without executing the command. It uses the output of
  75            the "detach -n" subcommand as input and is useful to identify any
  76            conflicting issues, such as the network device being incompatible,
  77            and can also determine whether the host is capable of supporting
  78            the zone. The path can be "-", to read the input from standard
  79            input.
  80 
  81            The zone's brand may include additional options that govern how the
  82            zone will be attached. See brands(5) for specific brand
  83            information.
  84 
  85            The zone being attached must first be configured using the zonecfg
  86            (see zonecfg(1M)) command. This does not apply when running "attach
  87            -n".
  88 
  89            Use the following command to attach a zone:
  90 
  91              # zoneadm -z my-zone attach
  92 
  93 
  94 
  95 
  96        boot [-- boot_options]
  97            Boot (or activate) the specified zones.
  98 
  99            The following boot_options are supported:
 100 
 101            -i altinit
 102                Select an alternative executable to be the primordial Process.
 103                altinit is a valid path to an executable. The default
 104                primordial process is init(1M).
 105 
 106 
 107            -m smf_options
 108                The smf_options include two categories of options to control
 109                booting behavior of the service management facility: recovery
 110                options and messages options.
 111 
 112                Message options determine the type and amount of messages that
 113                smf(5) displays during boot. Service options determine the
 114                services which are used to boot the system. See kernel(1M) for
 115                a listing of the -m suboptions.
 116 
 117 
 118            -s
 119                Boots only to milestone svc:/milestone/single-user:default. This
 120                milestone is equivalent to init level s. See svc.startd(1M) and
 121                init(1M).
 122 
 123 
 124 
 125        clone [-m copy] [-s zfs_snapshot] source_zone
 126            Install a zone by copying an existing installed zone. This
 127            subcommand is an alternative way to install the zone.
 128 
 129            -m copy
 130                Force the clone to be a copy, even if a "ZFS clone" is
 131                possible.
 132 
 133 
 134            -s zfs_snapshot
 135                Specify the name of a ZFS snapshot to use as the source of the
 136                clone. The snapshot must be a snapshot of the source zone taken
 137                from a previous "zoneadm clone" installation.
 138 
 139            The source zone must be halted before this subcommand can be used.
 140 
 141 
 142        detach [-n]
 143            Detach the specified zone. Detaching a zone is the first step in
 144            moving a zone from one system to another. The full procedure to
 145            migrate a zone is that the zone is detached, the zonepath directory
 146            is moved to the new host, and then the zone is attached on the new
 147            host. Once the zone is detached, it is left in the configured
 148            state. If you try to install or clone to a configured zone that has
 149            been detached, you will receive an error message and the install or
 150            clone subcommand will not be allowed to proceed. The -n option can
 151            be used to run the detach subcommand, without executing the
 152            command. This generates the information needed for running the
 153            "attach -n" subcommand, which is useful to identify any conflicting
 154            issues, such as the network device being incompatible or if the
 155            host is capable of supporting the zone. The information is sent to
 156            standard output and can be saved to a file or piped to the "attach
 157            -n" subcommand.
 158 
 159            Use the following command to detach a zone:
 160 
 161              # zoneadm -z my-zone detach
 162 
 163 
 164            The source zone must be halted before this subcommand can be used.
 165 
 166 
 167        halt
 168            Halt the specified zones. halt bypasses running the shutdown
 169            scripts inside the zone. It also removes run time resources of the
 170            zone.
 171 
 172 
 173        help [subcommand]
 174            Display general help. If you specify subcommand, displays help on
 175            subcommand.
 176 
 177 
 178        install [-x nodataset] [brand-specific options]
 179            Install the specified zone on the system. This subcommand
 180            automatically attempts to verify first, most verification errors
 181            are fatal. See the verify subcommand.
 182 
 183            -x nodataset
 184                Do not create a ZFS file system.
 185 
 186            The zone's brand may include additional options that govern how the
 187            software will be installed in the zone. See brands(5) for specific
 188            brand information.
 189 
 190 
 191        list [list_options]
 192            Display the name of the current zones, or the specified zone if
 193            indicated.
 194 
 195            By default, all running zones are listed. If you use this
 196            subcommand with the zoneadm -z zonename option, it lists only the
 197            specified zone, regardless of its state. In this case, the -i and -c
 198            options are disallowed.
 199 
 200            If neither the -i or -c options are given, all running zones are
 201            listed.
 202 
 203            The following list_options are supported:
 204 
 205            -c
 206                Display all configured zones. This option overides the -i
 207                option.
 208 
 209 
 210            -i
 211                Expand the display to all installed zones.
 212 
 213 
 214            -p
 215                Request machine parsable output. The output format is a list of
 216                lines, one per zone, with colon- delimited fields. These fields
 217                are:
 218 
 219                  zoneid:zonename:state:zonepath:uuid:brand:ip-type
 220 
 221 
 222                If the zonepath contains embedded colons, they can be escaped
 223                by a backslash (":"), which is parsable by using the shell
 224                read(1) function with the environmental variable IFS. The uuid
 225                value is assigned by libuuid(3LIB) when the zone is installed,
 226                and is useful for identifying the same zone when present (or
 227                renamed) on alternate boot environments. Any software that
 228                parses the output of the "zoneadm list -p" command must be able
 229                to handle any fields that may be added in the future.
 230 
 231                The -v and -p options are mutually exclusive. If neither -v nor -p
 232                is used, just the zone name is listed.
 233 
 234 
 235            -v
 236                Display verbose information, including zone name, id, current
 237                state, root directory, brand type, ip-type, and options.
 238 
 239                The -v and -p options are mutually exclusive. If neither -v nor -p
 240                is used, just the zone name is listed.
 241 
 242 
 243 
 244        mark incomplete
 245            Change the state of an installed zone to "incomplete." This command
 246            may be useful in cases where administrative changes on the system
 247            have rendered a zone unusable or inconsistent. This change cannot
 248            be undone (except by uninstalling the zone).
 249 
 250 
 251        move new_zonepath
 252            Move the zonepath to new_zonepath. The zone must be halted before
 253            this subcommand can be used. The new_zonepath must be a local file
 254            system and normal restrictions for zonepath apply.
 255 
 256 
 257        ready
 258            Prepares a zone for running applications but does not start any
 259            user processes in the zone.
 260 
 261 
 262        reboot[-- boot_options]]
 263            Restart the zones. This is equivalent to a halt boot sequence. This
 264            subcommand fails if the specified zones are not active. See boot
 265            subcommand for the boot options.
 266 
 267 
 268        shutdown [-r [-- boot_options]]
 269            Gracefully shutdown the specified zone. This subcommand waits for
 270            all zone processes to finish; the default timeout is
 271            SCF_PROPERTY_TIMEOUT value from the SMF service system/zones. If
 272            the -r option is specified, reboot the zone. See boot subcommand for
 273            the boot options.
 274 
 275 
 276        uninstall [-F]
 277            Uninstall the specified zone from the system. Use this subcommand
 278            with caution.  It removes all of the files under the zonepath of
 279            the zone in question.  You can use the -F flag to force the action.
 280 
 281 
 282        verify
 283            Check to make sure the configuration of the specified zone can
 284            safely be installed on the machine. Following is a break-down of the
 285            checks by resource/property type:
 286 
 287            zonepath
 288                zonepath and its parent directory exist and are owned by root
 289                with appropriate modes . The appropriate modes are that
 290                zonepath is 700, its parent is not group or world-writable and
 291                so forth.  zonepath is not over an NFS mount. A sub-directory of
 292                the zonepath named "root" does not exist.
 293 
 294                If zonepath does not exist, the verify does not fail, but
 295                merely warns that a subsequent install will attempt to create
 296                it with proper permissions. A verify subsequent to that might
 297                fail should anything go wrong.
 298 
 299                zonepath cannot be a symbolic link.
 300 
 301 
 302            fs
 303                Any fs resources have their type value checked. An error is
 304                reported if the value is one of proc, mntfs, autofs, cachefs,
 305                or nfs or the filesystem does not have an associated mount
 306                binary at /usr/lib/fs/<fstype>/mount.
 307 
 308                It is an error for the directory to be a relative path.
 309 
 310                It is an error for the path specified by raw to be a relative
 311                path or if there is no fsck binary for a given filesystem type
 312                at /usr/lib/fs/<fstype>/fsck. It   is also an error if a
 313                corresponding fsck binary exists but a raw path is not
 314                specified.
 315 
 316 
 317            net
 318                All physical network interfaces exist. All network address
 319                resources are one of:
 320 
 321                    o      a valid IPv4 address, optionally followed by "/" and
 322                           a prefix length;
 323 
 324                    o      a valid IPv6 address, which must be followed by "/"
 325                           and a prefix length;
 326 
 327                    o      a host name which resolves to an IPv4 address.
 328                Note that hostnames that resolve to IPv6 addresses are not
 329                supported.
 330 
 331                The physical interface name is the network interface name.
 332 
 333                A zone can be configured to be either exclusive-IP or shared-IP.
 334                For a shared-IP zone, both the physical and address properties
 335                must be set. For an exclusive-IP zone, the physical property
 336                must be set and the address property cannot be set.
 337 
 338 
 339            rctl
 340                It also verifies that any defined resource control values are
 341                valid on the current machine. This means that the privilege
 342                level is privileged, the limit is lower than the currently
 343                defined system value, and that the defined action agrees with
 344                the actions that are valid for the given resource control.
 345 
 346 
 347 
 348 EXAMPLES
 349        Example 1 Using the -m Option
 350 
 351 
 352        The following command illustrates the use of the -m option.
 353 
 354 
 355          # zoneadm boot -- -m verbose
 356 
 357 
 358 
 359        Example 2 Using the -i Option
 360 
 361 
 362        The following command illustrates the use of the -i option.
 363 
 364 
 365          # zoneadm boot -- -i /sbin/init
 366 
 367 
 368 
 369        Example 3 Using the -s Option
 370 
 371 
 372        The following command illustrates the use of the -s option.
 373 
 374 
 375          # zoneadm boot -- -s
 376 
 377 
 378 
 379 EXIT STATUS
 380        The following exit values are returned:
 381 
 382        0
 383            Successful completion.
 384 
 385 
 386        1
 387            An error occurred.
 388 
 389 
 390        2
 391            Invalid usage.
 392 
 393 
 394 ATTRIBUTES
 395        See attributes(5) for descriptions of the following attributes:
 396 
 397 
 398 
 399 
 400        +--------------------+-----------------+
 401        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 402        +--------------------+-----------------+
 403        |Interface Stability | Committed       |
 404        +--------------------+-----------------+
 405 
 406 SEE ALSO
 407        read(1), svcs(1), zlogin(1), zonename(1), init(1M), kernel(1M),
 408        svcadm(1M), svc.startd(1M), svc.startd(1M), zonecfg(1M), libuuid(3LIB),
 409        attributes(5), brands(5), native(5), smf(5), zones(5)
 410 
 411 NOTES
 412        The zones(5) service is managed by the service management facility,
 413        smf(5), under the service identifier:
 414 
 415          svc:/system/zones:default
 416 
 417 
 418 
 419 
 420        Administrative actions on this service, such as enabling, disabling, or
 421        requesting restart, can be performed using svcadm(1M). The service's
 422        status can be queried using the svcs(1) command.
 423 
 424 
 425        The act of installing a new non-global zone is a fresh installation of
 426        the Solaris operating system. A new installation of Solaris must not
 427        require interaction with the user (that is, it must be "hands off").
 428        Because of this, packages installed in the global zone and all non-
 429        global zones cannot contain request scripts (see pkgask(1M)). If a
 430        package did have a request script, then the creation of a non-global
 431        zone could not be done without user intervention. Any package that
 432        contains a request script is added to the global zone only. See
 433        pkgadd(1M).
 434 
 435 
 436 
 437                                December 26, 2014                   ZONEADM(1M)