1 '\" te
   2 .\" Copyright 2014 Nexenta Systems, Inc. All rights reserved.
   3 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH ZONEADM 1M "Dec 26, 2014"
   8 .SH NAME
   9 zoneadm \- administer zones
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBzoneadm\fR \fB-z\fR \fIzonename\fR [\fB-u\fR \fIuuid-match\fR] \fIsubcommand\fR
  14      [\fIsubcommand_options\fR]
  15 .fi
  16 
  17 .LP
  18 .nf
  19 \fBzoneadm\fR [\fB-R\fR \fIroot\fR] [\fB-z\fR \fIzonename\fR] [\fB-u\fR \fIuuid-match\fR] list
  20      [\fIlist_options\fR]
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBzoneadm\fR [\fB-R\fR \fIroot\fR] \fB-z\fR \fIzonename\fR [\fB-u\fR \fIuuid-match\fR] mark incomplete
  26 .fi
  27 
  28 .SH DESCRIPTION
  29 .LP
  30 The \fBzoneadm\fR utility is used to administer system zones. A zone is an
  31 application container that is maintained by the operating system runtime.
  32 .SH SECURITY
  33 .LP
  34 Once a process has been placed in a zone other than zone \fB0\fR, the process
  35 or any of its children cannot change zones.
  36 .SH OPTIONS
  37 .LP
  38 The following options are supported:
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fB-R\fR \fIroot\fR\fR
  43 .ad
  44 .sp .6
  45 .RS 4n
  46 Specify an alternate root (boot environment). This option can only be used in
  47 conjunction with the "\fBlist\fR" and "\fBmark\fR" subcommands.
  48 .RE
  49 
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fB-u\fR \fIuuid-match\fR\fR
  54 .ad
  55 .sp .6
  56 .RS 4n
  57 Unique identifier for a zone, as assigned by \fBlibuuid\fR(3LIB). If this
  58 option is present and the argument is a non-empty string, then the zone
  59 matching the \fBUUID\fR is selected instead of the one named by the \fB-z\fR
  60 option, if such a zone is present.
  61 .RE
  62 
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fB-z\fR \fIzonename\fR\fR
  67 .ad
  68 .sp .6
  69 .RS 4n
  70 String identifier for a zone.
  71 .RE
  72 
  73 .SH SUBCOMMANDS
  74 .LP
  75 Subcommands which can result in destructive actions or loss of work have a
  76 \fB-F\fR flag to force the action. If input is from a terminal device, the user
  77 is prompted if such a command is given without the \fB-F\fR flag; otherwise, if
  78 such a command is given without the \fB-F\fR flag, the action is disallowed,
  79 with a diagnostic message written to standard error. If a zone installation or
  80 uninstallation is interrupted, the zone is left in the incomplete state. Use
  81 uninstall to reset such a zone back to the configured state.
  82 .sp
  83 .LP
  84 The following subcommands are supported:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBattach\fR [\fB-F\fR] [\fB-n\fR \fIpath\fR] [\fIbrand-specific
  89 options\fR]\fR
  90 .ad
  91 .sp .6
  92 .RS 4n
  93 The \fBattach\fR subcommand takes a zone that has been detached from one system
  94 and attaches the zone onto a new system. Therefore, it is advised (though not
  95 required) that the \fBdetach\fR subcommand should be run before the "attach"
  96 takes place. Once you have the new zone in the configured state, use the
  97 \fBattach\fR subcommand to set up the zone root instead of installing the zone
  98 as a new zone.
  99 .sp
 100 The \fB-F\fR option can be used to force the zone into the "installed" state
 101 with no validation. This option should be used with care since it can leave the
 102 zone in an unsupportable state if it was moved from a source system to a target
 103 system that is unable to properly host the zone. The \fB-n\fR option can be
 104 used to run the \fBattach\fR subcommand, without executing the command. It uses
 105 the output of the "\fBdetach\fR \fB-n\fR" subcommand as input and is useful to
 106 identify any conflicting issues, such as the network device being incompatible,
 107 and can also determine whether the host is capable of supporting the zone. The
 108 path can be "\fB-\fR", to read the input from standard input.
 109 .sp
 110 The zone's brand may include additional options that govern how the zone will
 111 be attached. See \fBbrands\fR(5) for specific brand information.
 112 .sp
 113 The zone being attached must first be configured using the \fBzonecfg\fR (see
 114 \fBzonecfg\fR(1M)) command. This does not apply when running "\fBattach\fR
 115 \fB-n\fR".
 116 .sp
 117 Use the following command to attach a zone:
 118 .sp
 119 .in +2
 120 .nf
 121 # \fBzoneadm -z my-zone attach\fR
 122 .fi
 123 .in -2
 124 .sp
 125 
 126 .RE
 127 
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBboot\fR [\fB--\fR \fIboot_options\fR]\fR
 132 .ad
 133 .sp .6
 134 .RS 4n
 135 Boot (or activate) the specified zones.
 136 .sp
 137 The following \fIboot_options\fR are supported:
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fB-i\fR \fIaltinit\fR\fR
 142 .ad
 143 .sp .6
 144 .RS 4n
 145 Select an alternative executable to be the primordial Process. \fIaltinit\fR is
 146 a valid path to an executable. The default primordial process is
 147 \fBinit\fR(1M).
 148 .RE
 149 
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fB-m\fR \fIsmf_options\fR\fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 The \fIsmf_options\fR include two categories of options to control booting
 158 behavior of the service management facility: recovery options and messages
 159 options.
 160 .sp
 161 Message options determine the type and amount of messages that \fBsmf\fR(5)
 162 displays during boot. Service options determine the services which are used to
 163 boot the system. See \fBkernel\fR(1M) for a listing of the \fB-m\fR suboptions.
 164 .RE
 165 
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fB-s\fR\fR
 170 .ad
 171 .sp .6
 172 .RS 4n
 173 Boots only to milestone \fBsvc:/milestone/single-user:default\fR. This
 174 milestone is equivalent to init level \fBs\fR. See \fBsvc.startd\fR(1M) and
 175 \fBinit\fR(1M).
 176 .RE
 177 
 178 .RE
 179 
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBclone\fR [\fB-m\fR \fIcopy\fR] [\fB-s\fR \fIzfs_snapshot\fR]
 184 \fIsource_zone\fR\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 Install a zone by copying an existing installed zone. This subcommand is an
 189 alternative way to install the zone.
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fB-m\fR \fIcopy\fR\fR
 194 .ad
 195 .sp .6
 196 .RS 4n
 197 Force the clone to be a copy, even if a "\fBZFS\fR clone" is possible.
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fB-s\fR \fIzfs_snapshot\fR\fR
 204 .ad
 205 .sp .6
 206 .RS 4n
 207 Specify the name of a \fBZFS\fR snapshot to use as the source of the clone. The
 208 \fIsnapshot\fR must be a \fIsnapshot\fR of the source zone taken from a
 209 previous "\fBzoneadm\fR clone" installation.
 210 .RE
 211 
 212 The source zone must be halted before this subcommand can be used.
 213 .RE
 214 
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBdetach\fR [\fB-n\fR]\fR
 219 .ad
 220 .sp .6
 221 .RS 4n
 222 Detach the specified zone. Detaching a zone is the first step in moving a zone
 223 from one system to another. The full procedure to migrate a zone is that the
 224 zone is detached, the \fIzonepath\fR directory is moved to the new host, and
 225 then the zone is attached on the new host. Once the zone is detached, it is
 226 left in the configured state. If you try to install or clone to a configured
 227 zone that has been detached, you will receive an error message and the
 228 \fBinstall\fR or \fBclone\fR subcommand will not be allowed to proceed. The
 229 \fB-n\fR option can be used to run the \fBdetach\fR subcommand, without
 230 executing the command. This generates the information needed for running the
 231 "\fBattach\fR \fB-n\fR" subcommand, which is useful to identify any conflicting
 232 issues, such as the network device being incompatible or if the host is capable
 233 of supporting the zone. The information is sent to standard output and can be
 234 saved to a file or piped to the "\fBattach\fR \fB-n\fR" subcommand.
 235 .sp
 236 Use the following command to detach a zone:
 237 .sp
 238 .in +2
 239 .nf
 240 # zoneadm -z my-zone detach
 241 .fi
 242 .in -2
 243 .sp
 244 
 245 The source zone must be halted before this subcommand can be used.
 246 .RE
 247 
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBhalt\fR\fR
 252 .ad
 253 .sp .6
 254 .RS 4n
 255 Halt the specified zones. \fBhalt\fR bypasses running the shutdown scripts
 256 inside the zone. It also removes run time resources of the zone.
 257 .RE
 258 
 259 .sp
 260 .ne 2
 261 .na
 262 \fB\fBhelp\fR [\fIsubcommand\fR]\fR
 263 .ad
 264 .sp .6
 265 .RS 4n
 266 Display general help. If you specify \fIsubcommand\fR, displays help on
 267 \fIsubcommand\fR.
 268 .RE
 269 
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fBinstall\fR [\fB-x\fR \fInodataset\fR] [\fIbrand-specific options\fR]\fR
 274 .ad
 275 .sp .6
 276 .RS 4n
 277 Install the specified zone on the system. This subcommand automatically
 278 attempts to verify first, most verification errors are fatal. See the
 279 \fBverify\fR subcommand.
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fB-x\fR \fInodataset\fR\fR
 284 .ad
 285 .sp .6
 286 .RS 4n
 287 Do not create a \fBZFS\fR file system.
 288 .RE
 289 
 290 The zone's brand may include additional options that govern how the software
 291 will be installed in the zone. See \fBbrands\fR(5) for specific brand
 292 information.
 293 .RE
 294 
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fBlist\fR [\fIlist_options\fR]\fR
 299 .ad
 300 .sp .6
 301 .RS 4n
 302 Display the name of the current zones, or the specified zone if indicated.
 303 .sp
 304 By default, all running zones are listed. If you use this subcommand with the
 305 \fBzoneadm\fR \fB-z\fR \fIzonename\fR option, it lists only the specified zone,
 306 regardless of its state. In this case, the \fB-i\fR and \fB-c\fR options are
 307 disallowed.
 308 .sp
 309 If neither the \fB-i\fR or \fB-c\fR options are given, all running zones are
 310 listed.
 311 .sp
 312 The following \fIlist_options\fR are supported:
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fB-c\fR\fR
 317 .ad
 318 .sp .6
 319 .RS 4n
 320 Display all configured zones. This option overides the \fB-i\fR option.
 321 .RE
 322 
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fB-i\fR\fR
 327 .ad
 328 .sp .6
 329 .RS 4n
 330 Expand the display to all installed zones.
 331 .RE
 332 
 333 .sp
 334 .ne 2
 335 .na
 336 \fB\fB-p\fR\fR
 337 .ad
 338 .sp .6
 339 .RS 4n
 340 Request machine parsable output. The output format is a list of lines, one per
 341 zone, with colon- delimited fields. These fields are:
 342 .sp
 343 .in +2
 344 .nf
 345 zoneid:zonename:state:zonepath:uuid:brand:ip-type
 346 .fi
 347 .in -2
 348 .sp
 349 
 350 If the \fBzonepath\fR contains embedded colons, they can be escaped by a
 351 backslash ("\:"), which is parsable by using the shell \fBread\fR(1) function
 352 with the environmental variable \fBIFS\fR. The \fIuuid\fR value is assigned by
 353 \fBlibuuid\fR(3LIB) when the zone is installed, and is useful for identifying
 354 the same zone when present (or renamed) on alternate boot environments. Any
 355 software that parses the output of the "\fBzoneadm list -p\fR" command must be
 356 able to handle any fields that may be added in the future.
 357 .sp
 358 The \fB-v\fR and \fB-p\fR options are mutually exclusive. If neither \fB-v\fR
 359 nor \fB-p\fR is used, just the zone name is listed.
 360 .RE
 361 
 362 .sp
 363 .ne 2
 364 .na
 365 \fB\fB-v\fR\fR
 366 .ad
 367 .sp .6
 368 .RS 4n
 369 Display verbose information, including zone name, id, current state, root
 370 directory, brand type, ip-type, and options.
 371 .sp
 372 The \fB-v\fR and \fB-p\fR options are mutually exclusive. If neither \fB-v\fR
 373 nor \fB-p\fR is used, just the zone name is listed.
 374 .RE
 375 
 376 .RE
 377 
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fBmark incomplete\fR\fR
 382 .ad
 383 .sp .6
 384 .RS 4n
 385 Change the state of an installed zone to "incomplete." This command may be
 386 useful in cases where administrative changes on the system have rendered a zone
 387 unusable or inconsistent. This change cannot be undone (except by uninstalling
 388 the zone).
 389 .RE
 390 
 391 .sp
 392 .ne 2
 393 .na
 394 \fB\fBmove\fR \fInew_zonepath\fR\fR
 395 .ad
 396 .sp .6
 397 .RS 4n
 398 Move the \fIzonepath\fR to \fInew_zonepath\fR. The zone must be halted before
 399 this subcommand can be used. The \fInew_zonepath\fR must be a local file system
 400 and normal restrictions for \fIzonepath\fR apply.
 401 .RE
 402 
 403 .sp
 404 .ne 2
 405 .na
 406 \fB\fBready\fR\fR
 407 .ad
 408 .sp .6
 409 .RS 4n
 410 Prepares a zone for running applications but does not start any user processes
 411 in the zone.
 412 .RE
 413 
 414 .sp
 415 .ne 2
 416 .na
 417 \fB\fBreboot\fR\ [\fB--\fR \fIboot_options\fR]]\fR
 418 .ad
 419 .sp .6
 420 .RS 4n
 421 Restart the zones. This is equivalent to a \fBhalt\fR \fBboot\fR sequence. This
 422 subcommand fails if the specified zones are not active. See \fIboot\fR subcommand
 423 for the boot options.
 424 .RE
 425 
 426 .sp
 427 .ne 2
 428 .na
 429 \fB\fBshutdown\fR [\fB-r\fR [\fB--\fR \fIboot_options\fR]]\fR
 430 .ad
 431 .sp .6
 432 .RS 4n
 433 Gracefully shutdown the specified zone. This subcommand waits for all zone
 434 processes to finish; the default timeout is SCF_PROPERTY_TIMEOUT value from
 435 the SMF service system/zones. If the \fB-r\fR option is specified, reboot the
 436 zone. See \fIboot\fR subcommand for the boot options.
 437 .RE
 438 
 439 .sp
 440 .ne 2
 441 .na
 442 \fB\fBuninstall [\fR\fB-F\fR\fB]\fR\fR
 443 .ad
 444 .sp .6
 445 .RS 4n
 446 Uninstall the specified zone from the system. Use this subcommand with caution.
 447 It removes all of the files under the \fIzonepath\fR of the zone in question.
 448 You can use the \fB-F\fR flag to force the action.
 449 .RE
 450 
 451 .sp
 452 .ne 2
 453 .na
 454 \fB\fBverify\fR\fR
 455 .ad
 456 .sp .6
 457 .RS 4n
 458 Check to make sure the configuration of the specified zone can safely be
 459 installed on the machine. Following is a break-down of the checks by
 460 \fBresource/property\fR type:
 461 .sp
 462 .ne 2
 463 .na
 464 \fB\fBzonepath\fR\fR
 465 .ad
 466 .sp .6
 467 .RS 4n
 468 \fBzonepath\fR and its parent directory exist and are owned by root with
 469 appropriate modes . The appropriate modes are that \fBzonepath\fR is \fB700\fR,
 470 its parent is not \fBgroup\fR or \fBworld-writable\fR and so forth.
 471 \fBzonepath\fR is not over an NFS mount. A sub-directory of the \fBzonepath\fR
 472 named "root" does not exist.
 473 .sp
 474 If \fBzonepath\fR does not exist, the \fBverify\fR does not fail, but merely
 475 warns that a subsequent install will attempt to create it with proper
 476 permissions. A \fBverify\fR subsequent to that might fail should anything go
 477 wrong.
 478 .sp
 479 \fBzonepath\fR cannot be a symbolic link.
 480 .RE
 481 
 482 .sp
 483 .ne 2
 484 .na
 485 \fB\fBfs\fR\fR
 486 .ad
 487 .sp .6
 488 .RS 4n
 489 Any \fBfs\fR resources have their \fItype\fR value checked. An error is
 490 reported if the value is one of \fBproc\fR, \fBmntfs\fR, \fBautofs\fR,
 491 \fBcachefs\fR, or \fBnfs\fR or the filesystem does not have an associated mount
 492 binary at \fB/usr/lib/fs/\fI<fstype>\fR/mount\fR.
 493 .sp
 494 It is an error for the \fIdirectory\fR to be a relative path.
 495 .sp
 496 It is an error for the path specified by \fBraw\fR to be a relative path or if
 497 there is no \fBfsck\fR binary for a given filesystem type at
 498 \fB/usr/lib/fs/\fI<fstype>\fR/fsck\fR. It is also an error if a corresponding
 499 \fBfsck\fR binary exists but a \fBraw\fR path is not specified.
 500 .RE
 501 
 502 .sp
 503 .ne 2
 504 .na
 505 \fB\fBnet\fR\fR
 506 .ad
 507 .sp .6
 508 .RS 4n
 509 All physical network interfaces exist. All network address resources are one
 510 of:
 511 .RS +4
 512 .TP
 513 .ie t \(bu
 514 .el o
 515 a valid IPv4 address, optionally followed by "\fB/\fR" and a prefix length;
 516 .RE
 517 .RS +4
 518 .TP
 519 .ie t \(bu
 520 .el o
 521 a valid IPv6 address, which must be followed by "\fB/\fR" and a prefix length;
 522 .RE
 523 .RS +4
 524 .TP
 525 .ie t \(bu
 526 .el o
 527 a host name which resolves to an IPv4 address.
 528 .RE
 529 Note that hostnames that resolve to IPv6 addresses are not supported.
 530 .sp
 531 The physical interface name is the network interface name.
 532 .sp
 533 A zone can be configured to be either exclusive-IP or shared-IP. For a
 534 shared-IP zone, both the physical and address properties must be set. For an
 535 exclusive-IP zone, the physical property must be set and the address property
 536 cannot be set.
 537 .RE
 538 
 539 .sp
 540 .ne 2
 541 .na
 542 \fB\fBrctl\fR\fR
 543 .ad
 544 .sp .6
 545 .RS 4n
 546 It also verifies that any defined resource control values are valid on the
 547 current machine. This means that the privilege level is \fBprivileged\fR, the
 548 limit is lower than the currently defined system value, and that the defined
 549 action agrees with the actions that are valid for the given resource control.
 550 .RE
 551 
 552 .RE
 553 
 554 .SH EXAMPLES
 555 .LP
 556 \fBExample 1 \fRUsing the \fB-m\fR Option
 557 .sp
 558 .LP
 559 The following command illustrates the use of the \fB-m\fR option.
 560 
 561 .sp
 562 .in +2
 563 .nf
 564 # \fBzoneadm boot -- -m verbose\fR
 565 .fi
 566 .in -2
 567 .sp
 568 
 569 .LP
 570 \fBExample 2 \fRUsing the \fB-i\fR Option
 571 .sp
 572 .LP
 573 The following command illustrates the use of the \fB-i\fR option.
 574 
 575 .sp
 576 .in +2
 577 .nf
 578 # \fBzoneadm boot -- -i /sbin/init\fR
 579 .fi
 580 .in -2
 581 .sp
 582 
 583 .LP
 584 \fBExample 3 \fRUsing the \fB-s\fR Option
 585 .sp
 586 .LP
 587 The following command illustrates the use of the \fB-s\fR option.
 588 
 589 .sp
 590 .in +2
 591 .nf
 592 # \fBzoneadm boot -- -s\fR
 593 .fi
 594 .in -2
 595 .sp
 596 
 597 .SH EXIT STATUS
 598 .LP
 599 The following exit values are returned:
 600 .sp
 601 .ne 2
 602 .na
 603 \fB\fB0\fR\fR
 604 .ad
 605 .sp .6
 606 .RS 4n
 607 Successful completion.
 608 .RE
 609 
 610 .sp
 611 .ne 2
 612 .na
 613 \fB\fB1\fR\fR
 614 .ad
 615 .sp .6
 616 .RS 4n
 617 An error occurred.
 618 .RE
 619 
 620 .sp
 621 .ne 2
 622 .na
 623 \fB\fB2\fR\fR
 624 .ad
 625 .sp .6
 626 .RS 4n
 627 Invalid usage.
 628 .RE
 629 
 630 .SH ATTRIBUTES
 631 .LP
 632 See \fBattributes\fR(5) for descriptions of the following attributes:
 633 .sp
 634 
 635 .sp
 636 .TS
 637 box;
 638 c | c
 639 l | l .
 640 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 641 _
 642 Interface Stability     Committed
 643 .TE
 644 
 645 .SH SEE ALSO
 646 .LP
 647 \fBread\fR(1), \fBsvcs\fR(1), \fBzlogin\fR(1), \fBzonename\fR(1),
 648 \fBinit\fR(1M), \fBkernel\fR(1M), \fBsvcadm\fR(1M), \fBsvc.startd\fR(1M),
 649 \fBsvc.startd\fR(1M), \fBzonecfg\fR(1M), \fBlibuuid\fR(3LIB),
 650 \fBattributes\fR(5), \fBbrands\fR(5), \fBnative\fR(5), \fBsmf\fR(5),
 651 \fBzones\fR(5)
 652 .SH NOTES
 653 .LP
 654 The \fBzones\fR(5) service is managed by the service management facility,
 655 \fBsmf\fR(5), under the service identifier:
 656 .sp
 657 .in +2
 658 .nf
 659 svc:/system/zones:default
 660 .fi
 661 .in -2
 662 .sp
 663 
 664 .sp
 665 .LP
 666 Administrative actions on this service, such as enabling, disabling, or
 667 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
 668 status can be queried using the \fBsvcs\fR(1) command.
 669 .sp
 670 .LP
 671 The act of installing a new non-global zone is a fresh installation of the
 672 Solaris operating system. A new installation of Solaris must not require
 673 interaction with the user (that is, it must be "hands off"). Because of this,
 674 packages installed in the global zone and all non-global zones cannot contain
 675 request scripts (see \fBpkgask\fR(1M)). If a package did have a request script,
 676 then the creation of a non-global zone could not be done without user
 677 intervention. Any package that contains a request script is added to the global
 678 zone only. See \fBpkgadd\fR(1M).