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 "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_RESOURCE_CLASS_OCF "ocf"

#define	PCMK_RESOURCE_CLASS_SERVICE "service"

#define	PCMK_RESOURCE_CLASS_LSB "lsb"

#define	PCMK_RESOURCE_CLASS_SYSTEMD "systemd"

#define	PCMK_RESOURCE_CLASS_UPSTART "upstart"

#define	PCMK_RESOURCE_CLASS_NAGIOS "nagios"

#define	PCMK_RESOURCE_CLASS_STONITH "stonith"

#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	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 }

enum	svc_action_flags { SVC_ACTION_LEAVE_GROUP = 0x01, SVC_ACTION_NON_BLOCKED = 0x02 }

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)

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

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

const char *	resources_find_service_class (const char *agent)
	Find first service class that can provide a specified agent. More...

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

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

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

gboolean	services_action_cancel (const char name, const char action, guint interval_ms)
	Cancel a recurring action. More...

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. 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 54 of file services.h.

◆ PCMK_OCF_REASON_PREFIX

#define PCMK_OCF_REASON_PREFIX "ocf-exit-reason:"

Definition at line 51 of file services.h.

◆ PCMK_RESOURCE_CLASS_LSB

#define PCMK_RESOURCE_CLASS_LSB "lsb"

Definition at line 41 of file services.h.

◆ PCMK_RESOURCE_CLASS_NAGIOS

#define PCMK_RESOURCE_CLASS_NAGIOS "nagios"

Definition at line 44 of file services.h.

◆ PCMK_RESOURCE_CLASS_OCF

#define PCMK_RESOURCE_CLASS_OCF "ocf"

Definition at line 39 of file services.h.

◆ PCMK_RESOURCE_CLASS_SERVICE

#define PCMK_RESOURCE_CLASS_SERVICE "service"

Definition at line 40 of file services.h.

◆ PCMK_RESOURCE_CLASS_STONITH

#define PCMK_RESOURCE_CLASS_STONITH "stonith"

Definition at line 45 of file services.h.

◆ PCMK_RESOURCE_CLASS_SYSTEMD

#define PCMK_RESOURCE_CLASS_SYSTEMD "systemd"

Definition at line 42 of file services.h.

◆ PCMK_RESOURCE_CLASS_UPSTART

#define PCMK_RESOURCE_CLASS_UPSTART "upstart"

Definition at line 43 of file services.h.

◆ SYSTEMCTL

#define SYSTEMCTL "/bin/systemctl"

Definition at line 35 of file services.h.

Typedef Documentation

◆ svc_action_private_t

typedef struct svc_action_private_s svc_action_private_t

Definition at line 106 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

enum 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 56 of file services.h.

◆ lsb_status_exitcode

enum 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 70 of file services.h.

◆ nagios_exitcode

enum nagios_exitcode

Enumerator
NAGIOS_STATE_OK
NAGIOS_STATE_WARNING
NAGIOS_STATE_CRITICAL
NAGIOS_STATE_UNKNOWN
NAGIOS_INSUFFICIENT_PRIV
NAGIOS_STATE_DEPENDENT
NAGIOS_NOT_INSTALLED	Deprecated: Unused

Definition at line 82 of file services.h.

◆ svc_action_flags

enum svc_action_flags

Enumerator
SVC_ACTION_LEAVE_GROUP
SVC_ACTION_NON_BLOCKED

Definition at line 100 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]	root	full path to a directory to read
[in]	files	return list of files if TRUE or directories if FALSE
[in]	executable	if TRUE and files is TRUE, only return executable files

Returns: a list of what was found. The list items are char *.

Note: It is the caller's responsibility to free the result with g_list_free_full(list, free).

Definition at line 1048 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]	name	Name of resource
[in]	standard	Resource agent standard (ocf, lsb, etc.)
[in]	provider	Resource agent provider
[in]	agent	Resource agent name
[in]	action	action (start, stop, monitor, etc.)
[in]	interval_ms	How often to repeat this action (if 0, execute once)
[in]	timeout	Consider action failed if it does not complete in this many milliseconds
[in]	params	Action parameters

Returns: newly allocated action instance

Postcondition: After the call, 'params' is owned, and later free'd by the svc_action_t result

Note: 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
	)

