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