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 #ifndef PCMK__PCMKI_PCMKI_FENCE__H 10 # define PCMK__PCMKI_PCMKI_FENCE__H 11 12 # include <crm/stonith-ng.h> 13 # include <crm/common/output_internal.h> 14 15 /*! 16 * \brief Control how much of the fencing history is output. 17 */ 18 enum pcmk__fence_history { 19 pcmk__fence_history_none, 20 pcmk__fence_history_reduced, 21 pcmk__fence_history_full 22 }; 23 24 /*! 25 * \brief Ask the cluster to perform fencing 26 * 27 * \note This is the internal version of pcmk_request_fencing(). External users 28 * of the pacemaker API should use that function instead. 29 * 30 * \param[in,out] st A connection to the fencer API 31 * \param[in] target The node that should be fenced 32 * \param[in] action The fencing action (on, off, reboot) to perform 33 * \param[in] name Who requested the fence action? 34 * \param[in] timeout How long to wait for operation to complete (in ms) 35 * \param[in] tolerance If a successful action for \p target happened within 36 * this many milliseconds, return success without 37 * performing the action again 38 * \param[in] delay Apply this delay (in milliseconds) before initiating 39 * fencing action (a value of -1 applies no delay and 40 * disables any fencing delay from pcmk_delay_base and 41 * pcmk_delay_max) 42 * \param[out] reason If not NULL, where to put descriptive failure reason 43 * 44 * \return Standard Pacemaker return code 45 * \note If \p reason is not NULL, the caller is responsible for freeing its 46 * returned value. 47 * \todo delay is eventually used with g_timeout_add() and should be guint 48 */ 49 int pcmk__request_fencing(stonith_t *st, const char *target, const char *action, 50 const char *name, unsigned int timeout, 51 unsigned int tolerance, int delay, char **reason); 52 53 /*! 54 * \brief List the fencing operations that have occurred for a specific node 55 * 56 * \note This is the internal version of pcmk_fence_history(). External users 57 * of the pacemaker API should use that function instead. 58 * 59 * \note \p out should be initialized with pcmk__output_new() before calling this 60 * function and destroyed with out->finish and pcmk__output_free() before 61 * reusing it with any other functions in this library. 62 * 63 * \param[in,out] out The output functions structure 64 * \param[in,out] st A connection to the fencer API 65 * \param[in] target The node to get history for 66 * \param[in] timeout How long to wait for operation to complete (in ms) 67 * \param[in] verbose Include additional output 68 * \param[in] broadcast Gather fencing history from all nodes 69 * \param[in] cleanup Clean up fencing history after listing 70 * 71 * \return Standard Pacemaker return code 72 */ 73 int pcmk__fence_history(pcmk__output_t *out, stonith_t *st, const char *target, 74 unsigned int timeout, int verbose, bool broadcast, 75 bool cleanup); 76 77 /*! 78 * \brief List all installed fence agents 79 * 80 * \note This is the internal version of pcmk_fence_installed(). External users 81 * of the pacemaker API should use that function instead. 82 * 83 * \note \p out should be initialized with pcmk__output_new() before calling this 84 * function and destroyed with out->finish and pcmk__output_free() before 85 * reusing it with any other functions in this library. 86 * 87 * \param[in,out] out The output functions structure 88 * \param[in,out] st A connection to the fencer API 89 * \param[in] timeout How long to wait for the operation to complete (in ms) 90 * 91 * \return Standard Pacemaker return code 92 */ 93 int pcmk__fence_installed(pcmk__output_t *out, stonith_t *st, unsigned int timeout); 94 95 /*! 96 * \brief When was a device last fenced? 97 * 98 * \note This is the internal version of pcmk_fence_last(). External users 99 * of the pacemaker API should use that function instead. 100 * 101 * \note \p out should be initialized with pcmk__output_new() before calling this 102 * function and destroyed with out->finish and pcmk__output_free() before 103 * reusing it with any other functions in this library. 104 * 105 * \param[in,out] out The output functions structure. 106 * \param[in] target The node that was fenced. 107 * \param[in] as_nodeid 108 * 109 * \return Standard Pacemaker return code 110 */ 111 int pcmk__fence_last(pcmk__output_t *out, const char *target, bool as_nodeid); 112 113 /*! 114 * \brief List nodes that can be fenced 115 * 116 * \note This is the internal version of pcmk_fence_list_targets(). External users 117 * of the pacemaker API should use that function instead. 118 * 119 * \note \p out should be initialized with pcmk__output_new() before calling this 120 * function and destroyed with out->finish and pcmk__output_free() before 121 * reusing it with any other functions in this library. 122 * 123 * \param[in,out] out The output functions structure 124 * \param[in,out] st A connection to the fencer API 125 * \param[in] device_id Resource ID of fence device to check 126 * \param[in] timeout How long to wait for operation to complete (in ms) 127 * 128 * \return Standard Pacemaker return code 129 */ 130 int pcmk__fence_list_targets(pcmk__output_t *out, stonith_t *st, 131 const char *device_id, unsigned int timeout); 132 133 /*! 134 * \brief Get metadata for a fence agent 135 * 136 * \note This is the internal version of pcmk_fence_metadata(). External users 137 * of the pacemaker API should use that function instead. 138 * 139 * \note \p out should be initialized with pcmk__output_new() before calling this 140 * function and destroyed with out->finish and pcmk__output_free() before 141 * reusing it with any other functions in this library. 142 * 143 * \param[in,out] out The output functions structure 144 * \param[in,out] st A connection to the fencer API 145 * \param[in] agent The fence agent to get metadata for 146 * \param[in] timeout How long to wait for the operation to complete (in ms) 147 * 148 * \return Standard Pacemaker return code 149 */ 150 int pcmk__fence_metadata(pcmk__output_t *out, stonith_t *st, const char *agent, 151 unsigned int timeout); 152 153 /*! 154 * \brief List registered fence devices 155 * 156 * \note This is the internal version of pcmk_fence_metadata(). External users 157 * of the pacemaker API should use that function instead. 158 * 159 * \note \p out should be initialized with pcmk__output_new() before calling this 160 * function and destroyed with out->finish and pcmk__output_free() before 161 * reusing it with any other functions in this library. 162 * 163 * \param[in,out] out The output functions structure 164 * \param[in,out] st A connection to the fencer API 165 * \param[in] target If not NULL, return only devices that can fence this 166 * \param[in] timeout How long to wait for the operation to complete (in ms) 167 * 168 * \return Standard Pacemaker return code 169 */ 170 int pcmk__fence_registered(pcmk__output_t *out, stonith_t *st, 171 const char *target, unsigned int timeout); 172 173 /*! 174 * \brief Register a fencing level for a specific node, node regex, or attribute 175 * 176 * \note This is the internal version of pcmk_fence_register_level(). External users 177 * of the pacemaker API should use that function instead. 178 * 179 * \p target can take three different forms: 180 * - name=value, in which case \p target is an attribute. 181 * - @pattern, in which case \p target is a node regex. 182 * - Otherwise, \p target is a node name. 183 * 184 * \param[in,out] st A connection to the fencer API 185 * \param[in] target The object to register a fencing level for 186 * \param[in] fence_level Index number of level to add 187 * \param[in] devices Devices to use in level 188 * 189 * \return Standard Pacemaker return code 190 */ 191 int pcmk__fence_register_level(stonith_t *st, const char *target, 192 int fence_level, 193 const stonith_key_value_t *devices); 194 195 /*! 196 * \brief Unregister a fencing level for specific node, node regex, or attribute 197 * 198 * \note This is the internal version of pcmk_fence_unregister_level(). External users 199 * of the pacemaker API should use that function instead. 200 * 201 * \p target can take three different forms: 202 * - name=value, in which case \p target is an attribute. 203 * - @pattern, in which case \p target is a node regex. 204 * - Otherwise, \p target is a node name. 205 * 206 * \param[in,out] st A connection to the fencer API 207 * \param[in] target The object to unregister a fencing level for 208 * \param[in] fence_level Index number of level to remove 209 * 210 * \return Standard Pacemaker return code 211 */ 212 int pcmk__fence_unregister_level(stonith_t *st, const char *target, 213 int fence_level); 214 215 /*! 216 * \brief Validate a fence device configuration 217 * 218 * \note This is the internal version of pcmk_stonith_validate(). External users 219 * of the pacemaker API should use that function instead. 220 * 221 * \note \p out should be initialized with pcmk__output_new() before calling this 222 * function and destroyed with out->finish and pcmk__output_free() before 223 * reusing it with any other functions in this library. 224 * 225 * \param[in,out] out The output functions structure 226 * \param[in,out] st A connection to the fencer API 227 * \param[in] agent The agent to validate (for example, "fence_xvm") 228 * \param[in] id Fence device ID (may be NULL) 229 * \param[in] params Fence device configuration parameters 230 * \param[in] timeout How long to wait for the operation to complete (in ms) 231 * 232 * \return Standard Pacemaker return code 233 */ 234 int pcmk__fence_validate(pcmk__output_t *out, stonith_t *st, const char *agent, 235 const char *id, const stonith_key_value_t *params, 236 unsigned int timeout); 237 238 /*! 239 * \brief Fetch fencing history, optionally reducing it 240 * 241 * \param[in,out] st A connection to the fencer API 242 * \param[out] stonith_history Destination for storing the history 243 * \param[in] fence_history How much of the fencing history to display 244 * 245 * \return Standard Pacemaker return code 246 */ 247 int 248 pcmk__get_fencing_history(stonith_t *st, stonith_history_t **stonith_history, 249 enum pcmk__fence_history fence_history); 250 #endif