![[first]](../icons/first.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[bottom]](../icons/bottom.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
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)
/* ![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
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
![[last]](../icons/last.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/