ipc.h File Reference

IPC interface to Pacemaker daemons. More...

#include <sys/uio.h>
#include <qb/qbipcc.h>
#include <crm/common/xml.h>

Include dependency graph for ipc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	create_reply(request, xml_response_data)   create_reply_adv(request, xml_response_data, __func__)
#define	create_request(task, xml_data, host_to, sys_to, sys_from, uuid_from)

Typedefs
typedef struct pcmk_ipc_api_s	pcmk_ipc_api_t
	Client connection to Pacemaker IPC. More...
typedef void(*	pcmk_ipc_callback_t) (pcmk_ipc_api_t *api, enum pcmk_ipc_event event_type, crm_exit_t status, void *event_data, void *user_data)
	Callback function type for Pacemaker daemon IPC APIs. More...
typedef struct crm_ipc_s	crm_ipc_t

Enumerations
enum	pcmk_ipc_server {   pcmk_ipc_attrd, pcmk_ipc_based, pcmk_ipc_controld, pcmk_ipc_execd,   pcmk_ipc_fenced, pcmk_ipc_pacemakerd, pcmk_ipc_schedulerd }
	Available IPC interfaces. More...
enum	pcmk_ipc_event { pcmk_ipc_event_connect, pcmk_ipc_event_disconnect, pcmk_ipc_event_reply, pcmk_ipc_event_notify }
	Possible event types that an IPC event callback can be called for. More...
enum	pcmk_ipc_dispatch { pcmk_ipc_dispatch_main, pcmk_ipc_dispatch_poll, pcmk_ipc_dispatch_sync }
	How IPC replies should be dispatched. More...
enum	crm_ipc_flags {   crm_ipc_flags_none = 0x00000000, crm_ipc_compressed = 0x00000001, crm_ipc_proxied = 0x00000100, crm_ipc_client_response = 0x00000200,   crm_ipc_server_event = 0x00010000, crm_ipc_server_free = 0x00020000, crm_ipc_proxied_relay_response = 0x00040000, crm_ipc_server_info = 0x00100000,   crm_ipc_server_error = 0x00200000 }

Functions
xmlNode *	create_reply_adv (const xmlNode *request, xmlNode *xml_response_data, const char *origin)
	Create a Pacemaker reply (for IPC or cluster layer) More...
xmlNode *	create_request_adv (const char *task, xmlNode *xml_data, const char *host_to, const char *sys_to, const char *sys_from, const char *uuid_from, const char *origin)
	Create a Pacemaker request (for IPC or cluster layer) More...
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_free_ipc_api (pcmk_ipc_api_t *api)
	Free the contents of an IPC API object. 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...
int	pcmk_poll_ipc (const 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...
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...
const char *	pcmk_ipc_name (const 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_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)
void	pcmk_free_ipc_event (struct iovec *event)
	Free an I/O vector created by pcmk__ipc_prepare_iov() More...
int	crm_ipc_send (crm_ipc_t *client, const xmlNode *message, enum crm_ipc_flags flags, int32_t ms_timeout, xmlNode **reply)
	Send an IPC XML message. More...
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)
unsigned int	crm_ipc_default_buffer_size (void)
	Return pacemaker's default IPC buffer size. 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...
xmlNode *	create_hello_message (const char *uuid, const char *client_name, const char *major_version, const char *minor_version)
	Create XML for a controller IPC "hello" message. More...

Detailed Description

IPC interface to Pacemaker daemons.

Definition in file ipc.h.

Macro Definition Documentation

create_reply

#define create_reply	(		request,
			xml_response_data
	)		create_reply_adv(request, xml_response_data, __func__)

Deprecated:

Do not use

Definition at line 39 of file ipc.h.

create_request

#define create_request	(		task,
			xml_data,
			host_to,
			sys_to,
			sys_from,
			uuid_from
	)

Value:

create_request_adv(task, xml_data, host_to, sys_to, sys_from, uuid_from, \
                       __func__)

