diff --git a/doc/Makefile.am b/doc/Makefile.am
index a40ddfe628..448d03b867 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,171 +1,172 @@
#
# Copyright 2003-2023 the Pacemaker project contributors
#
# The version control history for this file may have further details.
#
# This source code is licensed under the GNU General Public License version 2
# or later (GPLv2+) WITHOUT ANY WARRANTY.
#
include $(top_srcdir)/mk/common.mk
# Define release-related variables
include $(top_srcdir)/mk/release.mk
# What formats to use for book uploads (i.e. "make www";
# use BOOK_FORMATS in sphinx subdirectory to change local builds)
BOOK_FORMATS ?= html \
singlehtml \
pdf \
epub
# SNMP MIB
mibdir = $(datadir)/snmp/mibs
dist_mib_DATA = PCMK-MIB.txt
# Deprecated plaintext documents (dynamically converted to HTML)
DEPRECATED_ORIGINAL = crm_fencing.txt
DEPRECATED_GENERATED =
if BUILD_ASCIIDOC
DEPRECATED_GENERATED += $(DEPRECATED_ORIGINAL:%.txt=%.html)
endif
DEPRECATED_ALL = $(DEPRECATED_ORIGINAL) \
$(DEPRECATED_GENERATED)
doc_DATA = $(DEPRECATED_ALL)
noinst_SCRIPTS = abi-check
SUBDIRS = sphinx
EXTRA_DIST = $(DEPRECATED_ORIGINAL)
# toplevel rsync destination for www targets (without trailing slash)
-RSYNC_DEST ?= root@www.clusterlabs.org:/var/www/html
+RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html
-# recursive, preserve symlinks/permissions/times, verbose, compress,
+# recursive, preserve symlinks, preserve permissions, verbose, compress,
# don't cross filesystems, sparse, show progress
-RSYNC_OPTS = -rlptvzxS --progress
+RSYNC_OPTS = -rlpvzxS --progress
if IS_ASCIIDOC
ASCIIDOC_HTML_ARGS = --unsafe --backend=xhtml11
ASCIIDOC_DBOOK_ARGS = -b docbook -d book
else
ASCIIDOC_HTML_ARGS = --backend=html5
ASCIIDOC_DBOOK_ARGS = -b docbook45 -d book
endif
%.html: %.txt
$(AM_V_GEN)$(ASCIIDOC_CONV) $(ASCIIDOC_HTML_ARGS) --out-file=$@ $< $(PCMK_quiet)
# For Makefile debugging
.PHONY: vars
vars:
@echo DEPRECATED_ORIGINAL=\'$(DEPRECATED_ORIGINAL)\'
@echo DEPRECATED_GENERATED=\'$(DEPRECATED_GENERATED)\'
@echo LAST_RELEASE=\'$(LAST_RELEASE)\'
@echo TAG=\'$(TAG)\'
.PHONY: deprecated-upload
deprecated-upload: $(DEPRECATED_ALL)
rsync $(RSYNC_OPTS) $(DEPRECATED_ALL) "$(RSYNC_DEST)/$(PACKAGE)/doc/"
.PHONY: deprecated-clean
deprecated-clean:
-rm -f $(DEPRECATED_GENERATED)
# Annotated source code as HTML
# Cleaning first ensures we don't index unrelated stuff like RPM sources
.PHONY: global
global:
$(MAKE) $(AM_MAKEFLAGS) -C .. clean-generic
$(MAKE) $(AM_MAKEFLAGS) -C ../rpm rpm-clean
cd .. && gtags -q && htags -sanhIT doc
.PHONY: global-upload
global-upload: global
rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_DEST)/$(PACKAGE)/global/$(TAG)/"
.PHONY: global-clean
global-clean:
-rm -rf HTML
# Man pages as HTML
%.8.html: %.8
groff -mandoc `man -w ./$<` -T html > $@
%.7.html: %.7
groff -mandoc `man -w ./$<` -T html > $@
.PHONY: manhtml
manhtml:
$(MAKE) $(AM_MAKEFLAGS) -C .. all
- find .. -name "[a-z]*.[78]" -exec $(MAKE) $(AM_MAKEFLAGS) \{\}.html \;
+ find ../agents ../daemons ../tools -name "[a-z]*.[78]" \
+ -exec $(MAKE) $(AM_MAKEFLAGS) \{\}.html \;
.PHONY: manhtml-upload
manhtml-upload: manhtml
find .. -name "[a-z]*.[78].html" -exec \
rsync $(RSYNC_OPTS) \{\} "$(RSYNC_DEST)/$(PACKAGE)/man/" \;
.PHONY: manhtml-clean
manhtml-clean:
-find .. -name "[a-z]*.[78].html" -exec rm \{\} \;
# API documentation as HTML
.PHONY: doxygen
doxygen: Doxyfile
doxygen Doxyfile
.PHONY: doxygen-upload
doxygen-upload: doxygen
rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_DEST)/$(PACKAGE)/doxygen/$(TAG)/"
.PHONY: doxygen-clean
doxygen-clean:
-rm -rf api
# ABI compatibility report as HTML
.PHONY: abi
abi: abi-check
./abi-check $(PACKAGE) $(LAST_RELEASE) $(TAG)
.PHONY: abi-www
abi-www:
export RSYNC_DEST=$(RSYNC_DEST); ./abi-check -u $(PACKAGE) $(LAST_RELEASE) $(TAG)
.PHONY: abi-clean
abi-clean:
-rm -rf abi_dumps compat_reports
# The main documentation books (which are actually in the sphinx subdirectory)
.PHONY: books-upload
books-upload:
$(MAKE) $(AM_MAKEFLAGS) -C sphinx clean
$(MAKE) $(AM_MAKEFLAGS) -C sphinx \
RSYNC_DEST="$(RSYNC_DEST)" \
BOOK_FORMATS="$(BOOK_FORMATS)" \
books-upload
# All online documentation (except ABI compatibility, which is run separately)
.PHONY: www
www: clean-local deprecated-upload manhtml-upload global-upload doxygen-upload books-upload
.PHONY: clean-local
clean-local: global-clean manhtml-clean doxygen-clean abi-clean deprecated-clean
# "make check" will cause "make all" to be run, which means docs will get built
# as a part of running tests if they haven't already. That seems unnecessary, so
# override the default check-recursive rule with this one that just returns. If
# we ever need to add tests to this directory, this rule will have to come out.
.PHONY: check-recursive
check-recursive:
@true
diff --git a/doc/sphinx/Pacemaker_Administration/agents.rst b/doc/sphinx/Pacemaker_Administration/agents.rst
index 34bea60f85..f6df901cdf 100644
--- a/doc/sphinx/Pacemaker_Administration/agents.rst
+++ b/doc/sphinx/Pacemaker_Administration/agents.rst
@@ -1,1182 +1,1182 @@
.. index::
single: resource agent
Resource Agents
---------------
Action Completion
#################
If one resource depends on another resource via constraints, the cluster will
interpret an expected result as sufficient to continue with dependent actions.
This may cause timing issues if the resource agent start returns before the
service is not only launched but fully ready to perform its function, or if the
resource agent stop returns before the service has fully released all its
claims on system resources. At a minimum, the start or stop should not return
before a status command would return the expected (started or stopped) result.
.. index::
single: OCF resource agent
single: resource agent; OCF
OCF Resource Agents
###################
.. index::
single: OCF resource agent; location
Location of Custom Scripts
__________________________
OCF Resource Agents are found in ``/usr/lib/ocf/resource.d/$PROVIDER``
When creating your own agents, you are encouraged to create a new directory
under ``/usr/lib/ocf/resource.d/`` so that they are not confused with (or
overwritten by) the agents shipped by existing providers.
So, for example, if you choose the provider name of big-corp and want a new
resource named big-app, you would create a resource agent called
``/usr/lib/ocf/resource.d/big-corp/big-app`` and define a resource:
.. code-block: xml
.. index::
single: OCF resource agent; action
Actions
_______
All OCF resource agents are required to implement the following actions.
.. list-table:: **Required Actions for OCF Agents**
:class: longtable
:widths: 1 4 3
:header-rows: 1
* - Action
- Description
- Instructions
* - .. _start_action:
.. index::
single: OCF resource agent; start
single: start action
start
- Start the resource
- Return :ref:`OCF_SUCCESS ` on success and an appropriate
error code otherwise. Must not report success until the resource is fully
active.
* - .. _stop_action:
.. index::
single: OCF resource agent; stop
single: stop action
stop
- Stop the resource
- Return :ref:`OCF_SUCCESS ` on success and an appropriate
error code otherwise. Must not report success until the resource is fully
stopped.
* - .. _monitor_action:
.. index::
single: OCF resource agent; monitor
single: monitor action
monitor
- Check the resource's state
- Return :ref:`OCF_SUCCESS ` if the resource is running,
:ref:`OCF_NOT_RUNNING ` if it is stopped, and any other
:ref:`OCF exit code ` if it is failed. **Note:** The
monitor action should test the state of the resource on the local machine
only.
* - .. _meta_data_action:
.. index::
single: OCF resource agent; meta-data
single: meta-data action
meta-data
- Describe the resource
- Provide information about this resource in the XML format defined by the
OCF standard. Return :ref:`OCF_SUCCESS `. **Note:** This is
*not* required to be performed as root.
OCF resource agents may optionally implement additional actions. Some are used
only with advanced resource types such as clones.
.. list-table:: **Optional Actions for OCF Resource Agents**
:class: longtable:
:widths: 1 4 3
:header-rows: 1
* - Action
- Description
- Instructions
* - .. _validate_all_action:
.. index::
single: OCF resource agent; validate-all
single: validate-all action
validate-all
- Validate the instance parameters provided.
- Return :ref:`OCF_SUCCESS ` if parameters are valid,
:ref:`OCF_ERR_ARGS ` if not valid, and
:ref:`OCF_ERR_CONFIGURED ` if resource is not
configured.
* - .. _promote_action:
.. index::
single: OCF resource agent; promote
single: promote action
promote
- Bring the local instance of a promotable clone resource to the promoted
role.
- Return :ref:`OCF_SUCCESS ` on success.
* - .. _demote_action:
.. index::
single: OCF resource agent; demote
single: demote action
demote
- Bring the local instance of a promotable clone resource to the unpromoted
role.
- Return :ref:`OCF_SUCCESS ` on success.
* - .. _notify_action:
.. index::
single: OCF resource agent; notify
single: notify action
notify
- Used by the cluster to send the agent pre- and post-notification events
telling the resource what has happened and what will happen.
- Must not fail. Must return :ref:`OCF_SUCCESS `.
* - .. _reload_action:
.. index::
single: OCF resource agent; reload
single: reload action
reload
- Reload the service's own configuration.
- Not used by Pacemaker.
* - .. _reload_agent_action:
.. index::
single: OCF resource agent; reload-agent
single: reload-agent action
reload-agent
- Make effective any changes in instance parameters marked as reloadable in
the agent's meta-data.
- This is used when the agent can handle a change in some of its parameters
more efficiently than stopping and starting the resource.
* - .. _recover_action:
.. index::
single: OCF resource agent; recover
single: recover action
recover
- Restart the service.
- Not used by Pacemaker.
.. important::
If you create a new OCF resource agent, use `ocf-tester` to verify that the
agent complies with the OCF standard properly.
.. index::
single: OCF resource agent; return code
How Are OCF Return Codes Interpreted?
_____________________________________
The first thing the cluster does is to check the return code against the
expected result. If the result does not match the expected value, then the
operation is considered to have failed, and recovery action is initiated.
There are three types of failure recovery:
.. list-table:: **Types of Recovery Performed by the Cluster**
:class: longtable
:widths: 1 5 5
:header-rows: 1
* - Type
- Description
- Action Taken by the Cluster
* - .. _soft_error:
.. index::
single: OCF resource agent; soft error
soft
- A transient error
- Restart the resource or move it to a new location
* - .. _hard_error:
.. index::
single: OCF resource agent; hard error
hard
- A non-transient error that may be specific to the current node
- Move the resource elsewhere and prevent it from being retried on the
current node
* - .. _fatal_error:
.. index::
single: OCF resource agent; fatal error
fatal
- A non-transient error that will be common to all cluster nodes (for
example, a bad configuration was specified)
- Stop the resource and prevent it from being started on any cluster node
.. _ocf_return_codes:
OCF Return Codes
________________
The following table outlines the various OCF return codes and the type of
recovery the cluster will initiate when a failure code is received. Although
counterintuitive, even actions that return ``OCF_SUCCESS`` can be considered to
have failed, if ``OCF_SUCCESS`` was not the expected return value.
.. list-table:: **OCF Exit Codes and Their Recovery Types**
:class: longtable
:widths: 1 3 6 2
:header-rows: 1
* - Exit Code
- OCF Alias
- Description
- Recovery
* - .. _OCF_SUCCESS:
.. index::
single: OCF_SUCCESS
single: OCF return code; OCF_SUCCESS
pair: OCF return code; 0
0
- OCF_SUCCESS
- Success. The command completed successfully. This is the expected result
for all start, stop, promote, and demote actions.
- :ref:`soft `
* - .. _OCF_ERR_GENERIC:
.. index::
single: OCF_ERR_GENERIC
single: OCF return code; OCF_ERR_GENERIC
pair: OCF return code; 1
1
- OCF_ERR_GENERIC
- Generic "there was a problem" error code.
- :ref:`hard `
* - .. _OCF_ERR_ARGS:
.. index::
single: OCF_ERR_ARGS
single: OCF return code; OCF_ERR_ARGS
pair: OCF return code; 2
2
- OCF_ERR_ARGS
- The resource's parameter values are not valid on this machine (for
example, a value refers to a file not found on the local host).
- :ref:`hard `
* - .. _OCF_ERR_UNIMPLEMENTED:
.. index::
single: OCF_ERR_UNIMPLEMENTED
single: OCF return code; OCF_ERR_UNIMPLEMENTED
pair: OCF return code; 3
3
- OCF_ERR_UNIMPLEMENTED
- The requested action is not implemented.
- :ref:`hard `
* - .. _OCF_ERR_PERM:
.. index::
single: OCF_ERR_PERM
single: OCF return code; OCF_ERR_PERM
pair: OCF return code; 4
4
- OCF_ERR_PERM
- The resource agent does not have sufficient privileges to complete the
task.
- :ref:`hard `
* - .. _OCF_ERR_INSTALLED:
.. index::
single: OCF_ERR_INSTALLED
single: OCF return code; OCF_ERR_INSTALLED
pair: OCF return code; 5
5
- OCF_ERR_INSTALLED
- The tools required by the resource are not installed on this machine.
- :ref:`hard `
* - .. _OCF_ERR_CONFIGURED:
.. index::
single: OCF_ERR_CONFIGURED
single: OCF return code; OCF_ERR_CONFIGURED
pair: OCF return code; 6
6
- OCF_ERR_CONFIGURED
- The resource's parameter values are inherently invalid (for example, a
required parameter was not given).
- :ref:`fatal `
* - .. _OCF_NOT_RUNNING:
.. index::
single: OCF_NOT_RUNNING
single: OCF return code; OCF_NOT_RUNNING
pair: OCF return code; 7
7
- OCF_NOT_RUNNING
- The resource is safely stopped. This should only be returned by monitor
actions, not stop actions.
- N/A
* - .. _OCF_RUNNING_PROMOTED:
.. index::
single: OCF_RUNNING_PROMOTED
single: OCF return code; OCF_RUNNING_PROMOTED
pair: OCF return code; 8
8
- OCF_RUNNING_PROMOTED
- The resource is running in the promoted role.
- :ref:`soft `
* - .. _OCF_FAILED_PROMOTED:
.. index::
single: OCF_FAILED_PROMOTED
single: OCF return code; OCF_FAILED_PROMOTED
pair: OCF return code; 9
9
- OCF_FAILED_PROMOTED
- The resource is (or might be) in the promoted role but has failed. The
resource will be demoted, stopped, and then started (and possibly
promoted) again.
- :ref:`soft `
* - .. _OCF_DEGRADED:
.. index::
single: OCF_DEGRADED
single: OCF return code; OCF_DEGRADED
pair: OCF return code; 190
190
- OCF_DEGRADED
- The resource is properly active, but in such a condition that future
failures are more likely.
- none
* - .. _OCF_DEGRADED_PROMOTED:
.. index::
single: OCF_DEGRADED_PROMOTED
single: OCF return code; OCF_DEGRADED_PROMOTED
pair: OCF return code; 191
191
- OCF_DEGRADED_PROMOTED
- The resource is properly active in the promoted role, but in such a
condition that future failures are more likely.
- none
* - other
- *none*
- Custom error code.
- soft
Exceptions to the recovery handling described above:
* Probes (non-recurring monitor actions) that find a resource active
(or in the promoted role) will not result in recovery action unless it is
also found active elsewhere.
* The recovery action taken when a resource is found active more than
once is determined by the resource's ``multiple-active`` property.
* Recurring actions that return ``OCF_ERR_UNIMPLEMENTED``
do not cause any type of recovery.
* Actions that return one of the "degraded" codes will be treated the same as
if they had returned success, but status output will indicate that the
resource is degraded.
.. _ocf_env_vars:
Environment Variables
_____________________
Pacemaker sets certain environment variables when it executes an OCF resource
agent. Agents can check these variables to get information about resource
parameters or the execution environment.
**Note:** Pacemaker may set other environment variables for its own purposes.
They may be present in the agent's environment, but Pacemaker is not providing
them for the agent's use, and so the agent should not rely on any variables not
listed in the table below.
.. list-table:: **OCF Environment Variables**
:class: longtable
:widths: 1 6
:header-rows: 1
* - Environment Variable
- Description
* - .. _OCF_CHECK_LEVEL:
.. index::
single: OCF_CHECK_LEVEL
single: environment variable; OCF_CHECK_LEVEL
OCF_CHECK_LEVEL
- Requested intensity level of checks in ``monitor`` and ``validate-all``
actions. Usually set as an operation attribute; see Pacemaker Explained
for an example.
* - .. _OCF_EXIT_REASON_PREFIX:
.. index::
single: OCF_EXIT_REASON_PREFIX
single: environment variable; OCF_EXIT_REASON_PREFIX
OCF_EXIT_REASON_PREFIX
- Prefix for printing fatal error messages from the resource agent.
* - .. _OCF_RA_VERSION_MAJOR:
.. index::
single: OCF_RA_VERSION_MAJOR
single: environment variable; OCF_RA_VERSION_MAJOR
OCF_RA_VERSION_MAJOR
- Major version number of the OCF Resource Agent API. If the script does
not support this revision, it should report an error.
See the `OCF specification `_ for an
explanation of the versioning scheme used. The version number is split
into two numbers for ease of use in shell scripts. These two may be used
by the agent to determine whether it is run under an OCF-compliant
resource manager.
* - .. _OCF_RA_VERSION_MINOR:
.. index::
single: OCF_RA_VERSION_MINOR
single: environment variable; OCF_RA_VERSION_MINOR
OCF_RA_VERSION_MINOR
- Minor version number of the OCF Resource Agent API. See
:ref:`OCF_RA_VERSION_MAJOR ` for more details.
* - .. _OCF_RESKEY_crm_feature_set:
.. index::
single: OCF_RESKEY_crm_feature_set
single: environment variable; OCF_RESKEY_crm_feature_set
OCF_RESKEY_crm_feature_set
- ``crm_feature_set`` on the DC (or on the local node, if the agent is run
by ``crm_resource``).
* - .. _OCF_RESKEY_CRM_meta_interval:
.. index::
single: OCF_RESKEY_CRM_meta_interval
single: environment variable; OCF_RESKEY_CRM_meta_interval
OCF_RESKEY_CRM_meta_interval
- Interval (in milliseconds) of the current operation.
* - .. _OCF_RESKEY_CRM_meta_name:
.. index::
single: OCF_RESKEY_CRM_meta_name
single: environment variable; OCF_RESKEY_CRM_meta_name
OCF_RESKEY_CRM_meta_name
- Name of the current operation.
* - .. _OCF_RESKEY_CRM_meta_notify:
.. index::
single: OCF_RESKEY_CRM_meta_notify_*
single: environment variable; OCF_RESKEY_CRM_meta_notify_*
OCF_RESKEY_CRM_meta_notify_*
- See :ref:`Clone Notifications `.
* - .. _OCF_RESKEY_CRM_meta_on_node:
.. index::
single: OCF_RESKEY_CRM_meta_on_node
single: environment variable; OCF_RESKEY_CRM_meta_on_node
OCF_RESKEY_CRM_meta_on_node
- Name of the node where the current operation is running.
* - .. _OCF_RESKEY_CRM_meta_on_node_uuid:
.. index::
single: OCF_RESKEY_CRM_meta_on_node_uuid
single: environment variable; OCF_RESKEY_CRM_meta_on_node_uuid
OCF_RESKEY_CRM_meta_on_node_uuid
- Cluster-layer ID of the node where the current operation is running (or
node name for Pacemaker Remote nodes).
* - .. _OCF_RESKEY_CRM_meta_physical_host:
.. index::
single: OCF_RESKEY_CRM_meta_physical_host
single: environment variable; OCF_RESKEY_CRM_meta_physical_host
OCF_RESKEY_CRM_meta_physical_host
- If the node where the current operation is running is a guest node, the
host on which the container is running.
* - .. _OCF_RESKEY_CRM_meta_timeout:
.. index::
single: OCF_RESKEY_CRM_meta_timeout
single: environment variable; OCF_RESKEY_CRM_meta_timeout
OCF_RESKEY_CRM_meta_timeout
- Timeout (in milliseconds) of the current operation.
* - .. _OCF_RESKEY_CRM_meta:
.. index::
single: OCF_RESKEY_CRM_meta_*
single: environment variable; OCF_RESKEY_CRM_meta_*
OCF_RESKEY_CRM_meta_*
- Each of a resource's meta-attributes is converted to an environment
variable prefixed with "OCF_RESKEY_CRM_meta\_". See Pacemaker Explained
for some meta-attributes that have special meaning to Pacemaker.
* - .. _OCF_RESKEY:
.. index::
single: OCF_RESKEY_*
single: environment variable; OCF_RESKEY_*
OCF_RESKEY_*
- Each of a resource's instance parameters is converted to an environment
variable prefixed with "OCF_RESKEY\_".
* - .. _OCF_RESOURCE_INSTANCE:
.. index::
single: OCF_RESOURCE_INSTANCE
single: environment variable; OCF_RESOURCE_INSTANCE
OCF_RESOURCE_INSTANCE
- The name of the resource instance.
* - .. _OCF_RESOURCE_PROVIDER:
.. index::
single: OCF_RESOURCE_PROVIDER
single: environment variable; OCF_RESOURCE_PROVIDER
OCF_RESOURCE_PROVIDER
- The name of the resource agent provider.
* - .. _OCF_RESOURCE_TYPE:
.. index::
single: OCF_RESOURCE_TYPE
single: environment variable; OCF_RESOURCE_TYPE
OCF_RESOURCE_TYPE
- The name of the resource type.
* - .. _OCF_ROOT:
.. index::
single: OCF_ROOT
single: environment variable; OCF_ROOT
OCF_ROOT
- The root of the OCF directory hierarchy.
* - .. _OCF_TRACE_FILE:
.. index::
single: OCF_TRACE_FILE
single: environment variable; OCF_TRACE_FILE
OCF_TRACE_FILE
- The absolute path or file descriptor to write trace output to, if
``OCF_TRACE_RA`` is set to true. Pacemaker sets this only to
``/dev/stderr`` and only when running a resource agent via
``crm_resource``.
* - .. _OCF_TRACE_RA:
.. index::
single: OCF_TRACE_RA
single: environment variable; OCF_TRACE_RA
OCF_TRACE_RA
- If set to true, enable tracing of the resource agent. Trace output is
written to ``OCF_TRACE_FILE`` if set; otherwise, it's written to a file
in ``OCF_RESKEY_trace_dir`` if set or in a default directory if not.
Pacemaker sets this to true only when running a resource agent via
``crm_resource`` with one or more ``-V`` flags.
* - .. _PCMK_DEBUGLOG:
.. _HA_DEBUGLOG:
.. index::
single: PCMK_DEBUGLOG
single: environment variable; PCMK_DEBUGLOG
single: HA_DEBUGLOG
single: environment variable; HA_DEBUGLOG
PCMK_DEBUGLOG (and HA_DEBUGLOG)
- Where to write resource agent debug logs. Pacemaker sets this to
``PCMK_logfile`` if set to a value other than ``none`` and if debugging
is enabled for the executor.
* - .. _PCMK_LOGFACILITY:
.. _HA_LOGFACILITY:
.. index::
single: PCMK_LOGFACILITY
single: environment variable; PCMK_LOGFACILITY
single: HA_LOGFACILITY
single: environment variable; HA_LOGFACILITY
PCMK_LOGFACILITY (and HA_LOGFACILITY)
- Syslog facility for resource agent logs. Pacemaker sets this to
``PCMK_logfacility`` if set to a value other than ``none`` or
``/dev/null``.
* - .. _PCMK_LOGFILE:
- .. _HA_LOGFILE::
+ .. _HA_LOGFILE:
.. index::
single: PCMK_LOGFILE:
single: environment variable; PCMK_LOGFILE:
single: HA_LOGFILE:
single: environment variable; HA_LOGFILE:
PCMK_LOGFILE (and HA_LOGFILE)
- Where to write resource agent logs. Pacemaker sets this to
``PCMK_logfile`` if set to a value other than ``none``.
* - .. _PCMK_service:
.. index::
single: PCMK_service
single: environment variable; PCMK_service
PCMK_service
- The name of the Pacemaker subsystem or command-line tool that's executing
the resource agent. Specific values are subject to change; useful mainly
for logging.
Clone Resource Agent Requirements
_________________________________
Any resource can be used as an anonymous clone, as it requires no additional
support from the resource agent. Whether it makes sense to do so depends on your
resource and its resource agent.
Resource Agent Requirements for Globally Unique Clones
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Globally unique clones require additional support in the resource agent. In
particular, it must respond with ``OCF_SUCCESS`` only if the node has that exact
instance active. All other probes for instances of the clone should result in
``OCF_NOT_RUNNING`` (or one of the other OCF error codes if they are failed).
Individual instances of a clone are identified by appending a colon and a
numerical offset (for example, ``apache:2``).
A resource agent can find out how many copies there are by examining the
``OCF_RESKEY_CRM_meta_clone_max`` environment variable and which instance it is
by examining ``OCF_RESKEY_CRM_meta_clone``.
The resource agent must not make any assumptions (based on
``OCF_RESKEY_CRM_meta_clone``) about which numerical instances are active. In
particular, the list of active copies is not always an unbroken sequence, nor
does it always start at 0.
Resource Agent Requirements for Promotable Clones
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Promotable clone resources require two extra actions, ``demote`` and ``promote``,
which are responsible for changing the state of the resource. Like ``start`` and
``stop``, they should return ``OCF_SUCCESS`` if they completed successfully or a
relevant error code if they did not.
The states can mean whatever you wish, but when the resource is started, it must
begin in the unpromoted role. From there, the cluster will decide which
instances to promote.
In addition to the clone requirements for monitor actions, agents must also
*accurately* report which state they are in. The cluster relies on the agent to
report its status (including role) accurately and does not indicate to the agent
what role it currently believes it to be in.
.. list-table:: **Role Implications of OCF Return Codes**
:class: longtable
:widths: 1 3
:header-rows: 1
* - Monitor Return Code
- Description
* - :ref:`OCF_NOT_RUNNING `
- .. index::
single: OCF_NOT_RUNNING
single: OCF return code; OCF_NOT_RUNNING
Stopped
* - :ref:`OCF_SUCCESS `
- .. index::
single: OCF_SUCCESS
single: OCF return code; OCF_SUCCESS
Running (Unpromoted)
* - :ref:`OCF_RUNNING_PROMOTED `
- .. index::
single: OCF_RUNNING_PROMOTED
single: OCF return code; OCF_RUNNING_PROMOTED
Running (Promoted)
* - :ref:`OCF_FAILED_PROMOTED `
- .. index::
single: OCF_FAILED_PROMOTED
single: OCF return code; OCF_FAILED_PROMOTED
Failed (Promoted)
* - Other
- Failed (Unpromoted)
.. _clone_notifications:
Clone Notifications
~~~~~~~~~~~~~~~~~~~
If the clone has the ``notify`` meta-attribute set to ``true`` and the resource
agent supports the ``notify`` action, Pacemaker will call the action when
appropriate, passing a number of extra variables. These variables, when combined
with additional context, can be used to calculate the current state of the
cluster and what is about to happen to it.
.. index::
single: clone; environment variables
single: notify; environment variables
.. list-table:: **Environment Variables Supplied with Clone Notify Actions**
:class: longtable
:widths: 1 1
:header-rows: 1
* - Variable
- Description
* - .. _OCF_RESKEY_CRM_meta_notify_type:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_type
single: OCF_RESKEY_CRM_meta_notify_type
OCF_RESKEY_CRM_meta_notify_type
- Allowed values: ``pre``, ``post``
* - .. _OCF_RESKEY_CRM_meta_notify_operation:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_operation
single: OCF_RESKEY_CRM_meta_notify_operation
OCF_RESKEY_CRM_meta_notify_operation
- Allowed values: ``start``, ``stop``
* - .. _OCF_RESKEY_CRM_meta_notify_start_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_start_resource
single: OCF_RESKEY_CRM_meta_notify_start_resource
OCF_RESKEY_CRM_meta_notify_start_resource
- Resources to be started
* - .. _OCF_RESKEY_CRM_meta_notify_stop_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_stop_resource
single: OCF_RESKEY_CRM_meta_notify_stop_resource
OCF_RESKEY_CRM_meta_notify_stop_resource
- Resources to be stopped
* - .. _OCF_RESKEY_CRM_meta_notify_active_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_active_resource
single: OCF_RESKEY_CRM_meta_notify_active_resource
OCF_RESKEY_CRM_meta_notify_active_resource
- Resources that are running
* - .. _OCF_RESKEY_CRM_meta_notify_inactive_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_inactive_resource
single: OCF_RESKEY_CRM_meta_notify_inactive_resource
OCF_RESKEY_CRM_meta_notify_inactive_resource
- Resources that are not running
* - .. _OCF_RESKEY_CRM_meta_notify_start_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_start_uname
single: OCF_RESKEY_CRM_meta_notify_start_uname
OCF_RESKEY_CRM_meta_notify_start_uname
- Nodes on which resources will be started
* - .. _OCF_RESKEY_CRM_meta_notify_stop_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_stop_uname
single: OCF_RESKEY_CRM_meta_notify_stop_uname
OCF_RESKEY_CRM_meta_notify_stop_uname
- Nodes on which resources will be stopped
* - .. _OCF_RESKEY_CRM_meta_notify_active_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_active_uname
single: OCF_RESKEY_CRM_meta_notify_active_uname
OCF_RESKEY_CRM_meta_notify_active_uname
- Nodes on which resources are running
The variables come in pairs, such as
``OCF_RESKEY_CRM_meta_notify_start_resource`` and
``OCF_RESKEY_CRM_meta_notify_start_uname``, and should be treated as an array of
whitespace-separated elements.
``OCF_RESKEY_CRM_meta_notify_inactive_resource`` is an exception, as the
matching ``uname`` variable does not exist since inactive resources are not
running on any node.
Thus, in order to indicate that ``clone:0`` will be started on ``sles-1``,
``clone:2`` will be started on ``sles-3``, and ``clone:3`` will be started
on ``sles-2``, the cluster would set:
.. topic:: Notification Variables
.. code-block:: none
OCF_RESKEY_CRM_meta_notify_start_resource="clone:0 clone:2 clone:3"
OCF_RESKEY_CRM_meta_notify_start_uname="sles-1 sles-3 sles-2"
.. note::
Pacemaker will log but otherwise ignore failures of notify actions.
Interpretation of Notification Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Pre-notification (stop):**
* Active resources: ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* Inactive resources: ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
**Post-notification (stop) / Pre-notification (start):**
* Active resources
* ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Inactive resources
* ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
**Post-notification (start):**
* Active resources:
* ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Inactive resources:
* ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
Extra Notifications for Promotable Clones
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. index::
single: clone; environment variables
single: promotable; environment variables
.. list-table:: **Extra Environment Variables Supplied for Promotable Clones**
:class: longtable
:widths: 1 1
:header-rows: 1
* - Variable
- Description
* - .. _OCF_RESKEY_CRM_meta_notify_promoted_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_promoted_resource
single: OCF_RESKEY_CRM_meta_notify_promoted_resource
OCF_RESKEY_CRM_meta_notify_promoted_resource
- Resources that are running in the promoted role
* - .. _OCF_RESKEY_CRM_meta_notify_unpromoted_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_unpromoted_resource
single: OCF_RESKEY_CRM_meta_notify_unpromoted_resource
OCF_RESKEY_CRM_meta_notify_unpromoted_resource
- Resources that are running in the unpromoted role
* - .. _OCF_RESKEY_CRM_meta_notify_promote_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_promote_resource
single: OCF_RESKEY_CRM_meta_notify_promote_resource
OCF_RESKEY_CRM_meta_notify_promote_resource
- Resources to be promoted
* - .. _OCF_RESKEY_CRM_meta_notify_demote_resource:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_demote_resource
single: OCF_RESKEY_CRM_meta_notify_demote_resource
OCF_RESKEY_CRM_meta_notify_demote_resource
- Resources to be demoted
* - .. _OCF_RESKEY_CRM_meta_notify_promote_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_promote_uname
single: OCF_RESKEY_CRM_meta_notify_promote_uname
OCF_RESKEY_CRM_meta_notify_promote_uname
- Nodes on which resources will be promoted
* - .. _OCF_RESKEY_CRM_meta_notify_demote_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_demote_uname
single: OCF_RESKEY_CRM_meta_notify_demote_uname
OCF_RESKEY_CRM_meta_notify_demote_uname
- Nodes on which resources will be demoted
* - .. _OCF_RESKEY_CRM_meta_notify_promoted_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_promoted_uname
single: OCF_RESKEY_CRM_meta_notify_promoted_uname
OCF_RESKEY_CRM_meta_notify_promoted_uname
- Nodes on which resources are running in the promoted role
* - .. _OCF_RESKEY_CRM_meta_notify_unpromoted_uname:
.. index::
single: environment variable; OCF_RESKEY_CRM_meta_notify_unpromoted_uname
single: OCF_RESKEY_CRM_meta_notify_unpromoted_uname
OCF_RESKEY_CRM_meta_notify_unpromoted_uname
- Nodes on which resources are running in the unpromoted role
Interpretation of Promotable Notification Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Pre-notification (demote):**
* Active resources: ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* Promoted resources: ``$OCF_RESKEY_CRM_meta_notify_promoted_resource``
* Unpromoted resources: ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource``
* Inactive resources: ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
**Post-notification (demote) / Pre-notification (stop):**
* Active resources: ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* Promoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_promoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Unpromoted resources: ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource``
* Inactive resources: ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
**Post-notification (stop) / Pre-notification (start)**
* Active resources:
* ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Promoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_promoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Unpromoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Inactive resources:
* ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
**Post-notification (start) / Pre-notification (promote)**
* Active resources:
* ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Promoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_promoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Unpromoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Inactive resources:
* ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
**Post-notification (promote)**
* Active resources:
* ``$OCF_RESKEY_CRM_meta_notify_active_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Promoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_promoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Unpromoted resources:
* ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Inactive resources:
* ``$OCF_RESKEY_CRM_meta_notify_inactive_resource``
* plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* minus ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource``
* Resources that were promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource``
* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource``
* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource``
.. index::
single: resource agent; LSB
single: LSB resource agent
single: init script
LSB Resource Agents (Init Scripts)
##################################
LSB Compliance
______________
The relevant part of the
`LSB specifications `_
includes a description of all the return codes listed here.
Assuming `some_service` is configured correctly and currently
inactive, the following sequence will help you determine if it is
LSB-compatible:
#. Start (stopped):
.. code-block:: none
# /etc/init.d/some_service start ; echo "result: $?"
* Did the service start?
* Did the echo command print ``result: 0`` (in addition to the init script's
usual output)?
#. Status (running):
.. code-block:: none
# /etc/init.d/some_service status ; echo "result: $?"
* Did the script accept the command?
* Did the script indicate the service was running?
* Did the echo command print ``result: 0`` (in addition to the init script's
usual output)?
#. Start (running):
.. code-block:: none
# /etc/init.d/some_service start ; echo "result: $?"
* Is the service still running?
* Did the echo command print ``result: 0`` (in addition to the init
script's usual output)?
#. Stop (running):
.. code-block:: none
# /etc/init.d/some_service stop ; echo "result: $?"
* Was the service stopped?
* Did the echo command print ``result: 0`` (in addition to the init
script's usual output)?
#. Status (stopped):
.. code-block:: none
# /etc/init.d/some_service status ; echo "result: $?"
* Did the script accept the command?
* Did the script indicate the service was not running?
* Did the echo command print ``result: 3`` (in addition to the init
script's usual output)?
#. Stop (stopped):
.. code-block:: none
# /etc/init.d/some_service stop ; echo "result: $?"
* Is the service still stopped?
* Did the echo command print ``result: 0`` (in addition to the init
script's usual output)?
#. Status (failed):
This step is not readily testable and relies on manual inspection of the script.
The script can use one of the error codes (other than 3) listed in the
LSB spec to indicate that it is active but failed. This tells the
cluster that before moving the resource to another node, it needs to
stop it on the existing one first.
If the answer to any of the above questions is no, then the script is not
LSB-compliant. Your options are then to either fix the script or write an OCF
agent based on the existing script.
diff --git a/tools/crm_rule.8.inc b/tools/crm_rule.8.inc
index 2b6ac89617..103bebacf7 100644
--- a/tools/crm_rule.8.inc
+++ b/tools/crm_rule.8.inc
@@ -1,8 +1,5 @@
[synopsis]
-crm_rule mode [options]
+crm_rule [options]
-/state of rules/
+/from the Pacemaker configuration/
.SH OPTIONS
-
-/multiple times/
-.SH NOTICE