stonith-ng.h

Go to the documentation of this file.

/*
 * Copyright 2004-2025 the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under the GNU Lesser General Public License
 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
 */
 
#ifndef PCMK__CRM_STONITH_NG__H
#  define PCMK__CRM_STONITH_NG__H
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* IMPORTANT: dlm source code includes this file directly. Until dlm v4.2.0
 * (commit 5afd9fdc), dlm did not have access to other Pacemaker headers on its
 * include path. This file should *not* include any other Pacemaker headers
 * until we decide that we no longer need to support dlm versions older than
 * v4.2.0.
 *
 * @COMPAT Remove this restriction and take any opportunities to simplify code
 * when possible.
 */
 
#  include <dlfcn.h>
#  include <errno.h>
#  include <stdbool.h>  // bool
#  include <stdint.h>   // uint32_t
#  include <time.h>     // time_t
 
// @TODO Keep this definition but make it internal
enum stonith_state {
    stonith_connected_command,
    stonith_connected_query,
    stonith_disconnected,
};
 
// @TODO Keep this definition but make it internal
enum stonith_call_options {
    // No options
    st_opt_none                 = 0,
 
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
    st_opt_verbose              = (1 << 0),
#endif
 
    // The fencing target is allowed to execute the request
    st_opt_allow_self_fencing   = (1 << 1),
 
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
    st_opt_allow_suicide        = st_opt_allow_self_fencing,
#endif
 
    // Used internally to indicate that request is manual fence confirmation
    // \internal Do not use
    st_opt_manual_ack           = (1 << 3),
 
    // Do not return any reply from server
    st_opt_discard_reply        = (1 << 4),
 
    // Used internally to indicate that request requires a fencing topology
    // \internal Do not use
    st_opt_topology             = (1 << 6),
 
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
    st_opt_scope_local          = (1 << 8),
#endif
 
    // Interpret target as node cluster layer ID instead of name
    st_opt_cs_nodeid            = (1 << 9),
 
    // Wait for request to be completed before returning
    st_opt_sync_call            = (1 << 12),
 
    // Request that server send an update with optimal callback timeout
    st_opt_timeout_updates      = (1 << 13),
 
    // Invoke callback only if request succeeded
    st_opt_report_only_success  = (1 << 14),
 
    // For a fence history request, request that the history be cleared
    st_opt_cleanup              = (1 << 19),
 
    // For a fence history request, broadcast the request to all nodes
    st_opt_broadcast            = (1 << 20),
};
 
// Order matters here, do not change values
// @TODO Keep this definition but make it internal
enum op_state {
    st_query,       
    st_exec,        
    st_done,        
    st_duplicate,   
    st_failed,      
};
 
// @TODO Keep this definition but make it internal
enum stonith_namespace {
    st_namespace_invalid,   
    st_namespace_any,       
 
    // Implemented internally by Pacemaker
    st_namespace_internal,  
 
    /* Neither of these projects are active any longer, but the fence agent
     * interfaces they created are still in use and supported by Pacemaker.
     */
    // Red Hat Cluster Suite compatible
    st_namespace_rhcs,      
 
    // Linux-HA compatible
    st_namespace_lha,       
};
 
/* @COMPAT Drop this and use a GList/GSList of pcmk_nvpair_t or a GHashtable as
 * appropriate
 */
typedef struct stonith_key_value_s {
    char *key;
    char *value;
    struct stonith_key_value_s *next;
} stonith_key_value_t;
 
// @TODO Keep this definition but make it internal
typedef struct stonith_history_s {
    char *target;
    char *action;
    char *origin;
    char *delegate;
    char *client;
    int state;
    time_t completed;
    struct stonith_history_s *next;
    long completed_nsec;
    char *exit_reason;
} stonith_history_t;
 
// @TODO Keep this typedef but rename it and make it internal
typedef struct stonith_s stonith_t;
 
// @TODO Keep this definition but make it internal
typedef struct stonith_event_s {
    char *id;
    char *operation;
    int result;
    char *origin;
    char *target;
    char *action;
    char *executioner;
 
    char *device;
 
    // Name of the client that initiated the action
    char *client_origin;
 
    void *opaque;
} stonith_event_t;
 
