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