root/include/crm/lrmd.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. lrmd_event_type2str

   1 /*
   2  * Copyright 2012-2021 the Pacemaker project contributors
   3  *
   4  * The version control history for this file may have further details.
   5  *
   6  * This source code is licensed under the GNU Lesser General Public License
   7  * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
   8  */
   9 
  10 #ifndef PCMK__CRM_LRMD__H
  11 #  define PCMK__CRM_LRMD__H
  12 
  13 #include <stdbool.h>      // bool
  14 #include <glib.h>         // guint, GList
  15 #include <crm_config.h>
  16 #include <crm/services.h>
  17 
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21 
  22 /**
  23  * \file
  24  * \brief Resource agent executor
  25  * \ingroup lrmd
  26  */
  27 
  28 typedef struct lrmd_s lrmd_t;
  29 typedef struct lrmd_key_value_s {
  30     char *key;
  31     char *value;
  32     struct lrmd_key_value_s *next;
  33 } lrmd_key_value_t;
  34 
  35 /* This should be bumped every time there is an incompatible change that
  36  * prevents older clients from connecting to this version of the server.
  37  */
  38 #define LRMD_PROTOCOL_VERSION "1.1"
  39 
  40 /* This is the version that the client version will actually be compared
  41  * against. This should be identical to LRMD_PROTOCOL_VERSION. However, we
  42  * accidentally bumped LRMD_PROTOCOL_VERSION in 6424a647 (1.1.15) when we didn't
  43  * need to, so for now it's different. If we ever have a truly incompatible
  44  * bump, we can drop this and compare against LRMD_PROTOCOL_VERSION.
  45  */
  46 #define LRMD_MIN_PROTOCOL_VERSION "1.0"
  47 
  48 /* *INDENT-OFF* */
  49 #define DEFAULT_REMOTE_KEY_LOCATION PACEMAKER_CONFIG_DIR "/authkey"
  50 #define ALT_REMOTE_KEY_LOCATION "/etc/corosync/authkey"
  51 #define DEFAULT_REMOTE_PORT 3121
  52 #define DEFAULT_REMOTE_USERNAME "lrmd"
  53 
  54 #define F_LRMD_OPERATION        "lrmd_op"
  55 #define F_LRMD_CLIENTNAME       "lrmd_clientname"
  56 #define F_LRMD_IS_IPC_PROVIDER  "lrmd_is_ipc_provider"
  57 #define F_LRMD_CLIENTID         "lrmd_clientid"
  58 #define F_LRMD_PROTOCOL_VERSION "lrmd_protocol_version"
  59 #define F_LRMD_REMOTE_MSG_TYPE  "lrmd_remote_msg_type"
  60 #define F_LRMD_REMOTE_MSG_ID    "lrmd_remote_msg_id"
  61 #define F_LRMD_CALLBACK_TOKEN   "lrmd_async_id"
  62 #define F_LRMD_CALLID           "lrmd_callid"
  63 #define F_LRMD_CALLOPTS         "lrmd_callopt"
  64 #define F_LRMD_CALLDATA         "lrmd_calldata"
  65 #define F_LRMD_RC               "lrmd_rc"
  66 #define F_LRMD_EXEC_RC          "lrmd_exec_rc"
  67 #define F_LRMD_OP_STATUS        "lrmd_exec_op_status"
  68 #define F_LRMD_TIMEOUT          "lrmd_timeout"
  69 #define F_LRMD_WATCHDOG         "lrmd_watchdog"
  70 #define F_LRMD_CLASS            "lrmd_class"
  71 #define F_LRMD_PROVIDER         "lrmd_provider"
  72 #define F_LRMD_TYPE             "lrmd_type"
  73 #define F_LRMD_ORIGIN           "lrmd_origin"
  74 
  75 #define F_LRMD_RSC_RUN_TIME      "lrmd_run_time"
  76 #define F_LRMD_RSC_RCCHANGE_TIME "lrmd_rcchange_time"
  77 #define F_LRMD_RSC_EXEC_TIME     "lrmd_exec_time"
  78 #define F_LRMD_RSC_QUEUE_TIME    "lrmd_queue_time"
  79 
  80 #define F_LRMD_RSC_ID           "lrmd_rsc_id"
  81 #define F_LRMD_RSC_ACTION       "lrmd_rsc_action"
  82 #define F_LRMD_RSC_USERDATA_STR "lrmd_rsc_userdata_str"
  83 #define F_LRMD_RSC_OUTPUT       "lrmd_rsc_output"
  84 #define F_LRMD_RSC_EXIT_REASON  "lrmd_rsc_exit_reason"
  85 #define F_LRMD_RSC_START_DELAY  "lrmd_rsc_start_delay"
  86 #define F_LRMD_RSC_INTERVAL     "lrmd_rsc_interval"
  87 #define F_LRMD_RSC_DELETED      "lrmd_rsc_deleted"
  88 #define F_LRMD_RSC              "lrmd_rsc"
  89 
  90 #define F_LRMD_ALERT_ID           "lrmd_alert_id"
  91 #define F_LRMD_ALERT_PATH         "lrmd_alert_path"
  92 #define F_LRMD_ALERT              "lrmd_alert"
  93 
  94 #define LRMD_OP_RSC_REG           "lrmd_rsc_register"
  95 #define LRMD_OP_RSC_EXEC          "lrmd_rsc_exec"
  96 #define LRMD_OP_RSC_CANCEL        "lrmd_rsc_cancel"
  97 #define LRMD_OP_RSC_UNREG         "lrmd_rsc_unregister"
  98 #define LRMD_OP_RSC_INFO          "lrmd_rsc_info"
  99 #define LRMD_OP_RSC_METADATA      "lrmd_rsc_metadata"
 100 #define LRMD_OP_POKE              "lrmd_rsc_poke"
 101 #define LRMD_OP_NEW_CLIENT        "lrmd_rsc_new_client"
 102 #define LRMD_OP_CHECK             "lrmd_check"
 103 #define LRMD_OP_ALERT_EXEC        "lrmd_alert_exec"
 104 #define LRMD_OP_GET_RECURRING     "lrmd_get_recurring"
 105 
 106 #define LRMD_IPC_OP_NEW           "new"
 107 #define LRMD_IPC_OP_DESTROY       "destroy"
 108 #define LRMD_IPC_OP_EVENT         "event"
 109 #define LRMD_IPC_OP_REQUEST       "request"
 110 #define LRMD_IPC_OP_RESPONSE      "response"
 111 #define LRMD_IPC_OP_SHUTDOWN_REQ  "shutdown_req"
 112 #define LRMD_IPC_OP_SHUTDOWN_ACK  "shutdown_ack"
 113 #define LRMD_IPC_OP_SHUTDOWN_NACK "shutdown_nack"
 114 
 115 #define F_LRMD_IPC_OP           "lrmd_ipc_op"
 116 #define F_LRMD_IPC_IPC_SERVER   "lrmd_ipc_server"
 117 #define F_LRMD_IPC_SESSION      "lrmd_ipc_session"
 118 #define F_LRMD_IPC_CLIENT       "lrmd_ipc_client"
 119 #define F_LRMD_IPC_USER         "lrmd_ipc_user"
 120 #define F_LRMD_IPC_MSG          "lrmd_ipc_msg"
 121 #define F_LRMD_IPC_MSG_ID       "lrmd_ipc_msg_id"
 122 #define F_LRMD_IPC_MSG_FLAGS    "lrmd_ipc_msg_flags"
 123 
 124 #define T_LRMD           "lrmd"
 125 #define T_LRMD_REPLY     "lrmd_reply"
 126 #define T_LRMD_NOTIFY    "lrmd_notify"
 127 #define T_LRMD_IPC_PROXY "lrmd_ipc_proxy"
 128 #define T_LRMD_RSC_OP    "lrmd_rsc_op"
 129 /* *INDENT-ON* */
 130 
 131 /*!
 132  * \brief Create a new connection to the local executor
 133  */
 134 lrmd_t *lrmd_api_new(void);
 135 
 136 /*!
 137  * \brief Create a new TLS connection to a remote executor
 138  *
 139  * \param nodename  name of remote node identified with this connection
 140  * \param server    name of server to connect to
 141  * \param port      port number to connect to
 142  *
 143  * \note nodename and server may be the same value.
 144  */
 145 lrmd_t *lrmd_remote_api_new(const char *nodename, const char *server, int port);
 146 
 147 /*!
 148  * \brief Use after lrmd_poll returns 1 to read and dispatch a message
 149  *
 150  * \param[in,out] lrmd  Executor connection object
 151  *
 152  * \return TRUE if connection is still up, FALSE if disconnected
 153  */
 154 bool lrmd_dispatch(lrmd_t * lrmd);
 155 
 156 /*!
 157  * \brief Poll for a specified timeout period to determine if a message
 158  *        is ready for dispatch
 159  *
 160  * \retval 1               Message is ready
 161  * \retval 0               Timeout occurred
 162  * \retval negative errno  Error occurred
 163  */
 164 int lrmd_poll(lrmd_t * lrmd, int timeout);
 165 
 166 /*!
 167  * \brief Destroy executor connection object
 168  */
 169 void lrmd_api_delete(lrmd_t * lrmd);
 170 lrmd_key_value_t *lrmd_key_value_add(lrmd_key_value_t * kvp, const char *key, const char *value);
 171 
 172 /* *INDENT-OFF* */
 173 /* Reserved for future use */
 174 enum lrmd_call_options {
 175     lrmd_opt_none = 0x00000000,
 176     /* lrmd_opt_sync_call = 0x00000001, //Not implemented, patches welcome. */
 177     /*! Only notify the client originating a exec() the results */
 178     lrmd_opt_notify_orig_only = 0x00000002,
 179     /*! Drop recurring operations initiated by a client when client disconnects.
 180      * This call_option is only valid when registering a resource. When used
 181      * remotely with the pacemaker_remote daemon, this option means that recurring
 182      * operations will be dropped once all the remote connections disconnect. */
 183     lrmd_opt_drop_recurring = 0x00000003,
 184     /*! Send notifications for recurring operations only when the result changes */
 185     lrmd_opt_notify_changes_only = 0x00000004,
 186 };
 187 
 188 enum lrmd_callback_event {
 189     lrmd_event_register,
 190     lrmd_event_unregister,
 191     lrmd_event_exec_complete,
 192     lrmd_event_disconnect,
 193     lrmd_event_connect,
 194     lrmd_event_poke,
 195     lrmd_event_new_client,
 196 };
 197 
 198 /* *INDENT-ON* */
 199 
 200 typedef struct lrmd_event_data_s {
 201     /*! Type of event, register, unregister, call_completed... */
 202     enum lrmd_callback_event type;
 203 
 204     /*! The resource this event occurred on. */
 205     const char *rsc_id;
 206     /*! The action performed, start, stop, monitor... */
 207     const char *op_type;
 208     /*! The user data passed by caller of exec() API function */
 209     const char *user_data;
 210 
 211     /*! The client api call id associated with this event */
 212     int call_id;
 213     /*! The operation's timeout period in ms. */
 214     int timeout;
 215     /*! The operation's recurring interval in ms. */
 216     guint interval_ms;
 217     /*! The operation's start delay value in ms. */
 218     int start_delay;
 219     /*! This operation that just completed is on a deleted rsc. */
 220     int rsc_deleted;
 221 
 222     /*! The executed ra return code mapped to OCF */
 223     enum ocf_exitcode rc;
 224     /*! The executor status returned for exec_complete events */
 225     int op_status;
 226     /*! stdout from resource agent operation */
 227     const char *output;
 228     /*! Timestamp of when op ran */
 229     unsigned int t_run;
 230     /*! Timestamp of last rc change */
 231     unsigned int t_rcchange;
 232     /*! Time in length op took to execute */
 233     unsigned int exec_time;
 234     /*! Time in length spent in queue */
 235     unsigned int queue_time;
 236 
 237     /*! int connection result. Used for connection and poke events */
 238     int connection_rc;
 239 
 240     /* This is a GHashTable containing the
 241      * parameters given to the operation */
 242     void *params;
 243 
 244     /*! client node name associated with this connection
 245      * (used to match actions to the proper client when there are multiple)
 246      */
 247     const char *remote_nodename;
 248 
 249     /*! exit failure reason string from resource agent operation */
 250     const char *exit_reason;
 251 } lrmd_event_data_t;
 252 
 253 lrmd_event_data_t *lrmd_new_event(const char *rsc_id, const char *task,
 254                                   guint interval_ms);
 255 lrmd_event_data_t *lrmd_copy_event(lrmd_event_data_t * event);
 256 void lrmd_free_event(lrmd_event_data_t * event);
 257 
 258 typedef struct lrmd_rsc_info_s {
 259     char *id;
 260     char *type;
 261     char *standard;
 262     char *provider;
 263 } lrmd_rsc_info_t;
 264 
 265 typedef struct lrmd_op_info_s {
 266     char *rsc_id;
 267     char *action;
 268     char *interval_ms_s;
 269     char *timeout_ms_s;
 270 } lrmd_op_info_t;
 271 
 272 lrmd_rsc_info_t *lrmd_new_rsc_info(const char *rsc_id, const char *standard,
 273                                    const char *provider, const char *type);
 274 lrmd_rsc_info_t *lrmd_copy_rsc_info(lrmd_rsc_info_t * rsc_info);
 275 void lrmd_free_rsc_info(lrmd_rsc_info_t * rsc_info);
 276 void lrmd_free_op_info(lrmd_op_info_t *op_info);
 277 
 278 typedef void (*lrmd_event_callback) (lrmd_event_data_t * event);
 279 
 280 typedef struct lrmd_list_s {
 281     const char *val;
 282     struct lrmd_list_s *next;
 283 } lrmd_list_t;
 284 
 285 void lrmd_list_freeall(lrmd_list_t * head);
 286 void lrmd_key_value_freeall(lrmd_key_value_t * head);
 287 
 288 typedef struct lrmd_api_operations_s {
 289     /*!
 290      * \brief Connect to an executor
 291      *
 292      * \return Legacy Pacemaker return code
 293      */
 294     int (*connect) (lrmd_t * lrmd, const char *client_name, int *fd);
 295 
 296     /*!
 297      * \brief Initiate an executor connection without blocking
 298      *
 299      * \return Legacy Pacemaker return code (if pcmk_ok, the event callback will
 300      *         be called later with the result)
 301      * \note This function requires a mainloop.
 302      */
 303     int (*connect_async) (lrmd_t * lrmd, const char *client_name, int timeout /*ms */ );
 304 
 305     /*!
 306      * \brief Check whether connection to executor daemon is (still) active
 307      *
 308      * \return 1 if the executor connection is active, 0 otherwise
 309      */
 310     int (*is_connected) (lrmd_t * lrmd);
 311 
 312     /*!
 313      * \brief Poke executor connection to verify it is still capable of serving requests
 314      * \note The response comes in the form of a poke event to the callback. 
 315      *
 316      * \return Legacy Pacemaker return code (if pcmk_ok, the event callback will
 317      *         be called later with the result)
 318      */
 319     int (*poke_connection) (lrmd_t * lrmd);
 320 
 321     /*!
 322      * \brief Disconnect from the executor.
 323      *
 324      * \return Legacy Pacemaker return code
 325      */
 326     int (*disconnect) (lrmd_t * lrmd);
 327 
 328     /*!
 329      * \brief Register a resource with the executor.
 330      *
 331      * \note Synchronous, guaranteed to occur in daemon before function returns.
 332      *
 333      * \return Legacy Pacemaker return code
 334      */
 335     int (*register_rsc) (lrmd_t * lrmd,
 336                          const char *rsc_id,
 337                          const char *standard,
 338                          const char *provider, const char *agent, enum lrmd_call_options options);
 339 
 340     /*!
 341      * \brief Retrieve a resource's registration information
 342      *
 343      * \return Resource information on success, otherwise NULL
 344      */
 345     lrmd_rsc_info_t *(*get_rsc_info) (lrmd_t * lrmd,
 346                                       const char *rsc_id, enum lrmd_call_options options);
 347 
 348     /*!
 349      * \brief Retrieve registered recurring operations
 350      *
 351      * \return Legacy Pacemaker return code
 352      */
 353     int (*get_recurring_ops) (lrmd_t *lrmd, const char *rsc_id, int timeout_ms,
 354                               enum lrmd_call_options options, GList **output);
 355 
 356     /*!
 357      * \brief Unregister a resource from the executor.
 358      *
 359      * \note All pending and recurring operations will be cancelled
 360      *       automatically.
 361      *
 362      * \note Synchronous, guaranteed to occur in daemon before function returns.
 363      *
 364      * \return Legacy Pacemaker return code (of particular interest, EINPROGRESS
 365      *         means that operations are in progress for the resource, and the
 366      *         unregistration will be done when they complete)
 367      */
 368     int (*unregister_rsc) (lrmd_t * lrmd, const char *rsc_id, enum lrmd_call_options options);
 369 
 370     /*!
 371      * \brief Set a callback for executor events
 372      */
 373     void (*set_callback) (lrmd_t * lrmd, lrmd_event_callback callback);
 374 
 375     /*!
 376      * \brief Issue a command on a resource
 377      *
 378      * \return A call ID for the action on success (in which case the action is
 379      *         queued in the executor, and the event callback will be called
 380      *         later with the result), otherwise a negative legacy Pacemaker
 381      *         return code
 382      *
 383      * \note exec() and cancel() operations on an individual resource are
 384      *       guaranteed to occur in the order the client API is called. However,
 385      *       operations on different resources are not guaranteed to occur in
 386      *       any specific order.
 387      */
 388     int (*exec) (lrmd_t * lrmd, const char *rsc_id, const char *action, const char *userdata,   /* userdata string given back in event notification */
 389                  guint interval_ms,
 390                  int timeout,   /* ms */
 391                  int start_delay,       /* ms */
 392                  enum lrmd_call_options options, lrmd_key_value_t * params);    /* ownership of params is given up to api here */
 393 
 394     /*!
 395      * \brief Cancel a recurring command.
 396      *
 397      * \return Legacy Pacemaker return code (if pcmk_ok, command is queued in
 398      *         daemon on function return, and the event callback will be called
 399      *         later with an exec_complete event with an lrmd_op_status
 400      *         signifying that the operation is cancelled)
 401      *
 402      * \note exec() and cancel() operations on an individual resource are
 403      *       guaranteed to occur in the order the client API is called. However,
 404      *       operations on different resources are not guaranteed to occur in
 405      *       any specific order.
 406      */
 407     int (*cancel) (lrmd_t *lrmd, const char *rsc_id, const char *action,
 408                    guint interval_ms);
 409 
 410     /*!
 411      * \brief Get resource metadata for a specified resource agent
 412      *
 413      * \param[in]  lrmd      Executor connection (unused)
 414      * \param[in]  standard  Resource agent class
 415      * \param[in]  provider  Resource agent provider
 416      * \param[in]  agent     Resource agent type
 417      * \param[out] output    Metadata will be stored here (must not be NULL)
 418      * \param[in]  options   Options to use with any executor API calls (unused)
 419      *
 420      * \return Legacy Pacemaker return code
 421      *
 422      * \note Caller is responsible for freeing output. This call is currently
 423      *       always synchronous (blocking), and always done directly by the
 424      *       library (not via the executor connection). This means that it is based
 425      *       on the local host environment, even if the executor connection is to a
 426      *       remote node, so (for most resource agent classes) this will fail if
 427      *       the agent is not installed locally. This also means that, if an
 428      *       external agent must be executed, it will be executed by the
 429      *       caller's user, not the executor's.
 430      * \todo Add a metadata call to the executor API and let the server handle this.
 431      */
 432     int (*get_metadata) (lrmd_t * lrmd,
 433                          const char *standard,
 434                          const char *provider,
 435                          const char *agent, char **output, enum lrmd_call_options options);
 436 
 437     /*!
 438      * \brief Retrieve a list of installed resource agents.
 439      *
 440      * \return Number of items in list on success, negative legacy Pacemaker
 441      *         return code otherwise
 442      *
 443      * \note if standard is not provided, all known agents will be returned
 444      * \note list must be freed using lrmd_list_freeall()
 445      */
 446     int (*list_agents) (lrmd_t * lrmd, lrmd_list_t ** agents,
 447                         const char *standard, const char *provider);
 448 
 449     /*!
 450      * \brief Retrieve a list of resource agent providers
 451      *
 452      * \return Number of items in list on success, negative legacy Pacemaker
 453      *         return code otherwise
 454      *
 455      * \note When the agent is provided, only the agent's provider will be returned
 456      * \note When no agent is supplied, all providers will be returned.
 457      * \note List must be freed using lrmd_list_freeall()
 458      */
 459     int (*list_ocf_providers) (lrmd_t * lrmd, const char *agent, lrmd_list_t ** providers);
 460 
 461     /*!
 462      * \brief Retrieve a list of standards supported by this machine/installation
 463      *
 464      * \return Number of items in list on success, negative legacy Pacemaker
 465      *         return code otherwise
 466      *
 467      * \note List must be freed using lrmd_list_freeall()
 468      */
 469     int (*list_standards) (lrmd_t * lrmd, lrmd_list_t ** standards);
 470 
 471     /*!
 472      * \brief Execute an alert agent
 473      *
 474      * \return Legacy Pacemaker return code (if pcmk_ok, the alert is queued in
 475      *         the executor, and the event callback will be called later with
 476      *         the result)
 477      *
 478      * \note Operations on individual alerts (by ID) are guaranteed to occur in
 479      *       the order the client API is called. Operations on different alerts
 480      *       are not guaranteed to occur in any specific order.
 481      */
 482     int (*exec_alert) (lrmd_t *lrmd, const char *alert_id,
 483                        const char *alert_path, int timeout, /* ms */
 484                        lrmd_key_value_t *params); /* ownership of params is given up to api here */
 485 
 486     /*!
 487      * \brief Get resource metadata for a resource agent, passing parameters
 488      *
 489      * \param[in]  lrmd      Executor connection (unused)
 490      * \param[in]  standard  Resource agent class
 491      * \param[in]  provider  Resource agent provider
 492      * \param[in]  agent     Resource agent type
 493      * \param[out] output    Metadata will be stored here (must not be NULL)
 494      * \param[in]  options   Options to use with any executor API calls (unused)
 495      * \param[in]  params    Parameters to pass to agent via environment
 496      *
 497      * \return Legacy Pacemaker return code
 498      *
 499      * \note This is identical to the get_metadata() API call, except parameters
 500      *       will be passed to the resource agent via environment variables.
 501      * \note The API will handle freeing params.
 502      */
 503     int (*get_metadata_params) (lrmd_t *lrmd, const char *standard,
 504                                 const char *provider, const char *agent,
 505                                 char **output, enum lrmd_call_options options,
 506                                 lrmd_key_value_t *params);
 507 
 508 } lrmd_api_operations_t;
 509 
 510 struct lrmd_s {
 511     lrmd_api_operations_t *cmds;
 512     void *lrmd_private;
 513 };
 514 
 515 static inline const char *
 516 lrmd_event_type2str(enum lrmd_callback_event type)
     /* [previous][next][first][last][top][bottom][index][help] */
 517 {
 518     switch (type) {
 519         case lrmd_event_register:
 520             return "register";
 521         case lrmd_event_unregister:
 522             return "unregister";
 523         case lrmd_event_exec_complete:
 524             return "exec_complete";
 525         case lrmd_event_disconnect:
 526             return "disconnect";
 527         case lrmd_event_connect:
 528             return "connect";
 529         case lrmd_event_poke:
 530             return "poke";
 531         case lrmd_event_new_client:
 532             return "new_client";
 533     }
 534     return "unknown";
 535 }
 536 
 537 #ifdef __cplusplus
 538 }
 539 #endif
 540 
 541 #endif

/* [previous][next][first][last][top][bottom][index][help] */