lrmd.h

Go to the documentation of this file.

/*
 * Copyright 2012-2021 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 LRMD__H
#  define LRMD__H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>      // bool
#include <glib.h>         // guint, GList
#include <crm_config.h>
#include <crm/services.h>

typedef struct lrmd_s lrmd_t;
typedef struct lrmd_key_value_s {
    char *key;
    char *value;
    struct lrmd_key_value_s *next;
} lrmd_key_value_t;

/* This should be bumped every time there is an incompatible change that
 * prevents older clients from connecting to this version of the server.
 */
#define LRMD_PROTOCOL_VERSION "1.1"

/* This is the version that the client version will actually be compared
 * against. This should be identical to LRMD_PROTOCOL_VERSION. However, we
 * accidentally bumped LRMD_PROTOCOL_VERSION in 6424a647 (1.1.15) when we didn't
 * need to, so for now it's different. If we ever have a truly incompatible
 * bump, we can drop this and compare against LRMD_PROTOCOL_VERSION.
 */
#define LRMD_MIN_PROTOCOL_VERSION "1.0"

/* *INDENT-OFF* */
#define DEFAULT_REMOTE_KEY_LOCATION PACEMAKER_CONFIG_DIR "/authkey"
#define ALT_REMOTE_KEY_LOCATION "/etc/corosync/authkey"
#define DEFAULT_REMOTE_PORT 3121
#define DEFAULT_REMOTE_USERNAME "lrmd"

#define F_LRMD_OPERATION        "lrmd_op"
#define F_LRMD_CLIENTNAME       "lrmd_clientname"
#define F_LRMD_IS_IPC_PROVIDER  "lrmd_is_ipc_provider"
#define F_LRMD_CLIENTID         "lrmd_clientid"
#define F_LRMD_PROTOCOL_VERSION "lrmd_protocol_version"
#define F_LRMD_REMOTE_MSG_TYPE  "lrmd_remote_msg_type"
#define F_LRMD_REMOTE_MSG_ID    "lrmd_remote_msg_id"
#define F_LRMD_CALLBACK_TOKEN   "lrmd_async_id"
#define F_LRMD_CALLID           "lrmd_callid"
#define F_LRMD_CALLOPTS         "lrmd_callopt"
#define F_LRMD_CALLDATA         "lrmd_calldata"
#define F_LRMD_RC               "lrmd_rc"
#define F_LRMD_EXEC_RC          "lrmd_exec_rc"
#define F_LRMD_OP_STATUS        "lrmd_exec_op_status"
#define F_LRMD_TIMEOUT          "lrmd_timeout"
#define F_LRMD_WATCHDOG         "lrmd_watchdog"
#define F_LRMD_CLASS            "lrmd_class"
#define F_LRMD_PROVIDER         "lrmd_provider"
#define F_LRMD_TYPE             "lrmd_type"
#define F_LRMD_ORIGIN           "lrmd_origin"

#define F_LRMD_RSC_RUN_TIME      "lrmd_run_time"
#define F_LRMD_RSC_RCCHANGE_TIME "lrmd_rcchange_time"
#define F_LRMD_RSC_EXEC_TIME     "lrmd_exec_time"
#define F_LRMD_RSC_QUEUE_TIME    "lrmd_queue_time"

#define F_LRMD_RSC_ID           "lrmd_rsc_id"
#define F_LRMD_RSC_ACTION       "lrmd_rsc_action"
#define F_LRMD_RSC_USERDATA_STR "lrmd_rsc_userdata_str"
#define F_LRMD_RSC_OUTPUT       "lrmd_rsc_output"
#define F_LRMD_RSC_EXIT_REASON  "lrmd_rsc_exit_reason"
#define F_LRMD_RSC_START_DELAY  "lrmd_rsc_start_delay"
#define F_LRMD_RSC_INTERVAL     "lrmd_rsc_interval"
#define F_LRMD_RSC_DELETED      "lrmd_rsc_deleted"
#define F_LRMD_RSC              "lrmd_rsc"

#define F_LRMD_ALERT_ID           "lrmd_alert_id"
#define F_LRMD_ALERT_PATH         "lrmd_alert_path"
#define F_LRMD_ALERT              "lrmd_alert"