Deprecated:

Do not use

Definition at line 49 of file ipc.h.

Typedef Documentation

crm_ipc_t

typedef struct crm_ipc_s crm_ipc_t

Definition at line 184 of file ipc.h.

pcmk_ipc_api_t

typedef struct pcmk_ipc_api_s pcmk_ipc_api_t

Client connection to Pacemaker IPC.

Definition at line 110 of file ipc.h.

pcmk_ipc_callback_t

typedef void(* pcmk_ipc_callback_t) (pcmk_ipc_api_t *api, enum pcmk_ipc_event event_type, crm_exit_t status, void *event_data, void *user_data)

Callback function type for Pacemaker daemon IPC APIs.

Parameters

[in,out]	api	IPC API connection
[in]	event_type	The type of event that occurred
[in]	status	Event status
[in,out]	event_data	Event-specific data
[in,out]	user_data	Caller data provided when callback was registered

Note

For connection and disconnection events, event_data may be NULL (for local IPC) or the name of the connected node (for remote IPC, for daemons that support that). For reply and notify events, event_data is defined by the specific daemon API.

Definition at line 126 of file ipc.h.

Enumeration Type Documentation

crm_ipc_flags

enum crm_ipc_flags

Enumerator
crm_ipc_flags_none
crm_ipc_compressed
crm_ipc_proxied
crm_ipc_client_response
crm_ipc_server_event
crm_ipc_server_free
crm_ipc_proxied_relay_response
crm_ipc_server_info	Deprecated: Unused
crm_ipc_server_error	Deprecated: Unused

Definition at line 163 of file ipc.h.

pcmk_ipc_dispatch

enum pcmk_ipc_dispatch

How IPC replies should be dispatched.

Enumerator
pcmk_ipc_dispatch_main	Attach IPC to GMainLoop for dispatch.
pcmk_ipc_dispatch_poll	Caller will poll and dispatch IPC.
pcmk_ipc_dispatch_sync	Sending a command will wait for any reply.

Definition at line 102 of file ipc.h.

pcmk_ipc_event

enum pcmk_ipc_event

Possible event types that an IPC event callback can be called for.

Enumerator
pcmk_ipc_event_connect	Result of asynchronous connection attempt.
pcmk_ipc_event_disconnect	Termination of IPC connection.
pcmk_ipc_event_reply	Daemon's reply to client IPC request.
pcmk_ipc_event_notify	Notification from daemon.

Definition at line 89 of file ipc.h.

pcmk_ipc_server

enum pcmk_ipc_server

Available IPC interfaces.

Enumerator
pcmk_ipc_attrd	Attribute manager.
pcmk_ipc_based	CIB manager.
pcmk_ipc_controld	Controller.
pcmk_ipc_execd	Executor.
pcmk_ipc_fenced	Fencer.
pcmk_ipc_pacemakerd	Launcher.
pcmk_ipc_schedulerd	Scheduler.

Definition at line 77 of file ipc.h.

Function Documentation

create_hello_message()

xmlNode* create_hello_message	(	const char *	uuid,
		const char *	client_name,
		const char *	major_version,
		const char *	minor_version
	)

Create XML for a controller IPC "hello" message.

Deprecated:

Do not use

Deprecated:

This function is deprecated as part of the public C API.

Definition at line 627 of file ipc_controld.c.

create_reply_adv()

xmlNode* create_reply_adv	(	const xmlNode *	original_request,
		xmlNode *	xml_response_data,
		const char *	origin
	)

Create a Pacemaker reply (for IPC or cluster layer)

Deprecated:

Do not use

Parameters

[in]	original_request	XML of request this is a reply to
[in]	xml_response_data	XML to copy as data section of reply
[in]	origin	Name of function that called this one

Returns

XML of new reply

Note

This function should not be called directly, but via the create_reply() wrapper.

The caller is responsible for freeing the result using free_xml().

Definition at line 104 of file messages.c.

create_request_adv()

