![[bottom]](../icons/bottom.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[first]](../icons/n_first.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * Copyright 2019-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__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 controller status
83 *
84 * \param[in,out] xml The destination for the result, as an XML tree.
85 * \param[in] dest_node Destination node for request
86 * \param[in] message_timeout_ms Message timeout
87 *
88 * \return Standard Pacemaker return code
89 */
90 int pcmk_controller_status(xmlNodePtr *xml, char *dest_node, unsigned int message_timeout_ms);
91
92 /*!
93 * \brief Get designated controller
94 *
95 * \param[in,out] xml The destination for the result, as an XML tree.
96 * \param[in] message_timeout_ms Message timeout
97 *
98 * \return Standard Pacemaker return code
99 */
100 int pcmk_designated_controller(xmlNodePtr *xml, unsigned int message_timeout_ms);
101
102 /*!
103 * \brief Free a :pcmk_injections_t structure
104 *
105 * \param[in,out] injections The structure to be freed
106 */
107 void pcmk_free_injections(pcmk_injections_t *injections);
108
109 /*!
110 * \brief Get pacemakerd status
111 *
112 * \param[in,out] xml The destination for the result, as an XML tree.
113 * \param[in] ipc_name IPC name for request
114 * \param[in] message_timeout_ms Message timeout
115 *
116 * \return Standard Pacemaker return code
117 */
118 int pcmk_pacemakerd_status(xmlNodePtr *xml, char *ipc_name, unsigned int message_timeout_ms);
119
120 /*!
121 * \brief Calculate and output resource operation digests
122 *
123 * \param[out] xml Where to store XML with result
124 * \param[in] rsc Resource to calculate digests for
125 * \param[in] node Node whose operation history should be used
126 * \param[in] overrides Hash table of configuration parameters to override
127 * \param[in] data_set Cluster working set (with status)
128 *
129 * \return Standard Pacemaker return code
130 */
131 int pcmk_resource_digests(xmlNodePtr *xml, pe_resource_t *rsc,
132 pe_node_t *node, GHashTable *overrides,
133 pe_working_set_t *data_set);
134
135 /**
136 * \brief Simulate a cluster's response to events.
137 *
138 * This high-level function essentially implements crm_simulate(8). It operates
139 * on an input CIB file and various lists of events that can be simulated. It
140 * optionally writes out a variety of artifacts to show the results of the
141 * simulation. Output can be modified with various flags.
142 *
143 * \param[in,out] xml The destination for the result, as an XML tree.
144 * \param[in,out] data_set Working set for the cluster.
145 * \param[in] events A structure containing cluster events
146 * (node up/down, tickets, injected operations)
147 * \param[in] flags A bitfield of :pcmk_sim_flags to modify
148 * operation of the simulation.
149 * \param[in] section_opts Which portions of the cluster status output
150 * should be displayed?
151 * \param[in] use_date The date to set the cluster's time to
152 * (may be NULL).
153 * \param[in] input_file The source CIB file, which may be overwritten by
154 * this function (may be NULL).
155 * \param[in] graph_file Where to write the XML-formatted transition graph
156 * (may be NULL, in which case no file will be
157 * written).
158 * \param[in] dot_file Where to write the dot(1) formatted transition
159 * graph (may be NULL, in which case no file will
160 * be written). See \p pcmk__write_sim_dotfile().
161 *
162 * \return Standard Pacemaker return code
163 */
164 int pcmk_simulate(xmlNodePtr *xml, pe_working_set_t *data_set,
165 pcmk_injections_t *injections, unsigned int flags,
166 unsigned int section_opts, char *use_date, char *input_file,
167 char *graph_file, char *dot_file);
168
169 /*!
170 * \brief Get nodes list
171 *
172 * \param[in,out] xml The destination for the result, as an XML tree.
173 * \param[in] node_types Node type(s) to return (default: all)
174 *
175 * \return Standard Pacemaker return code
176 */
177 int pcmk_list_nodes(xmlNodePtr *xml, char *node_types);
178
179 /*!
180 * \brief Output the current status of the cluster, formatted in the same way
181 * that `crm_mon --output-as=xml` would.
182 *
183 * \param[in,out] xml The destination for the result, as an XML tree.
184 *
185 * \return Standard Pacemaker return code
186 */
187 int pcmk_status(xmlNodePtr *xml);
188
189 #ifdef BUILD_PUBLIC_LIBPACEMAKER
190
191 /*!
192 * \brief Ask the cluster to perform fencing
193 *
194 * \param[in] st A connection to the fencer API
195 * \param[in] target The node that should be fenced
196 * \param[in] action The fencing action (on, off, reboot) to perform
197 * \param[in] name Who requested the fence action?
198 * \param[in] timeout How long to wait for the operation to complete (in ms)
199 * \param[in] tolerance If a successful action for \p target happened within
200 * this many ms, return 0 without performing the action
201 * again
202 * \param[in] delay Apply this delay (in milliseconds) before initiating the
203 * fencing action (a value of -1 applies no delay and also
204 * disables any fencing delay from pcmk_delay_base and
205 * pcmk_delay_max)
206 * \param[out] reason If not NULL, where to put descriptive failure reason
207 *
208 * \return Standard Pacemaker return code
209 * \note If \p reason is not NULL, the caller is responsible for freeing its
210 * returned value.
211 */
212 int pcmk_request_fencing(stonith_t *st, const char *target, const char *action,
213 const char *name, unsigned int timeout,
214 unsigned int tolerance, int delay, char **reason);
215
216 /*!
217 * \brief List the fencing operations that have occurred for a specific node.
218 *
219 * \note If \p xml is not NULL, it will be freed first and the previous
220 * contents lost.
221 *
222 * \param[in,out] xml The destination for the result, as an XML tree.
223 * \param[in] st A connection to the STONITH API.
224 * \param[in] target The node to get history for.
225 * \param[in] timeout How long to wait for the operation to complete (in ms).
226 * \param[in] quiet Suppress most output.
227 * \param[in] verbose Include additional output.
228 * \param[in] broadcast Gather fencing history from all nodes.
229 * \param[in] cleanup Clean up fencing history after listing.
230 *
231 * \return Standard Pacemaker return code
232 */
233 int pcmk_fence_history(xmlNodePtr *xml, stonith_t *st, char *target,
234 unsigned int timeout, bool quiet, int verbose,
235 bool broadcast, bool cleanup);
236
237 /*!
238 * \brief List all installed STONITH agents.
239 *
240 * \note If \p xml is not NULL, it will be freed first and the previous
241 * contents lost.
242 *
243 * \param[in,out] xml The destination for the result, as an XML tree.
244 * \param[in] st A connection to the STONITH API.
245 * \param[in] timeout How long to wait for the operation to complete (in ms).
246 *
247 * \return Standard Pacemaker return code
248 */
249 int pcmk_fence_installed(xmlNodePtr *xml, stonith_t *st, unsigned int timeout);
250
251 /*!
252 * \brief When was a device last fenced?
253 *
254 * \note If \p xml is not NULL, it will be freed first and the previous
255 * contents lost.
256 *
257 * \param[in,out] xml The destination for the result, as an XML tree.
258 * \param[in] target The node that was fenced.
259 * \param[in] as_nodeid
260 *
261 * \return Standard Pacemaker return code
262 */
263 int pcmk_fence_last(xmlNodePtr *xml, const char *target, bool as_nodeid);
264
265 /*!
266 * \brief List nodes that can be fenced.
267 *
268 * \note If \p xml is not NULL, it will be freed first and the previous
269 * contents lost.
270 *
271 * \param[in,out] xml The destination for the result, as an XML tree
272 * \param[in] st A connection to the STONITH API
273 * \param[in] device_id Resource ID of fence device to check
274 * \param[in] timeout How long to wait for the operation to complete (in ms)
275 *
276 * \return Standard Pacemaker return code
277 */
278 int pcmk_fence_list_targets(xmlNodePtr *xml, stonith_t *st,
279 const char *device_id, unsigned int timeout);
280
281 /*!
282 * \brief Get metadata for a resource.
283 *
284 * \note If \p xml is not NULL, it will be freed first and the previous
285 * contents lost.
286 *
287 * \param[in,out] xml The destination for the result, as an XML tree.
288 * \param[in] st A connection to the STONITH API.
289 * \param[in] agent The fence agent to get metadata for.
290 * \param[in] timeout How long to wait for the operation to complete (in ms).
291 *
292 * \return Standard Pacemaker return code
293 */
294 int pcmk_fence_metadata(xmlNodePtr *xml, stonith_t *st, char *agent,
295 unsigned int timeout);
296
297 /*!
298 * \brief List registered fence devices.
299 *
300 * \note If \p xml is not NULL, it will be freed first and the previous
301 * contents lost.
302 *
303 * \param[in,out] xml The destination for the result, as an XML tree.
304 * \param[in] st A connection to the STONITH API.
305 * \param[in] target If not NULL, only return devices that can fence
306 * this node.
307 * \param[in] timeout How long to wait for the operation to complete (in ms).
308 *
309 * \return Standard Pacemaker return code
310 */
311 int pcmk_fence_registered(xmlNodePtr *xml, stonith_t *st, char *target,
312 unsigned int timeout);
313
314 /*!
315 * \brief Register a fencing level for a specific node, node regex, or attribute.
316 *
317 * \p target can take three different forms:
318 * - name=value, in which case \p target is an attribute.
319 * - @pattern, in which case \p target is a node regex.
320 * - Otherwise, \p target is a node name.
321 *
322 * \param[in] st A connection to the STONITH API.
323 * \param[in] target The object to register a fencing level for.
324 * \param[in] fence_level Index number of level to add.
325 * \param[in] devices Devices to use in level.
326 *
327 * \return Standard Pacemaker return code
328 */
329 int pcmk_fence_register_level(stonith_t *st, char *target, int fence_level,
330 stonith_key_value_t *devices);
331
332 /*!
333 * \brief Unregister a fencing level for a specific node, node regex, or attribute.
334 *
335 * \p target can take three different forms:
336 * - name=value, in which case \p target is an attribute.
337 * - @pattern, in which case \p target is a node regex.
338 * - Otherwise, \p target is a node name.
339 *
340 * \param[in] st A connection to the STONITH API.
341 * \param[in] target The object to unregister a fencing level for.
342 * \param[in] fence_level Index number of level to remove.
343 *
344 * \return Standard Pacemaker return code
345 */
346 int pcmk_fence_unregister_level(stonith_t *st, char *target, int fence_level);
347
348 /*!
349 * \brief Validate a STONITH device configuration.
350 *
351 * \note If \p xml is not NULL, it will be freed first and the previous
352 * contents lost.
353 *
354 * \param[in,out] xml The destination for the result, as an XML tree.
355 * \param[in] st A connection to the STONITH API.
356 * \param[in] agent The agent to validate (for example, "fence_xvm").
357 * \param[in] id STONITH device ID (may be NULL).
358 * \param[in] params STONITH device configuration parameters.
359 * \param[in] timeout How long to wait for the operation to complete (in ms).
360 *
361 * \return Standard Pacemaker return code
362 */
363 int pcmk_fence_validate(xmlNodePtr *xml, stonith_t *st, const char *agent,
364 const char *id, stonith_key_value_t *params,
365 unsigned int timeout);
366 #endif
367
368 #ifdef __cplusplus
369 }
370 #endif
371
372 #endif
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/