|
1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> |
|
2 <!-- |
|
3 CDDL HEADER START |
|
4 |
|
5 The contents of this file are subject to the terms of the |
|
6 Common Development and Distribution License (the "License"). |
|
7 You may not use this file except in compliance with the License. |
|
8 |
|
9 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE |
|
10 or http://www.opensolaris.org/os/licensing. |
|
11 See the License for the specific language governing permissions |
|
12 and limitations under the License. |
|
13 |
|
14 When distributing Covered Code, include this CDDL HEADER in each |
|
15 file and include the License file at usr/src/OPENSOLARIS.LICENSE. |
|
16 If applicable, add the following below this CDDL HEADER, with the |
|
17 fields enclosed by brackets "[]" replaced with your own identifying |
|
18 information: Portions Copyright [yyyy] [name of copyright owner] |
|
19 |
|
20 CDDL HEADER END |
|
21 |
|
22 Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved. |
|
23 --> |
|
24 |
|
25 <api xmlns="http://xmlns.oracle.com/radadr" |
|
26 name="com.oracle.solaris.rad.smf"> |
|
27 |
|
28 <doc> |
|
29 <para> |
|
30 This API exposes common SMF configuration, actions, and state to |
|
31 <strong>rad(1m)</strong> clients. |
|
32 </para> |
|
33 |
|
34 <para> |
|
35 Three core interfaces are provided: |
|
36 </para> |
|
37 |
|
38 <list type="ordered"> |
|
39 <item> |
|
40 <link interface="Master">Master</link> - a top-level object providing access |
|
41 to all services and instances on the system |
|
42 </item> |
|
43 <item> |
|
44 <link interface="Service">Service</link> - an object that represents an SMF |
|
45 service |
|
46 </item> |
|
47 <item> |
|
48 <link interface="Instance">Instance</link> - an object that represents an SMF |
|
49 instance |
|
50 </item> |
|
51 </list> |
|
52 |
|
53 <para> |
|
54 The latter two interfaces, <link interface="Service">Service</link> and <link |
|
55 interface="Instance">Instance</link>, are derived from a common <link |
|
56 interface="Entity">Entity</link> interface. |
|
57 </para> |
|
58 |
|
59 <heading> |
|
60 Python SMF wrapper |
|
61 </heading> |
|
62 |
|
63 <para> |
|
64 Provided alongside this API is a convenience wrapper around the |
|
65 Python bindings to this API. Accessible by importing |
|
66 <code>smf.rad</code> from within a Python application, this wrapper |
|
67 simplifies access to the <link interface="Master">Master</link>, <link |
|
68 interface="Service">Service</link>, and <link interface="Instance">Instance</link> |
|
69 objects. |
|
70 </para> |
|
71 |
|
72 <para> |
|
73 Run <code>/usr/bin/pydoc smf.rad</code> for more information. |
|
74 </para> |
|
75 </doc> |
|
76 |
|
77 <!-- Entity (service/instance common) definitions --> |
|
78 |
|
79 <enum name="DepGrouping"> |
|
80 <summary> |
|
81 indicates how dependencies are evaluated |
|
82 </summary> |
|
83 <value name="REQUIRE_ALL"> |
|
84 <summary> |
|
85 all dependencies must be satisfied |
|
86 </summary> |
|
87 </value> |
|
88 <value name="REQUIRE_ANY"> |
|
89 <summary> |
|
90 only one dependency must be satisfied |
|
91 </summary> |
|
92 </value> |
|
93 <value name="EXCLUDE_ALL"> |
|
94 <summary> |
|
95 no dependency may be satisfied |
|
96 </summary> |
|
97 </value> |
|
98 <value name="OPTIONAL_ALL"> |
|
99 <summary> |
|
100 all satisfiable dependencies must be satisfied |
|
101 </summary> |
|
102 </value> |
|
103 </enum> |
|
104 |
|
105 <enum name="DepRestart"> |
|
106 <summary> |
|
107 describes when the dependent should be restarted |
|
108 </summary> |
|
109 <value name="ERROR"> |
|
110 <summary> |
|
111 restart when a dependency encounters an error |
|
112 </summary> |
|
113 </value> |
|
114 <value name="RESTART"> |
|
115 <summary> |
|
116 restart any time a dependency restarts |
|
117 </summary> |
|
118 </value> |
|
119 <value name="REFRESH"> |
|
120 <summary> |
|
121 restart when a dependency is refreshed |
|
122 </summary> |
|
123 </value> |
|
124 <value name="NONE"> |
|
125 <summary> |
|
126 only process dependencies when starting instance |
|
127 </summary> |
|
128 </value> |
|
129 </enum> |
|
130 |
|
131 <struct name="Dependency"> |
|
132 <summary> |
|
133 describes a dependency group |
|
134 </summary> |
|
135 <doc> |
|
136 Fully describes a dependency group, including |
|
137 the FMRIs for the dependencies, the type of |
|
138 dependency, and when the dependency should be |
|
139 evaluated. |
|
140 </doc> |
|
141 <field type="string" name="name"> |
|
142 <summary> |
|
143 the name of the dependency group |
|
144 </summary> |
|
145 </field> |
|
146 <field name="target"> |
|
147 <summary> |
|
148 the list of dependencies' FMRIs |
|
149 </summary> |
|
150 <list type="string" /> |
|
151 </field> |
|
152 <field typeref="DepGrouping" name="grouping"> |
|
153 <summary> |
|
154 how the dependencies are evaluated |
|
155 </summary> |
|
156 </field> |
|
157 <field typeref="DepRestart" name="restartOn"> |
|
158 <summary> |
|
159 when the dependent should be restarted |
|
160 </summary> |
|
161 </field> |
|
162 </struct> |
|
163 |
|
164 <enum name="PropertyType"> |
|
165 <summary>an SMF property type</summary> |
|
166 <value name="UNKNOWN" value="0" /> <!-- INVALID --> |
|
167 <value name="BOOLEAN" /> |
|
168 <value name="COUNT" /> |
|
169 <value name="INTEGER" /> |
|
170 <value name="TIME" /> |
|
171 <value name="ASTRING" /> |
|
172 <value name="OPAQUE" /> |
|
173 <value name="USTRING" value="100" /> |
|
174 <value name="URI" value="200" /> |
|
175 <value name="FMRI" /> |
|
176 <value name="HOST" value="300" /> |
|
177 <value name="HOSTNAME" /> |
|
178 <value name="NET_ADDRESS_V4" /> |
|
179 <value name="NET_ADDRESS_V6" /> |
|
180 <value name="NET_ADDRESS" /> |
|
181 </enum> |
|
182 |
|
183 <struct name="Property"> |
|
184 <summary>an SMF property and its values</summary> |
|
185 <doc> |
|
186 Describes a property, its type, and all its values. |
|
187 </doc> |
|
188 <field type="string" name="name"> |
|
189 <summary>the name of the property</summary> |
|
190 </field> |
|
191 <field typeref="PropertyType" name="type"> |
|
192 <summary>the type of the property</summary> |
|
193 </field> |
|
194 <field name="values"> |
|
195 <summary>all the property's values</summary> |
|
196 <doc> |
|
197 A list of all the values held by the |
|
198 property. A single-valued property |
|
199 will have a list of length 1. A |
|
200 property with no values will have a |
|
201 list of length 0. |
|
202 </doc> |
|
203 <list type="string" /> |
|
204 </field> |
|
205 </struct> |
|
206 |
|
207 <struct name="Manpage"> |
|
208 <summary>a description of a man page</summary> |
|
209 <doc> |
|
210 Provides all the information needed to find a |
|
211 man page. The referenced man page can be |
|
212 displayed by running <code>MANPATH=$path man |
|
213 -s $section $title</code>. |
|
214 </doc> |
|
215 <field type="string" name="title"> |
|
216 <summary>the man page name</summary> |
|
217 </field> |
|
218 <field type="string" name="section"> |
|
219 <summary>the section the man page is found in</summary> |
|
220 </field> |
|
221 <field type="string" name="path" nullable="true"> |
|
222 <summary>the path the man page is found in</summary> |
|
223 <doc> |
|
224 The colon-separated <code>MANPATH</code> the |
|
225 man page is found in. If this field |
|
226 has no value, the default |
|
227 <code>MANPATH</code> should to be used. |
|
228 </doc> |
|
229 </field> |
|
230 </struct> |
|
231 |
|
232 <struct name="Doclink"> |
|
233 <summary>an on-line documentation link</summary> |
|
234 <field type="string" name="name"> |
|
235 <summary>an informative name for the document</summary> |
|
236 </field> |
|
237 <field type="string" name="uri"> |
|
238 <summary>the URI of the document</summary> |
|
239 </field> |
|
240 </struct> |
|
241 |
|
242 <struct name="PropertyGroup"> |
|
243 <summary>an SMF property group</summary> |
|
244 <field type="string" name="name"> |
|
245 <summary>the name of the property group</summary> |
|
246 </field> |
|
247 <field type="string" name="type"> |
|
248 <summary>the type of the property group</summary> |
|
249 </field> |
|
250 <field type="uinteger" name="flags"> |
|
251 <summary>the property group flags</summary> |
|
252 </field> |
|
253 </struct> |
|
254 |
|
255 <struct name="PGTemplate"> |
|
256 <summary>template data for a property group</summary> |
|
257 <field type="string" name="pgname"> |
|
258 <summary>the property group name</summary> |
|
259 </field> |
|
260 <field type="string" name="pgtype"> |
|
261 <summary>the property group type</summary> |
|
262 </field> |
|
263 <field type="boolean" name="required"> |
|
264 <summary>is the property group required?</summary> |
|
265 </field> |
|
266 <field type="string" name="name" nullable="true"> |
|
267 <summary>a localized name</summary> |
|
268 </field> |
|
269 <field type="string" name="description" nullable="true"> |
|
270 <summary>a localized description</summary> |
|
271 </field> |
|
272 </struct> |
|
273 |
|
274 <enum name="PropertyVisibility"> |
|
275 <summary>the recommended visibility of a property</summary> |
|
276 <value name="HIDDEN"> |
|
277 <summary>the property shouldn't be displayed</summary> |
|
278 </value> |
|
279 <value name="READONLY"> |
|
280 <summary> |
|
281 the property isn't intended to be modified |
|
282 </summary> |
|
283 </value> |
|
284 <value name="READWRITE"> |
|
285 <summary>the property is modifiable</summary> |
|
286 </value> |
|
287 </enum> |
|
288 |
|
289 <struct name="PropTemplate"> |
|
290 <summary>template data for a property</summary> |
|
291 <field type="string" name="propname"> |
|
292 <summary>the name of the property</summary> |
|
293 </field> |
|
294 <field typeref="PropertyType" name="proptype"> |
|
295 <summary>the type of the property</summary> |
|
296 </field> |
|
297 <field type="boolean" name="required"> |
|
298 <summary>is the property required?</summary> |
|
299 </field> |
|
300 <field type="string" name="name" nullable="true"> |
|
301 <summary>a localized name</summary> |
|
302 </field> |
|
303 <field type="string" name="description" nullable="true"> |
|
304 <summary>a localized description</summary> |
|
305 </field> |
|
306 <field type="string" name="units" nullable="true"> |
|
307 <summary>a localized units label</summary> |
|
308 </field> |
|
309 <field typeref="PropertyVisibility" name="visibility"> |
|
310 <summary>how the property should be presented</summary> |
|
311 </field> |
|
312 <field type="ulong" name="cardinality_min"> |
|
313 <summary>the minimum number of values</summary> |
|
314 </field> |
|
315 <field type="ulong" name="cardinality_max"> |
|
316 <summary>the maximum number of values</summary> |
|
317 </field> |
|
318 <field name="separators" nullable="true"> |
|
319 <summary>value separator characters</summary> |
|
320 <doc> |
|
321 Separator characters used to embed |
|
322 multiple values in a single property |
|
323 value. |
|
324 </doc> |
|
325 <list type="string" /> |
|
326 </field> |
|
327 <!-- XXX: Choices, constraints needed --> |
|
328 </struct> |
|
329 |
|
330 <struct name="PropChange"> |
|
331 <summary>a change to make to a property</summary> |
|
332 <field type="string" name="name"> |
|
333 <summary>the property to change</summary> |
|
334 </field> |
|
335 <field typeref="PropertyType" name="type"> |
|
336 <summary>the type of the property to write</summary> |
|
337 </field> |
|
338 <field name="values"> |
|
339 <summary>a list of values</summary> |
|
340 <list type="string" /> |
|
341 </field> |
|
342 </struct> |
|
343 |
|
344 <enum name="ErrorCode"> |
|
345 <summary>the general cause for failure</summary> |
|
346 <doc> |
|
347 Indicates the general cause for failure. |
|
348 Specific meanings are defined by the individual |
|
349 APIs. |
|
350 </doc> |
|
351 <value name="INTERNAL"> |
|
352 <summary>an internal error occurred</summary> |
|
353 </value> |
|
354 <value name="DENIED"> |
|
355 <summary>access denied</summary> |
|
356 </value> |
|
357 <value name="READONLY"> |
|
358 <summary>configuration database is read only</summary> |
|
359 </value> |
|
360 <value name="NOTFOUND"> |
|
361 <summary>named object wasn't found</summary> |
|
362 </value> |
|
363 <value name="EXISTS"> |
|
364 <summary>name is already in use</summary> |
|
365 </value> |
|
366 <value name="BADVALUE"> |
|
367 <summary>an illegal value was supplied</summary> |
|
368 </value> |
|
369 <value name="BADSTATE"> |
|
370 <summary>system was in an invalid state</summary> |
|
371 </value> |
|
372 <value name="INVALID"> |
|
373 <summary>API was called incorrectly</summary> |
|
374 </value> |
|
375 </enum> |
|
376 |
|
377 <enum name="ErrorTarget"> |
|
378 <value name="NONE" /> |
|
379 <value name="SNAPSHOT" /> |
|
380 <value name="PROPERTYGROUP" /> |
|
381 <value name="PROPERTY" /> |
|
382 <value name="VALUE" /> |
|
383 </enum> |
|
384 |
|
385 <struct name="SmfError"> |
|
386 <field typeref="ErrorCode" name="error" /> |
|
387 <field typeref="ErrorTarget" name="target" /> |
|
388 <field type="string" name="aux" nullable="true" /> |
|
389 <field type="string" name="message" nullable="true" /> |
|
390 </struct> |
|
391 |
|
392 <interface name="Entity"> |
|
393 <summary> |
|
394 functionality common to services and instances |
|
395 </summary> |
|
396 |
|
397 <property type="string" name="fmri" access="ro"> |
|
398 <summary> |
|
399 the service/instance's FMRI |
|
400 </summary> |
|
401 </property> |
|
402 |
|
403 <property type="string" name="scope" access="ro"> |
|
404 <summary> |
|
405 the service/instance's scope |
|
406 </summary> |
|
407 </property> |
|
408 |
|
409 <property type="string" name="service" access="ro"> |
|
410 <summary> |
|
411 the service name of the service/instance |
|
412 </summary> |
|
413 </property> |
|
414 |
|
415 <property name="dependencies" access="ro"> |
|
416 <summary> |
|
417 the service/instance's dependencies |
|
418 </summary> |
|
419 <doc> |
|
420 A list of dependency objects describing |
|
421 the full nature of each dependency. An |
|
422 empty list is returned if there are no |
|
423 dependencies. |
|
424 </doc> |
|
425 <list typeref="Dependency" /> |
|
426 <error typeref="SmfError"> |
|
427 <doc> |
|
428 An internal SMF error occurred. |
|
429 </doc> |
|
430 </error> |
|
431 </property> |
|
432 |
|
433 <property name="manpages" access="ro"> |
|
434 <summary> |
|
435 the service/instance's manual pages |
|
436 </summary> |
|
437 <doc> |
|
438 A list of manual page objects |
|
439 describing the name, section, and path |
|
440 of each relevant manual page. An empty |
|
441 list is returned if no manual pages are |
|
442 defined. |
|
443 </doc> |
|
444 <list typeref="Manpage" /> |
|
445 <error typeref="SmfError"> |
|
446 <doc> |
|
447 An internal SMF error occurred. |
|
448 </doc> |
|
449 </error> |
|
450 </property> |
|
451 |
|
452 <property name="doclinks" access="ro"> |
|
453 <summary> |
|
454 documentation links |
|
455 </summary> |
|
456 <doc> |
|
457 A list of links to on-line |
|
458 documentation for the |
|
459 service/instance. An empty list is |
|
460 returned if no on-line documents are |
|
461 defined. |
|
462 </doc> |
|
463 <list typeref="Doclink" /> |
|
464 <error typeref="SmfError"> |
|
465 <doc> |
|
466 An internal SMF error occurred. |
|
467 </doc> |
|
468 </error> |
|
469 </property> |
|
470 |
|
471 <property name="pgs" access="ro"> |
|
472 <summary> |
|
473 directly-attached property groups |
|
474 </summary> |
|
475 <doc> |
|
476 A list of all directly-attached |
|
477 property groups, including name, |
|
478 type and flags for each. |
|
479 </doc> |
|
480 <list typeref="PropertyGroup" /> |
|
481 <error typeref="SmfError"> |
|
482 <doc> |
|
483 An internal SMF error occurred. |
|
484 </doc> |
|
485 </error> |
|
486 </property> |
|
487 |
|
488 <method name="delete"> |
|
489 <summary> |
|
490 delete the service/instance |
|
491 </summary> |
|
492 <doc> |
|
493 Delete the service or instance. |
|
494 </doc> |
|
495 <error typeref="SmfError"> |
|
496 <doc> |
|
497 <para> |
|
498 Failed to delete the service or |
|
499 instance. Cause: |
|
500 </para> |
|
501 <list> |
|
502 <item><code>INTERNAL</code> - |
|
503 an internal error occurred |
|
504 </item> |
|
505 <item><code>DENIED</code> - |
|
506 insufficient authorization |
|
507 </item> |
|
508 <item><code>READONLY</code> - |
|
509 the repository is read-only |
|
510 </item> |
|
511 <item><code>EXISTS</code> - |
|
512 delete was called on a service |
|
513 and the service still had |
|
514 instances |
|
515 </item> |
|
516 </list> |
|
517 </doc> |
|
518 </error> |
|
519 </method> |
|
520 |
|
521 <method name="deleteCust"> |
|
522 <summary> |
|
523 delete administrative customizations |
|
524 </summary> |
|
525 <doc> |
|
526 Delete all administrative customizations |
|
527 applied to a service/instance and its |
|
528 children, if any exist. |
|
529 </doc> |
|
530 <error typeref="SmfError"> |
|
531 <doc> |
|
532 <para> |
|
533 Failed to delete the administrative |
|
534 customizations applied to a service or |
|
535 instance. Cause: |
|
536 </para> |
|
537 <list> |
|
538 <item><code>INTERNAL</code> - |
|
539 an internal error occurred |
|
540 </item> |
|
541 <item><code>DENIED</code> - |
|
542 insufficient authorization |
|
543 </item> |
|
544 <item><code>READONLY</code> - |
|
545 the repository is read-only |
|
546 </item> |
|
547 </list> |
|
548 </doc> |
|
549 </error> |
|
550 </method> |
|
551 |
|
552 <method name="createPG"> |
|
553 <summary> |
|
554 create a property group |
|
555 </summary> |
|
556 <doc> |
|
557 Create a property group on the |
|
558 service/instance. |
|
559 </doc> |
|
560 <error typeref="SmfError"> |
|
561 <doc> |
|
562 <para> |
|
563 Failed to create the property |
|
564 group. Cause: |
|
565 </para> |
|
566 <list> |
|
567 <item><code>INTERNAL</code> - |
|
568 an internal error occurred |
|
569 </item> |
|
570 <item><code>DENIED</code> - |
|
571 insufficient authorization |
|
572 </item> |
|
573 <item><code>READONLY</code> - |
|
574 the repository is read-only |
|
575 </item> |
|
576 <item><code>EXISTS</code> - |
|
577 the propery group already exists |
|
578 </item> |
|
579 <item><code>BADVALUE</code> - |
|
580 an invalid property group name |
|
581 or type was specified |
|
582 </item> |
|
583 </list> |
|
584 </doc> |
|
585 </error> |
|
586 <argument type="string" name="pg_name"> |
|
587 <summary> |
|
588 the name of the new property group |
|
589 </summary> |
|
590 </argument> |
|
591 <argument type="string" name="pg_type"> |
|
592 <summary> |
|
593 the type of the new property group |
|
594 </summary> |
|
595 </argument> |
|
596 <argument type="uinteger" name="pg_flags"> |
|
597 <summary> |
|
598 the property group flags |
|
599 </summary> |
|
600 </argument> |
|
601 </method> |
|
602 |
|
603 <method name="deletePG"> |
|
604 <summary> |
|
605 delete a property group |
|
606 </summary> |
|
607 <doc> |
|
608 Delete a directly-attached property |
|
609 group and all its properties from the |
|
610 service/instance. |
|
611 </doc> |
|
612 <error typeref="SmfError"> |
|
613 <doc> |
|
614 <para> |
|
615 Failed to delete the property |
|
616 group. Cause: |
|
617 </para> |
|
618 <list> |
|
619 <item><code>INTERNAL</code> - |
|
620 an internal error occurred |
|
621 </item> |
|
622 <item><code>DENIED</code> - |
|
623 insufficient authorization |
|
624 </item> |
|
625 <item><code>READONLY</code> - |
|
626 the repository is read-only |
|
627 </item> |
|
628 <item><code>NOTFOUND</code> - |
|
629 the property group doesn't exist |
|
630 </item> |
|
631 </list> |
|
632 </doc> |
|
633 </error> |
|
634 <argument type="string" name="pg_name"> |
|
635 <summary> |
|
636 the name of the property group |
|
637 </summary> |
|
638 </argument> |
|
639 </method> |
|
640 |
|
641 <method name="deletePGCust"> |
|
642 <summary> |
|
643 delete administrative customizations |
|
644 </summary> |
|
645 <doc> |
|
646 Delete all administrative customizations |
|
647 applied to a property group and its children, |
|
648 if any exist. |
|
649 </doc> |
|
650 <error typeref="SmfError"> |
|
651 <doc> |
|
652 <para> |
|
653 Failed to delete the administrative customizations |
|
654 applied to a property group. Cause: |
|
655 </para> |
|
656 <list> |
|
657 <item><code>INTERNAL</code> - |
|
658 an internal error occurred |
|
659 </item> |
|
660 <item><code>DENIED</code> - |
|
661 insufficient authorization |
|
662 </item> |
|
663 <item><code>READONLY</code> - |
|
664 the repository is read-only |
|
665 </item> |
|
666 <item><code>NOTFOUND</code> - |
|
667 the property group doesn't |
|
668 exist |
|
669 </item> |
|
670 </list> |
|
671 </doc> |
|
672 </error> |
|
673 <argument type="string" name="pg_name"> |
|
674 <summary> |
|
675 the name of the property group |
|
676 </summary> |
|
677 </argument> |
|
678 </method> |
|
679 |
|
680 <method name="readProperties"> |
|
681 <summary> |
|
682 reads all properties in a directly-attached |
|
683 property group |
|
684 </summary> |
|
685 <doc> |
|
686 Read all properties in the specified |
|
687 directly-attached property group. The |
|
688 name, type, and values of each property |
|
689 are included. |
|
690 </doc> |
|
691 <result> |
|
692 <summary> |
|
693 a list of properties in the |
|
694 specified directly-attached |
|
695 property group |
|
696 </summary> |
|
697 <list typeref="Property" /> |
|
698 </result> |
|
699 <error typeref="SmfError"> |
|
700 <doc> |
|
701 <para> |
|
702 Failed to read properties from |
|
703 the property group. Cause: |
|
704 </para> |
|
705 <list> |
|
706 <item><code>INTERNAL</code> - |
|
707 an internal error occurred |
|
708 </item> |
|
709 <item><code>DENIED</code> - |
|
710 insufficient authorization |
|
711 </item> |
|
712 <item><code>NOTFOUND</code> - |
|
713 the property group doesn't exist |
|
714 </item> |
|
715 </list> |
|
716 </doc> |
|
717 </error> |
|
718 <argument type="string" name="pg_name"> |
|
719 <summary> |
|
720 the name of the property group |
|
721 </summary> |
|
722 </argument> |
|
723 </method> |
|
724 |
|
725 <method name="writeProperties"> |
|
726 <summary> |
|
727 commit a list of property changes to a |
|
728 property group |
|
729 </summary> |
|
730 <doc> |
|
731 <para> |
|
732 Commit a set of property changes to |
|
733 the specified property group. Each |
|
734 property change specifies a property, |
|
735 type, and optional set of values. If |
|
736 the property specified by a property |
|
737 change doesn't exist prior to the call, |
|
738 it will be created by the call. If the |
|
739 property specified by a property change |
|
740 exists prior to the call but has a |
|
741 different type, its type will be set to |
|
742 the type specified by the call. |
|
743 </para> |
|
744 <para> |
|
745 If the call succeeds, all the requested |
|
746 property changes were made. If the |
|
747 call fails, none of the requested |
|
748 changes were made. |
|
749 </para> |
|
750 </doc> |
|
751 <error typeref="SmfError"> |
|
752 <doc> |
|
753 <para> |
|
754 Failed to make all the |
|
755 requested property changes. |
|
756 Cause: |
|
757 </para> |
|
758 <list> |
|
759 <item><code>INTERNAL</code> - |
|
760 an internal error occurred |
|
761 </item> |
|
762 <item><code>DENIED</code> - |
|
763 insufficient authorization |
|
764 </item> |
|
765 <item><code>READONLY</code> - |
|
766 the repository is read-only |
|
767 </item> |
|
768 <item><code>NOTFOUND</code> - |
|
769 the property group doesn't |
|
770 exist (see target) |
|
771 </item> |
|
772 <item><code>BADVALUE</code> - |
|
773 a property had an invalid name, |
|
774 or a value couldn't be |
|
775 converted to the requested type |
|
776 (see target, aux) |
|
777 </item> |
|
778 <item><code>INVALID</code> - |
|
779 the same property was |
|
780 referenced by two |
|
781 <code>PropertyChange</code>s. |
|
782 </item> |
|
783 </list> |
|
784 <para> |
|
785 When an invidual property is |
|
786 the cause of the error, its |
|
787 name will be returned in |
|
788 <code>aux</code>. |
|
789 </para> |
|
790 </doc> |
|
791 </error> |
|
792 <argument type="string" name="pg_name"> |
|
793 <summary> |
|
794 the name of the property group |
|
795 </summary> |
|
796 </argument> |
|
797 <argument name="props"> |
|
798 <summary> |
|
799 the set of changes to apply |
|
800 </summary> |
|
801 <list typeref="PropChange" /> |
|
802 </argument> |
|
803 </method> |
|
804 |
|
805 <method name="readProperty"> |
|
806 <summary> |
|
807 read a single directly-attached property's |
|
808 values |
|
809 </summary> |
|
810 <doc> |
|
811 Read a single property from the |
|
812 specified directly-attached property |
|
813 group. The result includes the name, |
|
814 type, and values of the property. |
|
815 </doc> |
|
816 <result typeref="Property"> |
|
817 <summary> |
|
818 the specified property |
|
819 </summary> |
|
820 </result> |
|
821 <error typeref="SmfError"> |
|
822 <doc> |
|
823 <para> |
|
824 Failed to read the specified |
|
825 property. Cause: |
|
826 </para> |
|
827 <list> |
|
828 <item><code>INTERNAL</code> - |
|
829 an internal error occurred |
|
830 </item> |
|
831 <item><code>DENIED</code> - |
|
832 insufficient authorization |
|
833 </item> |
|
834 <item><code>NOTFOUND</code> - |
|
835 the property or property group |
|
836 doesn't exist (see target) |
|
837 </item> |
|
838 </list> |
|
839 </doc> |
|
840 </error> |
|
841 <argument type="string" name="pg_name"> |
|
842 <summary> |
|
843 the name of the property group |
|
844 </summary> |
|
845 </argument> |
|
846 <argument type="string" name="prop_name"> |
|
847 <summary> |
|
848 the name of the property |
|
849 </summary> |
|
850 </argument> |
|
851 </method> |
|
852 |
|
853 <method name="writeProperty"> |
|
854 <summary> |
|
855 writes a list of values to a property |
|
856 </summary> |
|
857 <doc> |
|
858 <para> |
|
859 Change the specified property. If the |
|
860 property doesn't exist prior to the |
|
861 call, it will be created by the call. |
|
862 If the property exists prior to the |
|
863 call but has a different type, its |
|
864 type will be set to the type |
|
865 specified by the call. |
|
866 </para> |
|
867 </doc> |
|
868 <error typeref="SmfError"> |
|
869 <doc> |
|
870 <para> |
|
871 Failed to make the requested |
|
872 property change. Cause: |
|
873 </para> |
|
874 <list> |
|
875 <item><code>INTERNAL</code> - |
|
876 an internal error occurred |
|
877 </item> |
|
878 <item><code>DENIED</code> - |
|
879 insufficient authorization |
|
880 </item> |
|
881 <item><code>READONLY</code> - |
|
882 the repository is read-only |
|
883 </item> |
|
884 <item><code>NOTFOUND</code> - |
|
885 the property group doesn't |
|
886 exist (see target) |
|
887 </item> |
|
888 <item><code>BADVALUE</code> - |
|
889 the property had an invalid |
|
890 name, or a value couldn't be |
|
891 converted to the requested type |
|
892 (see target) |
|
893 </item> |
|
894 </list> |
|
895 </doc> |
|
896 </error> |
|
897 <argument type="string" name="pg_name"> |
|
898 <summary> |
|
899 the name of the property group |
|
900 </summary> |
|
901 </argument> |
|
902 <argument type="string" name="prop_name"> |
|
903 <summary> |
|
904 the name of the property |
|
905 </summary> |
|
906 </argument> |
|
907 <argument typeref="PropertyType" name="prop_type"> |
|
908 <summary> |
|
909 the type of the property |
|
910 </summary> |
|
911 </argument> |
|
912 <argument name="values"> |
|
913 <summary> |
|
914 the new values for the property |
|
915 </summary> |
|
916 <list type="string" /> |
|
917 </argument> |
|
918 </method> |
|
919 |
|
920 <method name="deleteProperty"> |
|
921 <summary> |
|
922 delete a property |
|
923 </summary> |
|
924 <doc> |
|
925 <para> |
|
926 Delete a property from the service/instance. |
|
927 </para> |
|
928 </doc> |
|
929 <error typeref="SmfError"> |
|
930 <doc> |
|
931 <para> |
|
932 Failed to delete the property. |
|
933 Cause: |
|
934 </para> |
|
935 <list> |
|
936 <item><code>INTERNAL</code> - |
|
937 an internal error occurred |
|
938 </item> |
|
939 <item><code>DENIED</code> - |
|
940 insufficient authorization |
|
941 </item> |
|
942 <item><code>READONLY</code> - |
|
943 the repository is read-only |
|
944 </item> |
|
945 <item><code>NOTFOUND</code> - |
|
946 the property group doesn't |
|
947 exist, or the property to |
|
948 be deleted doesn't exist (see |
|
949 target) |
|
950 </item> |
|
951 <item><code>BADVALUE</code> - |
|
952 the property had an invalid |
|
953 name or type (see target) |
|
954 </item> |
|
955 <item><code>INVALID</code> - |
|
956 the property cannot be deleted |
|
957 while in use (see target) |
|
958 </item> |
|
959 </list> |
|
960 </doc> |
|
961 </error> |
|
962 <argument type="string" name="pg_name"> |
|
963 <summary> |
|
964 the name of the property group |
|
965 </summary> |
|
966 </argument> |
|
967 <argument type="string" name="prop_name"> |
|
968 <summary> |
|
969 the name of the property |
|
970 </summary> |
|
971 </argument> |
|
972 </method> |
|
973 |
|
974 <method name="deletePropertyCust"> |
|
975 <summary> |
|
976 delete administrative customizations |
|
977 </summary> |
|
978 <doc> |
|
979 Delete all administrative customizations |
|
980 applied to this property. |
|
981 </doc> |
|
982 <error typeref="SmfError"> |
|
983 <doc> |
|
984 <para> |
|
985 Failed to delete the administrative customizations |
|
986 applied to this property. Cause: |
|
987 </para> |
|
988 <list> |
|
989 <item><code>INTERNAL</code> - |
|
990 an internal error occurred |
|
991 </item> |
|
992 <item><code>DENIED</code> - |
|
993 insufficient authorization |
|
994 </item> |
|
995 <item><code>READONLY</code> - |
|
996 the repository is read-only |
|
997 </item> |
|
998 <item><code>NOTFOUND</code> - |
|
999 the property group, or property |
|
1000 doesn't exist (see target) |
|
1001 </item> |
|
1002 </list> |
|
1003 </doc> |
|
1004 </error> |
|
1005 <argument type="string" name="pg_name"> |
|
1006 <summary> |
|
1007 the name of the property group |
|
1008 </summary> |
|
1009 </argument> |
|
1010 <argument type="string" name="prop_name"> |
|
1011 <summary> |
|
1012 the name of the property |
|
1013 </summary> |
|
1014 </argument> |
|
1015 </method> |
|
1016 |
|
1017 <method name="getCommonName"> |
|
1018 <summary> |
|
1019 obtain the service/instance's localized |
|
1020 common name |
|
1021 </summary> |
|
1022 <doc> |
|
1023 Obtain the localized common name for the |
|
1024 service/instance, if one exists. If a |
|
1025 common name doesn't exist for the |
|
1026 specified locale, attempts to return |
|
1027 the common name for the "C" locale |
|
1028 instead. |
|
1029 </doc> |
|
1030 <result type="string" nullable="true"> |
|
1031 <summary> |
|
1032 the common name if available, or null |
|
1033 </summary> |
|
1034 </result> |
|
1035 <error typeref="SmfError"> |
|
1036 <doc> |
|
1037 An internal error occurred. |
|
1038 </doc> |
|
1039 </error> |
|
1040 <argument type="string" name="locale"> |
|
1041 <summary> |
|
1042 the desired locale |
|
1043 </summary> |
|
1044 </argument> |
|
1045 </method> |
|
1046 |
|
1047 <method name="getDescription"> |
|
1048 <summary> |
|
1049 obtain the service/instance's localized |
|
1050 description |
|
1051 </summary> |
|
1052 <doc> |
|
1053 Obtain the localized description for |
|
1054 the service/instance, if one exists. |
|
1055 If a description doesn't exist for the |
|
1056 specified locale, attempts to return |
|
1057 the description for the "C" locale |
|
1058 instead. |
|
1059 </doc> |
|
1060 <result type="string" nullable="true"> |
|
1061 <summary> |
|
1062 the description if available, or null |
|
1063 </summary> |
|
1064 </result> |
|
1065 <error typeref="SmfError"> |
|
1066 <doc> |
|
1067 An internal error occurred. |
|
1068 </doc> |
|
1069 </error> |
|
1070 <argument type="string" name="locale"> |
|
1071 <summary> |
|
1072 the desired locale |
|
1073 </summary> |
|
1074 </argument> |
|
1075 </method> |
|
1076 |
|
1077 <method name="getPGTemplates"> |
|
1078 <summary> |
|
1079 obtain all property group templates |
|
1080 </summary> |
|
1081 <doc> |
|
1082 Obtain all property group templates |
|
1083 for this service/instance. If |
|
1084 templates aren't provided for the |
|
1085 specified locale, attempts to return |
|
1086 the templates for the "C" locale |
|
1087 instead. |
|
1088 </doc> |
|
1089 <result> |
|
1090 <summary> |
|
1091 all available property group templates |
|
1092 </summary> |
|
1093 <list typeref="PGTemplate" /> |
|
1094 </result> |
|
1095 <error typeref="SmfError"> |
|
1096 <doc> |
|
1097 An internal error occurred. |
|
1098 </doc> |
|
1099 </error> |
|
1100 <argument type="string" name="locale"> |
|
1101 <summary> |
|
1102 the desired locale |
|
1103 </summary> |
|
1104 </argument> |
|
1105 </method> |
|
1106 |
|
1107 <method name="getPropTemplates"> |
|
1108 <summary> |
|
1109 obtain all property templates for a |
|
1110 property group |
|
1111 </summary> |
|
1112 <doc> |
|
1113 Obtain all property templates for the |
|
1114 specified property group of this |
|
1115 service/instance. If property |
|
1116 templates aren't provided for the |
|
1117 specified locale, attempts to return |
|
1118 the templates for the "C" locale |
|
1119 instead. If no templates exist for |
|
1120 properties of the specified property |
|
1121 group, an empty list is returned. |
|
1122 </doc> |
|
1123 <result> |
|
1124 <summary> |
|
1125 all available property templates |
|
1126 </summary> |
|
1127 <list typeref="PropTemplate" /> |
|
1128 </result> |
|
1129 <error typeref="SmfError"> |
|
1130 <doc> |
|
1131 An internal error occurred. |
|
1132 </doc> |
|
1133 </error> |
|
1134 <argument type="string" name="pg_name"> |
|
1135 <summary> |
|
1136 the name of the property group |
|
1137 </summary> |
|
1138 </argument> |
|
1139 <argument type="string" name="pg_type"> |
|
1140 <summary> |
|
1141 the type of the property group |
|
1142 </summary> |
|
1143 </argument> |
|
1144 <argument type="string" name="locale"> |
|
1145 <summary> |
|
1146 the desired locale |
|
1147 </summary> |
|
1148 </argument> |
|
1149 </method> |
|
1150 </interface> |
|
1151 |
|
1152 |
|
1153 <!-- Service definitions --> |
|
1154 |
|
1155 <interface name="Service"> |
|
1156 <summary>an SMF service object</summary> |
|
1157 |
|
1158 <doc> |
|
1159 <para> |
|
1160 The <code>Service</code> interface is an <link interface="Entity">Entity</link> that |
|
1161 represents an SMF service. Handles to this type of object can be |
|
1162 retrieved from the RAD server using an object name built with: |
|
1163 </para> |
|
1164 |
|
1165 <list type="ordered"> |
|
1166 <item> |
|
1167 the "<code>com.oracle.solaris.rad.smf</code>" domain name |
|
1168 </item> |
|
1169 <item> |
|
1170 a key named "<code>type</code>" paired with a value of |
|
1171 "<code>Service</code>" |
|
1172 </item> |
|
1173 <item> |
|
1174 a key named "<code>service</code>" paired with the service portion of |
|
1175 an SMF FMRI |
|
1176 </item> |
|
1177 </list> |
|
1178 |
|
1179 <para> |
|
1180 Object names for services can be pulled from the <link |
|
1181 struct="Service">Service</link>s exposed by the <link interface="Master" |
|
1182 property="services">Master.services</link> property. Or, they can be |
|
1183 built directly: |
|
1184 </para> |
|
1185 |
|
1186 <example caption="Service interface (Python)"> |
|
1187 import rad.client |
|
1188 import rad.util |
|
1189 |
|
1190 # Create a connection |
|
1191 radconn = rad.util.connect_unix() |
|
1192 |
|
1193 # Retrieve a particular service |
|
1194 service_name = rad.client.Name("<strong>com.oracle.solaris.rad.smf</strong>", |
|
1195 [("<strong>type</strong>", "<strong>Service</strong>"), ("<strong>service</strong>", "network/physical")]) |
|
1196 # Get a native-looking python object that throws RAD exceptions |
|
1197 service = radconn.get_object(service_name) |
|
1198 |
|
1199 # Do something with our service |
|
1200 print "service %s has %d instances" % (service.fmri, len(service.instances))</example> |
|
1201 |
|
1202 <para> |
|
1203 If using the Python SMF convenience wrapper delivered with this |
|
1204 API, this can be simplified to: |
|
1205 </para> |
|
1206 |
|
1207 <example caption="Service interface (Python, SMF wrapper)"> |
|
1208 import smf.rad |
|
1209 |
|
1210 repo = smf.rad.Repository() |
|
1211 |
|
1212 # Retrieve a particular service |
|
1213 service = repo.lookup_byfmri("svc:/network/physical") |
|
1214 |
|
1215 # Do something with our service |
|
1216 print "service %s has %d instances" % (service.fmri, len(service.instances))</example> |
|
1217 </doc> |
|
1218 |
|
1219 <version major="1" minor="0" stability="private" /> |
|
1220 <include typeref="Entity" /> |
|
1221 |
|
1222 <property name="instances" access="ro"> |
|
1223 <summary> |
|
1224 the list of instances of this service |
|
1225 </summary> |
|
1226 <doc> |
|
1227 The list of instances of this service. |
|
1228 An empty list if the service has no |
|
1229 instances. |
|
1230 </doc> |
|
1231 <list type="string" /> |
|
1232 <error typeref="SmfError"> |
|
1233 <doc> |
|
1234 An internal SMF error occurred. |
|
1235 </doc> |
|
1236 </error> |
|
1237 </property> |
|
1238 </interface> |
|
1239 |
|
1240 |
|
1241 <!-- Instance definitions --> |
|
1242 |
|
1243 <enum name="SMFState"> |
|
1244 <summary> |
|
1245 the state of an SMF instance |
|
1246 </summary> |
|
1247 <value name="NONE" /> |
|
1248 <value name="UNINIT" /> |
|
1249 <value name="MAINT" /> |
|
1250 <value name="OFFLINE" /> |
|
1251 <value name="DISABLED" /> |
|
1252 <value name="ONLINE" /> |
|
1253 <value name="DEGRADED" /> |
|
1254 <value name="LEGACY" /> |
|
1255 </enum> |
|
1256 |
|
1257 <struct name="ExtendedState"> |
|
1258 <!-- Includes state for atomicity --> |
|
1259 <summary> |
|
1260 extended instance state information |
|
1261 </summary> |
|
1262 <field typeref="SMFState" name="state"> |
|
1263 <summary>the current state of the instance</summary> |
|
1264 </field> |
|
1265 <field typeref="SMFState" name="nextState"> |
|
1266 <summary>the next state of the instance</summary> |
|
1267 </field> |
|
1268 <field type="string" name="auxstate" nullable="true"> |
|
1269 <summary>the auxiliary state of the instance</summary> |
|
1270 </field> |
|
1271 <field type="time" name="stime"> |
|
1272 <summary>the time of last state change</summary> |
|
1273 </field> |
|
1274 <field type="integer" name="contractid"> |
|
1275 <summary>the contract ID, or -1 if none</summary> |
|
1276 </field> |
|
1277 <field type="boolean" name="enabled"> |
|
1278 <summary>is the instance enabled?</summary> |
|
1279 </field> |
|
1280 <field type="boolean" name="enabled_temp"> |
|
1281 <summary>is the instance enabled temporarily?</summary> |
|
1282 <doc> |
|
1283 Indicates if the instance is enabled |
|
1284 temporarily. If the instance isn't |
|
1285 enabled or disable temporarily, this |
|
1286 mirrors the value of enabled. |
|
1287 </doc> |
|
1288 </field> |
|
1289 </struct> |
|
1290 |
|
1291 <struct name="LogInfo"> |
|
1292 <summary>instance log data</summary> |
|
1293 <field type="string" name="name"> |
|
1294 <summary>the log file's name</summary> |
|
1295 </field> |
|
1296 <field type="integer" name="size"> |
|
1297 <summary>the log file's size</summary> |
|
1298 </field> |
|
1299 <field type="time" name="MTime"> |
|
1300 <summary>the log file's modification time</summary> |
|
1301 </field> |
|
1302 <field type="opaque" name="contents"> |
|
1303 <summary>log file contents</summary> |
|
1304 </field> |
|
1305 </struct> |
|
1306 |
|
1307 <interface name="Instance"> |
|
1308 <summary>an SMF instance object</summary> |
|
1309 |
|
1310 <doc> |
|
1311 <para> |
|
1312 The <code>Instance</code> interface is an <link interface="Entity">Entity</link> |
|
1313 that represents an SMF instance. Handles to this type of object can be |
|
1314 retrieved from the RAD server using an object name built with: |
|
1315 </para> |
|
1316 |
|
1317 <list type="ordered"> |
|
1318 <item> |
|
1319 the "<code>com.oracle.solaris.rad.smf</code>" domain name |
|
1320 </item> |
|
1321 <item> |
|
1322 a key named "<code>type</code>" paired with a value of |
|
1323 "<code>Instance</code>" |
|
1324 </item> |
|
1325 <item> |
|
1326 a key named "<code>service</code>" paired with the service portion of |
|
1327 an SMF FMRI |
|
1328 </item> |
|
1329 <item> |
|
1330 a key named "<code>instance</code>" paired with the instance portion of |
|
1331 an SMF FMRI |
|
1332 </item> |
|
1333 </list> |
|
1334 |
|
1335 <para> |
|
1336 Object names for instances can be pulled from the <link |
|
1337 struct="Instance">Instance</link>s exposed by the <link interface="Master" |
|
1338 property="instances">Master.instances</link> property. Or, they can be |
|
1339 built directly: |
|
1340 </para> |
|
1341 |
|
1342 <example caption="Instance interface (Python)"> |
|
1343 import rad.client |
|
1344 import rad.util |
|
1345 |
|
1346 # Create a connection |
|
1347 radconn = rad.util.connect_unix() |
|
1348 |
|
1349 # Retrieve a particular instance |
|
1350 instance_name = rad.client.Name("<strong>com.oracle.solaris.rad.smf</strong>", |
|
1351 [("<strong>type</strong>", "<strong>Instance</strong>"), ("<strong>service</strong>", "network/physical"), |
|
1352 ("<strong>instance</strong>", "default")]) |
|
1353 # Get a native-looking python object that throws RAD exceptions |
|
1354 instance = radconn.get_object(instance_name) |
|
1355 |
|
1356 # Do something with our instance |
|
1357 print "instance %s state: %s" % (instance.fmri, instance.state)</example> |
|
1358 |
|
1359 <para> |
|
1360 If using the Python SMF convenience wrapper delivered with this |
|
1361 API, this can be simplified to: |
|
1362 </para> |
|
1363 |
|
1364 <example caption="Instance interface (Python, SMF wrapper)"> |
|
1365 import smf.rad |
|
1366 |
|
1367 repo = smf.rad.Repository() |
|
1368 |
|
1369 # Retrieve a particular instance |
|
1370 instance = repo.lookup_byfmri("svc:/network/physical:default") |
|
1371 |
|
1372 # Do something with our instance |
|
1373 print "instance %s state: %s" % (instance.fmri, instance.state)</example> |
|
1374 </doc> |
|
1375 |
|
1376 <version major="1" minor="0" stability="private" /> |
|
1377 <include typeref="Entity" /> |
|
1378 |
|
1379 <property type="string" name="instance" access="ro"> |
|
1380 <summary>the name of the instance</summary> |
|
1381 </property> |
|
1382 <property type="string" name="restarter" access="ro"> |
|
1383 <summary>the fmri of the instance's restarter</summary> |
|
1384 <error typeref="SmfError"> |
|
1385 <doc> |
|
1386 An internal SMF error occurred. |
|
1387 </doc> |
|
1388 </error> |
|
1389 </property> |
|
1390 <property type="boolean" name="enabled" access="ro"> |
|
1391 <summary>is the instance effectively enabled?</summary> |
|
1392 <error typeref="SmfError"> |
|
1393 <doc> |
|
1394 An internal SMF error occurred. |
|
1395 </doc> |
|
1396 </error> |
|
1397 </property> |
|
1398 <property typeref="SMFState" name="state" access="ro"> |
|
1399 <summary>the current state of the instance</summary> |
|
1400 <error typeref="SmfError"> |
|
1401 <doc> |
|
1402 An internal SMF error occurred. |
|
1403 </doc> |
|
1404 </error> |
|
1405 </property> |
|
1406 <property typeref="ExtendedState" name="ex_state" access="ro"> |
|
1407 <summary>the extended state of the instance</summary> |
|
1408 <error typeref="SmfError"> |
|
1409 <doc> |
|
1410 An internal SMF error occurred. |
|
1411 </doc> |
|
1412 </error> |
|
1413 </property> |
|
1414 <property name="snapshots" access="ro"> |
|
1415 <summary>a list of the instance's snapshots</summary> |
|
1416 <list type="string" /> |
|
1417 <error typeref="SmfError"> |
|
1418 <doc> |
|
1419 An internal SMF error occurred. |
|
1420 </doc> |
|
1421 </error> |
|
1422 </property> |
|
1423 |
|
1424 <method name="readSnapshotPGs"> |
|
1425 <summary> |
|
1426 read all property groups in the |
|
1427 composed view of the specified snapshot |
|
1428 </summary> |
|
1429 <result> |
|
1430 <list typeref="PropertyGroup" /> |
|
1431 </result> |
|
1432 <error typeref="SmfError"> |
|
1433 <doc> |
|
1434 <para> |
|
1435 Failed to read the list of |
|
1436 property groups. Cause: |
|
1437 </para> |
|
1438 <list> |
|
1439 <item><code>INTERNAL</code> - |
|
1440 an internal error occurred |
|
1441 </item> |
|
1442 <item><code>NOTFOUND</code> - |
|
1443 the snapshot doesn't exist |
|
1444 </item> |
|
1445 </list> |
|
1446 </doc> |
|
1447 </error> |
|
1448 <argument type="string" name="snap_name" nullable="true"> |
|
1449 <summary> |
|
1450 the name of the snapshot, or null for the running snapshot |
|
1451 </summary> |
|
1452 </argument> |
|
1453 </method> |
|
1454 |
|
1455 <method name="readSnapshotProperties"> |
|
1456 <summary> |
|
1457 reads all properties in the composed view |
|
1458 of the specified snapshot of a property group |
|
1459 </summary> |
|
1460 <result> |
|
1461 <list typeref="Property" /> |
|
1462 </result> |
|
1463 <error typeref="SmfError"> |
|
1464 <doc> |
|
1465 <para> |
|
1466 Failed to read properties from |
|
1467 the snapshot's composed view of |
|
1468 the specified property group. |
|
1469 Cause: |
|
1470 </para> |
|
1471 <list> |
|
1472 <item><code>INTERNAL</code> - |
|
1473 an internal error occurred |
|
1474 </item> |
|
1475 <item><code>DENIED</code> - |
|
1476 insufficient authorization |
|
1477 </item> |
|
1478 <item><code>NOTFOUND</code> - |
|
1479 the property group or snapshot |
|
1480 doesn't exist (see target) |
|
1481 </item> |
|
1482 </list> |
|
1483 </doc> |
|
1484 </error> |
|
1485 <argument type="string" name="snap_name" nullable="true"> |
|
1486 <summary> |
|
1487 the name of the snapshot, or null for the running snapshot |
|
1488 </summary> |
|
1489 </argument> |
|
1490 <argument type="string" name="pg_name"> |
|
1491 <summary> |
|
1492 the name of the property group |
|
1493 </summary> |
|
1494 </argument> |
|
1495 </method> |
|
1496 |
|
1497 <method name="readSnapshotProperty"> |
|
1498 <summary> |
|
1499 reads a property in the composed view |
|
1500 of the specified snapshot |
|
1501 </summary> |
|
1502 <doc> |
|
1503 Reads a single property from the |
|
1504 composed view of the specified property |
|
1505 group. The result includes the name, |
|
1506 type, and values of the property. |
|
1507 </doc> |
|
1508 <result typeref="Property" /> |
|
1509 <error typeref="SmfError"> |
|
1510 <doc> |
|
1511 <para> |
|
1512 Failed to read the property. |
|
1513 Cause: |
|
1514 </para> |
|
1515 <list> |
|
1516 <item><code>INTERNAL</code> - |
|
1517 an internal error occurred |
|
1518 </item> |
|
1519 <item><code>DENIED</code> - |
|
1520 insufficient authorization |
|
1521 </item> |
|
1522 <item><code>NOTFOUND</code> - |
|
1523 the snapshot, property group, |
|
1524 or property doesn't exist (see |
|
1525 target) |
|
1526 </item> |
|
1527 </list> |
|
1528 </doc> |
|
1529 </error> |
|
1530 <argument type="string" name="snap_name" nullable="true"> |
|
1531 <summary> |
|
1532 the name of the snapshot, or null for the running snapshot |
|
1533 </summary> |
|
1534 </argument> |
|
1535 <argument type="string" name="pg_name"> |
|
1536 <summary> |
|
1537 the name of the property group |
|
1538 </summary> |
|
1539 </argument> |
|
1540 <argument type="string" name="prop_name"> |
|
1541 <summary> |
|
1542 the name of the property |
|
1543 </summary> |
|
1544 </argument> |
|
1545 </method> |
|
1546 |
|
1547 <method name="clear"> |
|
1548 <summary> |
|
1549 clear the instance if degraded or in maintenance |
|
1550 </summary> |
|
1551 <doc> |
|
1552 Attempt to clear the maintenance or |
|
1553 degraded state from the instance. This |
|
1554 operation occurs asynchronously, and |
|
1555 will return success even though the |
|
1556 attempt could fail. |
|
1557 </doc> |
|
1558 <error typeref="SmfError"> |
|
1559 <doc> |
|
1560 <para> |
|
1561 Was unable to attempt clearing |
|
1562 the instance. Cause: |
|
1563 </para> |
|
1564 <list> |
|
1565 <item><code>INTERNAL</code> - |
|
1566 an internal error occurred |
|
1567 </item> |
|
1568 <item><code>DENIED</code> - |
|
1569 insufficient authorization |
|
1570 </item> |
|
1571 <item><code>READONLY</code> - |
|
1572 the repository is read-only |
|
1573 </item> |
|
1574 <item><code>BADSTATE</code> - |
|
1575 the instance wasn't in the |
|
1576 maintenance or degraded state |
|
1577 </item> |
|
1578 </list> |
|
1579 </doc> |
|
1580 </error> |
|
1581 <!-- <argument type="boolean" name="synchronous" /> --> |
|
1582 </method> |
|
1583 |
|
1584 <method name="restart"> |
|
1585 <summary> |
|
1586 restarts the instance |
|
1587 </summary> |
|
1588 <doc> |
|
1589 Attempt to restart the instance. This |
|
1590 operation occurs asynchronously, and |
|
1591 will return success even though the |
|
1592 attempt could fail. |
|
1593 </doc> |
|
1594 <error typeref="SmfError"> |
|
1595 <doc> |
|
1596 <para> |
|
1597 Was unable to attempt |
|
1598 restarting the instance. |
|
1599 Cause: |
|
1600 </para> |
|
1601 <list> |
|
1602 <item><code>INTERNAL</code> - |
|
1603 an internal error occurred |
|
1604 </item> |
|
1605 <item><code>DENIED</code> - |
|
1606 insufficient authorization |
|
1607 </item> |
|
1608 <item><code>READONLY</code> - |
|
1609 the repository is read-only |
|
1610 </item> |
|
1611 </list> |
|
1612 </doc> |
|
1613 </error> |
|
1614 <!-- <argument type="boolean" name="synchronous" /> --> |
|
1615 </method> |
|
1616 |
|
1617 <method name="refresh"> |
|
1618 <summary> |
|
1619 refresh the instance |
|
1620 </summary> |
|
1621 <doc> |
|
1622 Attempt to refresh the instance. This |
|
1623 operation occurs asynchronously, and |
|
1624 will return success even though the |
|
1625 attempt could fail. |
|
1626 </doc> |
|
1627 <error typeref="SmfError"> |
|
1628 <doc> |
|
1629 <para> |
|
1630 Was unable to attempt |
|
1631 restarting the instance. |
|
1632 Cause: |
|
1633 </para> |
|
1634 <list> |
|
1635 <item><code>INTERNAL</code> - |
|
1636 an internal error occurred |
|
1637 </item> |
|
1638 <item><code>DENIED</code> - |
|
1639 insufficient authorization |
|
1640 </item> |
|
1641 <item><code>READONLY</code> - |
|
1642 the repository is read-only |
|
1643 </item> |
|
1644 </list> |
|
1645 </doc> |
|
1646 </error> |
|
1647 <!-- <argument type="boolean" name="synchronous" /> --> |
|
1648 </method> |
|
1649 |
|
1650 <method name="maintain"> |
|
1651 <summary> |
|
1652 place the instance in maintenance |
|
1653 </summary> |
|
1654 <doc> |
|
1655 Attempt to place the instance in |
|
1656 maintenance. This operation occurs |
|
1657 asynchronously, and will return success |
|
1658 even though the attempt could fail. |
|
1659 </doc> |
|
1660 <error typeref="SmfError"> |
|
1661 <doc> |
|
1662 <para> |
|
1663 Was unable to attempt to place |
|
1664 the instance in maintenance. |
|
1665 Cause: |
|
1666 </para> |
|
1667 <list> |
|
1668 <item><code>INTERNAL</code> - |
|
1669 an internal error occurred |
|
1670 </item> |
|
1671 <item><code>DENIED</code> - |
|
1672 insufficient authorization |
|
1673 </item> |
|
1674 <item><code>READONLY</code> - |
|
1675 the repository is read-only |
|
1676 </item> |
|
1677 </list> |
|
1678 </doc> |
|
1679 </error> |
|
1680 <argument type="boolean" name="immediate"> |
|
1681 <summary> |
|
1682 skip attempting a clean shutdown |
|
1683 </summary> |
|
1684 </argument> |
|
1685 <argument type="boolean" name="temporary"> |
|
1686 <summary> |
|
1687 maintenance doesn't persist after reboot |
|
1688 </summary> |
|
1689 </argument> |
|
1690 <!-- <argument type="boolean" name="synchronous" /> --> |
|
1691 </method> |
|
1692 |
|
1693 <method name="enable"> |
|
1694 <summary> |
|
1695 enable the instance |
|
1696 </summary> |
|
1697 <doc> |
|
1698 Enable the instance. This operation is |
|
1699 idempotent; enabling an enabled |
|
1700 instance has no effect. |
|
1701 </doc> |
|
1702 <error typeref="SmfError"> |
|
1703 <doc> |
|
1704 <para> |
|
1705 Was unable to enable the |
|
1706 instance. Cause: |
|
1707 </para> |
|
1708 <list> |
|
1709 <item><code>INTERNAL</code> - |
|
1710 an internal error occurred |
|
1711 </item> |
|
1712 <item><code>DENIED</code> - |
|
1713 insufficient authorization |
|
1714 </item> |
|
1715 <item><code>READONLY</code> - |
|
1716 the repository is read-only |
|
1717 </item> |
|
1718 </list> |
|
1719 </doc> |
|
1720 </error> |
|
1721 <argument type="boolean" name="temporary"> |
|
1722 <summary> |
|
1723 enable doesn't persist after reboot |
|
1724 </summary> |
|
1725 </argument> |
|
1726 <!-- <argument type="boolean" name="synchronous" /> --> |
|
1727 </method> |
|
1728 |
|
1729 <method name="disable"> |
|
1730 <summary> |
|
1731 disable the instance |
|
1732 </summary> |
|
1733 <doc> |
|
1734 Disable the instance. This operation |
|
1735 is idempotent; disabling a disabled |
|
1736 instance has no effect. |
|
1737 </doc> |
|
1738 <error typeref="SmfError"> |
|
1739 <doc> |
|
1740 <para> |
|
1741 Was unable to disable the |
|
1742 instance. Cause: |
|
1743 </para> |
|
1744 <list> |
|
1745 <item><code>INTERNAL</code> - |
|
1746 an internal error occurred |
|
1747 </item> |
|
1748 <item><code>DENIED</code> - |
|
1749 insufficient authorization |
|
1750 </item> |
|
1751 <item><code>READONLY</code> - |
|
1752 the repository is read-only |
|
1753 </item> |
|
1754 </list> |
|
1755 </doc> |
|
1756 </error> |
|
1757 <argument type="boolean" name="temporary"> |
|
1758 <summary> |
|
1759 disable doesn't persist after reboot |
|
1760 </summary> |
|
1761 </argument> |
|
1762 <!-- <argument type="boolean" name="synchronous" /> --> |
|
1763 </method> |
|
1764 |
|
1765 <method name="getLogInfo"> |
|
1766 <summary> |
|
1767 obtain instance log file data |
|
1768 </summary> |
|
1769 <doc> |
|
1770 Obtain information from and about the |
|
1771 instance's log file. Includes the |
|
1772 name, size, modification time, and |
|
1773 contents. |
|
1774 </doc> |
|
1775 <result typeref="LogInfo"> |
|
1776 <summary> |
|
1777 the requested log file data |
|
1778 </summary> |
|
1779 </result> |
|
1780 <error typeref="SmfError"> |
|
1781 <doc> |
|
1782 <para> |
|
1783 Was unable to obtain log data. |
|
1784 Cause: |
|
1785 </para> |
|
1786 <list> |
|
1787 <item><code>INTERNAL</code> - |
|
1788 an internal error occurred |
|
1789 </item> |
|
1790 <item><code>DENIED</code> - |
|
1791 insufficient authorization |
|
1792 </item> |
|
1793 <item><code>NOTFOUND</code> - |
|
1794 no log file found |
|
1795 </item> |
|
1796 </list> |
|
1797 </doc> |
|
1798 </error> |
|
1799 <argument type="integer" name="max_size"> |
|
1800 <summary> |
|
1801 bytes of log file content to return |
|
1802 </summary> |
|
1803 </argument> |
|
1804 </method> |
|
1805 </interface> |
|
1806 |
|
1807 |
|
1808 <!-- Master object definitions --> |
|
1809 |
|
1810 <struct name="Service"> |
|
1811 <field type="string" name="fmri" /> |
|
1812 <field type="name" name="objectName" /> |
|
1813 <field name="instances"> |
|
1814 <list type="string" /> |
|
1815 </field> |
|
1816 </struct> |
|
1817 |
|
1818 <struct name="Instance"> |
|
1819 <field type="string" name="fmri" /> |
|
1820 <field type="name" name="objectName" /> |
|
1821 <field type="time" name="stime" /> |
|
1822 <field typeref="SMFState" name="state" /> |
|
1823 </struct> |
|
1824 |
|
1825 <struct name="StateChange"> |
|
1826 <field type="name" name="source" /> |
|
1827 <field typeref="SMFState" name="state" /> |
|
1828 <field typeref="SMFState" name="nextState" /> |
|
1829 <field type="string" name="auxState" nullable="true" /> |
|
1830 <field type="time" name="stateTime" /> |
|
1831 <field type="string" name="reason" nullable="true" /> |
|
1832 </struct> |
|
1833 |
|
1834 <struct name="Addition"> |
|
1835 <field type="name" name="name" /> |
|
1836 <field type="string" name="frmi" /> |
|
1837 <field typeref="Instance" name="instance" nullable="true" /> |
|
1838 <field typeref="Service" name="service" nullable="true" /> |
|
1839 </struct> |
|
1840 |
|
1841 <struct name="Removal"> |
|
1842 <field type="string" name="fmri" /> |
|
1843 </struct> |
|
1844 |
|
1845 <interface name="Master"> |
|
1846 <summary> |
|
1847 a top-level object providing access to all services and instances on |
|
1848 the system |
|
1849 </summary> |
|
1850 |
|
1851 <doc> |
|
1852 <para> |
|
1853 The <code>Master</code> interface provides an iterative entrypoint into the |
|
1854 SMF subsystem. Handles to this type of object can be retrieved from the |
|
1855 RAD server using an object name built with: |
|
1856 </para> |
|
1857 |
|
1858 <list type="ordered"> |
|
1859 <item> |
|
1860 the "<code>com.oracle.solaris.rad.smf</code>" domain name |
|
1861 </item> |
|
1862 <item> |
|
1863 a key named "<code>type</code>" paired with a value of |
|
1864 "<code>Master</code>" |
|
1865 </item> |
|
1866 </list> |
|
1867 |
|
1868 <para> |
|
1869 For example, to report the number of services in the <link |
|
1870 enum="SMFState" value="ONLINE">ONLINE</link> state: |
|
1871 </para> |
|
1872 |
|
1873 <example caption="Master interface (Python)"> |
|
1874 import rad.client |
|
1875 import rad.util |
|
1876 |
|
1877 # Create a connection |
|
1878 radconn = rad.util.connect_unix() |
|
1879 |
|
1880 # Retrieve the Master object |
|
1881 master_name = rad.client.Name("<strong>com.oracle.solaris.rad.smf</strong>", |
|
1882 [("<strong>type</strong>", "<strong>Master</strong>")]) |
|
1883 # Get a native-looking python object that throws RAD exceptions |
|
1884 master = radconn.get_object(master_name) |
|
1885 |
|
1886 # Retrieve a handle to the SMFState enum |
|
1887 SMFState = rad.client.get_types(master).SMFState |
|
1888 |
|
1889 # Do something with the Master object |
|
1890 print "%d service instances are online" % \ |
|
1891 len([x for x in master.instances if x.state is SMFState.ONLINE])</example> |
|
1892 |
|
1893 <para> |
|
1894 If using the Python SMF convenience wrapper delivered with this |
|
1895 API, this can be simplified to: |
|
1896 </para> |
|
1897 |
|
1898 <example caption="Master interface (Python, SMF wrapper)"> |
|
1899 import smf.rad |
|
1900 |
|
1901 # Get quick access to the Master interface |
|
1902 repo = smf.rad.Repository() |
|
1903 master = repo.get_master() |
|
1904 |
|
1905 # Retrieve a handle to the SMFState enum |
|
1906 SMFState = rad.client.get_types(master).SMFState |
|
1907 |
|
1908 # Do something with the master object |
|
1909 print "%d service instances are online" % \ |
|
1910 len([x for x in master.instances if x.state is SMFState.ONLINE])</example> |
|
1911 </doc> |
|
1912 |
|
1913 <version major="1" minor="0" stability="private" /> |
|
1914 |
|
1915 <property name="services" access="ro"> |
|
1916 <list typeref="Service" /> |
|
1917 <error typeref="SmfError" /> |
|
1918 </property> |
|
1919 |
|
1920 <property name="instances" access="ro"> |
|
1921 <list typeref="Instance" /> |
|
1922 <error typeref="SmfError" /> |
|
1923 </property> |
|
1924 |
|
1925 <event typeref="StateChange" name="statechange" /> |
|
1926 <event typeref="Addition" name="additions" /> |
|
1927 <event typeref="Removal" name="removals" /> |
|
1928 </interface> |
|
1929 </api> |