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 /_build/ 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 .. 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 ` on success and an appropriate + error code otherwise. Must not report success until the resource is fully + active. + * - .. _stop_action: + + .. index:: + single: OCF resource agent; stop + single: stop action + + stop + - Stop the resource + - Return :ref:`OCF_SUCCESS ` on success and an appropriate + error code otherwise. Must not report success until the resource is fully + stopped. + * - .. _monitor_action: + + .. index:: + single: OCF resource agent; monitor + single: monitor action + + monitor + - Check the resource's state + - Return :ref:`OCF_SUCCESS ` if the resource is running, + :ref:`OCF_NOT_RUNNING ` if it is stopped, and any other + :ref:`OCF exit code ` if it is failed. **Note:** The + monitor action should test the state of the resource on the local machine + only. + * - .. _meta_data_action: + + .. index:: + single: OCF resource agent; meta-data + single: meta-data action + + meta-data + - Describe the resource + - Provide information about this resource in the XML format defined by the + OCF standard. Return :ref:`OCF_SUCCESS `. **Note:** This is + *not* required to be performed as root. OCF resource agents may optionally implement additional actions. Some are used only with advanced resource types such as clones. -.. 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 ` if parameters are valid, + :ref:`OCF_ERR_ARGS ` if not valid, and + :ref:`OCF_ERR_CONFIGURED ` if resource is not + configured. + * - .. _promote_action: + + .. index:: + single: OCF resource agent; promote + single: promote action + + promote + - Bring the local instance of a promotable clone resource to the promoted + role. + - Return :ref:`OCF_SUCCESS ` on success. + * - .. _demote_action: + + .. index:: + single: OCF resource agent; demote + single: demote action + + demote + - Bring the local instance of a promotable clone resource to the unpromoted + role. + - Return :ref:`OCF_SUCCESS ` on success. + * - .. _notify_action: + + .. index:: + single: OCF resource agent; notify + single: notify action + + notify + - Used by the cluster to send the agent pre- and post-notification events + telling the resource what has happened and what will happen. + - Must not fail. Must return :ref:`OCF_SUCCESS `. + * - .. _reload_action: + + .. index:: + single: OCF resource agent; reload + single: reload action + + reload + - Reload the service's own configuration. + - Not used by Pacemaker. + * - .. _reload_agent_action: + + .. index:: + single: OCF resource agent; reload-agent + single: reload-agent action + + reload-agent + - Make effective any changes in instance parameters marked as reloadable in + the agent's meta-data. + - This is used when the agent can handle a change in some of its parameters + more efficiently than stopping and starting the resource. + * - .. _recover_action: + + .. index:: + single: OCF resource agent; recover + single: recover action + + recover + - Restart the service. + - Not used by Pacemaker. .. important:: If you create a new OCF resource agent, use `ocf-tester` to verify that the agent complies with the OCF standard properly. .. index:: single: OCF resource agent; return code -How are OCF Return Codes Interpreted? +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 ` + * - .. _OCF_ERR_GENERIC: + + .. index:: + single: OCF_ERR_GENERIC + single: OCF return code; OCF_ERR_GENERIC + pair: OCF return code; 1 + + 1 + - OCF_ERR_GENERIC + - Generic "there was a problem" error code. + - :ref:`hard ` + * - .. _OCF_ERR_ARGS: + + .. index:: + single: OCF_ERR_ARGS + single: OCF return code; OCF_ERR_ARGS + pair: OCF return code; 2 + + 2 + - OCF_ERR_ARGS + - The resource's parameter values are not valid on this machine (for + example, a value refers to a file not found on the local host). + - :ref:`hard ` + * - .. _OCF_ERR_UNIMPLEMENTED: + + .. index:: + single: OCF_ERR_UNIMPLEMENTED + single: OCF return code; OCF_ERR_UNIMPLEMENTED + pair: OCF return code; 3 + + 3 + - OCF_ERR_UNIMPLEMENTED + - The requested action is not implemented. + - :ref:`hard ` + * - .. _OCF_ERR_PERM: + + .. index:: + single: OCF_ERR_PERM + single: OCF return code; OCF_ERR_PERM + pair: OCF return code; 4 + + 4 + - OCF_ERR_PERM + - The resource agent does not have sufficient privileges to complete the + task. + - :ref:`hard ` + * - .. _OCF_ERR_INSTALLED: + + .. index:: + single: OCF_ERR_INSTALLED + single: OCF return code; OCF_ERR_INSTALLED + pair: OCF return code; 5 + + 5 + - OCF_ERR_INSTALLED + - The tools required by the resource are not installed on this machine. + - :ref:`hard ` + * - .. _OCF_ERR_CONFIGURED: + + .. index:: + single: OCF_ERR_CONFIGURED + single: OCF return code; OCF_ERR_CONFIGURED + pair: OCF return code; 6 + + 6 + - OCF_ERR_CONFIGURED + - The resource's parameter values are inherently invalid (for example, a + required parameter was not given). + - :ref:`fatal ` + * - .. _OCF_NOT_RUNNING: + + .. index:: + single: OCF_NOT_RUNNING + single: OCF return code; OCF_NOT_RUNNING + pair: OCF return code; 7 + + 7 + - OCF_NOT_RUNNING + - The resource is safely stopped. This should only be returned by monitor + actions, not stop actions. + - N/A + * - .. _OCF_RUNNING_PROMOTED: + + .. index:: + single: OCF_RUNNING_PROMOTED + single: OCF return code; OCF_RUNNING_PROMOTED + pair: OCF return code; 8 + + 8 + - OCF_RUNNING_PROMOTED + - The resource is running in the promoted role. + - :ref:`soft ` + * - .. _OCF_FAILED_PROMOTED: + + .. index:: + single: OCF_FAILED_PROMOTED + single: OCF return code; OCF_FAILED_PROMOTED + pair: OCF return code; 9 + + 9 + - OCF_FAILED_PROMOTED + - The resource is (or might be) in the promoted role but has failed. The + resource will be demoted, stopped, and then started (and possibly + promoted) again. + - :ref:`soft ` + * - .. _OCF_DEGRADED: + + .. index:: + single: OCF_DEGRADED + single: OCF return code; OCF_DEGRADED + pair: OCF return code; 190 + + 190 + - OCF_DEGRADED + - The resource is properly active, but in such a condition that future + failures are more likely. + - none + * - .. _OCF_DEGRADED_PROMOTED: + + .. index:: + single: OCF_DEGRADED_PROMOTED + single: OCF return code; OCF_DEGRADED_PROMOTED + pair: OCF return code; 191 + + 191 + - OCF_DEGRADED_PROMOTED + - The resource is properly active in the promoted role, but in such a + condition that future failures are more likely. + - none + * - other + - *none* + - Custom error code. + - soft Exceptions to the recovery handling described above: * Probes (non-recurring monitor actions) that find a resource active (or in the promoted role) will not result in recovery action unless it is also found active elsewhere. * The recovery action taken when a resource is found active more than once is determined by the resource's ``multiple-active`` property. * Recurring actions that return ``OCF_ERR_UNIMPLEMENTED`` do not cause any type of recovery. * Actions that return one of the "degraded" codes will be treated the same as if they had returned success, but status output will indicate that the resource is degraded. +.. _ocf_env_vars: + +Environment Variables +_____________________ + +Pacemaker sets certain environment variables when it executes an OCF resource +agent. Agents can check these variables to get information about resource +parameters or the execution environment. + +**Note:** Pacemaker may set other environment variables for its own purposes. +They may be present in the agent's environment, but Pacemaker is not providing +them for the agent's use, and so the agent should not rely on any variables not +listed in the table below. + +.. list-table:: **OCF Environment Variables** + :class: longtable + :widths: 1 6 + :header-rows: 1 + + * - Environment Variable + - Description + * - .. _OCF_CHECK_LEVEL: + + .. index:: + single: OCF_CHECK_LEVEL + single: environment variable; OCF_CHECK_LEVEL + + OCF_CHECK_LEVEL + - Requested intensity level of checks in ``monitor`` and ``validate-all`` + actions. Usually set as an operation attribute; see Pacemaker Explained + for an example. + * - .. _OCF_EXIT_REASON_PREFIX: + + .. index:: + single: OCF_EXIT_REASON_PREFIX + single: environment variable; OCF_EXIT_REASON_PREFIX + + OCF_EXIT_REASON_PREFIX + - Prefix for printing fatal error messages from the resource agent. + * - .. _OCF_RA_VERSION_MAJOR: + + .. index:: + single: OCF_RA_VERSION_MAJOR + single: environment variable; OCF_RA_VERSION_MAJOR + + OCF_RA_VERSION_MAJOR + - Major version number of the OCF Resource Agent API. If the script does + not support this revision, it should report an error. + See the `OCF specification `_ for an + explanation of the versioning scheme used. The version number is split + into two numbers for ease of use in shell scripts. These two may be used + by the agent to determine whether it is run under an OCF-compliant + resource manager. + * - .. _OCF_RA_VERSION_MINOR: + + .. index:: + single: OCF_RA_VERSION_MINOR + single: environment variable; OCF_RA_VERSION_MINOR + + OCF_RA_VERSION_MINOR + - Minor version number of the OCF Resource Agent API. See + :ref:`OCF_RA_VERSION_MAJOR ` for more details. + * - .. _OCF_RESKEY_crm_feature_set: + + .. index:: + single: OCF_RESKEY_crm_feature_set + single: environment variable; OCF_RESKEY_crm_feature_set + + OCF_RESKEY_crm_feature_set + - ``crm_feature_set`` on the DC (or on the local node, if the agent is run + by ``crm_resource``). + * - .. _OCF_RESKEY_CRM_meta_interval: + + .. index:: + single: OCF_RESKEY_CRM_meta_interval + single: environment variable; OCF_RESKEY_CRM_meta_interval + + OCF_RESKEY_CRM_meta_interval + - Interval (in milliseconds) of the current operation. + * - .. _OCF_RESKEY_CRM_meta_name: + + .. index:: + single: OCF_RESKEY_CRM_meta_name + single: environment variable; OCF_RESKEY_CRM_meta_name + + OCF_RESKEY_CRM_meta_name + - Name of the current operation. + * - .. _OCF_RESKEY_CRM_meta_notify: + + .. index:: + single: OCF_RESKEY_CRM_meta_notify_* + single: environment variable; OCF_RESKEY_CRM_meta_notify_* + + OCF_RESKEY_CRM_meta_notify_* + - See :ref:`Clone Notifications `. + * - .. _OCF_RESKEY_CRM_meta_on_node: + + .. index:: + single: OCF_RESKEY_CRM_meta_on_node + single: environment variable; OCF_RESKEY_CRM_meta_on_node + + OCF_RESKEY_CRM_meta_on_node + - Name of the node where the current operation is running. + * - .. _OCF_RESKEY_CRM_meta_on_node_uuid: + + .. index:: + single: OCF_RESKEY_CRM_meta_on_node_uuid + single: environment variable; OCF_RESKEY_CRM_meta_on_node_uuid + + OCF_RESKEY_CRM_meta_on_node_uuid + - Cluster-layer ID of the node where the current operation is running (or + node name for Pacemaker Remote nodes). + * - .. _OCF_RESKEY_CRM_meta_physical_host: + + .. index:: + single: OCF_RESKEY_CRM_meta_physical_host + single: environment variable; OCF_RESKEY_CRM_meta_physical_host + + OCF_RESKEY_CRM_meta_physical_host + - If the node where the current operation is running is a guest node, the + host on which the container is running. + * - .. _OCF_RESKEY_CRM_meta_timeout: + + .. index:: + single: OCF_RESKEY_CRM_meta_timeout + single: environment variable; OCF_RESKEY_CRM_meta_timeout + + OCF_RESKEY_CRM_meta_timeout + - Timeout (in milliseconds) of the current operation. + * - .. _OCF_RESKEY_CRM_meta: + + .. index:: + single: OCF_RESKEY_CRM_meta_* + single: environment variable; OCF_RESKEY_CRM_meta_* + + OCF_RESKEY_CRM_meta_* + - Each of a resource's meta-attributes is converted to an environment + variable prefixed with "OCF_RESKEY_CRM_meta\_". See Pacemaker Explained + for some meta-attributes that have special meaning to Pacemaker. + * - .. _OCF_RESKEY: + + .. index:: + single: OCF_RESKEY_* + single: environment variable; OCF_RESKEY_* + + OCF_RESKEY_* + - Each of a resource's instance parameters is converted to an environment + variable prefixed with "OCF_RESKEY\_". + * - .. _OCF_RESOURCE_INSTANCE: + + .. index:: + single: OCF_RESOURCE_INSTANCE + single: environment variable; OCF_RESOURCE_INSTANCE + + OCF_RESOURCE_INSTANCE + - The name of the resource instance. + * - .. _OCF_RESOURCE_PROVIDER: + + .. index:: + single: OCF_RESOURCE_PROVIDER + single: environment variable; OCF_RESOURCE_PROVIDER + + OCF_RESOURCE_PROVIDER + - The name of the resource agent provider. + * - .. _OCF_RESOURCE_TYPE: + + .. index:: + single: OCF_RESOURCE_TYPE + single: environment variable; OCF_RESOURCE_TYPE + + OCF_RESOURCE_TYPE + - The name of the resource type. + * - .. _OCF_ROOT: + + .. index:: + single: OCF_ROOT + single: environment variable; OCF_ROOT + + OCF_ROOT + - The root of the OCF directory hierarchy. + * - .. _OCF_TRACE_FILE: + + .. index:: + single: OCF_TRACE_FILE + single: environment variable; OCF_TRACE_FILE + + OCF_TRACE_FILE + - The absolute path or file descriptor to write trace output to, if + ``OCF_TRACE_RA`` is set to true. Pacemaker sets this only to + ``/dev/stderr`` and only when running a resource agent via + ``crm_resource``. + * - .. _OCF_TRACE_RA: + + .. index:: + single: OCF_TRACE_RA + single: environment variable; OCF_TRACE_RA + + OCF_TRACE_RA + - If set to true, enable tracing of the resource agent. Trace output is + written to ``OCF_TRACE_FILE`` if set; otherwise, it's written to a file + in ``OCF_RESKEY_trace_dir`` if set or in a default directory if not. + Pacemaker sets this to true only when running a resource agent via + ``crm_resource`` with one or more ``-V`` flags. + * - .. _PCMK_DEBUGLOG: + .. _HA_DEBUGLOG: + + .. index:: + single: PCMK_DEBUGLOG + single: environment variable; PCMK_DEBUGLOG + single: HA_DEBUGLOG + single: environment variable; HA_DEBUGLOG + + PCMK_DEBUGLOG (and HA_DEBUGLOG) + - Where to write resource agent debug logs. Pacemaker sets this to + ``PCMK_logfile`` if set to a value other than ``none`` and if debugging + is enabled for the executor. + * - .. _PCMK_LOGFACILITY: + .. _HA_LOGFACILITY: + + .. index:: + single: PCMK_LOGFACILITY + single: environment variable; PCMK_LOGFACILITY + single: HA_LOGFACILITY + single: environment variable; HA_LOGFACILITY + + PCMK_LOGFACILITY (and HA_LOGFACILITY) + - Syslog facility for resource agent logs. Pacemaker sets this to + ``PCMK_logfacility`` if set to a value other than ``none`` or + ``/dev/null``. + * - .. _PCMK_LOGFILE: + .. _HA_LOGFILE:: + + .. index:: + single: PCMK_LOGFILE: + single: environment variable; PCMK_LOGFILE: + single: HA_LOGFILE: + single: environment variable; HA_LOGFILE: + + PCMK_LOGFILE (and HA_LOGFILE) + - Where to write resource agent logs. Pacemaker sets this to + ``PCMK_logfile`` if set to a value other than ``none``. + * - .. _PCMK_service: + + .. index:: + single: PCMK_service + single: environment variable; PCMK_service + + PCMK_service + - The name of the Pacemaker subsystem or command-line tool that's executing + the resource agent. Specific values are subject to change; useful mainly + for logging. + +Clone Resource Agent Requirements +_________________________________ + +Any resource can be used as an anonymous clone, as it requires no additional +support from the resource agent. Whether it makes sense to do so depends on your +resource and its resource agent. + +Resource Agent Requirements for Globally Unique Clones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Globally unique clones require additional support in the resource agent. In +particular, it must respond with ``OCF_SUCCESS`` only if the node has that exact +instance active. All other probes for instances of the clone should result in +``OCF_NOT_RUNNING`` (or one of the other OCF error codes if they are failed). + +Individual instances of a clone are identified by appending a colon and a +numerical offset (for example, ``apache:2``). + +A resource agent can find out how many copies there are by examining the +``OCF_RESKEY_CRM_meta_clone_max`` environment variable and which instance it is +by examining ``OCF_RESKEY_CRM_meta_clone``. + +The resource agent must not make any assumptions (based on +``OCF_RESKEY_CRM_meta_clone``) about which numerical instances are active. In +particular, the list of active copies is not always an unbroken sequence, nor +does it always start at 0. + +Resource Agent Requirements for Promotable Clones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Promotable clone resources require two extra actions, ``demote`` and ``promote``, +which are responsible for changing the state of the resource. Like ``start`` and +``stop``, they should return ``OCF_SUCCESS`` if they completed successfully or a +relevant error code if they did not. + +The states can mean whatever you wish, but when the resource is started, it must +begin in the unpromoted role. From there, the cluster will decide which +instances to promote. + +In addition to the clone requirements for monitor actions, agents must also +*accurately* report which state they are in. The cluster relies on the agent to +report its status (including role) accurately and does not indicate to the agent +what role it currently believes it to be in. + +.. list-table:: **Role Implications of OCF Return Codes** + :class: longtable + :widths: 1 3 + :header-rows: 1 + + * - Monitor Return Code + - Description + * - :ref:`OCF_NOT_RUNNING ` + - .. index:: + single: OCF_NOT_RUNNING + single: OCF return code; OCF_NOT_RUNNING + + Stopped + * - :ref:`OCF_SUCCESS ` + - .. index:: + single: OCF_SUCCESS + single: OCF return code; OCF_SUCCESS + + Running (Unpromoted) + * - :ref:`OCF_RUNNING_PROMOTED ` + - .. index:: + single: OCF_RUNNING_PROMOTED + single: OCF return code; OCF_RUNNING_PROMOTED + + Running (Promoted) + * - :ref:`OCF_FAILED_PROMOTED ` + - .. index:: + single: OCF_FAILED_PROMOTED + single: OCF return code; OCF_FAILED_PROMOTED + + Failed (Promoted) + * - Other + - Failed (Unpromoted) + +.. _clone_notifications: + +Clone Notifications +~~~~~~~~~~~~~~~~~~~ + +If the clone has the ``notify`` meta-attribute set to ``true`` and the resource +agent supports the ``notify`` action, Pacemaker will call the action when +appropriate, passing a number of extra variables. These variables, when combined +with additional context, can be used to calculate the current state of the +cluster and what is about to happen to it. + +.. index:: + single: clone; environment variables + single: notify; environment variables + +.. list-table:: **Environment Variables Supplied with Clone Notify Actions** + :class: longtable + :widths: 1 1 + :header-rows: 1 + + * - Variable + - Description + * - .. _OCF_RESKEY_CRM_meta_notify_type: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_type + single: OCF_RESKEY_CRM_meta_notify_type + + OCF_RESKEY_CRM_meta_notify_type + - Allowed values: ``pre``, ``post`` + * - .. _OCF_RESKEY_CRM_meta_notify_operation: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_operation + single: OCF_RESKEY_CRM_meta_notify_operation + + OCF_RESKEY_CRM_meta_notify_operation + - Allowed values: ``start``, ``stop`` + * - .. _OCF_RESKEY_CRM_meta_notify_start_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_start_resource + single: OCF_RESKEY_CRM_meta_notify_start_resource + + OCF_RESKEY_CRM_meta_notify_start_resource + - Resources to be started + * - .. _OCF_RESKEY_CRM_meta_notify_stop_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_stop_resource + single: OCF_RESKEY_CRM_meta_notify_stop_resource + + OCF_RESKEY_CRM_meta_notify_stop_resource + - Resources to be stopped + * - .. _OCF_RESKEY_CRM_meta_notify_active_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_active_resource + single: OCF_RESKEY_CRM_meta_notify_active_resource + + OCF_RESKEY_CRM_meta_notify_active_resource + - Resources that are running + * - .. _OCF_RESKEY_CRM_meta_notify_inactive_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_inactive_resource + single: OCF_RESKEY_CRM_meta_notify_inactive_resource + + OCF_RESKEY_CRM_meta_notify_inactive_resource + - Resources that are not running + * - .. _OCF_RESKEY_CRM_meta_notify_start_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_start_uname + single: OCF_RESKEY_CRM_meta_notify_start_uname + + OCF_RESKEY_CRM_meta_notify_start_uname + - Nodes on which resources will be started + * - .. _OCF_RESKEY_CRM_meta_notify_stop_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_stop_uname + single: OCF_RESKEY_CRM_meta_notify_stop_uname + + OCF_RESKEY_CRM_meta_notify_stop_uname + - Nodes on which resources will be stopped + * - .. _OCF_RESKEY_CRM_meta_notify_active_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_active_uname + single: OCF_RESKEY_CRM_meta_notify_active_uname + + OCF_RESKEY_CRM_meta_notify_active_uname + - Nodes on which resources are running + +The variables come in pairs, such as +``OCF_RESKEY_CRM_meta_notify_start_resource`` and +``OCF_RESKEY_CRM_meta_notify_start_uname``, and should be treated as an array of +whitespace-separated elements. + +``OCF_RESKEY_CRM_meta_notify_inactive_resource`` is an exception, as the +matching ``uname`` variable does not exist since inactive resources are not +running on any node. + +Thus, in order to indicate that ``clone:0`` will be started on ``sles-1``, +``clone:2`` will be started on ``sles-3``, and ``clone:3`` will be started +on ``sles-2``, the cluster would set: + +.. topic:: Notification Variables + + .. code-block:: none + + OCF_RESKEY_CRM_meta_notify_start_resource="clone:0 clone:2 clone:3" + OCF_RESKEY_CRM_meta_notify_start_uname="sles-1 sles-3 sles-2" + +.. note:: + + Pacemaker will log but otherwise ignore failures of notify actions. + +Interpretation of Notification Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Pre-notification (stop):** + +* Active resources: ``$OCF_RESKEY_CRM_meta_notify_active_resource`` +* Inactive resources: ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` +* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + +**Post-notification (stop) / Pre-notification (start):** + +* Active resources + * ``$OCF_RESKEY_CRM_meta_notify_active_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Inactive resources + * ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + +**Post-notification (start):** + +* Active resources: + * ``$OCF_RESKEY_CRM_meta_notify_active_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Inactive resources: + * ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + +Extra Notifications for Promotable Clones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: clone; environment variables + single: promotable; environment variables + +.. list-table:: **Extra Environment Variables Supplied for Promotable Clones** + :class: longtable + :widths: 1 1 + :header-rows: 1 + + * - Variable + - Description + * - .. _OCF_RESKEY_CRM_meta_notify_promoted_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_promoted_resource + single: OCF_RESKEY_CRM_meta_notify_promoted_resource + + OCF_RESKEY_CRM_meta_notify_promoted_resource + - Resources that are running in the promoted role + * - .. _OCF_RESKEY_CRM_meta_notify_unpromoted_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_unpromoted_resource + single: OCF_RESKEY_CRM_meta_notify_unpromoted_resource + + OCF_RESKEY_CRM_meta_notify_unpromoted_resource + - Resources that are running in the unpromoted role + * - .. _OCF_RESKEY_CRM_meta_notify_promote_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_promote_resource + single: OCF_RESKEY_CRM_meta_notify_promote_resource + + OCF_RESKEY_CRM_meta_notify_promote_resource + - Resources to be promoted + * - .. _OCF_RESKEY_CRM_meta_notify_demote_resource: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_demote_resource + single: OCF_RESKEY_CRM_meta_notify_demote_resource + + OCF_RESKEY_CRM_meta_notify_demote_resource + - Resources to be demoted + * - .. _OCF_RESKEY_CRM_meta_notify_promote_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_promote_uname + single: OCF_RESKEY_CRM_meta_notify_promote_uname + + OCF_RESKEY_CRM_meta_notify_promote_uname + - Nodes on which resources will be promoted + * - .. _OCF_RESKEY_CRM_meta_notify_demote_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_demote_uname + single: OCF_RESKEY_CRM_meta_notify_demote_uname + + OCF_RESKEY_CRM_meta_notify_demote_uname + - Nodes on which resources will be demoted + * - .. _OCF_RESKEY_CRM_meta_notify_promoted_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_promoted_uname + single: OCF_RESKEY_CRM_meta_notify_promoted_uname + + OCF_RESKEY_CRM_meta_notify_promoted_uname + - Nodes on which resources are running in the promoted role + * - .. _OCF_RESKEY_CRM_meta_notify_unpromoted_uname: + + .. index:: + single: environment variable; OCF_RESKEY_CRM_meta_notify_unpromoted_uname + single: OCF_RESKEY_CRM_meta_notify_unpromoted_uname + + OCF_RESKEY_CRM_meta_notify_unpromoted_uname + - Nodes on which resources are running in the unpromoted role + +Interpretation of Promotable Notification Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Pre-notification (demote):** + +* Active resources: ``$OCF_RESKEY_CRM_meta_notify_active_resource`` +* Promoted resources: ``$OCF_RESKEY_CRM_meta_notify_promoted_resource`` +* Unpromoted resources: ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource`` +* Inactive resources: ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` +* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + +**Post-notification (demote) / Pre-notification (stop):** + +* Active resources: ``$OCF_RESKEY_CRM_meta_notify_active_resource`` +* Promoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_promoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Unpromoted resources: ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource`` +* Inactive resources: ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` +* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` + +**Post-notification (stop) / Pre-notification (start)** + +* Active resources: + * ``$OCF_RESKEY_CRM_meta_notify_active_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Promoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_promoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Unpromoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Inactive resources: + * ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + +**Post-notification (start) / Pre-notification (promote)** + +* Active resources: + * ``$OCF_RESKEY_CRM_meta_notify_active_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Promoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_promoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Unpromoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Inactive resources: + * ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + +**Post-notification (promote)** + +* Active resources: + * ``$OCF_RESKEY_CRM_meta_notify_active_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Promoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_promoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Unpromoted resources: + * ``$OCF_RESKEY_CRM_meta_notify_unpromoted_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Inactive resources: + * ``$OCF_RESKEY_CRM_meta_notify_inactive_resource`` + * plus ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + * minus ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources to be promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Resources to be demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources to be stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` +* Resources that were started: ``$OCF_RESKEY_CRM_meta_notify_start_resource`` +* Resources that were promoted: ``$OCF_RESKEY_CRM_meta_notify_promote_resource`` +* Resources that were demoted: ``$OCF_RESKEY_CRM_meta_notify_demote_resource`` +* Resources that were stopped: ``$OCF_RESKEY_CRM_meta_notify_stop_resource`` + .. index:: single: resource agent; LSB single: LSB resource agent single: init script LSB Resource Agents (Init Scripts) ################################## LSB Compliance ______________ The relevant part of the `LSB specifications `_ includes a description of all the return codes listed here. Assuming `some_service` is configured correctly and currently inactive, the following sequence will help you determine if it is LSB-compatible: #. Start (stopped): .. code-block:: none # /etc/init.d/some_service start ; echo "result: $?" * Did the service start? * Did the echo command print ``result: 0`` (in addition to the init script's usual output)? #. Status (running): .. code-block:: none # /etc/init.d/some_service status ; echo "result: $?" * Did the script accept the command? * Did the script indicate the service was running? * Did the echo command print ``result: 0`` (in addition to the init script's usual output)? #. Start (running): .. code-block:: none # /etc/init.d/some_service start ; echo "result: $?" * Is the service still running? * Did the echo command print ``result: 0`` (in addition to the init script's usual output)? #. Stop (running): .. code-block:: none # /etc/init.d/some_service stop ; echo "result: $?" * Was the service stopped? * Did the echo command print ``result: 0`` (in addition to the init script's usual output)? #. Status (stopped): .. code-block:: none # /etc/init.d/some_service status ; echo "result: $?" * Did the script accept the command? * Did the script indicate the service was not running? * Did the echo command print ``result: 3`` (in addition to the init script's usual output)? #. Stop (stopped): .. code-block:: none # /etc/init.d/some_service stop ; echo "result: $?" * Is the service still stopped? * Did the echo command print ``result: 0`` (in addition to the init script's usual output)? #. Status (failed): This step is not readily testable and relies on manual inspection of the script. The script can use one of the error codes (other than 3) listed in the LSB spec to indicate that it is active but failed. This tells the cluster that before moving the resource to another node, it needs to stop it on the existing one first. If the answer to any of the above questions is no, then the script is not LSB-compliant. Your options are then to either fix the script or write an OCF agent based on the existing script. diff --git a/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 '' A complete set of CIB properties will look something like this: .. topic:: XML attributes set for a cib element .. code-block:: xml .. 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 ` (required) +* :ref:`CIB_server ` +* :ref:`CIB_user ` +* :ref:`CIB_passwd ` +* :ref:`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 ` + for connecting to a remote CIB instance; ignored if + :ref:`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 ` is set. + * - .. _CIB_passwd: + + .. index:: + single: CIB_passwd + single: environment variable; CIB_passwd + + CIB_passwd + - + - :ref:`$CIB_user `'s password. Read from the command line if + unset. Used with :ref:`CIB_port ` for connecting to a remote + CIB instance; ignored if :ref:`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 ` via this port. Ignored if + :ref:`CIB_shadow ` or :ref:`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 ` for + connecting to a remote CIB instance; ignored if + :ref:`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 `. Should be set only to the name + of a shadow CIB created by :ref:`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 ` is set; otherwise + ``$TMPDIR/.cib`` if :ref:`$TMPDIR ` is set to an absolute path; + otherwise ``/tmp/.cib`` + - If set, shadow files are created in this directory. Ignored if + :ref:`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 `, or the current + effective user otherwise + - If used with :ref:`CIB_port `, connect to + :ref:`$CIB_server ` as this user. Must be part of the + |CRM_DAEMON_GROUP| group on :ref:`$CIB_server `. Otherwise + (without :ref:`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 `. + * - .. _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 ` 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 `: 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 ` 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 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 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 .. 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 ` 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 .. 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 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 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 ` 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 Using Promotable Clone Resources in Ordered Sets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a promotable clone is used in a :ref:`resource set ` 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 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 .. 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 .. 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 `_ with any infrastructure it requires: the *bundle*. Pacemaker bundles support `Docker `_, `podman `_ *(since 2.0.1)*, and `rkt `_ container technologies. [#]_ .. topic:: A bundle for a containerized web server .. code-block:: xml 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 ```` 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 ` | | | | 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 `. | | | | 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 ` 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 ` -- a :ref:`promotable clone ` 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 ` 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 `. 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 ``=""``. 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 ` + - 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 ` - 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 ` - 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 ` - |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 ` - 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 ` - 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 ` - 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 ` - - *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 ` - - *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 ` - - *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 ` - - *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 ` - 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 ` for allowed subsystems. Example: ``PCMK_blackbox="pacemakerd,pacemaker-execd"`` * - .. _pcmk_trace_blackbox: .. index:: pair:: node option; PCMK_trace_blackbox PCMK_trace_blackbox - :ref:`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 ` - 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 ` - - 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 ` - - 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 ` - 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 ` - 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 ` - |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 ` - - 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 ` - 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 ` - 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 ` - |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 ` - 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 ` - 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 ` - 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 ` - 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 ` - 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 ` - |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 ` - |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 ` - 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 ` - 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 ` + - + - 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 ` + - + - 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 ` - - *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 # # .. || replace:: # # where occurrences of || in the rST will be substituted with 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 # " v 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 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 // gboolean, GList # include // xmlNode # include # include #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 enum cib_call_options * 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