librestart.h revision 9263:48d14e1f550f
1/* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21/* 22 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 23 * Use is subject to license terms. 24 */ 25 26#ifndef _LIBRESTART_H 27#define _LIBRESTART_H 28 29#include <libsysevent.h> 30#include <libcontract.h> 31#include <libscf.h> 32#include <limits.h> 33#include <priv.h> 34#include <pwd.h> 35#include <sys/types.h> 36 37#ifdef __cplusplus 38extern "C" { 39#endif 40 41/* 42 * There are 3 parts to librestart. 43 * 1) The event protocol from the master restarter to its delegates. 44 * 2) A functional interface for updating the repository. 45 * 3) Convenience functions for common restarter tasks. 46 * 47 * Event protocol 48 * We need a reliable event protocol, as there's no way to define 49 * restarter events as idempotent. 50 * 51 * Currently using sysevent channels as the reliable event implementation. 52 * This could change if the implementation proves unsuitable, but 53 * the API defined here should abstract anything but a change in 54 * the fundamental event model. 55 * 56 * We offer functions to tease apart the event rather than generic 57 * nvpair interfaces. This is because each event type has a well- 58 * defined set of fields. 59 */ 60 61/* 62 * Some of the functions have external contracted consumers, review contracts 63 * when making incompatible changes. 64 */ 65 66typedef struct restarter_event_handle restarter_event_handle_t; 67typedef struct restarter_event restarter_event_t; 68 69typedef uint32_t restarter_event_type_t; 70 71/* 72 * Define an event protocol version. In theory, we could use this in 73 * the future to support delegated restarters which use an older 74 * protocol. In practice, increment RESTARTER_EVENT_VERSION whenever the 75 * protocol might have changed. 76 */ 77#define RESTARTER_EVENT_VERSION 4 78 79#define RESTARTER_FLAG_DEBUG 1 80 81/* 82 * Event types 83 * RESTARTER_EVENT_TYPE_ADD_INSTANCE 84 * responsible for a new (stopped) instance 85 * RESTARTER_EVENT_TYPE_REMOVE_INSTANCE 86 * no longer responsible for this instance; stop it and return 87 * RESTARTER_EVENT_TYPE_ENABLE 88 * no guarantee that dependencies are met; see 89 * RESTARTER_EVENT_TYPE_START 90 * RESTARTER_EVENT_TYPE_DISABLE 91 * no guarantee that instance was running 92 * RESTARTER_EVENT_TYPE_ADMIN_DEGRADED 93 * RESTARTER_EVENT_TYPE_ADMIN_REFRESH 94 * RESTARTER_EVENT_TYPE_ADMIN_RESTART 95 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF 96 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON 97 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE 98 * RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF 99 * RESTARTER_EVENT_TYPE_STOP 100 * dependencies are, or are becoming, unsatisfied 101 * RESTARTER_EVENT_TYPE_START 102 * dependencies have become satisfied 103 * RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE 104 * instance caused a dependency cycle 105 * RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY 106 * instance has an invalid dependency 107 */ 108 109#define RESTARTER_EVENT_TYPE_INVALID 0 110#define RESTARTER_EVENT_TYPE_ADD_INSTANCE 1 111#define RESTARTER_EVENT_TYPE_REMOVE_INSTANCE 2 112#define RESTARTER_EVENT_TYPE_ENABLE 3 113#define RESTARTER_EVENT_TYPE_DISABLE 4 114#define RESTARTER_EVENT_TYPE_ADMIN_DEGRADED 5 115#define RESTARTER_EVENT_TYPE_ADMIN_REFRESH 6 116#define RESTARTER_EVENT_TYPE_ADMIN_RESTART 7 117#define RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF 8 118#define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON 9 119#define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE 10 120#define RESTARTER_EVENT_TYPE_STOP 11 121#define RESTARTER_EVENT_TYPE_START 12 122#define RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE 13 123#define RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY 14 124#define RESTARTER_EVENT_TYPE_ADMIN_DISABLE 15 125 126#define RESTARTER_EVENT_ERROR -1 127 128#define RESTARTER_EVENT_INSTANCE_DISABLED 0 129#define RESTARTER_EVENT_INSTANCE_ENABLED 1 130 131typedef enum { 132 RESTARTER_STATE_NONE, 133 RESTARTER_STATE_UNINIT, 134 RESTARTER_STATE_MAINT, 135 RESTARTER_STATE_OFFLINE, 136 RESTARTER_STATE_DISABLED, 137 RESTARTER_STATE_ONLINE, 138 RESTARTER_STATE_DEGRADED 139} restarter_instance_state_t; 140 141/* 142 * These values are ordered by severity of required restart, as we use 143 * integer comparisons to determine error flow. 144 */ 145typedef enum { 146 RERR_UNSUPPORTED = -1, 147 RERR_NONE = 0, /* no error, restart, refresh */ 148 RERR_FAULT, /* fault occurred */ 149 RERR_RESTART, /* transition due to restart */ 150 RERR_REFRESH /* transition due to refresh */ 151} restarter_error_t; 152/* 153 * restarter_store_contract() and restarter_remove_contract() types 154 */ 155typedef enum { 156 RESTARTER_CONTRACT_PRIMARY, 157 RESTARTER_CONTRACT_TRANSIENT 158} restarter_contract_type_t; 159 160/* 161 * restarter_bind_handle() registers a delegate with svc.startd to 162 * begin consuming events. 163 * 164 * On initial bind, the delgated restarter receives an event for each 165 * instance it is responsible for, as if that instance was new. 166 * 167 * callers must have superuser privileges 168 * 169 * The event handler can return 0 for success, or EAGAIN to request 170 * retry of event delivery. EAGAIN may be returned 3 times before the 171 * event is discarded. 172 */ 173int restarter_bind_handle(uint32_t, const char *, 174 int (*event_handler)(restarter_event_t *), int, 175 restarter_event_handle_t **); 176 177restarter_event_type_t restarter_event_get_type(restarter_event_t *); 178uint64_t restarter_event_get_seq(restarter_event_t *); 179void restarter_event_get_time(restarter_event_t *, hrtime_t *); 180ssize_t restarter_event_get_instance(restarter_event_t *, char *, size_t); 181restarter_event_handle_t *restarter_event_get_handle(restarter_event_t *); 182 183/* 184 * The following functions work only on certain types of events. 185 * They fail with a return of -1 if they're called on an inappropriate event. 186 */ 187int restarter_event_get_enabled(restarter_event_t *); 188int restarter_event_get_current_states(restarter_event_t *, 189 restarter_instance_state_t *, restarter_instance_state_t *); 190 191/* 192 * Functions for updating the repository. 193 */ 194 195/* 196 * When setting state to "maintenance", callers of restarter_set_states() can 197 * set aux_state to "service_request" to communicate that another service has 198 * requested maintenance state for the target service. 199 * 200 * Callers should use restarter_inst_validate_aux_fmri() to validate the fmri 201 * of the requested service and pass "service_request" for aux_state when 202 * calling restarter_set_states(). See inetd and startd for examples. 203 */ 204int restarter_set_states(restarter_event_handle_t *, const char *, 205 restarter_instance_state_t, restarter_instance_state_t, 206 restarter_instance_state_t, restarter_instance_state_t, restarter_error_t, 207 const char *); 208int restarter_event_publish_retry(evchan_t *, const char *, const char *, 209 const char *, const char *, nvlist_t *, uint32_t); 210 211int restarter_store_contract(scf_instance_t *, ctid_t, 212 restarter_contract_type_t); 213int restarter_remove_contract(scf_instance_t *, ctid_t, 214 restarter_contract_type_t); 215 216ssize_t restarter_state_to_string(restarter_instance_state_t, char *, size_t); 217restarter_instance_state_t restarter_string_to_state(char *); 218 219#define RESTARTER_METHOD_CONTEXT_VERSION 6 220 221struct method_context { 222 /* Stable */ 223 uid_t uid, euid; 224 gid_t gid, egid; 225 int ngroups; /* -1 means use initgroups(). */ 226 gid_t groups[NGROUPS_MAX]; 227 priv_set_t *lpriv_set, *priv_set; 228 char *corefile_pattern; /* Optional. */ 229 char *project; /* NULL for no change */ 230 char *resource_pool; /* NULL for project default */ 231 char *working_dir; /* NULL for :default */ 232 char **env; /* NULL for no env */ 233 size_t env_sz; /* size of env array */ 234 235 /* Private */ 236 char *vbuf; 237 ssize_t vbuf_sz; 238 struct passwd pwd; 239 char *pwbuf; 240 ssize_t pwbufsz; 241}; 242 243int restarter_rm_libs_loadable(void); 244/* instance, restarter name, method name, command line, structure pointer */ 245const char *restarter_get_method_context(uint_t, scf_instance_t *, 246 scf_snapshot_t *, const char *, const char *, struct method_context **); 247int restarter_set_method_context(struct method_context *, const char **); 248void restarter_free_method_context(struct method_context *); 249 250 251int restarter_is_null_method(const char *); 252int restarter_is_kill_method(const char *); 253int restarter_is_kill_proc_method(const char *); 254 255/* Validate the inst fmri specified in restarter_actions/auxiliary_fmri */ 256int restarter_inst_validate_ractions_aux_fmri(scf_instance_t *); 257 258/* Delete instance's restarter_actions/auxiliary_fmri property */ 259int restarter_inst_reset_ractions_aux_fmri(scf_instance_t *); 260 261/* Get boolean value from instance's restarter_actions/auxiliary_tty */ 262int restarter_inst_ractions_from_tty(scf_instance_t *); 263 264/* Delete instance's restarter/auxiliary_fmri property */ 265int restarter_inst_reset_aux_fmri(scf_instance_t *); 266 267/* 268 * Set instance's restarter/auxiliary_fmri, value come from 269 * restarter_actions/auxliary_fmri 270 */ 271int restarter_inst_set_aux_fmri(scf_instance_t *); 272 273#ifdef __cplusplus 274} 275#endif 276 277#endif /* _LIBRESTART_H */ 278