1 '\" te
2 .\" Copyright (c) 2004, 2009 Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2015 Joyent, Inc.
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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 .\" See the License for the specific language governing permissions and limitations under the License. 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
6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH ZONECFG 1M "Nov 4, 2015"
8 .SH NAME
9 zonecfg \- set up zone configuration
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBzonecfg\fR {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR}
14 .fi
15
16 .LP
17 .nf
18 \fBzonecfg\fR {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR} \fIsubcommand\fR
19 .fi
20
21 .LP
22 .nf
23 \fBzonecfg\fR {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR} \fB-f\fR \fIcommand_file\fR
24 .fi
25
26 .LP
27 .nf
28 \fBzonecfg\fR help
29 .fi
30
31 .SH DESCRIPTION
32 .LP
33 The \fBzonecfg\fR utility creates and modifies the configuration of a zone.
34 Zone configuration consists of a number of resources and properties.
35 .sp
36 .LP
37 To simplify the user interface, \fBzonecfg\fR uses the concept of a scope. The
38 default scope is global.
39 .sp
40 .LP
41 The following synopsis of the \fBzonecfg\fR command is for interactive usage:
42 .sp
43 .in +2
44 .nf
45 {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR}
46 zonecfg {\fB-z\fR \fIzonename | \fB-u\fR \fIuuid} subcommand\fR
47 .fi
48 .in -2
49 .sp
50
51 .sp
52 .LP
53 Parameters changed through \fBzonecfg\fR do not affect a running zone. The zone
54 must be rebooted for the changes to take effect.
55 .sp
56 .LP
57 In addition to creating and modifying a zone, the \fBzonecfg\fR utility can
58 also be used to persistently specify the resource management settings for the
59 global zone.
60 .sp
61 .LP
62 In the following text, "rctl" is used as an abbreviation for "resource
63 control". See \fBresource_controls\fR(5).
64 .sp
65 .LP
66 Every zone is configured with an associated brand. The brand determines the
67 user-level environment used within the zone, as well as various behaviors for
68 the zone when it is installed, boots, or is shutdown. Once a zone has been
69 installed the brand cannot be changed. The default brand is determined by the
70 installed distribution in the global zone. Some brands do not support all of
71 the \fBzonecfg\fR properties and resources. See the brand-specific man page for
72 more details on each brand. For an overview of brands, see the \fBbrands\fR(5)
73 man page.
74 .SS "Resources"
75 .LP
76 The following resource types are supported:
77 .sp
78 .ne 2
79 .na
80 \fB\fBattr\fR\fR
81 .ad
82 .sp .6
83 .RS 4n
84 Generic attribute.
85 .RE
86
87 .sp
88 .ne 2
89 .na
90 \fB\fBcapped-cpu\fR\fR
91 .ad
92 .sp .6
93 .RS 4n
94 Limits for CPU usage.
95 .RE
96
97 .sp
98 .ne 2
99 .na
100 \fB\fBcapped-memory\fR\fR
101 .ad
102 .sp .6
103 .RS 4n
104 Limits for physical, swap, and locked memory.
105 .RE
106
107 .sp
108 .ne 2
109 .na
110 \fB\fBdataset\fR\fR
111 .ad
112 .sp .6
113 .RS 4n
114 \fBZFS\fR dataset.
115 .RE
116
117 .sp
118 .ne 2
119 .na
120 \fB\fBdedicated-cpu\fR\fR
121 .ad
122 .sp .6
123 .RS 4n
124 Subset of the system's processors dedicated to this zone while it is running.
125 .RE
126
127 .sp
128 .ne 2
129 .na
130 \fB\fBdevice\fR\fR
131 .ad
132 .sp .6
133 .RS 4n
134 Device.
135 .RE
136
137 .sp
138 .ne 2
139 .na
140 \fB\fBfs\fR\fR
141 .ad
142 .sp .6
143 .RS 4n
144 file-system
145 .RE
146
147 .sp
148 .ne 2
149 .na
150 \fB\fBnet\fR\fR
151 .ad
152 .sp .6
153 .RS 4n
154 Network interface.
155 .RE
156
157 .sp
158 .ne 2
159 .na
160 \fB\fBrctl\fR\fR
161 .ad
162 .sp .6
163 .RS 4n
164 Resource control.
165 .RE
166
167 .SS "Properties"
168 .LP
169 Each resource type has one or more properties. There are also some global
170 properties, that is, properties of the configuration as a whole, rather than of
171 some particular resource.
172 .sp
173 .LP
174 The following properties are supported:
175 .sp
176 .ne 2
177 .na
178 \fB(global)\fR
179 .ad
180 .sp .6
181 .RS 4n
182 \fBzonename\fR
183 .RE
184
185 .sp
186 .ne 2
187 .na
188 \fB(global)\fR
189 .ad
190 .sp .6
191 .RS 4n
192 \fBzonepath\fR
193 .RE
194
195 .sp
196 .ne 2
197 .na
198 \fB(global)\fR
199 .ad
200 .sp .6
201 .RS 4n
202 \fBautoboot\fR
203 .RE
204
205 .sp
206 .ne 2
207 .na
208 \fB(global)\fR
209 .ad
210 .sp .6
211 .RS 4n
212 \fBbootargs\fR
213 .RE
214
215 .sp
216 .ne 2
217 .na
218 \fB(global)\fR
219 .ad
220 .sp .6
221 .RS 4n
222 \fBpool\fR
223 .RE
224
225 .sp
226 .ne 2
227 .na
228 \fB(global)\fR
229 .ad
230 .sp .6
231 .RS 4n
232 \fBlimitpriv\fR
233 .RE
234
235 .sp
236 .ne 2
237 .na
238 \fB(global)\fR
239 .ad
240 .sp .6
241 .RS 4n
242 \fBbrand\fR
243 .RE
244
245 .sp
246 .ne 2
247 .na
248 \fB(global)\fR
249 .ad
250 .sp .6
251 .RS 4n
252 \fBcpu-shares\fR
253 .RE
254
255 .sp
256 .ne 2
257 .na
258 \fB(global)\fR
259 .ad
260 .sp .6
261 .RS 4n
262 \fBhostid\fR
263 .RE
264
265 .sp
266 .ne 2
267 .na
268 \fB(global)\fR
269 .ad
270 .sp .6
271 .RS 4n
272 \fBmax-lwps\fR
273 .RE
274
275 .sp
276 .ne 2
277 .na
278 \fB(global)\fR
279 .ad
280 .sp .6
281 .RS 4n
282 \fBmax-msg-ids\fR
283 .RE
284
285 .sp
286 .ne 2
287 .na
288 \fB(global)\fR
289 .ad
290 .sp .6
291 .RS 4n
292 \fBmax-sem-ids\fR
293 .RE
294
295 .sp
296 .ne 2
297 .na
298 \fB(global)\fR
299 .ad
300 .sp .6
301 .RS 4n
302 \fBmax-shm-ids\fR
303 .RE
304
305 .sp
306 .ne 2
307 .na
308 \fB(global)\fR
309 .ad
310 .sp .6
311 .RS 4n
312 \fBmax-shm-memory\fR
313 .RE
314
315 .sp
316 .ne 2
317 .na
318 \fB(global)\fR
319 .ad
320 .sp .6
321 .RS 4n
322 \fBscheduling-class\fR
323 .RE
324
325 .sp
326 .ne 2
327 .na
328 .B (global)
329 .ad
330 .sp .6
331 .RS 4n
332 .B fs-allowed
333 .RE
334
335 .sp
336 .ne 2
337 .na
338 \fB(global)\fR
339 .ad
340 .sp .6
341 .RS 4n
342 \fBzfs-io-priority\fR
343 .RE
344
345 .sp
346 .ne 2
347 .na
348 \fB\fBfs\fR\fR
349 .ad
350 .sp .6
351 .RS 4n
352 \fBdir\fR, \fBspecial\fR, \fBraw\fR, \fBtype\fR, \fBoptions\fR
353 .RE
354
355 .sp
356 .ne 2
357 .na
358 \fB\fBnet\fR\fR
359 .ad
360 .sp .6
361 .RS 4n
362 \fBaddress\fR, \fBallowed-address\fR, \fBdefrouter\fR, \fBglobal-nic\fR, \fBmac-addr\fR, \fBphysical\fR, \fBproperty\fR, \fBvlan-id\fR
363 .RE
364
365 .sp
366 .ne 2
367 .na
368 \fB\fBdevice\fR\fR
369 .ad
370 .sp .6
371 .RS 4n
372 \fBmatch\fR
373 .RE
374
375 .sp
376 .ne 2
377 .na
378 \fB\fBrctl\fR\fR
379 .ad
380 .sp .6
381 .RS 4n
382 \fBname\fR, \fBvalue\fR
383 .RE
384
385 .sp
386 .ne 2
387 .na
388 \fB\fBattr\fR\fR
389 .ad
390 .sp .6
391 .RS 4n
392 \fBname\fR, \fBtype\fR, \fBvalue\fR
393 .RE
394
395 .sp
396 .ne 2
397 .na
398 \fB\fBdataset\fR\fR
399 .ad
400 .sp .6
401 .RS 4n
402 \fBname\fR
403 .RE
404
405 .sp
406 .ne 2
407 .na
408 \fB\fBdedicated-cpu\fR\fR
409 .ad
410 .sp .6
411 .RS 4n
412 \fBncpus\fR, \fBimportance\fR
413 .RE
414
415 .sp
416 .ne 2
417 .na
418 \fB\fBcapped-memory\fR\fR
419 .ad
420 .sp .6
421 .RS 4n
422 \fBphysical\fR, \fBswap\fR, \fBlocked\fR
423 .RE
424
425 .sp
426 .ne 2
427 .na
428 \fB\fBcapped-cpu\fR\fR
429 .ad
430 .sp .6
431 .RS 4n
432 \fBncpus\fR
433 .RE
434
435 .sp
436 .LP
437 As for the property values which are paired with these names, they are either
438 simple, complex, or lists. The type allowed is property-specific. Simple values
439 are strings, optionally enclosed within quotation marks. Complex values have
440 the syntax:
441 .sp
442 .in +2
443 .nf
444 (<\fIname\fR>=<\fIvalue\fR>,<\fIname\fR>=<\fIvalue\fR>,...)
445 .fi
446 .in -2
447 .sp
448
449 .sp
450 .LP
451 where each <\fIvalue\fR> is simple, and the <\fIname\fR> strings are unique
452 within a given property. Lists have the syntax:
453 .sp
454 .in +2
455 .nf
456 [<\fIvalue\fR>,...]
457 .fi
458 .in -2
459 .sp
460
461 .sp
462 .LP
463 where each <\fIvalue\fR> is either simple or complex. A list of a single value
464 (either simple or complex) is equivalent to specifying that value without the
465 list syntax. That is, "foo" is equivalent to "[foo]". A list can be empty
466 (denoted by "[]").
467 .sp
468 .LP
469 In interpreting property values, \fBzonecfg\fR accepts regular expressions as
470 specified in \fBfnmatch\fR(5). See \fBEXAMPLES\fR.
471 .sp
472 .LP
473 The property types are described as follows:
474 .sp
475 .ne 2
476 .na
477 \fBglobal: \fBzonename\fR\fR
478 .ad
479 .sp .6
480 .RS 4n
481 The name of the zone.
482 .RE
483
484 .sp
485 .ne 2
486 .na
487 \fBglobal: \fBzonepath\fR\fR
488 .ad
489 .sp .6
490 .RS 4n
491 Path to zone's file system.
492 .RE
493
494 .sp
495 .ne 2
496 .na
497 \fBglobal: \fBautoboot\fR\fR
498 .ad
499 .sp .6
500 .RS 4n
501 Boolean indicating that a zone should be booted automatically at system boot.
502 Note that if the zones service is disabled, the zone will not autoboot,
503 regardless of the setting of this property. You enable the zones service with a
504 \fBsvcadm\fR command, such as:
505 .sp
506 .in +2
507 .nf
508 # \fBsvcadm enable svc:/system/zones:default\fR
509 .fi
510 .in -2
511 .sp
512
513 Replace \fBenable\fR with \fBdisable\fR to disable the zones service. See
514 \fBsvcadm\fR(1M).
515 .RE
516
517 .sp
518 .ne 2
519 .na
520 \fBglobal: \fBbootargs\fR\fR
521 .ad
522 .sp .6
523 .RS 4n
524 Arguments (options) to be passed to the zone bootup, unless options are
525 supplied to the "\fBzoneadm boot\fR" command, in which case those take
526 precedence. The valid arguments are described in \fBzoneadm\fR(1M).
527 .RE
528
529 .sp
530 .ne 2
531 .na
532 \fBglobal: \fBpool\fR\fR
533 .ad
534 .sp .6
535 .RS 4n
536 Name of the resource pool that this zone must be bound to when booted. This
537 property is incompatible with the \fBdedicated-cpu\fR resource.
538 .RE
539
540 .sp
541 .ne 2
542 .na
543 \fBglobal: \fBlimitpriv\fR\fR
544 .ad
545 .sp .6
546 .RS 4n
547 The maximum set of privileges any process in this zone can obtain. The property
548 should consist of a comma-separated privilege set specification as described in
549 \fBpriv_str_to_set\fR(3C). Privileges can be excluded from the resulting set by
550 preceding their names with a dash (-) or an exclamation point (!). The special
551 privilege string "zone" is not supported in this context. If the special string
552 "default" occurs as the first token in the property, it expands into a safe set
553 of privileges that preserve the resource and security isolation described in
554 \fBzones\fR(5). A missing or empty property is equivalent to this same set of
555 safe privileges.
556 .sp
557 The system administrator must take extreme care when configuring privileges for
558 a zone. Some privileges cannot be excluded through this mechanism as they are
559 required in order to boot a zone. In addition, there are certain privileges
560 which cannot be given to a zone as doing so would allow processes inside a zone
561 to unduly affect processes in other zones. \fBzoneadm\fR(1M) indicates when an
562 invalid privilege has been added or removed from a zone's privilege set when an
563 attempt is made to either "boot" or "ready" the zone.
564 .sp
565 See \fBprivileges\fR(5) for a description of privileges. The command "\fBppriv
566 -l\fR" (see \fBppriv\fR(1)) produces a list of all Solaris privileges. You can
567 specify privileges as they are displayed by \fBppriv\fR. In
568 \fBprivileges\fR(5), privileges are listed in the form
569 PRIV_\fIprivilege_name\fR. For example, the privilege \fIsys_time\fR, as you
570 would specify it in this property, is listed in \fBprivileges\fR(5) as
571 \fBPRIV_SYS_TIME\fR.
572 .RE
573
574 .sp
575 .ne 2
576 .na
577 \fBglobal: \fBbrand\fR\fR
578 .ad
579 .sp .6
580 .RS 4n
581 The zone's brand type.
582 .RE
583
584 .sp
585 .ne 2
586 .na
587 \fBglobal: \fBip-type\fR\fR
588 .ad
589 .sp .6
590 .RS 4n
591 A zone can either share the IP instance with the global zone, which is the
592 default, or have its own exclusive instance of IP.
593 .sp
594 This property takes the values \fBshared\fR and \fBexclusive\fR.
595 .RE
596
597 .sp
598 .ne 2
599 .na
600 \fBglobal: \fBhostid\fR\fR
601 .ad
602 .sp .6
603 .RS 4n
604 A zone can emulate a 32-bit host identifier to ease system consolidation. A
605 zone's \fBhostid\fR property is empty by default, meaning that the zone does
606 not emulate a host identifier. Zone host identifiers must be hexadecimal values
607 between 0 and FFFFFFFE. A \fB0x\fR or \fB0X\fR prefix is optional. Both
608 uppercase and lowercase hexadecimal digits are acceptable.
609 .RE
610
611 .sp
612 .ne 2
613 .na
614 \fB\fBfs\fR: dir, special, raw, type, options\fR
615 .ad
616 .sp .6
617 .RS 4n
618 Values needed to determine how, where, and so forth to mount file systems. See
619 \fBmount\fR(1M), \fBmount\fR(2), \fBfsck\fR(1M), and \fBvfstab\fR(4).
620 .RE
621
622 .sp
623 .ne 2
624 .na
625 \fB\fBinherit-pkg-dir\fR: dir\fR
626 .ad
627 .sp .6
628 .RS 4n
629 The directory path.
630 .RE
631
632 .sp
633 .ne 2
634 .na
635 \fB\fBnet\fR: address, allowed-address, defrouter, global-nic, mac-addr, physical, property, vlan-id\fR
636 .ad
637 .sp .6
638 .RS 4n
639 The network address and physical interface name of the network interface. The
640 network address is one of:
641 .RS +4
642 .TP
643 .ie t \(bu
644 .el o
645 a valid IPv4 address, optionally followed by "\fB/\fR" and a prefix length;
646 .RE
647 .RS +4
648 .TP
649 .ie t \(bu
650 .el o
651 a valid IPv6 address, which must be followed by "\fB/\fR" and a prefix length;
652 .RE
653 .RS +4
654 .TP
655 .ie t \(bu
656 .el o
657 a host name which resolves to an IPv4 address.
658 .RE
659 Note that host names that resolve to IPv6 addresses are not supported.
660 .sp
661 The physical interface name is the network interface name.
662 .sp
663 The default router is specified similarly to the network address except that it
664 must not be followed by a \fB/\fR (slash) and a network prefix length.
665 .sp
666 A zone can be configured to be either exclusive-IP or shared-IP. For a
667 shared-IP zone, you must set both the physical and address properties; setting
668 the default router is optional. The interface specified in the physical
669 property must be plumbed in the global zone prior to booting the non-global
670 zone. However, if the interface is not used by the global zone, it should be
671 configured \fBdown\fR in the global zone, and the default router for the
672 interface should be specified here.
673 .sp
674 The global-nic is used for exclusive stack zones which will use a VNIC on-demand. When the zone boots, a VNIC named using the physical property will be created on the global NIC. If provided, the mac-addr and vlan-id will be set on this VNIC.
675 .sp
676 The \fBproperty\fR setting is a resource which can be used to set arbitrary name/value pairs on the network. These name/value pairs are made available to the zone's brand, which can use them as needed to set up the network interface.
677 .sp
678 For an exclusive-IP zone, the physical property must be set and the address and
679 default router properties cannot be set.
680 .RE
681
682 .sp
683 .ne 2
684 .na
685 \fB\fBdevice\fR: match\fR
686 .ad
687 .sp .6
688 .RS 4n
689 Device name to match.
690 .RE
691
692 .sp
693 .ne 2
694 .na
695 \fB\fBrctl\fR: name, value\fR
696 .ad
697 .sp .6
698 .RS 4n
699 The name and \fIpriv\fR/\fIlimit\fR/\fIaction\fR triple of a resource control.
700 See \fBprctl\fR(1) and \fBrctladm\fR(1M). The preferred way to set rctl values
701 is to use the global property name associated with a specific rctl.
702 .RE
703
704 .sp
705 .ne 2
706 .na
707 \fB\fBattr\fR: name, type, value\fR
708 .ad
709 .sp .6
710 .RS 4n
711 The name, type and value of a generic attribute. The \fBtype\fR must be one of
712 \fBint\fR, \fBuint\fR, \fBboolean\fR or \fBstring\fR, and the value must be of
713 that type. \fBuint\fR means unsigned , that is, a non-negative integer.
714 .RE
715
716 .sp
717 .ne 2
718 .na
719 \fB\fBdataset\fR: name\fR
720 .ad
721 .sp .6
722 .RS 4n
723 The name of a \fBZFS\fR dataset to be accessed from within the zone. See
724 \fBzfs\fR(1M).
725 .RE
726
727 .sp
728 .ne 2
729 .na
730 \fBglobal: \fBcpu-shares\fR\fR
731 .ad
732 .sp .6
733 .RS 4n
734 The number of Fair Share Scheduler (FSS) shares to allocate to this zone. This
735 property is incompatible with the \fBdedicated-cpu\fR resource. This property
736 is the preferred way to set the \fBzone.cpu-shares\fR rctl.
737 .RE
738
739 .sp
740 .ne 2
741 .na
742 \fBglobal: \fBmax-lwps\fR\fR
743 .ad
744 .sp .6
745 .RS 4n
746 The maximum number of LWPs simultaneously available to this zone. This property
747 is the preferred way to set the \fBzone.max-lwps\fR rctl.
748 .RE
749
750 .sp
751 .ne 2
752 .na
753 \fBglobal: \fBmax-msg-ids\fR\fR
754 .ad
755 .sp .6
756 .RS 4n
757 The maximum number of message queue IDs allowed for this zone. This property is
758 the preferred way to set the \fBzone.max-msg-ids\fR rctl.
759 .RE
760
761 .sp
762 .ne 2
763 .na
764 \fBglobal: \fBmax-sem-ids\fR\fR
765 .ad
766 .sp .6
767 .RS 4n
768 The maximum number of semaphore IDs allowed for this zone. This property is the
769 preferred way to set the \fBzone.max-sem-ids\fR rctl.
770 .RE
771
772 .sp
773 .ne 2
774 .na
775 \fBglobal: \fBmax-shm-ids\fR\fR
776 .ad
777 .sp .6
778 .RS 4n
779 The maximum number of shared memory IDs allowed for this zone. This property is
780 the preferred way to set the \fBzone.max-shm-ids\fR rctl.
781 .RE
782
783 .sp
784 .ne 2
785 .na
786 \fBglobal: \fBmax-shm-memory\fR\fR
787 .ad
788 .sp .6
789 .RS 4n
790 The maximum amount of shared memory allowed for this zone. This property is the
791 preferred way to set the \fBzone.max-shm-memory\fR rctl. A scale (K, M, G, T)
792 can be applied to the value for this number (for example, 1M is one megabyte).
793 .RE
794
795 .sp
796 .ne 2
797 .na
798 \fBglobal: \fBscheduling-class\fR\fR
799 .ad
800 .sp .6
801 .RS 4n
802 Specifies the scheduling class used for processes running in a zone. When this
803 property is not specified, the scheduling class is established as follows:
804 .RS +4
805 .TP
806 .ie t \(bu
807 .el o
808 If the \fBcpu-shares\fR property or equivalent rctl is set, the scheduling
809 class \fBFSS\fR is used.
810 .RE
811 .RS +4
812 .TP
813 .ie t \(bu
814 .el o
815 If neither \fBcpu-shares\fR nor the equivalent rctl is set and the zone's pool
816 property references a pool that has a default scheduling class, that class is
817 used.
818 .RE
819 .RS +4
820 .TP
821 .ie t \(bu
822 .el o
823 Under any other conditions, the system default scheduling class is used.
824 .RE
825 .sp
826 If the \fBFX\fR scheduling class is specified, then the optional
827 \fBfixed-hi-pri\fR attribute can be set to \fBtrue\fR. This causes all of the
828 processes in the zone to run at the highest \fBFX\fR priority. By default
829 processes under \fBFX\fR run at the lowest priority. See \fBpriocntl\fR(2)
830 for details on each scheduling class.
831 .RE
832
833
834 .sp
835 .ne 2
836 .na
837 \fB\fBdedicated-cpu\fR: ncpus, importance\fR
838 .ad
839 .sp .6
840 .RS 4n
841 The number of CPUs that should be assigned for this zone's exclusive use. The
842 zone will create a pool and processor set when it boots. See \fBpooladm\fR(1M)
843 and \fBpoolcfg\fR(1M) for more information on resource pools. The \fBncpu\fR
844 property can specify a single value or a range (for example, 1-4) of
845 processors. The \fBimportance\fR property is optional; if set, it will specify
846 the \fBpset.importance\fR value for use by \fBpoold\fR(1M). If this resource is
847 used, there must be enough free processors to allocate to this zone when it
848 boots or the zone will not boot. The processors assigned to this zone will not
849 be available for the use of the global zone or other zones. This resource is
850 incompatible with both the \fBpool\fR and \fBcpu-shares\fR properties. Only a
851 single instance of this resource can be added to the zone.
852 .RE
853
854 .sp
855 .ne 2
856 .na
857 \fB\fBcapped-memory\fR: physical, swap, locked\fR
858 .ad
859 .sp .6
860 .RS 4n
861 The caps on the memory that can be used by this zone. A scale (K, M, G, T) can
862 be applied to the value for each of these numbers (for example, 1M is one
863 megabyte). Each of these properties is optional but at least one property must
864 be set when adding this resource. Only a single instance of this resource can
865 be added to the zone. The \fBphysical\fR property sets the \fBmax-rss\fR for
866 this zone. This will be enforced by \fBrcapd\fR(1M) running in the global zone.
867 The \fBswap\fR property is the preferred way to set the \fBzone.max-swap\fR
868 rctl. The \fBlocked\fR property is the preferred way to set the
869 \fBzone.max-locked-memory\fR rctl.
870 .RE
871
872 .sp
873 .ne 2
874 .na
875 \fB\fBcapped-cpu\fR: ncpus\fR
876 .ad
877 .sp .6
878 .RS 4n
879 Sets a limit on the amount of CPU time that can be used by a zone. The unit
880 used translates to the percentage of a single CPU that can be used by all user
881 threads in a zone, expressed as a fraction (for example, \fB\&.75\fR) or a
882 mixed number (whole number and fraction, for example, \fB1.25\fR). An
883 \fBncpu\fR value of \fB1\fR means 100% of a CPU, a value of \fB1.25\fR means
884 125%, \fB\&.75\fR mean 75%, and so forth. When projects within a capped zone
885 have their own caps, the minimum value takes precedence.
886 .sp
887 The \fBcapped-cpu\fR property is an alias for \fBzone.cpu-cap\fR resource
888 control and is related to the \fBzone.cpu-cap\fR resource control. See
889 \fBresource_controls\fR(5).
890 .RE
891
892 .sp
893 .ne 2
894 .na
895 \fBglobal: \fBfs-allowed\fR\fR
896 .ad
897 .sp .6
898 .RS 4n
899 A comma-separated list of additional filesystems that may be mounted within
900 the zone; for example "ufs,pcfs". By default, only hsfs(7fs) and network
901 filesystems can be mounted. If the first entry in the list is "-" then
902 that disables all of the default filesystems. If any filesystems are listed
903 after "-" then only those filesystems can be mounted.
904
905 This property does not apply to filesystems mounted into the zone via "add fs"
906 or "add dataset".
907
908 WARNING: allowing filesystem mounts other than the default may allow the zone
909 administrator to compromise the system with a malicious filesystem image, and
910 is not supported.
911 .RE
912
913 .sp
914 .ne 2
915 .na
916 \fBglobal: \fBzfs-io-priority\fR\fR
917 .ad
918 .sp .6
919 .RS 4n
920 Specifies a priority for this zone's ZFS I/O. The priority is used by the ZFS I/O scheduler as in input to determine how to schedule I/O across zones. By default all zones have a priority of 1. The value can be increased for zones whose I/O is more critical. This property is the preferred way to set the \fBzone.zfs-io-priority\fR rctl.
921 .RE
922
923 .sp
924 .LP
925 The following table summarizes resources, property-names, and types:
926 .sp
927 .in +2
928 .nf
929 resource property-name type
930 (global) zonename simple
931 (global) zonepath simple
932 (global) autoboot simple
933 (global) bootargs simple
934 (global) pool simple
935 (global) limitpriv simple
936 (global) brand simple
937 (global) ip-type simple
938 (global) hostid simple
939 (global) cpu-shares simple
940 (global) max-lwps simple
941 (global) max-msg-ids simple
942 (global) max-sem-ids simple
943 (global) max-shm-ids simple
944 (global) max-shm-memory simple
945 (global) scheduling-class simple
946 (global) zfs-io-priority simple
947 fs dir simple
948 special simple
949 raw simple
950 type simple
951 options list of simple
952 net address simple
953 allowed-address simple
954 defrouter simple
955 global-nic simple
956 mac-addr simple
957 physical simple
958 property list of complex
959 name simple
960 value simple
961 vlan-id simple
962 device match simple
963 rctl name simple
964 value list of complex
965 attr name simple
966 type simple
967 value simple
968 dataset name simple
969 dedicated-cpu ncpus simple or range
970 importance simple
971
972 capped-memory physical simple with scale
973 swap simple with scale
974 locked simple with scale
975
976 capped-cpu ncpus simple
977 .fi
978 .in -2
979 .sp
980
981 .sp
982 .LP
983 To further specify things, the breakdown of the complex property "value" of the
984 "rctl" resource type, it consists of three name/value pairs, the names being
985 "priv", "limit" and "action", each of which takes a simple value. The "name"
986 property of an "attr" resource is syntactically restricted in a fashion similar
987 but not identical to zone names: it must begin with an alphanumeric, and can
988 contain alphanumerics plus the hyphen (\fB-\fR), underscore (\fB_\fR), and dot
989 (\fB\&.\fR) characters. Attribute names beginning with "zone" are reserved for
990 use by the system. Finally, the "autoboot" global property must have a value of
991 "true" or "false".
992 .SS "Using Kernel Statistics to Monitor CPU Caps"
993 .LP
994 Using the kernel statistics (\fBkstat\fR(3KSTAT)) module \fBcaps\fR, the system
995 maintains information for all capped projects and zones. You can access this
996 information by reading kernel statistics (\fBkstat\fR(3KSTAT)), specifying
997 \fBcaps\fR as the \fBkstat\fR module name. The following command displays
998 kernel statistics for all active CPU caps:
999 .sp
1000 .in +2
1001 .nf
1002 # \fBkstat caps::'/cpucaps/'\fR
1003 .fi
1004 .in -2
1005 .sp
1006
1007 .sp
1008 .LP
1009 A \fBkstat\fR(1M) command running in a zone displays only CPU caps relevant for
1010 that zone and for projects in that zone. See \fBEXAMPLES\fR.
1011 .sp
1012 .LP
1013 The following are cap-related arguments for use with \fBkstat\fR(1M):
1014 .sp
1015 .ne 2
1016 .na
1017 \fB\fBcaps\fR\fR
1018 .ad
1019 .sp .6
1020 .RS 4n
1021 The \fBkstat\fR module.
1022 .RE
1023
1024 .sp
1025 .ne 2
1026 .na
1027 \fB\fBproject_caps\fR or \fBzone_caps\fR\fR
1028 .ad
1029 .sp .6
1030 .RS 4n
1031 \fBkstat\fR class, for use with the \fBkstat\fR \fB-c\fR option.
1032 .RE
1033
1034 .sp
1035 .ne 2
1036 .na
1037 \fB\fBcpucaps_project_\fR\fIid\fR or \fBcpucaps_zone_\fR\fIid\fR\fR
1038 .ad
1039 .sp .6
1040 .RS 4n
1041 \fBkstat\fR name, for use with the \fBkstat\fR \fB-n\fR option. \fIid\fR is the
1042 project or zone identifier.
1043 .RE
1044
1045 .sp
1046 .LP
1047 The following fields are displayed in response to a \fBkstat\fR(1M) command
1048 requesting statistics for all CPU caps.
1049 .sp
1050 .ne 2
1051 .na
1052 \fB\fBmodule\fR\fR
1053 .ad
1054 .sp .6
1055 .RS 4n
1056 In this usage of \fBkstat\fR, this field will have the value \fBcaps\fR.
1057 .RE
1058
1059 .sp
1060 .ne 2
1061 .na
1062 \fB\fBname\fR\fR
1063 .ad
1064 .sp .6
1065 .RS 4n
1066 As described above, \fBcpucaps_project_\fR\fIid\fR or
1067 \fBcpucaps_zone_\fR\fIid\fR
1068 .RE
1069
1070 .sp
1071 .ne 2
1072 .na
1073 \fB\fBabove_sec\fR\fR
1074 .ad
1075 .sp .6
1076 .RS 4n
1077 Total time, in seconds, spent above the cap.
1078 .RE
1079
1080 .sp
1081 .ne 2
1082 .na
1083 \fB\fBbelow_sec\fR\fR
1084 .ad
1085 .sp .6
1086 .RS 4n
1087 Total time, in seconds, spent below the cap.
1088 .RE
1089
1090 .sp
1091 .ne 2
1092 .na
1093 \fB\fBmaxusage\fR\fR
1094 .ad
1095 .sp .6
1096 .RS 4n
1097 Maximum observed CPU usage.
1098 .RE
1099
1100 .sp
1101 .ne 2
1102 .na
1103 \fB\fBnwait\fR\fR
1104 .ad
1105 .sp .6
1106 .RS 4n
1107 Number of threads on cap wait queue.
1108 .RE
1109
1110 .sp
1111 .ne 2
1112 .na
1113 \fB\fBusage\fR\fR
1114 .ad
1115 .sp .6
1116 .RS 4n
1117 Current aggregated CPU usage for all threads belonging to a capped project or
1118 zone, in terms of a percentage of a single CPU.
1119 .RE
1120
1121 .sp
1122 .ne 2
1123 .na
1124 \fB\fBvalue\fR\fR
1125 .ad
1126 .sp .6
1127 .RS 4n
1128 The cap value, in terms of a percentage of a single CPU.
1129 .RE
1130
1131 .sp
1132 .ne 2
1133 .na
1134 \fB\fBzonename\fR\fR
1135 .ad
1136 .sp .6
1137 .RS 4n
1138 Name of the zone for which statistics are displayed.
1139 .RE
1140
1141 .sp
1142 .LP
1143 See \fBEXAMPLES\fR for sample output from a \fBkstat\fR command.
1144 .SH OPTIONS
1145 .LP
1146 The following options are supported:
1147 .sp
1148 .ne 2
1149 .na
1150 \fB\fB-f\fR \fIcommand_file\fR\fR
1151 .ad
1152 .sp .6
1153 .RS 4n
1154 Specify the name of \fBzonecfg\fR command file. \fIcommand_file\fR is a text
1155 file of \fBzonecfg\fR subcommands, one per line.
1156 .RE
1157
1158 .sp
1159 .ne 2
1160 .na
1161 \fB\fB-z\fR \fIzonename\fR\fR
1162 .ad
1163 .sp .6
1164 .RS 4n
1165 Specify the name of a zone. Zone names are case sensitive. Zone names must
1166 begin with an alphanumeric character and can contain alphanumeric characters,
1167 the underscore (\fB_\fR) the hyphen (\fB-\fR), and the dot (\fB\&.\fR). The
1168 name \fBglobal\fR and all names beginning with \fBSUNW\fR are reserved and
1169 cannot be used.
1170 .RE
1171
1172 .sp
1173 .ne 2
1174 .na
1175 \fB\fB-u\fR \fIuuid\fR\fR
1176 .ad
1177 .sp .6
1178 .RS 4n
1179 Specify the uuid of a zone instead of the Zone name.
1180 .RE
1181
1182 .SH SUBCOMMANDS
1183 .LP
1184 You can use the \fBadd\fR and \fBselect\fR subcommands to select a specific
1185 resource, at which point the scope changes to that resource. The \fBend\fR and
1186 \fBcancel\fR subcommands are used to complete the resource specification, at
1187 which time the scope is reverted back to global. Certain subcommands, such as
1188 \fBadd\fR, \fBremove\fR and \fBset\fR, have different semantics in each scope.
1189 .sp
1190 .LP
1191 \fBzonecfg\fR supports a semicolon-separated list of subcommands. For example:
1192 .sp
1193 .in +2
1194 .nf
1195 # \fBzonecfg -z myzone "add net; set physical=myvnic; end"\fR
1196 .fi
1197 .in -2
1198 .sp
1199
1200 .sp
1201 .LP
1202 Subcommands which can result in destructive actions or loss of work have an
1203 \fB-F\fR option to force the action. If input is from a terminal device, the
1204 user is prompted when appropriate if such a command is given without the
1205 \fB-F\fR option otherwise, if such a command is given without the \fB-F\fR
1206 option, the action is disallowed, with a diagnostic message written to standard
1207 error.
1208 .sp
1209 .LP
1210 The following subcommands are supported:
1211 .sp
1212 .ne 2
1213 .na
1214 \fB\fBadd\fR \fIresource-type\fR (global scope)\fR
1215 .ad
1216 .br
1217 .na
1218 \fB\fBadd\fR \fIproperty-name property-value\fR (resource scope)\fR
1219 .ad
1220 .sp .6
1221 .RS 4n
1222 In the global scope, begin the specification for a given resource type. The
1223 scope is changed to that resource type.
1224 .sp
1225 In the resource scope, add a property of the given name with the given value.
1226 The syntax for property values varies with different property types. In
1227 general, it is a simple value or a list of simple values enclosed in square
1228 brackets, separated by commas (\fB[foo,bar,baz]\fR). See \fBPROPERTIES\fR.
1229 .RE
1230
1231 .sp
1232 .ne 2
1233 .na
1234 \fB\fBcancel\fR\fR
1235 .ad
1236 .sp .6
1237 .RS 4n
1238 End the resource specification and reset scope to global. Abandons any
1239 partially specified resources. \fBcancel\fR is only applicable in the resource
1240 scope.
1241 .RE
1242
1243 .sp
1244 .ne 2
1245 .na
1246 \fB\fBclear\fR \fIproperty-name\fR\fR
1247 .ad
1248 .sp .6
1249 .RS 4n
1250 Clear the value for the property.
1251 .RE
1252
1253 .sp
1254 .ne 2
1255 .na
1256 \fB\fBcommit\fR\fR
1257 .ad
1258 .sp .6
1259 .RS 4n
1260 Commit the current configuration from memory to stable storage. The
1261 configuration must be committed to be used by \fBzoneadm\fR. Until the
1262 in-memory configuration is committed, you can remove changes with the
1263 \fBrevert\fR subcommand. The \fBcommit\fR operation is attempted automatically
1264 upon completion of a \fBzonecfg\fR session. Since a configuration must be
1265 correct to be committed, this operation automatically does a verify.
1266 .RE
1267
1268 .sp
1269 .ne 2
1270 .na
1271 \fB\fBcreate [\fR\fB-F\fR\fB] [\fR \fB-a\fR \fIpath\fR |\fB-b\fR \fB|\fR \fB-t\fR \fItemplate\fR\fB] [\fR\fB-X\fR\fB]\fR\fR
1272 .ad
1273 .sp .6
1274 .RS 4n
1275 Create an in-memory configuration for the specified zone. Use \fBcreate\fR to
1276 begin to configure a new zone. See \fBcommit\fR for saving this to stable
1277 storage.
1278 .sp
1279 If you are overwriting an existing configuration, specify the \fB-F\fR option
1280 to force the action. Specify the \fB-t\fR \fItemplate\fR option to create a
1281 configuration identical to \fItemplate\fR, where \fItemplate\fR is the name of
1282 a configured zone.
1283 .sp
1284 Use the \fB-a\fR \fIpath\fR option to facilitate configuring a detached zone on
1285 a new host. The \fIpath\fR parameter is the zonepath location of a detached
1286 zone that has been moved on to this new host. Once the detached zone is
1287 configured, it should be installed using the "\fBzoneadm attach\fR" command
1288 (see \fBzoneadm\fR(1M)). All validation of the new zone happens during the
1289 \fBattach\fR process, not during zone configuration.
1290 .sp
1291 Use the \fB-b\fR option to create a blank configuration. Without arguments,
1292 \fBcreate\fR applies the Sun default settings.
1293 .sp
1294 Use the \fB-X\fR option to facilitate creating a zone whose XML definition already exists on the host. The zone will be atomically added to the zone index file.
1295 .RE
1296
1297 .sp
1298 .ne 2
1299 .na
1300 \fB\fBdelete [\fR\fB-F\fR\fB]\fR\fR
1301 .ad
1302 .sp .6
1303 .RS 4n
1304 Delete the specified configuration from memory and stable storage. This action
1305 is instantaneous, no commit is necessary. A deleted configuration cannot be
1306 reverted.
1307 .sp
1308 Specify the \fB-F\fR option to force the action.
1309 .RE
1310
1311 .sp
1312 .ne 2
1313 .na
1314 \fB\fBend\fR\fR
1315 .ad
1316 .sp .6
1317 .RS 4n
1318 End the resource specification. This subcommand is only applicable in the
1319 resource scope. \fBzonecfg\fR checks to make sure the current resource is
1320 completely specified. If so, it is added to the in-memory configuration (see
1321 \fBcommit\fR for saving this to stable storage) and the scope reverts to
1322 global. If the specification is incomplete, it issues an appropriate error
1323 message.
1324 .RE
1325
1326 .sp
1327 .ne 2
1328 .na
1329 \fB\fBexport [\fR\fB-f\fR \fIoutput-file\fR\fB]\fR\fR
1330 .ad
1331 .sp .6
1332 .RS 4n
1333 Print configuration to standard output. Use the \fB-f\fR option to print the
1334 configuration to \fIoutput-file\fR. This option produces output in a form
1335 suitable for use in a command file.
1336 .RE
1337
1338 .sp
1339 .ne 2
1340 .na
1341 \fB\fBhelp [usage] [\fIsubcommand\fR] [syntax] [\fR\fIcommand-name\fR\fB]\fR\fR
1342 .ad
1343 .sp .6
1344 .RS 4n
1345 Print general help or help about given topic.
1346 .RE
1347
1348 .sp
1349 .ne 2
1350 .na
1351 \fB\fBinfo zonename | zonepath | autoboot | brand | pool | limitpriv\fR\fR
1352 .ad
1353 .br
1354 .na
1355 \fB\fBinfo [\fR\fIresource-type\fR
1356 \fB[\fR\fIproperty-name\fR\fB=\fR\fIproperty-value\fR\fB]*]\fR\fR
1357 .ad
1358 .sp .6
1359 .RS 4n
1360 Display information about the current configuration. If \fIresource-type\fR is
1361 specified, displays only information about resources of the relevant type. If
1362 any \fIproperty-name\fR value pairs are specified, displays only information
1363 about resources meeting the given criteria. In the resource scope, any
1364 arguments are ignored, and \fBinfo\fR displays information about the resource
1365 which is currently being added or modified.
1366 .RE
1367
1368 .sp
1369 .ne 2
1370 .na
1371 \fB\fBremove\fR [\fR\fB-F\fR\fB] \fIresource-type\fR\fB [\fR\fIproperty-name\fR\fB=\fR\fIproperty-value\fR\fB]* \fR(global scope)\fR
1372 .br
1373 \fB\fBremove\fR \fR\fIproperty-name\fR\fB \fR\fIproperty-value\fR\fB \fR(resource scope)\fR
1374 .ad
1375 .sp .6
1376 .RS 4n
1377 In the global scope, removes the specified resource. The \fB[]\fR syntax means
1378 0 or more property name-value pairs. If you want to only remove a
1379 single instance of the resource, you must specify enough property name-value
1380 pairs for the resource to be uniquely identified. If no property name-value
1381 pairs are specified, all instances will be removed. If there is more than one
1382 pair specified, a confirmation is required, unless you use the \fB-F\fR
1383 option. Likewise, the \fB-F\fR option can be used to remove a resource that
1384 does not exist (that is, no error will occur). In the resource scope, remove
1385 the specified name-value pair.
1386 .RE
1387
1388 .sp
1389 .ne 2
1390 .na
1391 \fB\fBselect\fR \fIresource-type\fR
1392 \fB{\fR\fIproperty-name\fR\fB=\fR\fIproperty-value\fR\fB}\fR\fR
1393 .ad
1394 .sp .6
1395 .RS 4n
1396 Select the resource of the given type which matches the given
1397 \fIproperty-name\fR \fIproperty-value\fR pair criteria, for modification. This
1398 subcommand is applicable only in the global scope. The scope is changed to that
1399 resource type. The \fB{}\fR syntax means 1 or more of whatever is inside the
1400 curly braces. You must specify enough \fIproperty -name property-value\fR pairs
1401 for the resource to be uniquely identified.
1402 .RE
1403
1404 .sp
1405 .ne 2
1406 .na
1407 \fB\fBset\fR \fIproperty-name\fR\fB=\fR\fIproperty\fR\fB-\fR\fIvalue\fR\fR
1408 .ad
1409 .sp .6
1410 .RS 4n
1411 Set a given property name to the given value. Some properties (for example,
1412 \fBzonename\fR and \fBzonepath\fR) are global while others are
1413 resource-specific. This subcommand is applicable in both the global and
1414 resource scopes.
1415 .RE
1416
1417 .sp
1418 .ne 2
1419 .na
1420 \fB\fBverify\fR\fR
1421 .ad
1422 .sp .6
1423 .RS 4n
1424 Verify the current configuration for correctness:
1425 .RS +4
1426 .TP
1427 .ie t \(bu
1428 .el o
1429 All resources have all of their required properties specified.
1430 .RE
1431 .RS +4
1432 .TP
1433 .ie t \(bu
1434 .el o
1435 A \fBzonepath\fR is specified.
1436 .RE
1437 .RE
1438
1439 .sp
1440 .ne 2
1441 .na
1442 \fB\fBrevert\fR \fB[\fR\fB-F\fR\fB]\fR\fR
1443 .ad
1444 .sp .6
1445 .RS 4n
1446 Revert the configuration back to the last committed state. The \fB-F\fR option
1447 can be used to force the action.
1448 .RE
1449
1450 .sp
1451 .ne 2
1452 .na
1453 \fB\fBexit [\fR\fB-F\fR\fB]\fR\fR
1454 .ad
1455 .sp .6
1456 .RS 4n
1457 Exit the \fBzonecfg\fR session. A commit is automatically attempted if needed.
1458 You can also use an \fBEOF\fR character to exit \fBzonecfg\fR. The \fB-F\fR
1459 option can be used to force the action.
1460 .RE
1461
1462 .SH EXAMPLES
1463 .LP
1464 \fBExample 1 \fRCreating the Environment for a New Zone
1465 .sp
1466 .LP
1467 In the following example, \fBzonecfg\fR creates the environment for a new zone.
1468 \fB/usr/local\fR is loopback mounted from the global zone into
1469 \fB/opt/local\fR. \fB/opt/sfw\fR is loopback mounted from the global zone,
1470 three logical network interfaces are added, and a limit on the number of
1471 fair-share scheduler (FSS) CPU shares for a zone is set using the \fBrctl\fR
1472 resource type. The example also shows how to select a given resource for
1473 modification.
1474
1475 .sp
1476 .in +2
1477 .nf
1478 example# \fBzonecfg -z myzone3\fR
1479 my-zone3: No such zone configured
1480 Use 'create' to begin configuring a new zone.
1481 zonecfg:myzone3> \fBcreate\fR
1482 zonecfg:myzone3> \fBset zonepath=/export/home/my-zone3\fR
1483 zonecfg:myzone3> \fBset autoboot=true\fR
1484 zonecfg:myzone3> \fBadd fs\fR
1485 zonecfg:myzone3:fs> \fBset dir=/usr/local\fR
1486 zonecfg:myzone3:fs> \fBset special=/opt/local\fR
1487 zonecfg:myzone3:fs> \fBset type=lofs\fR
1488 zonecfg:myzone3:fs> \fBadd options [ro,nodevices]\fR
1489 zonecfg:myzone3:fs> \fBend\fR
1490 zonecfg:myzone3> \fBadd fs\fR
1491 zonecfg:myzone3:fs> \fBset dir=/mnt\fR
1492 zonecfg:myzone3:fs> \fBset special=/dev/dsk/c0t0d0s7\fR
1493 zonecfg:myzone3:fs> \fBset raw=/dev/rdsk/c0t0d0s7\fR
1494 zonecfg:myzone3:fs> \fBset type=ufs\fR
1495 zonecfg:myzone3:fs> \fBend\fR
1496 zonecfg:myzone3> \fBadd net\fR
1497 zonecfg:myzone3:net> \fBset address=192.168.0.1/24\fR
1498 zonecfg:myzone3:net> \fBset physical=eri0\fR
1499 zonecfg:myzone3:net> \fBend\fR
1500 zonecfg:myzone3> \fBadd net\fR
1501 zonecfg:myzone3:net> \fBset address=192.168.1.2/24\fR
1502 zonecfg:myzone3:net> \fBset physical=eri0\fR
1503 zonecfg:myzone3:net> \fBend\fR
1504 zonecfg:myzone3> \fBadd net\fR
1505 zonecfg:myzone3:net> \fBset address=192.168.2.3/24\fR
1506 zonecfg:myzone3:net> \fBset physical=eri0\fR
1507 zonecfg:myzone3:net> \fBend\fR
1508 zonecfg:my-zone3> \fBset cpu-shares=5\fR
1509 zonecfg:my-zone3> \fBadd capped-memory\fR
1510 zonecfg:my-zone3:capped-memory> \fBset physical=50m\fR
1511 zonecfg:my-zone3:capped-memory> \fBset swap=100m\fR
1512 zonecfg:my-zone3:capped-memory> \fBend\fR
1513 zonecfg:myzone3> \fBexit\fR
1514 .fi
1515 .in -2
1516 .sp
1517
1518 .LP
1519 \fBExample 2 \fRCreating a Non-Native Zone
1520 .sp
1521 .LP
1522 The following example creates a new Linux zone:
1523
1524 .sp
1525 .in +2
1526 .nf
1527 example# \fBzonecfg -z lxzone\fR
1528 lxzone: No such zone configured
1529 Use 'create' to begin configuring a new zone
1530 zonecfg:lxzone> \fBcreate -t SUNWlx\fR
1531 zonecfg:lxzone> \fBset zonepath=/export/zones/lxzone\fR
1532 zonecfg:lxzone> \fBset autoboot=true\fR
1533 zonecfg:lxzone> \fBexit\fR
1534 .fi
1535 .in -2
1536 .sp
1537
1538 .LP
1539 \fBExample 3 \fRCreating an Exclusive-IP Zone
1540 .sp
1541 .LP
1542 The following example creates a zone that is granted exclusive access to
1543 \fBbge1\fR and \fBbge33000\fR and that is isolated at the IP layer from the
1544 other zones configured on the system.
1545
1546 .sp
1547 .LP
1548 The IP addresses and routing is configured inside the new zone using
1549 \fBsysidtool\fR(1M).
1550
1551 .sp
1552 .in +2
1553 .nf
1554 example# \fBzonecfg -z excl\fR
1555 excl: No such zone configured
1556 Use 'create' to begin configuring a new zone
1557 zonecfg:excl> \fBcreate\fR
1558 zonecfg:excl> \fBset zonepath=/export/zones/excl\fR
1559 zonecfg:excl> \fBset ip-type=exclusive\fR
1560 zonecfg:excl> \fBadd net\fR
1561 zonecfg:excl:net> \fBset physical=bge1\fR
1562 zonecfg:excl:net> \fBend\fR
1563 zonecfg:excl> \fBadd net\fR
1564 zonecfg:excl:net> \fBset physical=bge33000\fR
1565 zonecfg:excl:net> \fBend\fR
1566 zonecfg:excl> \fBexit\fR
1567 .fi
1568 .in -2
1569 .sp
1570
1571 .LP
1572 \fBExample 4 \fRAssociating a Zone with a Resource Pool
1573 .sp
1574 .LP
1575 The following example shows how to associate an existing zone with an existing
1576 resource pool:
1577
1578 .sp
1579 .in +2
1580 .nf
1581 example# \fBzonecfg -z myzone\fR
1582 zonecfg:myzone> \fBset pool=mypool\fR
1583 zonecfg:myzone> \fBexit\fR
1584 .fi
1585 .in -2
1586 .sp
1587
1588 .sp
1589 .LP
1590 For more information about resource pools, see \fBpooladm\fR(1M) and
1591 \fBpoolcfg\fR(1M).
1592
1593 .LP
1594 \fBExample 5 \fRChanging the Name of a Zone
1595 .sp
1596 .LP
1597 The following example shows how to change the name of an existing zone:
1598
1599 .sp
1600 .in +2
1601 .nf
1602 example# \fBzonecfg -z myzone\fR
1603 zonecfg:myzone> \fBset zonename=myzone2\fR
1604 zonecfg:myzone2> \fBexit\fR
1605 .fi
1606 .in -2
1607 .sp
1608
1609 .LP
1610 \fBExample 6 \fRChanging the Privilege Set of a Zone
1611 .sp
1612 .LP
1613 The following example shows how to change the set of privileges an existing
1614 zone's processes will be limited to the next time the zone is booted. In this
1615 particular case, the privilege set will be the standard safe set of privileges
1616 a zone normally has along with the privilege to change the system date and
1617 time:
1618
1619 .sp
1620 .in +2
1621 .nf
1622 example# \fBzonecfg -z myzone\fR
1623 zonecfg:myzone> \fBset limitpriv="default,sys_time"\fR
1624 zonecfg:myzone2> \fBexit\fR
1625 .fi
1626 .in -2
1627 .sp
1628
1629 .LP
1630 \fBExample 7 \fRSetting the \fBzone.cpu-shares\fR Property for the Global Zone
1631 .sp
1632 .LP
1633 The following command sets the \fBzone.cpu-shares\fR property for the global
1634 zone:
1635
1636 .sp
1637 .in +2
1638 .nf
1639 example# \fBzonecfg -z global\fR
1640 zonecfg:global> \fBset cpu-shares=5\fR
1641 zonecfg:global> \fBexit\fR
1642 .fi
1643 .in -2
1644 .sp
1645
1646 .LP
1647 \fBExample 8 \fRUsing Pattern Matching
1648 .sp
1649 .LP
1650 The following commands illustrate \fBzonecfg\fR support for pattern matching.
1651 In the zone \fBflexlm\fR, enter:
1652
1653 .sp
1654 .in +2
1655 .nf
1656 zonecfg:flexlm> \fBadd device\fR
1657 zonecfg:flexlm:device> \fBset match="/dev/cua/a00[2-5]"\fR
1658 zonecfg:flexlm:device> \fBend\fR
1659 .fi
1660 .in -2
1661 .sp
1662
1663 .sp
1664 .LP
1665 In the global zone, enter:
1666
1667 .sp
1668 .in +2
1669 .nf
1670 global# \fBls /dev/cua\fR
1671 a a000 a001 a002 a003 a004 a005 a006 a007 b
1672 .fi
1673 .in -2
1674 .sp
1675
1676 .sp
1677 .LP
1678 In the zone \fBflexlm\fR, enter:
1679
1680 .sp
1681 .in +2
1682 .nf
1683 flexlm# \fBls /dev/cua\fR
1684 a002 a003 a004 a005
1685 .fi
1686 .in -2
1687 .sp
1688
1689 .LP
1690 \fBExample 9 \fRSetting a Cap for a Zone to Three CPUs
1691 .sp
1692 .LP
1693 The following sequence uses the \fBzonecfg\fR command to set the CPU cap for a
1694 zone to three CPUs.
1695
1696 .sp
1697 .in +2
1698 .nf
1699 zonecfg:myzone> \fBadd capped-cpu\fR
1700 zonecfg:myzone>capped-cpu> \fBset ncpus=3\fR
1701 zonecfg:myzone>capped-cpu>capped-cpu> \fBend\fR
1702 .fi
1703 .in -2
1704 .sp
1705
1706 .sp
1707 .LP
1708 The preceding sequence, which uses the capped-cpu property, is equivalent to
1709 the following sequence, which makes use of the \fBzone.cpu-cap\fR resource
1710 control.
1711
1712 .sp
1713 .in +2
1714 .nf
1715 zonecfg:myzone> \fBadd rctl\fR
1716 zonecfg:myzone:rctl> \fBset name=zone.cpu-cap\fR
1717 zonecfg:myzone:rctl> \fBadd value (priv=privileged,limit=300,action=none)\fR
1718 zonecfg:myzone:rctl> \fBend\fR
1719 .fi
1720 .in -2
1721 .sp
1722
1723 .LP
1724 \fBExample 10 \fRUsing \fBkstat\fR to Monitor CPU Caps
1725 .sp
1726 .LP
1727 The following command displays information about all CPU caps.
1728
1729 .sp
1730 .in +2
1731 .nf
1732 # \fBkstat -n /cpucaps/\fR
1733 module: caps instance: 0
1734 name: cpucaps_project_0 class: project_caps
1735 above_sec 0
1736 below_sec 2157
1737 crtime 821.048183159
1738 maxusage 2
1739 nwait 0
1740 snaptime 235885.637253027
1741 usage 0
1742 value 18446743151372347932
1743 zonename global
1744
1745 module: caps instance: 0
1746 name: cpucaps_project_1 class: project_caps
1747 above_sec 0
1748 below_sec 0
1749 crtime 225339.192787265
1750 maxusage 5
1751 nwait 0
1752 snaptime 235885.637591677
1753 usage 5
1754 value 18446743151372347932
1755 zonename global
1756
1757 module: caps instance: 0
1758 name: cpucaps_project_201 class: project_caps
1759 above_sec 0
1760 below_sec 235105
1761 crtime 780.37961782
1762 maxusage 100
1763 nwait 0
1764 snaptime 235885.637789687
1765 usage 43
1766 value 100
1767 zonename global
1768
1769 module: caps instance: 0
1770 name: cpucaps_project_202 class: project_caps
1771 above_sec 0
1772 below_sec 235094
1773 crtime 791.72983782
1774 maxusage 100
1775 nwait 0
1776 snaptime 235885.637967512
1777 usage 48
1778 value 100
1779 zonename global
1780
1781 module: caps instance: 0
1782 name: cpucaps_project_203 class: project_caps
1783 above_sec 0
1784 below_sec 235034
1785 crtime 852.104401481
1786 maxusage 75
1787 nwait 0
1788 snaptime 235885.638144304
1789 usage 47
1790 value 100
1791 zonename global
1792
1793 module: caps instance: 0
1794 name: cpucaps_project_86710 class: project_caps
1795 above_sec 22
1796 below_sec 235166
1797 crtime 698.441717859
1798 maxusage 101
1799 nwait 0
1800 snaptime 235885.638319871
1801 usage 54
1802 value 100
1803 zonename global
1804
1805 module: caps instance: 0
1806 name: cpucaps_zone_0 class: zone_caps
1807 above_sec 100733
1808 below_sec 134332
1809 crtime 821.048177123
1810 maxusage 207
1811 nwait 2
1812 snaptime 235885.638497731
1813 usage 199
1814 value 200
1815 zonename global
1816
1817 module: caps instance: 1
1818 name: cpucaps_project_0 class: project_caps
1819 above_sec 0
1820 below_sec 0
1821 crtime 225360.256448422
1822 maxusage 7
1823 nwait 0
1824 snaptime 235885.638714404
1825 usage 7
1826 value 18446743151372347932
1827 zonename test_001
1828
1829 module: caps instance: 1
1830 name: cpucaps_zone_1 class: zone_caps
1831 above_sec 2
1832 below_sec 10524
1833 crtime 225360.256440278
1834 maxusage 106
1835 nwait 0
1836 snaptime 235885.638896443
1837 usage 7
1838 value 100
1839 zonename test_001
1840 .fi
1841 .in -2
1842 .sp
1843
1844 .LP
1845 \fBExample 11 \fRDisplaying CPU Caps for a Specific Zone or Project
1846 .sp
1847 .LP
1848 Using the \fBkstat\fR \fB-c\fR and \fB-i\fR options, you can display CPU caps
1849 for a specific zone or project, as below. The first command produces a display
1850 for a specific project, the second for the same project within zone 1.
1851
1852 .sp
1853 .in +2
1854 .nf
1855 # \fBkstat -c project_caps\fR
1856
1857 # \fBkstat -c project_caps -i 1\fR
1858 .fi
1859 .in -2
1860 .sp
1861
1862 .SH EXIT STATUS
1863 .LP
1864 The following exit values are returned:
1865 .sp
1866 .ne 2
1867 .na
1868 \fB\fB0\fR\fR
1869 .ad
1870 .sp .6
1871 .RS 4n
1872 Successful completion.
1873 .RE
1874
1875 .sp
1876 .ne 2
1877 .na
1878 \fB\fB1\fR\fR
1879 .ad
1880 .sp .6
1881 .RS 4n
1882 An error occurred.
1883 .RE
1884
1885 .sp
1886 .ne 2
1887 .na
1888 \fB\fB2\fR\fR
1889 .ad
1890 .sp .6
1891 .RS 4n
1892 Invalid usage.
1893 .RE
1894
1895 .SH ATTRIBUTES
1896 .LP
1897 See \fBattributes\fR(5) for descriptions of the following attributes:
1898 .sp
1899
1900 .sp
1901 .TS
1902 box;
1903 c | c
1904 l | l .
1905 ATTRIBUTE TYPE ATTRIBUTE VALUE
1906 _
1907 Interface Stability Volatile
1908 .TE
1909
1910 .SH SEE ALSO
1911 .LP
1912 \fBppriv\fR(1), \fBprctl\fR(1), \fBzlogin\fR(1), \fBkstat\fR(1M),
1913 \fBmount\fR(1M), \fBpooladm\fR(1M), \fBpoolcfg\fR(1M), \fBpoold\fR(1M),
1914 \fBrcapd\fR(1M), \fBrctladm\fR(1M), \fBsvcadm\fR(1M), \fBsysidtool\fR(1M),
1915 \fBzfs\fR(1M), \fBzoneadm\fR(1M), \fBpriocntl\fR(2), \fBpriv_str_to_set\fR(3C),
1916 \fBkstat\fR(3KSTAT), \fBvfstab\fR(4), \fBattributes\fR(5), \fBbrands\fR(5),
1917 \fBfnmatch\fR(5), \fBlx\fR(5), \fBprivileges\fR(5), \fBresource_controls\fR(5),
1918 \fBzones\fR(5)
1919 .sp
1920 .LP
1921 \fISystem Administration Guide: Solaris Containers-Resource Management, and
1922 Solaris Zones\fR
1923 .SH NOTES
1924 .LP
1925 All character data used by \fBzonecfg\fR must be in US-ASCII encoding.