pacemaker  2.1.6-802a72226b
Scalable High-Availability cluster resource manager
Data Structures | Macros | Typedefs | Enumerations | Functions
services.h File Reference

Services API. More...

#include <glib.h>
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <stdbool.h>
#include <sys/types.h>
#include <crm_config.h>
#include <crm/common/agents.h>
#include <crm/common/results.h>
#include <crm/services_compat.h>
Include dependency graph for services.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  svc_action_s
 Object for executing external actions. More...
 

Macros

#define SYSTEMCTL   "/bin/systemctl"
 
#define PCMK_OCF_REASON_PREFIX   "ocf-exit-reason:"
 
#define PCMK_DEFAULT_AGENT_VERSION   "0.1"
 

Typedefs

typedef struct svc_action_private_s svc_action_private_t
 
typedef struct svc_action_s svc_action_t
 Object for executing external actions. More...
 

Enumerations

enum  lsb_exitcode {
  PCMK_LSB_OK = 0, PCMK_LSB_UNKNOWN_ERROR = 1, PCMK_LSB_INVALID_PARAM = 2, PCMK_LSB_UNIMPLEMENT_FEATURE = 3,
  PCMK_LSB_INSUFFICIENT_PRIV = 4, PCMK_LSB_NOT_INSTALLED = 5, PCMK_LSB_NOT_CONFIGURED = 6, PCMK_LSB_NOT_RUNNING = 7
}
 
enum  lsb_status_exitcode {
  PCMK_LSB_STATUS_OK = 0, PCMK_LSB_STATUS_VAR_PID = 1, PCMK_LSB_STATUS_VAR_LOCK = 2, PCMK_LSB_STATUS_NOT_RUNNING = 3,
  PCMK_LSB_STATUS_UNKNOWN = 4, PCMK_LSB_STATUS_NOT_INSTALLED = 150, PCMK_LSB_STATUS_INSUFFICIENT_PRIV = 151
}
 
enum  svc_action_flags { SVC_ACTION_LEAVE_GROUP = 0x01, SVC_ACTION_NON_BLOCKED = 0x02 }
 
enum  nagios_exitcode {
  NAGIOS_STATE_OK = 0, NAGIOS_STATE_WARNING = 1, NAGIOS_STATE_CRITICAL = 2, NAGIOS_STATE_UNKNOWN = 3,
  NAGIOS_INSUFFICIENT_PRIV = 100, NAGIOS_STATE_DEPENDENT = 4, NAGIOS_NOT_INSTALLED = 101
}
 

Functions

GList * get_directory_list (const char *root, gboolean files, gboolean executable)
 Get a list of files or directories in a given path. More...
 
GList * resources_list_providers (const char *standard)
 Get a list of providers. More...
 
GList * resources_list_agents (const char *standard, const char *provider)
 Get a list of resource agents. More...
 
GList * resources_list_standards (void)
 
gboolean resources_agent_exists (const char *standard, const char *provider, const char *agent)
 Check whether a resource agent exists on the local host. More...
 
svc_action_tresources_action_create (const char *name, const char *standard, const char *provider, const char *agent, const char *action, guint interval_ms, int timeout, GHashTable *params, enum svc_action_flags flags)
 Create a new resource action. More...
 
gboolean services_action_kick (const char *name, const char *action, guint interval_ms)
 Reschedule a recurring action for immediate execution. More...
 
const char * resources_find_service_class (const char *agent)
 Find first service class that can provide a specified agent. More...
 
svc_action_tservices_action_create_generic (const char *exec, const char *args[])
 Request execution of an arbitrary command. More...
 
void services_action_cleanup (svc_action_t *op)
 
void services_action_free (svc_action_t *op)
 
int services_action_user (svc_action_t *op, const char *user)
 Set the user and group that an action will execute as. More...
 
gboolean services_action_sync (svc_action_t *op)
 
gboolean services_action_async_fork_notify (svc_action_t *op, void(*action_callback)(svc_action_t *), void(*action_fork_callback)(svc_action_t *))
 Run an action asynchronously, with callback after process is forked. More...
 
gboolean services_action_async (svc_action_t *op, void(*action_callback)(svc_action_t *))
 Request asynchronous execution of an action. More...
 
gboolean services_action_cancel (const char *name, const char *action, guint interval_ms)
 Cancel a recurring action. More...
 
svc_action_tservices_alert_create (const char *id, const char *exec, int timeout, GHashTable *params, int sequence, void *cb_data)
 Create an alert agent action. More...
 
gboolean services_alert_async (svc_action_t *action, void(*cb)(svc_action_t *op))
 Execute an alert agent action. More...
 
enum ocf_exitcode services_result2ocf (const char *standard, const char *action, int exit_status)
 

Detailed Description

Services API.

Definition in file services.h.

Macro Definition Documentation

◆ PCMK_DEFAULT_AGENT_VERSION

#define PCMK_DEFAULT_AGENT_VERSION   "0.1"

Definition at line 47 of file services.h.

◆ PCMK_OCF_REASON_PREFIX

#define PCMK_OCF_REASON_PREFIX   "ocf-exit-reason:"

Definition at line 44 of file services.h.

◆ SYSTEMCTL

#define SYSTEMCTL   "/bin/systemctl"

Definition at line 37 of file services.h.

Typedef Documentation

◆ svc_action_private_t

Definition at line 102 of file services.h.

◆ svc_action_t

typedef struct svc_action_s svc_action_t

Object for executing external actions.

Note
This object should never be instantiated directly, but instead created using one of the constructor functions (resources_action_create() for resource agents, services_alert_create() for alert agents, or services_action_create_generic() for generic executables). Similarly, do not use sizeof() on this struct.

Enumeration Type Documentation

◆ lsb_exitcode

Enumerator
PCMK_LSB_OK 
PCMK_LSB_UNKNOWN_ERROR 
PCMK_LSB_INVALID_PARAM 
PCMK_LSB_UNIMPLEMENT_FEATURE 
PCMK_LSB_INSUFFICIENT_PRIV 
PCMK_LSB_NOT_INSTALLED 
PCMK_LSB_NOT_CONFIGURED 
PCMK_LSB_NOT_RUNNING 

Definition at line 49 of file services.h.

◆ lsb_status_exitcode

Enumerator
PCMK_LSB_STATUS_OK 
PCMK_LSB_STATUS_VAR_PID 
PCMK_LSB_STATUS_VAR_LOCK 
PCMK_LSB_STATUS_NOT_RUNNING 
PCMK_LSB_STATUS_UNKNOWN 
PCMK_LSB_STATUS_NOT_INSTALLED 
PCMK_LSB_STATUS_INSUFFICIENT_PRIV 

Definition at line 61 of file services.h.

◆ nagios_exitcode

Deprecated:
Do not use
Enumerator
NAGIOS_STATE_OK 
NAGIOS_STATE_WARNING 
NAGIOS_STATE_CRITICAL 
NAGIOS_STATE_UNKNOWN 
NAGIOS_INSUFFICIENT_PRIV 
NAGIOS_STATE_DEPENDENT 
NAGIOS_NOT_INSTALLED 

Definition at line 76 of file services.h.

◆ svc_action_flags

Enumerator
SVC_ACTION_LEAVE_GROUP 
SVC_ACTION_NON_BLOCKED 

Definition at line 96 of file services.h.

Function Documentation

◆ get_directory_list()

GList* get_directory_list ( const char *  root,
gboolean  files,
gboolean  executable 
)

Get a list of files or directories in a given path.

Parameters
[in]rootFull path to a directory to read
[in]filesReturn list of files if TRUE or directories if FALSE
[in]executableIf TRUE and files is TRUE, only return executable files
Returns
List of what was found as char * items.
Note
The caller is responsibile for freeing the result with g_list_free_full(list, free).

Definition at line 1055 of file services.c.

◆ resources_action_create()

svc_action_t* resources_action_create ( const char *  name,
const char *  standard,
const char *  provider,
const char *  agent,
const char *  action,
guint  interval_ms,
int  timeout,
GHashTable *  params,
enum svc_action_flags  flags 
)

