Print this page
14019 Allow more control over zone init exit actions
Portions contributed by: Joshua M. Clulow <jmc@joyent.com>
Portions contributed by: Andy Fiddaman <andy@omnios.org>
Reviewed by: C Fraire <cfraire@me.com>
Reviewed by: Gordon Ross <Gordon.W.Ross@gmail.com>
Approved by: Robert Mustacchi <rm@fingolfin.org>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/lib/libbrand/dtd/brand.dtd.1.man.txt
+++ new/usr/src/lib/libbrand/dtd/brand.dtd.1.man.txt
1 1 () ()
2 2
3 3
4 4
5 5 <?xml version='1.0' encoding='UTF-8' ?>
6 6
7 7 <!--
8 8 CDDL HEADER START
9 9
10 10 The contents of this file are subject to the terms of the
11 11 Common Development and Distribution License (the "License").
12 12 You may not use this file except in compliance with the License.
13 13
14 14 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
15 15 or http://www.opensolaris.org/os/licensing.
16 16 See the License for the specific language governing permissions
17 17 and limitations under the License.
18 18
19 19 When distributing Covered Code, include this CDDL HEADER in each
20 20 file and include the License file at usr/src/OPENSOLARIS.LICENSE.
21 21 If applicable, add the following below this CDDL HEADER, with the
22 22 fields enclosed by brackets "[]" replaced with your own identifying
23 23 information: Portions Copyright [yyyy] [name of copyright owner]
24 24
25 25 CDDL HEADER END
26 26
27 27 Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.
28 28 Copyright (c) 2011, Joyent, Inc. All rights reserved.
29 29
30 30 DO NOT EDIT THIS FILE.
31 31
32 32 Copyright 2014 Nexenta Systems, Inc. All rights reserved. -->
33 33
34 34 <!--
35 35 verify_cfg
36 36
37 37 Identifies the program to be invoked by zonecfg to verify that the
38 38 zone's configuration is legal, and that all the configured devices,
39 39 attributes, etc. are legal for this brand.
40 40
41 41 The program is called with a single argument: the path to a file
42 42 containing a temporary config.xml file the zone. It should return 0
43 43 on success and non-0 on failure. Any detailed error messages should be
44 44 displayed to stderr.
45 45
46 46 It has no attributes.
47 47
48 48 --> <!ELEMENT verify_cfg (#PCDATA) > <!ATTLIST verify_cfg> <!--
49 49 verify_adm
50 50
51 51 Identifies the program invoked by zoneadm to perform brand-specific
52 52 checks as to the viability of a zone on this specific machine.
53 53
54 54 The following replacements are performed:
55 55
56 56 %z Name of zone
57 57 %R Zonepath of zone
58 58 Additional arguments, if any, are appended.
59 59
60 60 The program should return 0 on success and non-0 on failure. Any
61 61 detailed error messages should be displayed to stderr.
62 62
63 63 It has no attributes.
64 64
65 65 --> <!ELEMENT verify_adm (#PCDATA) > <!ATTLIST verify_adm>
66 66
67 67 <!--
68 68 install
69 69
70 70 Identifies the program to invoke when installing a zone. The following
71 71 replacements are performed:
72 72
73 73 %z Name of zone
74 74 %R Zonepath of zone
75 75 Additional arguments, if any, are appended.
76 76
77 77 It has no attributes. --> <!ELEMENT install (#PCDATA) > <!ATTLIST
78 78 install>
79 79
80 80 <!--
81 81 installopts
82 82
83 83 Identifies the command-line options supported by the brand's
84 84 installation program, allowing zoneadm to parse the install line
85 85 properly.
86 86
87 87 It has no attributes. --> <!ELEMENT installopts (#PCDATA) > <!ATTLIST
88 88 installopts>
89 89
90 90 <!--
91 91 boot
92 92
93 93 This is a program which gets run by zoneadmd when a zone is booted.
94 94 The program will be invoked as the last step in the zone booting
95 95 process before the the first process is spawned inside the zone.
96 96
97 97 If this programs succeeds it should not generate any output.
98 98 If this program returns an error, any output generated by the
99 99 program will be sent to the zoneadmd message log.
100 100
101 101 The following replacements are performed:
102 102
103 103 %z Name of zone
104 104 %R Zonepath of zone
105 105 Additional arguments, if any, are appended.
106 106
107 107 It has no attributes. --> <!ELEMENT boot (#PCDATA) > <!ATTLIST boot>
108 108
109 109 <!--
110 110 sysboot
111 111
112 112 This is a program that will be run by zoneadm during system boot for an
113 113 installed zone that won't automatically boot.
114 114
115 115 If the program succeeds, then it should not generate output.
116 116 If the program returns an error, then the output it generates will be
117 117 sent to the zones SMF service's message log.
118 118
119 119 The following replacements are performed:
120 120
121 121 %z Name of the target zone
122 122 %R Zonepath of the target zone
123 123 Additional arguments, if any, are appended.
124 124
125 125 This element has no attributes. --> <!ELEMENT sysboot (#PCDATA) >
126 126 <!ATTLIST sysboot>
127 127
128 128 <!--
129 129 halt
130 130
131 131 This is a program which gets run by zoneadmd when a zone is being
132 132 halted. This callback is provided to allow a brand to cleanup any
133 133 special configuration that was setup during boot.
134 134
135 135 This program will also be invoked by zoneadmd if any part of the zone
136 136 booting process fail, even if the booting process failed before the
137 137 brand boot program was invoked. It is also possible that if the zone
138 138 fails to halt after invoking this program, future attempts to halt the
139 139 zone will invoke this program again. So this program should be
140 140 designed to clean up any resources allocated to a zone but it should
141 141 also be able to gracefully handle the case where resources that it
142 142 expects to release are not actually allocated (or have been already
143 143 released.)
144 144
145 145 If this programs succeeds it should not generate any output. If this
146 146 program returns an error, any output generated by the program will be
147 147 sent to the zoneadmd message log.
148 148
149 149 The following replacements are performed:
150 150
151 151 %z Name of zone
152 152 %R Zonepath of zone
153 153 Additional arguments, if any, are appended.
154 154
155 155 It has no attributes. --> <!ELEMENT halt (#PCDATA) > <!ATTLIST halt>
156 156
157 157 <!--
158 158 shutdown
159 159
160 160 This is a program which gets run by zoneadmd when a zone is being
161 161 shutdown gracefully. Currently only asynchronous mode is supported.
162 162
163 163 If this program succeeds it should not generate any output. If this
164 164 program returns an error, any output generated by the program will be
165 165 sent to the zoneadmd message log.
166 166
167 167 The following replacements are performed:
168 168
169 169 %z Name of zone
170 170 %R Zonepath of zone
171 171 Additional arguments, if any, are appended.
172 172
173 173 It has no attributes. --> <!ELEMENT shutdown (#PCDATA) > <!ATTLIST
174 174 shutdown>
175 175
176 176 <!--
177 177 modname
178 178
179 179 Path to the kernel module that implements the kernel-level
180 180 functionality of the brand.
181 181
182 182 It has no attributes. --> <!ELEMENT modname (#PCDATA) > <!ATTLIST
183 183 modname>
184 184
|
↓ open down ↓ |
184 lines elided |
↑ open up ↑ |
185 185 <!--
186 186 initname
187 187
188 188 Path to the initial executable that should be launched when booting a
189 189 branded zone.
190 190
191 191 It has no attributes. --> <!ELEMENT initname (#PCDATA) > <!ATTLIST
192 192 initname>
193 193
194 194 <!--
195 - restartinit
195 + restartinit, restartinit0 and restartinitreboot
196 196
197 - Boolean indicating that the program specified by the initname attr
198 - should be restarted, or not, if it exits. By default, the init program
199 - will be restarted if this attribute is not provided. Specifying false
200 - for this attr will prevent that.
197 + These three boolean elements control what action is taken when the
198 + program specified by the 'initname' element exits.
201 199
202 - It has no attributes. --> <!ELEMENT restartinit (#PCDATA) > <!ATTLIST
203 -restartinit>
200 + The default values are:
204 201
202 + restartinit: true
203 + restartinit0: false
204 + restartinitreboot: false
205 +
206 + If 'restartinit' is set to false then the init process will never be
207 + restarted and the zone will shut down once init exits. In this case, the
208 + other restartinit elements are ignored.
209 +
210 + When 'restartinit0' is set, init will only be restarted if it exited with
211 + an exit status of 0, otherwise the zone will shut down.
212 +
213 + If 'restartinitreboot' is set to true then whenever init should be
214 + restarted, based on the other restartinit elements, the zone will instead
215 + be rebooted.
216 +
217 + These have no attributes. --> <!ELEMENT restartinit (#PCDATA) >
218 +<!ATTLIST restartinit> <!ELEMENT restartinit0 (#PCDATA) > <!ATTLIST
219 +restartinit0> <!ELEMENT restartinitreboot (#PCDATA) > <!ATTLIST
220 +restartinitreboot>
221 +
205 222 <!--
206 223 login_cmd
207 224
208 225 Path to the initial login binary that should be executed when
209 226 attempting to zlogin into a branded zone.
210 227
211 228 The following replacements are performed:
212 229
213 230 %Z Name of the current zone
214 231 %u User login name
215 232
216 233 It has no attributes. --> <!ELEMENT login_cmd (#PCDATA) > <!ATTLIST
217 234 login_cmd>
218 235
219 236 <!--
220 237 forcedlogin_cmd
221 238
222 239 Path to the initial login binary that should be executed when
223 240 attempting to zlogin into a branded zone without authentication.
224 241
225 242 The following replacements are performed:
226 243
227 244 %Z Name of the current zone
228 245 %u User login name
229 246
230 247 It has no attributes. --> <!ELEMENT forcedlogin_cmd (#PCDATA) >
231 248 <!ATTLIST forcedlogin_cmd>
232 249
233 250 <!--
234 251 user_cmd
235 252
236 253 Path to the binary that will translate a user name to a passwd(4) entry.
237 254
238 255 The following replacements are performed:
239 256
240 257 %u User login name
241 258
242 259 It has no attributes. The passwd(4) entry is used to determine $LOGNAME,
243 260 $HOME, and $SHELL for non-interactive "zlogin -l <user> <cmd>". -->
244 261 <!ELEMENT user_cmd (#PCDATA) > <!ATTLIST user_cmd>
245 262
246 263 <!--
247 264 attach
248 265
249 266 Path to a hook that will perform any necessary processing on
250 267 a zone to allow it to be attached. The zone will be in the "configured"
251 268 state when this hook is run. This hook is never called when the zone
252 269 is "force attached" (-F).
253 270
254 271 If this hook exits with a non-zero exit status, the attach operation
255 272 will fail.
256 273
257 274 The following replacements are performed:
258 275
259 276 %z Name of zone
260 277 %R Zonepath of zone
261 278 Additional arguments, if any, are appended.
262 279
263 280 If no hook is provided, the internal zoneadm attach code will be used.
264 281
265 282 It has no attributes. --> <!ELEMENT attach (#PCDATA) > <!ATTLIST
266 283 attach>
267 284
268 285 <!--
269 286 postattach
270 287
271 288 Path to a hook that will perform any necessary post-processing on
272 289 a zone after it has been attached. The zone will be in the "installed"
273 290 state when this hook is run. This hook is never called when the zone
274 291 is "force attached" (-F).
275 292
276 293 If this hook exits with a non-zero exit status, the attach operation
277 294 will fail and the zone state will be reset to "configured".
278 295
279 296 The following replacements are performed:
280 297
281 298 %z Name of zone
282 299 %R Zonepath of zone
283 300 Additional arguments, if any, are appended.
284 301
285 302 It has no attributes. --> <!ELEMENT postattach (#PCDATA) > <!ATTLIST
286 303 postattach>
287 304
288 305 <!--
289 306 postclone
290 307
291 308 Path to a hook that will perform any necessary post-processing on
292 309 a zone after it has been cloned. The zone will be in the "incomplete"
293 310 state when this hook is run.
294 311
295 312 If this hook exits with a non-zero exit status, the clone operation
296 313 will fail and the zone will be left in the "incomplete" state,
297 314 otherwise the state will be changed to the "installed" state.
298 315
299 316 The following replacements are performed:
300 317
301 318 %z Name of zone
302 319 %R Zonepath of zone
303 320 Additional arguments, if any, are appended.
304 321
305 322 It has no attributes. --> <!ELEMENT postclone (#PCDATA) > <!ATTLIST
306 323 postclone>
307 324
308 325 <!--
309 326 postinstall
310 327
311 328 Path to a script that will perform any necessary post-processing on
312 329 a zone after it has been freshly installed. This hook will run after the
313 330 install hook completes and the zone is in the installed state. The
314 331 additional arguments are the same as what is passed to the install hook.
315 332
316 333 The following replacements are performed:
317 334
318 335 %z Name of zone
319 336 %R Zonepath of zone
320 337 Additional arguments, if any, are appended.
321 338
322 339 It has no attributes. --> <!ELEMENT postinstall (#PCDATA) > <!ATTLIST
323 340 postinstall>
324 341
325 342 <!--
326 343 predetach
327 344
328 345 Path to a hook that will perform any necessary pre-processing on
329 346 a zone before it is detached. The zone will be in the "installed"
330 347 state when this hook is run.
331 348
332 349 It is possible that if the zone fails to detach after invoking this
333 350 hook, future attempts to detach the zone will invoke this hook again.
334 351 So this hook should be designed to gracefully handle the case where
335 352 it is run multiple times on the same zone. If this hook exits with
336 353 a non-zero exit status, the detach operation will fail.
337 354
338 355 This hook is most commonly used when there is pre-processing for detaching
339 356 a zone but the built-in detach support will be used for the actual
340 357 detach. Otherwise, if a detach hook is provided, then it can be used
341 358 to do both preprocessing as well as the actual detach.
342 359
343 360 The following replacements are performed:
344 361
345 362 %z Name of zone
346 363 %R Zonepath of zone
347 364 Additional arguments, if any, are appended.
348 365
349 366 It has no attributes. --> <!ELEMENT predetach (#PCDATA) > <!ATTLIST
350 367 predetach>
351 368
352 369 <!--
353 370 detach
354 371
355 372 Path to a hook that will perform any necessary processing on
356 373 a zone to allow it to be detached. The zone will be in the "installed"
357 374 state when this hook is run.
358 375
359 376 It is possible that if the zone fails to detach while running this
360 377 hook, future attempts to detach the zone will invoke this hook again.
361 378 So this hook should be designed to gracefully handle the case where
362 379 it is run multiple times on the same zone. If this hook exits with
363 380 a non-zero exit status, the detach operation will fail and the zone will
364 381 be left in the "installed" state, otherwise the state will be changed
365 382 to "configured".
366 383
367 384 The following replacements are performed:
368 385
369 386 %z Name of zone
370 387 %R Zonepath of zone
371 388 Additional arguments, if any, are appended.
372 389
373 390 If no hook is provided, the internal zoneadm detach code will be used.
374 391
375 392 It has no attributes. --> <!ELEMENT detach (#PCDATA) > <!ATTLIST
376 393 detach>
377 394
378 395 <!--
379 396 clone
380 397 Path to a hook that will perform any necessary processing on a zone to
381 398 allow it to be installed via cloning. Cloning is an alternative to
382 399 installing so this hook should result in the same effect for the zone.
383 400 The zone will be in the "incomplete" state when this hook is run.
384 401
385 402 If this hook exits with a non-zero exit status, the clone operation
386 403 will fail and the zone will be left in the "incomplete" state, otherwise
387 404 the state will be changed to "installed".
388 405
389 406 The following replacements are performed:
390 407
391 408 %z Name of zone
392 409 %R Zonepath of zone
393 410 1st arg name of source zone
394 411 Additional arguments, if any, are appended.
395 412
396 413 If no hook is provided, the internal zoneadm cloning code will be used.
397 414 --> <!ELEMENT clone (#PCDATA) > <!ATTLIST clone>
398 415
399 416 <!--
400 417 preuninstall
401 418
402 419 Path to a script that will perform any necessary pre-processing on
403 420 a zone before it is uninstalled. The zone will be in the "installed"
404 421 state when this hook is run.
405 422
406 423 It is possible that if the zone fails to uninstall after invoking this
407 424 hook, future attempts to uninstall the zone will invoke this hook
408 425 again. So this hook should be designed to gracefully handle the case
409 426 where it is run multiple times on the same zone. If this hook exits
410 427 with a non-zero exit status, the uninstall operation will fail.
411 428
412 429 The following replacements are performed:
413 430
414 431 %z Name of zone
415 432 %R Zonepath of zone
416 433 Additional arguments, if any, are appended.
417 434
418 435 It has no attributes. --> <!ELEMENT preuninstall (#PCDATA) > <!ATTLIST
419 436 preuninstall>
420 437
421 438 <!--
422 439 uninstall
423 440 Identifies the hook to invoke when uninstalling a zone. The zone will
424 441 be in the "incomplete" state when this hook is run.
425 442
426 443 If this hook exits with a non-zero exit status, the uninstall operation
427 444 will fail and the zone will be left in the "incomplete" state, otherwise
428 445 the state will be changed to "configured".
429 446
430 447 The following replacements are performed:
431 448
432 449 %z Name of zone
433 450 %R Zonepath of zone
434 451 Additional arguments, if any, are appended.
435 452
436 453 If no hook is provided, the internal zoneadm uninstall code will be used.
437 454 --> <!ELEMENT uninstall (#PCDATA) > <!ATTLIST uninstall>
438 455
439 456 <!--
440 457 presnap
441 458 Identifies the hook to invoke before snapshotting a zone using the
442 459 built-in ZFS clone support.
443 460
444 461 If this hook exits with a non-zero exit status, the snapshot operation
445 462 will fail and the zfs clone operation will fail.
446 463
447 464 The following replacements are performed:
448 465
449 466 %z Name of zone
450 467 %R Zonepath of zone --> <!ELEMENT presnap (#PCDATA) > <!ATTLIST
451 468 presnap>
452 469
453 470 <!--
454 471 postsnap
455 472 Identifies the hook to invoke after snapshotting a zone using the
456 473 built-in ZFS clone support.
457 474
458 475 If this hook exits with a non-zero exit status, the zfs clone operation
459 476 will fail.
460 477
461 478 The following replacements are performed:
462 479
463 480 %z Name of zone
464 481 %R Zonepath of zone --> <!ELEMENT postsnap (#PCDATA) > <!ATTLIST
465 482 postsnap>
466 483
467 484 <!--
468 485 validatesnap
469 486 Identifies the hook to invoke to validate a snapshot of a zone using the
470 487 built-in ZFS clone support. This will validate a snapshot that was
471 488 explicitly specified to the clone command when the user wants to
472 489 re-use a snapshot from an earlier clone operation.
473 490
474 491 If this hook exits with a non-zero exit status, the snapshot validation
475 492 operation will fail, meaning the zfs snapshot cannot be used to install
476 493 the zone.
477 494
478 495 The following replacements are performed:
479 496
480 497 %z Name of zone
481 498 %R Zonepath of zone
482 499 1st arg snapshot name
483 500 2nd arg snapshot path --> <!ELEMENT validatesnap (#PCDATA) >
484 501 <!ATTLIST validatesnap>
485 502
486 503 <!--
487 504 prestatechange
488 505 Identifies the hook to invoke before zoneadmd makes a state change.
489 506 If this hook exits with a non-zero exit status, the action failed
490 507 and no further state change activity will take place.
491 508
492 509 The following replacements are performed:
493 510
494 511 %z Name of zone
495 512 %R Zonepath of zone
496 513 1st arg integer representing current state of zone 2 -
497 514 installed 3 - ready 4 - running 5 -
498 515 shutting down 6 - down 7 - mounted
499 516 2nd arg integer representing transition command 0 -
500 517 ready 1 - boot 4 - halt
501 518 3rd arg Alternate root (zonepath is mounted under this root)
502 519 empty string if zone not mounted under alternate root -->
503 520 <!ELEMENT prestatechange (#PCDATA) > <!ATTLIST prestatechange>
504 521
505 522 <!--
506 523 poststatechange
507 524 Identifies the hook to invoke after zoneadmd makes a successful state
508 525 change. If this hook exits with a non-zero exit status, the action failed
509 526 and zoneadmd treats the overall state change as failed, although
510 527 all of the actions up to running the hook will have taken place.
511 528
512 529 The following replacements are performed:
513 530
514 531 %z Name of zone
515 532 %R Zonepath of zone
516 533 See prestatechange comment for 1st, 2nd and 3rd argument values. -->
517 534 <!ELEMENT poststatechange (#PCDATA) > <!ATTLIST poststatechange>
518 535
519 536 <!--
520 537 query
521 538 Identifies a hook which can be called to get brand-specific information
522 539 about the zone. There is no specific place in zones where this is called,
523 540 calls within the zone infrastructure can be added as needed.
524 541
525 542 One example of the use of this hook is to query the implicit ZFS datasets
526 543 supported by the brand.
527 544
528 545 If this hook exits with a non-zero exit status, the query failed,
529 546 although in general, this hook shouldn't return non-zero.
530 547
531 548 The following replacements are performed:
532 549
533 550 %z Name of zone
534 551 %R Zonepath of zone
535 552 1st arg Arbitrary string which the hook can use to determine what
536 553 data to return. Brands implementing this hook should be
537 554 tolerant of arguments they don't support and simply do
538 555 nothing. --> <!ELEMENT query (#PCDATA) > <!ATTLIST query>
539 556
540 557 <!--
541 558 privilege
542 559
543 560 Add a privilege to the default, prohibited, or required set for all
544 561 zones of this brand with ip-type matched. If a privilege is added
545 562 to the default set all zones of this brand with ip-type matched on
546 563 the system will inherit this privilege unless the privilege is
547 564 removed via limitpriv in zonecfg(1m). If a privilege is added to
548 565 the prohibited set it can not be added to any zones with ip-type
549 566 matched via limitpriv in zonecfg(1m). If a privilege is added to
550 567 the required set then all zones of this brand with ip-type matched
551 568 on the system will inherit this privilege and it can't be removed via
552 569 limitpriv in zonecfg(1m).
553 570
554 571 Its attributes are
555 572 set The name of the set the privilege should go into.
556 573 name The name of the privilege.
557 574 ip-type Optional, indicates that adding of the privilege to the
558 575 set only applies to certain IP types. Can be "shared" or
559 576 "exclusive". If it is not specified, the default value
560 577 "all" will be used, which means it is applicable regardless
561 578 the IP type.
562 579
563 580 --> <!ELEMENT privilege (#PCDATA) > <!ATTLIST privilege set ( default |
564 581 prohibited | required ) #REQUIRED name CDATA #REQUIRED
565 582 ip-type ( shared | exclusive ) "all" >
566 583
|
↓ open down ↓ |
352 lines elided |
↑ open up ↑ |
567 584 <!--
568 585 brand
569 586
570 587 The toplevel container for a brand configuration.
571 588
572 589 Its attributes are
573 590
574 591 name The name of the brand. This must match the name of the
575 592 directory in which the configuration file is stored. -->
576 593
577 -<!ELEMENT brand (modname?, initname, restartinit?, login_cmd,
594 +<!ELEMENT brand (modname?, initname, restartinit?,
595 + restartinit0?, restartinitreboot?, login_cmd,
578 596 forcedlogin_cmd, user_cmd, install, installopts?,
579 597 boot?, sysboot?, halt?, shutdown?, verify_cfg?, verify_adm?,
580 598 postattach?, postclone?, postinstall?, predetach?, attach?,
581 599 detach?, clone?, presnap?, postsnap?, validatesnap?,
582 600 preuninstall?, uninstall?, prestatechange?,
583 601 poststatechange?, query?, privilege+)>
584 602
585 603 <!ATTLIST brand name CDATA #REQUIRED>
586 604
587 605
588 606
589 607 October 25, 2021 ()
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX