pacemaker  2.1.4-dc6eb4362
Scalable High-Availability cluster resource manager
Macros | Typedefs | Enumerations | Functions
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 (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 (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 (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_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)
 
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, 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__)

Definition at line 37 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__)
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)
Definition: messages.c:40

Definition at line 43 of file ipc.h.

Typedef Documentation

◆ crm_ipc_t

typedef struct crm_ipc_s crm_ipc_t

Definition at line 163 of file ipc.h.

◆ pcmk_ipc_api_t

Client connection to Pacemaker IPC.

Definition at line 95 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]apiIPC API connection
[in]event_typeThe type of event that occurred
[in]statusEvent status
[in]event_dataEvent-specific data
[in]user_dataCaller 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 111 of file ipc.h.

Enumeration Type Documentation

◆ 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 
crm_ipc_server_error 

Definition at line 144 of file ipc.h.

◆ 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 88 of file ipc.h.

◆ 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 80 of file ipc.h.

◆ 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 69 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:
This function is deprecated as part of the public C API.

Definition at line 596 of file ipc_controld.c.

◆ create_reply_adv()

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

Create a Pacemaker reply (for IPC or cluster layer)

Parameters
[in]original_requestXML of request this is a reply to
[in]xml_response_dataXML to copy as data section of reply
[in]originName 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 102 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)

Parameters
[in]taskWhat to set as the request's task
[in]msg_dataWhat to add as the request's data contents
[in]host_toWhat to set as the request's destination host
[in]sys_toWhat to set as the request's destination system
[in]sys_fromIf not NULL, set as request's origin system
[in]uuid_fromIf not NULL, use in request's origin system
[in]originName 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 1115 of file ipc_client.c.

◆ crm_ipc_buffer_flags()

uint32_t crm_ipc_buffer_flags ( crm_ipc_t client)

Definition at line 1122 of file ipc_client.c.

◆ crm_ipc_close()

void crm_ipc_close ( crm_ipc_t client)

Definition at line 917 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 847 of file ipc_client.c.

◆ crm_ipc_connected()

bool crm_ipc_connected ( crm_ipc_t client)

Definition at line 970 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 62 of file ipc_common.c.

◆ crm_ipc_destroy()

void crm_ipc_destroy ( crm_ipc_t client)

Definition at line 930 of file ipc_client.c.

◆ crm_ipc_get_fd()

int crm_ipc_get_fd ( crm_ipc_t client)

Definition at line 956 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 1441 of file ipc_client.c.

◆ crm_ipc_name()

const char* crm_ipc_name ( crm_ipc_t client)

Definition at line 1136 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 800 of file ipc_client.c.

◆ crm_ipc_read()

long crm_ipc_read ( crm_ipc_t client)

Definition at line 1066 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 1002 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 1209 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 484 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 543 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 423 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 201 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]eventI/O vector to free

Definition at line 280 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]apiIPC API connection
Returns
true if IPC is connected, false otherwise

Definition at line 282 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 242 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 747 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, and schedulerd 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 393 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 593 of file ipc_client.c.