librestart.h revision 13d8aaa19025bce854122482c986b488bbb781e8
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * CDDL HEADER START
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * The contents of this file are subject to the terms of the
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Common Development and Distribution License (the "License").
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * You may not use this file except in compliance with the License.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * or http://www.opensolaris.org/os/licensing.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * See the License for the specific language governing permissions
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * and limitations under the License.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * When distributing Covered Code, include this CDDL HEADER in each
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * If applicable, add the following below this CDDL HEADER, with the
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * fields enclosed by brackets "[]" replaced with your own identifying
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * information: Portions Copyright [yyyy] [name of copyright owner]
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * CDDL HEADER END
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * Copyright 2009 Sun Microsystems, Inc. All rights reserved.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Use is subject to license terms.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * There are 3 parts to librestart.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * 1) The event protocol from the master restarter to its delegates.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * 2) A functional interface for updating the repository.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * 3) Convenience functions for common restarter tasks.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Event protocol
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * We need a reliable event protocol, as there's no way to define
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * restarter events as idempotent.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Currently using sysevent channels as the reliable event implementation.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * This could change if the implementation proves unsuitable, but
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * the API defined here should abstract anything but a change in
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * the fundamental event model.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * We offer functions to tease apart the event rather than generic
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * nvpair interfaces. This is because each event type has a well-
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * defined set of fields.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Some of the functions have external contracted consumers, review contracts
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * when making incompatible changes.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathantypedef struct restarter_event_handle restarter_event_handle_t;
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathantypedef struct restarter_event restarter_event_t;
8d738d7d1f42180d941afa8b9a7310a2a437d17cSukumar Swaminathan * Define an event protocol version. In theory, we could use this in
8d738d7d1f42180d941afa8b9a7310a2a437d17cSukumar Swaminathan * the future to support delegated restarters which use an older
8d738d7d1f42180d941afa8b9a7310a2a437d17cSukumar Swaminathan * protocol. In practice, increment RESTARTER_EVENT_VERSION whenever the
8d738d7d1f42180d941afa8b9a7310a2a437d17cSukumar Swaminathan * protocol might have changed.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADD_INSTANCE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * responsible for a new (stopped) instance
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_REMOVE_INSTANCE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * no longer responsible for this instance; stop it and return
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ENABLE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * no guarantee that dependencies are met; see
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_START
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_DISABLE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * no guarantee that instance was running
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_DEGRADED
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_REFRESH
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_RESTART
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_STOP
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * dependencies are, or are becoming, unsatisfied
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_START
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * dependencies have become satisfied
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * instance caused a dependency cycle
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * instance has an invalid dependency
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADD_INSTANCE 1
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_REMOVE_INSTANCE 2
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_DEGRADED 5
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_REFRESH 6
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_RESTART 7
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_MAINT_OFF 8
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON 9
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_MAINT_ON_IMMEDIATE 10
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_DEPENDENCY_CYCLE 13
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_INVALID_DEPENDENCY 14
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_TYPE_ADMIN_DISABLE 15
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_INSTANCE_DISABLED 0
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_EVENT_INSTANCE_ENABLED 1
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * These values are ordered by severity of required restart, as we use
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * integer comparisons to determine error flow.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan RERR_NONE = 0, /* no error, restart, refresh */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan RERR_RESTART, /* transition due to restart */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan RERR_REFRESH /* transition due to refresh */
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * restarter_store_contract() and restarter_remove_contract() types
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amoretypedef enum {
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * restarter_bind_handle() registers a delegate with svc.startd to
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * begin consuming events.
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * On initial bind, the delgated restarter receives an event for each
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * instance it is responsible for, as if that instance was new.
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * callers must have superuser privileges
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * The event handler can return 0 for success, or EAGAIN to request
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * retry of event delivery. EAGAIN may be returned 3 times before the
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore * event is discarded.
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amoreint restarter_bind_handle(uint32_t, const char *,
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amore int (*event_handler)(restarter_event_t *), int,
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amorerestarter_event_type_t restarter_event_get_type(restarter_event_t *);
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amoreuint64_t restarter_event_get_seq(restarter_event_t *);
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amorevoid restarter_event_get_time(restarter_event_t *, hrtime_t *);
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amoressize_t restarter_event_get_instance(restarter_event_t *, char *, size_t);
3abb112f8485b33b6b9b52b340bede0a333c10bfGarrett D'Amorerestarter_event_handle_t *restarter_event_get_handle(restarter_event_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * The following functions work only on certain types of events.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * They fail with a return of -1 if they're called on an inappropriate event.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_event_get_enabled(restarter_event_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_event_get_current_states(restarter_event_t *,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan restarter_instance_state_t *, restarter_instance_state_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Functions for updating the repository.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * When setting state to "maintenance", callers of restarter_set_states() can
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * set aux_state to "service_request" to communicate that another service has
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * requested maintenance state for the target service.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Callers should use restarter_inst_validate_aux_fmri() to validate the fmri
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * of the requested service and pass "service_request" for aux_state when
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * calling restarter_set_states(). See inetd and startd for examples.
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_set_states(restarter_event_handle_t *, const char *,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan restarter_instance_state_t, restarter_instance_state_t,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan restarter_instance_state_t, restarter_instance_state_t, restarter_error_t,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan const char *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_event_publish_retry(evchan_t *, const char *, const char *,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan const char *, const char *, nvlist_t *, uint32_t);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_store_contract(scf_instance_t *, ctid_t,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_remove_contract(scf_instance_t *, ctid_t,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanssize_t restarter_state_to_string(restarter_instance_state_t, char *, size_t);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanrestarter_instance_state_t restarter_string_to_state(char *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#define RESTARTER_METHOD_CONTEXT_VERSION 6
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan int ngroups; /* -1 means use initgroups(). */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan char *resource_pool; /* NULL for project default */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan char *working_dir; /* NULL for :default */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan/* instance, restarter name, method name, command line, structure pointer */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanconst char *restarter_get_method_context(uint_t, scf_instance_t *,
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan scf_snapshot_t *, const char *, const char *, struct method_context **);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_set_method_context(struct method_context *, const char **);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanvoid restarter_free_method_context(struct method_context *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_is_null_method(const char *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_is_kill_method(const char *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_is_kill_proc_method(const char *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan/* Validate the inst fmri specified in restarter_actions/auxiliary_fmri */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_inst_validate_ractions_aux_fmri(scf_instance_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan/* Delete instance's restarter_actions/auxiliary_fmri property */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_inst_reset_ractions_aux_fmri(scf_instance_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan/* Get boolean value from instance's restarter_actions/auxiliary_tty */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_inst_ractions_from_tty(scf_instance_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan/* Delete instance's restarter/auxiliary_fmri property */
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_inst_reset_aux_fmri(scf_instance_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan * Set instance's restarter/auxiliary_fmri, value come from
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathanint restarter_inst_set_aux_fmri(scf_instance_t *);
4d0e50075058332ce0cd62bc2669a8a4dea45da0Sukumar Swaminathan#endif /* _LIBRESTART_H */