#define LRMD_OP_RSC_REG           "lrmd_rsc_register"
#define LRMD_OP_RSC_EXEC          "lrmd_rsc_exec"
#define LRMD_OP_RSC_CANCEL        "lrmd_rsc_cancel"
#define LRMD_OP_RSC_UNREG         "lrmd_rsc_unregister"
#define LRMD_OP_RSC_INFO          "lrmd_rsc_info"
#define LRMD_OP_RSC_METADATA      "lrmd_rsc_metadata"
#define LRMD_OP_POKE              "lrmd_rsc_poke"
#define LRMD_OP_NEW_CLIENT        "lrmd_rsc_new_client"
#define LRMD_OP_CHECK             "lrmd_check"
#define LRMD_OP_ALERT_EXEC        "lrmd_alert_exec"
#define LRMD_OP_GET_RECURRING     "lrmd_get_recurring"

#define LRMD_IPC_OP_NEW           "new"
#define LRMD_IPC_OP_DESTROY       "destroy"
#define LRMD_IPC_OP_EVENT         "event"
#define LRMD_IPC_OP_REQUEST       "request"
#define LRMD_IPC_OP_RESPONSE      "response"
#define LRMD_IPC_OP_SHUTDOWN_REQ  "shutdown_req"
#define LRMD_IPC_OP_SHUTDOWN_ACK  "shutdown_ack"
#define LRMD_IPC_OP_SHUTDOWN_NACK "shutdown_nack"

#define F_LRMD_IPC_OP           "lrmd_ipc_op"
#define F_LRMD_IPC_IPC_SERVER   "lrmd_ipc_server"
#define F_LRMD_IPC_SESSION      "lrmd_ipc_session"
#define F_LRMD_IPC_CLIENT       "lrmd_ipc_client"
#define F_LRMD_IPC_USER         "lrmd_ipc_user"
#define F_LRMD_IPC_MSG          "lrmd_ipc_msg"
#define F_LRMD_IPC_MSG_ID       "lrmd_ipc_msg_id"
#define F_LRMD_IPC_MSG_FLAGS    "lrmd_ipc_msg_flags"

#define T_LRMD           "lrmd"
#define T_LRMD_REPLY     "lrmd_reply"
#define T_LRMD_NOTIFY    "lrmd_notify"
#define T_LRMD_IPC_PROXY "lrmd_ipc_proxy"
#define T_LRMD_RSC_OP    "lrmd_rsc_op"
/* *INDENT-ON* */

lrmd_t *lrmd_api_new(void);

lrmd_t *lrmd_remote_api_new(const char *nodename, const char *server, int port);

bool lrmd_dispatch(lrmd_t * lrmd);

int lrmd_poll(lrmd_t * lrmd, int timeout);

void lrmd_api_delete(lrmd_t * lrmd);
lrmd_key_value_t *lrmd_key_value_add(lrmd_key_value_t * kvp, const char *key, const char *value);

/* *INDENT-OFF* */
/* Reserved for future use */
enum lrmd_call_options {
    lrmd_opt_none = 0x00000000,
    /* lrmd_opt_sync_call = 0x00000001, //Not implemented, patches welcome. */
    lrmd_opt_notify_orig_only = 0x00000002,
    lrmd_opt_drop_recurring = 0x00000003,
    lrmd_opt_notify_changes_only = 0x00000004,
};

enum lrmd_callback_event {
    lrmd_event_register,
    lrmd_event_unregister,
    lrmd_event_exec_complete,
    lrmd_event_disconnect,
    lrmd_event_connect,
    lrmd_event_poke,
    lrmd_event_new_client,
};

/* *INDENT-ON* */

typedef struct lrmd_event_data_s {
    enum lrmd_callback_event type;

    const char *rsc_id;
    const char *op_type;
    const char *user_data;

    int call_id;
    int timeout;
    guint interval_ms;
    int start_delay;
    int rsc_deleted;

    enum ocf_exitcode rc;
    int op_status;
    const char *output;
    unsigned int t_run;
    unsigned int t_rcchange;
    unsigned int exec_time;
    unsigned int queue_time;

    int connection_rc;

    /* This is a GHashTable containing the
     * parameters given to the operation */
    void *params;

    const char *remote_nodename;

    const char *exit_reason;
} lrmd_event_data_t;

lrmd_event_data_t *lrmd_new_event(const char *rsc_id, const char *task,
                                  guint interval_ms);
lrmd_event_data_t *lrmd_copy_event(lrmd_event_data_t * event);
void lrmd_free_event(lrmd_event_data_t * event);