xmlNode* create_request_adv	(	const char *	task,
		xmlNode *	msg_data,
		const char *	host_to,
		const char *	sys_to,
		const char *	sys_from,
		const char *	uuid_from,
		const char *	origin
	)

Create a Pacemaker request (for IPC or cluster layer)

Deprecated:

Do not use

Parameters

[in]	task	What to set as the request's task
[in]	msg_data	What to add as the request's data contents
[in]	host_to	What to set as the request's destination host
[in]	sys_to	What to set as the request's destination system
[in]	sys_from	If not NULL, set as request's origin system
[in]	uuid_from	If not NULL, use in request's origin system
[in]	origin	Name of function that called this one

Returns

XML of new request

Note

One of sys_from or uuid_from must be non-NULL

This function should not be called directly, but via the create_request() wrapper.

The caller is responsible for freeing the result using free_xml().

Definition at line 40 of file messages.c.

crm_ipc_buffer()

const char* crm_ipc_buffer

(

crm_ipc_t *

client

)

Definition at line 1206 of file ipc_client.c.

crm_ipc_buffer_flags()

uint32_t crm_ipc_buffer_flags

(

crm_ipc_t *

client

)

Definition at line 1213 of file ipc_client.c.

crm_ipc_close()

void crm_ipc_close

(

crm_ipc_t *

client

)

Definition at line 993 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,out]

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 968 of file ipc_client.c.

crm_ipc_connected()

bool crm_ipc_connected

(

crm_ipc_t *

client

)

Definition at line 1068 of file ipc_client.c.

crm_ipc_default_buffer_size()

unsigned int crm_ipc_default_buffer_size

(

void

)

Return pacemaker's default IPC buffer size.

Returns

IPC buffer size in bytes

Definition at line 88 of file ipc_common.c.

crm_ipc_destroy()

void crm_ipc_destroy

(

crm_ipc_t *

client

)

Definition at line 1006 of file ipc_client.c.

crm_ipc_get_fd()

int crm_ipc_get_fd

(

crm_ipc_t *

client

)

Definition at line 1054 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]	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 1572 of file ipc_client.c.

crm_ipc_name()

const char* crm_ipc_name

(

crm_ipc_t *

client

)

Definition at line 1227 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]	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 850 of file ipc_client.c.

crm_ipc_read()

long crm_ipc_read

(

crm_ipc_t *

client

)

Definition at line 1158 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,out]

client

Connection to check

Returns

Positive value if ready to be read, 0 if not ready, -errno on error

Definition at line 1100 of file ipc_client.c.

crm_ipc_send()

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

Send an IPC XML message.

Parameters

[in,out]	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 1300 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,out]	api	IPC API instance
[in]	dispatch_type	How IPC replies should be dispatched

Returns

Standard Pacemaker return code

Definition at line 571 of file ipc_client.c.

pcmk_disconnect_ipc()

void pcmk_disconnect_ipc

(

pcmk_ipc_api_t *

api

)

Disconnect an IPC API instance.

Parameters

[in,out]

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 594 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,out]

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 439 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,out]

api

IPC API object to free

Definition at line 206 of file ipc_client.c.

pcmk_free_ipc_event()

void pcmk_free_ipc_event

(

struct iovec *

event

)

Free an I/O vector created by pcmk__ipc_prepare_iov()

Parameters

[in,out]

event

I/O vector to free

Definition at line 259 of file ipc_server.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,out]

api

IPC API connection

Returns

true if IPC is connected, false otherwise

Definition at line 287 of file ipc_client.c.

pcmk_ipc_name()

const char* pcmk_ipc_name	(	const 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 247 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,out]	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 797 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]	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, and schedulerd IPC API.

Definition at line 51 of file ipc_client.c.

pcmk_poll_ipc()

int pcmk_poll_ipc	(	const 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 pcmk__ipc_fd(api->ipc), so the caller can call poll() themselves.

Definition at line 399 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,out]	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 645 of file ipc_client.c.