lib/common/crmcommon

/* */
   1 /*
   2  * Copyright 2018-2023 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 CRMCOMMON_PRIVATE__H
  11 #  define 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 #include <glib.h>           // GList
  21 #include <libxml/tree.h>    // xmlNode, xmlAttr
  22 #include <qb/qbipcc.h>      // struct qb_ipc_response_header
  23 
  24 // Decent chunk size for processing large amounts of data
  25 #define PCMK__BUFFER_SIZE 4096
  26 
  27 #if defined(PCMK__UNIT_TESTING)
  28 #undef G_GNUC_INTERNAL
  29 #define G_GNUC_INTERNAL
  30 #endif
  31 
  32 /* When deleting portions of an XML tree, we keep a record so we can know later
  33  * (e.g. when checking differences) that something was deleted.
  34  */
  35 typedef struct pcmk__deleted_xml_s {
  36         char *path;
  37         int position;
  38 } pcmk__deleted_xml_t;
  39 
  40 typedef struct xml_node_private_s {
  41         long check;
  42         uint32_t flags;
  43 } xml_node_private_t;
  44 
  45 typedef struct xml_doc_private_s {
  46         long check;
  47         uint32_t flags;
  48         char *user;
  49         GList *acls;
  50         GList *deleted_objs; // List of pcmk__deleted_xml_t
  51 } xml_doc_private_t;
  52 
  53 #define pcmk__set_xml_flags(xml_priv, flags_to_set) do {                    \
  54         (xml_priv)->flags = pcmk__set_flags_as(__func__, __LINE__,          \
  55             LOG_NEVER, "XML", "XML node", (xml_priv)->flags,                \
  56             (flags_to_set), #flags_to_set);                                 \
  57     } while (0)
  58 
  59 #define pcmk__clear_xml_flags(xml_priv, flags_to_clear) do {                \
  60         (xml_priv)->flags = pcmk__clear_flags_as(__func__, __LINE__,        \
  61             LOG_NEVER, "XML", "XML node", (xml_priv)->flags,                \
  62             (flags_to_clear), #flags_to_clear);                             \
  63     } while (0)
  64 
  65 G_GNUC_INTERNAL
  66 void pcmk__xml2text(const xmlNode *data, uint32_t options, GString *buffer,
  67                     int depth);
  68 
  69 G_GNUC_INTERNAL
  70 bool pcmk__tracking_xml_changes(xmlNode *xml, bool lazy);
  71 
  72 G_GNUC_INTERNAL
  73 void pcmk__mark_xml_created(xmlNode *xml);
  74 
  75 G_GNUC_INTERNAL
  76 int pcmk__xml_position(const xmlNode *xml,
  77                        enum xml_private_flags ignore_if_set);
  78 
  79 G_GNUC_INTERNAL
  80 xmlNode *pcmk__xml_match(const xmlNode *haystack, const xmlNode *needle,
  81                          bool exact);
  82 
  83 G_GNUC_INTERNAL
  84 void pcmk__xml_update(xmlNode *parent, xmlNode *target, xmlNode *update,
  85                       bool as_diff);
  86 
  87 G_GNUC_INTERNAL
  88 xmlNode *pcmk__xc_match(const xmlNode *root, const xmlNode *search_comment,
  89                         bool exact);
  90 
  91 G_GNUC_INTERNAL
  92 void pcmk__xc_update(xmlNode *parent, xmlNode *target, xmlNode *update);
  93 
  94 G_GNUC_INTERNAL
  95 void pcmk__free_acls(GList *acls);
  96 
  97 G_GNUC_INTERNAL
  98 void pcmk__unpack_acl(xmlNode *source, xmlNode *target, const char *user);
  99 
 100 G_GNUC_INTERNAL
 101 bool pcmk__is_user_in_group(const char *user, const char *group);
 102 
 103 G_GNUC_INTERNAL
 104 void pcmk__apply_acl(xmlNode *xml);
 105 
 106 G_GNUC_INTERNAL
 107 void pcmk__apply_creation_acl(xmlNode *xml, bool check_top);
 108 
 109 G_GNUC_INTERNAL
 110 void pcmk__mark_xml_attr_dirty(xmlAttr *a);
 111 
 112 G_GNUC_INTERNAL
 113 bool pcmk__xa_filterable(const char *name);
 114 
 115 G_GNUC_INTERNAL
 116 void pcmk__log_xmllib_err(void *ctx, const char *fmt, ...)
 117 G_GNUC_PRINTF(2, 3);
 118 
 119 G_GNUC_INTERNAL
 120 void pcmk__mark_xml_node_dirty(xmlNode *xml);
 121 
 122 G_GNUC_INTERNAL
 123 bool pcmk__marked_as_deleted(xmlAttrPtr a, void *user_data);
 124 
 125 G_GNUC_INTERNAL
 126 void pcmk__dump_xml_attr(const xmlAttr *attr, GString *buffer);
 127 
 128 /*
 129  * IPC
 130  */
 131 
 132 #define PCMK__IPC_VERSION 1
 133 
 134 #define PCMK__CONTROLD_API_MAJOR "1"
 135 #define PCMK__CONTROLD_API_MINOR "0"
 136 
 137 // IPC behavior that varies by daemon
 138 typedef struct pcmk__ipc_methods_s {
 139     /*!
 140      * \internal
 141      * \brief Allocate any private data needed by daemon IPC
 142      *
 143      * \param[in,out] api  IPC API connection
 144      *
 145      * \return Standard Pacemaker return code
 146      */
 147     int (*new_data)(pcmk_ipc_api_t *api);
 148 
 149     /*!
 150      * \internal
 151      * \brief Free any private data used by daemon IPC
 152      *
 153      * \param[in,out] api_data  Data allocated by new_data() method
 154      */
 155     void (*free_data)(void *api_data);
 156 
 157     /*!
 158      * \internal
 159      * \brief Perform daemon-specific handling after successful connection
 160      *
 161      * Some daemons require clients to register before sending any other
 162      * commands. The controller requires a CRM_OP_HELLO (with no reply), and
 163      * the CIB manager, executor, and fencer require a CRM_OP_REGISTER (with a
 164      * reply). Ideally this would be consistent across all daemons, but for now
 165      * this allows each to do its own authorization.
 166      *
 167      * \param[in,out] api  IPC API connection
 168      *
 169      * \return Standard Pacemaker return code
 170      */
 171     int (*post_connect)(pcmk_ipc_api_t *api);
 172 
 173     /*!
 174      * \internal
 175      * \brief Check whether an IPC request results in a reply
 176      *
 177      * \param[in,out] api      IPC API connection
 178      * \param[in]     request  IPC request XML
 179      *
 180      * \return true if request would result in an IPC reply, false otherwise
 181      */
 182     bool (*reply_expected)(pcmk_ipc_api_t *api, const xmlNode *request);
 183 
 184     /*!
 185      * \internal
 186      * \brief Perform daemon-specific handling of an IPC message
 187      *
 188      * \param[in,out] api  IPC API connection
 189      * \param[in,out] msg  Message read from IPC connection
 190      *
 191      * \return true if more IPC reply messages should be expected
 192      */
 193     bool (*dispatch)(pcmk_ipc_api_t *api, xmlNode *msg);
 194 
 195     /*!
 196      * \internal
 197      * \brief Perform daemon-specific handling of an IPC disconnect
 198      *
 199      * \param[in,out] api  IPC API connection
 200      */
 201     void (*post_disconnect)(pcmk_ipc_api_t *api);
 202 } pcmk__ipc_methods_t;
 203 
 204 // Implementation of pcmk_ipc_api_t
 205 struct pcmk_ipc_api_s {
 206     enum pcmk_ipc_server server;          // Daemon this IPC API instance is for
 207     enum pcmk_ipc_dispatch dispatch_type; // How replies should be dispatched
 208     size_t ipc_size_max;                  // maximum IPC buffer size
 209     crm_ipc_t *ipc;                       // IPC connection
 210     mainloop_io_t *mainloop_io;     // If using mainloop, I/O source for IPC
 211     bool free_on_disconnect;        // Whether disconnect should free object
 212     pcmk_ipc_callback_t cb;         // Caller-registered callback (if any)
 213     void *user_data;                // Caller-registered data (if any)
 214     void *api_data;                 // For daemon-specific use
 215     pcmk__ipc_methods_t *cmds;      // Behavior that varies by daemon
 216 };
 217 
 218 typedef struct pcmk__ipc_header_s {
 219     struct qb_ipc_response_header qb;
 220     uint32_t size_uncompressed;
 221     uint32_t size_compressed;
 222     uint32_t flags;
 223     uint8_t version;
 224 } pcmk__ipc_header_t;
 225 
 226 G_GNUC_INTERNAL
 227 int pcmk__send_ipc_request(pcmk_ipc_api_t *api, const xmlNode *request);
 228 
 229 G_GNUC_INTERNAL
 230 void pcmk__call_ipc_callback(pcmk_ipc_api_t *api,
 231                              enum pcmk_ipc_event event_type,
 232                              crm_exit_t status, void *event_data);
 233 
 234 G_GNUC_INTERNAL
 235 unsigned int pcmk__ipc_buffer_size(unsigned int max);
 236 
 237 G_GNUC_INTERNAL
 238 bool pcmk__valid_ipc_header(const pcmk__ipc_header_t *header);
 239 
 240 G_GNUC_INTERNAL
 241 pcmk__ipc_methods_t *pcmk__attrd_api_methods(void);
 242 
 243 G_GNUC_INTERNAL
 244 pcmk__ipc_methods_t *pcmk__controld_api_methods(void);
 245 
 246 G_GNUC_INTERNAL
 247 pcmk__ipc_methods_t *pcmk__pacemakerd_api_methods(void);
 248 
 249 G_GNUC_INTERNAL
 250 pcmk__ipc_methods_t *pcmk__schedulerd_api_methods(void);
 251 
 252 
 253 /*
 254  * Logging
 255  */
 256 
 257 //! XML is newly created
 258 #define PCMK__XML_PREFIX_CREATED "++"
 259 
 260 //! XML has been deleted
 261 #define PCMK__XML_PREFIX_DELETED "--"
 262 
 263 //! XML has been modified
 264 #define PCMK__XML_PREFIX_MODIFIED "+ "
 265 
 266 //! XML has been moved
 267 #define PCMK__XML_PREFIX_MOVED "+~"
 268 
 269 /*
 270  * Output
 271  */
 272 G_GNUC_INTERNAL
 273 int pcmk__bare_output_new(pcmk__output_t **out, const char *fmt_name,
 274                           const char *filename, char **argv);
 275 
 276 G_GNUC_INTERNAL
 277 void pcmk__register_patchset_messages(pcmk__output_t *out);
 278 
 279 
 280 /*
 281  * Utils
 282  */
 283 #define PCMK__PW_BUFFER_LEN 500
 284 
 285 
 286 #endif  // CRMCOMMON_PRIVATE__H
/* */
root/lib/common/crmcommon_private.h

INCLUDED FROM
