1 /* 2 * Copyright 2004-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 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, xmlNode * message, enum crm_ipc_flags flags, 174 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