![[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/cib/cib_types.h>
16 # include <crm/pengine/pe_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] data_set Cluster working set (with status)
206 *
207 * \return Standard Pacemaker return code
208 */
209 int pcmk_resource_digests(xmlNodePtr *xml, pe_resource_t *rsc,
210 const pe_node_t *node, GHashTable *overrides,
211 pe_working_set_t *data_set);
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] data_set Working set for the cluster
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, pe_working_set_t *data_set,
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 #ifdef BUILD_PUBLIC_LIBPACEMAKER
341
342 /*!
343 * \brief Ask the cluster to perform fencing
344 *
345 * \param[in,out] st A connection to the fencer API
346 * \param[in] target The node that should be fenced
347 * \param[in] action The fencing action (on, off, reboot) to perform
348 * \param[in] name Who requested the fence action?
349 * \param[in] timeout How long to wait for operation to complete (in ms)
350 * \param[in] tolerance If a successful action for \p target happened within
351 * this many ms, return 0 without performing the action
352 * again
353 * \param[in] delay Apply this delay (in milliseconds) before initiating
354 * fencing action (-1 applies no delay and also
355 * disables any fencing delay from pcmk_delay_base and
356 * pcmk_delay_max)
357 * \param[out] reason If not NULL, where to put descriptive failure reason
358 *
359 * \return Standard Pacemaker return code
360 * \note If \p reason is not NULL, the caller is responsible for freeing its
361 * returned value.
362 */
363 int pcmk_request_fencing(stonith_t *st, const char *target, const char *action,
364 const char *name, unsigned int timeout,
365 unsigned int tolerance, int delay, char **reason);
366
367 /*!
368 * \brief List the fencing operations that have occurred for a specific node
369 *
370 * \note If \p xml is not NULL, it will be freed first and the previous
371 * contents lost.
372 *
373 * \param[in,out] xml The destination for the result, as an XML tree
374 * \param[in,out] st A connection to the fencer API
375 * \param[in] target The node to get history for
376 * \param[in] timeout How long to wait for operation to complete (in ms)
377 * \param[in] quiet Suppress most output
378 * \param[in] verbose Include additional output
379 * \param[in] broadcast Gather fencing history from all nodes
380 * \param[in] cleanup Clean up fencing history after listing
381 *
382 * \return Standard Pacemaker return code
383 */
384 int pcmk_fence_history(xmlNodePtr *xml, stonith_t *st, const char *target,
385 unsigned int timeout, bool quiet, int verbose,
386 bool broadcast, bool cleanup);
387
388 /*!
389 * \brief List all installed fence agents
390 *
391 * \param[in,out] xml The destination for the result, as an XML tree (if
392 * not NULL, previous contents will be freed and lost)
393 * \param[in,out] st A connection to the fencer API
394 * \param[in] timeout How long to wait for operation to complete (in ms)
395 *
396 * \return Standard Pacemaker return code
397 */
398 int pcmk_fence_installed(xmlNodePtr *xml, stonith_t *st, unsigned int timeout);
399
400 /*!
401 * \brief When was a device last fenced?
402 *
403 * \param[in,out] xml The destination for the result, as an XML tree (if
404 * not NULL, previous contents will be freed and lost)
405 * \param[in] target The node that was fenced
406 * \param[in] as_nodeid If true, \p target has node ID rather than name
407 *
408 * \return Standard Pacemaker return code
409 */
410 int pcmk_fence_last(xmlNodePtr *xml, const char *target, bool as_nodeid);
411
412 /*!
413 * \brief List nodes that can be fenced
414 *
415 * \param[in,out] xml The destination for the result, as an XML tree (if
416 * not NULL, previous contents will be freed and lost)
417 * \param[in,out] st A connection to the fencer API
418 * \param[in] device_id Resource ID of fence device to check
419 * \param[in] timeout How long to wait for operation to complete (in ms)
420 *
421 * \return Standard Pacemaker return code
422 */
423 int pcmk_fence_list_targets(xmlNodePtr *xml, stonith_t *st,
424 const char *device_id, unsigned int timeout);
425
426 /*!
427 * \brief Get metadata for a fence agent
428 *
429 * \note If \p xml is not NULL, it will be freed first and the previous
430 * contents lost.
431 *
432 * \param[in,out] xml The destination for the result, as an XML tree (if
433 * not NULL, previous contents will be freed and lost)
434 * \param[in,out] st A connection to the fencer API
435 * \param[in] agent The fence agent to get metadata for
436 * \param[in] timeout How long to wait for operation to complete (in ms)
437 *
438 * \return Standard Pacemaker return code
439 */
440 int pcmk_fence_metadata(xmlNodePtr *xml, stonith_t *st, const char *agent,
441 unsigned int timeout);
442
443 /*!
444 * \brief List registered fence devices
445 *
446 * \param[in,out] xml The destination for the result, as an XML tree (if
447 * not NULL, previous contents will be freed and lost)
448 * \param[in,out] st A connection to the fencer API
449 * \param[in] target If not NULL, return only devices that can fence this
450 * \param[in] timeout How long to wait for operation to complete (in ms)
451 *
452 * \return Standard Pacemaker return code
453 */
454 int pcmk_fence_registered(xmlNodePtr *xml, stonith_t *st, const char *target,
455 unsigned int timeout);
456
457 /*!
458 * \brief Register a fencing topology level
459 *
460 * \param[in,out] st A connection to the fencer API
461 * \param[in] target What fencing level targets (as "name=value" to
462 * target by given node attribute, or "@pattern" to
463 * target by node name pattern, or a node name)
464 * \param[in] fence_level Index number of level to add
465 * \param[in] devices Devices to use in level
466 *
467 * \return Standard Pacemaker return code
468 */
469 int pcmk_fence_register_level(stonith_t *st, const char *target,
470 int fence_level,
471 const stonith_key_value_t *devices);
472
473 /*!
474 * \brief Unregister a fencing topology level
475 *
476 * \param[in,out] st A connection to the fencer API
477 * \param[in] target What fencing level targets (as "name=value" to
478 * target by given node attribute, or "@pattern" to
479 * target by node name pattern, or a node name)
480 * \param[in] fence_level Index number of level to remove
481 *
482 * \return Standard Pacemaker return code
483 */
484 int pcmk_fence_unregister_level(stonith_t *st, const char *target,
485 int fence_level);
486
487 /*!
488 * \brief Validate a fence device configuration
489 *
490 * \param[in,out] xml The destination for the result, as an XML tree (if
491 * not NULL, previous contents will be freed and lost)
492 * \param[in,out] st A connection to the fencer API
493 * \param[in] agent The agent to validate (for example, "fence_xvm")
494 * \param[in] id Fence device ID (may be NULL)
495 * \param[in] params Fence device configuration parameters
496 * \param[in] timeout How long to wait for operation to complete (in ms)
497 *
498 * \return Standard Pacemaker return code
499 */
500 int pcmk_fence_validate(xmlNodePtr *xml, stonith_t *st, const char *agent,
501 const char *id, const stonith_key_value_t *params,
502 unsigned int timeout);
503 #endif
504
505 #ifdef __cplusplus
506 }
507 #endif
508
509 #endif
![[bottom]](../icons/n_bottom.png){kind=icon}
*/