Print this page
7711 SMF: Finish implementing support for degraded state
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/lib/librestart/common/librestart.h
+++ new/usr/src/lib/librestart/common/librestart.h
1 1 /*
2 2 * CDDL HEADER START
3 3 *
4 4 * The contents of this file are subject to the terms of the
5 5 * Common Development and Distribution License (the "License").
6 6 * You may not use this file except in compliance with the License.
7 7 *
8 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 9 * or http://www.opensolaris.org/os/licensing.
10 10 * See the License for the specific language governing permissions
11 11 * and limitations under the License.
12 12 *
|
↓ open down ↓ |
12 lines elided |
↑ open up ↑ |
13 13 * When distributing Covered Code, include this CDDL HEADER in each
14 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 15 * If applicable, add the following below this CDDL HEADER, with the
16 16 * fields enclosed by brackets "[]" replaced with your own identifying
17 17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 18 *
19 19 * CDDL HEADER END
20 20 */
21 21 /*
22 22 * Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
23 + * Copyright 2017 RackTop Systems.
23 24 */
24 25
25 26 #ifndef _LIBRESTART_H
26 27 #define _LIBRESTART_H
27 28
28 29 #include <libsysevent.h>
29 30 #include <libcontract.h>
30 31 #include <libscf.h>
31 32 #include <limits.h>
32 33 #include <priv.h>
33 34 #include <pwd.h>
34 35 #include <sys/types.h>
35 36 #include <sys/secflags.h>
36 37
37 38 #ifdef __cplusplus
38 39 extern "C" {
39 40 #endif
40 41
41 42 /*
42 43 * There are 3 parts to librestart.
43 44 * 1) The event protocol from the master restarter to its delegates.
44 45 * 2) A functional interface for updating the repository.
45 46 * 3) Convenience functions for common restarter tasks.
46 47 *
47 48 * Event protocol
48 49 * We need a reliable event protocol, as there's no way to define
49 50 * restarter events as idempotent.
50 51 *
51 52 * Currently using sysevent channels as the reliable event implementation.
52 53 * This could change if the implementation proves unsuitable, but
53 54 * the API defined here should abstract anything but a change in
54 55 * the fundamental event model.
55 56 *
56 57 * We offer functions to tease apart the event rather than generic
57 58 * nvpair interfaces. This is because each event type has a well-
58 59 * defined set of fields.
59 60 */
60 61
61 62 /*
62 63 * Some of the functions have external contracted consumers, review contracts
63 64 * when making incompatible changes.
64 65 */
65 66
66 67 typedef struct restarter_event_handle restarter_event_handle_t;
67 68 typedef struct restarter_event restarter_event_t;
68 69
69 70 typedef uint32_t restarter_event_type_t;
70 71
71 72 /*
72 73 * Define an event protocol version. In theory, we could use this in
73 74 * the future to support delegated restarters which use an older
74 75 * protocol. In practice, increment RESTARTER_EVENT_VERSION whenever the
75 76 * protocol might have changed.
76 77 */
77 78 #define RESTARTER_EVENT_VERSION 5
78 79
79 80 #define RESTARTER_FLAG_DEBUG 1
80 81
81 82 #define RESTARTER_ERRMSGSZ 1024
82 83
83 84 /*
|
↓ open down ↓ |
51 lines elided |
↑ open up ↑ |
84 85 * Event types
85 86 * RESTARTER_EVENT_TYPE_ADD_INSTANCE
86 87 * responsible for a new (stopped) instance
87 88 * RESTARTER_EVENT_TYPE_REMOVE_INSTANCE
88 89 * no longer responsible for this instance; stop it and return
89 90 * RESTARTER_EVENT_TYPE_ENABLE
90 91 * no guarantee that dependencies are met; see
91 92 * RESTARTER_EVENT_TYPE_START
92 93 * RESTARTER_EVENT_TYPE_DISABLE
93 94 * no guarantee that instance was running
95 + * RESTARTER_EVENT_TYPE_ADMIN_RESTORE
94 96 * RESTARTER_EVENT_TYPE_ADMIN_DEGRADED
97 + * RESTARTER_EVENT_TYPE_ADMIN_DEGRADE_IMMEDIATE
95 98 * RESTARTER_EVENT_TYPE_ADMIN_REFRESH
96 99 * RESTARTER_EVENT_TYPE_ADMIN_RESTART
97 100 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF
98 101 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON
99 102 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE
100 103 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF
101 104 * RESTARTER_EVENT_TYPE_STOP
102 105 * dependencies are, or are becoming, unsatisfied
103 106 * RESTARTER_EVENT_TYPE_START
104 107 * dependencies have become satisfied
105 108 * RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE
106 109 * instance caused a dependency cycle
107 110 * RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY
108 111 * instance has an invalid dependency
109 112 */
110 113
111 114 #define RESTARTER_EVENT_TYPE_INVALID 0
112 115 #define RESTARTER_EVENT_TYPE_ADD_INSTANCE 1
113 116 #define RESTARTER_EVENT_TYPE_REMOVE_INSTANCE 2
114 117 #define RESTARTER_EVENT_TYPE_ENABLE 3
115 118 #define RESTARTER_EVENT_TYPE_DISABLE 4
116 119 #define RESTARTER_EVENT_TYPE_ADMIN_DEGRADED 5
117 120 #define RESTARTER_EVENT_TYPE_ADMIN_REFRESH 6
|
↓ open down ↓ |
13 lines elided |
↑ open up ↑ |
118 121 #define RESTARTER_EVENT_TYPE_ADMIN_RESTART 7
119 122 #define RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF 8
120 123 #define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON 9
121 124 #define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE 10
122 125 #define RESTARTER_EVENT_TYPE_STOP 11
123 126 #define RESTARTER_EVENT_TYPE_START 12
124 127 #define RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE 13
125 128 #define RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY 14
126 129 #define RESTARTER_EVENT_TYPE_ADMIN_DISABLE 15
127 130 #define RESTARTER_EVENT_TYPE_STOP_RESET 16
131 +#define RESTARTER_EVENT_TYPE_ADMIN_RESTORE 17
132 +#define RESTARTER_EVENT_TYPE_ADMIN_DEGRADE_IMMEDIATE 18
128 133
129 134 #define RESTARTER_EVENT_ERROR -1
130 135
131 136 #define RESTARTER_EVENT_INSTANCE_DISABLED 0
132 137 #define RESTARTER_EVENT_INSTANCE_ENABLED 1
133 138
134 139 typedef enum {
135 140 RESTARTER_STATE_NONE,
136 141 RESTARTER_STATE_UNINIT,
137 142 RESTARTER_STATE_MAINT,
138 143 RESTARTER_STATE_OFFLINE,
139 144 RESTARTER_STATE_DISABLED,
140 145 RESTARTER_STATE_ONLINE,
141 146 RESTARTER_STATE_DEGRADED
142 147 } restarter_instance_state_t;
143 148
144 149 /*
145 150 * These values are ordered by severity of required restart, as we use
146 151 * integer comparisons to determine error flow.
147 152 */
148 153 typedef enum {
149 154 RERR_UNSUPPORTED = -1,
150 155 RERR_NONE = 0, /* no error, restart, refresh */
151 156 RERR_FAULT, /* fault occurred */
152 157 RERR_RESTART, /* transition due to restart */
153 158 RERR_REFRESH /* transition due to refresh */
154 159 } restarter_error_t;
155 160 /*
156 161 * restarter_store_contract() and restarter_remove_contract() types
157 162 */
158 163 typedef enum {
159 164 RESTARTER_CONTRACT_PRIMARY,
160 165 RESTARTER_CONTRACT_TRANSIENT
161 166 } restarter_contract_type_t;
162 167
163 168 /*
164 169 * restarter_bind_handle() registers a delegate with svc.startd to
165 170 * begin consuming events.
166 171 *
167 172 * On initial bind, the delgated restarter receives an event for each
168 173 * instance it is responsible for, as if that instance was new.
169 174 *
170 175 * callers must have superuser privileges
171 176 *
172 177 * The event handler can return 0 for success, or EAGAIN to request
173 178 * retry of event delivery. EAGAIN may be returned 3 times before the
174 179 * event is discarded.
175 180 */
176 181 int restarter_bind_handle(uint32_t, const char *,
177 182 int (*event_handler)(restarter_event_t *), int,
178 183 restarter_event_handle_t **);
179 184
180 185 restarter_event_type_t restarter_event_get_type(restarter_event_t *);
181 186 uint64_t restarter_event_get_seq(restarter_event_t *);
182 187 void restarter_event_get_time(restarter_event_t *, hrtime_t *);
183 188 ssize_t restarter_event_get_instance(restarter_event_t *, char *, size_t);
184 189 restarter_event_handle_t *restarter_event_get_handle(restarter_event_t *);
185 190
186 191 /*
187 192 * The following functions work only on certain types of events.
188 193 * They fail with a return of -1 if they're called on an inappropriate event.
189 194 */
190 195 int restarter_event_get_enabled(restarter_event_t *);
191 196 int restarter_event_get_current_states(restarter_event_t *,
192 197 restarter_instance_state_t *, restarter_instance_state_t *);
193 198
194 199 /*
195 200 * State transition reasons
196 201 */
197 202
198 203 typedef enum {
199 204 restarter_str_none,
200 205 restarter_str_administrative_request,
201 206 restarter_str_bad_repo_state,
202 207 restarter_str_clear_request,
203 208 restarter_str_ct_ev_core,
204 209 restarter_str_ct_ev_exit,
205 210 restarter_str_ct_ev_hwerr,
206 211 restarter_str_ct_ev_signal,
207 212 restarter_str_dependencies_satisfied,
208 213 restarter_str_dependency_activity,
209 214 restarter_str_dependency_cycle,
210 215 restarter_str_disable_request,
211 216 restarter_str_enable_request,
212 217 restarter_str_fault_threshold_reached,
213 218 restarter_str_insert_in_graph,
214 219 restarter_str_invalid_dependency,
215 220 restarter_str_invalid_restarter,
216 221 restarter_str_method_failed,
217 222 restarter_str_per_configuration,
218 223 restarter_str_refresh,
219 224 restarter_str_restart_request,
220 225 restarter_str_restarting_too_quickly,
221 226 restarter_str_service_request,
222 227 restarter_str_startd_restart
223 228 } restarter_str_t;
224 229
225 230 struct restarter_state_transition_reason {
226 231 restarter_str_t str_key;
227 232 const char *str_short;
228 233 const char *str_long;
229 234 };
230 235
231 236 /*
232 237 * Functions for updating the repository.
233 238 */
234 239
235 240 /*
236 241 * When setting state to "maintenance", callers of restarter_set_states() can
237 242 * set aux_state to "service_request" to communicate that another service has
238 243 * requested maintenance state for the target service.
239 244 *
240 245 * Callers should use restarter_inst_validate_aux_fmri() to validate the fmri
241 246 * of the requested service and pass "service_request" for aux_state when
242 247 * calling restarter_set_states(). See inetd and startd for examples.
243 248 */
244 249 int restarter_set_states(restarter_event_handle_t *, const char *,
245 250 restarter_instance_state_t, restarter_instance_state_t,
246 251 restarter_instance_state_t, restarter_instance_state_t, restarter_error_t,
247 252 restarter_str_t);
248 253 int restarter_event_publish_retry(evchan_t *, const char *, const char *,
249 254 const char *, const char *, nvlist_t *, uint32_t);
250 255
251 256 /*
252 257 * functions for retrieving the state transition reason messages
253 258 */
254 259
255 260 #define RESTARTER_STRING_VERSION 1
256 261
257 262 uint32_t restarter_str_version(void);
258 263 const char *restarter_get_str_short(restarter_str_t);
259 264 const char *restarter_get_str_long(restarter_str_t);
260 265
261 266 int restarter_store_contract(scf_instance_t *, ctid_t,
262 267 restarter_contract_type_t);
263 268 int restarter_remove_contract(scf_instance_t *, ctid_t,
264 269 restarter_contract_type_t);
265 270
266 271 ssize_t restarter_state_to_string(restarter_instance_state_t, char *, size_t);
267 272 restarter_instance_state_t restarter_string_to_state(char *);
268 273
269 274 #define RESTARTER_METHOD_CONTEXT_VERSION 8
270 275
271 276 struct method_context {
272 277 /* Stable */
273 278 uid_t uid, euid;
274 279 gid_t gid, egid;
275 280 int ngroups; /* -1 means use initgroups(). */
276 281 gid_t groups[NGROUPS_MAX];
277 282 scf_secflags_t def_secflags;
278 283 secflagdelta_t secflag_delta;
279 284 priv_set_t *lpriv_set, *priv_set;
280 285 char *corefile_pattern; /* Optional. */
281 286 char *project; /* NULL for no change */
282 287 char *resource_pool; /* NULL for project default */
283 288 char *working_dir; /* NULL for :default */
284 289 char **env; /* NULL for no env */
285 290 size_t env_sz; /* size of env array */
286 291
287 292 /* Private */
288 293 char *vbuf;
289 294 ssize_t vbuf_sz;
290 295 struct passwd pwd;
291 296 char *pwbuf;
292 297 ssize_t pwbufsz;
293 298 };
294 299
295 300 /*
296 301 * An error structure that contains a message string, and a type
297 302 * that can be used to determine course of action by the reciever
298 303 * of the error structure.
299 304 *
300 305 * type - usually will be an errno equivalent but could contain
301 306 * defined error types for exampe SCF_ERROR_XXX
302 307 * msg - must be at the end of the structure as if the message is
303 308 * longer than EMSGSIZE we will reallocate the structure to
304 309 * handle the overflow
305 310 */
306 311 typedef struct mc_error {
307 312 int destroy; /* Flag to indicate destruction steps */
308 313 int type; /* Type of error for decision making */
309 314 int size; /* The size of the error message string */
310 315 char msg[RESTARTER_ERRMSGSZ];
311 316 } mc_error_t;
312 317
313 318 int restarter_rm_libs_loadable(void);
314 319 /* instance, restarter name, method name, command line, structure pointer */
315 320 mc_error_t *restarter_get_method_context(uint_t, scf_instance_t *,
316 321 scf_snapshot_t *, const char *, const char *, struct method_context **);
317 322 void restarter_mc_error_destroy(mc_error_t *);
318 323 int restarter_set_method_context(struct method_context *, const char **);
319 324 void restarter_free_method_context(struct method_context *);
320 325
321 326
322 327 int restarter_is_null_method(const char *);
323 328 int restarter_is_kill_method(const char *);
324 329 int restarter_is_kill_proc_method(const char *);
325 330
326 331 /* Validate the inst fmri specified in restarter_actions/auxiliary_fmri */
327 332 int restarter_inst_validate_ractions_aux_fmri(scf_instance_t *);
328 333
329 334 /* Delete instance's restarter_actions/auxiliary_fmri property */
330 335 int restarter_inst_reset_ractions_aux_fmri(scf_instance_t *);
331 336
332 337 /* Get boolean value from instance's restarter_actions/auxiliary_tty */
333 338 int restarter_inst_ractions_from_tty(scf_instance_t *);
334 339
335 340 /* Delete instance's restarter/auxiliary_fmri property */
336 341 int restarter_inst_reset_aux_fmri(scf_instance_t *);
337 342
338 343 /* Get boolean value from instance's restarter_actions/do_dump */
339 344 int restarter_inst_dump(scf_instance_t *);
340 345
341 346 /*
342 347 * Set instance's restarter/auxiliary_fmri, value come from
343 348 * restarter_actions/auxliary_fmri
344 349 */
345 350 int restarter_inst_set_aux_fmri(scf_instance_t *);
346 351
347 352 #ifdef __cplusplus
348 353 }
349 354 #endif
350 355
351 356 #endif /* _LIBRESTART_H */
|
↓ open down ↓ |
214 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX