Services API. More...

#include <glib.h>
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <stdbool.h>
#include <sys/types.h>
#include "common/results.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

Macros
#define	OCF_ROOT_DIR "/usr/lib/ocf"

#define	LSB_ROOT_DIR "/etc/init.d"

#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

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	op_status { PCMK_LRM_OP_UNKNOWN = -2, PCMK_LRM_OP_PENDING = -1, PCMK_LRM_OP_DONE, PCMK_LRM_OP_CANCELLED, PCMK_LRM_OP_TIMEOUT, PCMK_LRM_OP_NOTSUPPORTED, PCMK_LRM_OP_ERROR, PCMK_LRM_OP_ERROR_HARD, PCMK_LRM_OP_ERROR_FATAL, PCMK_LRM_OP_NOT_INSTALLED, PCMK_LRM_OP_NOT_CONNECTED, PCMK_LRM_OP_INVALID }

enum	nagios_exitcode { NAGIOS_STATE_OK = 0, NAGIOS_STATE_WARNING = 1, NAGIOS_STATE_CRITICAL = 2, NAGIOS_STATE_UNKNOWN = 3, NAGIOS_STATE_DEPENDENT = 4, NAGIOS_INSUFFICIENT_PRIV = 100, 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 *	services_list (void)

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 *	services_action_create (const char name, const char action, guint interval_ms, int timeout)

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 *))

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

Detailed Description

Services API.

Definition in file services.h.

Macro Definition Documentation

◆ LSB_ROOT_DIR

#define LSB_ROOT_DIR "/etc/init.d"

Definition at line 37 of file services.h.

◆ OCF_ROOT_DIR

#define OCF_ROOT_DIR "/usr/lib/ocf"

Definition at line 33 of file services.h.

◆ PCMK_DEFAULT_AGENT_VERSION

#define PCMK_DEFAULT_AGENT_VERSION "0.1"

Definition at line 61 of file services.h.

◆ PCMK_OCF_REASON_PREFIX

#define PCMK_OCF_REASON_PREFIX "ocf-exit-reason:"

Definition at line 58 of file services.h.

◆ PCMK_RESOURCE_CLASS_LSB

#define PCMK_RESOURCE_CLASS_LSB "lsb"

Definition at line 48 of file services.h.

◆ PCMK_RESOURCE_CLASS_NAGIOS

#define PCMK_RESOURCE_CLASS_NAGIOS "nagios"

Definition at line 51 of file services.h.

◆ PCMK_RESOURCE_CLASS_OCF

#define PCMK_RESOURCE_CLASS_OCF "ocf"

Definition at line 46 of file services.h.

◆ PCMK_RESOURCE_CLASS_SERVICE

#define PCMK_RESOURCE_CLASS_SERVICE "service"

Definition at line 47 of file services.h.

◆ PCMK_RESOURCE_CLASS_STONITH

#define PCMK_RESOURCE_CLASS_STONITH "stonith"

Definition at line 52 of file services.h.

◆ PCMK_RESOURCE_CLASS_SYSTEMD

#define PCMK_RESOURCE_CLASS_SYSTEMD "systemd"

Definition at line 49 of file services.h.

◆ PCMK_RESOURCE_CLASS_UPSTART

#define PCMK_RESOURCE_CLASS_UPSTART "upstart"

Definition at line 50 of file services.h.

◆ SYSTEMCTL

#define SYSTEMCTL "/bin/systemctl"

Definition at line 42 of file services.h.

Typedef Documentation

◆ svc_action_private_t

typedef struct svc_action_private_s svc_action_private_t

Definition at line 121 of file services.h.

◆ svc_action_t

typedef struct svc_action_s svc_action_t

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

◆ nagios_exitcode

enum nagios_exitcode

Enumerator
NAGIOS_STATE_OK
NAGIOS_STATE_WARNING
NAGIOS_STATE_CRITICAL
NAGIOS_STATE_UNKNOWN
NAGIOS_STATE_DEPENDENT
NAGIOS_INSUFFICIENT_PRIV
NAGIOS_NOT_INSTALLED

Definition at line 104 of file services.h.

◆ op_status

enum op_status

Enumerator
PCMK_LRM_OP_UNKNOWN
PCMK_LRM_OP_PENDING
PCMK_LRM_OP_DONE
PCMK_LRM_OP_CANCELLED
PCMK_LRM_OP_TIMEOUT
PCMK_LRM_OP_NOTSUPPORTED
PCMK_LRM_OP_ERROR
PCMK_LRM_OP_ERROR_HARD
PCMK_LRM_OP_ERROR_FATAL
PCMK_LRM_OP_NOT_INSTALLED
PCMK_LRM_OP_NOT_CONNECTED
PCMK_LRM_OP_INVALID

Definition at line 89 of file services.h.

◆ svc_action_flags

enum svc_action_flags

Enumerator
SVC_ACTION_LEAVE_GROUP
SVC_ACTION_NON_BLOCKED

Definition at line 115 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 912 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 165 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 1024 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 69 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 968 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 958 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 918 of file services.c.

◆ services_action_async()

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

Definition at line 772 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	services action data
[in]	action_callback	callback for when the action completes
[in]	action_fork_callback	callback for when action forked successfully

Return values

TRUE	succesfully started execution
FALSE	failed to start execution, no callback will be received

Definition at line 740 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 550 of file services.c.

◆ services_action_cleanup()

void services_action_cleanup ( svc_action_t * op )

Definition at line 433 of file services.c.

◆ services_action_create()

svc_action_t* services_action_create	(	const char *	name,
		const char *	action,
		guint	interval_ms,
		int	timeout
	)

Definition at line 276 of file services_lsb.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 311 of file services.c.

◆ services_action_free()

void services_action_free ( svc_action_t * op )

Definition at line 472 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 617 of file services.c.

◆ services_action_sync()

gboolean services_action_sync ( svc_action_t * op )

Definition at line 877 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 379 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 397 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 349 of file services.c.

◆ services_list()

GList* services_list ( void )

Get a list of services

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

Definition at line 284 of file services_lsb.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LSB_ROOT_DIR

◆ OCF_ROOT_DIR

◆ 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

◆ op_status

◆ 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()

◆ services_action_create_generic()

◆ services_action_free()

◆ services_action_kick()

◆ services_action_sync()

◆ services_action_user()

◆ services_alert_async()

◆ services_alert_create()

◆ services_list()