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