root/include/crm/common/ipc.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


   1 /*
   2  * Copyright 2004-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 PCMK__CRM_COMMON_IPC__H
  11 #  define PCMK__CRM_COMMON_IPC__H
  12 
  13 
  14 #include <sys/uio.h>
  15 #include <qb/qbipcc.h>
  16 #include <crm/common/xml.h>
  17 
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21 
  22 /**
  23  * \file
  24  * \brief IPC interface to Pacemaker daemons
  25  *
  26  * \ingroup core
  27  */
  28 
  29 /*
  30  * Message creation utilities
  31  *
  32  * These are used for both IPC messages and cluster layer messages. However,
  33  * since this is public API, they stay in this header for backward
  34  * compatibility.
  35  */
  36 
  37 #define create_reply(request, xml_response_data)    \
  38     create_reply_adv(request, xml_response_data, __func__)
  39 
  40 xmlNode *create_reply_adv(const xmlNode *request, xmlNode *xml_response_data,
  41                           const char *origin);
  42 
  43 #define create_request(task, xml_data, host_to, sys_to, sys_from, uuid_from) \
  44     create_request_adv(task, xml_data, host_to, sys_to, sys_from, uuid_from, \
  45                        __func__)
  46 
  47 xmlNode *create_request_adv(const char *task, xmlNode *xml_data,
  48                             const char *host_to, const char *sys_to,
  49                             const char *sys_from, const char *uuid_from,
  50                             const char *origin);
  51 
  52 
  53 /*
  54  * The library supports two methods of creating IPC connections. The older code
  55  * allows connecting to any arbitrary IPC name. The newer code only allows
  56  * connecting to one of the Pacemaker daemons.
  57  *
  58  * As daemons are converted to use the new model, the old functions should be
  59  * considered deprecated for use with those daemons. Once all daemons are
  60  * converted, the old functions should be officially deprecated as public API
  61  * and eventually made internal API.
  62  */
  63 
  64 /*
  65  * Pacemaker daemon IPC
  66  */
  67 
  68 //! Available IPC interfaces
  69 enum pcmk_ipc_server {
  70     pcmk_ipc_attrd,         //!< Attribute manager
  71     pcmk_ipc_based,         //!< CIB manager
  72     pcmk_ipc_controld,      //!< Controller
  73     pcmk_ipc_execd,         //!< Executor
  74     pcmk_ipc_fenced,        //!< Fencer
  75     pcmk_ipc_pacemakerd,    //!< Launcher
  76     pcmk_ipc_schedulerd,    //!< Scheduler
  77 };
  78 
  79 //! Possible event types that an IPC event callback can be called for
  80 enum pcmk_ipc_event {
  81     pcmk_ipc_event_connect,     //!< Result of asynchronous connection attempt
  82     pcmk_ipc_event_disconnect,  //!< Termination of IPC connection
  83     pcmk_ipc_event_reply,       //!< Daemon's reply to client IPC request
  84     pcmk_ipc_event_notify,      //!< Notification from daemon
  85 };
  86 
  87 //! How IPC replies should be dispatched
  88 enum pcmk_ipc_dispatch {
  89     pcmk_ipc_dispatch_main, //!< Attach IPC to GMainLoop for dispatch
  90     pcmk_ipc_dispatch_poll, //!< Caller will poll and dispatch IPC
  91     pcmk_ipc_dispatch_sync, //!< Sending a command will wait for any reply
  92 };
  93 
  94 //! Client connection to Pacemaker IPC
  95 typedef struct pcmk_ipc_api_s pcmk_ipc_api_t;
  96 
  97 /*!
  98  * \brief Callback function type for Pacemaker daemon IPC APIs
  99  *
 100  * \param[in,out] api         IPC API connection
 101  * \param[in]     event_type  The type of event that occurred
 102  * \param[in]     status      Event status
 103  * \param[in,out] event_data  Event-specific data
 104  * \param[in,out] user_data   Caller data provided when callback was registered
 105  *
 106  * \note For connection and disconnection events, event_data may be NULL (for
 107  *       local IPC) or the name of the connected node (for remote IPC, for
 108  *       daemons that support that). For reply and notify events, event_data is
 109  *       defined by the specific daemon API.
 110  */
 111 typedef void (*pcmk_ipc_callback_t)(pcmk_ipc_api_t *api,
 112                                     enum pcmk_ipc_event event_type,
 113                                     crm_exit_t status,
 114                                     void *event_data, void *user_data);
 115 
 116 int pcmk_new_ipc_api(pcmk_ipc_api_t **api, enum pcmk_ipc_server server);
 117 
 118 void pcmk_free_ipc_api(pcmk_ipc_api_t *api);
 119 
 120 int pcmk_connect_ipc(pcmk_ipc_api_t *api, enum pcmk_ipc_dispatch dispatch_type);
 121 
 122 void pcmk_disconnect_ipc(pcmk_ipc_api_t *api);
 123 
 124 int pcmk_poll_ipc(const pcmk_ipc_api_t *api, int timeout_ms);
 125 
 126 void pcmk_dispatch_ipc(pcmk_ipc_api_t *api);
 127 
 128 void pcmk_register_ipc_callback(pcmk_ipc_api_t *api, pcmk_ipc_callback_t cb,
 129                                 void *user_data);
 130 
 131 const char *pcmk_ipc_name(const pcmk_ipc_api_t *api, bool for_log);
 132 
 133 bool pcmk_ipc_is_connected(pcmk_ipc_api_t *api);
 134 
 135 int pcmk_ipc_purge_node(pcmk_ipc_api_t *api, const char *node_name,
 136                         uint32_t nodeid);
 137 
 138 
 139 /*
 140  * Generic IPC API (to eventually be deprecated as public API and made internal)
 141  */
 142 
 143 /* *INDENT-OFF* */
 144 enum crm_ipc_flags
 145 {
 146     crm_ipc_flags_none      = 0x00000000,
 147 
 148     crm_ipc_compressed      = 0x00000001, /* Message has been compressed */
 149 
 150     crm_ipc_proxied         = 0x00000100, /* _ALL_ replies to proxied connections need to be sent as events */
 151     crm_ipc_client_response = 0x00000200, /* A Response is expected in reply */
 152 
 153     // These are options for Pacemaker's internal use only (pcmk__ipc_send_*())
 154     crm_ipc_server_event    = 0x00010000, /* Send an Event instead of a Response */
 155     crm_ipc_server_free     = 0x00020000, /* Free the iovec after sending */
 156     crm_ipc_proxied_relay_response = 0x00040000, /* all replies to proxied connections are sent as events, this flag preserves whether the event should be treated as an actual event, or a response.*/
 157 
 158 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
 159     crm_ipc_server_info     = 0x00100000, //!< \deprecated Unused
 160     crm_ipc_server_error    = 0x00200000, //!< \deprecated Unused
 161 #endif
 162 };
 163 /* *INDENT-ON* */
 164 
 165 typedef struct crm_ipc_s crm_ipc_t;
 166 
 167 crm_ipc_t *crm_ipc_new(const char *name, size_t max_size);
 168 bool crm_ipc_connect(crm_ipc_t * client);
 169 void crm_ipc_close(crm_ipc_t * client);
 170 void crm_ipc_destroy(crm_ipc_t * client);
 171 void pcmk_free_ipc_event(struct iovec *event);
 172 
 173 int crm_ipc_send(crm_ipc_t *client, const xmlNode *message,
 174                  enum crm_ipc_flags flags, int32_t ms_timeout, xmlNode **reply);
 175 
 176 int crm_ipc_get_fd(crm_ipc_t * client);
 177 bool crm_ipc_connected(crm_ipc_t * client);
 178 int crm_ipc_ready(crm_ipc_t * client);
 179 long crm_ipc_read(crm_ipc_t * client);
 180 const char *crm_ipc_buffer(crm_ipc_t * client);
 181 uint32_t crm_ipc_buffer_flags(crm_ipc_t * client);
 182 const char *crm_ipc_name(crm_ipc_t * client);
 183 unsigned int crm_ipc_default_buffer_size(void);
 184 
 185 /*!
 186  * \brief Check the authenticity of the IPC socket peer process (legacy)
 187  *
 188  * If everything goes well, peer's authenticity is verified by the means
 189  * of comparing against provided referential UID and GID (either satisfies),
 190  * and the result of this check can be deduced from the return value.
 191  * As an exception, detected UID of 0 ("root") satisfies arbitrary
 192  * provided referential daemon's credentials.
 193  *
 194  * \param[in]  sock    IPC related, connected Unix socket to check peer of
 195  * \param[in]  refuid  referential UID to check against
 196  * \param[in]  refgid  referential GID to check against
 197  * \param[out] gotpid  to optionally store obtained PID of the peer
 198  *                     (not available on FreeBSD, special value of 1
 199  *                     used instead, and the caller is required to
 200  *                     special case this value respectively)
 201  * \param[out] gotuid  to optionally store obtained UID of the peer
 202  * \param[out] gotgid  to optionally store obtained GID of the peer
 203  *
 204  * \return 0 if IPC related socket's peer is not authentic given the
 205  *         referential credentials (see above), 1 if it is,
 206  *         negative value on error (generally expressing -errno unless
 207  *         it was zero even on nonhappy path, -pcmk_err_generic is
 208  *         returned then; no message is directly emitted)
 209  *
 210  * \note While this function is tolerant on what constitutes authorized
 211  *       IPC daemon process (its effective user matches UID=0 or \p refuid,
 212  *       or at least its group matches \p refgid), either or both (in case
 213  *       of UID=0) mismatches on the expected credentials of such peer
 214  *       process \e shall be investigated at the caller when value of 1
 215  *       gets returned there, since higher-than-expected privileges in
 216  *       respect to the expected/intended credentials possibly violate
 217  *       the least privilege principle and may pose an additional risk
 218  *       (i.e. such accidental inconsistency shall be eventually fixed).
 219  */
 220 int crm_ipc_is_authentic_process(int sock, uid_t refuid, gid_t refgid,
 221                                  pid_t *gotpid, uid_t *gotuid, gid_t *gotgid);
 222 
 223 /* This is controller-specific but is declared in this header for C API
 224  * backward compatibility.
 225  */
 226 xmlNode *create_hello_message(const char *uuid, const char *client_name,
 227                               const char *major_version, const char *minor_version);
 228 
 229 #ifdef __cplusplus
 230 }
 231 #endif
 232 
 233 #endif

/* [previous][next][first][last][top][bottom][index][help] */