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_t *	crm_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

const char* crm_ipc_buffer

(

crm_ipc_t *

client

)

Definition at line 1056 of file ipc_client.c.

uint32_t crm_ipc_buffer_flags

(

crm_ipc_t *

client

)

Definition at line 1063 of file ipc_client.c.

void crm_ipc_close

(

crm_ipc_t *

client

)

Definition at line 862 of file ipc_client.c.

bool crm_ipc_connect

(

crm_ipc_t *

client

)

Establish an IPC connection to a Pacemaker component.

Parameters

[in]

client

Connection 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.

bool crm_ipc_connected

(

crm_ipc_t *

client

)

Definition at line 915 of file ipc_client.c.

void crm_ipc_destroy

(

crm_ipc_t *

client

)

Definition at line 875 of file ipc_client.c.

int crm_ipc_get_fd

(

crm_ipc_t *

client

)

Definition at line 901 of file ipc_client.c.

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]	sock	IPC related, connected Unix socket to check peer of
[in]	refuid	referential UID to check against
[in]	refgid	referential GID to check against
[out]	gotpid	to 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]	gotuid	to optionally store obtained UID of the peer
[out]	gotgid	to 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.

const char* crm_ipc_name

(

crm_ipc_t *

client

)

Definition at line 1077 of file ipc_client.c.

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]	name	IPC system name to connect to
[in]	max_size	Use 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.

long crm_ipc_read

(

crm_ipc_t *

client

)

Definition at line 1011 of file ipc_client.c.

int crm_ipc_ready

(

crm_ipc_t *

client

)

Check whether an IPC connection is ready to be read.

Parameters

[in]

client

Connection 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.

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]	client	Connection to IPC server
[in]	message	XML message to send
[in]	flags	Bitmask of crm_ipc_flags
[in]	ms_timeout	Give up if not sent within this much time (5 seconds if 0, or no timeout if negative)
[out]	reply	Reply 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.

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.

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_ipc	libqb client connection if available
[in]	sock	IPC related, connected Unix socket to check peer of
[in]	refuid	referential UID to check against
[in]	refgid	referential GID to check against
[out]	gotpid	to 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]	gotuid	to optionally store obtained UID of the peer
[out]	gotgid	to 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.

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.

int pcmk__send_ipc_request	(	pcmk_ipc_api_t *	api,
		xmlNode *	request
	)

Definition at line 584 of file ipc_client.c.

int pcmk_connect_ipc	(	pcmk_ipc_api_t *	api,
		enum pcmk_ipc_dispatch	dispatch_type
	)

Connect to a Pacemaker daemon via IPC.

Parameters

[in]	api	IPC API instance
[out]	dispatch_type	How IPC replies should be dispatched

Returns

Standard Pacemaker return code

Definition at line 452 of file ipc_client.c.

void pcmk_disconnect_ipc

(

pcmk_ipc_api_t *

api

)

Disconnect an IPC API instance.

Parameters

[in]

api

IPC 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.

void pcmk_dispatch_ipc

(

pcmk_ipc_api_t *

api

)

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

Parameters

[in]

api

IPC 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.

void pcmk_free_ipc_api

(

pcmk_ipc_api_t *

api

)

Free the contents of an IPC API object.

Parameters

[in]

api

IPC API object to free

Definition at line 200 of file ipc_client.c.

bool pcmk_ipc_is_connected

(

pcmk_ipc_api_t *

api

)

Check whether an IPC API connection is active.

Parameters

[in]

api

IPC API connection

Returns

true if IPC is connected, false otherwise

Definition at line 281 of file ipc_client.c.

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]	api	IPC API connection
[in]	for_log	If 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.

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]	api	IPC API connection
[in]	node_name	If not NULL, name of node to purge
[in]	nodeid	If 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.

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]	api	Where to store new IPC object
[in]	server	Which 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.

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]	api	IPC API connection
[in]	timeout_ms	If 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.

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]	api	IPC API connection
[in]	callback	Callback to register
[in]	userdata	Caller 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.