![[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-2021 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 PACEMAKER__H
11 # define PACEMAKER__H
12
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16
17 /**
18 * \file
19 * \brief High Level API
20 * \ingroup pacemaker
21 */
22
23 # include <glib.h>
24 # include <libxml/tree.h>
25 # include <crm/pengine/pe_types.h>
26
27 # include <crm/stonith-ng.h>
28
29 /*!
30 * \brief Modify operation of running a cluster simulation.
31 */
32 enum pcmk_sim_flags {
33 pcmk_sim_none = 0,
34 pcmk_sim_all_actions = 1 << 0,
35 pcmk_sim_show_pending = 1 << 1,
36 pcmk_sim_process = 1 << 2,
37 pcmk_sim_show_scores = 1 << 3,
38 pcmk_sim_show_utilization = 1 << 4,
39 pcmk_sim_simulate = 1 << 5,
40 pcmk_sim_sanitized = 1 << 6,
41 pcmk_sim_verbose = 1 << 7,
42 };
43
44 /*!
45 * \brief Synthetic cluster events that can be injected into the cluster
46 * for running simulations.
47 */
48 typedef struct {
49 /*! A list of node names (gchar *) to simulate bringing online */
50 GList *node_up;
51 /*! A list of node names (gchar *) to simulate bringing offline */
52 GList *node_down;
53 /*! A list of node names (gchar *) to simulate failing */
54 GList *node_fail;
55 /*! A list of operations (gchar *) to inject. The format of these strings
56 * is described in the "Operation Specification" section of crm_simulate
57 * help output.
58 */
59 GList *op_inject;
60 /*! A list of operations (gchar *) that should return a given error code
61 * if they fail. The format of these strings is described in the
62 * "Operation Specification" section of crm_simulate help output.
63 */
64 GList *op_fail;
65 /*! A list of tickets (gchar *) to simulate granting */
66 GList *ticket_grant;
67 /*! A list of tickets (gchar *) to simulate revoking */
68 GList *ticket_revoke;
69 /*! A list of tickets (gchar *) to simulate putting on standby */
70 GList *ticket_standby;
71 /*! A list of tickets (gchar *) to simulate activating */
72 GList *ticket_activate;
73 /*! Does the cluster have an active watchdog device? */
74 char *watchdog;
75 /*! Does the cluster have quorum? */
76 char *quorum;
77 } pcmk_injections_t;
78
79 /*!
80 * \brief Get controller status
81 *
82 * \param[in,out] xml The destination for the result, as an XML tree.
83 * \param[in] dest_node Destination node for request
84 * \param[in] message_timeout_ms Message timeout
85 *
86 * \return Standard Pacemaker return code
87 */
88 int pcmk_controller_status(xmlNodePtr *xml, char *dest_node, unsigned int message_timeout_ms);
89
90 /*!
91 * \brief Get designated controller
92 *
93 * \param[in,out] xml The destination for the result, as an XML tree.
94 * \param[in] message_timeout_ms Message timeout
95 *
96 * \return Standard Pacemaker return code
97 */
98 int pcmk_designated_controller(xmlNodePtr *xml, unsigned int message_timeout_ms);
99
100 /*!
101 * \brief Free a :pcmk_injections_t structure
102 *
103 * \param[in,out] injections The structure to be freed
104 */
105 void pcmk_free_injections(pcmk_injections_t *injections);
106
107 /*!
108 * \brief Get pacemakerd status
109 *
110 * \param[in,out] xml The destination for the result, as an XML tree.
111 * \param[in] ipc_name IPC name for request
112 * \param[in] message_timeout_ms Message timeout
113 *
114 * \return Standard Pacemaker return code
115 */
116 int pcmk_pacemakerd_status(xmlNodePtr *xml, char *ipc_name, unsigned int message_timeout_ms);
117
118 /*!
119 * \brief Calculate and output resource operation digests
120 *
121 * \param[out] xml Where to store XML with result
122 * \param[in] rsc Resource to calculate digests for
123 * \param[in] node Node whose operation history should be used
124 * \param[in] overrides Hash table of configuration parameters to override
125 * \param[in] data_set Cluster working set (with status)
126 *
127 * \return Standard Pacemaker return code
128 */
129 int pcmk_resource_digests(xmlNodePtr *xml, pe_resource_t *rsc,
130 pe_node_t *node, GHashTable *overrides,
131 pe_working_set_t *data_set);
132
133 /**
134 * \brief Simulate a cluster's response to events.
135 *
136 * This high-level function essentially implements crm_simulate(8). It operates
137 * on an input CIB file and various lists of events that can be simulated. It
138 * optionally writes out a variety of artifacts to show the results of the
139 * simulation. Output can be modified with various flags.
140 *
141 * \param[in,out] xml The destination for the result, as an XML tree.
142 * \param[in,out] data_set Working set for the cluster.
143 * \param[in] events A structure containing cluster events
144 * (node up/down, tickets, injected operations)
145 * \param[in] flags A bitfield of :pcmk_sim_flags to modify
146 * operation of the simulation.
147 * \param[in] section_opts Which portions of the cluster status output
148 * should be displayed?
149 * \param[in] use_date The date to set the cluster's time to
150 * (may be NULL).
151 * \param[in] input_file The source CIB file, which may be overwritten by
152 * this function (may be NULL).
153 * \param[in] graph_file Where to write the XML-formatted transition graph
154 * (may be NULL, in which case no file will be
155 * written).
156 * \param[in] dot_file Where to write the dot(1) formatted transition
157 * graph (may be NULL, in which case no file will
158 * be written). See \p pcmk__write_sim_dotfile().
159 *
160 * \return Standard Pacemaker return code
161 */
162 int pcmk_simulate(xmlNodePtr *xml, pe_working_set_t *data_set,
163 pcmk_injections_t *injections, unsigned int flags,
164 unsigned int section_opts, char *use_date, char *input_file,
165 char *graph_file, char *dot_file);
166
167 /*!
168 * \brief Get nodes list
169 *
170 * \param[in,out] xml The destination for the result, as an XML tree.
171 * \param[in] node_types Node type(s) to return (default: all)
172 *
173 * \return Standard Pacemaker return code
174 */
175 int pcmk_list_nodes(xmlNodePtr *xml, char *node_types);
176
177 #ifdef BUILD_PUBLIC_LIBPACEMAKER
178
179 /*!
180 * \brief Perform a STONITH action.
181 *
182 * \param[in] st A connection to the STONITH API.
183 * \param[in] target The node receiving the action.
184 * \param[in] action The action to perform.
185 * \param[in] name Who requested the fence action?
186 * \param[in] timeout How long to wait for the operation to complete (in ms).
187 * \param[in] tolerance If a successful action for \p target happened within
188 * this many ms, return 0 without performing the action
189 * again.
190 * \param[in] delay Apply a fencing delay. Value -1 means disable also any
191 * static/random fencing delays from pcmk_delay_base/max.
192 *
193 * \return Standard Pacemaker return code
194 */
195 int pcmk_fence_action(stonith_t *st, const char *target, const char *action,
196 const char *name, unsigned int timeout, unsigned int tolerance,
197 int delay);
198
199 /*!
200 * \brief List the fencing operations that have occurred for a specific node.
201 *
202 * \note If \p xml is not NULL, it will be freed first and the previous
203 * contents lost.
204 *
205 * \param[in,out] xml The destination for the result, as an XML tree.
206 * \param[in] st A connection to the STONITH API.
207 * \param[in] target The node to get history for.
208 * \param[in] timeout How long to wait for the operation to complete (in ms).
209 * \param[in] quiet Suppress most output.
210 * \param[in] verbose Include additional output.
211 * \param[in] broadcast Gather fencing history from all nodes.
212 * \param[in] cleanup Clean up fencing history after listing.
213 *
214 * \return Standard Pacemaker return code
215 */
216 int pcmk_fence_history(xmlNodePtr *xml, stonith_t *st, char *target,
217 unsigned int timeout, bool quiet, int verbose,
218 bool broadcast, bool cleanup);
219
220 /*!
221 * \brief List all installed STONITH agents.
222 *
223 * \note If \p xml is not NULL, it will be freed first and the previous
224 * contents lost.
225 *
226 * \param[in,out] xml The destination for the result, as an XML tree.
227 * \param[in] st A connection to the STONITH API.
228 * \param[in] timeout How long to wait for the operation to complete (in ms).
229 *
230 * \return Standard Pacemaker return code
231 */
232 int pcmk_fence_installed(xmlNodePtr *xml, stonith_t *st, unsigned int timeout);
233
234 /*!
235 * \brief When was a device last fenced?
236 *
237 * \note If \p xml is not NULL, it will be freed first and the previous
238 * contents lost.
239 *
240 * \param[in,out] xml The destination for the result, as an XML tree.
241 * \param[in] target The node that was fenced.
242 * \param[in] as_nodeid
243 *
244 * \return Standard Pacemaker return code
245 */
246 int pcmk_fence_last(xmlNodePtr *xml, const char *target, bool as_nodeid);
247
248 /*!
249 * \brief List nodes that can be fenced.
250 *
251 * \note If \p xml is not NULL, it will be freed first and the previous
252 * contents lost.
253 *
254 * \param[in,out] xml The destination for the result, as an XML tree
255 * \param[in] st A connection to the STONITH API
256 * \param[in] device_id Resource ID of fence device to check
257 * \param[in] timeout How long to wait for the operation to complete (in ms)
258 *
259 * \return Standard Pacemaker return code
260 */
261 int pcmk_fence_list_targets(xmlNodePtr *xml, stonith_t *st,
262 const char *device_id, unsigned int timeout);
263
264 /*!
265 * \brief Get metadata for a resource.
266 *
267 * \note If \p xml is not NULL, it will be freed first and the previous
268 * contents lost.
269 *
270 * \param[in,out] xml The destination for the result, as an XML tree.
271 * \param[in] st A connection to the STONITH API.
272 * \param[in] agent The fence agent to get metadata for.
273 * \param[in] timeout How long to wait for the operation to complete (in ms).
274 *
275 * \return Standard Pacemaker return code
276 */
277 int pcmk_fence_metadata(xmlNodePtr *xml, stonith_t *st, char *agent,
278 unsigned int timeout);
279
280 /*!
281 * \brief List registered fence devices.
282 *
283 * \note If \p xml is not NULL, it will be freed first and the previous
284 * contents lost.
285 *
286 * \param[in,out] xml The destination for the result, as an XML tree.
287 * \param[in] st A connection to the STONITH API.
288 * \param[in] target If not NULL, only return devices that can fence
289 * this node.
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_registered(xmlNodePtr *xml, stonith_t *st, char *target,
295 unsigned int timeout);
296
297 /*!
298 * \brief Register a fencing level for a specific node, node regex, or attribute.
299 *
300 * \p target can take three different forms:
301 * - name=value, in which case \p target is an attribute.
302 * - @pattern, in which case \p target is a node regex.
303 * - Otherwise, \p target is a node name.
304 *
305 * \param[in] st A connection to the STONITH API.
306 * \param[in] target The object to register a fencing level for.
307 * \param[in] fence_level Index number of level to add.
308 * \param[in] devices Devices to use in level.
309 *
310 * \return Standard Pacemaker return code
311 */
312 int pcmk_fence_register_level(stonith_t *st, char *target, int fence_level,
313 stonith_key_value_t *devices);
314
315 /*!
316 * \brief Unregister a fencing level for a specific node, node regex, or attribute.
317 *
318 * \p target can take three different forms:
319 * - name=value, in which case \p target is an attribute.
320 * - @pattern, in which case \p target is a node regex.
321 * - Otherwise, \p target is a node name.
322 *
323 * \param[in] st A connection to the STONITH API.
324 * \param[in] target The object to unregister a fencing level for.
325 * \param[in] fence_level Index number of level to remove.
326 *
327 * \return Standard Pacemaker return code
328 */
329 int pcmk_fence_unregister_level(stonith_t *st, char *target, int fence_level);
330
331 /*!
332 * \brief Validate a STONITH device configuration.
333 *
334 * \note If \p xml is not NULL, it will be freed first and the previous
335 * contents lost.
336 *
337 * \param[in,out] xml The destination for the result, as an XML tree.
338 * \param[in] st A connection to the STONITH API.
339 * \param[in] agent The agent to validate (for example, "fence_xvm").
340 * \param[in] id STONITH device ID (may be NULL).
341 * \param[in] params STONITH device configuration parameters.
342 * \param[in] timeout How long to wait for the operation to complete (in ms).
343 *
344 * \return Standard Pacemaker return code
345 */
346 int pcmk_fence_validate(xmlNodePtr *xml, stonith_t *st, const char *agent,
347 const char *id, stonith_key_value_t *params,
348 unsigned int timeout);
349 #endif
350
351 #ifdef __cplusplus
352 }
353 #endif
354
355 #endif
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/