root/lib/common/crmcommon_private.h

/* */

INCLUDED FROM

DEFINITIONS

1. pcmk__log_xmllib_err

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

/* */