Create a new resource action.

Parameters
[in]nameName of resource that action is for
[in]standardResource agent standard
[in]providerResource agent provider
[in]agentResource agent name
[in]actionName of action to create
[in]interval_msHow often to repeat action (if 0, execute once)
[in]timeoutError if not complete within this time (ms)
[in,out]paramsAction parameters
[in]flagsGroup of enum svc_action_flags
Returns
Newly allocated action
Note
This function assumes ownership of (and may free) params.
The caller is responsible for freeing the return value using services_action_free().

Definition at line 335 of file services.c.

◆ resources_agent_exists()

gboolean resources_agent_exists ( const char *  standard,
const char *  provider,
const char *  agent 
)

Check whether a resource agent exists on the local host.

Parameters
[in]standardResource agent standard of agent to check
[in]providerProvider of agent to check (or NULL)
[in]agentName of agent to check
Returns
TRUE if agent exists locally, otherwise FALSE

Definition at line 1175 of file services.c.

◆ resources_find_service_class()

const char* resources_find_service_class ( const char *  agent)

Find first service class that can provide a specified agent.

Parameters
[in]agentName of agent to search for
Returns
Service class if found, NULL otherwise
Note
The priority is LSB, then systemd, then upstart. It would be preferable to put systemd first, but LSB merely requires a file existence check, while systemd requires contacting D-Bus.

Definition at line 72 of file services.c.

◆ resources_list_agents()

GList* resources_list_agents ( const char *  standard,
const char *  provider 
)

Get a list of resource agents.

Parameters
[in]standardList agents of this standard (or NULL for all)
[in]providerList agents of this provider (or NULL for all)
Returns
List of resource agents as char * items.
Note
The caller is responsible for freeing the result using g_list_free_full(list, free).

Definition at line 1119 of file services.c.

◆ resources_list_providers()

GList* resources_list_providers ( const char *  standard)

Get a list of providers.

Parameters
[in]standardList providers of this resource agent standard
Returns
List of providers as char * list items (or NULL if standard does not support providers)
Note
The caller is responsible for freeing the result using g_list_free_full(list, free).

Definition at line 1109 of file services.c.

◆ resources_list_standards()

GList* resources_list_standards ( void  )

Get list of available standards

Returns
List of resource standards as char * items.
Note
The caller is responsible for freeing the result using g_list_free_full(list, free).

Definition at line 1061 of file services.c.

◆ services_action_async()

gboolean services_action_async ( svc_action_t op,
void(*)(svc_action_t *)  action_callback 
)

Request asynchronous execution of an action.

Parameters
[in,out]opAction to execute
[in]action_callbackFunction to call when the action completes (if NULL, any previously set callback will continue to be used)
Return values
TRUEif the caller should not free or otherwise use op again, because one of these conditions is true:
  • op is NULL.
  • The action was successfully initiated, in which case action_callback has not been called (it will be called when the action completes).
  • The action's ID matched an existing recurring action. The existing action has taken over the callback and callback data from op and has been re-initiated asynchronously, and op has been freed.
  • Another action for the same resource is in flight, and op will be blocked until it completes.
  • The action could not be initiated, and is either non-recurring or being cancelled. action_callback has been called, and op has been freed.
Return values
FALSEif is still valid, because the action cannot be initiated, and is a recurring action that is not being cancelled. action_callback has been called, and a timer has been set for the next invocation of op.

Definition at line 901 of file services.c.

◆ services_action_async_fork_notify()

gboolean services_action_async_fork_notify ( svc_action_t op,
void(*)(svc_action_t *)  action_callback,
void(*)(svc_action_t *)  action_fork_callback 
)

Run an action asynchronously, with callback after process is forked.

