pacemaker  2.1.1-52dc28db4
Scalable High-Availability cluster resource manager
Functions
ipc_client.c File Reference
#include <crm_internal.h>
#include <stdio.h>
#include <sys/types.h>
#include <errno.h>
#include <bzlib.h>
#include <crm/crm.h>
#include <crm/msg_xml.h>
#include <crm/common/ipc.h>
#include <crm/common/ipc_internal.h>
#include "crmcommon_private.h"
Include dependency graph for ipc_client.c:

Go to the source code of this file.

Functions

int pcmk_new_ipc_api (pcmk_ipc_api_t **api, enum pcmk_ipc_server server)
 Create a new object for using Pacemaker daemon IPC. More...
 
void pcmk__call_ipc_callback (pcmk_ipc_api_t *api, enum pcmk_ipc_event event_type, crm_exit_t status, void *event_data)
 
void pcmk_free_ipc_api (pcmk_ipc_api_t *api)
 Free the contents of an IPC API object. More...
 
const char * pcmk_ipc_name (pcmk_ipc_api_t *api, bool for_log)
 Get the IPC name used with an IPC API connection. More...
 
bool pcmk_ipc_is_connected (pcmk_ipc_api_t *api)
 Check whether an IPC API connection is active. More...
 
int pcmk_poll_ipc (pcmk_ipc_api_t *api, int timeout_ms)
 Check whether an IPC connection has data available (without main loop) More...
 
void pcmk_dispatch_ipc (pcmk_ipc_api_t *api)
 Dispatch available messages on an IPC connection (without main loop) More...
 
int pcmk_connect_ipc (pcmk_ipc_api_t *api, enum pcmk_ipc_dispatch dispatch_type)
 Connect to a Pacemaker daemon via IPC. More...
 
void pcmk_disconnect_ipc (pcmk_ipc_api_t *api)
 Disconnect an IPC API instance. More...
 
void pcmk_register_ipc_callback (pcmk_ipc_api_t *api, pcmk_ipc_callback_t cb, void *user_data)
 Register a callback for IPC API events. More...
 
int pcmk__send_ipc_request (pcmk_ipc_api_t *api, xmlNode *request)
 
int pcmk_ipc_purge_node (pcmk_ipc_api_t *api, const char *node_name, uint32_t nodeid)
 Ask a Pacemaker daemon to purge a node from its peer cache. More...
 
crm_ipc_tcrm_ipc_new (const char *name, size_t max_size)
 Create a new (legacy) object for using Pacemaker daemon IPC. More...
 
bool crm_ipc_connect (crm_ipc_t *client)
 Establish an IPC connection to a Pacemaker component. More...
 
void crm_ipc_close (crm_ipc_t *client)
 
void crm_ipc_destroy (crm_ipc_t *client)
 
int crm_ipc_get_fd (crm_ipc_t *client)
 
bool crm_ipc_connected (crm_ipc_t *client)
 
int crm_ipc_ready (crm_ipc_t *client)
 Check whether an IPC connection is ready to be read. More...
 
long crm_ipc_read (crm_ipc_t *client)
 
const char * crm_ipc_buffer (crm_ipc_t *client)
 
uint32_t crm_ipc_buffer_flags (crm_ipc_t *client)
 
const char * crm_ipc_name (crm_ipc_t *client)
 
int crm_ipc_send (crm_ipc_t *client, xmlNode *message, enum crm_ipc_flags flags, int32_t ms_timeout, xmlNode **reply)
 Send an IPC XML message. More...
 
int pcmk__crm_ipc_is_authentic_process (qb_ipcc_connection_t *qb_ipc, int sock, uid_t refuid, gid_t refgid, pid_t *gotpid, uid_t *gotuid, gid_t *gotgid)
 Check the authenticity of the IPC socket peer process. More...
 
int crm_ipc_is_authentic_process (int sock, uid_t refuid, gid_t refgid, pid_t *gotpid, uid_t *gotuid, gid_t *gotgid)
 Check the authenticity of the IPC socket peer process (legacy) More...
 
int pcmk__ipc_is_authentic_process_active (const char *name, uid_t refuid, gid_t refgid, pid_t *gotpid)
 

Function Documentation

◆ crm_ipc_buffer()

const char* crm_ipc_buffer ( crm_ipc_t client)

Definition at line 1056 of file ipc_client.c.

◆ crm_ipc_buffer_flags()

uint32_t crm_ipc_buffer_flags ( crm_ipc_t client)

Definition at line 1063 of file ipc_client.c.

◆ crm_ipc_close()

void crm_ipc_close ( crm_ipc_t client)

Definition at line 862 of file ipc_client.c.

◆ crm_ipc_connect()

bool crm_ipc_connect ( crm_ipc_t client)

Establish an IPC connection to a Pacemaker component.

Parameters
[in]clientConnection instance obtained from crm_ipc_new()
Returns
TRUE on success, FALSE otherwise (in which case errno will be set; specifically, in case of discovering the remote side is not authentic, its value is set to ECONNABORTED).

Definition at line 792 of file ipc_client.c.

◆ crm_ipc_connected()

bool crm_ipc_connected ( crm_ipc_t client)

Definition at line 915 of file ipc_client.c.

◆ crm_ipc_destroy()

void crm_ipc_destroy ( crm_ipc_t client)

Definition at line 875 of file ipc_client.c.

◆ crm_ipc_get_fd()

int crm_ipc_get_fd ( crm_ipc_t client)

Definition at line 901 of file ipc_client.c.

◆ crm_ipc_is_authentic_process()

int crm_ipc_is_authentic_process ( int  sock,
uid_t  refuid,
gid_t  refgid,
pid_t *  gotpid,
uid_t *  gotuid,
gid_t *  gotgid 
)

Check the authenticity of the IPC socket peer process (legacy)

If everything goes well, peer's authenticity is verified by the means of comparing against provided referential UID and GID (either satisfies), and the result of this check can be deduced from the return value. As an exception, detected UID of 0 ("root") satisfies arbitrary provided referential daemon's credentials.

Parameters
[in]sockIPC related, connected Unix socket to check peer of
[in]refuidreferential UID to check against
[in]refgidreferential GID to check against
[out]gotpidto optionally store obtained PID of the peer (not available on FreeBSD, special value of 1 used instead, and the caller is required to special case this value respectively)
[out]gotuidto optionally store obtained UID of the peer
[out]gotgidto optionally store obtained GID of the peer
Returns
0 if IPC related socket's peer is not authentic given the referential credentials (see above), 1 if it is, negative value on error (generally expressing -errno unless it was zero even on nonhappy path, -pcmk_err_generic is returned then; no message is directly emitted)
Note
While this function is tolerant on what constitutes authorized IPC daemon process (its effective user matches UID=0 or refuid, or at least its group matches refgid), either or both (in case of UID=0) mismatches on the expected credentials of such peer process shall be investigated at the caller when value of 1 gets returned there, since higher-than-expected privileges in respect to the expected/intended credentials possibly violate the least privilege principle and may pose an additional risk (i.e. such accidental inconsistency shall be eventually fixed).

Definition at line 1382 of file ipc_client.c.

◆ crm_ipc_name()

const char* crm_ipc_name ( crm_ipc_t client)

Definition at line 1077 of file ipc_client.c.

◆ crm_ipc_new()

crm_ipc_t* crm_ipc_new ( const char *  name,
size_t  max_size 
)

Create a new (legacy) object for using Pacemaker daemon IPC.

Parameters
[in]nameIPC system name to connect to
[in]max_sizeUse a maximum IPC buffer size of at least this size
Returns
Newly allocated IPC object on success, NULL otherwise
Note
The caller is responsible for freeing the result using crm_ipc_destroy().
This should be considered deprecated for use with daemons supported by pcmk_new_ipc_api().

Definition at line 745 of file ipc_client.c.

◆ crm_ipc_read()

long crm_ipc_read ( crm_ipc_t client)

Definition at line 1011 of file ipc_client.c.

◆ crm_ipc_ready()

int crm_ipc_ready ( crm_ipc_t client)

Check whether an IPC connection is ready to be read.