typedef struct lrmd_rsc_info_s {
    char *id;
    char *type;
    char *standard;
    char *provider;
} lrmd_rsc_info_t;

typedef struct lrmd_op_info_s {
    char *rsc_id;
    char *action;
    char *interval_ms_s;
    char *timeout_ms_s;
} lrmd_op_info_t;

lrmd_rsc_info_t *lrmd_new_rsc_info(const char *rsc_id, const char *standard,
                                   const char *provider, const char *type);
lrmd_rsc_info_t *lrmd_copy_rsc_info(lrmd_rsc_info_t * rsc_info);
void lrmd_free_rsc_info(lrmd_rsc_info_t * rsc_info);
void lrmd_free_op_info(lrmd_op_info_t *op_info);

typedef void (*lrmd_event_callback) (lrmd_event_data_t * event);

typedef struct lrmd_list_s {
    const char *val;
    struct lrmd_list_s *next;
} lrmd_list_t;

void lrmd_list_freeall(lrmd_list_t * head);
void lrmd_key_value_freeall(lrmd_key_value_t * head);

typedef struct lrmd_api_operations_s {
    int (*connect) (lrmd_t * lrmd, const char *client_name, int *fd);

    int (*connect_async) (lrmd_t * lrmd, const char *client_name, int timeout /*ms */ );

    int (*is_connected) (lrmd_t * lrmd);

    int (*poke_connection) (lrmd_t * lrmd);

    int (*disconnect) (lrmd_t * lrmd);

    int (*register_rsc) (lrmd_t * lrmd,
                         const char *rsc_id,
                         const char *standard,
                         const char *provider, const char *agent, enum lrmd_call_options options);

    lrmd_rsc_info_t *(*get_rsc_info) (lrmd_t * lrmd,
                                      const char *rsc_id, enum lrmd_call_options options);

    int (*get_recurring_ops) (lrmd_t *lrmd, const char *rsc_id, int timeout_ms,
                              enum lrmd_call_options options, GList **output);

    int (*unregister_rsc) (lrmd_t * lrmd, const char *rsc_id, enum lrmd_call_options options);

    void (*set_callback) (lrmd_t * lrmd, lrmd_event_callback callback);

    int (*exec) (lrmd_t * lrmd, const char *rsc_id, const char *action, const char *userdata,   /* userdata string given back in event notification */
                 guint interval_ms,
                 int timeout,   /* ms */
                 int start_delay,       /* ms */
                 enum lrmd_call_options options, lrmd_key_value_t * params);    /* ownership of params is given up to api here */

    int (*cancel) (lrmd_t *lrmd, const char *rsc_id, const char *action,
                   guint interval_ms);

    int (*get_metadata) (lrmd_t * lrmd,
                         const char *standard,
                         const char *provider,
                         const char *agent, char **output, enum lrmd_call_options options);

    int (*list_agents) (lrmd_t * lrmd, lrmd_list_t ** agents,
                        const char *standard, const char *provider);

    int (*list_ocf_providers) (lrmd_t * lrmd, const char *agent, lrmd_list_t ** providers);

    int (*list_standards) (lrmd_t * lrmd, lrmd_list_t ** standards);

    int (*exec_alert) (lrmd_t *lrmd, const char *alert_id,
                       const char *alert_path, int timeout, /* ms */
                       lrmd_key_value_t *params); /* ownership of params is given up to api here */

    int (*get_metadata_params) (lrmd_t *lrmd, const char *standard,
                                const char *provider, const char *agent,
                                char **output, enum lrmd_call_options options,
                                lrmd_key_value_t *params);

} lrmd_api_operations_t;

struct lrmd_s {
    lrmd_api_operations_t *cmds;
    void *lrmd_private;
};

static inline const char *
lrmd_event_type2str(enum lrmd_callback_event type)
{
    switch (type) {
        case lrmd_event_register:
            return "register";
        case lrmd_event_unregister:
            return "unregister";
        case lrmd_event_exec_complete:
            return "exec_complete";
        case lrmd_event_disconnect:
            return "disconnect";
        case lrmd_event_connect:
            return "connect";
        case lrmd_event_poke:
            return "poke";
        case lrmd_event_new_client:
            return "new_client";
    }
    return "unknown";
}

#ifdef __cplusplus
}
#endif

#endif