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