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