pacemaker  2.1.4-dc6eb4362
Scalable High-Availability cluster resource manager
stonith-ng.h
Go to the documentation of this file.
1 /*
2  * Copyright 2004-2022 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_STONITH_NG__H
11 # define PCMK__CRM_STONITH_NG__H
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
23 /* IMPORTANT: DLM source code includes this file directly, without having access
24  * to other Pacemaker headers on its include path, so this file should *not*
25  * include any other Pacemaker headers. (DLM might be updated to avoid the
26  * issue, but we should still follow this guideline for a long time after.)
27  */
28 
29 # include <dlfcn.h>
30 # include <errno.h>
31 # include <stdbool.h> // bool
32 # include <stdint.h> // uint32_t
33 # include <time.h> // time_t
34 
35 # define T_STONITH_NOTIFY_DISCONNECT "st_notify_disconnect"
36 # define T_STONITH_NOTIFY_FENCE "st_notify_fence"
37 # define T_STONITH_NOTIFY_HISTORY "st_notify_history"
38 # define T_STONITH_NOTIFY_HISTORY_SYNCED "st_notify_history_synced"
39 
40 /* *INDENT-OFF* */
45 };
46 
48  st_opt_none = 0x00000000,
49  st_opt_verbose = 0x00000001,
50  st_opt_allow_suicide = 0x00000002,
51 
52  st_opt_manual_ack = 0x00000008,
53  st_opt_discard_reply = 0x00000010,
54 /* st_opt_all_replies = 0x00000020, */
55  st_opt_topology = 0x00000040,
56  st_opt_scope_local = 0x00000100,
57  st_opt_cs_nodeid = 0x00000200,
58  st_opt_sync_call = 0x00001000,
61  st_opt_timeout_updates = 0x00002000,
64  /* used where ever apropriate - e.g. cleanup of history */
65  st_opt_cleanup = 0x000080000,
66  /* used where ever apropriate - e.g. send out a history query to all nodes */
67  st_opt_broadcast = 0x000100000,
68 };
69 
72 {
78 };
79 
80 // Supported fence agent interface standards
84  st_namespace_internal, // Implemented internally by Pacemaker
85 
86  /* Neither of these projects are active any longer, but the fence agent
87  * interfaces they created are still in use and supported by Pacemaker.
88  */
89  st_namespace_rhcs, // Red Hat Cluster Suite compatible
90  st_namespace_lha, // Linux-HA compatible
91 };
92 
93 enum stonith_namespace stonith_text2namespace(const char *namespace_s);
94 const char *stonith_namespace2text(enum stonith_namespace st_namespace);
95 enum stonith_namespace stonith_get_namespace(const char *agent,
96  const char *namespace_s);
97 
98 typedef struct stonith_key_value_s {
99  char *key;
100  char *value;
103 
104 typedef struct stonith_history_s {
105  char *target;
106  char *action;
107  char *origin;
108  char *delegate;
109  char *client;
110  int state;
111  time_t completed;
114  char *exit_reason;
116 
117 typedef struct stonith_s stonith_t;
118 
119 typedef struct stonith_event_s
120 {
121  char *id;
122  char *type;
123  char *message;
124  char *operation;
125 
126  int result;
127  char *origin;
128  char *target;
129  char *action;
130  char *executioner;
131 
132  char *device;
133 
136 
138  void *opaque;
140 
141 typedef struct stonith_callback_data_s {
142  int rc;
143  int call_id;
144  void *userdata;
145 
147  void *opaque;
149 
151 {
155  int (*free) (stonith_t *st);
156 
162  int (*connect) (stonith_t *st, const char *name, int *stonith_fd);
163 
170 
178  stonith_t *st, int options, const char *name);
179 
187  stonith_t *st, int options, const char *id,
188  const char *provider, const char *agent, stonith_key_value_t *params);
189 
196  int (*remove_level)(
197  stonith_t *st, int options, const char *node, int level);
198 
206  stonith_t *st, int options, const char *node, int level, stonith_key_value_t *device_list);
207 
215  int (*metadata)(stonith_t *st, int options,
216  const char *device, const char *provider, char **output, int timeout);
217 
227  int (*list_agents)(stonith_t *stonith, int call_options, const char *provider,
228  stonith_key_value_t **devices, int timeout);
229 
236  int (*list)(stonith_t *st, int options, const char *id, char **list_output, int timeout);
237 
244  int (*monitor)(stonith_t *st, int options, const char *id, int timeout);
245 
252  int (*status)(stonith_t *st, int options, const char *id, const char *port, int timeout);
253 
262  int (*query)(stonith_t *st, int options, const char *node,
263  stonith_key_value_t **devices, int timeout);
264 
280  int (*fence)(stonith_t *st, int options, const char *node, const char *action,
281  int timeout, int tolerance);
282 
289  int (*confirm)(stonith_t *st, int options, const char *node);
290 
296  int (*history)(stonith_t *st, int options, const char *node, stonith_history_t **output, int timeout);
297 
299  stonith_t *st, const char *event,
300  void (*notify)(stonith_t *st, stonith_event_t *e));
301 
311  int (*remove_notification)(stonith_t *st, const char *event);
312 
328  int call_id,
329  int timeout,
330  int options,
331  void *userdata,
332  const char *callback_name,
333  void (*callback)(stonith_t *st, stonith_callback_data_t *data));
334 
340  int (*remove_callback)(stonith_t *st, int call_id, bool all_callbacks);
341 
358  int (*remove_level_full)(stonith_t *st, int options,
359  const char *node, const char *pattern,
360  const char *attr, const char *value, int level);
361 
379  int (*register_level_full)(stonith_t *st, int options,
380  const char *node, const char *pattern,
381  const char *attr, const char *value,
382  int level, stonith_key_value_t *device_list);
383 
402  int (*validate)(stonith_t *st, int call_options, const char *rsc_id,
403  const char *namespace_s, const char *agent,
404  stonith_key_value_t *params, int timeout, char **output,
405  char **error_output);
406 
424  int (*fence_with_delay)(stonith_t *st, int options, const char *node, const char *action,
425  int timeout, int tolerance, int delay);
426 
428 
429 struct stonith_s
430 {
432 
433  int call_id;
435  void *st_private;
436 
438 };
439 /* *INDENT-ON* */
440 
441 /* Core functions */
444 
446 
448 
450  const char *value);
451 void stonith_key_value_freeall(stonith_key_value_t * kvp, int keys, int values);
452 
454 
455 // Convenience functions
456 int stonith_api_connect_retry(stonith_t *st, const char *name,
457  int max_attempts);
458 const char *stonith_op_state_str(enum op_state state);
459 
460 /* Basic helpers that allows nodes to be fenced and the history to be
461  * queried without mainloop or the caller understanding the full API
462  *
463  * At least one of nodeid and uname are required
464  */
465 int stonith_api_kick(uint32_t nodeid, const char *uname, int timeout, bool off);
466 time_t stonith_api_time(uint32_t nodeid, const char *uname, bool in_progress);
467 
468 /*
469  * Helpers for using the above functions without install-time dependencies
470  *
471  * Usage:
472  * #include <crm/stonith-ng.h>
473  *
474  * To turn a node off by corosync nodeid:
475  * stonith_api_kick_helper(nodeid, 120, 1);
476  *
477  * To check the last fence date/time (also by nodeid):
478  * last = stonith_api_time_helper(nodeid, 0);
479  *
480  * To check if fencing is in progress:
481  * if(stonith_api_time_helper(nodeid, 1) > 0) { ... }
482  *
483  * eg.
484 
485  #include <stdio.h>
486  #include <time.h>
487  #include <crm/stonith-ng.h>
488  int
489  main(int argc, char ** argv)
490  {
491  int rc = 0;
492  int nodeid = 102;
493 
494  rc = stonith_api_time_helper(nodeid, 0);
495  printf("%d last fenced at %s\n", nodeid, ctime(rc));
496 
497  rc = stonith_api_kick_helper(nodeid, 120, 1);
498  printf("%d fence result: %d\n", nodeid, rc);
499 
500  rc = stonith_api_time_helper(nodeid, 0);
501  printf("%d last fenced at %s\n", nodeid, ctime(rc));
502 
503  return 0;
504  }
505 
506  */
507 
508 # define STONITH_LIBRARY "libstonithd.so.26"
509 
510 typedef int (*st_api_kick_fn) (int nodeid, const char *uname, int timeout, bool off);
511 typedef time_t (*st_api_time_fn) (int nodeid, const char *uname, bool in_progress);
512 
513 static inline int
514 stonith_api_kick_helper(uint32_t nodeid, int timeout, bool off)
515 {
516  static void *st_library = NULL;
517  static st_api_kick_fn st_kick_fn;
518 
519  if (st_library == NULL) {
520  st_library = dlopen(STONITH_LIBRARY, RTLD_LAZY);
521  }
522  if (st_library && st_kick_fn == NULL) {
523  st_kick_fn = (st_api_kick_fn) dlsym(st_library, "stonith_api_kick");
524  }
525  if (st_kick_fn == NULL) {
526 #ifdef ELIBACC
527  return -ELIBACC;
528 #else
529  return -ENOSYS;
530 #endif
531  }
532 
533  return (*st_kick_fn) (nodeid, NULL, timeout, off);
534 }
535 
536 static inline time_t
537 stonith_api_time_helper(uint32_t nodeid, bool in_progress)
538 {
539  static void *st_library = NULL;
540  static st_api_time_fn st_time_fn;
541 
542  if (st_library == NULL) {
543  st_library = dlopen(STONITH_LIBRARY, RTLD_LAZY);
544  }
545  if (st_library && st_time_fn == NULL) {
546  st_time_fn = (st_api_time_fn) dlsym(st_library, "stonith_api_time");
547  }
548  if (st_time_fn == NULL) {
549  return 0;
550  }
551 
552  return (*st_time_fn) (nodeid, NULL, in_progress);
553 }
554 
564 bool stonith_agent_exists(const char *agent, int timeout);
565 
571 const char *stonith_action_str(const char *action);
572 
573 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
574 /* Normally we'd put this section in a separate file (crm/fencing/compat.h), but
575  * we can't do that for the reason noted at the top of this file. That does mean
576  * we have to duplicate these declarations where they're implemented.
577  */
578 
580 const char *get_stonith_provider(const char *agent, const char *provider);
581 
582 #endif
583 
584 #ifdef __cplusplus
585 }
586 #endif
587 
588 #endif
struct stonith_history_s * next
Definition: stonith-ng.h:112
int(* register_level_full)(stonith_t *st, int options, const char *node, const char *pattern, const char *attr, const char *value, int level, stonith_key_value_t *device_list)
Register fencing level for specified node, pattern or attribute.
Definition: stonith-ng.h:379
char data[0]
Definition: cpg.c:55
struct stonith_api_operations_s stonith_api_operations_t
struct stonith_key_value_s stonith_key_value_t
const char * name
Definition: cib.c:24
int stonith_api_kick(uint32_t nodeid, const char *uname, int timeout, bool off)
Definition: st_client.c:1905
int(* query)(stonith_t *st, int options, const char *node, stonith_key_value_t **devices, int timeout)
Retrieve a list of registered stonith devices.
Definition: stonith-ng.h:262
struct stonith_history_s stonith_history_t
enum stonith_namespace stonith_get_namespace(const char *agent, const char *namespace_s)
Determine namespace of a fence agent.
Definition: st_client.c:151
struct stonith_key_value_s * next
Definition: stonith-ng.h:101
int(* register_level)(stonith_t *st, int options, const char *node, int level, stonith_key_value_t *device_list)
Register a fencing level for specified node with local fencer.
Definition: stonith-ng.h:205
const char * get_stonith_provider(const char *agent, const char *provider)
Definition: st_client.c:2523
stonith_namespace
Definition: stonith-ng.h:81
int(* remove_callback)(stonith_t *st, int call_id, bool all_callbacks)
Remove a registered callback for a given call id.
Definition: stonith-ng.h:340
bool stonith_dispatch(stonith_t *st)
Definition: st_client.c:1618
stonith_t * stonith_api_new(void)
Definition: st_client.c:1762
const char * action
Definition: pcmk_fence.c:29
int stonith_api_connect_retry(stonith_t *st, const char *name, int max_attempts)
Make a blocking connection attempt to the fencer.
Definition: st_client.c:1840
stonith_key_value_t * stonith_key_value_add(stonith_key_value_t *kvp, const char *key, const char *value)
Definition: st_client.c:1861
int(* free)(stonith_t *st)
Destroy the stonith api structure.
Definition: stonith-ng.h:155
struct stonith_callback_data_s stonith_callback_data_t
stonith_t * st
Definition: pcmk_fence.c:27
bool stonith_agent_exists(const char *agent, int timeout)
Definition: st_client.c:2011
const char * stonith_op_state_str(enum op_state state)
Return string equivalent of an operation state value.
Definition: st_client.c:2275
enum stonith_state state
Definition: stonith-ng.h:431
unsigned int tolerance
Definition: pcmk_fence.c:32
const char * stonith_action_str(const char *action)
Turn stonith action into a more readable string.
Definition: st_client.c:2042
time_t(* st_api_time_fn)(int nodeid, const char *uname, bool in_progress)
Definition: stonith-ng.h:511
op_state
Definition: stonith-ng.h:71
int(* metadata)(stonith_t *st, int options, const char *device, const char *provider, char **output, int timeout)
Get the metadata documentation for a resource.
Definition: stonith-ng.h:215
int(* register_device)(stonith_t *st, int options, const char *id, const char *provider, const char *agent, stonith_key_value_t *params)
Register a fence device with the local fencer.
Definition: stonith-ng.h:186
int(* status)(stonith_t *st, int options, const char *id, const char *port, int timeout)
Check to see if a local stonith device&#39;s port is reachable.
Definition: stonith-ng.h:252
int(* fence)(stonith_t *st, int options, const char *node, const char *action, int timeout, int tolerance)
Issue a fencing action against a node.
Definition: stonith-ng.h:280
int(* register_callback)(stonith_t *st, int call_id, int timeout, int options, void *userdata, const char *callback_name, void(*callback)(stonith_t *st, stonith_callback_data_t *data))
Register a callback to receive the result of an asynchronous call.
Definition: stonith-ng.h:327
int(* disconnect)(stonith_t *st)
Disconnect from the local stonith daemon.
Definition: stonith-ng.h:169
void stonith_key_value_freeall(stonith_key_value_t *kvp, int keys, int values)
Definition: st_client.c:1884
int(* list)(stonith_t *st, int options, const char *id, char **list_output, int timeout)
Retrieve string listing hosts and port assignments from a local stonith device.
Definition: stonith-ng.h:236
int(* list_agents)(stonith_t *stonith, int call_options, const char *provider, stonith_key_value_t **devices, int timeout)
Retrieve a list of installed stonith agents.
Definition: stonith-ng.h:227
void stonith_dump_pending_callbacks(stonith_t *st)
Definition: st_client.c:1335
int(* fence_with_delay)(stonith_t *st, int options, const char *node, const char *action, int timeout, int tolerance, int delay)
Issue a fencing action against a node with requested fencing delay.
Definition: stonith-ng.h:424
int(* connect)(stonith_t *st, const char *name, int *stonith_fd)
Connect to the local stonith daemon.
Definition: stonith-ng.h:162
uint32_t id
Definition: cpg.c:45
int call_timeout
Definition: stonith-ng.h:434
int(* remove_device)(stonith_t *st, int options, const char *name)
Unregister a fence device with the local fencer.
Definition: stonith-ng.h:177
stonith_state
Definition: stonith-ng.h:41
int(* register_notification)(stonith_t *st, const char *event, void(*notify)(stonith_t *st, stonith_event_t *e))
Definition: stonith-ng.h:298
#define ELIBACC
Definition: portability.h:130
stonith_call_options
Definition: stonith-ng.h:47
int(* monitor)(stonith_t *st, int options, const char *id, int timeout)
Check to see if a local stonith device is reachable.
Definition: stonith-ng.h:244
char * client_origin
Definition: stonith-ng.h:135
int(* remove_notification)(stonith_t *st, const char *event)
Remove a previously registered notification for event, or all notifications if NULL.
Definition: stonith-ng.h:311
int(* validate)(stonith_t *st, int call_options, const char *rsc_id, const char *namespace_s, const char *agent, stonith_key_value_t *params, int timeout, char **output, char **error_output)
Validate an arbitrary stonith device configuration.
Definition: stonith-ng.h:402
void stonith_api_delete(stonith_t *st)
Definition: st_client.c:1676
int(* remove_level_full)(stonith_t *st, int options, const char *node, const char *pattern, const char *attr, const char *value, int level)
Unregister fencing level for specified node, pattern or attribute.
Definition: stonith-ng.h:358
stonith_api_operations_t * cmds
Definition: stonith-ng.h:437
int(* remove_level)(stonith_t *st, int options, const char *node, int level)
Unregister a fencing level for specified node with local fencer.
Definition: stonith-ng.h:196
int delay
Definition: pcmk_fence.c:33
void stonith_history_free(stonith_history_t *history)
Definition: st_client.c:737
char * executioner
Definition: stonith-ng.h:130
char * operation
Definition: stonith-ng.h:124
struct stonith_event_s stonith_event_t
char uname[MAX_NAME]
Definition: cpg.c:50
int(* st_api_kick_fn)(int nodeid, const char *uname, int timeout, bool off)
Definition: stonith-ng.h:510
time_t stonith_api_time(uint32_t nodeid, const char *uname, bool in_progress)
Definition: st_client.c:1947
int(* confirm)(stonith_t *st, int options, const char *node)
Manually confirm that a node is down.
Definition: stonith-ng.h:289
#define STONITH_LIBRARY
Definition: stonith-ng.h:508
void * st_private
Definition: stonith-ng.h:435
enum stonith_namespace stonith_text2namespace(const char *namespace_s)
Get agent namespace by name.
Definition: st_client.c:104
const char * stonith_namespace2text(enum stonith_namespace st_namespace)
Get agent namespace name.
Definition: st_client.c:130
unsigned int timeout
Definition: pcmk_fence.c:31
int call_id
Definition: stonith-ng.h:433
int(* history)(stonith_t *st, int options, const char *node, stonith_history_t **output, int timeout)
Retrieve a list of fencing operations that have occurred for a specific node.
Definition: stonith-ng.h:296