![[first]](../icons/first.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[last]](../icons/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 2019-2023 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__PACEMAKER__H
11 # define PCMK__PACEMAKER__H
12
13 # include <glib.h>
14 # include <libxml/tree.h>
15 # include <crm/common/scheduler.h>
16 # include <crm/cib/cib_types.h>
17
18 # include <crm/stonith-ng.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /**
25 * \file
26 * \brief High Level API
27 * \ingroup pacemaker
28 */
29
30
31 /*!
32 * \brief Modify operation of running a cluster simulation.
33 */
34 enum pcmk_sim_flags {
35 pcmk_sim_none = 0,
36 pcmk_sim_all_actions = 1 << 0,
37 pcmk_sim_show_pending = 1 << 1,
38 pcmk_sim_process = 1 << 2,
39 pcmk_sim_show_scores = 1 << 3,
40 pcmk_sim_show_utilization = 1 << 4,
41 pcmk_sim_simulate = 1 << 5,
42 pcmk_sim_sanitized = 1 << 6,
43 pcmk_sim_verbose = 1 << 7,
44 };
45
46 /*!
47 * \brief Synthetic cluster events that can be injected into the cluster
48 * for running simulations.
49 */
50 typedef struct {
51 /*! A list of node names (gchar *) to simulate bringing online */
52 GList *node_up;
53 /*! A list of node names (gchar *) to simulate bringing offline */
54 GList *node_down;
55 /*! A list of node names (gchar *) to simulate failing */
56 GList *node_fail;
57 /*! A list of operations (gchar *) to inject. The format of these strings
58 * is described in the "Operation Specification" section of crm_simulate
59 * help output.
60 */
61 GList *op_inject;
62 /*! A list of operations (gchar *) that should return a given error code
63 * if they fail. The format of these strings is described in the
64 * "Operation Specification" section of crm_simulate help output.
65 */
66 GList *op_fail;
67 /*! A list of tickets (gchar *) to simulate granting */
68 GList *ticket_grant;
69 /*! A list of tickets (gchar *) to simulate revoking */
70 GList *ticket_revoke;
71 /*! A list of tickets (gchar *) to simulate putting on standby */
72 GList *ticket_standby;
73 /*! A list of tickets (gchar *) to simulate activating */
74 GList *ticket_activate;
75 /*! Does the cluster have an active watchdog device? */
76 char *watchdog;
77 /*! Does the cluster have quorum? */
78 char *quorum;
79 } pcmk_injections_t;
80
81 /*!
82 * \brief Get and output controller status
83 *
84 * \param[in,out] xml Destination for the result, as an XML tree
85 * \param[in] node_name Name of node whose status is desired
86 * (\p NULL for DC)
87 * \param[in] message_timeout_ms How long to wait for a reply from the
88 * \p pacemaker-controld API. If 0,
89 * \p pcmk_ipc_dispatch_sync will be used.
90 * Otherwise, \p pcmk_ipc_dispatch_poll will
91 * be used.
92 *
93 * \return Standard Pacemaker return code
94 */
95 int pcmk_controller_status(xmlNodePtr *xml, const char *node_name,
96 unsigned int message_timeout_ms);
97
98 /*!
99 * \brief Get and output designated controller node name
100 *
101 * \param[in,out] xml Destination for the result, as an XML tree
102 * \param[in] message_timeout_ms How long to wait for a reply from the
103 * \p pacemaker-controld API. If 0,
104 * \p pcmk_ipc_dispatch_sync will be used.
105 * Otherwise, \p pcmk_ipc_dispatch_poll will
106 * be used.
107 *
108 * \return Standard Pacemaker return code
109 */
110 int pcmk_designated_controller(xmlNodePtr *xml,
111 unsigned int message_timeout_ms);
112
113 /*!
114 * \brief Free a :pcmk_injections_t structure
115 *
116 * \param[in,out] injections The structure to be freed
117 */
118 void pcmk_free_injections(pcmk_injections_t *injections);
119
120 /*!
121 * \brief Get and optionally output node info corresponding to a node ID from
122 * the controller
123 *
124 * \param[in,out] xml Destination for the result, as an XML tree
125 * \param[in,out] node_id ID of node whose name to get. If \p NULL
126 * or 0, get the local node name. If not
127 * \p NULL, store the true node ID here on
128 * success.
129 * \param[out] node_name If not \p NULL, where to store the node
130 * name
131 * \param[out] uuid If not \p NULL, where to store the node
132 * UUID
133 * \param[out] state If not \p NULL, where to store the
134 * membership state
135 * \param[out] is_remote If not \p NULL, where to store whether the
136 * node is a Pacemaker Remote node
137 * \param[out] have_quorum If not \p NULL, where to store whether the
138 * node has quorum
139 * \param[in] show_output Whether to output the node info
140 * \param[in] message_timeout_ms How long to wait for a reply from the
141 * \p pacemaker-controld API. If 0,
142 * \p pcmk_ipc_dispatch_sync will be used.
143 * Otherwise, \p pcmk_ipc_dispatch_poll will
144 * be used.
145 *
146 * \return Standard Pacemaker return code
147 *
148 * \note The caller is responsible for freeing \p *node_name, \p *uuid, and
149 * \p *state using \p free().
150 */
151 int pcmk_query_node_info(xmlNodePtr *xml, uint32_t *node_id, char **node_name,
152 char **uuid, char **state, bool *have_quorum,
153 bool *is_remote, bool show_output,
154 unsigned int message_timeout_ms);
155
156 /*!
157 * \brief Get the node name corresponding to a node ID from the controller
158 *
159 * \param[in,out] xml Destination for the result, as an XML tree
160 * \param[in,out] node_id ID of node whose name to get (or 0 for the
161 * local node)
162 * \param[out] node_name If not \p NULL, where to store the node
163 * name
164 * \param[in] message_timeout_ms How long to wait for a reply from the
165 * \p pacemaker-controld API. If 0,
166 * \p pcmk_ipc_dispatch_sync will be used.
167 * Otherwise, \p pcmk_ipc_dispatch_poll will
168 * be used.
169 *
170 * \return Standard Pacemaker return code
171 *
172 * \note The caller is responsible for freeing \p *node_name using \p free().
173 */
174 static inline int
175 pcmk_query_node_name(xmlNodePtr *xml, uint32_t node_id, char **node_name,
/* ![[next]](../icons/right.png)
![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
176 unsigned int message_timeout_ms)
177 {
178 return pcmk_query_node_info(xml, &node_id, node_name, NULL, NULL, NULL,
179 NULL, false, message_timeout_ms);
180 }
181
182 /*!
183 * \brief Get and output \p pacemakerd status
184 *
185 * \param[in,out] xml Destination for the result, as an XML tree
186 * \param[in] ipc_name IPC name for request
187 * \param[in] message_timeout_ms How long to wait for a reply from the
188 * \p pacemakerd API. If 0,
189 * \p pcmk_ipc_dispatch_sync will be used.
190 * Otherwise, \p pcmk_ipc_dispatch_poll will
191 * be used.
192 *
193 * \return Standard Pacemaker return code
194 */
195 int pcmk_pacemakerd_status(xmlNodePtr *xml, const char *ipc_name,
196 unsigned int message_timeout_ms);
197
198 /*!
199 * \brief Calculate and output resource operation digests
200 *
201 * \param[out] xml Where to store XML with result
202 * \param[in,out] rsc Resource to calculate digests for
203 * \param[in] node Node whose operation history should be used
204 * \param[in] overrides Hash table of configuration parameters to override
205 * \param[in] scheduler Scheduler data (with status)
206 *
207 * \return Standard Pacemaker return code
208 */
209 int pcmk_resource_digests(xmlNodePtr *xml, pcmk_resource_t *rsc,
210 const pcmk_node_t *node, GHashTable *overrides,
211 pcmk_scheduler_t *scheduler);
212
213 /*!
214 * \brief Simulate a cluster's response to events
215 *
216 * This high-level function essentially implements crm_simulate(8). It operates
217 * on an input CIB file and various lists of events that can be simulated. It
218 * optionally writes out a variety of artifacts to show the results of the
219 * simulation. Output can be modified with various flags.
220 *
221 * \param[in,out] xml The destination for the result, as an XML tree
222 * \param[in,out] scheduler Scheduler data
223 * \param[in] injections A structure containing cluster events
224 * (node up/down, tickets, injected operations)
225 * \param[in] flags A bitfield of :pcmk_sim_flags to modify
226 * operation of the simulation
227 * \param[in] section_opts Which portions of the cluster status output
228 * should be displayed?
229 * \param[in] use_date Date to set the cluster's time to (may be NULL)
230 * \param[in] input_file The source CIB file, which may be overwritten by
231 * this function (may be NULL)
232 * \param[in] graph_file Where to write the XML-formatted transition graph
233 * (may be NULL, in which case no file will be
234 * written)
235 * \param[in] dot_file Where to write the dot(1) formatted transition
236 * graph (may be NULL, in which case no file will
237 * be written)
238 *
239 * \return Standard Pacemaker return code
240 */
241 int pcmk_simulate(xmlNodePtr *xml, pcmk_scheduler_t *scheduler,
242 const pcmk_injections_t *injections, unsigned int flags,
243 unsigned int section_opts, const char *use_date,
244 const char *input_file, const char *graph_file,
245 const char *dot_file);
246
247 /*!
248 * \brief Get nodes list
249 *
250 * \param[in,out] xml The destination for the result, as an XML tree
251 * \param[in] node_types Node type(s) to return (default: all)
252 *
253 * \return Standard Pacemaker return code
254 */
255 int pcmk_list_nodes(xmlNodePtr *xml, const char *node_types);
256
257 /*!
258 * \brief Output cluster status formatted like `crm_mon --output-as=xml`
259 *
260 * \param[in,out] xml The destination for the result, as an XML tree
261 *
262 * \return Standard Pacemaker return code
263 */
264 int pcmk_status(xmlNodePtr *xml);
265
266 /*!
267 * \brief Check whether each rule in a list is in effect
268 *
269 * \param[in,out] xml The destination for the result, as an XML tree
270 * \param[in] input The CIB XML to check (if \c NULL, use current CIB)
271 * \param[in] date Check whether the rule is in effect at this date and
272 * time (if \c NULL, use current date and time)
273 * \param[in] rule_ids The IDs of the rules to check, as a <tt>NULL</tt>-
274 * terminated list.
275 *
276 * \return Standard Pacemaker return code
277 */
278 int pcmk_check_rules(xmlNodePtr *xml, xmlNodePtr input, const crm_time_t *date,
279 const char **rule_ids);
280
281 /*!
282 * \brief Check whether a given rule is in effect
283 *
284 * \param[in,out] xml The destination for the result, as an XML tree
285 * \param[in] input The CIB XML to check (if \c NULL, use current CIB)
286 * \param[in] date Check whether the rule is in effect at this date and
287 * time (if \c NULL, use current date and time)
288 * \param[in] rule_ids The ID of the rule to check
289 *
290 * \return Standard Pacemaker return code
291 */
292 static inline int
293 pcmk_check_rule(xmlNodePtr *xml, xmlNodePtr input, const crm_time_t *date,
/* ![[previous]](../icons/left.png)
![[last]](../icons/n_last.png)
*/
294 const char *rule_id)
295 {
296 const char *rule_ids[] = {rule_id, NULL};
297 return pcmk_check_rules(xml, input, date, rule_ids);
298 }
299
300 /*!
301 * \enum pcmk_rc_disp_flags
302 * \brief Bit flags to control which fields of result code info are displayed
303 */
304 enum pcmk_rc_disp_flags {
305 pcmk_rc_disp_none = 0, //!< (Does nothing)
306 pcmk_rc_disp_code = (1 << 0), //!< Display result code number
307 pcmk_rc_disp_name = (1 << 1), //!< Display result code name
308 pcmk_rc_disp_desc = (1 << 2), //!< Display result code description
309 };
310
311 /*!
312 * \brief Display the name and/or description of a result code
313 *
314 * \param[in,out] xml The destination for the result, as an XML tree
315 * \param[in] code The result code
316 * \param[in] type Interpret \c code as this type of result code.
317 * Supported values: \c pcmk_result_legacy,
318 * \c pcmk_result_rc, \c pcmk_result_exitcode.
319 * \param[in] flags Group of \c pcmk_rc_disp_flags
320 *
321 * \return Standard Pacemaker return code
322 */
323 int pcmk_show_result_code(xmlNodePtr *xml, int code, enum pcmk_result_type type,
324 uint32_t flags);
325
326 /*!
327 * \brief List all valid result codes in a particular family
328 *
329 * \param[in,out] xml The destination for the result, as an XML tree
330 * \param[in] type The family of result codes to list. Supported
331 * values: \c pcmk_result_legacy, \c pcmk_result_rc,
332 * \c pcmk_result_exitcode.
333 * \param[in] flags Group of \c pcmk_rc_disp_flags
334 *
335 * \return Standard Pacemaker return code
336 */
337 int pcmk_list_result_codes(xmlNodePtr *xml, enum pcmk_result_type type,
338 uint32_t flags);
339
340 /*!
341 * \brief List available providers for the given OCF agent
342 *
343 * \param[in,out] xml The destination for the result, as an XML tree
344 * \param[in] agent_spec Resource agent name
345 *
346 * \return Standard Pacemaker return code
347 */
348 int pcmk_list_alternatives(xmlNodePtr *xml, const char *agent_spec);
349
350 /*!
351 * \brief List all agents available for the named standard and/or provider
352 *
353 * \param[in,out] xml The destination for the result, as an XML tree
354 * \param[in] agent_spec STD[:PROV]
355 *
356 * \return Standard Pacemaker return code
357 */
358 int pcmk_list_agents(xmlNodePtr *xml, char *agent_spec);
359
360 /*!
361 * \brief List all available OCF providers for the given agent
362 *
363 * \param[in,out] xml The destination for the result, as an XML tree
364 * \param[in] agent_spec Resource agent name
365 *
366 * \return Standard Pacemaker return code
367 */
368 int pcmk_list_providers(xmlNodePtr *xml, const char *agent_spec);
369
370 /*!
371 * \brief List all available resource agent standards
372 *
373 * \param[in,out] xml The destination for the result, as an XML tree
374 *
375 * \return Standard Pacemaker return code
376 */
377 int pcmk_list_standards(xmlNodePtr *xml);
378
379 #ifdef BUILD_PUBLIC_LIBPACEMAKER
380
381 /*!
382 * \brief Ask the cluster to perform fencing
383 *
384 * \param[in,out] st A connection to the fencer API
385 * \param[in] target The node that should be fenced
386 * \param[in] action The fencing action (on, off, reboot) to perform
387 * \param[in] name Who requested the fence action?
388 * \param[in] timeout How long to wait for operation to complete (in ms)
389 * \param[in] tolerance If a successful action for \p target happened within
390 * this many ms, return 0 without performing the action
391 * again
392 * \param[in] delay Apply this delay (in milliseconds) before initiating
393 * fencing action (-1 applies no delay and also
394 * disables any fencing delay from pcmk_delay_base and
395 * pcmk_delay_max)
396 * \param[out] reason If not NULL, where to put descriptive failure reason
397 *
398 * \return Standard Pacemaker return code
399 * \note If \p reason is not NULL, the caller is responsible for freeing its
400 * returned value.
401 */
402 int pcmk_request_fencing(stonith_t *st, const char *target, const char *action,
403 const char *name, unsigned int timeout,
404 unsigned int tolerance, int delay, char **reason);
405
406 /*!
407 * \brief List the fencing operations that have occurred for a specific node
408 *
409 * \note If \p xml is not NULL, it will be freed first and the previous
410 * contents lost.
411 *
412 * \param[in,out] xml The destination for the result, as an XML tree
413 * \param[in,out] st A connection to the fencer API
414 * \param[in] target The node to get history for
415 * \param[in] timeout How long to wait for operation to complete (in ms)
416 * \param[in] quiet Suppress most output
417 * \param[in] verbose Include additional output
418 * \param[in] broadcast Gather fencing history from all nodes
419 * \param[in] cleanup Clean up fencing history after listing
420 *
421 * \return Standard Pacemaker return code
422 */
423 int pcmk_fence_history(xmlNodePtr *xml, stonith_t *st, const char *target,
424 unsigned int timeout, bool quiet, int verbose,
425 bool broadcast, bool cleanup);
426
427 /*!
428 * \brief List all installed fence agents
429 *
430 * \param[in,out] xml The destination for the result, as an XML tree (if
431 * not NULL, previous contents will be freed and lost)
432 * \param[in,out] st A connection to the fencer API
433 * \param[in] timeout How long to wait for operation to complete (in ms)
434 *
435 * \return Standard Pacemaker return code
436 */
437 int pcmk_fence_installed(xmlNodePtr *xml, stonith_t *st, unsigned int timeout);
438
439 /*!
440 * \brief When was a device last fenced?
441 *
442 * \param[in,out] xml The destination for the result, as an XML tree (if
443 * not NULL, previous contents will be freed and lost)
444 * \param[in] target The node that was fenced
445 * \param[in] as_nodeid If true, \p target has node ID rather than name
446 *
447 * \return Standard Pacemaker return code
448 */
449 int pcmk_fence_last(xmlNodePtr *xml, const char *target, bool as_nodeid);
450
451 /*!
452 * \brief List nodes that can be fenced
453 *
454 * \param[in,out] xml The destination for the result, as an XML tree (if
455 * not NULL, previous contents will be freed and lost)
456 * \param[in,out] st A connection to the fencer API
457 * \param[in] device_id Resource ID of fence device to check
458 * \param[in] timeout How long to wait for operation to complete (in ms)
459 *
460 * \return Standard Pacemaker return code
461 */
462 int pcmk_fence_list_targets(xmlNodePtr *xml, stonith_t *st,
463 const char *device_id, unsigned int timeout);
464
465 /*!
466 * \brief Get metadata for a fence agent
467 *
468 * \note If \p xml is not NULL, it will be freed first and the previous
469 * contents lost.
470 *
471 * \param[in,out] xml The destination for the result, as an XML tree (if
472 * not NULL, previous contents will be freed and lost)
473 * \param[in,out] st A connection to the fencer API
474 * \param[in] agent The fence agent to get metadata for
475 * \param[in] timeout How long to wait for operation to complete (in ms)
476 *
477 * \return Standard Pacemaker return code
478 */
479 int pcmk_fence_metadata(xmlNodePtr *xml, stonith_t *st, const char *agent,
480 unsigned int timeout);
481
482 /*!
483 * \brief List registered fence devices
484 *
485 * \param[in,out] xml The destination for the result, as an XML tree (if
486 * not NULL, previous contents will be freed and lost)
487 * \param[in,out] st A connection to the fencer API
488 * \param[in] target If not NULL, return only devices that can fence this
489 * \param[in] timeout How long to wait for operation to complete (in ms)
490 *
491 * \return Standard Pacemaker return code
492 */
493 int pcmk_fence_registered(xmlNodePtr *xml, stonith_t *st, const char *target,
494 unsigned int timeout);
495
496 /*!
497 * \brief Register a fencing topology level
498 *
499 * \param[in,out] st A connection to the fencer API
500 * \param[in] target What fencing level targets (as "name=value" to
501 * target by given node attribute, or "@pattern" to
502 * target by node name pattern, or a node name)
503 * \param[in] fence_level Index number of level to add
504 * \param[in] devices Devices to use in level
505 *
506 * \return Standard Pacemaker return code
507 */
508 int pcmk_fence_register_level(stonith_t *st, const char *target,
509 int fence_level,
510 const stonith_key_value_t *devices);
511
512 /*!
513 * \brief Unregister a fencing topology level
514 *
515 * \param[in,out] st A connection to the fencer API
516 * \param[in] target What fencing level targets (as "name=value" to
517 * target by given node attribute, or "@pattern" to
518 * target by node name pattern, or a node name)
519 * \param[in] fence_level Index number of level to remove
520 *
521 * \return Standard Pacemaker return code
522 */
523 int pcmk_fence_unregister_level(stonith_t *st, const char *target,
524 int fence_level);
525
526 /*!
527 * \brief Validate a fence device configuration
528 *
529 * \param[in,out] xml The destination for the result, as an XML tree (if
530 * not NULL, previous contents will be freed and lost)
531 * \param[in,out] st A connection to the fencer API
532 * \param[in] agent The agent to validate (for example, "fence_xvm")
533 * \param[in] id Fence device ID (may be NULL)
534 * \param[in] params Fence device configuration parameters
535 * \param[in] timeout How long to wait for operation to complete (in ms)
536 *
537 * \return Standard Pacemaker return code
538 */
539 int pcmk_fence_validate(xmlNodePtr *xml, stonith_t *st, const char *agent,
540 const char *id, const stonith_key_value_t *params,
541 unsigned int timeout);
542 #endif
543
544 #ifdef __cplusplus
545 }
546 #endif
547
548 #endif
![[bottom]](../icons/n_bottom.png){kind=icon}
*/