diff --git a/doc/sphinx/Pacemaker_Administration/upgrading.rst b/doc/sphinx/Pacemaker_Administration/upgrading.rst index 687a875002..3cd13a5f52 100644 --- a/doc/sphinx/Pacemaker_Administration/upgrading.rst +++ b/doc/sphinx/Pacemaker_Administration/upgrading.rst @@ -1,535 +1,535 @@ .. index:: upgrade Upgrading a Pacemaker Cluster ----------------------------- .. index:: version Pacemaker Versioning #################### Pacemaker has an overall release version, plus separate version numbers for certain internal components. .. index:: single: version; release * **Pacemaker release version:** This version consists of three numbers (*x.y.z*). The major version number (the *x* in *x.y.z*) increases when at least some rolling upgrades are not possible from the previous major version. For example, a rolling upgrade from 1.0.8 to 1.1.15 should always be supported, but a rolling upgrade from 1.0.8 to 2.0.0 may not be possible. The minor version (the *y* in *x.y.z*) increases when there are significant changes in cluster default behavior, tool behavior, and/or the API interface (for software that utilizes Pacemaker libraries). The main benefit is to alert you to pay closer attention to the release notes, to see if you might be affected. The release counter (the *z* in *x.y.z*) is increased with all public releases of Pacemaker, which typically include both bug fixes and new features. .. index:: single: feature set single: version; feature set * **CRM feature set:** This version number applies to the communication between full cluster nodes, and is used to avoid problems in mixed-version clusters. The major version number increases when nodes with different versions would not work (rolling upgrades are not allowed). The minor version number increases when mixed-version clusters are allowed only during rolling upgrades. The minor-minor version number is ignored, but allows resource agents to detect cluster support for various features. [#]_ Pacemaker ensures that the longest-running node is the cluster's DC. This ensures new features are not enabled until all nodes are upgraded to support them. .. index:: single: version; Pacemaker Remote protocol * **Pacemaker Remote protocol version:** This version applies to communication between a Pacemaker Remote node and the cluster. It increases when an older cluster node would have problems hosting the connection to a newer Pacemaker Remote node. To avoid these problems, Pacemaker Remote nodes will accept connections only from cluster nodes with the same or newer Pacemaker Remote protocol version. Unlike with CRM feature set differences between full cluster nodes, mixed Pacemaker Remote protocol versions between Pacemaker Remote nodes and full cluster nodes are fine, as long as the Pacemaker Remote nodes have the older version. This can be useful, for example, to host a legacy application in an older operating system version used as a Pacemaker Remote node. .. index:: single: version; XML schema * **XML schema version:** Pacemaker’s configuration syntax — what's allowed in the Configuration Information Base (CIB) — has its own version. This allows the configuration syntax to evolve over time while still allowing clusters with older configurations to work without change. .. index:: single: upgrade; methods Upgrading Cluster Software ########################## There are three approaches to upgrading a cluster, each with advantages and disadvantages. .. table:: **Upgrade Methods** +---------------------------------------------------+----------+----------+--------+---------+----------+----------+ | Method | Available| Can be | Service| Service | Exercises| Allows | | | between | used with| outage | recovery| failover | change of| | | all | Pacemaker| during | during | logic | messaging| | | versions | Remote | upgrade| upgrade | | layer | | | | nodes | | | | [#]_ | +===================================================+==========+==========+========+=========+==========+==========+ | Complete cluster shutdown | yes | yes | always | N/A | no | yes | +---------------------------------------------------+----------+----------+--------+---------+----------+----------+ | Rolling (node by node) | no | yes | always | yes | yes | no | | | | | [#]_ | | | | +---------------------------------------------------+----------+----------+--------+---------+----------+----------+ | Detach and reattach | yes | no | only | no | no | yes | | | | | due to | | | | | | | | failure| | | | +---------------------------------------------------+----------+----------+--------+---------+----------+----------+ .. index:: single: upgrade; shutdown Complete Cluster Shutdown _________________________ In this scenario, one shuts down all cluster nodes and resources, then upgrades all the nodes before restarting the cluster. #. On each node: a. Shutdown the cluster software (pacemaker and the messaging layer). #. Upgrade the Pacemaker software. This may also include upgrading the messaging layer and/or the underlying operating system. #. Check the configuration with the ``crm_verify`` tool. #. On each node: a. Start the cluster software. Currently, only Corosync version 2 and greater is supported as the cluster layer, but if another stack is supported in the future, the stack does not need to be the same one before the upgrade. One variation of this approach is to build a new cluster on new hosts. This allows the new version to be tested beforehand, and minimizes downtime by having the new nodes ready to be placed in production as soon as the old nodes are shut down. .. index:: single: upgrade; rolling upgrade Rolling (node by node) ______________________ In this scenario, each node is removed from the cluster, upgraded, and then brought back online, until all nodes are running the newest version. Special considerations when planning a rolling upgrade: * If you plan to upgrade other cluster software -- such as the messaging layer -- at the same time, consult that software's documentation for its compatibility with a rolling upgrade. * If the major version number is changing in the Pacemaker version you are upgrading to, a rolling upgrade may not be possible. Read the new version's release notes (as well the information here) for what limitations may exist. * If the CRM feature set is changing in the Pacemaker version you are upgrading to, you should run a mixed-version cluster only during a small rolling upgrade window. If one of the older nodes drops out of the cluster for any reason, it will not be able to rejoin until it is upgraded. * If the Pacemaker Remote protocol version is changing, all cluster nodes should be upgraded before upgrading any Pacemaker Remote nodes. See the ClusterLabs wiki's `release calendar `_ to figure out whether the CRM feature set and/or Pacemaker Remote protocol version changed between the the Pacemaker release versions in your rolling upgrade. To perform a rolling upgrade, on each node in turn: #. Put the node into standby mode, and wait for any active resources to be moved cleanly to another node. (This step is optional, but allows you to deal with any resource issues before the upgrade.) #. Shutdown the cluster software (pacemaker and the messaging layer) on the node. #. Upgrade the Pacemaker software. This may also include upgrading the messaging layer and/or the underlying operating system. #. If this is the first node to be upgraded, check the configuration with the ``crm_verify`` tool. #. Start the messaging layer. This must be the same messaging layer (currently only Corosync version 2 and greater is supported) that the rest of the cluster is using. .. note:: Even if a rolling upgrade from the current version of the cluster to the newest version is not directly possible, it may be possible to perform a rolling upgrade in multiple steps, by upgrading to an intermediate version first. .. table:: **Version Compatibility Table** +-------------------------+---------------------------+ | Version being Installed | Oldest Compatible Version | +=========================+===========================+ | Pacemaker 2.y.z | Pacemaker 1.1.11 [#]_ | +-------------------------+---------------------------+ | Pacemaker 1.y.z | Pacemaker 1.0.0 | +-------------------------+---------------------------+ | Pacemaker 0.7.z | Pacemaker 0.6.z | +-------------------------+---------------------------+ .. index:: single: upgrade; detach and reattach Detach and Reattach ___________________ The reattach method is a variant of a complete cluster shutdown, where the resources are left active and get re-detected when the cluster is restarted. This method may not be used if the cluster contains any Pacemaker Remote nodes. #. Tell the cluster to stop managing services. This is required to allow the services to remain active after the cluster shuts down. .. code-block:: none # crm_attribute --name maintenance-mode --update true #. On each node, shutdown the cluster software (pacemaker and the messaging layer), and upgrade the Pacemaker software. This may also include upgrading the messaging layer. While the underlying operating system may be upgraded at the same time, that will be more likely to cause outages in the detached services (certainly, if a reboot is required). #. Check the configuration with the ``crm_verify`` tool. #. On each node, start the cluster software. Currently, only Corosync version 2 and greater is supported as the cluster layer, but if another stack is supported in the future, the stack does not need to be the same one before the upgrade. #. Verify that the cluster re-detected all resources correctly. #. Allow the cluster to resume managing resources again: .. code-block:: none # crm_attribute --name maintenance-mode --delete .. note:: While the goal of the detach-and-reattach method is to avoid disturbing running services, resources may still move after the upgrade if any resource's location is governed by a rule based on transient node attributes. Transient node attributes are erased when the node leaves the cluster. A common example is using the ``ocf:pacemaker:ping`` resource to set a node attribute used to locate other resources. .. index:: pair: upgrade; CIB Upgrading the Configuration ########################### The CIB schema version can change from one Pacemaker version to another. After cluster software is upgraded, the cluster will continue to use the older schema version that it was previously using. This can be useful, for example, when administrators have written tools that modify the configuration, and are based on the older syntax. [#]_ However, when using an older syntax, new features may be unavailable, and there is a performance impact, since the cluster must do a non-persistent configuration upgrade before each transition. So while using the old syntax is possible, it is not advisable to continue using it indefinitely. Even if you wish to continue using the old syntax, it is a good idea to follow the upgrade procedure outlined below, except for the last step, to ensure that the new software has no problems with your existing configuration (since it will perform much the same task internally). If you are brave, it is sufficient simply to run ``cibadmin --upgrade``. A more cautious approach would proceed like this: #. Create a shadow copy of the configuration. The later commands will automatically operate on this copy, rather than the live configuration. .. code-block:: none # crm_shadow --create shadow .. index:: single: configuration; verify #. Verify the configuration is valid with the new software (which may be stricter about syntax mistakes, or may have dropped support for deprecated features): .. code-block:: none # crm_verify --live-check #. Fix any errors or warnings. #. Perform the upgrade: .. code-block:: none # cibadmin --upgrade #. If this step fails, there are three main possibilities: a. The configuration was not valid to start with (did you do steps 2 and 3?). #. The transformation failed; `report a bug `_. #. The transformation was successful but produced an invalid result. If the result of the transformation is invalid, you may see a number of errors from the validation library. If these are not helpful, visit the `Validation FAQ wiki page `_ and/or try the manual upgrade procedure described below. #. Check the changes: .. code-block:: none # crm_shadow --diff If at this point there is anything about the upgrade that you wish to fine-tune (for example, to change some of the automatic IDs), now is the time to do so: .. code-block:: none # crm_shadow --edit This will open the configuration in your favorite editor (whichever is specified by the standard ``$EDITOR`` environment variable). #. Preview how the cluster will react: .. code-block:: none # crm_simulate --live-check --save-dotfile shadow.dot -S # dot -Tsvg shadow.dot -o shadow.svg You can then view shadow.svg with any compatible image viewer or web browser. Verify that either no resource actions will occur or that you are happy with any that are scheduled. If the output contains actions you do not expect (possibly due to changes to the score calculations), you may need to make further manual changes. See :ref:`crm_simulate` for further details on how to interpret the output of ``crm_simulate`` and ``dot``. #. Upload the changes: .. code-block:: none # crm_shadow --commit shadow --force In the unlikely event this step fails, please report a bug. .. note:: It is also possible to perform the configuration upgrade steps manually: #. Locate the ``upgrade*.xsl`` conversion scripts provided with the source code. These will often be installed in a location such as ``/usr/share/pacemaker``, or may be obtained from the - `source repository `_. + `source repository `_. #. Run the conversion scripts that apply to your older version, for example: .. code-block:: none # xsltproc /path/to/upgrade06.xsl config06.xml > config10.xml #. Locate the ``pacemaker.rng`` script (from the same location as the xsl files). #. Check the XML validity: .. code-block:: none # xmllint --relaxng /path/to/pacemaker.rng config10.xml The advantage of this method is that it can be performed without the cluster running, and any validation errors are often more informative. What Changed in 2.1 ################### The Pacemaker 2.1 release is fully backward-compatible in both the CIB XML and the C API. Highlights: * Pacemaker now supports the **OCF Resource Agent API version 1.1**. Most notably, the ``Master`` and ``Slave`` role names have been renamed to ``Promoted`` and ``Unpromoted``. * Pacemaker now supports colocations where the dependent resource does not affect the primary resource's placement (via a new ``influence`` colocation constraint option and ``critical`` resource meta-attribute). This is intended for cases where a less-important resource must be colocated with an essential resource, but it is preferred to leave the less-important resource stopped if it fails, rather than move both resources. * If Pacemaker is built with libqb 2.0 or later, the detail log will use **millisecond-resolution timestamps**. * In addition to crm_mon and stonith_admin, the crmadmin, crm_resource, crm_simulate, and crm_verify commands now support the ``--output-as`` and ``--output-to`` options, including **XML output** (which scripts and higher-level tools are strongly recommended to use instead of trying to parse the text output, which may change from release to release). For a detailed list of changes, see the release notes and the `Pacemaker 2.1 Changes `_ page on the ClusterLabs wiki. What Changed in 2.0 ################### The main goal of the 2.0 release was to remove support for deprecated syntax, along with some small changes in default configuration behavior and tool behavior. Highlights: * Only Corosync version 2 and greater is now supported as the underlying cluster layer. Support for Heartbeat and Corosync 1 (including CMAN) is removed. * The Pacemaker detail log file is now stored in ``/var/log/pacemaker/pacemaker.log`` by default. * The record-pending cluster property now defaults to true, which allows status tools such as crm_mon to show operations that are in progress. * Support for a number of deprecated build options, environment variables, and configuration settings has been removed. * The ``master`` tag has been deprecated in favor of using the ``clone`` tag with the new ``promotable`` meta-attribute set to ``true``. "Master/slave" clone resources are now referred to as "promotable" clone resources. * The public API for Pacemaker libraries that software applications can use has changed significantly. For a detailed list of changes, see the release notes and the `Pacemaker 2.0 Changes `_ page on the ClusterLabs wiki. What Changed in 1.0 ################### New ___ * Failure timeouts. * New section for resource and operation defaults. * Tool for making offline configuration changes. * ``Rules``, ``instance_attributes``, ``meta_attributes`` and sets of operations can be defined once and referenced in multiple places. * The CIB now accepts XPath-based create/modify/delete operations. See ``cibadmin --help``. * Multi-dimensional colocation and ordering constraints. * The ability to connect to the CIB from non-cluster machines. * Allow recurring actions to be triggered at known times. Changed _______ * Syntax * All resource and cluster options now use dashes (-) instead of underscores (_) * ``master_slave`` was renamed to ``master`` * The ``attributes`` container tag was removed * The operation field ``pre-req`` has been renamed ``requires`` * All operations must have an ``interval``, ``start``/``stop`` must have it set to zero * The ``stonith-enabled`` option now defaults to true. * The cluster will refuse to start resources if ``stonith-enabled`` is true (or unset) and no STONITH resources have been defined * The attributes of colocation and ordering constraints were renamed for clarity. * ``resource-failure-stickiness`` has been replaced by ``migration-threshold``. * The parameters for command-line tools have been made consistent * Switched to 'RelaxNG' schema validation and 'libxml2' parser * id fields are now XML IDs which have the following limitations: * id's cannot contain colons (:) * id's cannot begin with a number * id's must be globally unique (not just unique for that tag) * Some fields (such as those in constraints that refer to resources) are IDREFs. This means that they must reference existing resources or objects in order for the configuration to be valid. Removing an object which is referenced elsewhere will therefore fail. * The CIB representation, from which a MD5 digest is calculated to verify CIBs on the nodes, has changed. This means that every CIB update will require a full refresh on any upgraded nodes until the cluster is fully upgraded to 1.0. This will result in significant performance degradation and it is therefore highly inadvisable to run a mixed 1.0/0.6 cluster for any longer than absolutely necessary. * Ping node information no longer needs to be added to ``ha.cf``. Simply include the lists of hosts in your ping resource(s). Removed _______ * Syntax * It is no longer possible to set resource meta options as top-level attributes. Use meta-attributes instead. * Resource and operation defaults are no longer read from ``crm_config``. .. rubric:: Footnotes .. [#] Before CRM feature set 3.1.0 (Pacemaker 2.0.0), the minor-minor version number was treated the same as the minor version. .. [#] Currently, Corosync version 2 and greater is the only supported cluster stack, but other stacks have been supported by past versions, and may be supported by future versions. .. [#] Any active resources will be moved off the node being upgraded, so there will be at least a brief outage unless all resources can be migrated "live". .. [#] Rolling upgrades from Pacemaker 1.1.z to 2.y.z are possible only if the cluster uses corosync version 2 or greater as its messaging layer, and the Cluster Information Base (CIB) uses schema 1.0 or higher in its ``validate-with`` property. .. [#] As of Pacemaker 2.0.0, only schema versions pacemaker-1.0 and higher are supported (excluding pacemaker-1.1, which was an experimental schema now known as pacemaker-next). diff --git a/doc/sphinx/Pacemaker_Development/c.rst b/doc/sphinx/Pacemaker_Development/c.rst index 7a3a6bf309..9f00144bf4 100644 --- a/doc/sphinx/Pacemaker_Development/c.rst +++ b/doc/sphinx/Pacemaker_Development/c.rst @@ -1,924 +1,924 @@ .. index:: single: C pair: C; guidelines C Coding Guidelines ------------------- Pacemaker is a large project accepting contributions from developers with a wide range of skill levels and organizational affiliations, and maintained by multiple people over long periods of time. Following consistent guidelines makes reading, writing, and reviewing code easier, and helps avoid common mistakes. Some existing Pacemaker code does not follow these guidelines, for historical reasons and API backward compatibility, but new code should. Code Organization ################# Pacemaker's C code is organized as follows: +-----------------+-----------------------------------------------------------+ | Directory | Contents | +=================+===========================================================+ | daemons | the Pacemaker daemons (pacemakerd, pacemaker-based, etc.) | +-----------------+-----------------------------------------------------------+ | include | header files for library APIs | +-----------------+-----------------------------------------------------------+ | lib | libraries | +-----------------+-----------------------------------------------------------+ | tools | command-line tools | +-----------------+-----------------------------------------------------------+ Source file names should be unique across the entire project, to allow for individual tracing via ``PCMK_trace_files``. .. index:: single: C; library single: C library Pacemaker Libraries ################### +---------------+---------+---------------+---------------------------+-------------------------------------+ | Library | Symbol | Source | API Headers | Description | | | prefix | location | | | +===============+=========+===============+===========================+=====================================+ | libcib | cib | lib/cib | | include/crm/cib.h | .. index:: | | | | | | include/crm/cib/* | single: C library; libcib | | | | | | single: libcib | | | | | | | | | | | | API for pacemaker-based IPC and | | | | | | the CIB | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libcrmcluster | pcmk | lib/cluster | | include/crm/cluster.h | .. index:: | | | | | | include/crm/cluster/* | single: C library; libcrmcluster | | | | | | single: libcrmcluster | | | | | | | | | | | | Abstract interface to underlying | | | | | | cluster layer | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libcrmcommon | pcmk | lib/common | | include/crm/common/* | .. index:: | | | | | | some of include/crm/* | single: C library; libcrmcommon | | | | | | single: libcrmcommon | | | | | | | | | | | | Everything else | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libcrmservice | svc | lib/services | | include/crm/services.h | .. index:: | | | | | | single: C library; libcrmservice | | | | | | single: libcrmservice | | | | | | | | | | | | Abstract interface to supported | | | | | | resource types (OCF, LSB, etc.) | +---------------+---------+---------------+---------------------------+-------------------------------------+ | liblrmd | lrmd | lib/lrmd | | include/crm/lrmd*.h | .. index:: | | | | | | single: C library; liblrmd | | | | | | single: liblrmd | | | | | | | | | | | | API for pacemaker-execd IPC | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libpacemaker | pcmk | lib/pacemaker | | include/pacemaker*.h | .. index:: | | | | | | include/pcmki/* | single: C library; libpacemaker | | | | | | single: libpacemaker | | | | | | | | | | | | High-level APIs equivalent to | | | | | | command-line tool capabilities | | | | | | (and high-level internal APIs) | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libpe_rules | pe | lib/pengine | | include/crm/pengine/* | .. index:: | | | | | | single: C library; libpe_rules | | | | | | single: libpe_rules | | | | | | | | | | | | Scheduler functionality related | | | | | | to evaluating rules | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libpe_status | pe | lib/pengine | | include/crm/pengine/* | .. index:: | | | | | | single: C library; libpe_status | | | | | | single: libpe_status | | | | | | | | | | | | Low-level scheduler functionality | +---------------+---------+---------------+---------------------------+-------------------------------------+ | libstonithd | stonith | lib/fencing | | include/crm/stonith-ng.h| .. index:: | | | | | | include/crm/fencing/* | single: C library; libstonithd | | | | | | single: libstonithd | | | | | | | | | | | | API for pacemaker-fenced IPC | +---------------+---------+---------------+---------------------------+-------------------------------------+ Public versus Internal APIs ___________________________ Pacemaker libraries have both internal and public APIs. Internal APIs are those used only within Pacemaker; public APIs are those offered (via header files and documentation) for external code to use. Generic functionality needed by Pacemaker itself, such as string processing or XML processing, should remain internal, while functions providing useful high-level access to Pacemaker capabilities should be public. When in doubt, keep APIs internal, because it's easier to expose a previously internal API than hide a previously public API. Internal APIs can be changed as needed. The public API/ABI should maintain a degree of stability so that external applications using it do not need to be rewritten or rebuilt frequently. Many OSes/distributions avoid breaking API/ABI compatibility within a major release, so if Pacemaker breaks compatibility, that significantly delays when OSes can package the new version. Therefore, changes to public APIs should be backward-compatible (as detailed throughout this chapter), unless we are doing a (rare) release where we specifically intend to break compatibility. External applications known to use Pacemaker's public C API include `sbd `_ and dlm_controld. .. index:: pair: C; API documentation single: Doxygen API Documentation _________________ Pacemaker uses `Doxygen `_ to automatically generate its `online API documentation `_, so all public API (header files, functions, structs, enums, etc.) should be documented with Doxygen comment blocks. Other code may be documented in the same way if desired, with an ``\internal`` tag in the Doxygen comment. Simple example of an internal function with a Doxygen comment block: .. code-block:: c /*! * \internal * \brief Return string length plus 1 * * Return the number of characters in a given string, plus one. * * \param[in] s A string (must not be NULL) * * \return The length of \p s plus 1. */ static int f(const char *s) { return strlen(s) + 1; } API Header File Naming ______________________ * Internal API headers should be named ending in ``_internal.h``, in the same location as public headers, with the exception of libpacemaker, which for historical reasons keeps internal headers in ``include/pcmki/pcmki_*.h``). * If a library needs to share symbols just within the library, header files for these should be named ending in ``_private.h`` and located in the library source directory (not ``include``). Such functions should be declared as ``G_GNUC_INTERNAL``, to aid compiler efficiency (glib defines this symbol appropriately for the compiler). Header files that are not library API are located in the same locations as other source code. .. index:: pair: C; naming API Symbol Naming _________________ Exposed API symbols (non-``static`` function names, ``struct`` and ``typedef`` names in header files, etc.) must begin with the prefix appropriate to the library (shown in the table at the beginning of this section). This reduces the chance of naming collisions when external software links against the library. The prefix is usually lowercase but may be all-caps for some defined constants and macros. Public API symbols should follow the library prefix with a single underbar (for example, ``pcmk_something``), and internal API symbols with a double underbar (for example, ``pcmk__other_thing``). File-local symbols (such as static functions) and non-library code do not require a prefix, though a unique prefix indicating an executable (controld, crm_mon, etc.) can be helpful to indicate symbols shared between multiple source files for the executable. Public API Deprecation ______________________ Public APIs may not be removed in most Pacemaker releases, but they may be deprecated. When a public API is deprecated, it is moved to a header whose name ends in ``compat.h``. The original header includes the compatibility header only if the ``PCMK_ALLOW_DEPRECATED`` symbol is undefined or defined to 1. This allows external code to continue using the deprecated APIs, but internal code is prevented from using them because the ``crm_internal.h`` header defines the symbol to 0. .. index:: pair: C; boilerplate pair: license; C pair: copyright; C C Boilerplate ############# Every C file should start with a short copyright and license notice: .. code-block:: c /* * Copyright the Pacemaker project contributors * * The version control history for this file may have further details. * * This source code is licensed under WITHOUT ANY WARRANTY. */ ** should follow the policy set forth in the -`COPYING `_ file, +`COPYING `_ file, generally one of "GNU General Public License version 2 or later (GPLv2+)" or "GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)". Header files should additionally protect against multiple inclusion by defining a unique symbol of the form ``PCMK____H``. For example: .. code-block:: c #ifndef PCMK__MY_HEADER__H # define PCMK__MY_HEADER__H // header code here #endif // PCMK__MY_HEADER__H Public API header files should additionally declare "C" compatibility for inclusion by C++, and give a Doxygen file description. For example: .. code-block:: c #ifdef __cplusplus extern "C" { #endif /*! * \file * \brief My brief description here * \ingroup core */ // header code here #ifdef __cplusplus } #endif .. index:: pair: C; whitespace Line Formatting ############### * Indentation must be 4 spaces, no tabs. * Do not leave trailing whitespace. * Lines should be no longer than 80 characters unless limiting line length hurts readability. .. index:: pair: C; comment Comments ######## .. code-block:: c /* Single-line comments may look like this */ // ... or this /* Multi-line comments should start immediately after the comment opening. * Subsequent lines should start with an aligned asterisk. The comment * closing should be aligned and on a line by itself. */ .. index:: single: C; pointer Variables ######### * Pointers: .. code-block:: c /* (1) The asterisk goes by the variable name, not the type; * (2) Avoid leaving pointers uninitialized, to lessen the impact of * use-before-assignment bugs */ char *my_string = NULL; // Use space before asterisk and after closing parenthesis in a cast char *foo = (char *) bar; * Global variables should be avoided in libraries when possible. State information should instead be passed as function arguments (often as a structure). This is not for thread safety -- Pacemaker's use of forking ensures it will never be threaded -- but it does minimize overhead, improve readability, and avoid obscure side effects. * Time intervals are sometimes represented in Pacemaker code as user-defined text specifications (for example, "10s"), other times as an integer number of seconds or milliseconds, and still other times as a string representation of an integer number. Variables for these should be named with an indication of which is being used (for example, use ``interval_spec``, ``interval_ms``, or ``interval_ms_s`` instead of ``interval``). .. index:: pair: C; operator Operators ######### .. code-block:: c // Operators have spaces on both sides x = a; /* (1) Do not rely on operator precedence; use parentheses when mixing * operators with different priority, for readability. * (2) No space is used after an opening parenthesis or before a closing * parenthesis. */ x = a + b - (c * d); .. index:: single: C; if single: C; else single: C; while single: C; for single: C; switch Control Statements (if, else, while, for, switch) ################################################# .. code-block:: c /* * (1) The control keyword is followed by a space, a left parenthesis * without a space, the condition, a right parenthesis, a space, and the * opening bracket on the same line. * (2) Always use braces around control statement blocks, even if they only * contain one line. This makes code review diffs smaller if a line gets * added in the future, and avoids the chance of bad indenting making a * line incorrectly appear to be part of the block. * (3) The closing bracket is on a line by itself. */ if (v < 0) { return 0; } /* "else" and "else if" are on the same line with the previous ending brace * and next opening brace, separated by a space. Blank lines may be used * between blocks to help readability. */ if (v > 0) { return 0; } else if (a == 0) { return 1; } else { return 2; } /* Do not use assignments in conditions. This ensures that the developer's * intent is always clear, makes code reviews easier, and reduces the chance * of using assignment where comparison is intended. */ // Do this ... a = f(); if (a) { return 0; } // ... NOT this if (a = f()) { return 0; } /* It helps readability to use the "!" operator only in boolean * comparisons, and explicitly compare numeric values against 0, * pointers against NULL, etc. This helps remind the reader of the * type being compared. */ int i = 0; char *s = NULL; bool cond = false; if (!cond) { return 0; } if (i == 0) { return 0; } if (s == NULL) { return 0; } /* In a "switch" statement, indent "case" one level, and indent the body of * each "case" another level. */ switch (expression) { case 0: command1; break; case 1: command2; break; default: command3; break; } .. index:: single: C; struct Structures ########## Changes to structures defined in public API headers (adding or removing members, or changing member types) are generally not possible without breaking API compatibility. However, there are exceptions: * Public API structures can be designed such that they can be allocated only via API functions, not declared directly or allocated with standard memory functions using ``sizeof``. * This can be enforced simply by documentating the limitation, in which case new ``struct`` members can be added to the end of the structure without breaking compatibility. * Alternatively, the structure definition can be kept in an internal header, with only a pointer type definition kept in a public header, in which case the structure definition can be changed however needed. .. index:: single: C; enum Enumerations ############ * Enumerations should not have a ``typedef``, and do not require any naming convention beyond what applies to all exposed symbols. * New values should usually be added to the end of public API enumerations, because the compiler will define the values to 0, 1, etc., in the order given, and inserting a value in the middle would change the numerical values of all later values, breaking code compiled with the old values. However, if enum numerical values are explicitly specified rather than left to the compiler, new values can be added anywhere. * When defining constant integer values, enum should be preferred over ``#define`` or ``const`` when possible. This allows type checking without consuming memory. Flag groups ___________ Pacemaker often uses flag groups (also called bit fields or bitmasks) for a collection of boolean options (flags/bits). This is more efficient for storage and manipulation than individual booleans, but its main advantage is when used in public APIs, because using another bit in a bitmask is backward compatible, whereas adding a new function argument (or sometimes even a structure member) is not. .. code-block:: c #include /* (1) Define an enumeration to name the individual flags, for readability. * An enumeration is preferred to a series of "#define" constants * because it is typed, and logically groups the related names. * (2) Define the values using left-shifting, which is more readable and * less error-prone than hexadecimal literals (0x0001, 0x0002, 0x0004, * etc.). * (3) Using a comma after the last entry makes diffs smaller for reviewing * if a new value needs to be added or removed later. */ enum pcmk__some_bitmask_type { pcmk__some_value = (1 << 0), pcmk__other_value = (1 << 1), pcmk__another_value = (1 << 2), }; /* The flag group itself should be an unsigned type from stdint.h (not * the enum type, since it will be a mask of the enum values and not just * one of them). uint32_t is the most common, since we rarely need more than * 32 flags, but a smaller or larger type could be appropriate in some * cases. */ uint32_t flags = pcmk__some_value|pcmk__other_value; /* If the values will be used only with uint64_t, define them accordingly, * to make compilers happier. */ enum pcmk__something_else { pcmk__whatever = (UINT64_C(1) << 0), }; We have convenience functions for checking flags (see ``pcmk_any_flags_set()``, ``pcmk_all_flags_set()``, and ``pcmk_is_set()``) as well as setting and clearing them (see ``pcmk__set_flags_as()`` and ``pcmk__clear_flags_as()``, usually used via wrapper macros defined for specific flag groups). These convenience functions should be preferred to direct bitwise arithmetic, for readability and logging consistency. .. index:: pair: C; booleans pair: C; bool pair: C; gboolean Booleans ######## Boolean Types _____________ Booleans in C can be represented by an integer type, ``bool``, or ``gboolean``. Integers are sometimes useful for storing booleans when they must be converted to and from a string, such as an XML attribute value (for which ``crm_element_value_int()`` can be used). Integer booleans use 0 for false and nonzero (usually 1) for true. ``gboolean`` should be used with glib APIs that specify it. ``gboolean`` should always be used with glib's ``TRUE`` and ``FALSE`` constants. Otherwise, ``bool`` should be preferred. ``bool`` should be used with the ``true`` and ``false`` constants from the ``stdbool.h`` header. Testing Booleans ________________ Do not use equality operators when testing booleans. For example: .. code-block:: c // Do this if (bool1) { fn(); } if (!bool2) { fn2(); } // Not this if (bool1 == true) { fn(); } if (bool2 == false) { fn2(); } // Otherwise there's no logical end ... if ((bool1 == false) == true) { fn(); } Conversely, equality operators *should* be used with non-boolean variables, even when just testing zero or nonzero: .. code-block:: c int var1 = fn(); // Prefer this, because it gives a hint to the type when reading it if (var1 == 0) { fn2(); } // Not this, because a reader could mistakenly assume it is a boolean if (!var1) { fn2(); } .. index:: pair: C; function Functions ######### Function names should be unique across the entire project, to allow for individual tracing via ``PCMK_trace_functions``, and make it easier to search code and follow detail logs. Function Definitions ____________________ .. code-block:: c /* * (1) The return type goes on its own line * (2) The opening brace goes by itself on a line * (3) Use "const" with pointer arguments whenever appropriate, to allow the * function to be used by more callers. */ int my_func1(const char *s) { return 0; } /* Functions with no arguments must explicitly list them as void, * for compatibility with strict compilers */ int my_func2(void) { return 0; } /* * (1) For functions with enough arguments that they must break to the next * line, align arguments with the first argument. * (2) When a function argument is a function itself, use the pointer form. * (3) Declare functions and file-global variables as ``static`` whenever * appropriate. This gains a slight efficiency in shared libraries, and * helps the reader know that it is not used outside the one file. */ static int my_func3(int bar, const char *a, const char *b, const char *c, void (*callback)()) { return 0; } Return Values _____________ Functions that need to indicate success or failure should follow one of the following guidelines. More details, including functions for using them in user messages and converting from one to another, can be found in ``include/crm/common/results.h``. * A **standard Pacemaker return code** is one of the ``pcmk_rc_*`` enum values or a system errno code, as an ``int``. * ``crm_exit_t`` (the ``CRM_EX_*`` enum values) is a system-independent code suitable for the exit status of a process, or for interchange between nodes. * Other special-purpose status codes exist, such as ``enum ocf_exitcode`` for the possible exit statuses of OCF resource agents (along with some Pacemaker-specific extensions). It is usually obvious when the context calls for such. * Some older Pacemaker APIs use the now-deprecated "legacy" return values of ``pcmk_ok`` or the positive or negative value of one of the ``pcmk_err_*`` constants or system errno codes. * Functions registered with external libraries (as callbacks for example) should use the appropriate signature defined by those libraries, rather than follow Pacemaker guidelines. Of course, functions may have return values that aren't success/failure indicators, such as a pointer, integer count, or bool. Public API Functions ____________________ Unless we are doing a (rare) release where we break public API compatibility, new public API functions can be added, but existing function signatures (return type, name, and argument types) should not be changed. To work around this, an existing function can become a wrapper for a new function. .. index:: pair: C; memory Memory Management ################# * Always use ``calloc()`` rather than ``malloc()``. It has no additional cost on modern operating systems, and reduces the severity and security risks of uninitialized memory usage bugs. * Ensure that all dynamically allocated memory is freed when no longer needed, and not used after it is freed. This can be challenging in the more event-driven, callback-oriented sections of code. * Free dynamically allocated memory using the free function corresponding to how it was allocated. For example, use ``free()`` with ``calloc()``, and ``g_free()`` with most glib functions that allocate objects. .. index:: pair: C; logging pair: C; output Logging and Output ################## Logging Vs. Output __________________ Log messages and output messages are logically similar but distinct. Oversimplifying a bit, daemons log, and tools output. Log messages are intended to help with troubleshooting and debugging. They may have a high level of technical detail, and are usually filtered by severity -- for example, the system log by default gets messages of notice level and higher. Output is intended to let the user know what a tool is doing, and is generally terser and less technical, and may even be parsed by scripts. Output might have "verbose" and "quiet" modes, but it is not filtered by severity. Common Guidelines for All Messages __________________________________ * When format strings are used for derived data types whose implementation may vary across platforms (``pid_t``, ``time_t``, etc.), the safest approach is to use ``%lld`` in the format string, and cast the value to ``long long``. * Do not rely on ``%s`` handling ``NULL`` values properly. While the standard library functions might, not all Pacemaker API using them does, and it's safest to get in the habit of always ensuring format values are non-NULL. For debug and trace messages, the ``crm_str()`` macro is sufficient and will map NULL to the string "", but for other messages an understandable string appropriate to the context should be used when the value is NULL. * The convenience macros ``pcmk__plural_s()`` and ``pcmk__plural_alt()`` are handy when logging a word that may be singular or plural. Logging _______ Pacemaker uses libqb for logging, but wraps it with a higher level of functionality (see ``include/crm/common/logging*h``). A few macros ``crm_err()``, ``crm_warn()``, etc. do most of the heavy lifting. By default, Pacemaker sends logs at notice level and higher to the system log, and logs at info level and higher to the detail log (typically ``/var/log/pacemaker/pacemaker.log``). The intent is that most users will only ever need the system log, but for deeper troubleshooting and developer debugging, the detail log may be helpful, at the cost of being more technical and difficult to follow. The same message can have more detail in the detail log than in the system log, using libqb's "extended logging" feature: .. code-block:: c /* The following will log a simple message in the system log, like: warning: Action failed: Node not found with extra detail in the detail log, like: warning: Action failed: Node not found | rc=-1005 id=hgjjg-51006 */ crm_warn("Action failed: %s " CRM_XS " rc=%d id=%s", pcmk_rc_str(rc), rc, id); Output ______ Pacemaker has a somewhat complicated system for tool output. The main benefit is that the user can select the output format with the ``--output-as`` option (usually "text" for human-friendly output or "xml" for reliably script-parsable output, though ``crm_mon`` additionally supports "console" and "html"). A custom message can be defined with a unique string identifier, plus implementation functions for each supported format. The caller invokes the message using the identifier. The user selects the output format via ``--output-as``, and the output code automatically calls the appropriate implementation function. The interface (most importantly ``pcmk__output_t``) is declared in ``include/crm/common/output*h``. See the API comments and existing tools for examples. .. index:: pair: C; strings String Handling ############### Define Constants for Magic Strings __________________________________ A "magic" string is one used for control purposes rather than human reading, and which must be exactly the same every time it is used. Examples would be configuration option names, XML attribute names, or environment variable names. These should always be defined constants, rather than using the string literal everywhere. If someone mistypes a defined constant, the code won't compile, but if they mistype a literal, it could go unnoticed until a user runs into a problem. Library Functions _________________ Pacemaker's libcrmcommon has a large number of functions to assist in string handling. The most commonly used ones are: * ``pcmk__str_eq()`` tests string equality (similar to ``strcmp()``), but can handle NULL, and takes options for case-insensitive, whether NULL should be considered a match, etc. * ``crm_strdup_printf()`` takes ``printf()``-style arguments and creates a string from them (dynamically allocated, so it must be freed with ``free()``). It asserts on memory failure, so the return value is always non-NULL. String handling functions should almost always be internal API, since Pacemaker isn't intended to be used as a general-purpose library. Most are declared in ``include/crm/common/strings_internal.h``. ``util.h`` has some older ones that are public API (for now, but will eventually be made internal). char*, gchar*, and GString __________________________ When using dynamically allocated strings, be careful to always use the appropriate free function. * ``char*`` strings allocated with something like ``calloc()`` must be freed with ``free()``. Most Pacemaker library functions that allocate strings use this implementation. * glib functions often use ``gchar*`` instead, which must be freed with ``g_free()``. * Occasionally, it's convenient to use glib's flexible ``GString*`` type, which must be freed with ``g_string_free()``. .. index:: pair: C; regular expression Regular Expressions ################### - Use ``REG_NOSUB`` with ``regcomp()`` whenever possible, for efficiency. - Be sure to use ``regfree()`` appropriately. .. index:: single: Makefile.am Makefiles ######### Pacemaker uses `automake `_ for building, so the Makefile.am in each directory should be edited rather than Makefile.in or Makefile, which are automatically generated. * Public API headers are installed (by adding them to a ``HEADERS`` variable in ``Makefile.am``), but internal API headers are not (by adding them to ``noinst_HEADERS``). .. index:: pair: C; vim settings vim Settings ############ Developers who use ``vim`` to edit source code can add the following settings to their ``~/.vimrc`` file to follow Pacemaker C coding guidelines: .. code-block:: none " follow Pacemaker coding guidelines when editing C source code files filetype plugin indent on au FileType c setlocal expandtab tabstop=4 softtabstop=4 shiftwidth=4 textwidth=80 autocmd BufNewFile,BufRead *.h set filetype=c let c_space_errors = 1 diff --git a/doc/sphinx/Pacemaker_Development/faq.rst b/doc/sphinx/Pacemaker_Development/faq.rst index 7d4bbd5ccd..f38d3e5d7b 100644 --- a/doc/sphinx/Pacemaker_Development/faq.rst +++ b/doc/sphinx/Pacemaker_Development/faq.rst @@ -1,166 +1,166 @@ Frequently Asked Questions -------------------------- :Q: Who is this document intended for? :A: Anyone who wishes to read and/or edit the Pacemaker source code. Casual contributors should feel free to read just this FAQ, and consult other chapters as needed. ---- .. index:: single: download single: source code single: git single: git; GitHub :Q: Where is the source code for Pacemaker? :A: The `source code for Pacemaker `_ is kept on `GitHub `_, as are all software projects under the `ClusterLabs `_ umbrella. Pacemaker uses `Git `_ for source code management. If you are a Git newbie, the `gittutorial(7) man page `_ is an excellent starting point. If you're familiar with using Git from the command line, you can create a local copy of the Pacemaker source code with: **git clone https://github.com/ClusterLabs/pacemaker.git** ---- .. index:: single: git; branch :Q: What are the different Git branches and repositories used for? -:A: * The `master branch `_ +:A: * The `main branch `_ is the primary branch used for development. * The `2.1 branch `_ is the current release branch. Normally, it does not receive any changes, but during the release cycle for a new release, it will contain release candidates. During the release cycle, certain bug fixes will go to the - 2.1 branch first (and be pulled into master later). + 2.1 branch first (and be pulled into main later). * The `2.0 branch `_, `1.1 branch `_, and separate `1.0 repository `_ are frozen snapshots of earlier release series, no longer being developed. * Messages will be posted to the `developers@ClusterLabs.org `_ mailing list during the release cycle, with instructions about which branches to use when submitting requests. ---- :Q: How do I build from the source code? -:A: See `INSTALL.md `_ +:A: See `INSTALL.md `_ in the main checkout directory. ---- :Q: What coding style should I follow? :A: You'll be mostly fine if you simply follow the example of existing code. When unsure, see the relevant chapter of this document for language-specific recommendations. Pacemaker has grown and evolved organically over many years, so you will see much code that doesn't conform to the current guidelines. We discourage making changes solely to bring code into conformance, as any change requires developer time for review and opens the possibility of adding bugs. However, new code should follow the guidelines, and it is fine to bring lines of older code into conformance when modifying that code for other reasons. ---- .. index:: single: git; commit message :Q: How should I format my Git commit messages? :A: An example is "Feature: scheduler: wobble the frizzle better". * The first part is the type of change, used to automatically generate the change log for the next release. Commit messages with the following will be included in the change log: * **Feature** for new features * **Fix** for bug fixes (**Bug** or **High** also work) * **API** for changes to the public API Everything else will *not* automatically be in the change log, and so don't really matter, but types commonly used include: * **Log** for changes to log messages or handling * **Doc** for changes to documentation or comments * **Test** for changes in CTS and regression tests * **Low**, **Med**, or **Mid** for bug fixes not significant enough for a change log entry * **Refactor** for refactoring-only code changes * **Build** for build process changes * The next part is the name of the component(s) being changed, for example, **controller** or **libcrmcommon** (it's more free-form, so don't sweat getting it exact). * The rest briefly describes the change. The git project recommends the entire summary line stay under 50 characters, but more is fine if needed for clarity. * Except for the most simple and obvious of changes, the summary should be followed by a blank line and a longer explanation of *why* the change was made. ---- :Q: How can I test my changes? :A: The source repository has some unit tests for simple functions, though this is a recent effort without much coverage yet. Pacemaker's Cluster Test Suite (CTS) has regression tests for most major components; these will automatically be run for any pull requests submitted through GitHub, and are sufficient for most changes. Additionally, CTS has a lab component that can be used to set up a test cluster and run a wide variety of complex tests, for testing major changes. See cts/README.md in the source repository for details. ---- .. index:: license :Q: What is Pacemaker's license? :A: Except where noted otherwise in the file itself, the source code for all Pacemaker programs is licensed under version 2 or later of the GNU General Public License (`GPLv2+ `_), its headers and libraries under version 2.1 or later of the less restrictive GNU Lesser General Public License (`LGPLv2.1+ `_), its documentation under version 4.0 or later of the Creative Commons Attribution-ShareAlike International Public License (`CC-BY-SA-4.0 `_), and its init scripts under the `Revised BSD `_ license. If you find any deviations from this policy, or wish to inquire about alternate licensing arrangements, please e-mail the `developers@ClusterLabs.org `_ mailing list. Licensing issues are also discussed on the `ClusterLabs wiki `_. ---- :Q: How can I contribute my changes to the project? :A: Contributions of bug fixes or new features are very much appreciated! Patches can be submitted as `pull requests `_ via GitHub (the preferred method, due to its excellent `features `_), or e-mailed to the `developers@ClusterLabs.org `_ mailing list as an attachment in a format Git can import. Authors may only submit changes that they have the right to submit under the open source license indicated in the affected files. ---- .. index:: mailing list :Q: What if I still have questions? :A: Ask on the `developers@ClusterLabs.org `_ mailing list for development-related questions, or on the `users@ClusterLabs.org `_ mailing list for general questions about using Pacemaker. Developers often also hang out on the [ClusterLabs IRC channel](https://wiki.clusterlabs.org/wiki/ClusterLabs_IRC_channel). diff --git a/doc/sphinx/Pacemaker_Development/python.rst b/doc/sphinx/Pacemaker_Development/python.rst index d73dc91566..54e6c55a54 100644 --- a/doc/sphinx/Pacemaker_Development/python.rst +++ b/doc/sphinx/Pacemaker_Development/python.rst @@ -1,81 +1,81 @@ .. index:: single: Python pair: Python; guidelines Python Coding Guidelines ------------------------ .. index:: pair: Python; boilerplate pair: license; Python pair: copyright; Python .. _s-python-boilerplate: Python Boilerplate ################## If a Python file is meant to be executed (as opposed to imported), it should have a ``.in`` extension, and its first line should be: .. code-block:: python #!@PYTHON@ which will be replaced with the appropriate python executable when Pacemaker is built. To make that happen, add an entry to ``CONFIG_FILES_EXEC()`` in ``configure.ac``, and add the file name without ``.in`` to ``.gitignore`` (see existing examples). After the above line if any, every Python file should start like this: .. code-block:: python """ """ __copyright__ = "Copyright the Pacemaker project contributors" __license__ = " WITHOUT ANY WARRANTY" ** is obviously a brief description of the file's purpose. The string may contain any other information typically used in a Python file `docstring `_. ```` should follow the policy set forth in the -`COPYING `_ file, +`COPYING `_ file, generally one of "GNU General Public License version 2 or later (GPLv2+)" or "GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)". .. index:: single: Python; 3 single: Python; version Python Version Compatibility ############################ Pacemaker targets compatibility with Python 3.4 and later. Do not use features not available in all targeted Python versions. An example is the ``subprocess.run()`` function. .. index:: pair: Python; whitespace Formatting Python Code ###################### * Indentation must be 4 spaces, no tabs. * Do not leave trailing whitespace. * Lines should be no longer than 80 characters unless limiting line length significantly impacts readability. For Python, this limitation is flexible since breaking a line often impacts readability, but definitely keep it under 120 characters. * Where not conflicting with this style guide, it is recommended (but not required) to follow `PEP 8 `_. * It is recommended (but not required) to format Python code such that ``pylint --disable=line-too-long,too-many-lines,too-many-instance-attributes,too-many-arguments,too-many-statements`` produces minimal complaints (even better if you don't need to disable all those checks). diff --git a/doc/sphinx/Pacemaker_Explained/resources.rst b/doc/sphinx/Pacemaker_Explained/resources.rst index 2737354bc7..c86559d655 100644 --- a/doc/sphinx/Pacemaker_Explained/resources.rst +++ b/doc/sphinx/Pacemaker_Explained/resources.rst @@ -1,1063 +1,1063 @@ .. _resource: Cluster Resources ----------------- .. _s-resource-primitive: What is a Cluster Resource? ########################### .. index:: single: resource A resource is a service made highly available by a cluster. The simplest type of resource, a *primitive* resource, is described in this chapter. More complex forms, such as groups and clones, are described in later chapters. Every primitive resource has a *resource agent*. A resource agent is an external program that abstracts the service it provides and present a consistent view to the cluster. This allows the cluster to be agnostic about the resources it manages. The cluster doesn't need to understand how the resource works because it relies on the resource agent to do the right thing when given a **start**, **stop** or **monitor** command. For this reason, it is crucial that resource agents are well-tested. Typically, resource agents come in the form of shell scripts. However, they can be written using any technology (such as C, Python or Perl) that the author is comfortable with. .. _s-resource-supported: .. index:: single: resource; class Resource Classes ################ Pacemaker supports several classes of agents: * OCF * LSB * Systemd * Upstart (deprecated) * Service * Fencing * Nagios Plugins .. index:: single: resource; OCF single: OCF; resources single: Open Cluster Framework; resources Open Cluster Framework ______________________ The OCF standard [#]_ is basically an extension of the Linux Standard Base conventions for init scripts to: * support parameters, * make them self-describing, and * make them extensible OCF specs have strict definitions of the exit codes that actions must return [#]_. The cluster follows these specifications exactly, and giving the wrong exit code will cause the cluster to behave in ways you will likely find puzzling and annoying. In particular, the cluster needs to distinguish a completely stopped resource from one which is in some erroneous and indeterminate state. Parameters are passed to the resource agent as environment variables, with the special prefix ``OCF_RESKEY_``. So, a parameter which the user thinks of as ``ip`` will be passed to the resource agent as ``OCF_RESKEY_ip``. The number and purpose of the parameters is left to the resource agent; however, the resource agent should use the **meta-data** command to advertise any that it supports. The OCF class is the most preferred as it is an industry standard, highly flexible (allowing parameters to be passed to agents in a non-positional manner) and self-describing. For more information, see the `reference `_ and the *Resource Agents* chapter of *Pacemaker Administration*. .. index:: single: resource; LSB single: LSB; resources single: Linux Standard Base; resources Linux Standard Base ___________________ *LSB* resource agents are more commonly known as *init scripts*. If a full path is not given, they are assumed to be located in ``/etc/init.d``. Commonly, they are provided by the OS distribution. In order to be used with a Pacemaker cluster, they must conform to the LSB specification [#]_. .. warning:: Many distributions or particular software packages claim LSB compliance but ship with broken init scripts. For details on how to check whether your init script is LSB-compatible, see the `Resource Agents` chapter of `Pacemaker Administration`. Common problematic violations of the LSB standard include: * Not implementing the ``status`` operation at all * Not observing the correct exit status codes for ``start``/``stop``/``status`` actions * Starting a started resource returns an error * Stopping a stopped resource returns an error .. important:: Remember to make sure the computer is `not` configured to start any services at boot time -- that should be controlled by the cluster. .. _s-resource-supported-systemd: .. index:: single: Resource; Systemd single: Systemd; resources Systemd _______ Most Linux distributions have replaced the old `SysV `_ style of initialization daemons and scripts with `Systemd `_. Pacemaker is able to manage these services `if they are present`. Instead of init scripts, systemd has `unit files`. Generally, the services (unit files) are provided by the OS distribution, but there are online guides for converting from init scripts [#]_. .. important:: Remember to make sure the computer is `not` configured to start any services at boot time -- that should be controlled by the cluster. .. index:: single: Resource; Upstart single: Upstart; resources Upstart _______ Some distributions replaced the old `SysV `_ style of initialization daemons (and scripts) with `Upstart `_. Pacemaker is able to manage these services `if they are present`. Instead of init scripts, Upstart has `jobs`. Generally, the services (jobs) are provided by the OS distribution. .. important:: Remember to make sure the computer is `not` configured to start any services at boot time -- that should be controlled by the cluster. .. warning:: Upstart support is deprecated in Pacemaker. Upstart is no longer an actively maintained project, and test platforms for it are no longer readily usable. Support will likely be dropped entirely at the next major release of Pacemaker. .. index:: single: Resource; System Services single: System Service; resources System Services _______________ Since there are various types of system services (``systemd``, ``upstart``, and ``lsb``), Pacemaker supports a special ``service`` alias which intelligently figures out which one applies to a given cluster node. This is particularly useful when the cluster contains a mix of ``systemd``, ``upstart``, and ``lsb``. In order, Pacemaker will try to find the named service as: * an LSB init script * a Systemd unit file * an Upstart job .. index:: single: Resource; STONITH single: STONITH; resources STONITH _______ The STONITH class is used exclusively for fencing-related resources. This is discussed later in :ref:`fencing`. .. index:: single: Resource; Nagios Plugins single: Nagios Plugins; resources Nagios Plugins ______________ Nagios Plugins [#]_ are a way to monitor services. Pacemaker can use these as resources, to react to a change in the service's status. To use plugins as resources, Pacemaker must have been built with support, and OCF-style meta-data for the plugins must be installed on nodes that can run them. Meta-data for several common plugins is provided by the `nagios-agents-metadata `_ project. The supported parameters for such a resource are same as the long options of the plugin. Start and monitor actions for plugin resources are implemented as invoking the plugin. A plugin result of "OK" (0) is treated as success, a result of "WARN" (1) is treated as a successful but degraded service, and any other result is considered a failure. A plugin resource is not going to change its status after recovery by restarting the plugin, so using them alone does not make sense with ``on-fail`` set (or left to default) to ``restart``. Another value could make sense, for example, if you want to fence or standby nodes that cannot reach some external service. A more common use case for plugin resources is to configure them with a ``container`` meta-attribute set to the name of another resource that actually makes the service available, such as a virtual machine or container. With ``container`` set, the plugin resource will automatically be colocated with the containing resource and ordered after it, and the containing resource will be considered failed if the plugin resource fails. This allows monitoring of a service inside a virtual machine or container, with recovery of the virtual machine or container if the service fails. Configuring a virtual machine as a guest node, or a container as a :ref:`bundle `, is the preferred way of monitoring a service inside, but plugin resources can be useful when it is not practical to modify the virtual machine or container image for this purpose. .. _primitive-resource: Resource Properties ################### These values tell the cluster which resource agent to use for the resource, where to find that resource agent and what standards it conforms to. .. table:: **Properties of a Primitive Resource** +----------+------------------------------------------------------------------+ | Field | Description | +==========+==================================================================+ | id | .. index:: | | | single: id; resource | | | single: resource; property, id | | | | | | Your name for the resource | +----------+------------------------------------------------------------------+ | class | .. index:: | | | single: class; resource | | | single: resource; property, class | | | | | | The standard the resource agent conforms to. Allowed values: | | | ``lsb``, ``nagios``, ``ocf``, ``service``, ``stonith``, | | | ``systemd``, ``upstart`` | +----------+------------------------------------------------------------------+ | type | .. index:: | | | single: type; resource | | | single: resource; property, type | | | | | | The name of the Resource Agent you wish to use. E.g. | | | ``IPaddr`` or ``Filesystem`` | +----------+------------------------------------------------------------------+ | provider | .. index:: | | | single: provider; resource | | | single: resource; property, provider | | | | | | The OCF spec allows multiple vendors to supply the same resource | | | agent. To use the OCF resource agents supplied by the Heartbeat | | | project, you would specify ``heartbeat`` here. | +----------+------------------------------------------------------------------+ The XML definition of a resource can be queried with the **crm_resource** tool. For example: .. code-block:: none # crm_resource --resource Email --query-xml might produce: .. topic:: A system resource definition .. code-block:: xml .. note:: One of the main drawbacks to system services (LSB, systemd or Upstart) resources is that they do not allow any parameters! .. topic:: An OCF resource definition .. code-block:: xml .. _resource_options: Resource Options ################ Resources have two types of options: *meta-attributes* and *instance attributes*. Meta-attributes apply to any type of resource, while instance attributes are specific to each resource agent. Resource Meta-Attributes ________________________ Meta-attributes are used by the cluster to decide how a resource should behave and can be easily set using the ``--meta`` option of the **crm_resource** command. .. table:: **Meta-attributes of a Primitive Resource** +----------------------------+----------------------------------+------------------------------------------------------+ | Field | Default | Description | +============================+==================================+======================================================+ | priority | 0 | .. index:: | | | | single: priority; resource option | | | | single: resource; option, priority | | | | | | | | If not all resources can be active, the cluster | | | | will stop lower priority resources in order to | | | | keep higher priority ones active. | +----------------------------+----------------------------------+------------------------------------------------------+ | critical | true | .. index:: | | | | single: critical; resource option | | | | single: resource; option, critical | | | | | | | | Use this value as the default for ``influence`` in | | | | all :ref:`colocation constraints | | | | ` involving this resource, | | | | as well as the implicit colocation constraints | | | | created if this resource is in a :ref:`group | | | | `. For details, see | | | | :ref:`s-coloc-influence`. *(since 2.1.0)* | +----------------------------+----------------------------------+------------------------------------------------------+ | target-role | Started | .. index:: | | | | single: target-role; resource option | | | | single: resource; option, target-role | | | | | | | | What state should the cluster attempt to keep this | | | | resource in? Allowed values: | | | | | | | | * ``Stopped:`` Force the resource to be stopped | | | | * ``Started:`` Allow the resource to be started | | | | (and in the case of :ref:`promotable clone | | | | resources `, promoted | | | | if appropriate) | | | | * ``Unpromoted:`` Allow the resource to be started, | | | | but only in the unpromoted role if the resource is | | | | :ref:`promotable ` | | | | * ``Promoted:`` Equivalent to ``Started`` | +----------------------------+----------------------------------+------------------------------------------------------+ | is-managed | TRUE | .. index:: | | | | single: is-managed; resource option | | | | single: resource; option, is-managed | | | | | | | | Is the cluster allowed to start and stop | | | | the resource? Allowed values: ``true``, ``false`` | +----------------------------+----------------------------------+------------------------------------------------------+ | maintenance | FALSE | .. index:: | | | | single: maintenance; resource option | | | | single: resource; option, maintenance | | | | | | | | Similar to the ``maintenance-mode`` | | | | :ref:`cluster option `, but for | | | | a single resource. If true, the resource will not | | | | be started, stopped, or monitored on any node. This | | | | differs from ``is-managed`` in that monitors will | | | | not be run. Allowed values: ``true``, ``false`` | +----------------------------+----------------------------------+------------------------------------------------------+ | resource-stickiness | 1 for individual clone | .. _resource-stickiness: | | | instances, 0 for all | | | | other resources | .. index:: | | | | single: resource-stickiness; resource option | | | | single: resource; option, resource-stickiness | | | | | | | | A score that will be added to the current node when | | | | a resource is already active. This allows running | | | | resources to stay where they are, even if they | | | | would be placed elsewhere if they were being | | | | started from a stopped state. | +----------------------------+----------------------------------+------------------------------------------------------+ | requires | ``quorum`` for resources | .. _requires: | | | with a ``class`` of ``stonith``, | | | | otherwise ``unfencing`` if | .. index:: | | | unfencing is active in the | single: requires; resource option | | | cluster, otherwise ``fencing`` | single: resource; option, requires | | | if ``stonith-enabled`` is true, | | | | otherwise ``quorum`` | Conditions under which the resource can be | | | | started. Allowed values: | | | | | | | | * ``nothing:`` can always be started | | | | * ``quorum:`` The cluster can only start this | | | | resource if a majority of the configured nodes | | | | are active | | | | * ``fencing:`` The cluster can only start this | | | | resource if a majority of the configured nodes | | | | are active *and* any failed or unknown nodes | | | | have been :ref:`fenced ` | | | | * ``unfencing:`` The cluster can only start this | | | | resource if a majority of the configured nodes | | | | are active *and* any failed or unknown nodes have | | | | been fenced *and* only on nodes that have been | | | | :ref:`unfenced ` | +----------------------------+----------------------------------+------------------------------------------------------+ | migration-threshold | INFINITY | .. index:: | | | | single: migration-threshold; resource option | | | | single: resource; option, migration-threshold | | | | | | | | How many failures may occur for this resource on | | | | a node, before this node is marked ineligible to | | | | host this resource. A value of 0 indicates that this | | | | feature is disabled (the node will never be marked | | | | ineligible); by constrast, the cluster treats | | | | INFINITY (the default) as a very large but finite | | | | number. This option has an effect only if the | | | | failed operation specifies ``on-fail`` as | | | | ``restart`` (the default), and additionally for | | | | failed ``start`` operations, if the cluster | | | | property ``start-failure-is-fatal`` is ``false``. | +----------------------------+----------------------------------+------------------------------------------------------+ | failure-timeout | 0 | .. index:: | | | | single: failure-timeout; resource option | | | | single: resource; option, failure-timeout | | | | | | | | How many seconds to wait before acting as if the | | | | failure had not occurred, and potentially allowing | | | | the resource back to the node on which it failed. | | | | A value of 0 indicates that this feature is | | | | disabled. | +----------------------------+----------------------------------+------------------------------------------------------+ | multiple-active | stop_start | .. index:: | | | | single: multiple-active; resource option | | | | single: resource; option, multiple-active | | | | | | | | What should the cluster do if it ever finds the | | | | resource active on more than one node? Allowed | | | | values: | | | | | | | | * ``block``: mark the resource as unmanaged | | | | * ``stop_only``: stop all active instances and | | | | leave them that way | | | | * ``stop_start``: stop all active instances and | | | | start the resource in one location only | +----------------------------+----------------------------------+------------------------------------------------------+ | allow-migrate | TRUE for ocf:pacemaker:remote | Whether the cluster should try to "live migrate" | | | resources, FALSE otherwise | this resource when it needs to be moved (see | | | | :ref:`live-migration`) | +----------------------------+----------------------------------+------------------------------------------------------+ | container-attribute-target | | Specific to bundle resources; see | | | | :ref:`s-bundle-attributes` | +----------------------------+----------------------------------+------------------------------------------------------+ | remote-node | | The name of the Pacemaker Remote guest node this | | | | resource is associated with, if any. If | | | | specified, this both enables the resource as a | | | | guest node and defines the unique name used to | | | | identify the guest node. The guest must be | | | | configured to run the Pacemaker Remote daemon | | | | when it is started. **WARNING:** This value | | | | cannot overlap with any resource or node IDs. | +----------------------------+----------------------------------+------------------------------------------------------+ | remote-port | 3121 | If ``remote-node`` is specified, the port on the | | | | guest used for its Pacemaker Remote connection. | | | | The Pacemaker Remote daemon on the guest must | | | | be configured to listen on this port. | +----------------------------+----------------------------------+------------------------------------------------------+ | remote-addr | value of ``remote-node`` | If ``remote-node`` is specified, the IP | | | | address or hostname used to connect to the | | | | guest via Pacemaker Remote. The Pacemaker Remote | | | | daemon on the guest must be configured to accept | | | | connections on this address. | +----------------------------+----------------------------------+------------------------------------------------------+ | remote-connect-timeout | 60s | If ``remote-node`` is specified, how long before | | | | a pending guest connection will time out. | +----------------------------+----------------------------------+------------------------------------------------------+ As an example of setting resource options, if you performed the following commands on an LSB Email resource: .. code-block:: none # crm_resource --meta --resource Email --set-parameter priority --parameter-value 100 # crm_resource -m -r Email -p multiple-active -v block the resulting resource definition might be: .. topic:: An LSB resource with cluster options .. code-block:: xml In addition to the cluster-defined meta-attributes described above, you may also configure arbitrary meta-attributes of your own choosing. Most commonly, this would be done for use in :ref:`rules `. For example, an IT department might define a custom meta-attribute to indicate which company department each resource is intended for. To reduce the chance of name collisions with cluster-defined meta-attributes added in the future, it is recommended to use a unique, organization-specific prefix for such attributes. .. _s-resource-defaults: Setting Global Defaults for Resource Meta-Attributes ____________________________________________________ To set a default value for a resource option, add it to the ``rsc_defaults`` section with ``crm_attribute``. For example, .. code-block:: none # crm_attribute --type rsc_defaults --name is-managed --update false would prevent the cluster from starting or stopping any of the resources in the configuration (unless of course the individual resources were specifically enabled by having their ``is-managed`` set to ``true``). Resource Instance Attributes ____________________________ The resource agents of some resource classes (lsb, systemd and upstart *not* among them) can be given parameters which determine how they behave and which instance of a service they control. If your resource agent supports parameters, you can add them with the ``crm_resource`` command. For example, .. code-block:: none # crm_resource --resource Public-IP --set-parameter ip --parameter-value 192.0.2.2 would create an entry in the resource like this: .. topic:: An example OCF resource with instance attributes .. code-block:: xml For an OCF resource, the result would be an environment variable called ``OCF_RESKEY_ip`` with a value of ``192.0.2.2``. The list of instance attributes supported by an OCF resource agent can be found by calling the resource agent with the ``meta-data`` command. The output contains an XML description of all the supported attributes, their purpose and default values. .. topic:: Displaying the metadata for the Dummy resource agent template .. code-block:: none # export OCF_ROOT=/usr/lib/ocf # $OCF_ROOT/resource.d/pacemaker/Dummy meta-data .. code-block:: xml 1.1 This is a dummy OCF resource agent. It does absolutely nothing except keep track of whether it is running or not, and can be configured so that actions fail or take a long time. Its purpose is primarily for testing, and to serve as a template for resource agent writers. Example stateless resource agent Location to store the resource state in. State file Fake password field Password Fake attribute that can be changed to cause a reload Fake attribute that can be changed to cause a reload Number of seconds to sleep during operations. This can be used to test how the cluster reacts to operation timeouts. Operation sleep duration in seconds. Start, migrate_from, and reload-agent actions will return failure if running on the host specified here, but the resource will run successfully anyway (future monitor calls will find it running). This can be used to test on-fail=ignore. Report bogus start failure on specified host If this is set, the environment will be dumped to this file for every call. Environment dump file .. index:: single: resource; action single: resource; operation .. _operation: Resource Operations ################### *Operations* are actions the cluster can perform on a resource by calling the resource agent. Resource agents must support certain common operations such as start, stop, and monitor, and may implement any others. Operations may be explicitly configured for two purposes: to override defaults for options (such as timeout) that the cluster will use whenever it initiates the operation, and to run an operation on a recurring basis (for example, to monitor the resource for failure). .. topic:: An OCF resource with a non-default start timeout .. code-block:: xml Pacemaker identifies operations by a combination of name and interval, so this combination must be unique for each resource. That is, you should not configure two operations for the same resource with the same name and interval. .. _operation_properties: Operation Properties ____________________ Operation properties may be specified directly in the ``op`` element as XML attributes, or in a separate ``meta_attributes`` block as ``nvpair`` elements. XML attributes take precedence over ``nvpair`` elements if both are specified. .. table:: **Properties of an Operation** +----------------+-----------------------------------+-----------------------------------------------------+ | Field | Default | Description | +================+===================================+=====================================================+ | id | | .. index:: | | | | single: id; action property | | | | single: action; property, id | | | | | | | | A unique name for the operation. | +----------------+-----------------------------------+-----------------------------------------------------+ | name | | .. index:: | | | | single: name; action property | | | | single: action; property, name | | | | | | | | The action to perform. This can be any action | | | | supported by the agent; common values include | | | | ``monitor``, ``start``, and ``stop``. | +----------------+-----------------------------------+-----------------------------------------------------+ | interval | 0 | .. index:: | | | | single: interval; action property | | | | single: action; property, interval | | | | | | | | How frequently (in seconds) to perform the | | | | operation. A value of 0 means "when needed". | | | | A positive value defines a *recurring action*, | | | | which is typically used with | | | | :ref:`monitor `. | +----------------+-----------------------------------+-----------------------------------------------------+ | timeout | | .. index:: | | | | single: timeout; action property | | | | single: action; property, timeout | | | | | | | | How long to wait before declaring the action | | | | has failed | +----------------+-----------------------------------+-----------------------------------------------------+ | on-fail | Varies by action: | .. index:: | | | | single: on-fail; action property | | | * ``stop``: ``fence`` if | single: action; property, on-fail | | | ``stonith-enabled`` is true | | | | or ``block`` otherwise | The action to take if this action ever fails. | | | * ``demote``: ``on-fail`` of the | Allowed values: | | | ``monitor`` action with | | | | ``role`` set to ``Promoted``, | * ``ignore:`` Pretend the resource did not fail. | | | if present, enabled, and | * ``block:`` Don't perform any further operations | | | configured to a value other | on the resource. | | | than ``demote``, or ``restart`` | * ``stop:`` Stop the resource and do not start | | | otherwise | it elsewhere. | | | * all other actions: ``restart`` | * ``demote:`` Demote the resource, without a | | | | full restart. This is valid only for ``promote`` | | | | actions, and for ``monitor`` actions with both | | | | a nonzero ``interval`` and ``role`` set to | | | | ``Promoted``; for any other action, a | | | | configuration error will be logged, and the | | | | default behavior will be used. *(since 2.0.5)* | | | | * ``restart:`` Stop the resource and start it | | | | again (possibly on a different node). | | | | * ``fence:`` STONITH the node on which the | | | | resource failed. | | | | * ``standby:`` Move *all* resources away from the | | | | node on which the resource failed. | +----------------+-----------------------------------+-----------------------------------------------------+ | enabled | TRUE | .. index:: | | | | single: enabled; action property | | | | single: action; property, enabled | | | | | | | | If ``false``, ignore this operation definition. | | | | This is typically used to pause a particular | | | | recurring ``monitor`` operation; for instance, it | | | | can complement the respective resource being | | | | unmanaged (``is-managed=false``), as this alone | | | | will :ref:`not block any configured monitoring | | | | `. Disabling the operation | | | | does not suppress all actions of the given type. | | | | Allowed values: ``true``, ``false``. | +----------------+-----------------------------------+-----------------------------------------------------+ | record-pending | TRUE | .. index:: | | | | single: record-pending; action property | | | | single: action; property, record-pending | | | | | | | | If ``true``, the intention to perform the operation | | | | is recorded so that GUIs and CLI tools can indicate | | | | that an operation is in progress. This is best set | | | | as an *operation default* | | | | (see :ref:`s-operation-defaults`). Allowed values: | | | | ``true``, ``false``. | +----------------+-----------------------------------+-----------------------------------------------------+ | role | | .. index:: | | | | single: role; action property | | | | single: action; property, role | | | | | | | | Run the operation only on node(s) that the cluster | | | | thinks should be in the specified role. This only | | | | makes sense for recurring ``monitor`` operations. | | | | Allowed (case-sensitive) values: ``Stopped``, | | | | ``Started``, and in the case of :ref:`promotable | | | | clone resources `, | | | | ``Unpromoted`` and ``Promoted``. | +----------------+-----------------------------------+-----------------------------------------------------+ .. note:: When ``on-fail`` is set to ``demote``, recovery from failure by a successful demote causes the cluster to recalculate whether and where a new instance should be promoted. The node with the failure is eligible, so if promotion scores have not changed, it will be promoted again. There is no direct equivalent of ``migration-threshold`` for the promoted role, but the same effect can be achieved with a location constraint using a :ref:`rule ` with a node attribute expression for the resource's fail count. For example, to immediately ban the promoted role from a node with any failed promote or promoted instance monitor: .. code-block:: xml This example assumes that there is a promotable clone of the ``my_primitive`` resource (note that the primitive name, not the clone name, is used in the rule), and that there is a recurring 10-second-interval monitor configured for the promoted role (fail count attributes specify the interval in milliseconds). .. _s-resource-monitoring: Monitoring Resources for Failure ________________________________ When Pacemaker first starts a resource, it runs one-time ``monitor`` operations (referred to as *probes*) to ensure the resource is running where it's supposed to be, and not running where it's not supposed to be. (This behavior can be affected by the ``resource-discovery`` location constraint property.) Other than those initial probes, Pacemaker will *not* (by default) check that the resource continues to stay healthy [#]_. You must configure ``monitor`` operations explicitly to perform these checks. .. topic:: An OCF resource with a recurring health check .. code-block:: xml By default, a ``monitor`` operation will ensure that the resource is running where it is supposed to. The ``target-role`` property can be used for further checking. For example, if a resource has one ``monitor`` operation with ``interval=10 role=Started`` and a second ``monitor`` operation with ``interval=11 role=Stopped``, the cluster will run the first monitor on any nodes it thinks *should* be running the resource, and the second monitor on any nodes that it thinks *should not* be running the resource (for the truly paranoid, who want to know when an administrator manually starts a service by mistake). .. note:: Currently, monitors with ``role=Stopped`` are not implemented for :ref:`clone ` resources. .. _s-monitoring-unmanaged: Monitoring Resources When Administration is Disabled ____________________________________________________ Recurring ``monitor`` operations behave differently under various administrative settings: * When a resource is unmanaged (by setting ``is-managed=false``): No monitors will be stopped. If the unmanaged resource is stopped on a node where the cluster thinks it should be running, the cluster will detect and report that it is not, but it will not consider the monitor failed, and will not try to start the resource until it is managed again. Starting the unmanaged resource on a different node is strongly discouraged and will at least cause the cluster to consider the resource failed, and may require the resource's ``target-role`` to be set to ``Stopped`` then ``Started`` to be recovered. * When a node is put into standby: All resources will be moved away from the node, and all ``monitor`` operations will be stopped on the node, except those specifying ``role`` as ``Stopped`` (which will be newly initiated if appropriate). * When the cluster is put into maintenance mode: All resources will be marked as unmanaged. All monitor operations will be stopped, except those specifying ``role`` as ``Stopped`` (which will be newly initiated if appropriate). As with single unmanaged resources, starting a resource on a node other than where the cluster expects it to be will cause problems. .. _s-operation-defaults: Setting Global Defaults for Operations ______________________________________ You can change the global default values for operation properties in a given cluster. These are defined in an ``op_defaults`` section of the CIB's ``configuration`` section, and can be set with ``crm_attribute``. For example, .. code-block:: none # crm_attribute --type op_defaults --name timeout --update 20s would default each operation's ``timeout`` to 20 seconds. If an operation's definition also includes a value for ``timeout``, then that value would be used for that operation instead. When Implicit Operations Take a Long Time _________________________________________ The cluster will always perform a number of implicit operations: ``start``, ``stop`` and a non-recurring ``monitor`` operation used at startup to check whether the resource is already active. If one of these is taking too long, then you can create an entry for them and specify a longer timeout. .. topic:: An OCF resource with custom timeouts for its implicit actions .. code-block:: xml Multiple Monitor Operations ___________________________ Provided no two operations (for a single resource) have the same name and interval, you can have as many ``monitor`` operations as you like. In this way, you can do a superficial health check every minute and progressively more intense ones at higher intervals. To tell the resource agent what kind of check to perform, you need to provide each monitor with a different value for a common parameter. The OCF standard creates a special parameter called ``OCF_CHECK_LEVEL`` for this purpose and dictates that it is "made available to the resource agent without the normal ``OCF_RESKEY`` prefix". Whatever name you choose, you can specify it by adding an ``instance_attributes`` block to the ``op`` tag. It is up to each resource agent to look for the parameter and decide how to use it. .. topic:: An OCF resource with two recurring health checks, performing different levels of checks specified via ``OCF_CHECK_LEVEL``. .. code-block:: xml Disabling a Monitor Operation _____________________________ The easiest way to stop a recurring monitor is to just delete it. However, there can be times when you only want to disable it temporarily. In such cases, simply add ``enabled=false`` to the operation's definition. .. topic:: Example of an OCF resource with a disabled health check .. code-block:: xml This can be achieved from the command line by executing: .. code-block:: none # cibadmin --modify --xml-text '' Once you've done whatever you needed to do, you can then re-enable it with .. code-block:: none # cibadmin --modify --xml-text '' -.. [#] See https://github.com/ClusterLabs/OCF-spec/tree/master/ra. The +.. [#] See https://github.com/ClusterLabs/OCF-spec/tree/main/ra. The Pacemaker implementation has been somewhat extended from the OCF specs. .. [#] The resource-agents source code includes the **ocf-tester** script, which can be useful in this regard. .. [#] See http://refspecs.linux-foundation.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html for the LSB Spec as it relates to init scripts. .. [#] For example, http://0pointer.de/blog/projects/systemd-for-admins-3.html .. [#] The project has two independent forks, hosted at https://www.nagios-plugins.org/ and https://www.monitoring-plugins.org/. Output from both projects' plugins is similar, so plugins from either project can be used with pacemaker. .. [#] Currently, anyway. Automatic monitoring operations may be added in a future version of Pacemaker.