root/lib/common/crmcommon_private.h

/* */

INCLUDED FROM

DEFINITIONS

1. pcmk__log_xmllib_err

   1 /*
   2  * Copyright 2018-2024 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__COMMON_CRMCOMMON_PRIVATE__H
  11 #define PCMK__COMMON_CRMCOMMON_PRIVATE__H
  12 
  13 /* This header is for the sole use of libcrmcommon, so that functions can be
  14  * declared with G_GNUC_INTERNAL for efficiency.
  15  */
  16 
  17 #include <stdint.h>         // uint8_t, uint32_t
  18 #include <stdbool.h>        // bool
  19 #include <sys/types.h>      // size_t
  20 
  21 #include <glib.h>           // G_GNUC_INTERNAL, G_GNUC_PRINTF, gchar, etc.
  22 #include <libxml/tree.h>    // xmlNode, xmlAttr
  23 #include <qb/qbipcc.h>      // struct qb_ipc_response_header
  24 
  25 #include <crm/common/ipc.h>             // pcmk_ipc_api_t, crm_ipc_t, etc.
  26 #include <crm/common/iso8601.h>         // crm_time_t
  27 #include <crm/common/logging.h>         // LOG_NEVER
  28 #include <crm/common/mainloop.h>        // mainloop_io_t
  29 #include <crm/common/output_internal.h> // pcmk__output_t
  30 #include <crm/common/results.h>         // crm_exit_t
  31 #include <crm/common/rules.h>           // pcmk_rule_input_t
  32 #include <crm/common/xml.h>             // pcmkXmlStr
  33 #include <crm/common/xml_internal.h>    // enum xml_private_flags
  34 
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38 
  39 // Decent chunk size for processing large amounts of data
  40 #define PCMK__BUFFER_SIZE 4096
  41 
  42 #if defined(PCMK__UNIT_TESTING)
  43 #undef G_GNUC_INTERNAL
  44 #define G_GNUC_INTERNAL
  45 #endif
  46 
  47 /* When deleting portions of an XML tree, we keep a record so we can know later
  48  * (e.g. when checking differences) that something was deleted.
  49  */
  50 typedef struct pcmk__deleted_xml_s {
  51     gchar *path;
  52     int position;
  53 } pcmk__deleted_xml_t;
  54 
  55 typedef struct xml_node_private_s {
  56         uint32_t check;
  57         uint32_t flags;
  58 } xml_node_private_t;
  59 
  60 typedef struct xml_doc_private_s {
  61         uint32_t check;
  62         uint32_t flags;
  63         char *user;
  64         GList *acls;
  65         GList *deleted_objs; // List of pcmk__deleted_xml_t
  66 } xml_doc_private_t;
  67 
  68 // XML private data magic numbers
  69 #define PCMK__XML_DOC_PRIVATE_MAGIC     0x81726354UL
  70 #define PCMK__XML_NODE_PRIVATE_MAGIC    0x54637281UL
  71 
  72 // XML entity references
  73 #define PCMK__XML_ENTITY_AMP    "&amp;"
  74 #define PCMK__XML_ENTITY_GT     "&gt;"
  75 #define PCMK__XML_ENTITY_LT     "&lt;"
  76 #define PCMK__XML_ENTITY_QUOT   "&quot;"
  77 
  78 #define pcmk__set_xml_flags(xml_priv, flags_to_set) do {                    \
  79         (xml_priv)->flags = pcmk__set_flags_as(__func__, __LINE__,          \
  80             LOG_NEVER, "XML", "XML node", (xml_priv)->flags,                \
  81             (flags_to_set), #flags_to_set);                                 \
  82     } while (0)
  83 
  84 #define pcmk__clear_xml_flags(xml_priv, flags_to_clear) do {                \
  85         (xml_priv)->flags = pcmk__clear_flags_as(__func__, __LINE__,        \
  86             LOG_NEVER, "XML", "XML node", (xml_priv)->flags,                \
  87             (flags_to_clear), #flags_to_clear);                             \
  88     } while (0)
  89 
  90 G_GNUC_INTERNAL
  91 bool pcmk__xml_reset_node_flags(xmlNode *xml, void *user_data);
  92 
  93 G_GNUC_INTERNAL
  94 void pcmk__xml_set_parent_flags(xmlNode *xml, uint64_t flags);
  95 
  96 G_GNUC_INTERNAL
  97 void pcmk__xml_new_private_data(xmlNode *xml);
  98 
  99 G_GNUC_INTERNAL
 100 void pcmk__xml_free_private_data(xmlNode *xml);
 101 
 102 G_GNUC_INTERNAL
 103 void pcmk__xml_free_node(xmlNode *xml);
 104 
 105 G_GNUC_INTERNAL
 106 xmlDoc *pcmk__xml_new_doc(void);
 107 
 108 G_GNUC_INTERNAL
 109 bool pcmk__tracking_xml_changes(xmlNode *xml, bool lazy);
 110 
 111 G_GNUC_INTERNAL
 112 int pcmk__xml_position(const xmlNode *xml,
 113                        enum xml_private_flags ignore_if_set);
 114 
 115 G_GNUC_INTERNAL
 116 xmlNode *pcmk__xml_match(const xmlNode *haystack, const xmlNode *needle,
 117                          bool exact);
 118 
 119 G_GNUC_INTERNAL
 120 xmlNode *pcmk__xc_match(const xmlNode *root, const xmlNode *search_comment,
 121                         bool exact);
 122 
 123 G_GNUC_INTERNAL
 124 void pcmk__xc_update(xmlNode *parent, xmlNode *target, xmlNode *update);
 125 
 126 G_GNUC_INTERNAL
 127 void pcmk__free_acls(GList *acls);
 128 
 129 G_GNUC_INTERNAL
 130 void pcmk__unpack_acl(xmlNode *source, xmlNode *target, const char *user);
 131 
 132 G_GNUC_INTERNAL
 133 bool pcmk__is_user_in_group(const char *user, const char *group);
 134 
 135 G_GNUC_INTERNAL
 136 void pcmk__apply_acl(xmlNode *xml);
 137 
 138 G_GNUC_INTERNAL
 139 void pcmk__apply_creation_acl(xmlNode *xml, bool check_top);
 140 
 141 G_GNUC_INTERNAL
 142 int pcmk__xa_remove(xmlAttr *attr, bool force);
 143 
 144 G_GNUC_INTERNAL
 145 void pcmk__mark_xml_attr_dirty(xmlAttr *a);
 146 
 147 G_GNUC_INTERNAL
 148 bool pcmk__xa_filterable(const char *name);
 149 
 150 G_GNUC_INTERNAL
 151 void pcmk__log_xmllib_err(void *ctx, const char *fmt, ...)
     /*  */
 152 G_GNUC_PRINTF(2, 3);
 153 
 154 G_GNUC_INTERNAL
 155 void pcmk__mark_xml_node_dirty(xmlNode *xml);
 156 
 157 G_GNUC_INTERNAL
 158 bool pcmk__marked_as_deleted(xmlAttrPtr a, void *user_data);
 159 
 160 G_GNUC_INTERNAL
 161 void pcmk__dump_xml_attr(const xmlAttr *attr, GString *buffer);
 162 
 163 G_GNUC_INTERNAL
 164 int pcmk__xe_set_score(xmlNode *target, const char *name, const char *value);
 165 
 166 G_GNUC_INTERNAL
 167 bool pcmk__xml_is_name_start_char(const char *utf8, int *len);
 168 
 169 G_GNUC_INTERNAL
 170 bool pcmk__xml_is_name_char(const char *utf8, int *len);
 171 
 172 /*
 173  * Date/times
 174  */
 175 
 176 // For use with pcmk__add_time_from_xml()
 177 enum pcmk__time_component {
 178     pcmk__time_unknown,
 179     pcmk__time_years,
 180     pcmk__time_months,
 181     pcmk__time_weeks,
 182     pcmk__time_days,
 183     pcmk__time_hours,
 184     pcmk__time_minutes,
 185     pcmk__time_seconds,
 186 };
 187 
 188 G_GNUC_INTERNAL
 189 const char *pcmk__time_component_attr(enum pcmk__time_component component);
 190 
 191 G_GNUC_INTERNAL
 192 int pcmk__add_time_from_xml(crm_time_t *t, enum pcmk__time_component component,
 193                             const xmlNode *xml);
 194 
 195 G_GNUC_INTERNAL
 196 void pcmk__set_time_if_earlier(crm_time_t *target, const crm_time_t *source);
 197 
 198 
 199 /*
 200  * IPC
 201  */
 202 
 203 #define PCMK__IPC_VERSION 1
 204 
 205 #define PCMK__CONTROLD_API_MAJOR "1"
 206 #define PCMK__CONTROLD_API_MINOR "0"
 207 
 208 // IPC behavior that varies by daemon
 209 typedef struct pcmk__ipc_methods_s {
 210     /*!
 211      * \internal
 212      * \brief Allocate any private data needed by daemon IPC
 213      *
 214      * \param[in,out] api  IPC API connection
 215      *
 216      * \return Standard Pacemaker return code
 217      */
 218     int (*new_data)(pcmk_ipc_api_t *api);
 219 
 220     /*!
 221      * \internal
 222      * \brief Free any private data used by daemon IPC
 223      *
 224      * \param[in,out] api_data  Data allocated by new_data() method
 225      */
 226     void (*free_data)(void *api_data);
 227 
 228     /*!
 229      * \internal
 230      * \brief Perform daemon-specific handling after successful connection
 231      *
 232      * Some daemons require clients to register before sending any other
 233      * commands. The controller requires a CRM_OP_HELLO (with no reply), and
 234      * the CIB manager, executor, and fencer require a CRM_OP_REGISTER (with a
 235      * reply). Ideally this would be consistent across all daemons, but for now
 236      * this allows each to do its own authorization.
 237      *
 238      * \param[in,out] api  IPC API connection
 239      *
 240      * \return Standard Pacemaker return code
 241      */
 242     int (*post_connect)(pcmk_ipc_api_t *api);
 243 
 244     /*!
 245      * \internal
 246      * \brief Check whether an IPC request results in a reply
 247      *
 248      * \param[in,out] api      IPC API connection
 249      * \param[in]     request  IPC request XML
 250      *
 251      * \return true if request would result in an IPC reply, false otherwise
 252      */
 253     bool (*reply_expected)(pcmk_ipc_api_t *api, const xmlNode *request);
 254 
 255     /*!
 256      * \internal
 257      * \brief Perform daemon-specific handling of an IPC message
 258      *
 259      * \param[in,out] api  IPC API connection
 260      * \param[in,out] msg  Message read from IPC connection
 261      *
 262      * \return true if more IPC reply messages should be expected
 263      */
 264     bool (*dispatch)(pcmk_ipc_api_t *api, xmlNode *msg);
 265 
 266     /*!
 267      * \internal
 268      * \brief Perform daemon-specific handling of an IPC disconnect
 269      *
 270      * \param[in,out] api  IPC API connection
 271      */
 272     void (*post_disconnect)(pcmk_ipc_api_t *api);
 273 } pcmk__ipc_methods_t;
 274 
 275 // Implementation of pcmk_ipc_api_t
 276 struct pcmk_ipc_api_s {
 277     enum pcmk_ipc_server server;          // Daemon this IPC API instance is for
 278     enum pcmk_ipc_dispatch dispatch_type; // How replies should be dispatched
 279     size_t ipc_size_max;                  // maximum IPC buffer size
 280     crm_ipc_t *ipc;                       // IPC connection
 281     mainloop_io_t *mainloop_io;     // If using mainloop, I/O source for IPC
 282     bool free_on_disconnect;        // Whether disconnect should free object
 283     pcmk_ipc_callback_t cb;         // Caller-registered callback (if any)
 284     void *user_data;                // Caller-registered data (if any)
 285     void *api_data;                 // For daemon-specific use
 286     pcmk__ipc_methods_t *cmds;      // Behavior that varies by daemon
 287 };
 288 
 289 typedef struct pcmk__ipc_header_s {
 290     struct qb_ipc_response_header qb;
 291     uint32_t size_uncompressed;
 292     uint32_t size_compressed;
 293     uint32_t flags;
 294     uint8_t version;
 295 } pcmk__ipc_header_t;
 296 
 297 G_GNUC_INTERNAL
 298 int pcmk__send_ipc_request(pcmk_ipc_api_t *api, const xmlNode *request);
 299 
 300 G_GNUC_INTERNAL
 301 void pcmk__call_ipc_callback(pcmk_ipc_api_t *api,
 302                              enum pcmk_ipc_event event_type,
 303                              crm_exit_t status, void *event_data);
 304 
 305 G_GNUC_INTERNAL
 306 unsigned int pcmk__ipc_buffer_size(unsigned int max);
 307 
 308 G_GNUC_INTERNAL
 309 bool pcmk__valid_ipc_header(const pcmk__ipc_header_t *header);
 310 
 311 G_GNUC_INTERNAL
 312 pcmk__ipc_methods_t *pcmk__attrd_api_methods(void);
 313 
 314 G_GNUC_INTERNAL
 315 pcmk__ipc_methods_t *pcmk__controld_api_methods(void);
 316 
 317 G_GNUC_INTERNAL
 318 pcmk__ipc_methods_t *pcmk__pacemakerd_api_methods(void);
 319 
 320 G_GNUC_INTERNAL
 321 pcmk__ipc_methods_t *pcmk__schedulerd_api_methods(void);
 322 
 323 
 324 /*
 325  * Logging
 326  */
 327 
 328 //! XML is newly created
 329 #define PCMK__XML_PREFIX_CREATED "++"
 330 
 331 //! XML has been deleted
 332 #define PCMK__XML_PREFIX_DELETED "--"
 333 
 334 //! XML has been modified
 335 #define PCMK__XML_PREFIX_MODIFIED "+ "
 336 
 337 //! XML has been moved
 338 #define PCMK__XML_PREFIX_MOVED "+~"
 339 
 340 /*
 341  * Output
 342  */
 343 G_GNUC_INTERNAL
 344 int pcmk__bare_output_new(pcmk__output_t **out, const char *fmt_name,
 345                           const char *filename, char **argv);
 346 
 347 G_GNUC_INTERNAL
 348 void pcmk__register_option_messages(pcmk__output_t *out);
 349 
 350 G_GNUC_INTERNAL
 351 void pcmk__register_patchset_messages(pcmk__output_t *out);
 352 
 353 G_GNUC_INTERNAL
 354 bool pcmk__output_text_get_fancy(pcmk__output_t *out);
 355 
 356 /*
 357  * Rules
 358  */
 359 
 360 // How node attribute values may be compared in rules
 361 enum pcmk__comparison {
 362     pcmk__comparison_unknown,
 363     pcmk__comparison_defined,
 364     pcmk__comparison_undefined,
 365     pcmk__comparison_eq,
 366     pcmk__comparison_ne,
 367     pcmk__comparison_lt,
 368     pcmk__comparison_lte,
 369     pcmk__comparison_gt,
 370     pcmk__comparison_gte,
 371 };
 372 
 373 // How node attribute values may be parsed in rules
 374 enum pcmk__type {
 375     pcmk__type_unknown,
 376     pcmk__type_string,
 377     pcmk__type_integer,
 378     pcmk__type_number,
 379     pcmk__type_version,
 380 };
 381 
 382 // Where to obtain reference value for a node attribute comparison
 383 enum pcmk__reference_source {
 384     pcmk__source_unknown,
 385     pcmk__source_literal,
 386     pcmk__source_instance_attrs,
 387     pcmk__source_meta_attrs,
 388 };
 389 
 390 G_GNUC_INTERNAL
 391 enum pcmk__comparison pcmk__parse_comparison(const char *op);
 392 
 393 G_GNUC_INTERNAL
 394 enum pcmk__type pcmk__parse_type(const char *type, enum pcmk__comparison op,
 395                                  const char *value1, const char *value2);
 396 
 397 G_GNUC_INTERNAL
 398 enum pcmk__reference_source pcmk__parse_source(const char *source);
 399 
 400 G_GNUC_INTERNAL
 401 int pcmk__cmp_by_type(const char *value1, const char *value2,
 402                       enum pcmk__type type);
 403 
 404 G_GNUC_INTERNAL
 405 int pcmk__unpack_duration(const xmlNode *duration, const crm_time_t *start,
 406                           crm_time_t **end);
 407 
 408 G_GNUC_INTERNAL
 409 int pcmk__evaluate_date_spec(const xmlNode *date_spec, const crm_time_t *now);
 410 
 411 G_GNUC_INTERNAL
 412 int pcmk__evaluate_attr_expression(const xmlNode *expression,
 413                                    const pcmk_rule_input_t *rule_input);
 414 
 415 G_GNUC_INTERNAL
 416 int pcmk__evaluate_rsc_expression(const xmlNode *expr,
 417                                   const pcmk_rule_input_t *rule_input);
 418 
 419 G_GNUC_INTERNAL
 420 int pcmk__evaluate_op_expression(const xmlNode *expr,
 421                                  const pcmk_rule_input_t *rule_input);
 422 
 423 
 424 /*
 425  * Utils
 426  */
 427 #define PCMK__PW_BUFFER_LEN 500
 428 
 429 
 430 /*
 431  * Schemas
 432  */
 433 typedef struct {
 434     unsigned char v[2];
 435 } pcmk__schema_version_t;
 436 
 437 enum pcmk__schema_validator {
 438     pcmk__schema_validator_none,
 439     pcmk__schema_validator_rng
 440 };
 441 
 442 typedef struct {
 443     int schema_index;
 444     char *name;
 445 
 446     /*!
 447      * List of XSLT stylesheets for upgrading from this schema version to the
 448      * next one. Sorted by the order in which they should be applied to the CIB.
 449      */
 450     GList *transforms;
 451 
 452     void *cache;
 453     enum pcmk__schema_validator validator;
 454     pcmk__schema_version_t version;
 455 } pcmk__schema_t;
 456 
 457 G_GNUC_INTERNAL
 458 GList *pcmk__find_x_0_schema(void);
 459 
 460 #ifdef __cplusplus
 461 }
 462 #endif
 463 
 464 #endif  // PCMK__COMMON_CRMCOMMON_PRIVATE__H

/* */