Does the given standard, provider, and agent describe a resource that can exist?

Parameters

[in]	standard	Which class of agent does the resource belong to?
[in]	provider	What provides the agent (NULL for most standards)?
[in]	agent	What is the name of the agent?

Returns: A boolean

Definition at line 1168 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] agent Name 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]	standard	list agents using this standard (e.g. ocf, lsb, etc.) (or NULL for all)
[in]	provider	list agents from this provider (or NULL for all)

Returns: a list of resource agents. The list items are char *.

Note: The caller is responsible for freeing the result using g_list_free_full(list, free).

Definition at line 1112 of file services.c.

◆ resources_list_providers()

GList* resources_list_providers ( const char * standard )

Get a list of providers.

Parameters

[in] standard list providers of this standard (e.g. ocf, lsb, etc.)

Returns: a 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 1102 of file services.c.

◆ resources_list_standards()

GList* resources_list_standards ( void )

Get list of available standards

Returns: a list of resource standards. The list items are char *. This list must be destroyed using g_list_free_full(list, free).

Definition at line 1054 of file services.c.

◆ services_action_async()

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

Definition at line 894 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.

Parameters

[in]	op	Action to run
[in]	action_callback	Function to call when the action completes
[in]	action_fork_callback	Function to call after action process forks

Returns: TRUE if execution was successfully initiated, FALSE otherwise (in which case the callback will not be called)

Definition at line 862 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]	name	Name of resource that operation is for
[in]	action	Name of operation to cancel
[in]	interval_ms	Interval of operation to cancel

Returns: TRUE if action was successfully cancelled, FALSE otherwise

Definition at line 659 of file services.c.

◆ services_action_cleanup()

void services_action_cleanup ( svc_action_t * op )

Definition at line 496 of file services.c.

◆ services_action_create_generic()

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

Utilize services API to execute 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]	exec	command to execute
[in]	args	arguments to the command, NULL terminated

Returns: a svc_action_t object, used to pass to the execute function (services_action_sync() or services_action_async()) and is provided to the callback.

Definition at line 356 of file services.c.

◆ services_action_free()

void services_action_free ( svc_action_t * op )

Definition at line 580 of file services.c.

◆ services_action_kick()

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

Kick a recurring action so it is scheduled immediately for re-execution

Definition at line 727 of file services.c.

◆ services_action_sync()

gboolean services_action_sync ( svc_action_t * op )

Definition at line 1013 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]	action	Action to modify
[in]	user	Name of user to execute action as
[in]	group	Name 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 442 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]	action	Action to execute
[in]	cb	Function 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().

Definition at line 460 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]	id	Alert ID
[in]	exec	Path to alert agent executable
[in]	timeout	Action timeout
[in]	params	Parameters to use with action
[in]	sequence	Action sequence number
[in]	cb_data	Data 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 545 of file services.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PCMK_DEFAULT_AGENT_VERSION

◆ PCMK_OCF_REASON_PREFIX

◆ PCMK_RESOURCE_CLASS_LSB

◆ PCMK_RESOURCE_CLASS_NAGIOS

◆ PCMK_RESOURCE_CLASS_OCF

◆ PCMK_RESOURCE_CLASS_SERVICE

◆ PCMK_RESOURCE_CLASS_STONITH

◆ PCMK_RESOURCE_CLASS_SYSTEMD

◆ PCMK_RESOURCE_CLASS_UPSTART

◆ SYSTEMCTL

Typedef Documentation

◆ svc_action_private_t

◆ svc_action_t

Enumeration Type Documentation

◆ lsb_exitcode

◆ lsb_status_exitcode

◆ nagios_exitcode

◆ svc_action_flags

Function Documentation

◆ get_directory_list()

◆ resources_action_create()

◆ resources_agent_exists()

◆ resources_find_service_class()

◆ resources_list_agents()

◆ resources_list_providers()

◆ resources_list_standards()

◆ services_action_async()

◆ services_action_async_fork_notify()

◆ services_action_cancel()

◆ services_action_cleanup()

◆ services_action_create_generic()

◆ services_action_free()

◆ services_action_kick()

◆ services_action_sync()

◆ services_action_user()

◆ services_alert_async()

◆ services_alert_create()

◆ services_result2ocf()