Page MenuHomeClusterLabs Projects
Files F3687356

No OneTemporary
Actions

View Options

diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index e48e19a780..5f3902fc59 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -1,222 +1,223 @@
#
# 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
# Things you might want to override on the command line
# Books to generate
BOOKS ?= Clusters_from_Scratch \
Pacemaker_Administration \
Pacemaker_Development \
Pacemaker_Explained \
Pacemaker_Python_API \
Pacemaker_Remote
# Output formats to generate. Possible values:
# html (multiple HTML files)
# dirhtml (HTML files named index.html in multiple directories)
# singlehtml (a single large HTML file)
# text
# pdf
# epub
# latex
# linkcheck (not actually a format; check validity of external links)
#
# The results will end up in <book>/_build/<format>
BOOK_FORMATS ?= singlehtml
# Set to "a4paper" or "letterpaper" if building latex format
PAPER ?= letterpaper
# Additional options for sphinx-build
SPHINXFLAGS ?=
# toplevel rsync destination for www targets (without trailing slash)
RSYNC_DEST ?= root@www.clusterlabs.org:/var/www/html
# End of useful overrides
# Example scheduler transition graphs
# @TODO The original CIB XML for these is long lost. Ideally, we would recreate
# something similar and keep those here instead of the DOTs (or use a couple of
# scheduler regression test inputs instead), then regenerate the SVG
# equivalents using crm_simulate and dot when making a release.
DOTS = $(wildcard shared/images/*.dot)
# Vector sources for generated PNGs (including SVG equivalents of DOTS, created
# manually using dot)
SVGS = $(wildcard shared/images/pcmk-*.svg) \
$(DOTS:%.dot=%.svg)
# PNG images generated from SVGS
#
# These will not be accessible in a VPATH build, which will generate warnings
# when building the documentation, but the make will still succeed. It is
# nontrivial to get them working for VPATH builds and not worth the effort.
PNGS_GENERATED = $(SVGS:%.svg=%.png)
# Original PNG image sources
PNGS_Clusters_from_Scratch = $(wildcard Clusters_from_Scratch/images/*.png)
PNGS_Pacemaker_Explained = $(wildcard Pacemaker_Explained/images/*.png)
PNGS_Pacemaker_Remote = $(wildcard Pacemaker_Remote/images/*.png)
STATIC_FILES = $(wildcard _static/*.css)
EXTRA_DIST = $(wildcard */*.rst) $(DOTS) $(SVGS) \
$(PNGS_Clusters_from_Scratch) \
$(PNGS_Pacemaker_Explained) \
$(PNGS_Pacemaker_Remote) \
$(wildcard Pacemaker_Python_API/_templates/*rst) \
$(STATIC_FILES) \
conf.py.in
# recursive, preserve symlinks/permissions/times, verbose, compress,
# don't cross filesystems, sparse, show progress
RSYNC_OPTS = -rlptvzxS --progress
PACKAGE_SERIES=$(shell echo "$VERSION" | awk -F. '{ print $1"."$2 }')
BOOK_RSYNC_DEST = $(RSYNC_DEST)/$(PACKAGE)/doc/$(PACKAGE_SERIES)
BOOK = none
DEPS_intro = shared/pacemaker-intro.rst \
$(PNGS_GENERATED)
DEPS_Clusters_from_Scratch = $(DEPS_intro) \
$(PNGS_Clusters_from_Scratch)
DEPS_Pacemaker_Administration = $(DEPS_intro)
DEPS_Pacemaker_Development =
DEPS_Pacemaker_Explained = $(DEPS_intro) \
$(PNGS_Pacemaker_Explained)
DEPS_Pacemaker_Python_API = ../../python
DEPS_Pacemaker_Remote = $(PNGS_Pacemaker_Remote)
if BUILD_SPHINX_DOCS
INKSCAPE_CMD = $(INKSCAPE) --export-dpi=90 -C
# Pattern rule to generate PNGs from SVGs
# (--export-png works with Inkscape <1.0, --export-filename with >=1.0;
# create the destination directory in case this is a VPATH build)
%.png: %.svg
$(AM_V_at)-$(MKDIR_P) "$(shell dirname "$@")"
$(AM_V_GEN) { \
$(INKSCAPE_CMD) --export-png="$@" "$<" 2>/dev/null \
|| $(INKSCAPE_CMD) --export-filename="$@" "$<"; \
} $(PCMK_quiet)
# Create a book's Sphinx configuration.
# Create the book directory in case this is a VPATH build.
$(BOOKS:%=%/conf.py): conf.py.in
$(AM_V_at)-$(MKDIR_P) "$(@:%/conf.py=%)"
$(AM_V_GEN)sed \
-e 's/%VERSION%/$(VERSION)/g' \
-e 's/%BOOK_ID%/$(@:%/conf.py=%)/g' \
-e 's/%BOOK_TITLE%/$(subst _, ,$(@:%/conf.py=%))/g' \
-e 's#%SRC_DIR%#$(abs_srcdir)#g' \
-e 's#%ABS_TOP_SRCDIR%#$(abs_top_srcdir)#g' \
-e 's#%CONFIGDIR%#@CONFIGDIR@#g' \
-e 's#%CRM_BLACKBOX_DIR%#@CRM_BLACKBOX_DIR@#g' \
+ -e 's#%CRM_CONFIG_DIR%#@CRM_CONFIG_DIR@#g' \
-e 's#%CRM_DAEMON_GROUP%#@CRM_DAEMON_GROUP@#g' \
-e 's#%CRM_DAEMON_USER%#@CRM_DAEMON_USER@#g' \
-e 's#%CRM_LOG_DIR%#@CRM_LOG_DIR@#g' \
-e 's#%CRM_SCHEMA_DIRECTORY%#@CRM_SCHEMA_DIRECTORY@#g' \
-e 's#%PACEMAKER_CONFIG_DIR%#@PACEMAKER_CONFIG_DIR@#g' \
-e 's#%PCMK_GNUTLS_PRIORITIES%#@PCMK_GNUTLS_PRIORITIES@#g' \
$(<) > "$@"
$(BOOK)/_build: $(STATIC_FILES) $(BOOK)/conf.py $(DEPS_$(BOOK)) $(wildcard $(srcdir)/$(BOOK)/*.rst)
@echo 'Building "$(subst _, ,$(BOOK))" because of $?' $(PCMK_quiet)
$(AM_V_at)rm -rf "$@"
$(AM_V_BOOK)for format in $(BOOK_FORMATS); do \
echo -e "\n * Building $$format" $(PCMK_quiet); \
doctrees="doctrees"; \
real_format="$$format"; \
case "$$format" in \
pdf) real_format="latex" ;; \
gettext) doctrees="gettext-doctrees" ;; \
esac; \
$(SPHINX) -b "$$real_format" -d "$@/$$doctrees" \
-c "$(builddir)/$(BOOK)" \
-D latex_elements.papersize=$(PAPER) \
$(SPHINXFLAGS) \
"$(srcdir)/$(BOOK)" "$@/$$format" \
$(PCMK_quiet); \
if [ "$$format" = "pdf" ]; then \
$(MAKE) $(AM_MAKEFLAGS) -C "$@/$$format" \
all-pdf; \
fi; \
done
endif
build-$(PACKAGE_SERIES).txt: all
$(AM_V_GEN)echo "Generated on `date --utc` from version $(TAG)" > "$@"
.PHONY: books-upload
books-upload: all build-$(PACKAGE_SERIES).txt
if BUILD_SPHINX_DOCS
@echo "Uploading $(PACKAGE_SERIES) documentation set"
@for book in $(BOOKS); do \
echo " * $$book"; \
rsync $(RSYNC_OPTS) $(BOOK_FORMATS:%=$$book/_build/%) \
"$(BOOK_RSYNC_DEST)/$$book/"; \
done
@rsync $(RSYNC_OPTS) "$(builddir)/build-$(PACKAGE_SERIES).txt" \
"$(RSYNC_DEST)/$(PACKAGE)/doc"
endif
.PHONY: all-local
all-local:
if BUILD_SPHINX_DOCS
@for book in $(BOOKS); do \
$(MAKE) $(AM_MAKEFLAGS) BOOK=$$book \
PAPER="$(PAPER)" SPHINXFLAGS="$(SPHINXFLAGS)" \
BOOK_FORMATS="$(BOOK_FORMATS)" $$book/_build; \
done
endif
.PHONY: install-data-local
install-data-local: all-local
if BUILD_SPHINX_DOCS
$(AM_V_at)for book in $(BOOKS); do \
for format in $(BOOK_FORMATS); do \
formatdir="$$book/_build/$$format"; \
for f in `find "$$formatdir" -print`; do \
dname="`echo $$f | sed s:_build/::`"; \
dloc="$(DESTDIR)/$(docdir)/$$dname"; \
if [ -d "$$f" ]; then \
$(INSTALL) -d -m 755 "$$dloc"; \
else \
$(INSTALL_DATA) "$$f" "$$dloc"; \
fi \
done; \
done; \
done
endif
.PHONY: uninstall-local
uninstall-local:
if BUILD_SPHINX_DOCS
$(AM_V_at)for book in $(BOOKS); do \
rm -rf "$(DESTDIR)/$(docdir)/$$book"; \
done
endif
.PHONY: clean-local
clean-local:
$(AM_V_at)-rm -rf \
$(BOOKS:%="$(builddir)/%/_build") \
$(BOOKS:%="$(builddir)/%/conf.py") \
$(BOOKS:%="$(builddir)/%/generated") \
$(PNGS_GENERATED)
diff --git a/doc/sphinx/Pacemaker_Administration/agents.rst b/doc/sphinx/Pacemaker_Administration/agents.rst
index e5b17e273f..34bea60f85 100644
--- a/doc/sphinx/Pacemaker_Administration/agents.rst
+++ b/doc/sphinx/Pacemaker_Administration/agents.rst
@@ -1,443 +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
<primitive id="custom-app" class="ocf" provider="big-corp" type="big-app"/>
.. index::
single: OCF resource agent; action
Actions
_______
All OCF resource agents are required to implement the following actions.
-.. table:: **Required Actions for OCF Agents**
-
- +--------------+-------------+------------------------------------------------+
- | Action | Description | Instructions |
- +==============+=============+================================================+
- | start | Start the | .. index:: |
- | | resource | single: OCF resource agent; start |
- | | | single: start action |
- | | | |
- | | | Return 0 on success and an appropriate |
- | | | error code otherwise. Must not report |
- | | | success until the resource is fully |
- | | | active. |
- +--------------+-------------+------------------------------------------------+
- | stop | Stop the | .. index:: |
- | | resource | single: OCF resource agent; stop |
- | | | single: stop action |
- | | | |
- | | | Return 0 on success and an appropriate |
- | | | error code otherwise. Must not report |
- | | | success until the resource is fully |
- | | | stopped. |
- +--------------+-------------+------------------------------------------------+
- | monitor | Check the | .. index:: |
- | | resource's | single: OCF resource agent; monitor |
- | | state | single: monitor action |
- | | | |
- | | | Exit 0 if the resource is running, 7 |
- | | | if it is stopped, and any other OCF |
- | | | exit code if it is failed. NOTE: The |
- | | | monitor script should test the state |
- | | | of the resource on the local machine |
- | | | only. |
- +--------------+-------------+------------------------------------------------+
- | meta-data | Describe | .. index:: |
- | | the | single: OCF resource agent; meta-data |
- | | resource | single: meta-data action |
- | | | |
- | | | Provide information about this |
- | | | resource in the XML format defined by |
- | | | the OCF standard. Exit with 0. NOTE: |
- | | | This is *not* required to be performed |
- | | | as root. |
- +--------------+-------------+------------------------------------------------+
+.. 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 <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 <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 <OCF_SUCCESS>` if the resource is running,
+ :ref:`OCF_NOT_RUNNING <OCF_NOT_RUNNING>` if it is stopped, and any other
+ :ref:`OCF exit code <ocf_return_codes>` 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 <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.
-.. table:: **Optional Actions for OCF Resource Agents**
-
- +--------------+-------------+------------------------------------------------+
- | Action | Description | Instructions |
- +==============+=============+================================================+
- | validate-all | This should | .. index:: |
- | | validate | single: OCF resource agent; validate-all |
- | | the | single: validate-all action |
- | | instance | |
- | | parameters | Return 0 if parameters are valid, 2 if |
- | | provided. | not valid, and 6 if resource is not |
- | | | configured. |
- +--------------+-------------+------------------------------------------------+
- | promote | Bring the | .. index:: |
- | | local | single: OCF resource agent; promote |
- | | instance of | single: promote action |
- | | a promotable| |
- | | clone | Return 0 on success |
- | | resource to | |
- | | the promoted| |
- | | role. | |
- +--------------+-------------+------------------------------------------------+
- | demote | Bring the | .. index:: |
- | | local | single: OCF resource agent; demote |
- | | instance of | single: demote action |
- | | a promotable| |
- | | clone | Return 0 on success |
- | | resource to | |
- | | the | |
- | | unpromoted | |
- | | role. | |
- +--------------+-------------+------------------------------------------------+
- | notify | Used by the | .. index:: |
- | | cluster to | single: OCF resource agent; notify |
- | | send | single: notify action |
- | | the agent | |
- | | pre- and | Must not fail. Must exit with 0 |
- | | post- | |
- | | notification| |
- | | events | |
- | | telling the | |
- | | resource | |
- | | what has | |
- | | happened and| |
- | | will happen.| |
- +--------------+-------------+------------------------------------------------+
- | reload | Reload the | .. index:: |
- | | service's | single: OCF resource agent; reload |
- | | own | single: reload action |
- | | config. | |
- | | | Not used by Pacemaker |
- +--------------+-------------+------------------------------------------------+
- | reload-agent | Make | .. index:: |
- | | effective | single: OCF resource agent; reload-agent |
- | | any changes | single: reload-agent action |
- | | in instance | |
- | | parameters | This is used when the agent can handle a |
- | | marked as | change in some of its parameters more |
- | | reloadable | efficiently than stopping and starting the |
- | | in the | resource. |
- | | agent's | |
- | | meta-data. | |
- +--------------+-------------+------------------------------------------------+
- | recover | Restart the | .. index:: |
- | | service. | single: OCF resource agent; recover |
- | | | single: recover action |
- | | | |
- | | | Not used by Pacemaker |
- +--------------+-------------+------------------------------------------------+
+.. 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 <OCF_SUCCESS>` if parameters are valid,
+ :ref:`OCF_ERR_ARGS <OCF_ERR_ARGS>` if not valid, and
+ :ref:`OCF_ERR_CONFIGURED <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 <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 <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 <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?
+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.
+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:
-.. table:: **Types of recovery performed by the cluster**
-
- +-------+--------------------------------------------+--------------------------------------+
- | Type | Description | Action Taken by the Cluster |
- +=======+============================================+======================================+
- | soft | .. index:: | Restart the resource or move it to a |
- | | single: OCF resource agent; soft error | new location |
- | | | |
- | | A transient error occurred | |
- +-------+--------------------------------------------+--------------------------------------+
- | hard | .. index:: | Move the resource elsewhere and |
- | | single: OCF resource agent; hard error | prevent it from being retried on the |
- | | | current node |
- | | A non-transient error that | |
- | | may be specific to the | |
- | | current node | |
- +-------+--------------------------------------------+--------------------------------------+
- | fatal | .. index:: | Stop the resource and prevent it |
- | | single: OCF resource agent; fatal error | from being started on any cluster |
- | | | node |
- | | A non-transient error that | |
- | | will be common to all | |
- | | cluster nodes (e.g. a bad | |
- | | configuration was specified) | |
- +-------+--------------------------------------------+--------------------------------------+
+.. 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 different OCF return codes and the type of
+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 0 (aka. ``OCF_SUCCESS``) can be
-considered to have failed, if 0 was not the expected return value.
-
-.. table:: **OCF Exit Codes and their Recovery Types**
-
- +-------+-----------------------+---------------------------------------------------+----------+
- | Exit | OCF Alias | Description | Recovery |
- | Code | | | |
- +=======+=======================+===================================================+==========+
- | 0 | OCF_SUCCESS | .. index:: | soft |
- | | | single: OCF_SUCCESS | |
- | | | single: OCF return code; OCF_SUCCESS | |
- | | | pair: OCF return code; 0 | |
- | | | | |
- | | | Success. The command completed successfully. | |
- | | | This is the expected result for all start, | |
- | | | stop, promote and demote commands. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 1 | OCF_ERR_GENERIC | .. index:: | soft |
- | | | single: OCF_ERR_GENERIC | |
- | | | single: OCF return code; OCF_ERR_GENERIC | |
- | | | pair: OCF return code; 1 | |
- | | | | |
- | | | Generic "there was a problem" error code. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 2 | OCF_ERR_ARGS | .. index:: | hard |
- | | | single: OCF_ERR_ARGS | |
- | | | single: OCF return code; OCF_ERR_ARGS | |
- | | | pair: OCF return code; 2 | |
- | | | | |
- | | | 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). | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 3 | OCF_ERR_UNIMPLEMENTED | .. index:: | hard |
- | | | single: OCF_ERR_UNIMPLEMENTED | |
- | | | single: OCF return code; OCF_ERR_UNIMPLEMENTED | |
- | | | pair: OCF return code; 3 | |
- | | | | |
- | | | The requested action is not implemented. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 4 | OCF_ERR_PERM | .. index:: | hard |
- | | | single: OCF_ERR_PERM | |
- | | | single: OCF return code; OCF_ERR_PERM | |
- | | | pair: OCF return code; 4 | |
- | | | | |
- | | | The resource agent does not have | |
- | | | sufficient privileges to complete the task. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 5 | OCF_ERR_INSTALLED | .. index:: | hard |
- | | | single: OCF_ERR_INSTALLED | |
- | | | single: OCF return code; OCF_ERR_INSTALLED | |
- | | | pair: OCF return code; 5 | |
- | | | | |
- | | | The tools required by the resource are | |
- | | | not installed on this machine. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 6 | OCF_ERR_CONFIGURED | .. index:: | fatal |
- | | | single: OCF_ERR_CONFIGURED | |
- | | | single: OCF return code; OCF_ERR_CONFIGURED | |
- | | | pair: OCF return code; 6 | |
- | | | | |
- | | | The resource's parameter values are inherently | |
- | | | invalid (for example, a required parameter was | |
- | | | not given). | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 7 | OCF_NOT_RUNNING | .. index:: | N/A |
- | | | single: OCF_NOT_RUNNING | |
- | | | single: OCF return code; OCF_NOT_RUNNING | |
- | | | pair: OCF return code; 7 | |
- | | | | |
- | | | The resource is safely stopped. This should only | |
- | | | be returned by monitor actions, not stop actions. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 8 | OCF_RUNNING_PROMOTED | .. index:: | soft |
- | | | single: OCF_RUNNING_PROMOTED | |
- | | | single: OCF return code; OCF_RUNNING_PROMOTED | |
- | | | pair: OCF return code; 8 | |
- | | | | |
- | | | The resource is running in the promoted role. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 9 | OCF_FAILED_PROMOTED | .. index:: | soft |
- | | | single: OCF_FAILED_PROMOTED | |
- | | | single: OCF return code; OCF_FAILED_PROMOTED | |
- | | | pair: OCF return code; 9 | |
- | | | | |
- | | | 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. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 190 | OCF_DEGRADED | .. index:: | none |
- | | | single: OCF_DEGRADED | |
- | | | single: OCF return code; OCF_DEGRADED | |
- | | | pair: OCF return code; 190 | |
- | | | | |
- | | | The resource is properly active, but in such a | |
- | | | condition that future failures are more likely. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | 191 | OCF_DEGRADED_PROMOTED | .. index:: | none |
- | | | single: OCF_DEGRADED_PROMOTED | |
- | | | single: OCF return code; OCF_DEGRADED_PROMOTED | |
- | | | pair: OCF return code; 191 | |
- | | | | |
- | | | The resource is properly active in the promoted | |
- | | | role, but in such a condition that future | |
- | | | failures are more likely. | |
- +-------+-----------------------+---------------------------------------------------+----------+
- | other | *none* | Custom error code. | soft |
- +-------+-----------------------+---------------------------------------------------+----------+
+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 <soft_error>`
+ * - .. _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 <hard_error>`
+ * - .. _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 <hard_error>`
+ * - .. _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 <hard_error>`
+ * - .. _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 <hard_error>`
+ * - .. _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 <hard_error>`
+ * - .. _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 <fatal_error>`
+ * - .. _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 <soft_error>`
+ * - .. _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 <soft_error>`
+ * - .. _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 <http://standards.clusterlabs.org>`_ 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 <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 <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::
+
+ .. 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 <OCF_NOT_RUNNING>`
+ - .. index::
+ single: OCF_NOT_RUNNING
+ single: OCF return code; OCF_NOT_RUNNING
+
+ Stopped
+ * - :ref:`OCF_SUCCESS <OCF_SUCCESS>`
+ - .. index::
+ single: OCF_SUCCESS
+ single: OCF return code; OCF_SUCCESS
+
+ Running (Unpromoted)
+ * - :ref:`OCF_RUNNING_PROMOTED <OCF_RUNNING_PROMOTED>`
+ - .. index::
+ single: OCF_RUNNING_PROMOTED
+ single: OCF return code; OCF_RUNNING_PROMOTED
+
+ Running (Promoted)
+ * - :ref:`OCF_FAILED_PROMOTED <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 <http://refspecs.linuxfoundation.org/lsb.shtml>`_
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/doc/sphinx/Pacemaker_Administration/configuring.rst b/doc/sphinx/Pacemaker_Administration/configuring.rst
index 295c96a89a..e4d70c4828 100644
--- a/doc/sphinx/Pacemaker_Administration/configuring.rst
+++ b/doc/sphinx/Pacemaker_Administration/configuring.rst
@@ -1,265 +1,226 @@
.. index::
single: configuration
single: CIB
Configuring Pacemaker
---------------------
Pacemaker's configuration, the CIB, is stored in XML format. Cluster
administrators have multiple options for modifying the configuration either via
the XML, or at a more abstract (and easier for humans to understand) level.
Pacemaker reacts to configuration changes as soon as they are saved.
Pacemaker's command-line tools and most higher-level tools provide the ability
to batch changes together and commit them at once, rather than make a series of
small changes, which could cause avoid unnecessary actions as Pacemaker
responds to each change individually.
Pacemaker tracks revisions to the configuration and will reject any update
older than the current revision. Thus, it is a good idea to serialize all
changes to the configuration. Avoid attempting simultaneous changes, whether on
the same node or different nodes, and whether manually or using some automated
configuration tool.
.. note::
It is not necessary to update the configuration on all cluster nodes.
Pacemaker immediately synchronizes changes to all active members of the
cluster. To reduce bandwidth, the cluster only broadcasts the incremental
updates that result from your changes and uses checksums to ensure that each
copy is consistent.
Configuration Using Higher-level Tools
######################################
Most users will benefit from using higher-level tools provided by projects
separate from Pacemaker. Some of the most commonly used include the crm shell,
hawk, and pcs. [#]_
See those projects' documentation for details on how to configure Pacemaker
using them.
Configuration Using Pacemaker's Command-Line Tools
##################################################
Pacemaker provides lower-level, command-line tools to manage the cluster. Most
configuration tasks can be performed with these tools, without needing any XML
knowledge.
To enable STONITH for example, one could run:
.. code-block:: none
# crm_attribute --name stonith-enabled --update 1
Or, to check whether **node1** is allowed to run resources, there is:
.. code-block:: none
# crm_standby --query --node node1
Or, to change the failure threshold of **my-test-rsc**, one can use:
.. code-block:: none
# crm_resource -r my-test-rsc --set-parameter migration-threshold --parameter-value 3 --meta
Examples of using these tools for specific cases will be given throughout this
document where appropriate. See the man pages for further details.
See :ref:`cibadmin` for how to edit the CIB using XML.
See :ref:`crm_shadow` for a way to make a series of changes, then commit them
all at once to the live cluster.
.. index::
single: configuration; CIB properties
single: CIB; properties
single: CIB property
Working with CIB Properties
___________________________
Although these fields can be written to by the user, in
most cases the cluster will overwrite any values specified by the
user with the "correct" ones.
To change the ones that can be specified by the user, for example
``admin_epoch``, one should use:
.. code-block:: none
# cibadmin --modify --xml-text '<cib admin_epoch="42"/>'
A complete set of CIB properties will look something like this:
.. topic:: XML attributes set for a cib element
.. code-block:: xml
<cib crm_feature_set="3.0.7" validate-with="pacemaker-1.2"
admin_epoch="42" epoch="116" num_updates="1"
cib-last-written="Mon Jan 12 15:46:39 2015" update-origin="rhel7-1"
update-client="crm_attribute" have-quorum="1" dc-uuid="1">
.. index::
single: configuration; cluster options
Querying and Setting Cluster Options
____________________________________
Cluster options can be queried and modified using the ``crm_attribute`` tool.
To get the current value of ``cluster-delay``, you can run:
.. code-block:: none
# crm_attribute --query --name cluster-delay
which is more simply written as
.. code-block:: none
# crm_attribute -G -n cluster-delay
If a value is found, you'll see a result like this:
.. code-block:: none
# crm_attribute -G -n cluster-delay
scope=crm_config name=cluster-delay value=60s
If no value is found, the tool will display an error:
.. code-block:: none
# crm_attribute -G -n clusta-deway
scope=crm_config name=clusta-deway value=(null)
Error performing operation: No such device or address
To use a different value (for example, 30 seconds), simply run:
.. code-block:: none
# crm_attribute --name cluster-delay --update 30s
To go back to the cluster's default value, you can delete the value, for example:
.. code-block:: none
# crm_attribute --name cluster-delay --delete
Deleted crm_config option: id=cib-bootstrap-options-cluster-delay name=cluster-delay
When Options are Listed More Than Once
______________________________________
If you ever see something like the following, it means that the option you're
modifying is present more than once.
.. topic:: Deleting an option that is listed twice
.. code-block:: none
# crm_attribute --name batch-limit --delete
Please choose from one of the matches below and supply the 'id' with --id
Multiple attributes match name=batch-limit in crm_config:
Value: 50 (set=cib-bootstrap-options, id=cib-bootstrap-options-batch-limit)
Value: 100 (set=custom, id=custom-batch-limit)
In such cases, follow the on-screen instructions to perform the requested
action. To determine which value is currently being used by the cluster, refer
to the "Rules" chapter of *Pacemaker Explained*.
.. index::
single: configuration; remote
.. _remote_connection:
Connecting from a Remote Machine
################################
Provided Pacemaker is installed on a machine, it is possible to connect to the
cluster even if the machine itself is not in the same cluster. To do this, one
-simply sets up a number of environment variables and runs the same commands as
-when working on a cluster node.
-
-.. list-table:: **Environment Variables Used to Connect to Remote Instances of the CIB**
- :class: longtable
- :widths: 2 2 5
- :header-rows: 1
-
- * - Environment Variable
- - Default
- - Description
- * - .. index::
- single: CIB_user
- single: environment variable; CIB_user
-
- CIB_user
- - |CRM_DAEMON_USER_RAW|
- - The user to connect as. Needs to be part of the |CRM_DAEMON_GROUP| group
- on the target host.
- * - .. index::
- single: CIB_passwd
- single: environment variable; CIB_passwd
-
- CIB_passwd
- -
- - The user's password. Read from the command line if unset.
- * - .. index::
- single: CIB_server
- single: environment variable; CIB_server
-
- CIB_server
- - localhost
- - The host to contact
- * - .. index::
- single: CIB_port
- single: environment variable; CIB_port
-
- CIB_port
- -
- - The port on which to contact the server; required
- * - .. index::
- single: CIB_encrypted
- single: environment variable; CIB_encrypted
-
- CIB_encrypted
- - true
- - Whether to encrypt network traffic
+simply sets the following environment variables and runs the same commands as
+when working on a cluster node:
+
+* :ref:`CIB_port <CIB_port>` (required)
+* :ref:`CIB_server <CIB_server>`
+* :ref:`CIB_user <CIB_user>`
+* :ref:`CIB_passwd <CIB_passwd>`
+* :ref:`CIB_encrypted <CIB_encrypted>`
So, if **c001n01** is an active cluster node and is listening on port 1234
for connections, and **someuser** is a member of the |CRM_DAEMON_GROUP| group,
then the following would prompt for **someuser**'s password and return
the cluster's current configuration:
.. code-block:: none
# export CIB_port=1234; export CIB_server=c001n01; export CIB_user=someuser;
# cibadmin -Q
For security reasons, the cluster does not listen for remote connections by
default. If you wish to allow remote access, you need to set the
``remote-tls-port`` (encrypted) or ``remote-clear-port`` (unencrypted) CIB
properties (i.e., those kept in the ``cib`` tag, like ``num_updates`` and
``epoch``). Encrypted communication is keyless, which makes it subject to
man-in-the-middle attacks, and thus either option should be used only on
protected networks.
.. important::
The Pacemaker version on the administration host must be the same or greater
than the version(s) on the cluster nodes. Otherwise, it may not have the
schema files necessary to validate the CIB.
.. rubric:: Footnotes
.. [#] For a list, see "Configuration Tools" at
https://clusterlabs.org/components.html
diff --git a/doc/sphinx/Pacemaker_Administration/index.rst b/doc/sphinx/Pacemaker_Administration/index.rst
index af893801b6..c8fd7220b5 100644
--- a/doc/sphinx/Pacemaker_Administration/index.rst
+++ b/doc/sphinx/Pacemaker_Administration/index.rst
@@ -1,38 +1,39 @@
Pacemaker Administration
========================
*Managing Pacemaker Clusters*
Abstract
--------
This document has instructions and tips for system administrators who
manage high-availability clusters using Pacemaker.
Table of Contents
-----------------
.. toctree::
:maxdepth: 3
:numbered:
intro
installing
cluster
+ options
configuring
tools
administrative
moving
troubleshooting
upgrading
alerts
agents
pcs-crmsh
Index
-----
* :ref:`genindex`
* :ref:`search`
diff --git a/doc/sphinx/Pacemaker_Administration/options.rst b/doc/sphinx/Pacemaker_Administration/options.rst
new file mode 100644
index 0000000000..731d17f288
--- /dev/null
+++ b/doc/sphinx/Pacemaker_Administration/options.rst
@@ -0,0 +1,178 @@
+.. index:: client options
+
+Client Options
+--------------
+
+Pacemaker uses several environment variables set on the client side.
+
+.. note:: Directory and file paths below may differ on your system depending on
+ your Pacemaker build settings. Check your Pacemaker configuration
+ file to find the correct paths.
+
+.. list-table:: **Client-side Environment Variables**
+ :class: longtable
+ :widths: 2 4 5
+ :header-rows: 1
+
+ * - Environment Variable
+ - Default
+ - Description
+ * - .. _CIB_encrypted:
+
+ .. index::
+ single: CIB_encrypted
+ single: environment variable; CIB_encrypted
+
+ CIB_encrypted
+ - true
+ - Whether to encrypt network traffic. Used with :ref:`CIB_port <CIB_port>`
+ for connecting to a remote CIB instance; ignored if
+ :ref:`CIB_port <CIB_port>` is not set.
+ * - .. _CIB_file:
+
+ .. index::
+ single: CIB_file
+ single: environment variable; CIB_file
+
+ CIB_file
+ -
+ - If set, CIB connections are created against the named XML file. Clients
+ read an input CIB from, and write the result CIB to, the named file.
+ Ignored if :ref:`CIB_shadow <CIB_shadow>` is set.
+ * - .. _CIB_passwd:
+
+ .. index::
+ single: CIB_passwd
+ single: environment variable; CIB_passwd
+
+ CIB_passwd
+ -
+ - :ref:`$CIB_user <CIB_user>`'s password. Read from the command line if
+ unset. Used with :ref:`CIB_port <CIB_port>` for connecting to a remote
+ CIB instance; ignored if :ref:`CIB_port <CIB_port>` is not set.
+ * - .. _CIB_port:
+
+ .. index::
+ single: CIB_port
+ single: environment variable; CIB_port
+
+ CIB_port
+ -
+ - If set, CIB connections are created as clients to a remote CIB instance
+ on :ref:`$CIB_server <CIB_server>` via this port. Ignored if
+ :ref:`CIB_shadow <CIB_shadow>` or :ref:`CIB_file <CIB_file>` is set.
+ * - .. _CIB_server:
+
+ .. index::
+ single: CIB_server
+ single: environment variable; CIB_server
+
+ CIB_server
+ - localhost
+ - The host to connect to. Used with :ref:`CIB_port <CIB_port>` for
+ connecting to a remote CIB instance; ignored if
+ :ref:`CIB_port <CIB_port>` is not set.
+ * - .. _CIB_shadow:
+
+ .. index::
+ single: CIB_shadow
+ single: environment variable; CIB_shadow
+
+ CIB_shadow
+ -
+ - If set, CIB connections are created against a temporary working
+ ("shadow") CIB file called ``shadow.$CIB_shadow`` in
+ :ref:`$CIB_shadow_dir <CIB_shadow_dir>`. Should be set only to the name
+ of a shadow CIB created by :ref:`crm_shadow <crm_shadow>`. Otherwise,
+ behavior is undefined.
+ * - .. _CIB_shadow_dir:
+
+ .. index::
+ single: CIB_shadow_dir
+ single: environment variable; CIB_shadow_dir
+
+ CIB_shadow_dir
+ - |CRM_CONFIG_DIR| if the current user is ``root`` or |CRM_DAEMON_USER|;
+ otherwise ``$HOME/.cib`` if :ref:`$HOME <HOME>` is set; otherwise
+ ``$TMPDIR/.cib`` if :ref:`$TMPDIR <TMPDIR>` is set to an absolute path;
+ otherwise ``/tmp/.cib``
+ - If set, shadow files are created in this directory. Ignored if
+ :ref:`CIB_shadow <CIB_shadow>` is not set.
+ * - .. _CIB_user:
+
+ .. index::
+ single: CIB_user
+ single: environment variable; CIB_user
+
+ CIB_user
+ - |CRM_DAEMON_USER| if used with :ref:`CIB_port <CIB_port>`, or the current
+ effective user otherwise
+ - If used with :ref:`CIB_port <CIB_port>`, connect to
+ :ref:`$CIB_server <CIB_server>` as this user. Must be part of the
+ |CRM_DAEMON_GROUP| group on :ref:`$CIB_server <CIB_server>`. Otherwise
+ (without :ref:`CIB_port <CIB_port>`), this is used only for ACL and
+ display purposes.
+ * - .. _EDITOR:
+
+ .. index::
+ single: EDITOR
+ single: environment variable; EDITOR
+
+ EDITOR
+ -
+ - Text editor to use for editing shadow files. Required for the ``--edit``
+ command of :ref:`crm_shadow <crm_shadow>`.
+ * - .. _HOME:
+
+ .. index::
+ single: HOME
+ single: environment variable; HOME
+
+ HOME
+ - Current user's home directory as configured in the passwd database, if an
+ entry exists
+ - Used to create a default :ref:`CIB_shadow_dir <CIB_shadow_dir>` for non-
+ privileged users.
+ * - .. _PE_fail:
+
+ .. index::
+ single: PE_fail
+ single: environment variable; PE_fail
+
+ PE_fail
+ - 0
+ - Advanced use only: A dummy graph action with action ID matching this
+ option will be marked as failed. Primarily for developer use with
+ scheduler simulations.
+ * - .. _PS1:
+
+ .. index::
+ single: PS1
+ single: environment variable; PS1
+
+ PS1
+ -
+ - The shell's primary prompt string. Used by
+ :ref:`crm_shadow <crm_shadow>`: set to indicate that the user is in an
+ interactive shadow CIB session, and checked to determine whether the user
+ is already in an interactive session before creating a new one.
+ * - .. _SHELL:
+
+ .. index::
+ single: SHELL
+ single: environment variable; SHELL
+
+ SHELL
+ -
+ - Absolute path to a shell. Used by :ref:`crm_shadow <crm_shadow>` when
+ launching an interactive session.
+ * - .. _TMPDIR:
+
+ .. index::
+ single: TMPDIR
+ single: environment variable; TMPDIR
+
+ TMPDIR
+ - /tmp
+ - Directory for temporary files. If not an absolute path, the default is
+ used instead.
diff --git a/doc/sphinx/Pacemaker_Administration/pcs-crmsh.rst b/doc/sphinx/Pacemaker_Administration/pcs-crmsh.rst
index 3eda60adfa..7eb9720f27 100644
--- a/doc/sphinx/Pacemaker_Administration/pcs-crmsh.rst
+++ b/doc/sphinx/Pacemaker_Administration/pcs-crmsh.rst
@@ -1,443 +1,444 @@
Quick Comparison of pcs and crm shell
-------------------------------------
``pcs`` and ``crm shell`` are two popular higher-level command-line interfaces
to Pacemaker. Each has its own syntax; this chapter gives a quick comparion of
how to accomplish the same tasks using either one. Some examples also show the
equivalent command using low-level Pacmaker command-line tools.
These examples show the simplest syntax; see the respective man pages for all
possible options.
Show Cluster Configuration and Status
#####################################
.. topic:: Show Configuration (Raw XML)
.. code-block:: none
crmsh # crm configure show xml
pcs # pcs cluster cib
pacemaker # cibadmin -Q
.. topic:: Show Configuration (Human-friendly)
.. code-block:: none
crmsh # crm configure show
pcs # pcs config
.. topic:: Show Cluster Status
.. code-block:: none
crmsh # crm status
pcs # pcs status
pacemaker # crm_mon -1
Manage Nodes
############
.. topic:: Put node "pcmk-1" in standby mode
.. code-block:: none
crmsh # crm node standby pcmk-1
pcs-0.9 # pcs cluster standby pcmk-1
pcs-0.10 # pcs node standby pcmk-1
pacemaker # crm_standby -N pcmk-1 -v on
.. topic:: Remove node "pcmk-1" from standby mode
.. code-block:: none
crmsh # crm node online pcmk-1
pcs-0.9 # pcs cluster unstandby pcmk-1
pcs-0.10 # pcs node unstandby pcmk-1
pacemaker # crm_standby -N pcmk-1 -v off
Manage Cluster Properties
#########################
.. topic:: Set the "stonith-enabled" cluster property to "false"
.. code-block:: none
crmsh # crm configure property stonith-enabled=false
pcs # pcs property set stonith-enabled=false
pacemaker # crm_attribute -n stonith-enabled -v false
Show Resource Agent Information
###############################
.. topic:: List Resource Agent (RA) Classes
.. code-block:: none
crmsh # crm ra classes
pcs # pcs resource standards
pacmaker # crm_resource --list-standards
.. topic:: List Available Resource Agents (RAs) by Standard
.. code-block:: none
crmsh # crm ra list ocf
pcs # pcs resource agents ocf
pacemaker # crm_resource --list-agents ocf
.. topic:: List Available Resource Agents (RAs) by OCF Provider
.. code-block:: none
crmsh # crm ra list ocf pacemaker
pcs # pcs resource agents ocf:pacemaker
pacemaker # crm_resource --list-agents ocf:pacemaker
.. topic:: List Available Resource Agent Parameters
.. code-block:: none
crmsh # crm ra info IPaddr2
pcs # pcs resource describe IPaddr2
pacemaker # crm_resource --show-metadata ocf:heartbeat:IPaddr2
You can also use the full ``class:provider:type`` format with crmsh and pcs if
multiple RAs with the same name are available.
.. topic:: Show Available Fence Agent Parameters
.. code-block:: none
crmsh # crm ra info stonith:fence_ipmilan
pcs # pcs stonith describe fence_ipmilan
Manage Resources
################
.. topic:: Create a Resource
.. code-block:: none
+
crmsh # crm configure primitive ClusterIP IPaddr2 params ip=192.168.122.120 cidr_netmask=24
pcs # pcs resource create ClusterIP IPaddr2 ip=192.168.122.120 cidr_netmask=24
Both crmsh and pcs determine the standard and provider (``ocf:heartbeat``) automatically
since ``IPaddr2`` is unique, and automatically create operations (including
monitor) based on the agent's meta-data.
.. topic:: Show Configuration of All Resources
.. code-block:: none
crmsh # crm configure show
pcs-0.9 # pcs resource show --full
pcs-0.10 # pcs resource config
.. topic:: Show Configuration of One Resource
.. code-block:: none
crmsh # crm configure show ClusterIP
pcs-0.9 # pcs resource show ClusterIP
pcs-0.10 # pcs resource config ClusterIP
.. topic:: Show Configuration of Fencing Resources
.. code-block:: none
crmsh # crm resource status
pcs-0.9 # pcs stonith show --full
pcs-0.10 # pcs stonith config
.. topic:: Start a Resource
.. code-block:: none
crmsh # crm resource start ClusterIP
pcs # pcs resource enable ClusterIP
pacemaker # crm_resource -r ClusterIP --set-parameter target-role --meta -v Started
.. topic:: Stop a Resource
.. code-block:: none
crmsh # crm resource stop ClusterIP
pcs # pcs resource disable ClusterIP
pacemaker # crm_resource -r ClusterIP --set-parameter target-role --meta -v Stopped
.. topic:: Remove a Resource
.. code-block:: none
crmsh # crm configure delete ClusterIP
pcs # pcs resource delete ClusterIP
.. topic:: Modify a Resource's Instance Parameters
.. code-block:: none
crmsh # crm resource param ClusterIP set clusterip_hash=sourceip
pcs # pcs resource update ClusterIP clusterip_hash=sourceip
pacemaker # crm_resource -r ClusterIP --set-parameter clusterip_hash -v sourceip
crmsh also has an `edit` command which edits the simplified CIB syntax
(same commands as the command line) via a configurable text editor.
.. topic:: Modify a Resource's Instance Parameters Interactively
.. code-block:: none
crmsh # crm configure edit ClusterIP
Using the interactive shell mode of crmsh, multiple changes can be
edited and verified before committing to the live configuration:
.. topic:: Make Multiple Configuration Changes Interactively
.. code-block:: none
crmsh # crm configure
crmsh # edit
crmsh # verify
crmsh # commit
.. topic:: Delete a Resource's Instance Parameters
.. code-block:: none
crmsh # crm resource param ClusterIP delete nic
pcs # pcs resource update ClusterIP nic=
pacemaker # crm_resource -r ClusterIP --delete-parameter nic
.. topic:: List Current Resource Defaults
.. code-block:: none
crmsh # crm configure show type:rsc_defaults
pcs # pcs resource defaults
pacemaker # cibadmin -Q --scope rsc_defaults
.. topic:: Set Resource Defaults
.. code-block:: none
crmsh # crm configure rsc_defaults resource-stickiness=100
pcs # pcs resource defaults resource-stickiness=100
.. topic:: List Current Operation Defaults
.. code-block:: none
crmsh # crm configure show type:op_defaults
pcs # pcs resource op defaults
pacemaker # cibadmin -Q --scope op_defaults
.. topic:: Set Operation Defaults
.. code-block:: none
crmsh # crm configure op_defaults timeout=240s
pcs # pcs resource op defaults timeout=240s
.. topic:: Enable Resource Agent Tracing for a Resource
.. code-block:: none
crmsh # crm resource trace Website
.. topic:: Clear Fail Counts for a Resource
.. code-block:: none
crmsh # crm resource cleanup Website
pcs # pcs resource cleanup Website
pacemaker # crm_resource --cleanup -r Website
.. topic:: Create a Clone Resource
.. code-block:: none
crmsh # crm configure clone WebIP ClusterIP meta globally-unique=true clone-max=2 clone-node-max=2
pcs # pcs resource clone ClusterIP globally-unique=true clone-max=2 clone-node-max=2
.. topic:: Create a Promotable Clone Resource
.. code-block:: none
crmsh # crm configure ms WebDataClone WebData \
meta master-max=1 master-node-max=1 \
clone-max=2 clone-node-max=1 notify=true
crmsh # crm configure clone WebDataClone WebData \
meta promotable=true \
promoted-max=1 promoted-node-max=1 \
clone-max=2 clone-node-max=1 notify=true
pcs-0.9 # pcs resource master WebDataClone WebData \
master-max=1 master-node-max=1 \
clone-max=2 clone-node-max=1 notify=true
pcs-0.10 # pcs resource promotable WebData WebDataClone \
promoted-max=1 promoted-node-max=1 \
clone-max=2 clone-node-max=1 notify=true
crmsh supports both ways ('configure ms' is deprecated) to configure promotable clone since crmsh 4.4.0.
pcs will generate the clone name automatically if it is omitted from the
command line.
Manage Constraints
##################
.. topic:: Create a Colocation Constraint
.. code-block:: none
crmsh # crm configure colocation website-with-ip INFINITY: WebSite ClusterIP
pcs # pcs constraint colocation add ClusterIP with WebSite INFINITY
.. topic:: Create a Colocation Constraint Based on Role
.. code-block:: none
crmsh # crm configure colocation another-ip-with-website inf: AnotherIP WebSite:Master
pcs # pcs constraint colocation add Started AnotherIP with Promoted WebSite INFINITY
.. topic:: Create an Ordering Constraint
.. code-block:: none
crmsh # crm configure order apache-after-ip mandatory: ClusterIP WebSite
pcs # pcs constraint order ClusterIP then WebSite
.. topic:: Create an Ordering Constraint Based on Role
.. code-block:: none
crmsh # crm configure order ip-after-website Mandatory: WebSite:Master AnotherIP
pcs # pcs constraint order promote WebSite then start AnotherIP
.. topic:: Create a Location Constraint
.. code-block:: none
crmsh # crm configure location prefer-pcmk-1 WebSite 50: pcmk-1
pcs # pcs constraint location WebSite prefers pcmk-1=50
.. topic:: Create a Location Constraint Based on Role
.. code-block:: none
crmsh # crm configure location prefer-pcmk-1 WebSite rule role=Master 50: \#uname eq pcmk-1
pcs # pcs constraint location WebSite rule role=Promoted 50 \#uname eq pcmk-1
.. topic:: Move a Resource to a Specific Node (by Creating a Location Constraint)
.. code-block:: none
crmsh # crm resource move WebSite pcmk-1
pcs # pcs resource move WebSite pcmk-1
pacemaker # crm_resource -r WebSite --move -N pcmk-1
.. topic:: Move a Resource Away from Its Current Node (by Creating a Location Constraint)
.. code-block:: none
crmsh # crm resource ban Website pcmk-2
pcs # pcs resource ban Website pcmk-2
pacemaker # crm_resource -r WebSite --move
.. topic:: Remove any Constraints Created by Moving a Resource
.. code-block:: none
crmsh # crm resource unmove WebSite
pcs # pcs resource clear WebSite
pacemaker # crm_resource -r WebSite --clear
Advanced Configuration
######################
Manipulate Configuration Elements by Type
_________________________________________
.. topic:: List Constraints with IDs
.. code-block:: none
pcs # pcs constraint list --full
.. topic:: Remove Constraint by ID
.. code-block:: none
pcs # pcs constraint remove cli-ban-Website-on-pcmk-1
crmsh # crm configure remove cli-ban-Website-on-pcmk-1
crmsh's `show` and `edit` commands can be used to manage resources and
constraints by type:
.. topic:: Show Configuration Elements
.. code-block:: none
crmsh # crm configure show type:primitive
crmsh # crm configure edit type:colocation
Batch Changes
_____________
.. topic:: Make Multiple Changes and Apply Together
.. code-block:: none
crmsh # crm
crmsh # cib new drbd_cfg
crmsh # configure primitive WebData ocf:linbit:drbd params drbd_resource=wwwdata \
op monitor interval=60s
crmsh # configure ms WebDataClone WebData meta master-max=1 master-node-max=1 \
clone-max=2 clone-node-max=1 notify=true
crmsh # cib commit drbd_cfg
crmsh # quit
pcs # pcs cluster cib drbd_cfg
pcs # pcs -f drbd_cfg resource create WebData ocf:linbit:drbd drbd_resource=wwwdata \
op monitor interval=60s
pcs-0.9 # pcs -f drbd_cfg resource master WebDataClone WebData \
master-max=1 master-node-max=1 clone-max=2 clone-node-max=1 notify=true
pcs-0.10 # pcs -f drbd_cfg resource promotable WebData WebDataClone \
promoted-max=1 promoted-node-max=1 clone-max=2 clone-node-max=1 notify=true
pcs # pcs cluster cib-push drbd_cfg
Template Creation
_________________
.. topic:: Create Resource Template Based on Existing Primitives of Same Type
.. code-block:: none
crmsh # crm configure assist template ClusterIP AdminIP
Log Analysis
____________
.. topic:: Show Information About Recent Cluster Events
.. code-block:: none
crmsh # crm history
crmsh # peinputs
crmsh # transition pe-input-10
crmsh # transition log pe-input-10
Configuration Scripts
_____________________
.. topic:: Script Multiple-step Cluster Configurations
.. code-block:: none
crmsh # crm script show apache
crmsh # crm script run apache \
id=WebSite \
install=true \
virtual-ip:ip=192.168.0.15 \
database:id=WebData \
database:install=true
diff --git a/doc/sphinx/Pacemaker_Explained/collective.rst b/doc/sphinx/Pacemaker_Explained/collective.rst
index a4fa9dc65b..dc6832c061 100644
--- a/doc/sphinx/Pacemaker_Explained/collective.rst
+++ b/doc/sphinx/Pacemaker_Explained/collective.rst
@@ -1,1637 +1,1226 @@
.. index:
single: collective resource
single: resource; collective
Collective Resources
--------------------
Pacemaker supports several types of *collective* resources, which consist of
multiple, related resource instances.
.. index:
single: group resource
single: resource; group
.. _group-resources:
Groups - A Syntactic Shortcut
#############################
One of the most common elements of a cluster is a set of resources
that need to be located together, start sequentially, and stop in the
reverse order. To simplify this configuration, we support the concept
of groups.
.. topic:: A group of two primitive resources
.. code-block:: xml
<group id="shortcut">
<primitive id="Public-IP" class="ocf" type="IPaddr" provider="heartbeat">
<instance_attributes id="params-public-ip">
<nvpair id="public-ip-addr" name="ip" value="192.0.2.2"/>
</instance_attributes>
</primitive>
<primitive id="Email" class="lsb" type="exim"/>
</group>
Although the example above contains only two resources, there is no
limit to the number of resources a group can contain. The example is
also sufficient to explain the fundamental properties of a group:
* Resources are started in the order they appear in (**Public-IP** first,
then **Email**)
* Resources are stopped in the reverse order to which they appear in
(**Email** first, then **Public-IP**)
If a resource in the group can't run anywhere, then nothing after that
is allowed to run, too.
* If **Public-IP** can't run anywhere, neither can **Email**;
* but if **Email** can't run anywhere, this does not affect **Public-IP**
in any way
The group above is logically equivalent to writing:
.. topic:: How the cluster sees a group resource
.. code-block:: xml
<configuration>
<resources>
<primitive id="Public-IP" class="ocf" type="IPaddr" provider="heartbeat">
<instance_attributes id="params-public-ip">
<nvpair id="public-ip-addr" name="ip" value="192.0.2.2"/>
</instance_attributes>
</primitive>
<primitive id="Email" class="lsb" type="exim"/>
</resources>
<constraints>
<rsc_colocation id="xxx" rsc="Email" with-rsc="Public-IP" score="INFINITY"/>
<rsc_order id="yyy" first="Public-IP" then="Email"/>
</constraints>
</configuration>
Obviously as the group grows bigger, the reduced configuration effort
can become significant.
Another (typical) example of a group is a DRBD volume, the filesystem
mount, an IP address, and an application that uses them.
.. index::
pair: XML element; group
Group Properties
________________
.. table:: **Properties of a Group Resource**
:widths: 1 4
+-------------+------------------------------------------------------------------+
| Field | Description |
+=============+==================================================================+
| id | .. index:: |
| | single: group; property, id |
| | single: property; id (group) |
| | single: id; group property |
| | |
| | A unique name for the group |
+-------------+------------------------------------------------------------------+
| description | .. index:: |
| | single: group; attribute, description |
| | single: attribute; description (group) |
| | single: description; group attribute |
| | |
| | An optional description of the group, for the user's own |
| | purposes. |
| | E.g. ``resources needed for website`` |
+-------------+------------------------------------------------------------------+
Group Options
_____________
Groups inherit the ``priority``, ``target-role``, and ``is-managed`` properties
from primitive resources. See :ref:`resource_options` for information about
those properties.
Group Instance Attributes
_________________________
Groups have no instance attributes. However, any that are set for the group
object will be inherited by the group's children.
Group Contents
______________
Groups may only contain a collection of cluster resources (see
:ref:`primitive-resource`). To refer to a child of a group resource, just use
the child's ``id`` instead of the group's.
Group Constraints
_________________
Although it is possible to reference a group's children in
constraints, it is usually preferable to reference the group itself.
.. topic:: Some constraints involving groups
.. code-block:: xml
<constraints>
<rsc_location id="group-prefers-node1" rsc="shortcut" node="node1" score="500"/>
<rsc_colocation id="webserver-with-group" rsc="Webserver" with-rsc="shortcut"/>
<rsc_order id="start-group-then-webserver" first="Webserver" then="shortcut"/>
</constraints>
.. index::
pair: resource-stickiness; group
Group Stickiness
________________
Stickiness, the measure of how much a resource wants to stay where it
is, is additive in groups. Every active resource of the group will
contribute its stickiness value to the group's total. So if the
default ``resource-stickiness`` is 100, and a group has seven members,
five of which are active, then the group as a whole will prefer its
current location with a score of 500.
.. index::
single: clone
single: resource; clone
.. _s-resource-clone:
Clones - Resources That Can Have Multiple Active Instances
##########################################################
*Clone* resources are resources that can have more than one copy active at the
same time. This allows you, for example, to run a copy of a daemon on every
node. You can clone any primitive or group resource [#]_.
Anonymous versus Unique Clones
______________________________
A clone resource is configured to be either *anonymous* or *globally unique*.
Anonymous clones are the simplest. These behave completely identically
everywhere they are running. Because of this, there can be only one instance of
an anonymous clone active per node.
The instances of globally unique clones are distinct entities. All instances
are launched identically, but one instance of the clone is not identical to any
other instance, whether running on the same node or a different node. As an
example, a cloned IP address can use special kernel functionality such that
each instance handles a subset of requests for the same IP address.
.. index::
single: promotable clone
single: resource; promotable
.. _s-resource-promotable:
Promotable clones
_________________
If a clone is *promotable*, its instances can perform a special role that
Pacemaker will manage via the ``promote`` and ``demote`` actions of the resource
agent.
Services that support such a special role have various terms for the special
role and the default role: primary and secondary, master and replica,
controller and worker, etc. Pacemaker uses the terms *promoted* and
*unpromoted* to be agnostic to what the service calls them or what they do.
All that Pacemaker cares about is that an instance comes up in the unpromoted role
when started, and the resource agent supports the ``promote`` and ``demote`` actions
to manage entering and exiting the promoted role.
.. index::
pair: XML element; clone
Clone Properties
________________
.. table:: **Properties of a Clone Resource**
:widths: 1 4
+-------------+------------------------------------------------------------------+
| Field | Description |
+=============+==================================================================+
| id | .. index:: |
| | single: clone; property, id |
| | single: property; id (clone) |
| | single: id; clone property |
| | |
| | A unique name for the clone |
+-------------+------------------------------------------------------------------+
| description | .. index:: |
| | single: clone; attribute, description |
| | single: attribute; description (clone) |
| | single: description; clone attribute |
| | |
| | An optional description of the clone, for the user's own |
| | purposes. |
| | E.g. ``IP address for website`` |
+-------------+------------------------------------------------------------------+
.. index::
pair: options; clone
Clone Options
_____________
:ref:`Options <resource_options>` inherited from primitive resources:
``priority, target-role, is-managed``
.. table:: **Clone-specific configuration options**
:class: longtable
:widths: 1 1 3
+-------------------+-----------------+-------------------------------------------------------+
| Field | Default | Description |
+===================+=================+=======================================================+
| globally-unique | false | .. index:: |
| | | single: clone; option, globally-unique |
| | | single: option; globally-unique (clone) |
| | | single: globally-unique; clone option |
| | | |
| | | If **true**, each clone instance performs a |
| | | distinct function |
+-------------------+-----------------+-------------------------------------------------------+
| clone-max | 0 | .. index:: |
| | | single: clone; option, clone-max |
| | | single: option; clone-max (clone) |
| | | single: clone-max; clone option |
| | | |
| | | The maximum number of clone instances that can |
| | | be started across the entire cluster. If 0, the |
| | | number of nodes in the cluster will be used. |
+-------------------+-----------------+-------------------------------------------------------+
| clone-node-max | 1 | .. index:: |
| | | single: clone; option, clone-node-max |
| | | single: option; clone-node-max (clone) |
| | | single: clone-node-max; clone option |
| | | |
| | | If ``globally-unique`` is **true**, the maximum |
| | | number of clone instances that can be started |
| | | on a single node |
+-------------------+-----------------+-------------------------------------------------------+
| clone-min | 0 | .. index:: |
| | | single: clone; option, clone-min |
| | | single: option; clone-min (clone) |
| | | single: clone-min; clone option |
| | | |
| | | Require at least this number of clone instances |
| | | to be runnable before allowing resources |
| | | depending on the clone to be runnable. A value |
| | | of 0 means require all clone instances to be |
| | | runnable. |
+-------------------+-----------------+-------------------------------------------------------+
| notify | false | .. index:: |
| | | single: clone; option, notify |
| | | single: option; notify (clone) |
| | | single: notify; clone option |
| | | |
| | | Call the resource agent's **notify** action for |
| | | all active instances, before and after starting |
| | | or stopping any clone instance. The resource |
| | | agent must support this action. |
| | | Allowed values: **false**, **true** |
+-------------------+-----------------+-------------------------------------------------------+
| ordered | false | .. index:: |
| | | single: clone; option, ordered |
| | | single: option; ordered (clone) |
| | | single: ordered; clone option |
| | | |
| | | If **true**, clone instances must be started |
| | | sequentially instead of in parallel. |
| | | Allowed values: **false**, **true** |
+-------------------+-----------------+-------------------------------------------------------+
| interleave | false | .. index:: |
| | | single: clone; option, interleave |
| | | single: option; interleave (clone) |
| | | single: interleave; clone option |
| | | |
| | | When this clone is ordered relative to another |
| | | clone, if this option is **false** (the default), |
| | | the ordering is relative to *all* instances of |
| | | the other clone, whereas if this option is |
| | | **true**, the ordering is relative only to |
| | | instances on the same node. |
| | | Allowed values: **false**, **true** |
+-------------------+-----------------+-------------------------------------------------------+
| promotable | false | .. index:: |
| | | single: clone; option, promotable |
| | | single: option; promotable (clone) |
| | | single: promotable; clone option |
| | | |
| | | If **true**, clone instances can perform a |
| | | special role that Pacemaker will manage via the |
| | | resource agent's **promote** and **demote** |
| | | actions. The resource agent must support these |
| | | actions. |
| | | Allowed values: **false**, **true** |
+-------------------+-----------------+-------------------------------------------------------+
| promoted-max | 1 | .. index:: |
| | | single: clone; option, promoted-max |
| | | single: option; promoted-max (clone) |
| | | single: promoted-max; clone option |
| | | |
| | | If ``promotable`` is **true**, the number of |
| | | instances that can be promoted at one time |
| | | across the entire cluster |
+-------------------+-----------------+-------------------------------------------------------+
| promoted-node-max | 1 | .. index:: |
| | | single: clone; option, promoted-node-max |
| | | single: option; promoted-node-max (clone) |
| | | single: promoted-node-max; clone option |
| | | |
| | | If ``promotable`` is **true** and ``globally-unique`` |
| | | is **false**, the number of clone instances can be |
| | | promoted at one time on a single node |
+-------------------+-----------------+-------------------------------------------------------+
.. note:: **Deprecated Terminology**
In older documentation and online examples, you may see promotable clones
referred to as *multi-state*, *stateful*, or *master/slave*; these mean the
same thing as *promotable*. Certain syntax is supported for backward
compatibility, but is deprecated and will be removed in a future version:
* Using a ``master`` tag, instead of a ``clone`` tag with the ``promotable``
meta-attribute set to ``true``
* Using the ``master-max`` meta-attribute instead of ``promoted-max``
* Using the ``master-node-max`` meta-attribute instead of
``promoted-node-max``
* Using ``Master`` as a role name instead of ``Promoted``
* Using ``Slave`` as a role name instead of ``Unpromoted``
Clone Contents
______________
Clones must contain exactly one primitive or group resource.
.. topic:: A clone that runs a web server on all nodes
.. code-block:: xml
<clone id="apache-clone">
<primitive id="apache" class="lsb" type="apache">
<operations>
<op id="apache-monitor" name="monitor" interval="30"/>
</operations>
</primitive>
</clone>
.. warning::
You should never reference the name of a clone's child (the primitive or group
resource being cloned). If you think you need to do this, you probably need to
re-evaluate your design.
Clone Instance Attribute
________________________
Clones have no instance attributes; however, any that are set here will be
inherited by the clone's child.
.. index::
single: clone; constraint
Clone Constraints
_________________
In most cases, a clone will have a single instance on each active cluster
node. If this is not the case, you can indicate which nodes the
cluster should preferentially assign copies to with resource location
constraints. These constraints are written no differently from those
for primitive resources except that the clone's **id** is used.
.. topic:: Some constraints involving clones
.. code-block:: xml
<constraints>
<rsc_location id="clone-prefers-node1" rsc="apache-clone" node="node1" score="500"/>
<rsc_colocation id="stats-with-clone" rsc="apache-stats" with="apache-clone"/>
<rsc_order id="start-clone-then-stats" first="apache-clone" then="apache-stats"/>
</constraints>
Ordering constraints behave slightly differently for clones. In the
example above, ``apache-stats`` will wait until all copies of ``apache-clone``
that need to be started have done so before being started itself.
Only if *no* copies can be started will ``apache-stats`` be prevented
from being active. Additionally, the clone will wait for
``apache-stats`` to be stopped before stopping itself.
Colocation of a primitive or group resource with a clone means that
the resource can run on any node with an active instance of the clone.
The cluster will choose an instance based on where the clone is running and
the resource's own location preferences.
Colocation between clones is also possible. If one clone **A** is colocated
with another clone **B**, the set of allowed locations for **A** is limited to
nodes on which **B** is (or will be) active. Placement is then performed
normally.
.. index::
single: promotable clone; constraint
.. _promotable-clone-constraints:
Promotable Clone Constraints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For promotable clone resources, the ``first-action`` and/or ``then-action`` fields
for ordering constraints may be set to ``promote`` or ``demote`` to constrain the
promoted role, and colocation constraints may contain ``rsc-role`` and/or
``with-rsc-role`` fields.
.. topic:: Constraints involving promotable clone resources
.. code-block:: xml
<constraints>
<rsc_location id="db-prefers-node1" rsc="database" node="node1" score="500"/>
<rsc_colocation id="backup-with-db-unpromoted" rsc="backup"
with-rsc="database" with-rsc-role="Unpromoted"/>
<rsc_colocation id="myapp-with-db-promoted" rsc="myApp"
with-rsc="database" with-rsc-role="Promoted"/>
<rsc_order id="start-db-before-backup" first="database" then="backup"/>
<rsc_order id="promote-db-then-app" first="database" first-action="promote"
then="myApp" then-action="start"/>
</constraints>
In the example above, **myApp** will wait until one of the database
copies has been started and promoted before being started
itself on the same node. Only if no copies can be promoted will **myApp** be
prevented from being active. Additionally, the cluster will wait for
**myApp** to be stopped before demoting the database.
Colocation of a primitive or group resource with a promotable clone
resource means that it can run on any node with an active instance of
the promotable clone resource that has the specified role (``Promoted`` or
``Unpromoted``). In the example above, the cluster will choose a location
based on where database is running in the promoted role, and if there are
multiple promoted instances it will also factor in **myApp**'s own location
preferences when deciding which location to choose.
Colocation with regular clones and other promotable clone resources is also
possible. In such cases, the set of allowed locations for the **rsc**
clone is (after role filtering) limited to nodes on which the
``with-rsc`` promotable clone resource is (or will be) in the specified role.
Placement is then performed as normal.
Using Promotable Clone Resources in Colocation Sets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a promotable clone is used in a :ref:`resource set <s-resource-sets>`
inside a colocation constraint, the resource set may take a ``role`` attribute.
In the following example, an instance of **B** may be promoted only on a node
where **A** is in the promoted role. Additionally, resources **C** and **D**
must be located on a node where both **A** and **B** are promoted.
.. topic:: Colocate C and D with A's and B's promoted instances
.. code-block:: xml
<constraints>
<rsc_colocation id="coloc-1" score="INFINITY" >
<resource_set id="colocated-set-example-1" sequential="true" role="Promoted">
<resource_ref id="A"/>
<resource_ref id="B"/>
</resource_set>
<resource_set id="colocated-set-example-2" sequential="true">
<resource_ref id="C"/>
<resource_ref id="D"/>
</resource_set>
</rsc_colocation>
</constraints>
Using Promotable Clone Resources in Ordered Sets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a promotable clone is used in a :ref:`resource set <s-resource-sets>`
inside an ordering constraint, the resource set may take an ``action``
attribute.
.. topic:: Start C and D after first promoting A and B
.. code-block:: xml
<constraints>
<rsc_order id="order-1" score="INFINITY" >
<resource_set id="ordered-set-1" sequential="true" action="promote">
<resource_ref id="A"/>
<resource_ref id="B"/>
</resource_set>
<resource_set id="ordered-set-2" sequential="true" action="start">
<resource_ref id="C"/>
<resource_ref id="D"/>
</resource_set>
</rsc_order>
</constraints>
In the above example, **B** cannot be promoted until **A** has been promoted.
Additionally, resources **C** and **D** must wait until **A** and **B** have
been promoted before they can start.
.. index::
pair: resource-stickiness; clone
.. _s-clone-stickiness:
Clone Stickiness
________________
To achieve stable assignments, clones are slightly sticky by default. If no
value for ``resource-stickiness`` is provided, the clone will use a value of 1.
Being a small value, it causes minimal disturbance to the score calculations of
other resources but is enough to prevent Pacemaker from needlessly moving
instances around the cluster.
.. note::
For globally unique clones, this may result in multiple instances of the
clone staying on a single node, even after another eligible node becomes
active (for example, after being put into standby mode then made active again).
If you do not want this behavior, specify a ``resource-stickiness`` of 0
for the clone temporarily and let the cluster adjust, then set it back
to 1 if you want the default behavior to apply again.
.. important::
If ``resource-stickiness`` is set in the ``rsc_defaults`` section, it will
apply to clone instances as well. This means an explicit ``resource-stickiness``
of 0 in ``rsc_defaults`` works differently from the implicit default used when
``resource-stickiness`` is not specified.
-
-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 only respond with ``${OCF_SUCCESS}`` 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, e.g. **apache:2**.
-
-Resource agents 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 will not always be an unbroken
-sequence, nor 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 come up 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.
-
-.. table:: **Role implications of OCF return codes**
- :widths: 1 3
-
- +----------------------+--------------------------------------------------+
- | Monitor Return Code | Description |
- +======================+==================================================+
- | OCF_NOT_RUNNING | .. index:: |
- | | single: OCF_NOT_RUNNING |
- | | single: OCF return code; OCF_NOT_RUNNING |
- | | |
- | | Stopped |
- +----------------------+--------------------------------------------------+
- | OCF_SUCCESS | .. index:: |
- | | single: OCF_SUCCESS |
- | | single: OCF return code; OCF_SUCCESS |
- | | |
- | | Running (Unpromoted) |
- +----------------------+--------------------------------------------------+
- | OCF_RUNNING_PROMOTED | .. index:: |
- | | single: OCF_RUNNING_PROMOTED |
- | | single: OCF return code; OCF_RUNNING_PROMOTED |
- | | |
- | | Running (Promoted) |
- +----------------------+--------------------------------------------------+
- | OCF_FAILED_PROMOTED | .. index:: |
- | | single: OCF_FAILED_PROMOTED |
- | | single: OCF return code; OCF_FAILED_PROMOTED |
- | | |
- | | Failed (Promoted) |
- +----------------------+--------------------------------------------------+
- | Other | .. index:: |
- | | single: return code |
- | | |
- | | Failed (Unpromoted) |
- +----------------------+--------------------------------------------------+
-
-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 which, 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
-
-.. table:: **Environment variables supplied with Clone notify actions**
- :widths: 1 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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
-
-.. table:: **Extra environment variables supplied for promotable clones**
- :widths: 1 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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 |
- | | |
- | | 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``
-
Monitoring Promotable Clone Resources
_____________________________________
The usual monitor actions are insufficient to monitor a promotable clone
resource, because Pacemaker needs to verify not only that the resource is
active, but also that its actual role matches its intended one.
Define two monitoring actions: the usual one will cover the unpromoted role,
and an additional one with ``role="Promoted"`` will cover the promoted role.
.. topic:: Monitoring both states of a promotable clone resource
.. code-block:: xml
<clone id="myPromotableRsc">
<meta_attributes id="myPromotableRsc-meta">
<nvpair name="promotable" value="true"/>
</meta_attributes>
<primitive id="myRsc" class="ocf" type="myApp" provider="myCorp">
<operations>
<op id="public-ip-unpromoted-check" name="monitor" interval="60"/>
<op id="public-ip-promoted-check" name="monitor" interval="61" role="Promoted"/>
</operations>
</primitive>
</clone>
.. important::
It is crucial that *every* monitor operation has a different interval!
Pacemaker currently differentiates between operations
only by resource and interval; so if (for example) a promotable clone resource
had the same monitor interval for both roles, Pacemaker would ignore the
role when checking the status -- which would cause unexpected return
codes, and therefore unnecessary complications.
.. _s-promotion-scores:
Determining Which Instance is Promoted
______________________________________
Pacemaker can choose a promotable clone instance to be promoted in one of two
ways:
* Promotion scores: These are node attributes set via the ``crm_attribute``
command using the ``--promotion`` option, which generally would be called by
the resource agent's start action if it supports promotable clones. This tool
automatically detects both the resource and host, and should be used to set a
preference for being promoted. Based on this, ``promoted-max``, and
``promoted-node-max``, the instance(s) with the highest preference will be
promoted.
* Constraints: Location constraints can indicate which nodes are most preferred
to be promoted.
.. topic:: Explicitly preferring node1 to be promoted
.. code-block:: xml
<rsc_location id="promoted-location" rsc="myPromotableRsc">
<rule id="promoted-rule" score="100" role="Promoted">
<expression id="promoted-exp" attribute="#uname" operation="eq" value="node1"/>
</rule>
</rsc_location>
.. index:
single: bundle
single: resource; bundle
pair: container; Docker
pair: container; podman
pair: container; rkt
.. _s-resource-bundle:
Bundles - Containerized Resources
#################################
Pacemaker supports a special syntax for launching a service inside a
`container <https://en.wikipedia.org/wiki/Operating-system-level_virtualization>`_
with any infrastructure it requires: the *bundle*.
Pacemaker bundles support `Docker <https://www.docker.com/>`_,
`podman <https://podman.io/>`_ *(since 2.0.1)*, and
`rkt <https://coreos.com/rkt/>`_ container technologies. [#]_
.. topic:: A bundle for a containerized web server
.. code-block:: xml
<bundle id="httpd-bundle">
<podman image="pcmk:http" replicas="3"/>
<network ip-range-start="192.168.122.131"
host-netmask="24"
host-interface="eth0">
<port-mapping id="httpd-port" port="80"/>
</network>
<storage>
<storage-mapping id="httpd-syslog"
source-dir="/dev/log"
target-dir="/dev/log"
options="rw"/>
<storage-mapping id="httpd-root"
source-dir="/srv/html"
target-dir="/var/www/html"
options="rw,Z"/>
<storage-mapping id="httpd-logs"
source-dir-root="/var/log/pacemaker/bundles"
target-dir="/etc/httpd/logs"
options="rw,Z"/>
</storage>
<primitive class="ocf" id="httpd" provider="heartbeat" type="apache"/>
</bundle>
Bundle Prerequisites
____________________
Before configuring a bundle in Pacemaker, the user must install the appropriate
container launch technology (Docker, podman, or rkt), and supply a fully
configured container image, on every node allowed to run the bundle.
Pacemaker will create an implicit resource of type **ocf:heartbeat:docker**,
**ocf:heartbeat:podman**, or **ocf:heartbeat:rkt** to manage a bundle's
container. The user must ensure that the appropriate resource agent is
installed on every node allowed to run the bundle.
.. index::
pair: XML element; bundle
Bundle Properties
_________________
.. table:: **XML Attributes of a bundle Element**
:widths: 1 4
+-------------+------------------------------------------------------------------+
| Field | Description |
+=============+==================================================================+
| id | .. index:: |
| | single: bundle; attribute, id |
| | single: attribute; id (bundle) |
| | single: id; bundle attribute |
| | |
| | A unique name for the bundle (required) |
+-------------+------------------------------------------------------------------+
| description | .. index:: |
| | single: bundle; attribute, description |
| | single: attribute; description (bundle) |
| | single: description; bundle attribute |
| | |
| | An optional description of the group, for the user's own |
| | purposes. |
| | E.g. ``manages the container that runs the service`` |
+-------------+------------------------------------------------------------------+
A bundle must contain exactly one ``docker``, ``podman``, or ``rkt`` element.
.. index::
pair: XML element; docker
pair: XML element; podman
pair: XML element; rkt
Bundle Container Properties
___________________________
.. table:: **XML attributes of a docker, podman, or rkt Element**
:class: longtable
:widths: 2 3 4
+-------------------+------------------------------------+---------------------------------------------------+
| Attribute | Default | Description |
+===================+====================================+===================================================+
| image | | .. index:: |
| | | single: docker; attribute, image |
| | | single: attribute; image (docker) |
| | | single: image; docker attribute |
| | | single: podman; attribute, image |
| | | single: attribute; image (podman) |
| | | single: image; podman attribute |
| | | single: rkt; attribute, image |
| | | single: attribute; image (rkt) |
| | | single: image; rkt attribute |
| | | |
| | | Container image tag (required) |
+-------------------+------------------------------------+---------------------------------------------------+
| replicas | Value of ``promoted-max`` | .. index:: |
| | if that is positive, else 1 | single: docker; attribute, replicas |
| | | single: attribute; replicas (docker) |
| | | single: replicas; docker attribute |
| | | single: podman; attribute, replicas |
| | | single: attribute; replicas (podman) |
| | | single: replicas; podman attribute |
| | | single: rkt; attribute, replicas |
| | | single: attribute; replicas (rkt) |
| | | single: replicas; rkt attribute |
| | | |
| | | A positive integer specifying the number of |
| | | container instances to launch |
+-------------------+------------------------------------+---------------------------------------------------+
| replicas-per-host | 1 | .. index:: |
| | | single: docker; attribute, replicas-per-host |
| | | single: attribute; replicas-per-host (docker) |
| | | single: replicas-per-host; docker attribute |
| | | single: podman; attribute, replicas-per-host |
| | | single: attribute; replicas-per-host (podman) |
| | | single: replicas-per-host; podman attribute |
| | | single: rkt; attribute, replicas-per-host |
| | | single: attribute; replicas-per-host (rkt) |
| | | single: replicas-per-host; rkt attribute |
| | | |
| | | A positive integer specifying the number of |
| | | container instances allowed to run on a |
| | | single node |
+-------------------+------------------------------------+---------------------------------------------------+
| promoted-max | 0 | .. index:: |
| | | single: docker; attribute, promoted-max |
| | | single: attribute; promoted-max (docker) |
| | | single: promoted-max; docker attribute |
| | | single: podman; attribute, promoted-max |
| | | single: attribute; promoted-max (podman) |
| | | single: promoted-max; podman attribute |
| | | single: rkt; attribute, promoted-max |
| | | single: attribute; promoted-max (rkt) |
| | | single: promoted-max; rkt attribute |
| | | |
| | | A non-negative integer that, if positive, |
| | | indicates that the containerized service |
| | | should be treated as a promotable service, |
| | | with this many replicas allowed to run the |
| | | service in the promoted role |
+-------------------+------------------------------------+---------------------------------------------------+
| network | | .. index:: |
| | | single: docker; attribute, network |
| | | single: attribute; network (docker) |
| | | single: network; docker attribute |
| | | single: podman; attribute, network |
| | | single: attribute; network (podman) |
| | | single: network; podman attribute |
| | | single: rkt; attribute, network |
| | | single: attribute; network (rkt) |
| | | single: network; rkt attribute |
| | | |
| | | If specified, this will be passed to the |
| | | ``docker run``, ``podman run``, or |
| | | ``rkt run`` command as the network setting |
| | | for the container. |
+-------------------+------------------------------------+---------------------------------------------------+
| run-command | ``/usr/sbin/pacemaker-remoted`` if | .. index:: |
| | bundle contains a **primitive**, | single: docker; attribute, run-command |
| | otherwise none | single: attribute; run-command (docker) |
| | | single: run-command; docker attribute |
| | | single: podman; attribute, run-command |
| | | single: attribute; run-command (podman) |
| | | single: run-command; podman attribute |
| | | single: rkt; attribute, run-command |
| | | single: attribute; run-command (rkt) |
| | | single: run-command; rkt attribute |
| | | |
| | | This command will be run inside the container |
| | | when launching it ("PID 1"). If the bundle |
| | | contains a **primitive**, this command *must* |
| | | start ``pacemaker-remoted`` (but could, for |
| | | example, be a script that does other stuff, too). |
+-------------------+------------------------------------+---------------------------------------------------+
| options | | .. index:: |
| | | single: docker; attribute, options |
| | | single: attribute; options (docker) |
| | | single: options; docker attribute |
| | | single: podman; attribute, options |
| | | single: attribute; options (podman) |
| | | single: options; podman attribute |
| | | single: rkt; attribute, options |
| | | single: attribute; options (rkt) |
| | | single: options; rkt attribute |
| | | |
| | | Extra command-line options to pass to the |
| | | ``docker run``, ``podman run``, or ``rkt run`` |
| | | command |
+-------------------+------------------------------------+---------------------------------------------------+
.. note::
Considerations when using cluster configurations or container images from
Pacemaker 1.1:
* If the container image has a pre-2.0.0 version of Pacemaker, set ``run-command``
to ``/usr/sbin/pacemaker_remoted`` (note the underbar instead of dash).
* ``masters`` is accepted as an alias for ``promoted-max``, but is deprecated since
2.0.0, and support for it will be removed in a future version.
Bundle Network Properties
_________________________
A bundle may optionally contain one ``<network>`` element.
.. index::
pair: XML element; network
single: bundle; network
.. table:: **XML attributes of a network Element**
:widths: 2 1 5
+----------------+---------+------------------------------------------------------------+
| Attribute | Default | Description |
+================+=========+============================================================+
| add-host | TRUE | .. index:: |
| | | single: network; attribute, add-host |
| | | single: attribute; add-host (network) |
| | | single: add-host; network attribute |
| | | |
| | | If TRUE, and ``ip-range-start`` is used, Pacemaker will |
| | | automatically ensure that ``/etc/hosts`` inside the |
| | | containers has entries for each |
| | | :ref:`replica name <s-resource-bundle-note-replica-names>` |
| | | and its assigned IP. |
+----------------+---------+------------------------------------------------------------+
| ip-range-start | | .. index:: |
| | | single: network; attribute, ip-range-start |
| | | single: attribute; ip-range-start (network) |
| | | single: ip-range-start; network attribute |
| | | |
| | | If specified, Pacemaker will create an implicit |
| | | ``ocf:heartbeat:IPaddr2`` resource for each container |
| | | instance, starting with this IP address, using up to |
| | | ``replicas`` sequential addresses. These addresses can be |
| | | used from the host's network to reach the service inside |
| | | the container, though it is not visible within the |
| | | container itself. Only IPv4 addresses are currently |
| | | supported. |
+----------------+---------+------------------------------------------------------------+
| host-netmask | 32 | .. index:: |
| | | single: network; attribute; host-netmask |
| | | single: attribute; host-netmask (network) |
| | | single: host-netmask; network attribute |
| | | |
| | | If ``ip-range-start`` is specified, the IP addresses |
| | | are created with this CIDR netmask (as a number of bits). |
+----------------+---------+------------------------------------------------------------+
| host-interface | | .. index:: |
| | | single: network; attribute; host-interface |
| | | single: attribute; host-interface (network) |
| | | single: host-interface; network attribute |
| | | |
| | | If ``ip-range-start`` is specified, the IP addresses are |
| | | created on this host interface (by default, it will be |
| | | determined from the IP address). |
+----------------+---------+------------------------------------------------------------+
| control-port | 3121 | .. index:: |
| | | single: network; attribute; control-port |
| | | single: attribute; control-port (network) |
| | | single: control-port; network attribute |
| | | |
| | | If the bundle contains a ``primitive``, the cluster will |
| | | use this integer TCP port for communication with |
| | | Pacemaker Remote inside the container. Changing this is |
| | | useful when the container is unable to listen on the |
| | | default port, for example, when the container uses the |
| | | host's network rather than ``ip-range-start`` (in which |
| | | case ``replicas-per-host`` must be 1), or when the bundle |
| | | may run on a Pacemaker Remote node that is already |
| | | listening on the default port. Any ``PCMK_remote_port`` |
| | | environment variable set on the host or in the container |
| | | is ignored for bundle connections. |
+----------------+---------+------------------------------------------------------------+
.. _s-resource-bundle-note-replica-names:
.. note::
Replicas are named by the bundle id plus a dash and an integer counter starting
with zero. For example, if a bundle named **httpd-bundle** has **replicas=2**, its
containers will be named **httpd-bundle-0** and **httpd-bundle-1**.
.. index::
pair: XML element; port-mapping
Additionally, a ``network`` element may optionally contain one or more
``port-mapping`` elements.
.. table:: **Attributes of a port-mapping Element**
:widths: 2 1 5
+---------------+-------------------+------------------------------------------------------+
| Attribute | Default | Description |
+===============+===================+======================================================+
| id | | .. index:: |
| | | single: port-mapping; attribute, id |
| | | single: attribute; id (port-mapping) |
| | | single: id; port-mapping attribute |
| | | |
| | | A unique name for the port mapping (required) |
+---------------+-------------------+------------------------------------------------------+
| port | | .. index:: |
| | | single: port-mapping; attribute, port |
| | | single: attribute; port (port-mapping) |
| | | single: port; port-mapping attribute |
| | | |
| | | If this is specified, connections to this TCP port |
| | | number on the host network (on the container's |
| | | assigned IP address, if ``ip-range-start`` is |
| | | specified) will be forwarded to the container |
| | | network. Exactly one of ``port`` or ``range`` |
| | | must be specified in a ``port-mapping``. |
+---------------+-------------------+------------------------------------------------------+
| internal-port | value of ``port`` | .. index:: |
| | | single: port-mapping; attribute, internal-port |
| | | single: attribute; internal-port (port-mapping) |
| | | single: internal-port; port-mapping attribute |
| | | |
| | | If ``port`` and this are specified, connections |
| | | to ``port`` on the host's network will be |
| | | forwarded to this port on the container network. |
+---------------+-------------------+------------------------------------------------------+
| range | | .. index:: |
| | | single: port-mapping; attribute, range |
| | | single: attribute; range (port-mapping) |
| | | single: range; port-mapping attribute |
| | | |
| | | If this is specified, connections to these TCP |
| | | port numbers (expressed as *first_port*-*last_port*) |
| | | on the host network (on the container's assigned IP |
| | | address, if ``ip-range-start`` is specified) will |
| | | be forwarded to the same ports in the container |
| | | network. Exactly one of ``port`` or ``range`` |
| | | must be specified in a ``port-mapping``. |
+---------------+-------------------+------------------------------------------------------+
.. note::
If the bundle contains a ``primitive``, Pacemaker will automatically map the
``control-port``, so it is not necessary to specify that port in a
``port-mapping``.
.. index:
pair: XML element; storage
pair: XML element; storage-mapping
single: bundle; storage
.. _s-bundle-storage:
Bundle Storage Properties
_________________________
A bundle may optionally contain one ``storage`` element. A ``storage`` element
has no properties of its own, but may contain one or more ``storage-mapping``
elements.
.. table:: **Attributes of a storage-mapping Element**
:widths: 2 1 5
+-----------------+---------+-------------------------------------------------------------+
| Attribute | Default | Description |
+=================+=========+=============================================================+
| id | | .. index:: |
| | | single: storage-mapping; attribute, id |
| | | single: attribute; id (storage-mapping) |
| | | single: id; storage-mapping attribute |
| | | |
| | | A unique name for the storage mapping (required) |
+-----------------+---------+-------------------------------------------------------------+
| source-dir | | .. index:: |
| | | single: storage-mapping; attribute, source-dir |
| | | single: attribute; source-dir (storage-mapping) |
| | | single: source-dir; storage-mapping attribute |
| | | |
| | | The absolute path on the host's filesystem that will be |
| | | mapped into the container. Exactly one of ``source-dir`` |
| | | and ``source-dir-root`` must be specified in a |
| | | ``storage-mapping``. |
+-----------------+---------+-------------------------------------------------------------+
| source-dir-root | | .. index:: |
| | | single: storage-mapping; attribute, source-dir-root |
| | | single: attribute; source-dir-root (storage-mapping) |
| | | single: source-dir-root; storage-mapping attribute |
| | | |
| | | The start of a path on the host's filesystem that will |
| | | be mapped into the container, using a different |
| | | subdirectory on the host for each container instance. |
| | | The subdirectory will be named the same as the |
| | | :ref:`replica name <s-resource-bundle-note-replica-names>`. |
| | | Exactly one of ``source-dir`` and ``source-dir-root`` |
| | | must be specified in a ``storage-mapping``. |
+-----------------+---------+-------------------------------------------------------------+
| target-dir | | .. index:: |
| | | single: storage-mapping; attribute, target-dir |
| | | single: attribute; target-dir (storage-mapping) |
| | | single: target-dir; storage-mapping attribute |
| | | |
| | | The path name within the container where the host |
| | | storage will be mapped (required) |
+-----------------+---------+-------------------------------------------------------------+
| options | | .. index:: |
| | | single: storage-mapping; attribute, options |
| | | single: attribute; options (storage-mapping) |
| | | single: options; storage-mapping attribute |
| | | |
| | | A comma-separated list of file system mount |
| | | options to use when mapping the storage |
+-----------------+---------+-------------------------------------------------------------+
.. note::
Pacemaker does not define the behavior if the source directory does not already
exist on the host. However, it is expected that the container technology and/or
its resource agent will create the source directory in that case.
.. note::
If the bundle contains a ``primitive``,
Pacemaker will automatically map the equivalent of
``source-dir=/etc/pacemaker/authkey target-dir=/etc/pacemaker/authkey``
and ``source-dir-root=/var/log/pacemaker/bundles target-dir=/var/log`` into the
container, so it is not necessary to specify those paths in a
``storage-mapping``.
.. important::
The ``PCMK_authkey_location`` environment variable must not be set to anything
other than the default of ``/etc/pacemaker/authkey`` on any node in the cluster.
.. important::
If SELinux is used in enforcing mode on the host, you must ensure the container
is allowed to use any storage you mount into it. For Docker and podman bundles,
adding "Z" to the mount options will create a container-specific label for the
mount that allows the container access.
.. index::
single: bundle; primitive
Bundle Primitive
________________
A bundle may optionally contain one :ref:`primitive <primitive-resource>`
resource. The primitive may have operations, instance attributes, and
meta-attributes defined, as usual.
If a bundle contains a primitive resource, the container image must include
the Pacemaker Remote daemon, and at least one of ``ip-range-start`` or
``control-port`` must be configured in the bundle. Pacemaker will create an
implicit **ocf:pacemaker:remote** resource for the connection, launch
Pacemaker Remote within the container, and monitor and manage the primitive
resource via Pacemaker Remote.
If the bundle has more than one container instance (replica), the primitive
resource will function as an implicit :ref:`clone <s-resource-clone>` -- a
:ref:`promotable clone <s-resource-promotable>` if the bundle has ``promoted-max``
greater than zero.
.. note::
If you want to pass environment variables to a bundle's Pacemaker Remote
connection or primitive, you have two options:
* Environment variables whose value is the same regardless of the underlying host
may be set using the container element's ``options`` attribute.
* If you want variables to have host-specific values, you can use the
:ref:`storage-mapping <s-bundle-storage>` element to map a file on the host as
``/etc/pacemaker/pcmk-init.env`` in the container *(since 2.0.3)*.
Pacemaker Remote will parse this file as a shell-like format, with
variables set as NAME=VALUE, ignoring blank lines and comments starting
with "#".
.. important::
When a bundle has a ``primitive``, Pacemaker on all cluster nodes must be able to
contact Pacemaker Remote inside the bundle's containers.
* The containers must have an accessible network (for example, ``network`` should
not be set to "none" with a ``primitive``).
* The default, using a distinct network space inside the container, works in
combination with ``ip-range-start``. Any firewall must allow access from all
cluster nodes to the ``control-port`` on the container IPs.
* If the container shares the host's network space (for example, by setting
``network`` to "host"), a unique ``control-port`` should be specified for each
bundle. Any firewall must allow access from all cluster nodes to the
``control-port`` on all cluster and remote node IPs.
.. index::
single: bundle; node attributes
.. _s-bundle-attributes:
Bundle Node Attributes
______________________
If the bundle has a ``primitive``, the primitive's resource agent may want to set
node attributes such as :ref:`promotion scores <s-promotion-scores>`. However, with
containers, it is not apparent which node should get the attribute.
If the container uses shared storage that is the same no matter which node the
container is hosted on, then it is appropriate to use the promotion score on the
bundle node itself.
On the other hand, if the container uses storage exported from the underlying host,
then it may be more appropriate to use the promotion score on the underlying host.
Since this depends on the particular situation, the
``container-attribute-target`` resource meta-attribute allows the user to specify
which approach to use. If it is set to ``host``, then user-defined node attributes
will be checked on the underlying host. If it is anything else, the local node
(in this case the bundle node) is used as usual.
This only applies to user-defined attributes; the cluster will always check the
local node for cluster-defined attributes such as ``#uname``.
If ``container-attribute-target`` is ``host``, the cluster will pass additional
environment variables to the primitive's resource agent that allow it to set
node attributes appropriately: ``CRM_meta_container_attribute_target`` (identical
to the meta-attribute value) and ``CRM_meta_physical_host`` (the name of the
underlying host).
.. note::
When called by a resource agent, the ``attrd_updater`` and ``crm_attribute``
commands will automatically check those environment variables and set
attributes appropriately.
.. index::
single: bundle; meta-attributes
Bundle Meta-Attributes
______________________
Any meta-attribute set on a bundle will be inherited by the bundle's
primitive and any resources implicitly created by Pacemaker for the bundle.
This includes options such as ``priority``, ``target-role``, and ``is-managed``. See
:ref:`resource_options` for more information.
Bundles support clone meta-attributes including ``notify``, ``ordered``, and
``interleave``.
Limitations of Bundles
______________________
Restarting pacemaker while a bundle is unmanaged or the cluster is in
maintenance mode may cause the bundle to fail.
Bundles may not be explicitly cloned or included in groups. This includes the
bundle's primitive and any resources implicitly created by Pacemaker for the
bundle. (If ``replicas`` is greater than 1, the bundle will behave like a clone
implicitly.)
Bundles do not have instance attributes, utilization attributes, or operations,
though a bundle's primitive may have them.
A bundle with a primitive can run on a Pacemaker Remote node only if the bundle
uses a distinct ``control-port``.
.. [#] Of course, the service must support running multiple instances.
.. [#] Docker is a trademark of Docker, Inc. No endorsement by or association with
Docker, Inc. is implied.
diff --git a/doc/sphinx/Pacemaker_Explained/local-options.rst b/doc/sphinx/Pacemaker_Explained/local-options.rst
index 1182562478..b95051777f 100644
--- a/doc/sphinx/Pacemaker_Explained/local-options.rst
+++ b/doc/sphinx/Pacemaker_Explained/local-options.rst
@@ -1,527 +1,568 @@
Host-Local Configuration
------------------------
.. index::
pair: XML element; configuration
.. note:: Directory and file paths below may differ on your system depending on
your Pacemaker build settings. Check your Pacemaker configuration
file to find the correct paths.
Pacemaker supports several host-local configuration options. These options can
be configured on each node in the main Pacemaker configuration file
(|PCMK_CONFIG_FILE|) in the format ``<NAME>="<VALUE>"``. They work by setting
environment variables when Pacemaker daemons start up.
.. list-table:: **Local Options**
:class: longtable
:widths: 2 2 2 5
:header-rows: 1
* - Name
- Type
- Default
- Description
+
+ * - .. _cib_pam_service:
+
+ .. index::
+ pair: node option; CIB_pam_service
+
+ CIB_pam_service
+ - :ref:`text <text>`
+ - login
+ - PAM service to use for remote CIB client authentication (passed to
+ ``pam_start``).
+
* - .. _pcmk_logfacility:
.. index::
pair: node option; PCMK_logfacility
PCMK_logfacility
- :ref:`enumeration <enumeration>`
- daemon
- Enable logging via the system log or journal, using the specified log
facility. Messages sent here are of value to all Pacemaker
administrators. This can be disabled using ``none``, but that is not
recommended. Allowed values:
* ``none``
* ``daemon``
* ``user``
* ``local0``
* ``local1``
* ``local2``
* ``local3``
* ``local4``
* ``local5``
* ``local6``
* ``local7``
* - .. _pcmk_logpriority:
.. index::
pair:: node option; PCMK_logpriority
PCMK_logpriority
- :ref:`enumeration <enumeration>`
- notice
- Unless system logging is disabled using ``PCMK_logfacility=none``,
messages of the specified log severity and higher will be sent to the
system log. The default is appropriate for most installations. Allowed
values:
* ``emerg``
* ``alert``
* ``crit``
* ``error``
* ``warning``
* ``notice``
* ``info``
* ``debug``
* - .. _pcmk_logfile:
.. index::
pair:: node option; PCMK_logfile
PCMK_logfile
- :ref:`text <text>`
- |PCMK_LOG_FILE|
- Unless set to ``none``, more detailed log messages will be sent to the
specified file (in addition to the system log, if enabled). These
messages may have extended information, and will include messages of info
severity. This log is of more use to developers and advanced system
- administrators, and when reporting problems.
+ administrators, and when reporting problems. Note: The default is
+ |PCMK_CONTAINER_LOG_FILE| (inside the container) for bundled container
+ nodes; this would typically be mapped to a different path on the host
+ running the container.
* - .. _pcmk_logfile_mode:
.. index::
pair:: node option; PCMK_logfile_mode
PCMK_logfile_mode
- :ref:`text <text>`
- 0660
- Pacemaker will set the permissions on the detail log to this value (see
``chmod(1)``).
* - .. _pcmk_debug:
.. index::
pair:: node option; PCMK_debug
PCMK_debug
- :ref:`enumeration <enumeration>`
- no
- Whether to send debug severity messages to the detail log. This may be
set for all subsystems (``yes`` or ``no``) or for specific (comma-
separated) subsystems. Allowed subsystems are:
* ``pacemakerd``
* ``pacemaker-attrd``
* ``pacemaker-based``
* ``pacemaker-controld``
* ``pacemaker-execd``
* ``pacemaker-fenced``
* ``pacemaker-schedulerd``
Example: ``PCMK_debug="pacemakerd,pacemaker-execd"``
* - .. _pcmk_stderr:
.. index::
pair:: node option; PCMK_stderr
PCMK_stderr
- :ref:`boolean <boolean>`
- no
- *Advanced Use Only:* Whether to send daemon log messages to stderr. This
would be useful only during troubleshooting, when starting Pacemaker
manually on the command line.
Setting this option in the configuration file is pointless, since the
file is not read when starting Pacemaker manually. However, it can be set
directly as an environment variable on the command line.
* - .. _pcmk_trace_functions:
.. index::
pair:: node option; PCMK_trace_functions
PCMK_trace_functions
- :ref:`text <text>`
-
- *Advanced Use Only:* Send debug and trace severity messages from these
(comma-separated) source code functions to the detail log.
Example:
``PCMK_trace_functions="func1,func2"``
* - .. _pcmk_trace_files:
.. index::
pair:: node option; PCMK_trace_files
PCMK_trace_files
- :ref:`text <text>`
-
- *Advanced Use Only:* Send debug and trace severity messages from all
functions in these (comma-separated) source file names to the detail log.
Example: ``PCMK_trace_files="file1.c,file2.c"``
* - .. _pcmk_trace_formats:
.. index::
pair:: node option; PCMK_trace_formats
PCMK_trace_formats
- :ref:`text <text>`
-
- *Advanced Use Only:* Send trace severity messages that are generated by
these (comma-separated) format strings in the source code to the detail
log.
Example: ``PCMK_trace_formats="Error: %s (%d)"``
* - .. _pcmk_trace_tags:
.. index::
pair:: node option; PCMK_trace_tags
PCMK_trace_tags
- :ref:`text <text>`
-
- *Advanced Use Only:* Send debug and trace severity messages related to
these (comma-separated) resource IDs to the detail log.
Example: ``PCMK_trace_tags="client-ip,dbfs"``
* - .. _pcmk_blackbox:
.. index::
pair:: node option; PCMK_blackbox
PCMK_blackbox
- :ref:`enumeration <enumeration>`
- no
- *Advanced Use Only:* Enable blackbox logging globally (``yes`` or ``no``)
or by subsystem. A blackbox contains a rolling buffer of all logs (of all
severities). Blackboxes are stored under |CRM_BLACKBOX_DIR| by default,
by default, and their contents can be viewed using the ``qb-blackbox(8)``
command.
The blackbox recorder can be enabled at start using this variable, or at
runtime by sending a Pacemaker subsystem daemon process a ``SIGUSR1`` or
``SIGTRAP`` signal, and disabled by sending ``SIGUSR2`` (see
``kill(1)``). The blackbox will be written after a crash, assertion
failure, or ``SIGTRAP`` signal.
See :ref:`PCMK_debug <pcmk_debug>` for allowed subsystems.
Example:
``PCMK_blackbox="pacemakerd,pacemaker-execd"``
* - .. _pcmk_trace_blackbox:
.. index::
pair:: node option; PCMK_trace_blackbox
PCMK_trace_blackbox
- :ref:`enumeration <enumeration>`
-
- *Advanced Use Only:* Write a blackbox whenever the message at the
specified function and line is logged. Multiple entries may be comma-
separated.
Example: ``PCMK_trace_blackbox="remote.c:144,remote.c:149"``
* - .. _pcmk_node_start_state:
.. index::
pair:: node option; PCMK_node_start_state
PCMK_node_start_state
- :ref:`enumeration <enumeration>`
- default
- By default, the local host will join the cluster in an online or standby
state when Pacemaker first starts depending on whether it was previously
put into standby mode. If this variable is set to ``standby`` or
``online``, it will force the local host to join in the specified state.
* - .. _pcmk_node_action_limit:
.. index::
pair:: node option; PCMK_node_action_limit
PCMK_node_action_limit
- :ref:`nonnegative integer <nonnegative_integer>`
-
- Specify the maximum number of jobs that can be scheduled on this node. If
set, this overrides the ``node-action-limit`` cluster property for this
node.
* - .. _pcmk_shutdown_delay:
.. index::
pair:: node option; PCMK_shutdown_delay
PCMK_shutdown_delay
- :ref:`timeout <timeout>`
-
- Specify a delay before shutting down ``pacemakerd`` after shutting down
all other Pacemaker daemons.
* - .. _pcmk_fail_fast:
.. index::
pair:: node option; PCMK_fail_fast
PCMK_fail_fast
- :ref:`boolean <boolean>`
- no
- By default, if a Pacemaker subsystem crashes, the main ``pacemakerd``
process will attempt to restart it. If this variable is set to ``yes``,
``pacemakerd`` will panic the local host instead.
* - .. _pcmk_panic_action:
.. index::
pair:: node option; PCMK_panic_action
PCMK_panic_action
- :ref:`enumeration <enumeration>`
- reboot
- Pacemaker will panic the local host under certain conditions. By default,
this means rebooting the host. This variable can change that behavior: if
``crash``, trigger a kernel crash (useful if you want a kernel dump to
investigate); if ``sync-reboot`` or ``sync-crash``, synchronize
filesystems before rebooting the host or triggering a kernel crash. The
sync values are more likely to preserve log messages, but with the risk
that the host may be left active if the synchronization hangs.
* - .. _pcmk_authkey_location:
.. index::
pair:: node option; PCMK_authkey_location
PCMK_authkey_location
- :ref:`text <text>`
- |PCMK_AUTHKEY_FILE|
- Use the contents of this file as the authorization key to use with
Pacemaker Remote connections. This file must be readable by Pacemaker
daemons (that is, it must allow read permissions to either the
|CRM_DAEMON_USER| user or the |CRM_DAEMON_GROUP| group), and its contents
must be identical on all nodes.
* - .. _pcmk_remote_address:
.. index::
pair:: node option; PCMK_remote_address
PCMK_remote_address
- :ref:`text <text>`
-
- By default, if the Pacemaker Remote service is run on the local node, it
will listen for connections on all IP addresses. This may be set to one
address to listen on instead, as a resolvable hostname or as a numeric
IPv4 or IPv6 address. When resolving names or listening on all addresses,
IPv6 will be preferred if available. When listening on an IPv6 address,
IPv4 clients will be supported via IPv4-mapped IPv6 addresses.
Example: ``PCMK_remote_address="192.0.2.1"``
* - .. _pcmk_remote_port:
.. index::
pair:: node option; PCMK_remote_port
PCMK_remote_port
- :ref:`port <port>`
- 3121
- Use this TCP port number for Pacemaker Remote node connections. This
value must be the same on all nodes.
* - .. _pcmk_remote_pid1:
.. index::
pair:: node option; PCMK_remote_pid1
PCMK_remote_pid1
- :ref:`enumeration <enumeration>`
- default
- *Advanced Use Only:* When a bundle resource's ``run-command`` option is
left to default, Pacemaker Remote runs as PID 1 in the bundle's
containers. When it does so, it loads environment variables from the
container's |PCMK_INIT_ENV_FILE| and performs the PID 1 responsibility of
reaping dead subprocesses.
This option controls whether those actions are performed when Pacemaker
Remote is not running as PID 1. It is intended primarily for developer
testing but can be useful when ``run-command`` is set to a separate,
custom PID 1 process that launches Pacemaker Remote.
* ``full``: Pacemaker Remote loads environment variables from
|PCMK_INIT_ENV_FILE| and reaps dead subprocesses.
* ``vars``: Pacemaker Remote loads environment variables from
|PCMK_INIT_ENV_FILE| but does not reap dead subprocesses.
* ``default``: Pacemaker Remote performs neither action.
If Pacemaker Remote is running as PID 1, this option is ignored, and the
behavior is the same as for ``full``.
* - .. _pcmk_tls_priorities:
.. index::
pair:: node option; PCMK_tls_priorities
PCMK_tls_priorities
- :ref:`text <text>`
- |PCMK_GNUTLS_PRIORITIES|
- *Advanced Use Only:* These GnuTLS cipher priorities will be used for TLS
connections (whether for Pacemaker Remote connections or remote CIB
access, when enabled). See:
https://gnutls.org/manual/html_node/Priority-Strings.html
Pacemaker will append ``":+ANON-DH"`` for remote CIB access and
``":+DHE-PSK:+PSK"`` for Pacemaker Remote connections, as they are
required for the respective functionality.
Example:
``PCMK_tls_priorities="SECURE128:+SECURE192"``
* - .. _pcmk_dh_min_bits:
.. index::
pair:: node option; PCMK_dh_min_bits
PCMK_dh_min_bits
- :ref:`nonnegative integer <nonnegative_integer>`
- 0 (no minimum)
- *Advanced Use Only:* Set a lower bound on the bit length of the prime
number generated for Diffie-Hellman parameters needed by TLS connections.
The default is no minimum.
The server (Pacemaker Remote daemon, or CIB manager configured to accept
remote clients) will use this value to provide a floor for the value
recommended by the GnuTLS library. The library will only accept a limited
number of specific values, which vary by library version, so setting
these is recommended only when required for compatibility with specific
client versions.
Clients (connecting cluster nodes or remote CIB commands) will require
that the server use a prime of at least this size. This is recommended
only when the value must be lowered in order for the client's GnuTLS
library to accept a connection to an older server.
* - .. _pcmk_dh_max_bits:
.. index::
pair:: node option; PCMK_dh_max_bits
PCMK_dh_max_bits
- :ref:`nonnegative integer <nonnegative_integer>`
- 0 (no maximum)
- *Advanced Use Only:* Set an upper bound on the bit length of the prime
number generated for Diffie-Hellman parameters needed by TLS connections.
The default is no maximum.
The server (Pacemaker Remote daemon, or CIB manager configured to accept
remote clients) will use this value to provide a ceiling for the value
recommended by the GnuTLS library. The library will only accept a limited
number of specific values, which vary by library version, so setting
these is recommended only when required for compatibility with specific
client versions.
Clients do not use ``PCMK_dh_max_bits``.
* - .. _pcmk_ipc_type:
.. index::
pair:: node option; PCMK_ipc_type
PCMK_ipc_type
- :ref:`enumeration <enumeration>`
- shared-mem
- *Advanced Use Only:* Force use of a particular IPC method. Allowed values:
* ``shared-mem``
* ``socket``
* ``posix``
* ``sysv``
* - .. _pcmk_ipc_buffer:
.. index::
pair:: node option; PCMK_ipc_buffer
PCMK_ipc_buffer
- :ref:`nonnegative integer <nonnegative_integer>`
- 131072
- *Advanced Use Only:* Specify an IPC buffer size in bytes. This can be
useful when connecting to large clusters that result in messages
exceeding the default size (which will also result in log messages
referencing this variable).
* - .. _pcmk_cluster_type:
.. index::
pair:: node option; PCMK_cluster_type
PCMK_cluster_type
- :ref:`enumeration <enumeration>`
- corosync
- *Advanced Use Only:* Specify the cluster layer to be used. If unset,
Pacemaker will detect and use a supported cluster layer, if available.
Currently, ``"corosync"`` is the only supported cluster layer. If
multiple layers are supported in the future, this will allow overriding
Pacemaker's automatic detection to select a specific one.
* - .. _pcmk_schema_directory:
.. index::
pair:: node option; PCMK_schema_directory
PCMK_schema_directory
- :ref:`text <text>`
- |CRM_SCHEMA_DIRECTORY|
- *Advanced Use Only:* Specify an alternate location for RNG schemas and
XSL transforms.
* - .. _pcmk_remote_schema_directory:
.. index::
pair:: node option; PCMK_remote_schema_directory
PCMK_remote_schema_directory
- :ref:`text <text>`
- |PCMK__REMOTE_SCHEMA_DIR|
- *Advanced Use Only:* Specify an alternate location on Pacemaker Remote
nodes for storing newer RNG schemas and XSL transforms fetched from
the cluster.
* - .. _pcmk_valgrind_enabled:
.. index::
pair:: node option; PCMK_valgrind_enabled
PCMK_valgrind_enabled
- :ref:`enumeration <enumeration>`
- no
- *Advanced Use Only:* Whether subsystem daemons should be run under
``valgrind``. Allowed values are the same as for ``PCMK_debug``.
* - .. _pcmk_callgrind_enabled:
.. index::
pair:: node option; PCMK_callgrind_enabled
PCMK_callgrind_enabled
- :ref:`enumeration <enumeration>`
- no
- *Advanced Use Only:* Whether subsystem daemons should be run under
``valgrind`` with the ``callgrind`` tool enabled. Allowed values are the
same as for ``PCMK_debug``.
+ * - .. _sbd_sync_resource_startup:
+
+ .. index::
+ pair:: node option; SBD_SYNC_RESOURCE_STARTUP
+
+ SBD_SYNC_RESOURCE_STARTUP
+ - :ref:`boolean <boolean>`
+ -
+ - If true, ``pacemakerd`` waits for a ping from ``sbd`` during startup
+ before starting other Pacemaker daemons, and during shutdown after
+ stopping other Pacemaker daemons but before exiting. Default value is set
+ based on the ``--with-sbd-sync-default`` configure script option.
+
+ * - .. _sbd_watchdog_timeout:
+
+ .. index::
+ pair:: node option; SBD_WATCHDOG_TIMEOUT
+
+ SBD_WATCHDOG_TIMEOUT
+ - :ref:`duration <duration>`
+ -
+ - If the ``stonith-watchdog-timeout`` cluster property is set to a negative
+ or invalid value, use double this value as the default if positive, or
+ use 0 as the default otherwise. This value must be greater than the value
+ of ``stonith-watchdog-timeout`` if both are set.
+
* - .. _valgrind_opts:
.. index::
pair:: node option; VALGRIND_OPTS
VALGRIND_OPTS
- :ref:`text <text>`
-
- *Advanced Use Only:* Pass these options to valgrind, when enabled (see
``valgrind(1)``). ``"--vgdb=no"`` should usually be specified because
``pacemaker-execd`` can lower privileges when executing commands, which
would otherwise leave a bunch of unremovable files in ``/tmp``.
diff --git a/doc/sphinx/conf.py.in b/doc/sphinx/conf.py.in
index 556eb7250e..9aac5e95d0 100644
--- a/doc/sphinx/conf.py.in
+++ b/doc/sphinx/conf.py.in
@@ -1,329 +1,330 @@
""" Sphinx configuration for Pacemaker documentation
"""
__copyright__ = "Copyright 2020-2023 the Pacemaker project contributors"
__license__ = "GNU General Public License version 2 or later (GPLv2+) WITHOUT ANY WARRANTY"
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import datetime
import os
import sys
# Variables that can be used later in this file
authors = "the Pacemaker project contributors"
year = datetime.datetime.now().year
doc_license = "Creative Commons Attribution-ShareAlike International Public License"
doc_license += " version 4.0 or later (CC-BY-SA v4.0+)"
# rST markup to insert at beginning of every document; mainly used for
#
# .. |<abbr>| replace:: <Full text>
#
# where occurrences of |<abbr>| in the rST will be substituted with <Full text>
rst_prolog="""
.. |CFS_DISTRO| replace:: AlmaLinux
.. |CFS_DISTRO_VER| replace:: 9
.. |CRM_BLACKBOX_DIR| replace:: ``%CRM_BLACKBOX_DIR%``
+.. |CRM_CONFIG_DIR| replace:: ``%CRM_CONFIG_DIR%``
.. |CRM_DAEMON_GROUP| replace:: ``%CRM_DAEMON_GROUP%``
.. |CRM_DAEMON_USER| replace:: ``%CRM_DAEMON_USER%``
-.. |CRM_DAEMON_USER_RAW| replace:: %CRM_DAEMON_USER%
.. |CRM_SCHEMA_DIRECTORY| replace:: %CRM_SCHEMA_DIRECTORY%
.. |PCMK_AUTHKEY_FILE| replace:: %PACEMAKER_CONFIG_DIR%/authkey
.. |PCMK_CONFIG_FILE| replace:: ``%CONFIGDIR%/pacemaker``
+.. |PCMK_GNUTLS_PRIORITIES| replace:: %PCMK_GNUTLS_PRIORITIES%
.. |PCMK_INIT_ENV_FILE| replace:: ``%PACEMAKER_CONFIG_DIR%/pcmk-init.env``
.. |PCMK_LOG_FILE| replace:: %CRM_LOG_DIR%/pacemaker.log
-.. |PCMK_GNUTLS_PRIORITIES| replace:: %PCMK_GNUTLS_PRIORITIES%
+.. |PCMK_CONTAINER_LOG_FILE| replace:: ``/var/log/pcmk-init.log``
.. |REMOTE_DISTRO| replace:: AlmaLinux
.. |REMOTE_DISTRO_VER| replace:: 9
"""
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('%ABS_TOP_SRCDIR%/python'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.autosummary']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = '%BOOK_ID%'
copyright = "2009-%s %s. Released under the terms of the %s" % (year, authors, doc_license)
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The full version, including alpha/beta/rc tags.
release = '%VERSION%'
# The short X.Y version.
version = release.rsplit('.', 1)[0]
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'vs'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'pyramid'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
html_style = 'pacemaker.css'
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = "%BOOK_TITLE%"
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = [ '%SRC_DIR%/_static' ]
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Pacemakerdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_engine = "xelatex"
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', '%BOOK_ID%.tex', '%BOOK_TITLE%', authors, 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', '%BOOK_ID%', 'Part of the Pacemaker documentation set', [authors], 8)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', '%BOOK_ID%', '%BOOK_TITLE%', authors, '%BOOK_TITLE%',
'Pacemaker is an advanced, scalable high-availability cluster resource manager.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = '%BOOK_TITLE%'
epub_author = authors
epub_publisher = 'ClusterLabs.org'
epub_copyright = copyright
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
epub_scheme = 'URL'
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
epub_identifier = 'https://www.clusterlabs.org/pacemaker/doc/2.1/%BOOK_ID%/epub/%BOOK_ID%.epub'
# A unique identification for the text.
epub_uid = 'ClusterLabs.org-Pacemaker-%BOOK_ID%'
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files that should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
epub_exclude_files = [
'_static/doctools.js',
'_static/jquery.js',
'_static/searchtools.js',
'_static/underscore.js',
'_static/basic.css',
'_static/websupport.js',
'search.html',
]
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
autosummary_generate = True
diff --git a/include/crm/cib/cib_types.h b/include/crm/cib/cib_types.h
index bebe770ed1..dad3c8f45d 100644
--- a/include/crm/cib/cib_types.h
+++ b/include/crm/cib/cib_types.h
@@ -1,359 +1,359 @@
/*
* Copyright 2004-2023 the Pacemaker project contributors
*
* The version control history for this file may have further details.
*
* This source code is licensed under the GNU Lesser General Public License
* version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
*/
#ifndef PCMK__CRM_CIB_CIB_TYPES__H
# define PCMK__CRM_CIB_CIB_TYPES__H
# include <glib.h> // gboolean, GList
# include <libxml/tree.h> // xmlNode
# include <crm/common/ipc.h>
# include <crm/common/xml.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \file
* \brief Data types for Cluster Information Base access
* \ingroup cib
*/
enum cib_variant {
cib_undefined = 0,
cib_native = 1,
cib_file = 2,
cib_remote = 3,
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
//! \deprecated This value will be removed in a future release
cib_database = 4,
#endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
};
enum cib_state {
cib_connected_command,
cib_connected_query,
cib_disconnected
};
enum cib_conn_type {
cib_command,
cib_query,
cib_no_connection,
cib_command_nonblocking,
};
enum cib_call_options {
cib_none = 0,
cib_verbose = (1 << 0), //!< Prefer stderr to logs
cib_xpath = (1 << 1),
cib_multiple = (1 << 2),
cib_can_create = (1 << 3),
cib_discard_reply = (1 << 4),
cib_no_children = (1 << 5),
cib_xpath_address = (1 << 6),
//! \deprecated This value will be removed in a future release
cib_mixed_update = (1 << 7),
/* @COMPAT: cib_scope_local is processed only in the legacy function
* parse_local_options_v1().
*
* If (host == NULL):
* * In legacy mode, the CIB manager forwards a request to the primary
* instance unless cib_scope_local is set or the local node is primary.
* * Outside of legacy mode:
* * If a request modifies the CIB, the CIB manager forwards it to all
* nodes.
* * Otherwise, the CIB manager processes the request locally.
*
* There is no current use case for this implementing this flag in
* non-legacy mode.
*/
//! \deprecated This value will be removed in a future release
cib_scope_local = (1 << 8),
cib_dryrun = (1 << 9),
/*!
* \brief Process request when the client commits the active transaction
*
* Add the request to the client's active transaction instead of processing
* it immediately. If the client has no active transaction, or if the
* request is not supported in transactions, the call will fail.
*
* The request is added to the transaction synchronously, and the return
* value indicates whether it was added successfully.
*
* Refer to \p cib_api_operations_t:init_transaction() and
* \p cib_api_operations_t:end_transaction() for more details on CIB
* transactions.
*/
cib_transaction = (1 << 10),
cib_sync_call = (1 << 12),
cib_no_mtime = (1 << 13),
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
//! \deprecated This value will be removed in a future release
cib_zero_copy = (1 << 14),
#endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
cib_inhibit_notify = (1 << 16),
#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
//! \deprecated This value will be removed in a future release
cib_quorum_override = (1 << 20),
#endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
//! \deprecated This value will be removed in a future release
cib_inhibit_bcast = (1 << 24),
cib_force_diff = (1 << 28),
};
typedef struct cib_s cib_t;
typedef struct cib_api_operations_s {
int (*signon) (cib_t *cib, const char *name, enum cib_conn_type type);
//! \deprecated This method will be removed and should not be used
int (*signon_raw) (cib_t *cib, const char *name, enum cib_conn_type type,
int *event_fd);
int (*signoff) (cib_t *cib);
int (*free) (cib_t *cib);
//! \deprecated This method will be removed and should not be used
int (*set_op_callback) (cib_t *cib, void (*callback) (const xmlNode *msg,
int callid, int rc,
xmlNode *output));
int (*add_notify_callback) (cib_t *cib, const char *event,
void (*callback) (const char *event,
xmlNode *msg));
int (*del_notify_callback) (cib_t *cib, const char *event,
void (*callback) (const char *event,
xmlNode *msg));
int (*set_connection_dnotify) (cib_t *cib,
void (*dnotify) (gpointer user_data));
//! \deprecated This method will be removed and should not be used
int (*inputfd) (cib_t *cib);
//! \deprecated This method will be removed and should not be used
int (*noop) (cib_t *cib, int call_options);
int (*ping) (cib_t *cib, xmlNode **output_data, int call_options);
int (*query) (cib_t *cib, const char *section, xmlNode **output_data,
int call_options);
int (*query_from) (cib_t *cib, const char *host, const char *section,
xmlNode **output_data, int call_options);
//! \deprecated This method will be removed and should not be used
int (*is_master) (cib_t *cib);
//! \deprecated Use the set_primary() method instead
int (*set_master) (cib_t *cib, int call_options);
//! \deprecated Use the set_secondary() method instead
int (*set_slave) (cib_t *cib, int call_options);
//! \deprecated This method will be removed and should not be used
int (*set_slave_all) (cib_t *cib, int call_options);
int (*sync) (cib_t *cib, const char *section, int call_options);
int (*sync_from) (cib_t *cib, const char *host, const char *section,
int call_options);
int (*upgrade) (cib_t *cib, int call_options);
int (*bump_epoch) (cib_t *cib, int call_options);
int (*create) (cib_t *cib, const char *section, xmlNode *data,
int call_options);
int (*modify) (cib_t *cib, const char *section, xmlNode *data,
int call_options);
//! \deprecated Use the \p modify() method instead
int (*update) (cib_t *cib, const char *section, xmlNode *data,
int call_options);
int (*replace) (cib_t *cib, const char *section, xmlNode *data,
int call_options);
int (*remove) (cib_t *cib, const char *section, xmlNode *data,
int call_options);
int (*erase) (cib_t *cib, xmlNode **output_data, int call_options);
//! \deprecated This method does nothing and should not be called
int (*delete_absolute) (cib_t *cib, const char *section, xmlNode *data,
int call_options);
//! \deprecated This method is not implemented and should not be used
int (*quit) (cib_t *cib, int call_options);
int (*register_notification) (cib_t *cib, const char *callback,
int enabled);
gboolean (*register_callback) (cib_t *cib, int call_id, int timeout,
gboolean only_success, void *user_data,
const char *callback_name,
void (*callback) (xmlNode*, int, int,
xmlNode*, void *));
gboolean (*register_callback_full)(cib_t *cib, int call_id, int timeout,
gboolean only_success, void *user_data,
const char *callback_name,
void (*callback)(xmlNode *, int, int,
xmlNode *, void *),
void (*free_func)(void *));
/*!
* \brief Set the local CIB manager as the cluster's primary instance
*
* \param[in,out] cib CIB connection
* \param[in] call_options Group of enum cib_call_options flags
*
* \return Legacy Pacemaker return code (in particular, pcmk_ok on success)
*/
int (*set_primary)(cib_t *cib, int call_options);
/*!
* \brief Set the local CIB manager as a secondary instance
*
* \param[in,out] cib CIB connection
* \param[in] call_options Group of enum cib_call_options flags
*
* \return Legacy Pacemaker return code (in particular, pcmk_ok on success)
*/
int (*set_secondary)(cib_t *cib, int call_options);
/*!
* \brief Get the given CIB connection's unique client identifier(s)
*
* These can be used to check whether this client requested the action that
* triggered a CIB notification.
*
* \param[in] cib CIB connection
* \param[out] async_id If not \p NULL, where to store asynchronous client
* ID
* \param[out] sync_id If not \p NULL, where to store synchronous client
* ID
*
* \return Legacy Pacemaker return code
*
* \note Some variants may have only one client for both asynchronous and
* synchronous requests.
*/
int (*client_id)(const cib_t *cib, const char **async_id,
const char **sync_id);
/*!
* \brief Initiate an atomic CIB transaction for this client
*
* If the client has initiated a transaction and a new request's call
* options contain \p cib_transaction, the new request is appended to the
* transaction for later processing.
*
* Supported requests are those that meet the following conditions:
* * can be processed synchronously (with any changes applied to a working
* CIB copy)
* * are not queries
* * do not involve other nodes
* * do not affect the state of pacemaker-based itself
*
* Currently supported CIB API functions include:
* * \p bump_epoch()
* * \p create()
* * \p erase()
* * \p modify()
* * \p remove()
* * \p replace()
* * \p upgrade()
*
* Because the transaction is atomic, individual requests do not trigger
* callbacks or notifications when they are processed, and they do not
* receive output XML. The commit request itself can trigger callbacks and
* notifications if any are registered.
*
* An \c init_transaction() call is always synchronous.
*
* \param[in,out] cib CIB connection
*
* \return Legacy Pacemaker return code
*/
int (*init_transaction)(cib_t *cib);
/*!
* \brief End and optionally commit this client's CIB transaction
*
* When a client commits a transaction, all requests in the transaction are
* processed in a FIFO manner until either a request fails or all requests
* have been processed. Changes are applied to a working copy of the CIB.
* If a request fails, the transaction and working CIB copy are discarded,
* and an error is returned. If all requests succeed, the working CIB copy
* replaces the initial CIB copy.
*
* Callbacks and notifications can be triggered by the commit request itself
* but not by the individual requests in a transaction.
*
* An \c end_transaction() call with \p commit set to \c false is always
* synchronous.
*
* \param[in,out] cib CIB connection
* \param[in] commit If \p true, commit transaction; otherwise,
* discard it
* \param[in] call_options Group of <tt>enum cib_call_options</tt>
* flags
*
* \return Legacy Pacemaker return code
*/
int (*end_transaction)(cib_t *cib, bool commit, int call_options);
/*!
* \brief Set the user as whom all CIB requests via methods will be executed
*
* By default, the value of the \c CIB_user environment variable is used if
- * set. Otherwise, \c root is used.
+ * set. Otherwise, the current effective user is used.
*
* \param[in,out] cib CIB connection
* \param[in] user Name of user whose permissions to use when
* processing requests
*/
void (*set_user)(cib_t *cib, const char *user);
int (*fetch_schemas)(cib_t *cib, xmlNode **output_data, const char *after_ver,
int call_options);
} cib_api_operations_t;
struct cib_s {
enum cib_state state;
enum cib_conn_type type;
enum cib_variant variant;
int call_id;
int call_timeout;
void *variant_opaque;
void *delegate_fn;
GList *notify_list;
//! \deprecated This method will be removed in a future release
void (*op_callback) (const xmlNode *msg, int call_id, int rc,
xmlNode *output);
cib_api_operations_t *cmds;
xmlNode *transaction;
char *user;
};
#ifdef __cplusplus
}
#endif
#endif // PCMK__CRM_CIB_CIB_TYPES__H

File Metadata

Mime Type
text/x-diff
Expires
Mon, Apr 21, 7:15 PM (16 h, 54 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1665468
Default Alt Text
(243 KB)

Event Timeline