1 '\" te
2 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH ZONEADM 1M "Feb 13, 2009"
7 .SH NAME
8 zoneadm \- administer zones
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBzoneadm\fR \fB-z\fR \fIzonename\fR [\fB-u\fR \fIuuid-match\fR] \fIsubcommand\fR
13 [\fIsubcommand_options\fR]
14 .fi
15
16 .LP
17 .nf
18 \fBzoneadm\fR [\fB-R\fR \fIroot\fR] [\fB-z\fR \fIzonename\fR] [\fB-u\fR \fIuuid-match\fR] list
19 [\fIlist_options\fR]
20 .fi
21
22 .LP
23 .nf
24 \fBzoneadm\fR [\fB-R\fR \fIroot\fR] \fB-z\fR \fIzonename\fR [\fB-u\fR \fIuuid-match\fR] mark incomplete
25 .fi
26
27 .SH DESCRIPTION
28 .sp
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 .sp
34 .LP
35 Once a process has been placed in a zone other than zone \fB0\fR, the process
36 or any of its children cannot change zones.
37 .SH OPTIONS
38 .sp
39 .LP
40 The following options are supported:
41 .sp
42 .ne 2
43 .na
44 \fB\fB-R\fR \fIroot\fR\fR
45 .ad
46 .sp .6
47 .RS 4n
48 Specify an alternate root (boot environment). This option can only be used in
49 conjunction with the "\fBlist\fR" and "\fBmark\fR" subcommands.
50 .RE
51
52 .sp
53 .ne 2
54 .na
55 \fB\fB-u\fR \fIuuid-match\fR\fR
56 .ad
57 .sp .6
58 .RS 4n
59 Unique identifier for a zone, as assigned by \fBlibuuid\fR(3LIB). If this
60 option is present and the argument is a non-empty string, then the zone
61 matching the \fBUUID\fR is selected instead of the one named by the \fB-z\fR
62 option, if such a zone is present.
63 .RE
64
65 .sp
66 .ne 2
67 .na
68 \fB\fB-z\fR \fIzonename\fR\fR
69 .ad
70 .sp .6
71 .RS 4n
72 String identifier for a zone.
73 .RE
74
75 .SH SUBCOMMANDS
76 .sp
77 .LP
78 Subcommands which can result in destructive actions or loss of work have a
79 \fB-F\fR flag to force the action. If input is from a terminal device, the user
80 is prompted if such a command is given without the \fB-F\fR flag; otherwise, if
81 such a command is given without the \fB-F\fR flag, the action is disallowed,
82 with a diagnostic message written to standard error. If a zone installation or
83 uninstallation is interrupted, the zone is left in the incomplete state. Use
84 uninstall to reset such a zone back to the configured state.
85 .sp
86 .LP
87 The following subcommands are supported:
88 .sp
89 .ne 2
90 .na
91 \fB\fBattach\fR [\fB-F\fR] [\fB-n\fR \fIpath\fR] [\fIbrand-specific
92 options\fR]\fR
93 .ad
94 .sp .6
95 .RS 4n
96 The \fBattach\fR subcommand takes a zone that has been detached from one system
97 and attaches the zone onto a new system. Therefore, it is advised (though not
98 required) that the \fBdetach\fR subcommand should be run before the "attach"
99 takes place. Once you have the new zone in the configured state, use the
100 \fBattach\fR subcommand to set up the zone root instead of installing the zone
101 as a new zone.
102 .sp
103 The \fB-F\fR option can be used to force the zone into the "installed" state
104 with no validation. This option should be used with care since it can leave the
105 zone in an unsupportable state if it was moved from a source system to a target
106 system that is unable to properly host the zone. The \fB-n\fR option can be
107 used to run the \fBattach\fR subcommand, without executing the command. It uses
108 the output of the "\fBdetach\fR \fB-n\fR" subcommand as input and is useful to
109 identify any conflicting issues, such as the network device being incompatible,
110 and can also determine whether the host is capable of supporting the zone. The
111 path can be "\fB-\fR", to read the input from standard input.
112 .sp
113 The zone's brand may include additional options that govern how the zone will
114 be attached. See \fBbrands\fR(5) for specific brand information.
115 .sp
116 The zone being attached must first be configured using the \fBzonecfg\fR (see
117 \fBzonecfg\fR(1M)) command. This does not apply when running "\fBattach\fR
118 \fB-n\fR".
119 .sp
120 Use the following command to attach a zone:
121 .sp
122 .in +2
123 .nf
124 # \fBzoneadm -z my-zone attach\fR
125 .fi
126 .in -2
127 .sp
128
129 .RE
130
131 .sp
132 .ne 2
133 .na
134 \fB\fBboot\fR [\fB--\fR \fIboot_options\fR]\fR
135 .ad
136 .sp .6
137 .RS 4n
138 Boot (or activate) the specified zones.
139 .sp
140 The following \fIboot_options\fR are supported:
141 .sp
142 .ne 2
143 .na
144 \fB\fB-i\fR \fIaltinit\fR\fR
145 .ad
146 .sp .6
147 .RS 4n
148 Select an alternative executable to be the primordial Process. \fIaltinit\fR is
149 a valid path to an executable. The default primordial process is
150 \fBinit\fR(1M).
151 .RE
152
153 .sp
154 .ne 2
155 .na
156 \fB\fB-m\fR \fIsmf_options\fR\fR
157 .ad
158 .sp .6
159 .RS 4n
160 The \fIsmf_options\fR include two categories of options to control booting
161 behavior of the service management facility: recovery options and messages
162 options.
163 .sp
164 Message options determine the type and amount of messages that \fBsmf\fR(5)
165 displays during boot. Service options determine the services which are used to
166 boot the system. See \fBkernel\fR(1M) for a listing of the \fB-m\fR suboptions.
167 .RE
168
169 .sp
170 .ne 2
171 .na
172 \fB\fB-s\fR\fR
173 .ad
174 .sp .6
175 .RS 4n
176 Boots only to milestone \fBsvc:/milestone/single-user:default\fR. This
177 milestone is equivalent to init level \fBs\fR. See \fBsvc.startd\fR(1M) and
178 \fBinit\fR(1M).
179 .RE
180
181 .RE
182
183 .sp
184 .ne 2
185 .na
186 \fB\fBclone\fR [\fB-m\fR \fIcopy\fR] [\fB-s\fR \fIzfs_snapshot\fR]
187 \fIsource_zone\fR\fR
188 .ad
189 .sp .6
190 .RS 4n
191 Install a zone by copying an existing installed zone. This subcommand is an
192 alternative way to install the zone.
193 .sp
194 .ne 2
195 .na
196 \fB\fB-m\fR \fIcopy\fR\fR
197 .ad
198 .sp .6
199 .RS 4n
200 Force the clone to be a copy, even if a "\fBZFS\fR clone" is possible.
201 .RE
202
203 .sp
204 .ne 2
205 .na
206 \fB\fB-s\fR \fIzfs_snapshot\fR\fR
207 .ad
208 .sp .6
209 .RS 4n
210 Specify the name of a \fBZFS\fR snapshot to use as the source of the clone. The
211 \fIsnapshot\fR must be a \fIsnapshot\fR of the source zone taken from a
212 previous "\fBzoneadm\fR clone" installation.
213 .RE
214
215 The source zone must be halted before this subcommand can be used.
216 .RE
217
218 .sp
219 .ne 2
220 .na
221 \fB\fBdetach\fR [\fB-n\fR]\fR
222 .ad
223 .sp .6
224 .RS 4n
225 Detach the specified zone. Detaching a zone is the first step in moving a zone
226 from one system to another. The full procedure to migrate a zone is that the
227 zone is detached, the \fIzonepath\fR directory is moved to the new host, and
228 then the zone is attached on the new host. Once the zone is detached, it is
229 left in the configured state. If you try to install or clone to a configured
230 zone that has been detached, you will receive an error message and the
231 \fBinstall\fR or \fBclone\fR subcommand will not be allowed to proceed. The
232 \fB-n\fR option can be used to run the \fBdetach\fR subcommand, without
233 executing the command. This generates the information needed for running the
234 "\fBattach\fR \fB-n\fR" subcommand, which is useful to identify any conflicting
235 issues, such as the network device being incompatible or if the host is capable
236 of supporting the zone. The information is sent to standard output and can be
237 saved to a file or piped to the "\fBattach\fR \fB-n\fR" subcommand.
238 .sp
239 Use the following command to detach a zone:
240 .sp
241 .in +2
242 .nf
243 # zoneadm -z my-zone detach
244 .fi
245 .in -2
246 .sp
247
248 The source zone must be halted before this subcommand can be used.
249 .RE
250
251 .sp
252 .ne 2
253 .na
254 \fB\fBhalt\fR\fR
255 .ad
256 .sp .6
257 .RS 4n
258 Halt the specified zones. \fBhalt\fR bypasses running the shutdown scripts
259 inside the zone. It also removes run time resources of the zone.
260 .sp
261 Use:
262 .sp
263 .in +2
264 .nf
265 zlogin \fIzone\fR shutdown
266 .fi
267 .in -2
268 .sp
269
270 to cleanly shutdown the zone by running the shutdown scripts.
271 .RE
272
273 .sp
274 .ne 2
275 .na
276 \fB\fBhelp\fR [\fIsubcommand\fR]\fR
277 .ad
278 .sp .6
279 .RS 4n
280 Display general help. If you specify \fIsubcommand\fR, displays help on
281 \fIsubcommand\fR.
282 .RE
283
284 .sp
285 .ne 2
286 .na
287 \fB\fBinstall\fR [\fB-x\fR \fInodataset\fR] [\fIbrand-specific options\fR]\fR
288 .ad
289 .sp .6
290 .RS 4n
291 Install the specified zone on the system. This subcommand automatically
292 attempts to verify first. It refuses to install if the verify step fails. See
293 the \fBverify\fR subcommand.
294 .sp
295 .ne 2
296 .na
297 \fB\fB-x\fR \fInodataset\fR\fR
298 .ad
299 .sp .6
300 .RS 4n
301 Do not create a \fBZFS\fR file system.
302 .RE
303
304 The zone's brand may include additional options that govern how the software
305 will be installed in the zone. See \fBbrands\fR(5) for specific brand
306 information.
307 .RE
308
309 .sp
310 .ne 2
311 .na
312 \fB\fBlist\fR [\fIlist_options\fR]\fR
313 .ad
314 .sp .6
315 .RS 4n
316 Display the name of the current zones, or the specified zone if indicated.
317 .sp
318 By default, all running zones are listed. If you use this subcommand with the
319 \fBzoneadm\fR \fB-z\fR \fIzonename\fR option, it lists only the specified zone,
320 regardless of its state. In this case, the \fB-i\fR and \fB-c\fR options are
321 disallowed.
322 .sp
323 If neither the \fB-i\fR or \fB-c\fR options are given, all running zones are
324 listed.
325 .sp
326 The following \fIlist_options\fR are supported:
327 .sp
328 .ne 2
329 .na
330 \fB\fB-c\fR\fR
331 .ad
332 .sp .6
333 .RS 4n
334 Display all configured zones. This option overides the \fB-i\fR option.
335 .RE
336
337 .sp
338 .ne 2
339 .na
340 \fB\fB-i\fR\fR
341 .ad
342 .sp .6
343 .RS 4n
344 Expand the display to all installed zones.
345 .RE
346
347 .sp
348 .ne 2
349 .na
350 \fB\fB-p\fR\fR
351 .ad
352 .sp .6
353 .RS 4n
354 Request machine parsable output. The output format is a list of lines, one per
355 zone, with colon- delimited fields. These fields are:
356 .sp
357 .in +2
358 .nf
359 zoneid:zonename:state:zonepath:uuid:brand:ip-type
360 .fi
361 .in -2
362 .sp
363
364 If the \fBzonepath\fR contains embedded colons, they can be escaped by a
365 backslash ("\:"), which is parsable by using the shell \fBread\fR(1) function
366 with the environmental variable \fBIFS\fR. The \fIuuid\fR value is assigned by
367 \fBlibuuid\fR(3LIB) when the zone is installed, and is useful for identifying
368 the same zone when present (or renamed) on alternate boot environments. Any
369 software that parses the output of the "\fBzoneadm list -p\fR" command must be
370 able to handle any fields that may be added in the future.
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 .sp
377 .ne 2
378 .na
379 \fB\fB-v\fR\fR
380 .ad
381 .sp .6
382 .RS 4n
383 Display verbose information, including zone name, id, current state, root
384 directory, brand type, ip-type, and options.
385 .sp
386 The \fB-v\fR and \fB-p\fR options are mutually exclusive. If neither \fB-v\fR
387 nor \fB-p\fR is used, just the zone name is listed.
388 .RE
389
390 .RE
391
392 .sp
393 .ne 2
394 .na
395 \fB\fBmark incomplete\fR\fR
396 .ad
397 .sp .6
398 .RS 4n
399 Change the state of an installed zone to "incomplete." This command may be
400 useful in cases where administrative changes on the system have rendered a zone
401 unusable or inconsistent. This change cannot be undone (except by uninstalling
402 the zone).
403 .RE
404
405 .sp
406 .ne 2
407 .na
408 \fB\fBmove\fR \fInew_zonepath\fR\fR
409 .ad
410 .sp .6
411 .RS 4n
412 Move the \fIzonepath\fR to \fInew_zonepath\fR. The zone must be halted before
413 this subcommand can be used. The \fInew_zonepath\fR must be a local file system
414 and normal restrictions for \fIzonepath\fR apply.
415 .RE
416
417 .sp
418 .ne 2
419 .na
420 \fB\fBready\fR\fR
421 .ad
422 .sp .6
423 .RS 4n
424 Prepares a zone for running applications but does not start any user processes
425 in the zone.
426 .RE
427
428 .sp
429 .ne 2
430 .na
431 \fB\fBreboot\fR\fR
432 .ad
433 .sp .6
434 .RS 4n
435 Restart the zones. This is equivalent to a \fBhalt\fR \fBboot\fR sequence. This
436 subcommand fails if the specified zones are not active.
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 .sp
599 .LP
600 The following exit values are returned:
601 .sp
602 .ne 2
603 .na
604 \fB\fB0\fR\fR
605 .ad
606 .sp .6
607 .RS 4n
608 Successful completion.
609 .RE
610
611 .sp
612 .ne 2
613 .na
614 \fB\fB1\fR\fR
615 .ad
616 .sp .6
617 .RS 4n
618 An error occurred.
619 .RE
620
621 .sp
622 .ne 2
623 .na
624 \fB\fB2\fR\fR
625 .ad
626 .sp .6
627 .RS 4n
628 Invalid usage.
629 .RE
630
631 .SH ATTRIBUTES
632 .sp
633 .LP
634 See \fBattributes\fR(5) for descriptions of the following attributes:
635 .sp
636
637 .sp
638 .TS
639 box;
640 c | c
641 l | l .
642 ATTRIBUTE TYPE ATTRIBUTE VALUE
643 _
644 Interface Stability Committed
645 .TE
646
647 .SH SEE ALSO
648 .sp
649 .LP
650 \fBread\fR(1), \fBsvcs\fR(1), \fBzlogin\fR(1), \fBzonename\fR(1),
651 \fBinit\fR(1M), \fBkernel\fR(1M), \fBsvcadm\fR(1M), \fBsvc.startd\fR(1M),
652 \fBsvc.startd\fR(1M), \fBzonecfg\fR(1M), \fBlibuuid\fR(3LIB),
653 \fBattributes\fR(5), \fBbrands\fR(5), \fBnative\fR(5), \fBsmf\fR(5),
654 \fBzones\fR(5)
655 .SH NOTES
656 .sp
657 .LP
658 The \fBzones\fR(5) service is managed by the service management facility,
659 \fBsmf\fR(5), under the service identifier:
660 .sp
661 .in +2
662 .nf
663 svc:/system/zones:default
664 .fi
665 .in -2
666 .sp
667
668 .sp
669 .LP
670 Administrative actions on this service, such as enabling, disabling, or
671 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
672 status can be queried using the \fBsvcs\fR(1) command.
673 .sp
674 .LP
675 The act of installing a new non-global zone is a fresh installation of the
676 Solaris operating system. A new installation of Solaris must not require
677 interaction with the user (that is, it must be "hands off"). Because of this,
678 packages installed in the global zone and all non-global zones cannot contain
679 request scripts (see \fBpkgask\fR(1M)). If a package did have a request script,
680 then the creation of a non-global zone could not be done without user
681 intervention. Any package that contains a request script is added to the global
682 zone only. See \fBpkgadd\fR(1M).