ipc_internal.h

Go to the documentation of this file.

/*
 * Copyright 2013-2025 the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under the GNU Lesser General Public License
 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
 */
 
#ifndef PCMK__CRM_COMMON_IPC_INTERNAL__H
#define PCMK__CRM_COMMON_IPC_INTERNAL__H
 
#include <stdbool.h>                // bool
#include <stdint.h>                 // uint32_t, uint64_t, UINT64_C()
#include <sys/uio.h>                // struct iovec
#include <sys/types.h>              // uid_t, gid_t, pid_t, size_t
 
#include <gnutls/gnutls.h>        // gnutls_session_t
 
#include <glib.h>                   // guint, gpointer, GQueue, ...
#include <libxml/tree.h>            // xmlNode
#include <qb/qbipcs.h>              // qb_ipcs_connection_t, ...
 
#include <crm_config.h>             // HAVE_GETPEEREID
#include <crm/crm.h>                    // crm_system_name
#include <crm/common/ipc.h>
#include <crm/common/ipc_controld.h>    // pcmk_controld_api_reply
#include <crm/common/ipc_pacemakerd.h>  // pcmk_pacemakerd_{api_reply,state}
#include <crm/common/mainloop.h>    // mainloop_io_t
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* denotes "non yieldable PID" on FreeBSD, or actual PID1 in scenarios that
   require a delicate handling anyway (socket-based activation with systemd);
   we can be reasonably sure that this PID is never possessed by the actual
   child daemon, as it gets taken either by the proper init, or by pacemakerd
   itself (i.e. this precludes anything else); note that value of zero
   is meant to carry "unset" meaning, and better not to bet on/conditionalize
   over signedness of pid_t */
#define PCMK__SPECIAL_PID  1
 
// Timeout (in seconds) to use for IPC client sends, reply waits, etc.
#define PCMK__IPC_TIMEOUT 120
 
#if defined(HAVE_GETPEEREID)
/* on FreeBSD, we don't want to expose "non-yieldable PID" (leading to
   "IPC liveness check only") as its nominal representation, which could
   cause confusion -- this is unambiguous as long as there's no
   socket-based activation like with systemd (very improbable) */
#define PCMK__SPECIAL_PID_AS_0(p)  (((p) == PCMK__SPECIAL_PID) ? 0 : (p))
#else
#define PCMK__SPECIAL_PID_AS_0(p)  (p)
#endif
 
int pcmk__ipc_is_authentic_process_active(const char *name, uid_t refuid,
                                          gid_t refgid, pid_t *gotpid);
 
int pcmk__connect_generic_ipc(crm_ipc_t *ipc);
int pcmk__ipc_fd(crm_ipc_t *ipc, int *fd);
int pcmk__connect_ipc(pcmk_ipc_api_t *api, enum pcmk_ipc_dispatch dispatch_type,
                      int attempts);
int pcmk__connect_ipc_retry_conrefused(pcmk_ipc_api_t *api,
                                       enum pcmk_ipc_dispatch dispatch_type,
                                       int attempts);
/*
 * Server-related
 */
 
typedef struct pcmk__client_s pcmk__client_t;
 
struct pcmk__remote_s {
    /* Shared */
    char *buffer;
    size_t buffer_size;
    size_t buffer_offset;
    int auth_timeout;
    int tcp_socket;
    mainloop_io_t *source;
    time_t uptime;
    char *start_state;
 
    /* CIB-only */
    char *token;
 
    /* TLS only */
 
    // Must be created by pcmk__new_tls_session()
    gnutls_session_t tls_session;
};
 
enum pcmk__client_flags {
    // Lower 32 bits are reserved for server (not library) use
 
    // Next 8 bits are reserved for client type (sort of a cheap enum)
 
    pcmk__client_ipc                    = (UINT64_C(1) << 32),
 
    pcmk__client_tcp                    = (UINT64_C(1) << 33),
 
    pcmk__client_tls                    = (UINT64_C(1) << 34),
 
    // The rest are client attributes
 
    pcmk__client_proxied                = (UINT64_C(1) << 40),
 
    pcmk__client_privileged             = (UINT64_C(1) << 41),
 
    pcmk__client_to_proxy               = (UINT64_C(1) << 42),
 
    pcmk__client_authenticated          = (UINT64_C(1) << 43),
 
    pcmk__client_tls_handshake_complete = (UINT64_C(1) << 44),
};
 
#define PCMK__CLIENT_TYPE(client) ((client)->flags & UINT64_C(0xff00000000))
 
struct pcmk__client_s {
    unsigned int pid;
 
    char *id;
    char *name;
    char *user;
    uint64_t flags; // Group of pcmk__client_flags
 
    int request_id;
    void *userdata;
 
    int event_timer;
    GQueue *event_queue;
 
    /* Buffer used to store a multipart IPC message when we are building it
     * up over multiple reads.
     */
    GByteArray *buffer;
 
    /* Depending on the client type, only some of the following will be
     * populated/valid. @TODO Maybe convert to a union.
     */
 
    qb_ipcs_connection_t *ipcs; /* IPC */
 
    struct pcmk__remote_s *remote;        /* TCP/TLS */
 
    unsigned int queue_backlog; /* IPC queue length after last flush */
    unsigned int queue_max;     /* Evict client whose queue grows this big */
};
 
#define pcmk__set_client_flags(client, flags_to_set) do {               \
        (client)->flags = pcmk__set_flags_as(__func__, __LINE__,        \
            LOG_TRACE,                                                  \
            "Client", pcmk__client_name(client),                        \
            (client)->flags, (flags_to_set), #flags_to_set);            \
    } while (0)
 