Parameters
[in]clientConnection to check
Returns
Positive value if ready to be read, 0 if not ready, -errno on error

Definition at line 947 of file ipc_client.c.

◆ crm_ipc_send()

int crm_ipc_send ( crm_ipc_t client,
xmlNode *  message,
enum crm_ipc_flags  flags,
int32_t  ms_timeout,
xmlNode **  reply 
)

Send an IPC XML message.

Parameters
[in]clientConnection to IPC server
[in]messageXML message to send
[in]flagsBitmask of crm_ipc_flags
[in]ms_timeoutGive up if not sent within this much time (5 seconds if 0, or no timeout if negative)
[out]replyReply from server (or NULL if none)
Returns
Negative errno on error, otherwise size of reply received in bytes if reply was needed, otherwise number of bytes sent

Definition at line 1150 of file ipc_client.c.

◆ pcmk__call_ipc_callback()

void pcmk__call_ipc_callback ( pcmk_ipc_api_t api,
enum pcmk_ipc_event  event_type,
crm_exit_t  status,
void *  event_data 
)

Definition at line 144 of file ipc_client.c.

◆ pcmk__crm_ipc_is_authentic_process()

int pcmk__crm_ipc_is_authentic_process ( qb_ipcc_connection_t *  qb_ipc,
int  sock,
uid_t  refuid,
gid_t  refgid,
pid_t *  gotpid,
uid_t *  gotuid,
gid_t *  gotgid 
)

Check the authenticity of the IPC socket peer process.

If everything goes well, peer's authenticity is verified by the means of comparing against provided referential UID and GID (either satisfies), and the result of this check can be deduced from the return value. As an exception, detected UID of 0 ("root") satisfies arbitrary provided referential daemon's credentials.

Parameters
[in]qb_ipclibqb client connection if available
[in]sockIPC related, connected Unix socket to check peer of
[in]refuidreferential UID to check against
[in]refgidreferential GID to check against
[out]gotpidto optionally store obtained PID of the peer (not available on FreeBSD, special value of 1 used instead, and the caller is required to special case this value respectively)
[out]gotuidto optionally store obtained UID of the peer
[out]gotgidto optionally store obtained GID of the peer
Returns
Standard Pacemaker return code ie: 0 if it the connection is authentic pcmk_rc_ipc_unauthorized if the connection is not authentic, standard errors.
Note
While this function is tolerant on what constitutes authorized IPC daemon process (its effective user matches UID=0 or refuid, or at least its group matches refgid), either or both (in case of UID=0) mismatches on the expected credentials of such peer process shall be investigated at the caller when value of 1 gets returned there, since higher-than-expected privileges in respect to the expected/intended credentials possibly violate the least privilege principle and may pose an additional risk (i.e. such accidental inconsistency shall be eventually fixed).

Definition at line 1305 of file ipc_client.c.

◆ pcmk__ipc_is_authentic_process_active()

int pcmk__ipc_is_authentic_process_active ( const char *  name,
uid_t  refuid,
gid_t  refgid,
pid_t *  gotpid 
)

Definition at line 1399 of file ipc_client.c.

◆ pcmk__send_ipc_request()

int pcmk__send_ipc_request ( pcmk_ipc_api_t api,
xmlNode *  request 
)

Definition at line 584 of file ipc_client.c.

◆ pcmk_connect_ipc()

int pcmk_connect_ipc ( pcmk_ipc_api_t api,
enum pcmk_ipc_dispatch  dispatch_type 
)

Connect to a Pacemaker daemon via IPC.

Parameters
[in]apiIPC API instance
[out]dispatch_typeHow IPC replies should be dispatched
Returns
Standard Pacemaker return code

Definition at line 452 of file ipc_client.c.

◆ pcmk_disconnect_ipc()

void pcmk_disconnect_ipc ( pcmk_ipc_api_t api)

Disconnect an IPC API instance.

Parameters
[in]apiIPC API connection
Returns
Standard Pacemaker return code
Note
If the connection is attached to a main loop, this function should be called before quitting the main loop, to ensure that all memory is freed.

