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