Parameters
[in,out]opAction to run
[in]action_callbackFunction to call when action completes (if NULL, any previously set callback will continue to be used)
[in]action_fork_callbackFunction to call after child process is forked for action (if NULL, any previously set callback will continue to be used)
Return values
TRUEif the caller should not free or otherwise use op again, because one of these conditions is true:
  • op is NULL.
  • The action was successfully initiated, in which case action_fork_callback has been called, but action_callback has not (it will be called when the action completes).
  • The action's ID matched an existing recurring action. The existing action has taken over the callback and callback data from op and has been re-initiated asynchronously, and op has been freed.
  • Another action for the same resource is in flight, and op will be blocked until it completes.
  • The action could not be initiated, and is either non-recurring or being cancelled. action_fork_callback has not been called, but action_callback has, and op has been freed.
Return values
FALSEif is still valid, because the action cannot be initiated, and is a recurring action that is not being cancelled. action_fork_callback has not been called, but action_callback has, and a timer has been set for the next invocation of op.

Definition at line 867 of file services.c.

◆ services_action_cancel()

gboolean services_action_cancel ( const char *  name,
const char *  action,
guint  interval_ms 
)

Cancel a recurring action.

Parameters
[in]nameName of resource that operation is for
[in]actionName of operation to cancel
[in]interval_msInterval of operation to cancel
Returns
TRUE if action was successfully cancelled, FALSE otherwise

Definition at line 664 of file services.c.

◆ services_action_cleanup()

void services_action_cleanup ( svc_action_t op)

Definition at line 501 of file services.c.

◆ services_action_create_generic()

svc_action_t* services_action_create_generic ( const char *  exec,
const char *  args[] 
)

Request execution of an arbitrary command.

This API has useful infrastructure in place to be able to run a command in the background and get notified via a callback when the command finishes.

Parameters
[in]execFull path to command executable
[in]argsNULL-terminated list of arguments to pass to command
Returns
Newly allocated action object

Definition at line 356 of file services.c.

◆ services_action_free()

void services_action_free ( svc_action_t op)

Definition at line 585 of file services.c.

◆ services_action_kick()

gboolean services_action_kick ( const char *  name,
const char *  action,
guint  interval_ms 
)

Reschedule a recurring action for immediate execution.

Parameters
[in]nameName of resource that action is for
[in]actionAction's name
[in]interval_msAction's interval (in milliseconds)
Returns
TRUE on success, otherwise FALSE

Definition at line 732 of file services.c.

◆ services_action_sync()

gboolean services_action_sync ( svc_action_t op)

Definition at line 1020 of file services.c.

◆ services_action_user()

int services_action_user ( svc_action_t op,
const char *  user 
)

Set the user and group that an action will execute as.

Parameters
[in,out]opAction to modify
[in]userName of user to execute action as
[in]groupName of group to execute action as
Returns
pcmk_ok on success, -errno otherwise
Note
This will have no effect unless the process executing the action runs as root, and the action is not a systemd or upstart action. We could implement this for systemd by adding User= and Group= to [Service] in the override file, but that seems more likely to cause problems than be useful.

Definition at line 445 of file services.c.

◆ services_alert_async()

gboolean services_alert_async ( svc_action_t action,
void(*)(svc_action_t *op)  cb 
)

Execute an alert agent action.

Parameters
[in,out]actionAction to execute
[in]cbFunction to call when action completes
Returns
TRUE if the library will free action, FALSE otherwise
Note
If this function returns FALSE, it is the caller's responsibility to free the action with services_action_free(). However, unless someone intentionally creates a recurring alert action, this will never return FALSE.

Definition at line 465 of file services.c.

◆ services_alert_create()

svc_action_t* services_alert_create ( const char *  id,
const char *  exec,
int  timeout,
GHashTable *  params,
int  sequence,
void *  cb_data 
)

Create an alert agent action.

Parameters
[in]idAlert ID
[in]execPath to alert agent executable
[in]timeoutAction timeout
[in]paramsParameters to use with action
[in]sequenceAction sequence number
[in]cb_dataData to pass to callback function
Returns
New action on success, NULL on error
Note
It is the caller's responsibility to free cb_data. The caller should not free params explicitly.

Definition at line 413 of file services.c.

◆ services_result2ocf()

enum ocf_exitcode services_result2ocf ( const char *  standard,
const char *  action,
int  exit_status 
)

Definition at line 550 of file services.c.