pacemaker  2.0.1-9e909a5bdd
Scalable High-Availability cluster resource manager
stonith-ng.h
Go to the documentation of this file.
1 /*
2  * Copyright 2004-2019 Andrew Beekhof <andrew@beekhof.net>
3  *
4  * This source code is licensed under the GNU Lesser General Public License
5  * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
6  */
7 
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11 
18 #ifndef STONITH_NG__H
19 # define STONITH_NG__H
20 
21 # include <dlfcn.h>
22 # include <errno.h>
23 # include <stdbool.h> // bool
24 # include <stdint.h> // uint32_t
25 # include <time.h> // time_t
26 
27 # define T_STONITH_NOTIFY_DISCONNECT "st_notify_disconnect"
28 # define T_STONITH_NOTIFY_FENCE "st_notify_fence"
29 # define T_STONITH_NOTIFY_HISTORY "st_notify_history"
30 
31 /* *INDENT-OFF* */
36 };
37 
39  st_opt_none = 0x00000000,
40  st_opt_verbose = 0x00000001,
41  st_opt_allow_suicide = 0x00000002,
42 
43  st_opt_manual_ack = 0x00000008,
44  st_opt_discard_reply = 0x00000010,
45 /* st_opt_all_replies = 0x00000020, */
46  st_opt_topology = 0x00000040,
47  st_opt_scope_local = 0x00000100,
48  st_opt_cs_nodeid = 0x00000200,
49  st_opt_sync_call = 0x00001000,
52  st_opt_timeout_updates = 0x00002000,
55  /* used where ever apropriate - e.g. cleanup of history */
56  st_opt_cleanup = 0x000080000,
57  /* used where ever apropriate - e.g. send out a history query to all nodes */
58  st_opt_broadcast = 0x000100000,
59 };
60 
63 {
69 };
70 
71 // Supported fence agent interface standards
75  st_namespace_internal, // Implemented internally by Pacemaker
76 
77  /* Neither of these projects are active any longer, but the fence agent
78  * interfaces they created are still in use and supported by Pacemaker.
79  */
80  st_namespace_rhcs, // Red Hat Cluster Suite compatible
81  st_namespace_lha, // Linux-HA compatible
82 };
83 
84 enum stonith_namespace stonith_text2namespace(const char *namespace_s);
85 const char *stonith_namespace2text(enum stonith_namespace st_namespace);
86 enum stonith_namespace stonith_get_namespace(const char *agent,
87  const char *namespace_s);
88 
89 typedef struct stonith_key_value_s {
90  char *key;
91  char *value;
94 
95 typedef struct stonith_history_s {
96  char *target;
97  char *action;
98  char *origin;
99  char *delegate;
100  char *client;
101  int state;
102  time_t completed;
105 
106 typedef struct stonith_s stonith_t;
107 
108 typedef struct stonith_event_s
109 {
110  char *id;
111  char *type;
112  char *message;
113  char *operation;
114 
115  int result;
116  char *origin;
117  char *target;
118  char *action;
119  char *executioner;
120 
121  char *device;
122 
125 
127 
129 {
130  int rc;
131  int call_id;
132  void *userdata;
134 
136 {
140  int (*free) (stonith_t *st);
141 
148  int (*connect) (stonith_t *st, const char *name, int *stonith_fd);
149 
156  int (*disconnect)(stonith_t *st);
157 
167  stonith_t *st, int options, const char *name);
168 
178  stonith_t *st, int options, const char *id,
179  const char *provider, const char *agent, stonith_key_value_t *params);
180 
189  int (*remove_level)(
190  stonith_t *st, int options, const char *node, int level);
191 
202  stonith_t *st, int options, const char *node, int level, stonith_key_value_t *device_list);
203 
212  int (*metadata)(stonith_t *st, int options,
213  const char *device, const char *provider, char **output, int timeout);
214 
225  int (*list_agents)(stonith_t *stonith, int call_options, const char *provider,
226  stonith_key_value_t **devices, int timeout);
227 
234  int (*list)(stonith_t *st, int options, const char *id, char **list_output, int timeout);
235 
242  int (*monitor)(stonith_t *st, int options, const char *id, int timeout);
243 
250  int (*status)(stonith_t *st, int options, const char *id, const char *port, int timeout);
251 
261  int (*query)(stonith_t *st, int options, const char *node,
262  stonith_key_value_t **devices, int timeout);
263 
279  int (*fence)(stonith_t *st, int options, const char *node, const char *action,
280  int timeout, int tolerance);
281 
288  int (*confirm)(stonith_t *st, int options, const char *node);
289 
298  int (*history)(stonith_t *st, int options, const char *node, stonith_history_t **output, int timeout);
299 
301  stonith_t *st, const char *event,
302  void (*notify)(stonith_t *st, stonith_event_t *e));
303  int (*remove_notification)(stonith_t *st, const char *event);
304 
323  int call_id,
324  int timeout,
325  int options,
326  void *userdata,
327  const char *callback_name,
328  void (*callback)(stonith_t *st, stonith_callback_data_t *data));
329 
333  int (*remove_callback)(stonith_t *st, int call_id, bool all_callbacks);
334 
351  int (*remove_level_full)(stonith_t *st, int options,
352  const char *node, const char *pattern,
353  const char *attr, const char *value, int level);
354 
372  int (*register_level_full)(stonith_t *st, int options,
373  const char *node, const char *pattern,
374  const char *attr, const char *value,
375  int level, stonith_key_value_t *device_list);
376 
395  int (*validate)(stonith_t *st, int call_options, const char *rsc_id,
396  const char *namespace_s, const char *agent,
397  stonith_key_value_t *params, int timeout, char **output,
398  char **error_output);
399 
401 
402 struct stonith_s
403 {
404  enum stonith_state state;
405 
406  int call_id;
408  void *st_private;
409 
411 };
412 /* *INDENT-ON* */
413 
414 /* Core functions */
416 void stonith_api_delete(stonith_t * st);
417 
419 
420 // deprecated (use stonith_get_namespace() instead)
421 const char *get_stonith_provider(const char *agent, const char *provider);
422 
423 bool stonith_dispatch(stonith_t * st);
424 
426  const char *value);
427 void stonith_key_value_freeall(stonith_key_value_t * kvp, int keys, int values);
428 
430 
431 /* Basic helpers that allows nodes to be fenced and the history to be
432  * queried without mainloop or the caller understanding the full API
433  *
434  * At least one of nodeid and uname are required
435  */
436 int stonith_api_kick(uint32_t nodeid, const char *uname, int timeout, bool off);
437 time_t stonith_api_time(uint32_t nodeid, const char *uname, bool in_progress);
438 
439 /*
440  * Helpers for using the above functions without install-time dependencies
441  *
442  * Usage:
443  * #include <crm/stonith-ng.h>
444  *
445  * To turn a node off by corosync nodeid:
446  * stonith_api_kick_helper(nodeid, 120, 1);
447  *
448  * To check the last fence date/time (also by nodeid):
449  * last = stonith_api_time_helper(nodeid, 0);
450  *
451  * To check if fencing is in progress:
452  * if(stonith_api_time_helper(nodeid, 1) > 0) { ... }
453  *
454  * eg.
455 
456  #include <stdio.h>
457  #include <time.h>
458  #include <crm/stonith-ng.h>
459  int
460  main(int argc, char ** argv)
461  {
462  int rc = 0;
463  int nodeid = 102;
464 
465  rc = stonith_api_time_helper(nodeid, 0);
466  printf("%d last fenced at %s\n", nodeid, ctime(rc));
467 
468  rc = stonith_api_kick_helper(nodeid, 120, 1);
469  printf("%d fence result: %d\n", nodeid, rc);
470 
471  rc = stonith_api_time_helper(nodeid, 0);
472  printf("%d last fenced at %s\n", nodeid, ctime(rc));
473 
474  return 0;
475  }
476 
477  */
478 
479 # define STONITH_LIBRARY "libstonithd.so.26"
480 
481 typedef int (*st_api_kick_fn) (int nodeid, const char *uname, int timeout, bool off);
482 typedef time_t (*st_api_time_fn) (int nodeid, const char *uname, bool in_progress);
483 
484 static inline int
485 stonith_api_kick_helper(uint32_t nodeid, int timeout, bool off)
486 {
487  static void *st_library = NULL;
488  static st_api_kick_fn st_kick_fn;
489 
490  if (st_library == NULL) {
491  st_library = dlopen(STONITH_LIBRARY, RTLD_LAZY);
492  }
493  if (st_library && st_kick_fn == NULL) {
494  st_kick_fn = (st_api_kick_fn) dlsym(st_library, "stonith_api_kick");
495  }
496  if (st_kick_fn == NULL) {
497 #ifdef ELIBACC
498  return -ELIBACC;
499 #else
500  return -ENOSYS;
501 #endif
502  }
503 
504  return (*st_kick_fn) (nodeid, NULL, timeout, off);
505 }
506 
507 static inline time_t
508 stonith_api_time_helper(uint32_t nodeid, bool in_progress)
509 {
510  static void *st_library = NULL;
511  static st_api_time_fn st_time_fn;
512 
513  if (st_library == NULL) {
514  st_library = dlopen(STONITH_LIBRARY, RTLD_LAZY);
515  }
516  if (st_library && st_time_fn == NULL) {
517  st_time_fn = (st_api_time_fn) dlsym(st_library, "stonith_api_time");
518  }
519  if (st_time_fn == NULL) {
520  return 0;
521  }
522 
523  return (*st_time_fn) (nodeid, NULL, in_progress);
524 }
525 
526 #ifdef __cplusplus
527 }
528 #endif
529 
530 #endif
stonith_api_operations_s::register_notification
int(* register_notification)(stonith_t *st, const char *event, void(*notify)(stonith_t *st, stonith_event_t *e))
Definition: stonith-ng.h:300
st_failed
@ st_failed
Definition: stonith-ng.h:68
stonith_dump_pending_callbacks
void stonith_dump_pending_callbacks(stonith_t *st)
Definition: st_client.c:1881
stonith_api_operations_s::remove_level
int(* remove_level)(stonith_t *st, int options, const char *node, int level)
Remove a fencing level for a specific node.
Definition: stonith-ng.h:189
st_opt_none
@ st_opt_none
Definition: stonith-ng.h:39
stonith_key_value_add
stonith_key_value_t * stonith_key_value_add(stonith_key_value_t *kvp, const char *key, const char *value)
Definition: st_client.c:2304
st_opt_manual_ack
@ st_opt_manual_ack
Definition: stonith-ng.h:43
stonith_api_operations_s::metadata
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:212
stonith_event_s::executioner
char * executioner
Definition: stonith-ng.h:119
data
char data[0]
Definition: internal.h:10
stonith_api_new
stonith_t * stonith_api_new(void)
Definition: st_client.c:2250
stonith_disconnected
@ stonith_disconnected
Definition: stonith-ng.h:35
stonith_call_options
stonith_call_options
Definition: stonith-ng.h:38
stonith_get_namespace
enum stonith_namespace stonith_get_namespace(const char *agent, const char *namespace_s)
Determine namespace of a fence agent.
Definition: st_client.c:176
st_namespace_rhcs
@ st_namespace_rhcs
Definition: stonith-ng.h:80
stonith_event_s::id
char * id
Definition: stonith-ng.h:110
st_duplicate
@ st_duplicate
Definition: stonith-ng.h:67
st_namespace_any
@ st_namespace_any
Definition: stonith-ng.h:74
st_opt_broadcast
@ st_opt_broadcast
Definition: stonith-ng.h:58
stonith_api_operations_s::disconnect
int(* disconnect)(stonith_t *st)
Disconnect from the local stonith daemon.
Definition: stonith-ng.h:156
st_opt_report_only_success
@ st_opt_report_only_success
Definition: stonith-ng.h:54
st_exec
@ st_exec
Definition: stonith-ng.h:65
stonith_api_operations_s::confirm
int(* confirm)(stonith_t *st, int options, const char *node)
Manually confirm that a node is down.
Definition: stonith-ng.h:288
stonith_api_operations_s::list
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:234
st_done
@ st_done
Definition: stonith-ng.h:66
stonith_event_s::type
char * type
Definition: stonith-ng.h:111
stonith_api_operations_s::connect
int(* connect)(stonith_t *st, const char *name, int *stonith_fd)
Connect to the local stonith daemon.
Definition: stonith-ng.h:148
st_opt_scope_local
@ st_opt_scope_local
Definition: stonith-ng.h:47
stonith_api_kick
int stonith_api_kick(uint32_t nodeid, const char *uname, int timeout, bool off)
Definition: st_client.c:2352
st_api_kick_fn
int(* st_api_kick_fn)(int nodeid, const char *uname, int timeout, bool off)
Definition: stonith-ng.h:481
st_opt_cleanup
@ st_opt_cleanup
Definition: stonith-ng.h:56
stonith_event_s::message
char * message
Definition: stonith-ng.h:112
stonith_callback_data_t
struct stonith_callback_data_s stonith_callback_data_t
stonith_api_delete
void stonith_api_delete(stonith_t *st)
Definition: st_client.c:2166
stonith_key_value_s
Definition: stonith-ng.h:89
stonith_api_operations_s::remove_device
int(* remove_device)(stonith_t *st, int options, const char *name)
Remove a registered stonith device with the local stonith daemon.
Definition: stonith-ng.h:166
stonith_key_value_s::value
char * value
Definition: stonith-ng.h:91
stonith_history_s::action
char * action
Definition: stonith-ng.h:97
stonith_history_s::state
int state
Definition: stonith-ng.h:101
stonith_api_operations_s::register_level_full
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 specific node, node regex or attribute.
Definition: stonith-ng.h:372
stonith_history_s::target
char * target
Definition: stonith-ng.h:96
stonith_api_operations_s::history
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:298
stonith_key_value_s::next
struct stonith_key_value_s * next
Definition: stonith-ng.h:92
stonith_api_operations_s::validate
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:395
stonith_api_operations_s::remove_notification
int(* remove_notification)(stonith_t *st, const char *event)
Definition: stonith-ng.h:303
stonith_event_s
Definition: stonith-ng.h:109
stonith_history_t
struct stonith_history_s stonith_history_t
stonith_history_s::next
struct stonith_history_s * next
Definition: stonith-ng.h:103
st_opt_cs_nodeid
@ st_opt_cs_nodeid
Definition: stonith-ng.h:48
stonith_text2namespace
enum stonith_namespace stonith_text2namespace(const char *namespace_s)
Get agent namespace by name.
Definition: st_client.c:129
stonith_s::state
enum stonith_state state
Definition: stonith-ng.h:404
stonith_history_s::delegate
char * delegate
Definition: stonith-ng.h:99
stonith_api_operations_s::remove_level_full
int(* remove_level_full)(stonith_t *st, int options, const char *node, const char *pattern, const char *attr, const char *value, int level)
Remove fencing level for specific node, node regex or attribute.
Definition: stonith-ng.h:351
st_namespace_internal
@ st_namespace_internal
Definition: stonith-ng.h:75
stonith_connected_command
@ stonith_connected_command
Definition: stonith-ng.h:33
st_opt_allow_suicide
@ st_opt_allow_suicide
Definition: stonith-ng.h:41
stonith_event_s::target
char * target
Definition: stonith-ng.h:117
uint32_t
#define uint32_t
Definition: stdint.in.h:156
uname
char uname[MAX_NAME]
Definition: internal.h:5
id
uint32_t id
Definition: internal.h:0
stonith_event_t
struct stonith_event_s stonith_event_t
stonith_history_s
Definition: stonith-ng.h:95
stonith_namespace2text
const char * stonith_namespace2text(enum stonith_namespace st_namespace)
Get agent namespace name.
Definition: st_client.c:155
stonith_api_operations_s::query
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:261
stonith_history_s::completed
time_t completed
Definition: stonith-ng.h:102
stonith_key_value_t
struct stonith_key_value_s stonith_key_value_t
st_opt_verbose
@ st_opt_verbose
Definition: stonith-ng.h:40
stonith_history_s::origin
char * origin
Definition: stonith-ng.h:98
st_opt_discard_reply
@ st_opt_discard_reply
Definition: stonith-ng.h:44
stonith_key_value_freeall
void stonith_key_value_freeall(stonith_key_value_t *kvp, int keys, int values)
Definition: st_client.c:2331
stonith_callback_data_s
Definition: stonith-ng.h:129
stonith_callback_data_s::call_id
int call_id
Definition: stonith-ng.h:131
stonith_api_operations_s
Definition: stonith-ng.h:136
stonith_callback_data_s::userdata
void * userdata
Definition: stonith-ng.h:132
stonith_api_operations_s::free
int(* free)(stonith_t *st)
Destroy the stonith api structure.
Definition: stonith-ng.h:140
stonith_callback_data_s::rc
int rc
Definition: stonith-ng.h:130
stonith_event_s::operation
char * operation
Definition: stonith-ng.h:113
op_state
op_state
Definition: stonith-ng.h:63
get_stonith_provider
const char * get_stonith_provider(const char *agent, const char *provider)
Deprecated (use stonith_get_namespace() instead)
Definition: st_client.c:1359
st_opt_topology
@ st_opt_topology
Definition: stonith-ng.h:46
stonith_s::cmds
stonith_api_operations_t * cmds
Definition: stonith-ng.h:410
stonith_event_s::action
char * action
Definition: stonith-ng.h:118
st_namespace_lha
@ st_namespace_lha
Definition: stonith-ng.h:81
st_namespace_invalid
@ st_namespace_invalid
Definition: stonith-ng.h:73
stonith_dispatch
bool stonith_dispatch(stonith_t *st)
Definition: st_client.c:2108
stonith_api_operations_s::status
int(* status)(stonith_t *st, int options, const char *id, const char *port, int timeout)
Check to see if a local stonith device's port is reachable.
Definition: stonith-ng.h:250
st_api_time_fn
time_t(* st_api_time_fn)(int nodeid, const char *uname, bool in_progress)
Definition: stonith-ng.h:482
stonith_key_value_s::key
char * key
Definition: stonith-ng.h:90
STONITH_LIBRARY
#define STONITH_LIBRARY
Definition: stonith-ng.h:479
stonith_api_operations_s::register_callback
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:322
stonith_event_s::device
char * device
Definition: stonith-ng.h:121
stonith_s::call_timeout
int call_timeout
Definition: stonith-ng.h:407
ELIBACC
#define ELIBACC
Definition: portability.h:140
stonith_event_s::origin
char * origin
Definition: stonith-ng.h:116
stonith_s::st_private
void * st_private
Definition: stonith-ng.h:408
stonith_api_operations_s::register_device
int(* register_device)(stonith_t *st, int options, const char *id, const char *provider, const char *agent, stonith_key_value_t *params)
Register a stonith device with the local stonith daemon.
Definition: stonith-ng.h:177
stonith_history_s::client
char * client
Definition: stonith-ng.h:100
stonith_api_operations_s::fence
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:279
stonith_state
stonith_state
Definition: stonith-ng.h:32
stonith_api_operations_t
struct stonith_api_operations_s stonith_api_operations_t
stonith_api_time
time_t stonith_api_time(uint32_t nodeid, const char *uname, bool in_progress)
Definition: st_client.c:2401
stonith_history_free
void stonith_history_free(stonith_history_t *history)
Definition: st_client.c:1342
st_opt_sync_call
@ st_opt_sync_call
Definition: stonith-ng.h:49
stonith_s::call_id
int call_id
Definition: stonith-ng.h:406
st_query
@ st_query
Definition: stonith-ng.h:64
stonith_api_operations_s::list_agents
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:225
stonith_api_operations_s::monitor
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:242
stonith_api_operations_s::remove_callback
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:333
st_opt_timeout_updates
@ st_opt_timeout_updates
Definition: stonith-ng.h:52
stonith_api_operations_s::register_level
int(* register_level)(stonith_t *st, int options, const char *node, int level, stonith_key_value_t *device_list)
Register a fencing level containing the fencing devices to be used at that level for a specific node.
Definition: stonith-ng.h:201
stonith_event_s::result
int result
Definition: stonith-ng.h:115
stonith_connected_query
@ stonith_connected_query
Definition: stonith-ng.h:34
stonith_s
Definition: stonith-ng.h:403
stonith_event_s::client_origin
char * client_origin
Definition: stonith-ng.h:124
stonith_namespace
stonith_namespace
Definition: stonith-ng.h:72