Definition at line 511 of file ipc_client.c.

◆ pcmk_dispatch_ipc()

void pcmk_dispatch_ipc ( pcmk_ipc_api_t api)

Dispatch available messages on an IPC connection (without main loop)

Parameters
[in]apiIPC API connection
Returns
Standard Pacemaker return code
Note
Callers of pcmk_connect_ipc() using pcmk_ipc_dispatch_poll should call this function when IPC data is available.

Definition at line 391 of file ipc_client.c.

◆ pcmk_free_ipc_api()

void pcmk_free_ipc_api ( pcmk_ipc_api_t api)

Free the contents of an IPC API object.

Parameters
[in]apiIPC API object to free

Definition at line 200 of file ipc_client.c.

◆ pcmk_ipc_is_connected()

bool pcmk_ipc_is_connected ( pcmk_ipc_api_t api)

Check whether an IPC API connection is active.

Parameters
[in]apiIPC API connection
Returns
true if IPC is connected, false otherwise

Definition at line 281 of file ipc_client.c.

◆ pcmk_ipc_name()

const char* pcmk_ipc_name ( pcmk_ipc_api_t api,
bool  for_log 
)

Get the IPC name used with an IPC API connection.

Parameters
[in]apiIPC API connection
[in]for_logIf true, return human-friendly name instead of IPC name
Returns
IPC API's human-friendly or connection name, or if none is available, "Pacemaker" if for_log is true and NULL if for_log is false

Definition at line 241 of file ipc_client.c.

◆ pcmk_ipc_purge_node()

int pcmk_ipc_purge_node ( pcmk_ipc_api_t api,
const char *  node_name,
uint32_t  nodeid 
)

Ask a Pacemaker daemon to purge a node from its peer cache.

Parameters
[in]apiIPC API connection
[in]node_nameIf not NULL, name of node to purge
[in]nodeidIf not 0, node ID of node to purge
Returns
Standard Pacemaker return code
Note
At least one of node_name or nodeid must be specified.

Definition at line 692 of file ipc_client.c.

◆ pcmk_new_ipc_api()

int pcmk_new_ipc_api ( pcmk_ipc_api_t **  api,
enum pcmk_ipc_server  server 
)

Create a new object for using Pacemaker daemon IPC.

Parameters
[out]apiWhere to store new IPC object
[in]serverWhich Pacemaker daemon the object is for
Returns
Standard Pacemaker result code
Note
The caller is responsible for freeing *api using pcmk_free_ipc_api().
This is intended to supersede crm_ipc_new() but currently only supports the controller & pacemakerd IPC API.

Definition at line 47 of file ipc_client.c.

◆ pcmk_poll_ipc()

int pcmk_poll_ipc ( pcmk_ipc_api_t api,
int  timeout_ms 
)

Check whether an IPC connection has data available (without main loop)

Parameters
[in]apiIPC API connection
[in]timeout_msIf less than 0, poll indefinitely; if 0, poll once and return immediately; otherwise, poll for up to this many milliseconds
Returns
Standard Pacemaker return code
Note
Callers of pcmk_connect_ipc() using pcmk_ipc_dispatch_poll should call this function to check whether IPC data is available. Return values of interest include pcmk_rc_ok meaning data is available, and EAGAIN meaning no data is available; all other values indicate errors.
Todo:
This does not allow the caller to poll multiple file descriptors at once. If there is demand for that, we could add a wrapper for crm_ipc_get_fd(api->ipc), so the caller can call poll() themselves.

Definition at line 361 of file ipc_client.c.

◆ pcmk_register_ipc_callback()

void pcmk_register_ipc_callback ( pcmk_ipc_api_t api,
pcmk_ipc_callback_t  cb,
void *  user_data 
)

Register a callback for IPC API events.

Parameters
[in]apiIPC API connection
[in]callbackCallback to register
[in]userdataCaller data to pass to callback
Note
This function may be called multiple times to update the callback and/or user data. The caller remains responsible for freeing userdata in any case (after the IPC is disconnected, if the user data is still registered with the IPC).

Definition at line 561 of file ipc_client.c.