// @TODO Keep this definition but make it internal
typedef struct stonith_callback_data_s {
    int rc;
    int call_id;
    void *userdata;
 
    void *opaque;
} stonith_callback_data_t;
 
// @TODO Keep this object but make it internal
typedef struct stonith_api_operations_s {
    int (*free) (stonith_t *st);
 
    int (*connect) (stonith_t *st, const char *name, int *stonith_fd);
 
    int (*disconnect)(stonith_t *st);
 
    int (*remove_device)(stonith_t *st, int options, const char *name);
 
    int (*register_device)(stonith_t *st, int options, const char *id,
                           const char *namespace_s, const char *agent,
                           const stonith_key_value_t *params);
 
    int (*remove_level)(stonith_t *st, int options, const char *node,
                        int level);
 
    int (*register_level)(stonith_t *st, int options, const char *node,
                          int level, const stonith_key_value_t *device_list);
 
    int (*metadata)(stonith_t *stonith, int call_options, const char *agent,
                    const char *namespace_s, char **output, int timeout_sec);
 
    int (*list_agents)(stonith_t *stonith, int call_options,
                       const char *namespace_s, stonith_key_value_t **devices,
                       int timeout);
 
    int (*list)(stonith_t *stonith, int call_options, const char *id,
                char **list_info, int timeout);
 
    int (*monitor)(stonith_t *stonith, int call_options, const char *id,
                   int timeout);
 
    int (*status)(stonith_t *stonith, int call_options, const char *id,
                  const char *port, int timeout);
 
    int (*query)(stonith_t *stonith, int call_options, const char *target,
                 stonith_key_value_t **devices, int timeout);
 
    int (*fence)(stonith_t *stonith, int call_options, const char *node,
                 const char *action, int timeout, int tolerance);
 
    int (*confirm)(stonith_t *stonith, int call_options, const char *target);
 
    int (*history)(stonith_t *stonith, int call_options, const char *node,
                   stonith_history_t **history, int timeout);
 
    int (*register_notification)(stonith_t *stonith, const char *event,
                                 void (*callback)(stonith_t *st,
                                                  stonith_event_t *e));
 
    int (*remove_notification)(stonith_t *stonith, const char *event);
 
    int (*register_callback)(stonith_t *stonith, int call_id, int timeout,
                             int options, void *user_data,
                             const char *callback_name,
                             void (*callback)(stonith_t *st,
                                              stonith_callback_data_t *data));
 
    int (*remove_callback)(stonith_t *stonith, int call_id, bool all_callbacks);
 
    int (*remove_level_full)(stonith_t *st, int options,
                             const char *node, const char *pattern,
                             const char *attr, const char *value, int level);
 
    int (*register_level_full)(stonith_t *st, int options,
                               const char *node, const char *pattern,
                               const char *attr, const char *value, int level,
                               const stonith_key_value_t *device_list);
 
    int (*validate)(stonith_t *st, int call_options, const char *rsc_id,
                    const char *namespace_s, const char *agent,
                    const stonith_key_value_t *params, int timeout,
                    char **output, char **error_output);
 
    int (*fence_with_delay)(stonith_t *stonith, int call_options,
                            const char *node, const char *action, int timeout,
                            int tolerance, int delay);
 
} stonith_api_operations_t;
 
// @TODO Keep this object but make it internal
struct stonith_s {
    enum stonith_state state;
    int call_id;
    void *st_private;
    stonith_api_operations_t *cmds;
};
 
/* Basic helpers that allows nodes to be fenced and the history to be
 * queried without mainloop or the caller understanding the full API
 *
 * At least one of nodeid and uname are required
 *
 * NOTE: dlm (as of at least 4.3.0) uses these (via the helper functions below)
 */
int stonith_api_kick(uint32_t nodeid, const char *uname, int timeout, bool off);
time_t stonith_api_time(uint32_t nodeid, const char *uname, bool in_progress);
 