#define pcmk__clear_client_flags(client, flags_to_clear) do {           \
        (client)->flags = pcmk__clear_flags_as(__func__, __LINE__,      \
            LOG_TRACE,                                                  \
            "Client", pcmk__client_name(client),                        \
            (client)->flags, (flags_to_clear), #flags_to_clear);        \
    } while (0)
 
#define pcmk__set_ipc_flags(ipc_flags, ipc_name, flags_to_set) do {         \
        ipc_flags = pcmk__set_flags_as(__func__, __LINE__, LOG_TRACE,       \
                                       "IPC", (ipc_name),                   \
                                       (ipc_flags), (flags_to_set),         \
                                       #flags_to_set);                      \
    } while (0)
 
#define pcmk__clear_ipc_flags(ipc_flags, ipc_name, flags_to_clear) do {     \
        ipc_flags = pcmk__clear_flags_as(__func__, __LINE__, LOG_TRACE,     \
                                         "IPC", (ipc_name),                 \
                                         (ipc_flags), (flags_to_clear),     \
                                         #flags_to_clear);                  \
    } while (0)
 
guint pcmk__ipc_client_count(void);
void pcmk__foreach_ipc_client(GHFunc func, gpointer user_data);
 
void pcmk__client_cleanup(void);
 
pcmk__client_t *pcmk__find_client(const qb_ipcs_connection_t *c);
pcmk__client_t *pcmk__find_client_by_id(const char *id);
const char *pcmk__client_name(const pcmk__client_t *c);
const char *pcmk__client_type_str(uint64_t client_type);
 
pcmk__client_t *pcmk__new_unauth_client(void *key);
pcmk__client_t *pcmk__new_client(qb_ipcs_connection_t *c, uid_t uid, gid_t gid);
void pcmk__free_client(pcmk__client_t *c);
void pcmk__drop_all_clients(qb_ipcs_service_t *s);
void pcmk__set_client_queue_max(pcmk__client_t *client, const char *qmax);
 
xmlNode *pcmk__ipc_create_ack_as(const char *function, int line, uint32_t flags,
                                 const char *tag, const char *ver, crm_exit_t status);
#define pcmk__ipc_create_ack(flags, tag, ver, st) \
    pcmk__ipc_create_ack_as(__func__, __LINE__, (flags), (tag), (ver), (st))
 
int pcmk__ipc_send_ack_as(const char *function, int line, pcmk__client_t *c,
                          uint32_t request, uint32_t flags, const char *tag,
                          const char *ver, crm_exit_t status);
#define pcmk__ipc_send_ack(c, req, flags, tag, ver, st) \
    pcmk__ipc_send_ack_as(__func__, __LINE__, (c), (req), (flags), (tag), (ver), (st))
 
int pcmk__ipc_prepare_iov(uint32_t request, const GString *message,
                          uint16_t index, struct iovec **result, ssize_t *bytes);
int pcmk__ipc_send_xml(pcmk__client_t *c, uint32_t request,
                       const xmlNode *message, uint32_t flags);
int pcmk__ipc_send_iov(pcmk__client_t *c, struct iovec *iov, uint32_t flags);
void pcmk__ipc_free_client_buffer(crm_ipc_t *client);
int pcmk__ipc_msg_append(GByteArray **buffer, guint8 *data);
xmlNode *pcmk__client_data2xml(pcmk__client_t *c, uint32_t *id, uint32_t *flags);
 
int pcmk__client_pid(qb_ipcs_connection_t *c);
 
void pcmk__serve_attrd_ipc(qb_ipcs_service_t **ipcs,
                           struct qb_ipcs_service_handlers *cb);
void pcmk__serve_fenced_ipc(qb_ipcs_service_t **ipcs,
                            struct qb_ipcs_service_handlers *cb);
void pcmk__serve_pacemakerd_ipc(qb_ipcs_service_t **ipcs,
                                struct qb_ipcs_service_handlers *cb);
qb_ipcs_service_t *pcmk__serve_schedulerd_ipc(struct qb_ipcs_service_handlers *cb);
qb_ipcs_service_t *pcmk__serve_controld_ipc(struct qb_ipcs_service_handlers *cb);
 
void pcmk__serve_based_ipc(qb_ipcs_service_t **ipcs_ro,
                           qb_ipcs_service_t **ipcs_rw,
                           qb_ipcs_service_t **ipcs_shm,
                           struct qb_ipcs_service_handlers *ro_cb,
                           struct qb_ipcs_service_handlers *rw_cb);
 
void pcmk__stop_based_ipc(qb_ipcs_service_t *ipcs_ro,
        qb_ipcs_service_t *ipcs_rw,
        qb_ipcs_service_t *ipcs_shm);
 
static inline const char *
pcmk__ipc_sys_name(const char *ipc_name, const char *fallback)
{
    return ipc_name ? ipc_name : ((crm_system_name ? crm_system_name : fallback));
}
 
const char *pcmk__pcmkd_state_enum2friendly(enum pcmk_pacemakerd_state state);
 
const char *pcmk__controld_api_reply2str(enum pcmk_controld_api_reply reply);
const char *pcmk__pcmkd_api_reply2str(enum pcmk_pacemakerd_api_reply reply);
 
#ifdef __cplusplus
}
#endif
 
#endif // PCMK__CRM_COMMON_IPC_INTERNAL__H