usr/src/lib/librestart/common/librestart.h

   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 (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
  23  */
  24
  25 #ifndef _LIBRESTART_H
  26 #define _LIBRESTART_H
  27
  28 #include <libsysevent.h>
  29 #include <libcontract.h>
  30 #include <libscf.h>
  31 #include <limits.h>
  32 #include <priv.h>
  33 #include <pwd.h>
  34 #include <sys/types.h>
  35 #include <sys/secflags.h>
  36
  37 #ifdef  __cplusplus
  38 extern "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
  66 typedef struct restarter_event_handle restarter_event_handle_t;
  67 typedef struct restarter_event restarter_event_t;
  68
  69 typedef 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         5
  78
  79 #define RESTARTER_FLAG_DEBUG            1
  80
  81 #define RESTARTER_ERRMSGSZ              1024
  82
  83 /*
  84  * Event types
  85  *      RESTARTER_EVENT_TYPE_ADD_INSTANCE
  86  *              responsible for a new (stopped) instance
  87  *      RESTARTER_EVENT_TYPE_REMOVE_INSTANCE
  88  *              no longer responsible for this instance; stop it and return
  89  *      RESTARTER_EVENT_TYPE_ENABLE
  90  *              no guarantee that dependencies are met; see
  91  *              RESTARTER_EVENT_TYPE_START
  92  *      RESTARTER_EVENT_TYPE_DISABLE
  93  *              no guarantee that instance was running
  94  *      RESTARTER_EVENT_TYPE_ADMIN_DEGRADED
  95  *      RESTARTER_EVENT_TYPE_ADMIN_REFRESH
  96  *      RESTARTER_EVENT_TYPE_ADMIN_RESTART
  97  *      RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF
  98  *      RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON
  99  *      RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE
 100  *      RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF
 101  *      RESTARTER_EVENT_TYPE_STOP
 102  *              dependencies are, or are becoming, unsatisfied
 103  *      RESTARTER_EVENT_TYPE_START
 104  *              dependencies have become satisfied
 105  *      RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE
 106  *              instance caused a dependency cycle
 107  *      RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY
 108  *              instance has an invalid dependency
 109  */
 110
 111 #define RESTARTER_EVENT_TYPE_INVALID                    0
 112 #define RESTARTER_EVENT_TYPE_ADD_INSTANCE               1
 113 #define RESTARTER_EVENT_TYPE_REMOVE_INSTANCE            2
 114 #define RESTARTER_EVENT_TYPE_ENABLE                     3
 115 #define RESTARTER_EVENT_TYPE_DISABLE                    4
 116 #define RESTARTER_EVENT_TYPE_ADMIN_DEGRADED             5
 117 #define RESTARTER_EVENT_TYPE_ADMIN_REFRESH              6
 118 #define RESTARTER_EVENT_TYPE_ADMIN_RESTART              7
 119 #define RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF            8
 120 #define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON             9
 121 #define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE   10
 122 #define RESTARTER_EVENT_TYPE_STOP                       11
 123 #define RESTARTER_EVENT_TYPE_START                      12
 124 #define RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE           13
 125 #define RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY         14
 126 #define RESTARTER_EVENT_TYPE_ADMIN_DISABLE              15
 127 #define RESTARTER_EVENT_TYPE_STOP_RESET                 16
 128
 129 #define RESTARTER_EVENT_ERROR                   -1
 130
 131 #define RESTARTER_EVENT_INSTANCE_DISABLED       0
 132 #define RESTARTER_EVENT_INSTANCE_ENABLED        1
 133
 134 typedef enum {
 135         RESTARTER_STATE_NONE,
 136         RESTARTER_STATE_UNINIT,
 137         RESTARTER_STATE_MAINT,
 138         RESTARTER_STATE_OFFLINE,
 139         RESTARTER_STATE_DISABLED,
 140         RESTARTER_STATE_ONLINE,
 141         RESTARTER_STATE_DEGRADED
 142 } restarter_instance_state_t;
 143
 144 /*
 145  * These values are ordered by severity of required restart, as we use
 146  * integer comparisons to determine error flow.
 147  */
 148 typedef enum {
 149         RERR_UNSUPPORTED = -1,
 150         RERR_NONE = 0,                  /* no error, restart, refresh */
 151         RERR_FAULT,                     /* fault occurred */
 152         RERR_RESTART,                   /* transition due to restart */
 153         RERR_REFRESH                    /* transition due to refresh */
 154 } restarter_error_t;
 155 /*
 156  * restarter_store_contract() and restarter_remove_contract() types
 157  */
 158 typedef enum {
 159         RESTARTER_CONTRACT_PRIMARY,
 160         RESTARTER_CONTRACT_TRANSIENT
 161 } restarter_contract_type_t;
 162
 163 /*
 164  * restarter_bind_handle() registers a delegate with svc.startd to
 165  * begin consuming events.
 166  *
 167  * On initial bind, the delgated restarter receives an event for each
 168  * instance it is responsible for, as if that instance was new.
 169  *
 170  * callers must have superuser privileges
 171  *
 172  * The event handler can return 0 for success, or EAGAIN to request
 173  * retry of event delivery. EAGAIN may be returned 3 times before the
 174  * event is discarded.
 175  */
 176 int restarter_bind_handle(uint32_t, const char *,
 177     int (*event_handler)(restarter_event_t *), int,
 178     restarter_event_handle_t **);
 179
 180 restarter_event_type_t restarter_event_get_type(restarter_event_t *);
 181 uint64_t restarter_event_get_seq(restarter_event_t *);
 182 void restarter_event_get_time(restarter_event_t *, hrtime_t *);
 183 ssize_t restarter_event_get_instance(restarter_event_t *, char *, size_t);
 184 restarter_event_handle_t *restarter_event_get_handle(restarter_event_t *);
 185
 186 /*
 187  * The following functions work only on certain types of events.
 188  * They fail with a return of -1 if they're called on an inappropriate event.
 189  */
 190 int restarter_event_get_enabled(restarter_event_t *);
 191 int restarter_event_get_current_states(restarter_event_t *,
 192     restarter_instance_state_t *, restarter_instance_state_t *);
 193
 194 /*
 195  * State transition reasons
 196  */
 197
 198 typedef enum {
 199         restarter_str_none,
 200         restarter_str_administrative_request,
 201         restarter_str_bad_repo_state,
 202         restarter_str_clear_request,
 203         restarter_str_ct_ev_core,
 204         restarter_str_ct_ev_exit,
 205         restarter_str_ct_ev_hwerr,
 206         restarter_str_ct_ev_signal,
 207         restarter_str_dependencies_satisfied,
 208         restarter_str_dependency_activity,
 209         restarter_str_dependency_cycle,
 210         restarter_str_disable_request,
 211         restarter_str_enable_request,
 212         restarter_str_fault_threshold_reached,
 213         restarter_str_insert_in_graph,
 214         restarter_str_invalid_dependency,
 215         restarter_str_invalid_restarter,
 216         restarter_str_method_failed,
 217         restarter_str_per_configuration,
 218         restarter_str_refresh,
 219         restarter_str_restart_request,
 220         restarter_str_restarting_too_quickly,
 221         restarter_str_service_request,
 222         restarter_str_startd_restart
 223 } restarter_str_t;
 224
 225 struct restarter_state_transition_reason {
 226         restarter_str_t str_key;
 227         const char      *str_short;
 228         const char      *str_long;
 229 };
 230
 231 /*
 232  * Functions for updating the repository.
 233  */
 234
 235 /*
 236  * When setting state to "maintenance", callers of restarter_set_states() can
 237  * set aux_state to "service_request" to communicate that another service has
 238  * requested maintenance state for the target service.
 239  *
 240  * Callers should use restarter_inst_validate_aux_fmri() to validate the fmri
 241  * of the requested service and pass "service_request" for aux_state when
 242  * calling restarter_set_states(). See inetd and startd for examples.
 243  */
 244 int restarter_set_states(restarter_event_handle_t *, const char *,
 245     restarter_instance_state_t, restarter_instance_state_t,
 246     restarter_instance_state_t, restarter_instance_state_t, restarter_error_t,
 247     restarter_str_t);
 248 int restarter_event_publish_retry(evchan_t *, const char *, const char *,
 249     const char *, const char *, nvlist_t *, uint32_t);
 250
 251 /*
 252  * functions for retrieving the state transition reason messages
 253  */
 254
 255 #define RESTARTER_STRING_VERSION        1
 256
 257 uint32_t restarter_str_version(void);
 258 const char *restarter_get_str_short(restarter_str_t);
 259 const char *restarter_get_str_long(restarter_str_t);
 260
 261 int restarter_store_contract(scf_instance_t *, ctid_t,
 262     restarter_contract_type_t);
 263 int restarter_remove_contract(scf_instance_t *, ctid_t,
 264     restarter_contract_type_t);
 265
 266 ssize_t restarter_state_to_string(restarter_instance_state_t, char *, size_t);
 267 restarter_instance_state_t restarter_string_to_state(char *);
 268
 269 #define RESTARTER_METHOD_CONTEXT_VERSION        8
 270
 271 struct method_context {
 272         /* Stable */
 273         uid_t           uid, euid;
 274         gid_t           gid, egid;
 275         int             ngroups;                /* -1 means use initgroups(). */
 276         gid_t           groups[NGROUPS_MAX];
 277         scf_secflags_t  def_secflags;
 278         secflagdelta_t  secflag_delta;
 279         priv_set_t      *lpriv_set, *priv_set;
 280         char            *corefile_pattern;      /* Optional. */
 281         char            *project;               /* NULL for no change */
 282         char            *resource_pool;         /* NULL for project default */
 283         char            *working_dir;           /* NULL for :default */
 284         char            **env;                  /* NULL for no env */
 285         size_t          env_sz;                 /* size of env array */
 286
 287         /* Private */
 288         char            *vbuf;
 289         ssize_t         vbuf_sz;
 290         struct passwd   pwd;
 291         char            *pwbuf;
 292         ssize_t         pwbufsz;
 293 };
 294
 295 /*
 296  * An error structure that contains a message string, and a type
 297  * that can be used to determine course of action by the reciever
 298  * of the error structure.
 299  *
 300  * type - usually will be an errno equivalent but could contain
 301  *      defined error types for exampe SCF_ERROR_XXX
 302  * msg - must be at the end of the structure as if the message is
 303  *      longer than EMSGSIZE we will reallocate the structure to
 304  *      handle the overflow
 305  */
 306 typedef struct mc_error {
 307         int     destroy;        /* Flag to indicate destruction steps */
 308         int     type;           /* Type of error for decision making */
 309         int     size;           /* The size of the error message string */
 310         char    msg[RESTARTER_ERRMSGSZ];
 311 } mc_error_t;
 312
 313 int restarter_rm_libs_loadable(void);
 314 /* instance, restarter name, method name, command line, structure pointer */
 315 mc_error_t *restarter_get_method_context(uint_t, scf_instance_t *,
 316     scf_snapshot_t *, const char *, const char *, struct method_context **);
 317 void restarter_mc_error_destroy(mc_error_t *);
 318 int restarter_set_method_context(struct method_context *, const char **);
 319 void restarter_free_method_context(struct method_context *);
 320
 321
 322 int restarter_is_null_method(const char *);
 323 int restarter_is_kill_method(const char *);
 324 int restarter_is_kill_proc_method(const char *);
 325
 326 /* Validate the inst fmri specified in  restarter_actions/auxiliary_fmri */
 327 int restarter_inst_validate_ractions_aux_fmri(scf_instance_t *);
 328
 329 /* Delete instance's restarter_actions/auxiliary_fmri property */
 330 int restarter_inst_reset_ractions_aux_fmri(scf_instance_t *);
 331
 332 /* Get boolean value from instance's restarter_actions/auxiliary_tty */
 333 int restarter_inst_ractions_from_tty(scf_instance_t *);
 334
 335 /* Delete instance's restarter/auxiliary_fmri property */
 336 int restarter_inst_reset_aux_fmri(scf_instance_t *);
 337
 338 /* Get boolean value from instance's restarter_actions/do_dump */
 339 int restarter_inst_dump(scf_instance_t *);
 340
 341 /*
 342  * Set instance's restarter/auxiliary_fmri, value come from
 343  * restarter_actions/auxliary_fmri
 344  */
 345 int restarter_inst_set_aux_fmri(scf_instance_t *);
 346
 347 #ifdef  __cplusplus
 348 }
 349 #endif
 350
 351 #endif  /* _LIBRESTART_H */