/*
 * Helpers for using the above functions without install-time dependencies
 *
 * Usage:
 *  #include <crm/stonith-ng.h>
 *
 * To turn a node off by corosync nodeid:
 *  stonith_api_kick_helper(nodeid, 120, 1);
 *
 * To check the last fence date/time (also by nodeid):
 *  last = stonith_api_time_helper(nodeid, 0);
 *
 * To check if fencing is in progress:
 *  if(stonith_api_time_helper(nodeid, 1) > 0) { ... }
 *
 * eg.
 
 #include <stdio.h>
 #include <time.h>
 #include <crm/stonith-ng.h>
 int
 main(int argc, char ** argv)
 {
     int rc = 0;
     int nodeid = 102;
 
     rc = stonith_api_time_helper(nodeid, 0);
     printf("%d last fenced at %s\n", nodeid, ctime(rc));
 
     rc = stonith_api_kick_helper(nodeid, 120, 1);
     printf("%d fence result: %d\n", nodeid, rc);
 
     rc = stonith_api_time_helper(nodeid, 0);
     printf("%d last fenced at %s\n", nodeid, ctime(rc));
 
     return 0;
 }
 
 */
 
#define STONITH_LIBRARY "libstonithd.so.56"
 
// NOTE: dlm (as of at least 4.3.0) uses these (via the helper functions below)
typedef int (*st_api_kick_fn) (int nodeid, const char *uname, int timeout, bool off);
typedef time_t (*st_api_time_fn) (int nodeid, const char *uname, bool in_progress);
 
// NOTE: dlm (as of at least 4.3.0) uses this
static inline int
stonith_api_kick_helper(uint32_t nodeid, int timeout, bool off)
{
    static void *st_library = NULL;
    static st_api_kick_fn st_kick_fn;
 
    if (st_library == NULL) {
        st_library = dlopen(STONITH_LIBRARY, RTLD_LAZY);
    }
    if (st_library && st_kick_fn == NULL) {
        st_kick_fn = (st_api_kick_fn) dlsym(st_library, "stonith_api_kick");
    }
    if (st_kick_fn == NULL) {
#ifdef ELIBACC
        return -ELIBACC;
#else
        return -ENOSYS;
#endif
    }
 
    return (*st_kick_fn) (nodeid, NULL, timeout, off);
}
 
// NOTE: dlm (as of at least 4.3.0) uses this
static inline time_t
stonith_api_time_helper(uint32_t nodeid, bool in_progress)
{
    static void *st_library = NULL;
    static st_api_time_fn st_time_fn;
 
    if (st_library == NULL) {
        st_library = dlopen(STONITH_LIBRARY, RTLD_LAZY);
    }
    if (st_library && st_time_fn == NULL) {
        st_time_fn = (st_api_time_fn) dlsym(st_library, "stonith_api_time");
    }
    if (st_time_fn == NULL) {
        return 0;
    }
 
    return (*st_time_fn) (nodeid, NULL, in_progress);
}
 
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
 
/* Normally we'd put this section in a separate file (crm/fencing/compat.h), but
 * we can't do that for the reason noted at the top of this file. That does mean
 * we have to duplicate these declarations where they're implemented.
 */
 
stonith_t *stonith_api_new(void);
 
void stonith_api_delete(stonith_t *stonith);
 
void stonith_dump_pending_callbacks(stonith_t *stonith);
 
bool stonith_dispatch(stonith_t *stonith_api);
 
stonith_key_value_t *stonith_key_value_add(stonith_key_value_t *kvp,
                                           const char *key, const char *value);
 
void stonith_key_value_freeall(stonith_key_value_t *head, int keys, int values);
 
void stonith_history_free(stonith_history_t *head);
 
int stonith_api_connect_retry(stonith_t *st, const char *name,
                              int max_attempts);
 
const char *stonith_op_state_str(enum op_state state);
 
bool stonith_agent_exists(const char *agent, int timeout);
 
const char *stonith_action_str(const char *action);
 
enum stonith_namespace stonith_text2namespace(const char *namespace_s);
 
const char *stonith_namespace2text(enum stonith_namespace st_namespace);
 
enum stonith_namespace stonith_get_namespace(const char *agent,
                                             const char *namespace_s);
 
#endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
 
#ifdef __cplusplus
}
#endif
 
#endif