diff --git a/doc/sphinx/Clusters_from_Scratch/cluster-setup.rst b/doc/sphinx/Clusters_from_Scratch/cluster-setup.rst index 5cdbe2f64c..748ce5049d 100644 --- a/doc/sphinx/Clusters_from_Scratch/cluster-setup.rst +++ b/doc/sphinx/Clusters_from_Scratch/cluster-setup.rst @@ -1,313 +1,313 @@ Set up a Cluster ---------------- Simplify Administration With a Cluster Shell ############################################ In the dark past, configuring Pacemaker required the administrator to read and write XML. In true UNIX style, there were also a number of different commands that specialized in different aspects of querying and updating the cluster. In addition, the various components of the cluster stack (Corosync, Pacemaker, etc.) had to be configured separately, with different configuration tools and formats. All of that has been greatly simplified with the creation of higher-level tools, whether command-line or GUIs, that hide all the mess underneath. Command-line cluster shells take all the individual aspects required for managing and configuring a cluster, and pack them into one simple-to-use command-line tool. They even allow you to queue up several changes at once and commit them all at once. Two popular command-line shells are ``pcs`` and ``crmsh``. Clusters from Scratch is based on ``pcs`` because it comes with |CFS_DISTRO|, but both have similar functionality. Choosing a shell or GUI is a matter of personal preference and what comes with (and perhaps is supported by) your choice of operating system. Install the Cluster Software ############################ Fire up a shell on both nodes and run the following to activate the High Availability repo. .. code-block:: console # dnf config-manager --set-enabled highavailability .. IMPORTANT:: This document will show commands that need to be executed on both nodes with a simple ``#`` prompt. Be sure to run them on each node individually. Now, we'll install ``pacemaker``, ``pcs``, and some other command-line tools that will make our lives easier: .. code-block:: console # dnf install -y pacemaker pcs psmisc policycoreutils-python3 .. NOTE:: This document uses ``pcs`` for cluster management. Other alternatives, such as ``crmsh``, are available, but their syntax will differ from the examples used here. Configure the Cluster Software ############################## .. index:: single: firewall Allow cluster services through firewall _______________________________________ On each node, allow cluster-related services through the local firewall: .. code-block:: console # firewall-cmd --permanent --add-service=high-availability success # firewall-cmd --reload success .. NOTE :: If you are using ``iptables`` directly, or some other firewall solution besides ``firewalld``, simply open the following ports, which can be used by various clustering components: TCP ports 2224, 3121, and 21064, and UDP port 5405. If you run into any problems during testing, you might want to disable the firewall and SELinux entirely until you have everything working. This may create significant security issues and should not be performed on machines that will be exposed to the outside world, but may be appropriate during development and testing on a protected host. To disable security measures: .. code-block:: console [root@pcmk-1 ~]# setenforce 0 [root@pcmk-1 ~]# sed -i.bak "s/SELINUX=enforcing/SELINUX=permissive/g" /etc/selinux/config [root@pcmk-1 ~]# systemctl mask firewalld.service [root@pcmk-1 ~]# systemctl stop firewalld.service [root@pcmk-1 ~]# iptables --flush Enable ``pcs`` Daemon _____________________ Before the cluster can be configured, the ``pcs`` daemon must be started and enabled to start at boot time on each node. This daemon works with the ``pcs`` command-line interface to manage synchronizing the Corosync configuration across all nodes in the cluster, among other functions. Start and enable the daemon by issuing the following commands on each node: .. code-block:: console # systemctl start pcsd.service # systemctl enable pcsd.service Created symlink from /etc/systemd/system/multi-user.target.wants/pcsd.service to /usr/lib/systemd/system/pcsd.service. The installed packages will create an |CRM_DAEMON_USER| user with a disabled password. While this is fine for running ``pcs`` commands locally, the account needs a login password in order to perform such tasks as syncing the Corosync configuration, or starting and stopping the cluster on other nodes. This tutorial will make use of such commands, so now we will set a password for the |CRM_DAEMON_USER| user, using the same password on both nodes: .. code-block:: console # passwd hacluster Changing password for user hacluster. New password: Retype new password: passwd: all authentication tokens updated successfully. .. NOTE:: Alternatively, to script this process or set the password on a different machine from the one you're logged into, you can use the ``--stdin`` option for ``passwd``: .. code-block:: console [root@pcmk-1 ~]# ssh pcmk-2 -- 'echo mysupersecretpassword | passwd --stdin hacluster' Configure Corosync __________________ On either node, use ``pcs host auth`` to authenticate as the ``hacluster`` user: .. code-block:: console [root@pcmk-1 ~]# pcs host auth pcmk-1 pcmk-2 Username: hacluster Password: pcmk-2: Authorized pcmk-1: Authorized Next, use ``pcs cluster setup`` on the same node to generate and synchronize the Corosync configuration: .. code-block:: console [root@pcmk-1 ~]# pcs cluster setup mycluster pcmk-1 pcmk-2 No addresses specified for host 'pcmk-1', using 'pcmk-1' No addresses specified for host 'pcmk-2', using 'pcmk-2' Destroying cluster on hosts: 'pcmk-1', 'pcmk-2'... pcmk-2: Successfully destroyed cluster pcmk-1: Successfully destroyed cluster Requesting remove 'pcsd settings' from 'pcmk-1', 'pcmk-2' pcmk-1: successful removal of the file 'pcsd settings' pcmk-2: successful removal of the file 'pcsd settings' Sending 'corosync authkey', 'pacemaker authkey' to 'pcmk-1', 'pcmk-2' pcmk-1: successful distribution of the file 'corosync authkey' pcmk-1: successful distribution of the file 'pacemaker authkey' pcmk-2: successful distribution of the file 'corosync authkey' pcmk-2: successful distribution of the file 'pacemaker authkey' Sending 'corosync.conf' to 'pcmk-1', 'pcmk-2' pcmk-1: successful distribution of the file 'corosync.conf' pcmk-2: successful distribution of the file 'corosync.conf' Cluster has been successfully set up. .. NOTE:: If you'd like, you can specify an ``addr`` option for each node in the ``pcs cluster setup`` command. This will create an explicit name-to-address mapping for each node in ``/etc/corosync/corosync.conf``, eliminating the need for hostname resolution via DNS, ``/etc/hosts``, and the like. .. code-block:: console [root@pcmk-1 ~]# pcs cluster setup mycluster \ pcmk-1 addr=192.168.122.101 pcmk-2 addr=192.168.122.102 If you received an authorization error for either of those commands, make sure you configured the ``hacluster`` user account on each node with the same password. The final ``corosync.conf`` configuration on each node should look something like the sample in :ref:`sample-corosync-configuration`. Explore pcs ########### Start by taking some time to familiarize yourself with what ``pcs`` can do. .. code-block:: console [root@pcmk-1 ~]# pcs Usage: pcs [-f file] [-h] [commands]... Control and configure pacemaker and corosync. Options: -h, --help Display usage and exit. -f file Perform actions on file instead of active CIB. Commands supporting the option use the initial state of the specified file as their input and then overwrite the file with the state reflecting the requested operation(s). A few commands only use the specified file in read-only mode since their effect is not a CIB modification. --debug Print all network traffic and external commands run. --version Print pcs version information. List pcs capabilities if --full is specified. --request-timeout Timeout for each outgoing request to another node in seconds. Default is 60s. --force Override checks and errors, the exact behavior depends on the command. WARNING: Using the --force option is strongly discouraged unless you know what you are doing. Commands: cluster Configure cluster options and nodes. resource Manage cluster resources. stonith Manage fence devices. constraint Manage resource constraints. property Manage pacemaker properties. acl Manage pacemaker access control lists. qdevice Manage quorum device provider on the local host. quorum Manage cluster quorum settings. booth Manage booth (cluster ticket manager). status View cluster status. config View and manage cluster configuration. pcsd Manage pcs daemon. host Manage hosts known to pcs/pcsd. node Manage cluster nodes. alert Manage pacemaker alerts. client Manage pcsd client configuration. dr Manage disaster recovery configuration. tag Manage pacemaker tags. As you can see, the different aspects of cluster management are separated into categories. To discover the functionality available in each of these categories, one can issue the command ``pcs help``. Below is an example of all the options available under the status category. .. code-block:: console [root@pcmk-1 ~]# pcs status help Usage: pcs status [commands]... View current cluster and resource status Commands: [status] [--full] [--hide-inactive] View all information about the cluster and resources (--full provides more details, --hide-inactive hides inactive resources). resources [] [node=] [--hide-inactive] Show status of all currently configured resources. If --hide-inactive is specified, only show active resources. If a resource or tag id is specified, only show status of the specified resource or resources in the specified tag. If node is specified, only show status of resources configured for the specified node. cluster View current cluster status. corosync View current membership information as seen by corosync. quorum View current quorum status. qdevice [--full] [] Show runtime status of specified model of quorum device provider. Using --full will give more detailed output. If is specified, only information about the specified cluster will be displayed. booth Print current status of booth on the local node. nodes [corosync | both | config] View current status of nodes from pacemaker. If 'corosync' is specified, view current status of nodes from corosync instead. If 'both' is specified, view current status of nodes from both corosync & pacemaker. If 'config' is specified, print nodes from corosync & pacemaker configuration. pcsd []... Show current status of pcsd on nodes specified, or on all nodes configured in the local cluster if no nodes are specified. xml View xml version of status (output from crm_mon -r -1 -X). Additionally, if you are interested in the version and supported cluster stack(s) available with your Pacemaker installation, run: .. code-block:: console [root@pcmk-1 ~]# pacemakerd --features Pacemaker 2.1.2-4.el9 (Build: ada5c3b36e2) - Supporting v3.13.0: agent-manpages cibsecrets corosync-ge-2 default-concurrent-fencing default-resource-stickiness default-sbd-sync generated-manpages monotonic nagios ncurses remote systemd + Supporting v3.13.0: agent-manpages cibsecrets corosync-ge-2 default-resource-stickiness default-sbd-sync generated-manpages monotonic nagios ncurses remote systemd diff --git a/doc/sphinx/Clusters_from_Scratch/fencing.rst b/doc/sphinx/Clusters_from_Scratch/fencing.rst index fa413d4305..3f9d12eb66 100644 --- a/doc/sphinx/Clusters_from_Scratch/fencing.rst +++ b/doc/sphinx/Clusters_from_Scratch/fencing.rst @@ -1,232 +1,231 @@ .. index:: fencing Configure Fencing ----------------- What is Fencing? ################ Fencing protects your data from being corrupted, and your application from becoming unavailable, due to unintended concurrent access by rogue nodes. Just because a node is unresponsive doesn't mean it has stopped accessing your data. The only way to be 100% sure that your data is safe, is to use fencing to ensure that the node is truly offline before allowing the data to be accessed from another node. Fencing also has a role to play in the event that a clustered service cannot be stopped. In this case, the cluster uses fencing to force the whole node offline, thereby making it safe to start the service elsewhere. Fencing is also known as STONITH, an acronym for "Shoot The Other Node In The Head", since the most popular form of fencing is cutting a host's power. In order to guarantee the safety of your data [#]_, fencing is enabled by default. .. NOTE:: It is possible to tell the cluster not to use fencing, by setting the ``fencing-enabled`` cluster property to false: .. code-block:: console [root@pcmk-1 ~]# pcs property set fencing-enabled=false [root@pcmk-1 ~]# pcs cluster verify --full However, this is completely inappropriate for a production cluster. It tells the cluster to simply pretend that failed nodes are safely powered off. Some vendors will refuse to support clusters that have fencing disabled. Even disabling it for a test cluster means you won't be able to test real failure scenarios. .. index:: single: fencing; device Choose a Fence Device ##################### The two broad categories of fence device are power fencing, which cuts off power to the target, and fabric fencing, which cuts off the target's access to some critical resource, such as a shared disk or access to the local network. Power fencing devices include: * Intelligent power switches * IPMI * Hardware watchdog device (alone, or in combination with shared storage used as a "poison pill" mechanism) Fabric fencing devices include: * Shared storage that can be cut off for a target host by another host (for example, an external storage device that supports SCSI-3 persistent reservations) * Intelligent network switches Using IPMI as a power fencing device may seem like a good choice. However, if the IPMI shares power and/or network access with the host (such as most onboard IPMI controllers), a power or network failure will cause both the host and its fencing device to fail. The cluster will be unable to recover, and must stop all resources to avoid a possible split-brain situation. Likewise, any device that relies on the machine being active (such as SSH-based "devices" sometimes used during testing) is inappropriate, because fencing will be required when the node is completely unresponsive. (Fence agents like ``fence_ilo_ssh``, which connects via SSH to an HP iLO but not to the cluster node, are fine.) Configure the Cluster for Fencing ################################# #. Install the fence agent(s). To see what packages are available, run ``dnf search fence-``. Be sure to install the package(s) on all cluster nodes. #. Configure the fence device itself to be able to fence your nodes and accept fencing requests. This includes any necessary configuration on the device and on the nodes, and any firewall or SELinux changes needed. Test the communication between the device and your nodes. #. Find the name of the correct fence agent: ``pcs stonith list`` #. Find the parameters associated with the device: ``pcs stonith describe `` #. Create a local copy of the CIB: ``pcs cluster cib fencing_cfg`` #. Create the fencing resource: ``pcs -f fencing_cfg stonith create [FENCING_DEVICE_OPTIONS]`` Any flags that do not take arguments, such as ``--ssl``, should be passed as ``ssl=1``. #. Ensure fencing is enabled in the cluster: ``pcs -f fencing_cfg property set fencing-enabled=true`` #. If the device does not know how to fence nodes based on their cluster node name, you may also need to set the special ``pcmk_host_map`` parameter. See ``man pacemaker-fenced`` for details. #. If the device does not support the ``list`` command, you may also need to set the special ``pcmk_host_list`` and/or ``pcmk_host_check`` parameters. See ``man pacemaker-fenced`` for details. #. If the device does not expect the target to be specified with the ``port`` parameter, you may also need to set the special ``pcmk_host_argument`` parameter. See ``man pacemaker-fenced`` for details. #. Commit the new configuration: ``pcs cluster cib-push fencing_cfg`` #. Once the fence device resource is running, test it (you might want to stop the cluster on that machine first): ``pcs stonith fence `` Example ####### For this example, assume we have a chassis containing four nodes and a separately powered IPMI device active on ``10.0.0.1``. Following the steps above would go something like this: Step 1: Install the ``fence-agents-ipmilan`` package on both nodes. Step 2: Configure the IP address, authentication credentials, etc. in the IPMI device itself. Step 3: Choose the ``fence_ipmilan`` STONITH agent. Step 4: Obtain the agent's possible parameters: .. code-block:: console [root@pcmk-1 ~]# pcs stonith describe fence_ipmilan fence_ipmilan - Fence agent for IPMI fence_ipmilan is an I/O Fencing agentwhich can be used with machines controlled by IPMI.This agent calls support software ipmitool (http://ipmitool.sf.net/). WARNING! This fence agent might report success before the node is powered off. You should use -m/method onoff if your fence device works correctly with that option. Stonith options: auth: IPMI Lan Auth type. cipher: Ciphersuite to use (same as ipmitool -C parameter) hexadecimal_kg: Hexadecimal-encoded Kg key for IPMIv2 authentication ip: IP address or hostname of fencing device ipport: TCP/UDP port to use for connection with device lanplus: Use Lanplus to improve security of connection method: Method to fence password: Login password or passphrase password_script: Script to run to retrieve password plug: IP address or hostname of fencing device (together with --port-as-ip) privlvl: Privilege level on IPMI device target: Bridge IPMI requests to the remote target address username: Login name quiet: Disable logging to stderr. Does not affect --verbose or --debug-file or logging to syslog. verbose: Verbose mode. Multiple -v flags can be stacked on the command line (e.g., -vvv) to increase verbosity. verbose_level: Level of debugging detail in output. Defaults to the number of --verbose flags specified on the command line, or to 1 if verbose=1 in a stonith device configuration (i.e., on stdin). debug_file: Write debug information to given file delay: Wait X seconds before fencing is started disable_timeout: Disable timeout (true/false) (default: true when run from Pacemaker 2.0+) ipmitool_path: Path to ipmitool binary login_timeout: Wait X seconds for cmd prompt after login port_as_ip: Make "port/plug" to be an alias to IP address power_timeout: Test X seconds for status change after ON/OFF power_wait: Wait X seconds after issuing ON/OFF shell_timeout: Wait X seconds for cmd prompt after issuing command stonith_status_sleep: Sleep X seconds between status calls during a STONITH action ipmitool_timeout: Timeout (sec) for IPMI operation retry_on: Count of attempts to retry power on use_sudo: Use sudo (without password) when calling 3rd party software sudo_path: Path to sudo binary pcmk_host_map: A mapping of host names to ports numbers for devices that do not support host names. Eg. node1:1;node2:2,3 would tell the cluster to use port 1 for node1 and ports 2 and 3 for node2 pcmk_host_list: A list of machines controlled by this device (Optional unless pcmk_host_check=static-list). pcmk_host_check: How to determine which machines are controlled by the device. Allowed values: dynamic-list (query the device via the 'list' command), static-list (check the pcmk_host_list attribute), status (query the device via the 'status' command), none (assume every device can fence every machine) pcmk_delay_max: Enable a delay of no more than the time specified before executing fencing actions. Pacemaker derives the overall delay by taking the value of pcmk_delay_base and adding a random delay value such that the sum is kept below this maximum. This prevents double fencing when using slow devices such as sbd. Use this to enable a random delay for fencing actions. The overall delay is derived from this random delay value adding a static delay so that the sum is kept below the maximum delay. pcmk_delay_base: Enable a base delay for fencing actions and specify base delay value. This enables a static delay for fencing actions, which can help avoid "death matches" where two nodes try to fence each other at the same time. If pcmk_delay_max is also used, a random delay will be added such that the total delay is kept below that value. This can be set to a single time value to apply to any node targeted by this device (useful if a separate device is configured for each target), or to a node map (for example, "node1:1s;node2:5") to set a different value per target. - pcmk_action_limit: The maximum number of actions can be performed in parallel on this device Cluster property concurrent-fencing=true needs to be configured first. Then use this to specify the maximum number - of actions can be performed in parallel on this device. -1 is unlimited. + pcmk_action_limit: If the concurrent-fencing cluster property is "true", this specifies the maximum number of actions that can be performed in parallel on this device. A value of -1 means unlimited. Default operations: monitor: interval=60s Step 5: ``pcs cluster cib fencing_cfg`` Step 6: Here are example parameters for creating our fence device resource: .. code-block:: console [root@pcmk-1 ~]# pcs -f fencing_cfg stonith create ipmi-fencing fence_ipmilan \ pcmk_host_list="pcmk-1 pcmk-2" ipaddr=10.0.0.1 login=testuser \ passwd=acd123 op monitor interval=60s [root@pcmk-1 ~]# pcs -f fencing_cfg stonith * ipmi-fencing (stonith:fence_ipmilan): Stopped Steps 7-10: Enable fencing in the cluster: .. code-block:: console [root@pcmk-1 ~]# pcs -f fencing_cfg property set fencing-enabled=true [root@pcmk-1 ~]# pcs -f fencing_cfg property Cluster Properties: cluster-infrastructure: corosync cluster-name: mycluster dc-version: 2.0.5-4.el8-ba59be7122 fencing-enabled: true have-watchdog: false Step 11: ``pcs cluster cib-push fencing_cfg --config`` Step 12: Test: .. code-block:: console [root@pcmk-1 ~]# pcs cluster stop pcmk-2 [root@pcmk-1 ~]# pcs stonith fence pcmk-2 After a successful test, login to any rebooted nodes, and start the cluster (with ``pcs cluster start``). .. [#] If the data is corrupt, there is little point in continuing to make it available. diff --git a/doc/sphinx/Pacemaker_Explained/cluster-options.rst b/doc/sphinx/Pacemaker_Explained/cluster-options.rst index a059e4809c..49c427e30b 100644 --- a/doc/sphinx/Pacemaker_Explained/cluster-options.rst +++ b/doc/sphinx/Pacemaker_Explained/cluster-options.rst @@ -1,913 +1,899 @@ Cluster-Wide Configuration -------------------------- .. index:: pair: XML element; cib pair: XML element; configuration Configuration Layout #################### The cluster is defined by the Cluster Information Base (CIB), which uses XML notation. The simplest CIB, an empty one, looks like this: .. topic:: An empty configuration .. code-block:: xml The empty configuration above contains the major sections that make up a CIB: * ``cib``: The entire CIB is enclosed with a ``cib`` element. Certain fundamental settings are defined as attributes of this element. * ``configuration``: This section -- the primary focus of this document -- contains traditional configuration information such as what resources the cluster serves and the relationships among them. * ``crm_config``: cluster-wide configuration options * ``nodes``: the machines that host the cluster * ``resources``: the services run by the cluster * ``constraints``: indications of how resources should be placed * ``status``: This section contains the history of each resource on each node. Based on this data, the cluster can construct the complete current state of the cluster. The authoritative source for this section is the local executor (pacemaker-execd process) on each cluster node, and the cluster will occasionally repopulate the entire section. For this reason, it is never written to disk, and administrators are advised against modifying it in any way. In this document, configuration settings will be described as properties or options based on how they are defined in the CIB: * Properties are XML attributes of an XML element. * Options are name-value pairs expressed as ``nvpair`` child elements of an XML element. Normally, you will use command-line tools that abstract the XML, so the distinction will be unimportant; both properties and options are cluster settings you can tweak. Options can appear within four types of enclosing elements: * ``cluster_property_set`` * ``instance_attributes`` * ``meta_attributes`` * ``utilization`` We will refer to a set of options and its enclosing element as a *block*. .. list-table:: **Properties of an Option Block's Enclosing Element** :class: longtable :widths: 15 15 15 55 :header-rows: 1 * - Name - Type - Default - Description * - .. _option_block_id: .. index:: pair: id; cluster_property_set pair: id; instance_attributes pair: id; meta_attributes pair: id; utilization single: attribute; id (cluster_property_set) single: attribute; id (instance_attributes) single: attribute; id (meta_attributes) single: attribute; id (utilization) id - :ref:`id ` - - A unique name for the block (required) * - .. _option_block_score: .. index:: pair: score; cluster_property_set pair: score; instance_attributes pair: score; meta_attributes pair: score; utilization single: attribute; score (cluster_property_set) single: attribute; score (instance_attributes) single: attribute; score (meta_attributes) single: attribute; score (utilization) score - :ref:`score ` - 0 - Priority with which to process the block Each block may optionally contain a :ref:`rule `. .. _option_precedence: Option Precedence ################# This subsection describes the precedence of options within a set of blocks and within a single block. Options are processed as follows: * All option blocks of a given type are processed in order of their ``score`` attribute, from highest to lowest. For ``cluster_property_set``, if there is a block whose enclosing element has ``id="cib-bootstrap-options"``, then that block is always processed first regardless of score. * If a block contains a rule that evaluates to false, that block is skipped. * Within a block, options are processed in order from first to last. * The first value found for a given option is applied, and the rest are ignored. Note that this means it is pointless to configure the same option twice in a single block, because occurrences after the first one would be ignored. For example, in the following configuration snippet, the ``no-quorum-policy`` value ``demote`` is applied. ``property-set2`` has a higher score than ``property-set1``, so it's processed first. There are no rules in this snippet, so both sets are processed. Within ``property-set2``, the value ``demote`` appears first, so the later value ``freeze`` is ignored. We've already found a value for ``no-quorum-policy`` before we begin processing ``property-set1``, so its value ``stop`` is ignored. .. code-block:: xml CIB Properties ############## Certain settings are defined by CIB properties (that is, attributes of the ``cib`` tag) rather than with the rest of the cluster configuration in the ``configuration`` section. The reason is simply a matter of parsing. These options are used by the configuration database which is, by design, mostly ignorant of the content it holds. So the decision was made to place them in an easy-to-find location. .. list-table:: **CIB Properties** :class: longtable :widths: 20 15 10 55 :header-rows: 1 * - Name - Type - Default - Description * - .. _admin_epoch: .. index:: pair: admin_epoch; cib admin_epoch - :ref:`nonnegative integer ` - 0 - When a node joins the cluster, the cluster asks the node with the highest (``admin_epoch``, ``epoch``, ``num_updates``) tuple to replace the configuration on all the nodes -- which makes setting them correctly very important. ``admin_epoch`` is never modified by the cluster; you can use this to make the configurations on any inactive nodes obsolete. * - .. _epoch: .. index:: pair: epoch; cib epoch - :ref:`nonnegative integer ` - 0 - The cluster increments this every time the CIB's configuration section is updated. * - .. _num_updates: .. index:: pair: num_updates; cib num_updates - :ref:`nonnegative integer ` - 0 - The cluster increments this every time the CIB's configuration or status sections are updated, and resets it to 0 when epoch changes. * - .. _validate_with: .. index:: pair: validate-with; cib validate-with - :ref:`enumeration ` - - Determines the type of XML validation that will be done on the configuration. Allowed values are ``none`` (in which case the cluster will not require that updates conform to expected syntax) and the base names of schema files installed on the local machine (for example, "pacemaker-3.9") * - .. _remote_tls_port: .. index:: pair: remote-tls-port; cib remote-tls-port - :ref:`port ` - - If set, the CIB manager will listen for anonymously encrypted remote connections on this port, to allow CIB administration from hosts not in the cluster. No key is used, so this should be used only on a protected network where man-in-the-middle attacks can be avoided. * - .. _remote_clear_port: .. index:: pair: remote-clear-port; cib remote-clear-port - :ref:`port ` - - If set to a TCP port number, the CIB manager will listen for remote connections on this port, to allow for CIB administration from hosts not in the cluster. No encryption is used, so this should be used only on a protected network. * - .. _cib_last_written: .. index:: pair: cib-last-written; cib cib-last-written - :ref:`date/time ` - - Indicates when the configuration was last written to disk. Maintained by the cluster; for informational purposes only. * - .. _have_quorum: .. index:: pair: have-quorum; cib have-quorum - :ref:`boolean ` - - Indicates whether the cluster has quorum. If false, the cluster's response is determined by ``no-quorum-policy`` (see below). Maintained by the cluster. * - .. _dc_uuid: .. index:: pair: dc-uuid; cib dc-uuid - :ref:`text ` - - Node ID of the cluster's current designated controller (DC). Used and maintained by the cluster. * - .. _execution_date: .. index:: pair: execution-date; cib execution-date - :ref:`epoch time ` - - Time to use when evaluating rules. .. _cluster_options: Cluster Options ############### Cluster options, as you might expect, control how the cluster behaves when confronted with various situations. They are grouped into sets within the ``crm_config`` section. In advanced configurations, there may be more than one set. (This will be described later in the chapter on :ref:`rules` where we will show how to have the cluster use different sets of options during working hours than during weekends.) For now, we will describe the simple case where each option is present at most once. You can obtain an up-to-date list of cluster options, including their default values, by running the ``man pacemaker-schedulerd`` and ``man pacemaker-controld`` commands. .. list-table:: **Cluster Options** :class: longtable :widths: 25 13 12 50 :header-rows: 1 * - Name - Type - Default - Description * - .. _cluster_name: .. index:: pair: cluster option; cluster-name cluster-name - :ref:`text ` - - An (optional) name for the cluster as a whole. This is mostly for users' convenience for use as desired in administration, but can be used in the Pacemaker configuration in :ref:`rules` (as the ``#cluster-name`` :ref:`node attribute `). It may also be used by higher-level tools when displaying cluster information, and by certain resource agents (for example, the ``ocf:heartbeat:GFS2`` agent stores the cluster name in filesystem meta-data). * - .. _dc_version: .. index:: pair: cluster option; dc-version dc-version - :ref:`version ` - *detected* - Version of Pacemaker on the cluster's designated controller (DC). Maintained by the cluster, and intended for diagnostic purposes. * - .. _cluster_infrastructure: .. index:: pair: cluster option; cluster-infrastructure cluster-infrastructure - :ref:`text ` - *detected* - The messaging layer with which Pacemaker is currently running. Maintained by the cluster, and intended for informational and diagnostic purposes. * - .. _no_quorum_policy: .. index:: pair: cluster option; no-quorum-policy no-quorum-policy - :ref:`enumeration ` - stop - What to do when the cluster does not have quorum. Allowed values: * ``ignore:`` continue all resource management * ``freeze:`` continue resource management, but don't recover resources from nodes not in the affected partition * ``stop:`` stop all resources in the affected cluster partition * ``demote:`` demote promotable resources and stop all other resources in the affected cluster partition *(since 2.0.5)* * ``fence:`` fence all nodes in the affected cluster partition *(since 2.1.9)* * ``suicide:`` same as ``fence`` *(deprecated since 2.1.9)* * - .. _batch_limit: .. index:: pair: cluster option; batch-limit batch-limit - :ref:`integer ` - 0 - The maximum number of actions that the cluster may execute in parallel across all nodes. The ideal value will depend on the speed and load of your network and cluster nodes. If zero, the cluster will impose a dynamically calculated limit only when any node has high load. If -1, the cluster will not impose any limit. * - .. _migration_limit: .. index:: pair: cluster option; migration-limit migration-limit - :ref:`integer ` - -1 - The number of :ref:`live migration ` actions that the cluster is allowed to execute in parallel on a node. A value of -1 means unlimited. * - .. _load_threshold: .. index:: pair: cluster option; load-threshold load-threshold - :ref:`percentage ` - 80% - Maximum amount of system load that should be used by cluster nodes. The cluster will slow down its recovery process when the amount of system resources used (currently CPU) approaches this limit. * - .. _node_action_limit: .. index:: pair: cluster option; node-action-limit node-action-limit - :ref:`integer ` - 0 - Maximum number of jobs that can be scheduled per node. If nonpositive or invalid, double the number of cores is used as the maximum number of jobs per node. :ref:`PCMK_node_action_limit ` overrides this option on a per-node basis. * - .. _symmetric_cluster: .. index:: pair: cluster option; symmetric-cluster symmetric-cluster - :ref:`boolean ` - true - If true, resources can run on any node by default. If false, a resource is allowed to run on a node only if a :ref:`location constraint ` enables it. * - .. _stop_all_resources: .. index:: pair: cluster option; stop-all-resources stop-all-resources - :ref:`boolean ` - false - Whether all resources should be disallowed from running (can be useful during maintenance or troubleshooting) * - .. _stop_removed_resources: .. index:: pair: cluster option; stop-removed-resources stop-removed-resources - :ref:`boolean ` - true - Whether resources that have been deleted from the configuration should be stopped. This value takes precedence over :ref:`is-managed ` (that is, even unmanaged resources will be stopped when removed if this value is ``true``). * - .. _cancel_removed_actions: .. index:: pair: cluster option; cancel-removed-actions cancel-removed-actions - :ref:`boolean ` - true - Whether recurring :ref:`operations ` that have been deleted from the configuration should be cancelled * - .. _start_failure_is_fatal: .. index:: pair: cluster option; start-failure-is-fatal start-failure-is-fatal - :ref:`boolean ` - true - Whether a failure to start a resource on a particular node prevents further start attempts on that node. If ``false``, the cluster will decide whether the node is still eligible based on the resource's current failure count and ``migration-threshold``. * - .. _maintenance_mode: .. index:: pair: cluster option; maintenance-mode maintenance-mode - :ref:`boolean ` - false - If true, the cluster will not start or stop any resource in the cluster, and any recurring operations (expect those specifying ``role`` as ``Stopped``) will be paused. If true, this overrides the :ref:`maintenance ` node attribute, :ref:`is-managed ` and :ref:`maintenance ` resource meta-attributes, and :ref:`enabled ` operation meta-attribute. * - .. _fencing_enabled: .. index:: pair: cluster option; fencing-enabled fencing-enabled - :ref:`boolean ` - true - Whether the cluster is allowed to fence nodes (for example, failed nodes and nodes with resources that can't be stopped). If true, at least one fence device must be configured before resources are allowed to run. If false, unresponsive nodes are immediately assumed to be running no resources, and resource recovery on online nodes starts without any further protection (which can mean *data loss* if the unresponsive node still accesses shared storage, for example). See also the :ref:`requires ` resource meta-attribute. This option applies only to fencing scheduled by the cluster, not to requests initiated externally (such as with the ``stonith_admin`` command-line tool). * - .. _fencing_action: .. index:: pair: cluster option; fencing-action fencing-action - :ref:`enumeration ` - reboot - Action the cluster should send to the fence agent when a node must be fenced. Allowed values are ``reboot`` and ``off``. * - .. _fencing_timeout: .. index:: pair: cluster option; fencing-timeout fencing-timeout - :ref:`duration ` - 60s - How long to wait for ``on``, ``off``, and ``reboot`` fence actions to complete by default. * - .. _fencing_max_attempts: .. index:: pair: cluster option; fencing-max-attempts fencing-max-attempts - :ref:`score ` - 10 - How many times fencing can fail for a target before the cluster will no longer immediately re-attempt it. Any value below 1 will be ignored, and the default will be used instead. * - .. _have_watchdog: .. index:: pair: cluster option; have-watchdog have-watchdog - :ref:`boolean ` - *detected* - Whether watchdog integration is enabled. This is set automatically by the cluster according to whether SBD is detected to be in use. User-configured values are ignored. The value `true` is meaningful if diskless SBD is used and :ref:`fencing-watchdog-timeout ` is nonzero. In that case, if fencing is required, watchdog-based self-fencing will be performed via SBD without requiring a fencing resource explicitly configured. * - .. _fencing_watchdog_timeout: .. index:: pair: cluster option; fencing-watchdog-timeout fencing-watchdog-timeout - :ref:`timeout ` - 0 - If nonzero, and the cluster detects ``have-watchdog`` as ``true``, then watchdog-based self-fencing will be performed via SBD when fencing is required. If this is set to a positive value, lost nodes are assumed to achieve self-fencing within this much time. This does not require a fencing resource to be explicitly configured, though a fence_watchdog resource can be configured, to limit use to specific nodes. If this is set to 0 (the default), the cluster will never assume watchdog-based self-fencing. If this is set to a negative value, the cluster will use twice the local value of the ``SBD_WATCHDOG_TIMEOUT`` environment variable if that is positive, or otherwise treat this as 0. **Warning:** When used, this timeout must be larger than ``SBD_WATCHDOG_TIMEOUT`` on all nodes that use watchdog-based SBD, and Pacemaker will refuse to start on any of those nodes where this is not true for the local value or SBD is not active. When this is set to a negative value, ``SBD_WATCHDOG_TIMEOUT`` must be set to the same value on all nodes that use SBD, otherwise data corruption or loss could occur. - - * - .. _concurrent-fencing: - - .. index:: - pair: cluster option; concurrent-fencing - - concurrent-fencing - - :ref:`boolean ` - - false - - Whether the cluster is allowed to initiate multiple fence actions - concurrently. Fence actions initiated externally, such as via the - ``stonith_admin`` tool or an application such as DLM, or by the fencer - itself such as recurring device monitors and ``status`` and ``list`` - commands, are not limited by this option. * - .. _fencing_reaction: .. index:: pair: cluster option; fencing-reaction fencing-reaction - :ref:`enumeration ` - stop - How should a cluster node react if notified of its own fencing? A cluster node may receive notification of a "succeeded" fencing that targeted it if fencing is misconfigured, or if fabric fencing is in use that doesn't cut cluster communication. Allowed values are ``stop`` to attempt to immediately stop Pacemaker and stay stopped, or ``panic`` to attempt to immediately reboot the local node, falling back to stop on failure. The default is likely to be changed to ``panic`` in a future release. *(since 2.0.3)* * - .. _priority_fencing_delay: .. index:: pair: cluster option; priority-fencing-delay priority-fencing-delay - :ref:`duration ` - 0 - Apply this delay to any fencing targeting the lost nodes with the highest total resource priority in case we don't have the majority of the nodes in our cluster partition, so that the more significant nodes potentially win any fencing match (especially meaningful in a split-brain of a 2-node cluster). A promoted resource instance takes the resource's priority plus 1 if the resource's priority is not 0. Any static or random delays introduced by ``pcmk_delay_base`` and ``pcmk_delay_max`` configured for the corresponding fencing resources will be added to this delay. This delay should be significantly greater than (safely twice) the maximum delay from those parameters. *(since 2.0.4)* * - .. _node_pending_timeout: .. index:: pair: cluster option; node-pending-timeout node-pending-timeout - :ref:`duration ` - 0 - Fence nodes that do not join the controller process group within this much time after joining the cluster, to allow the cluster to continue managing resources. A value of 0 means never fence pending nodes. Setting the value to 2h means fence nodes after 2 hours. *(since 2.1.7)* * - .. _cluster_delay: .. index:: pair: cluster option; cluster-delay cluster-delay - :ref:`duration ` - 60s - If the DC requires an action to be executed on another node, it will consider the action failed if it does not get a response from the other node within this time (beyond the action's own timeout). The ideal value will depend on the speed and load of your network and cluster nodes. * - .. _dc_deadtime: .. index:: pair: cluster option; dc-deadtime dc-deadtime - :ref:`duration ` - 20s - How long to wait for a response from other nodes when electing a DC. The ideal value will depend on the speed and load of your network and cluster nodes. * - .. _pe_error_series_max: .. index:: pair: cluster option; pe-error-series-max pe-error-series-max - :ref:`integer ` - -1 - The number of scheduler inputs resulting in errors to save. These inputs can be helpful during troubleshooting and when reporting issues. A negative value means save all inputs, and 0 means save none. * - .. _pe_warn_series_max: .. index:: pair: cluster option; pe-warn-series-max pe-warn-series-max - :ref:`integer ` - 5000 - The number of scheduler inputs resulting in warnings to save. These inputs can be helpful during troubleshooting and when reporting issues. A negative value means save all inputs, and 0 means save none. * - .. _pe_input_series_max: .. index:: pair: cluster option; pe-input-series-max pe-input-series-max - :ref:`integer ` - 4000 - The number of "normal" scheduler inputs to save. These inputs can be helpful during troubleshooting and when reporting issues. A negative value means save all inputs, and 0 means save none. * - .. _enable_acl: .. index:: pair: cluster option; enable-acl enable-acl - :ref:`boolean ` - false - Whether :ref:`access control lists ` should be used to authorize CIB modifications * - .. _placement_strategy: .. index:: pair: cluster option; placement-strategy placement-strategy - :ref:`enumeration ` - default - How the cluster should assign resources to nodes (see :ref:`utilization`). Allowed values are ``default``, ``utilization``, ``balanced``, and ``minimal``. * - .. _node_health_strategy: .. index:: pair: cluster option; node-health-strategy node-health-strategy - :ref:`enumeration ` - none - How the cluster should react to :ref:`node health ` attributes. Allowed values are ``none``, ``migrate-on-red``, ``only-green``, ``progressive``, and ``custom``. * - .. _node_health_base: .. index:: pair: cluster option; node-health-base node-health-base - :ref:`score ` - 0 - The base health score assigned to a node. Only used when ``node-health-strategy`` is ``progressive``. * - .. _node_health_green: .. index:: pair: cluster option; node-health-green node-health-green - :ref:`score ` - 0 - The score to use for a node health attribute whose value is ``green``. Only used when ``node-health-strategy`` is ``progressive`` or ``custom``. * - .. _node_health_yellow: .. index:: pair: cluster option; node-health-yellow node-health-yellow - :ref:`score ` - 0 - The score to use for a node health attribute whose value is ``yellow``. Only used when ``node-health-strategy`` is ``progressive`` or ``custom``. * - .. _node_health_red: .. index:: pair: cluster option; node-health-red node-health-red - :ref:`score ` - -INFINITY - The score to use for a node health attribute whose value is ``red``. Only used when ``node-health-strategy`` is ``progressive`` or ``custom``. * - .. _cluster_recheck_interval: .. index:: pair: cluster option; cluster-recheck-interval cluster-recheck-interval - :ref:`duration ` - 15min - Pacemaker is primarily event-driven, and looks ahead to know when to recheck the cluster for failure-timeout settings and most time-based rules *(since 2.0.3)*. However, it will also recheck the cluster after this amount of inactivity. This has three main effects: * :ref:`Rules ` using ``date_spec`` are guaranteed to be checked only this often. * If :ref:`fencing ` fails enough to reach :ref:`fencing-max-attempts `, attempts will begin again after at most this time. * It serves as a fail-safe in case of certain scheduler bugs. If the scheduler incorrectly determines only some of the actions needed to react to a particular event, it will often correctly determine the rest after at most this time. A value of 0 disables this polling. * - .. _shutdown_lock: .. index:: pair: cluster option; shutdown-lock shutdown-lock - :ref:`boolean ` - false - The default of false allows active resources to be recovered elsewhere when their node is cleanly shut down, which is what the vast majority of users will want. However, some users prefer to make resources highly available only for failures, with no recovery for clean shutdowns. If this option is true, resources active on a node when it is cleanly shut down are kept "locked" to that node (not allowed to run elsewhere) until they start again on that node after it rejoins (or for at most ``shutdown-lock-limit``, if set). Stonith resources and Pacemaker Remote connections are never locked. Clone and bundle instances and the promoted role of promotable clones are currently never locked, though support could be added in a future release. Locks may be manually cleared using the ``--refresh`` option of ``crm_resource`` (both the resource and node must be specified; this works with remote nodes if their connection resource's ``target-role`` is set to ``Stopped``, but not if Pacemaker Remote is stopped on the remote node without disabling the connection resource). *(since 2.0.4)* * - .. _shutdown_lock_limit: .. index:: pair: cluster option; shutdown-lock-limit shutdown-lock-limit - :ref:`duration ` - 0 - If ``shutdown-lock`` is true, and this is set to a nonzero time duration, locked resources will be allowed to start after this much time has passed since the node shutdown was initiated, even if the node has not rejoined. (This works with remote nodes only if their connection resource's ``target-role`` is set to ``Stopped``.) *(since 2.0.4)* * - .. _startup_fencing: .. index:: pair: cluster option; startup-fencing startup-fencing - :ref:`boolean ` - true - *Advanced Use Only:* Whether the cluster should fence unseen nodes at start-up. Setting this to false is unsafe, because the unseen nodes could be active and running resources but unreachable. ``dc-deadtime`` acts as a grace period before this fencing, since a DC must be elected to schedule fencing. * - .. _election_timeout: .. index:: pair: cluster option; election-timeout election-timeout - :ref:`duration ` - 2min - *Advanced Use Only:* If a winner is not declared within this much time of starting an election, the node that initiated the election will declare itself the winner. * - .. _shutdown_escalation: .. index:: pair: cluster option; shutdown-escalation shutdown-escalation - :ref:`duration ` - 20min - *Advanced Use Only:* The controller will exit immediately if a shutdown does not complete within this much time. * - .. _join_integration_timeout: .. index:: pair: cluster option; join-integration-timeout join-integration-timeout - :ref:`duration ` - 3min - *Advanced Use Only:* If you need to adjust this value, it probably indicates the presence of a bug. * - .. _join_finalization_timeout: .. index:: pair: cluster option; join-finalization-timeout join-finalization-timeout - :ref:`duration ` - 30min - *Advanced Use Only:* If you need to adjust this value, it probably indicates the presence of a bug. * - .. _transition_delay: .. index:: pair: cluster option; transition-delay transition-delay - :ref:`duration ` - 0s - *Advanced Use Only:* Delay cluster recovery for the configured interval to allow for additional or related events to occur. This can be useful if your configuration is sensitive to the order in which ping updates arrive. Enabling this option will slow down cluster recovery under all conditions. diff --git a/doc/sphinx/Pacemaker_Explained/fencing.rst b/doc/sphinx/Pacemaker_Explained/fencing.rst index 6c60632879..29b9e16872 100644 --- a/doc/sphinx/Pacemaker_Explained/fencing.rst +++ b/doc/sphinx/Pacemaker_Explained/fencing.rst @@ -1,1283 +1,1275 @@ .. index:: single: fencing single: STONITH .. _fencing: Fencing ------- What Is Fencing? ################ *Fencing* is the ability to make a node unable to run resources, even when that node is unresponsive to cluster commands. Fencing is also known as *STONITH*, an acronym for "Shoot The Other Node In The Head", since the most common fencing method is cutting power to the node. Another method is "fabric fencing", cutting the node's access to some capability required to run resources (such as network access or a shared disk). .. index:: single: fencing; why necessary Why Is Fencing Necessary? ######################### Fencing protects your data from being corrupted by malfunctioning nodes or unintentional concurrent access to shared resources. Fencing protects against the "split brain" failure scenario, where cluster nodes have lost the ability to reliably communicate with each other but are still able to run resources. If the cluster just assumed that uncommunicative nodes were down, then multiple instances of a resource could be started on different nodes. The effect of split brain depends on the resource type. For example, an IP address brought up on two hosts on a network will cause packets to randomly be sent to one or the other host, rendering the IP useless. For a database or clustered file system, the effect could be much more severe, causing data corruption or divergence. Fencing is also used when a resource cannot otherwise be stopped. If a resource fails to stop on a node, it cannot be started on a different node without risking the same type of conflict as split-brain. Fencing the original node ensures the resource can be safely started elsewhere. Users may also configure the ``on-fail`` property of :ref:`operation` or the ``loss-policy`` property of :ref:`ticket constraints ` to ``fence``, in which case the cluster will fence the resource's node if the operation fails or the ticket is lost. .. index:: single: fencing; device Fence Devices ############# A *fence device* or *fencing device* is a special type of resource that provides the means to fence a node. Examples of fencing devices include intelligent power switches and IPMI devices that accept SNMP commands to cut power to a node, and iSCSI controllers that allow SCSI reservations to be used to cut a node's access to a shared disk. Since fencing devices will be used to recover from loss of networking connectivity to other nodes, it is essential that they do not rely on the same network as the cluster itself, otherwise that network becomes a single point of failure. Since loss of a node due to power outage is indistinguishable from loss of network connectivity to that node, it is also essential that at least one fence device for a node does not share power with that node. For example, an on-board IPMI controller that shares power with its host should not be used as the sole fencing device for that host. Since fencing is used to isolate malfunctioning nodes, no fence device should rely on its target functioning properly. This includes, for example, devices that ssh into a node and issue a shutdown command (such devices might be suitable for testing, but never for production). .. index:: single: fencing; agent Fence Agents ############ A *fence agent* or *fencing agent* is a ``stonith``-class resource agent. The fence agent standard provides commands (such as ``off`` and ``reboot``) that the cluster can use to fence nodes. As with other resource agent classes, this allows a layer of abstraction so that Pacemaker doesn't need any knowledge about specific fencing technologies -- that knowledge is isolated in the agent. Pacemaker supports two fence agent standards, both inherited from no-longer-active projects: * Red Hat Cluster Suite (RHCS) style: These are typically installed in ``/usr/sbin`` with names starting with ``fence_``. * Linux-HA style: These typically have names starting with ``external/``. Pacemaker can support these agents using the **fence_legacy** RHCS-style agent as a wrapper, *if* support was enabled when Pacemaker was built, which requires the ``cluster-glue`` library. When a Fence Device Can Be Used ############################### Fencing devices do not actually "run" like most services. Typically, they just provide an interface for sending commands to an external device. Additionally, fencing may be initiated by Pacemaker, by other cluster-aware software such as DRBD or DLM, or manually by an administrator, at any point in the cluster life cycle, including before any resources have been started. To accommodate this, Pacemaker does not require the fence device resource to be "started" in order to be used. Whether a fence device is started or not determines whether a node runs any recurring monitor for the device, and gives the node a slight preference for being chosen to execute fencing using that device. By default, any node can execute any fencing device. If a fence device is disabled by setting its ``target-role`` to ``Stopped``, then no node can use that device. If a location constraint with a negative score prevents a specific node from "running" a fence device, then that node will never be chosen to execute fencing using the device. A node may fence itself, but the cluster will choose that only if no other nodes can do the fencing. A common configuration scenario is to have one fence device per target node. In such a case, users often configure anti-location constraints so that the target node does not monitor its own device. Limitations of Fencing Resources ################################ Fencing resources have certain limitations that other resource classes don't: * They may have only one set of meta-attributes and one set of instance attributes. * If :ref:`rules` are used to determine fencing resource options, these might be evaluated only when first read, meaning that later changes to the rules will have no effect. Therefore, it is better to avoid confusion and not use rules at all with fencing resources. These limitations could be revisited if there is sufficient user demand. .. index:: single: fencing; special instance attributes Special Meta-Attributes for Fencing Resources ############################################# The table below lists special resource meta-attributes that may be set for any fencing resource. .. list-table:: **Additional Properties of Fencing Resources** :widths: 10 10 10 70 :header-rows: 1 * - Field - Type - Default - Description * - provides - string - - .. index:: single: provides Any special capability provided by the fence device. Currently, only one such capability is meaningful: :ref:`unfencing `. .. _fencing-attributes: Special Instance Attributes for Fencing Resources ################################################# The table below lists special instance attributes that may be set for any fencing resource (*not* meta-attributes, even though they are interpreted by Pacemaker rather than the fence agent). These are also listed in the man page for ``pacemaker-fenced``. .. list-table:: **Additional Properties of Fencing Resources** :class: longtable :widths: 22 10 20 48 :header-rows: 1 * - Name - Type - Default - Description * - .. _primitive_stonith_timeout: .. index:: single: stonith-timeout (primitive instance attribute) stonith-timeout - :ref:`timeout ` - - This is not used by Pacemaker (see the ``pcmk_reboot_timeout``, ``pcmk_off_timeout``, etc., properties instead), but it may be used by Linux-HA fence agents. * - .. _pcmk_host_map: .. index:: single: pcmk_host_map pcmk_host_map - :ref:`text ` - - A mapping of node names to ports for devices that do not understand the node names. For example, ``node1:1;node2:2,3`` tells the cluster to use port 1 for ``node1`` and ports 2 and 3 for ``node2``. If ``pcmk_host_check`` is explicitly set to ``static-list``, either this or ``pcmk_host_list`` must be set. The port portion of the map may contain special characters such as spaces if preceded by a backslash *(since 2.1.2)*. * - .. _pcmk_host_list: .. index:: single: pcmk_host_list pcmk_host_list - :ref:`text ` - - Comma-separated list of nodes that can be targeted by this device (for example, ``node1,node2,node3``). If pcmk_host_check is ``static-list``, either this or ``pcmk_host_map`` must be set. * - .. _pcmk_host_check: .. index:: single: pcmk_host_check pcmk_host_check - :ref:`text ` - See :ref:`pcmk_host_check_default` - The method Pacemaker should use to determine which nodes can be targeted by this device. Allowed values: * ``static-list:`` targets are listed in the ``pcmk_host_list`` or ``pcmk_host_map`` attribute * ``dynamic-list:`` query the device via the agent's ``list`` action * ``status:`` query the device via the agent's ``status`` action * ``none:`` assume the device can fence any node * - .. _pcmk_delay_max: .. index:: single: pcmk_delay_max pcmk_delay_max - :ref:`duration ` - 0s - Enable a delay of no more than the time specified before executing fencing actions. Pacemaker derives the overall delay by taking the value of pcmk_delay_base and adding a random delay value such that the sum is kept below this maximum. This is sometimes used in two-node clusters to ensure that the nodes don't fence each other at the same time. * - .. _pcmk_delay_base: .. index:: single: pcmk_delay_base pcmk_delay_base - :ref:`text ` - 0s - Enable a static delay before executing fencing actions. This can be used, for example, in two-node clusters to ensure that the nodes don't fence each other, by having separate fencing resources with different values. The node that is fenced with the shorter delay will lose a fencing race. The overall delay introduced by pacemaker is derived from this value plus a random delay such that the sum is kept below the maximum delay. A single device can have different delays per node using a host map *(since 2.1.2)*, for example ``node1:0s;node2:5s.`` * - .. _pcmk_action_limit: .. index:: single: pcmk_action_limit pcmk_action_limit - :ref:`integer ` - 1 - The maximum number of actions that can be performed in parallel on this - device. A value of -1 means unlimited. Node fencing actions initiated by - the cluster (as opposed to an administrator running the + device. A value of -1 means unlimited. For node fencing actions initiated + by the cluster (as opposed to an administrator running the ``stonith_admin`` tool or the fencer running recurring device monitors - and ``status`` and ``list`` commands) are additionally subject to the - ``concurrent-fencing`` cluster property. + and ``status`` and ``list`` commands), this applies only if the + deprecated ``concurrent-fencing`` cluster property is set to true (the + default). * - .. _pcmk_host_argument: .. index:: single: pcmk_host_argument pcmk_host_argument - :ref:`text ` - ``port`` if the fence agent metadata advertises support for it, otherwise ``plug`` if supported, otherwise ``none`` - *Advanced use only.* Which parameter should be supplied to the fence agent to identify the node to be fenced. A value of ``none`` tells the cluster not to supply any additional parameters. * - .. _pcmk_reboot_action: .. index:: single: pcmk_reboot_action pcmk_reboot_action - :ref:`text ` - ``reboot`` - *Advanced use only.* The command to send to the resource agent in order to reboot a node. Some devices do not support the standard commands or may provide additional ones. Use this to specify an alternate, device-specific command. * - .. _pcmk_reboot_timeout: .. index:: single: pcmk_reboot_timeout pcmk_reboot_timeout - :ref:`timeout ` - 60s - *Advanced use only.* Specify an alternate timeout (in seconds) to use for ``reboot`` actions instead of the value of ``fencing-timeout``. Some devices need much more or less time to complete than normal. Use this to specify an alternate, device-specific timeout. * - .. _pcmk_reboot_retries: .. index:: single: pcmk_reboot_retries pcmk_reboot_retries - :ref:`integer ` - 2 - *Advanced use only.* The maximum number of times to retry the ``reboot`` command within the timeout period. Some devices do not support multiple connections, and operations may fail if the device is busy with another task, so Pacemaker will automatically retry the operation, if there is time remaining. Use this option to alter the number of times Pacemaker retries before giving up. * - .. _pcmk_off_action: .. index:: single: pcmk_off_action pcmk_off_action - :ref:`text ` - ``off`` - *Advanced use only.* The command to send to the resource agent in order to shut down a node. Some devices do not support the standard commands or may provide additional ones. Use this to specify an alternate, device-specific command. * - .. _pcmk_off_timeout: .. index:: single: pcmk_off_timeout pcmk_off_timeout - :ref:`timeout ` - 60s - *Advanced use only.* Specify an alternate timeout (in seconds) to use for ``off`` actions instead of the value of ``fencing-timeout``. Some devices need much more or less time to complete than normal. Use this to specify an alternate, device-specific timeout. * - .. _pcmk_off_retries: .. index:: single: pcmk_off_retries pcmk_off_retries - :ref:`integer ` - 2 - *Advanced use only.* The maximum number of times to retry the ``off`` command within the timeout period. Some devices do not support multiple connections, and operations may fail if the device is busy with another task, so Pacemaker will automatically retry the operation, if there is time remaining. Use this option to alter the number of times Pacemaker retries before giving up. * - .. _pcmk_list_action: .. index:: single: pcmk_list_action pcmk_list_action - :ref:`text ` - ``list`` - *Advanced use only.* The command to send to the resource agent in order to list nodes. Some devices do not support the standard commands or may provide additional ones. Use this to specify an alternate, device-specific command. * - .. _pcmk_list_timeout: .. index:: single: pcmk_list_timeout pcmk_list_timeout - :ref:`timeout ` - 60s - *Advanced use only.* Specify an alternate timeout (in seconds) to use for ``list`` actions instead of the value of ``fencing-timeout``. Some devices need much more or less time to complete than normal. Use this to specify an alternate, device-specific timeout. * - .. _pcmk_list_retries: .. index:: single: pcmk_list_retries pcmk_list_retries - :ref:`integer ` - 2 - *Advanced use only.* The maximum number of times to retry the ``list`` command within the timeout period. Some devices do not support multiple connections, and operations may fail if the device is busy with another task, so Pacemaker will automatically retry the operation, if there is time remaining. Use this option to alter the number of times Pacemaker retries before giving up. * - .. _pcmk_monitor_action: .. index:: single: pcmk_monitor_action pcmk_monitor_action - :ref:`text ` - ``monitor`` - *Advanced use only.* The command to send to the resource agent in order to report extended status. Some devices do not support the standard commands or may provide additional ones. Use this to specify an alternate, device-specific command. * - .. _pcmk_monitor_timeout: .. index:: single: pcmk_monitor_timeout pcmk_monitor_timeout - :ref:`timeout ` - 60s - *Advanced use only.* Specify an alternate timeout (in seconds) to use for ``monitor`` actions instead of the value of ``fencing-timeout``. Some devices need much more or less time to complete than normal. Use this to specify an alternate, device-specific timeout. * - .. _pcmk_monitor_retries: .. index:: single: pcmk_monitor_retries pcmk_monitor_retries - :ref:`integer ` - 2 - *Advanced use only.* The maximum number of times to retry the ``monitor`` command within the timeout period. Some devices do not support multiple connections, and operations may fail if the device is busy with another task, so Pacemaker will automatically retry the operation, if there is time remaining. Use this option to alter the number of times Pacemaker retries before giving up. * - .. _pcmk_status_action: .. index:: single: pcmk_status_action pcmk_status_action - :ref:`text ` - ``status`` - *Advanced use only.* The command to send to the resource agent in order to report status. Some devices do not support the standard commands or may provide additional ones. Use this to specify an alternate, device-specific command. * - .. _pcmk_status_timeout: .. index:: single: pcmk_status_timeout pcmk_status_timeout - :ref:`timeout ` - 60s - *Advanced use only.* Specify an alternate timeout (in seconds) to use for ``status`` actions instead of the value of ``fencing-timeout``. Some devices need much more or less time to complete than normal. Use this to specify an alternate, device-specific timeout. * - .. _pcmk_status_retries: .. index:: single: pcmk_status_retries pcmk_status_retries - :ref:`integer ` - 2 - *Advanced use only.* The maximum number of times to retry the ``status`` command within the timeout period. Some devices do not support multiple connections, and operations may fail if the device is busy with another task, so Pacemaker will automatically retry the operation, if there is time remaining. Use this option to alter the number of times Pacemaker retries before giving up. .. _pcmk_host_check_default: Default Check Type ################## If the user does not explicitly configure ``pcmk_host_check`` for a fence device, a default value appropriate to other configured parameters will be used: * If either ``pcmk_host_list`` or ``pcmk_host_map`` is configured, ``static-list`` will be used; * otherwise, if the fence device supports the ``list`` action, and the first attempt at using ``list`` succeeds, ``dynamic-list`` will be used; * otherwise, if the fence device supports the ``status`` action, ``status`` will be used; * otherwise, ``none`` will be used. .. index:: single: unfencing single: fencing; unfencing .. _unfencing: Unfencing ######### With fabric fencing (such as cutting network or shared disk access rather than power), it is expected that the cluster will fence the node, and then a system administrator must manually investigate what went wrong, correct any issues found, then reboot (or restart the cluster services on) the node. Once the node reboots and rejoins the cluster, some fabric fencing devices require an explicit command to restore the node's access. This capability is called *unfencing* and is typically implemented as the fence agent's ``on`` command. If any cluster resource has ``requires`` set to ``unfencing``, then that resource will not be probed or started on a node until that node has been unfenced. Fencing and Quorum ################## In general, a cluster partition may execute fencing only if the partition has quorum, and the ``fencing-enabled`` cluster property is set to true. However, there are exceptions: * The requirements apply only to fencing initiated by Pacemaker. If an administrator initiates fencing using the ``stonith_admin`` command, or an external application such as DLM initiates fencing using Pacemaker's C API, the requirements do not apply. * A cluster partition without quorum is allowed to fence any active member of that partition. As a corollary, this allows a ``no-quorum-policy`` of ``suicide`` to work. * If the ``no-quorum-policy`` cluster property is set to ``ignore``, then quorum is not required to execute fencing of any node. Fencing Timeouts ################ Fencing timeouts are complicated, since a single fencing operation can involve many steps, each of which may have a separate timeout. Fencing may be initiated in one of several ways: * An administrator may initiate fencing using the ``stonith_admin`` tool, which has a ``--timeout`` option (defaulting to 2 minutes) that will be used as the fence operation timeout. * An external application such as DLM may initiate fencing using the Pacemaker C API. The application will specify the fence operation timeout in this case, which might or might not be configurable by the user. * The cluster may initiate fencing itself. In this case, the ``fencing-timeout`` cluster property (defaulting to 1 minute) will be used as the fence operation timeout. However fencing is initiated, the initiator contacts Pacemaker's fencer (``pacemaker-fenced``) to request fencing. This connection and request has its own timeout, separate from the fencing operation timeout, but usually happens very quickly. The fencer will contact all fencers in the cluster to ask what devices they have available to fence the target node. The fence operation timeout will be used as the timeout for each of these queries. Once a fencing device has been selected, the fencer will check whether any action-specific timeout has been configured for the device, to use instead of the fence operation timeout. For example, if ``fencing-timeout`` is 60 seconds, but the fencing device has ``pcmk_reboot_timeout`` configured as 90 seconds, then a timeout of 90 seconds will be used for reboot actions using that device. A device may have retries configured, in which case the timeout applies across all attempts. For example, if a device has ``pcmk_reboot_retries`` configured as 2, and the first reboot attempt fails, the second attempt will only have whatever time is remaining in the action timeout after subtracting how much time the first attempt used. This means that if the first attempt fails due to using the entire timeout, no further attempts will be made. There is currently no way to configure a per-attempt timeout. If more than one device is required to fence a target, whether due to failure of the first device or a fencing topology with multiple devices configured for the target, each device will have its own separate action timeout. For all of the above timeouts, the fencer will generally multiply the configured value by 1.2 to get an actual value to use, to account for time needed by the fencer's own processing. Separate from the fencer's timeouts, some fence agents have internal timeouts for individual steps of their fencing process. These agents often have parameters to configure these timeouts, such as ``login-timeout``, ``shell-timeout``, or ``power-timeout``. Many such agents also have a ``disable-timeout`` parameter to ignore their internal timeouts and just let Pacemaker handle the timeout. This causes a difference in retry behavior. If ``disable-timeout`` is not set, and the agent hits one of its internal timeouts, it will report that as a failure to Pacemaker, which can then retry. If ``disable-timeout`` is set, and Pacemaker hits a timeout for the agent, then there will be no time remaining, and no retry will be done. Fence Devices Dependent on Other Resources ########################################## In some cases, a fence device may require some other cluster resource (such as an IP address) to be active in order to function properly. This is obviously undesirable in general: fencing may be required when the depended-on resource is not active, or fencing may be required because the node running the depended-on resource is no longer responding. However, this may be acceptable under certain conditions: * The dependent fence device should not be able to target any node that is allowed to run the depended-on resource. * The depended-on resource should not be disabled during production operation. -* The ``concurrent-fencing`` cluster property should be set to ``true``. - Otherwise, if both the node running the depended-on resource and some node - targeted by the dependent fence device need to be fenced, the fencing of the - node running the depended-on resource might be ordered first, making the - second fencing impossible and blocking further recovery. With concurrent - fencing, the dependent fence device might fail at first due to the - depended-on resource being unavailable, but it will be retried and eventually - succeed once the resource is brought back up. - Even under those conditions, there is one unlikely problem scenario. The DC always schedules fencing of itself after any other fencing needed, to avoid unnecessary repeated DC elections. If the dependent fence device targets the DC, and both the DC and a different node running the depended-on resource need to be fenced, the DC fencing will always fail and block further recovery. Note, however, that losing a DC node entirely causes some other node to become DC and schedule the fencing, so this is only a risk when a stop or other operation with ``on-fail`` set to ``fencing`` fails on the DC. .. index:: single: fencing; configuration Configuring Fencing ################### Higher-level tools can provide simpler interfaces to this process, but using Pacemaker command-line tools, this is how you could configure a fence device. #. Find the correct driver: .. code-block:: none # stonith_admin --list-installed .. note:: You may have to install packages to make fence agents available on your host. Searching your available packages for ``fence-`` is usually helpful. Ensure the packages providing the fence agents you require are installed on every cluster node. #. Find the required parameters associated with the device (replacing ``$AGENT_NAME`` with the name obtained from the previous step): .. code-block:: none # stonith_admin --metadata --agent $AGENT_NAME #. Create a file called ``fencing.xml`` containing a primitive resource with a class of ``stonith``, a type equal to the agent name obtained earlier, and a parameter for each of the values returned in the previous step. #. If the device does not know how to fence nodes based on their uname, you may also need to set the special ``pcmk_host_map`` parameter. See :ref:`fencing-attributes` for details. #. If the device does not support the ``list`` command, you may also need to set the special ``pcmk_host_list`` and/or ``pcmk_host_check`` parameters. See :ref:`fencing-attributes` for details. #. If the device does not expect the target to be specified with the ``port`` parameter, you may also need to set the special ``pcmk_host_argument`` parameter. See :ref:`fencing-attributes` for details. #. Upload it into the CIB using cibadmin: .. code-block:: none # cibadmin --create --scope resources --xml-file fencing.xml #. Set ``fencing-enabled`` to true: .. code-block:: none # crm_attribute --type crm_config --name fencing-enabled --update true #. Once the fencing resource is running, you can test it by executing the following, replacing ``$NODE_NAME`` with the name of the node to fence (although you might want to stop the cluster on that machine first): .. code-block:: none # stonith_admin --reboot $NODE_NAME Example Fencing Configuration _____________________________ For this example, we assume we have a cluster node, ``pcmk-1``, whose IPMI controller is reachable at the IP address 192.0.2.1. The IPMI controller uses the username ``testuser`` and the password ``abc123``. #. Looking at what's installed, we may see a variety of available agents: .. code-block:: none # stonith_admin --list-installed .. code-block:: none (... some output omitted ...) fence_idrac fence_ilo3 fence_ilo4 fence_ilo5 fence_imm fence_ipmilan (... some output omitted ...) Perhaps after some reading some man pages and doing some Internet searches, we might decide ``fence_ipmilan`` is our best choice. #. Next, we would check what parameters ``fence_ipmilan`` provides: .. code-block:: none # stonith_admin --metadata -a fence_ipmilan .. code-block:: xml fence_ipmilan is an I/O Fencing agentwhich can be used with machines controlled by IPMI.This agent calls support software ipmitool (http://ipmitool.sf.net/). WARNING! This fence agent might report success before the node is powered off. You should use -m/method onoff if your fence device works correctly with that option. Fencing action IPMI Lan Auth type. Ciphersuite to use (same as ipmitool -C parameter) Hexadecimal-encoded Kg key for IPMIv2 authentication IP address or hostname of fencing device IP address or hostname of fencing device TCP/UDP port to use for connection with device Use Lanplus to improve security of connection Login name Method to fence Login password or passphrase Script to run to retrieve password Login password or passphrase Script to run to retrieve password IP address or hostname of fencing device (together with --port-as-ip) IP address or hostname of fencing device (together with --port-as-ip) Privilege level on IPMI device Bridge IPMI requests to the remote target address Login name Disable logging to stderr. Does not affect --verbose or --debug-file or logging to syslog. Verbose mode Write debug information to given file Write debug information to given file Display version information and exit Display help and exit Wait X seconds before fencing is started Path to ipmitool binary Wait X seconds for cmd prompt after login Make "port/plug" to be an alias to IP address Test X seconds for status change after ON/OFF Wait X seconds after issuing ON/OFF Wait X seconds for cmd prompt after issuing command Count of attempts to retry power on Use sudo (without password) when calling 3rd party software Use sudo (without password) when calling 3rd party software Path to sudo binary Once we've decided what parameter values we think we need, it is a good idea to run the fence agent's status action manually, to verify that our values work correctly: .. code-block:: none # fence_ipmilan --lanplus -a 192.0.2.1 -l testuser -p abc123 -o status Chassis Power is on #. Based on that, we might create a fencing resource configuration like this in ``fencing.xml`` (or any file name, just use the same name with ``cibadmin`` later): .. code-block:: xml .. note:: Even though the man page shows that the ``action`` parameter is supported, we do not provide that in the resource configuration. Pacemaker will supply an appropriate action whenever the fence device must be used. #. In this case, we don't need to configure ``pcmk_host_map`` because ``fence_ipmilan`` ignores the target node name and instead uses its ``ip`` parameter to know how to contact the IPMI controller. #. We do need to let Pacemaker know which cluster node can be fenced by this device, since ``fence_ipmilan`` doesn't support the ``list`` action. Add a line like this to the agent's instance attributes: .. code-block:: xml #. We don't need to configure ``pcmk_host_argument`` since ``ip`` is all the fence agent needs (it ignores the target name). #. Make the configuration active: .. code-block:: none # cibadmin --create --scope resources --xml-file fencing.xml #. Set ``fencing-enabled`` to true (this only has to be done once): .. code-block:: none # crm_attribute --type crm_config --name fencing-enabled --update true #. Since our cluster is still in testing, we can reboot ``pcmk-1`` without bothering anyone, so we'll test our fencing configuration by running this from one of the other cluster nodes: .. code-block:: none # stonith_admin --reboot pcmk-1 Then we will verify that the node did, in fact, reboot. We can repeat that process to create a separate fencing resource for each node. With some other fence device types, a single fencing resource is able to be used for all nodes. In fact, we could do that with ``fence_ipmilan``, using the ``port-as-ip`` parameter along with ``pcmk_host_map``. Either approach is fine. .. index:: single: fencing; topology single: fencing-topology single: fencing-level Fencing Topologies ################## Pacemaker supports fencing nodes with multiple devices through a feature called *fencing topologies*. Fencing topologies may be used to provide alternative devices in case one fails, or to require multiple devices to all be executed successfully in order to consider the node successfully fenced, or even a combination of the two. Create the individual devices as you normally would, then define one or more ``fencing-level`` entries in the ``fencing-topology`` section of the configuration. * Each fencing level is attempted in order of ascending ``index``. Allowed values are 1 through 9. * If a device fails, processing terminates for the current level. No further devices in that level are exercised, and the next level is attempted instead. * If the operation succeeds for all the listed devices in a level, the level is deemed to have passed. * The operation is finished when a level has passed (success), or all levels have been attempted (failed). * If the operation failed, the next step is determined by the scheduler and/or the controller. Some possible uses of topologies include: * Try on-board IPMI, then an intelligent power switch if that fails * Try fabric fencing of both disk and network, then fall back to power fencing if either fails * Wait up to a certain time for a kernel dump to complete, then cut power to the node .. list-table:: **Attributes of a fencing-level Element** :class: longtable :widths: 25 75 :header-rows: 1 * - Attribute - Description * - id - .. index:: pair: fencing-level; id A unique name for this element (required) * - target - .. index:: pair: fencing-level; target The name of a single node to which this level applies * - target-pattern - .. index:: pair: fencing-level; target-pattern An extended regular expression (as defined in `POSIX `_) matching the names of nodes to which this level applies * - target-attribute - .. index:: pair: fencing-level; target-attribute The name of a node attribute that is set (to ``target-value``) for nodes to which this level applies * - target-value - .. index:: pair: fencing-level; target-value The node attribute value (of ``target-attribute``) that is set for nodes to which this level applies * - index - .. index:: pair: fencing-level; index The order in which to attempt the levels. Levels are attempted in ascending order *until one succeeds*. Valid values are 1 through 9. * - devices - .. index:: pair: fencing-level; devices A comma-separated list of devices that must all be tried for this level .. note:: **Fencing topology with different devices for different nodes** .. code-block:: xml ... ... Example Dual-Layer, Dual-Device Fencing Topologies __________________________________________________ The following example illustrates an advanced use of ``fencing-topology`` in a cluster with the following properties: * 2 nodes (prod-mysql1 and prod-mysql2) * the nodes have IPMI controllers reachable at 192.0.2.1 and 192.0.2.2 * the nodes each have two independent Power Supply Units (PSUs) connected to two independent Power Distribution Units (PDUs) reachable at 198.51.100.1 (port 10 and port 11) and 203.0.113.1 (port 10 and port 11) * fencing via the IPMI controller uses the ``fence_ipmilan`` agent (1 fence device per controller, with each device targeting a separate node) * fencing via the PDUs uses the ``fence_apc_snmp`` agent (1 fence device per PDU, with both devices targeting both nodes) * a random delay is used to lessen the chance of a "death match" * fencing topology is set to try IPMI fencing first then dual PDU fencing if that fails In a node failure scenario, Pacemaker will first select ``fence_ipmilan`` to try to kill the faulty node. Using the fencing topology, if that method fails, it will then move on to selecting ``fence_apc_snmp`` twice (once for the first PDU, then again for the second PDU). The fence action is considered successful only if both PDUs report the required status. If any of them fails, fencing loops back to the first fencing method, ``fence_ipmilan``, and so on, until the node is fenced or the fencing action is cancelled. .. note:: **First fencing method: single IPMI device per target** Each cluster node has it own dedicated IPMI controller that can be contacted for fencing using the following primitives: .. code-block:: xml .. note:: **Second fencing method: dual PDU devices** Each cluster node also has 2 distinct power supplies controlled by 2 distinct PDUs: * Node 1: PDU 1 port 10 and PDU 2 port 10 * Node 2: PDU 1 port 11 and PDU 2 port 11 The matching fencing agents are configured as follows: .. code-block:: xml .. note:: **Fencing topology** Now that all the fencing resources are defined, it's time to create the right topology. We want to first fence using IPMI and if that does not work, fence both PDUs to effectively and surely kill the node. .. code-block:: xml In ``fencing-topology``, the lowest ``index`` value for a target determines its first fencing method. Remapping Reboots ################# When the cluster needs to reboot a node, whether because ``fencing-action`` is ``reboot`` or because a reboot was requested externally (such as by ``stonith_admin --reboot``), it will remap that to other commands in two cases: * If the chosen fencing device does not support the ``reboot`` command, the cluster will ask it to perform ``off`` instead. * If a fencing topology level with multiple devices must be executed, the cluster will ask all the devices to perform ``off``, then ask the devices to perform ``on``. To understand the second case, consider the example of a node with redundant power supplies connected to intelligent power switches. Rebooting one switch and then the other would have no effect on the node. Turning both switches off, and then on, actually reboots the node. In such a case, the fencing operation will be treated as successful as long as the ``off`` commands succeed, because then it is safe for the cluster to recover any resources that were on the node. Timeouts and errors in the ``on`` phase will be logged but ignored. When a reboot operation is remapped, any action-specific timeout for the remapped action will be used (for example, ``pcmk_off_timeout`` will be used when executing the ``off`` command, not ``pcmk_reboot_timeout``). diff --git a/include/crm/common/scheduler_internal.h b/include/crm/common/scheduler_internal.h index 0a0f90d6ff..2f83896a34 100644 --- a/include/crm/common/scheduler_internal.h +++ b/include/crm/common/scheduler_internal.h @@ -1,311 +1,315 @@ /* * Copyright 2004-2025 the Pacemaker project contributors * * The version control history for this file may have further details. * * This source code is licensed under the GNU Lesser General Public License * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY. */ #ifndef PCMK__CRM_COMMON_SCHEDULER_INTERNAL__H #define PCMK__CRM_COMMON_SCHEDULER_INTERNAL__H #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif enum pcmk__check_parameters { /* Clear fail count if parameters changed for un-expired start or monitor * last_failure. */ pcmk__check_last_failure, /* Clear fail count if parameters changed for start, monitor, promote, or * migrate_from actions for active resources. */ pcmk__check_active, }; // Scheduling options and conditions enum pcmk__scheduler_flags { // No scheduler flags set (compare with equality rather than bit set) pcmk__sched_none = 0ULL, /* These flags are dynamically determined conditions */ // Whether partition has quorum (via \c PCMK_XA_HAVE_QUORUM attribute) //! \deprecated Call pcmk_has_quorum() to check quorum instead pcmk__sched_quorate = (1ULL << 0), // Whether cluster is symmetric (via symmetric-cluster property) pcmk__sched_symmetric_cluster = (1ULL << 1), // Whether scheduling encountered a non-configuration error pcmk__sched_processing_error = (1ULL << 2), // Whether cluster is in maintenance mode (via maintenance-mode property) pcmk__sched_in_maintenance = (1ULL << 3), // Whether fencing is enabled (via \c PCMK_OPT_FENCING_ENABLED property) pcmk__sched_fencing_enabled = (1ULL << 4), // Whether cluster has a fencing resource (via CIB resources) /*! \deprecated To indicate the cluster has a fencing resource, add either a * fencing resource configuration or the have-watchdog cluster option to the * input CIB */ pcmk__sched_have_fencing = (1ULL << 5), // Whether any resource provides or requires unfencing (via CIB resources) pcmk__sched_enable_unfencing = (1ULL << 6), - // Whether concurrent fencing is allowed (via concurrent-fencing property) + /* Whether concurrent fencing is allowed (via PCMK__OPT_CONCURRENT_FENCING + * property). + * + * @COMPAT The PCMK__OPT_CONCURRENT_FENCING property is deprecated. + */ pcmk__sched_concurrent_fencing = (1ULL << 7), /* * Whether resources removed from the configuration should be stopped (via * PCMK_OPT_STOP_REMOVED_RESOURCES property) */ pcmk__sched_stop_removed_resources = (1ULL << 8), /* * Whether recurring actions removed from the configuration should be * cancelled (via PCMK_OPT_CANCEL_REMOVED_ACTIONS property) */ pcmk__sched_cancel_removed_actions = (1ULL << 9), // Whether to stop all resources (via stop-all-resources property) pcmk__sched_stop_all = (1ULL << 10), // Whether scheduler processing encountered a warning pcmk__sched_processing_warning = (1ULL << 11), /* * Whether start failure should be treated as if * \c PCMK_META_MIGRATION_THRESHOLD is 1 (via * \c PCMK_OPT_START_FAILURE_IS_FATAL property) */ pcmk__sched_start_failure_fatal = (1ULL << 12), // Whether unseen nodes should be fenced (via startup-fencing property) pcmk__sched_startup_fencing = (1ULL << 14), /* * Whether resources should be left stopped when their node shuts down * cleanly (via shutdown-lock property) */ pcmk__sched_shutdown_lock = (1ULL << 15), /* * Whether resources' current state should be probed (when unknown) before * scheduling any other actions (via the PCMK__OPT_ENABLE_STARTUP_PROBES * property). * * @COMPAT Drop this when the PCMK__OPT_ENABLE_STARTUP_PROBES property is * dropped. */ pcmk__sched_probe_resources = (1ULL << 16), // Whether the CIB status section has been parsed yet pcmk__sched_have_status = (1ULL << 17), // Whether the cluster includes any Pacemaker Remote nodes (via CIB) pcmk__sched_have_remote_nodes = (1ULL << 18), /* The remaining flags are scheduling options that must be set explicitly */ /* * Whether to skip unpacking the CIB status section and stop the scheduling * sequence after applying node-specific location criteria (skipping * assignment, ordering, actions, etc.). */ pcmk__sched_location_only = (1ULL << 20), // Whether sensitive resource attributes have been masked pcmk__sched_sanitized = (1ULL << 21), // Skip counting of total, disabled, and blocked resource instances pcmk__sched_no_counts = (1ULL << 23), // Whether node scores should be output instead of logged pcmk__sched_output_scores = (1ULL << 25), // Whether to show node and resource utilization (in log or output) pcmk__sched_show_utilization = (1ULL << 26), /* * Whether to stop the scheduling sequence after unpacking the CIB, * calculating cluster status, and applying node health (skipping * applying node-specific location criteria, assignment, etc.) */ pcmk__sched_validate_only = (1ULL << 27), /* Can Pacemaker Remote nodes be fenced even from a node that doesn't * have quorum? */ pcmk__sched_fence_remote_no_quorum = (1ULL << 28), }; // Implementation of pcmk__scheduler_private_t struct pcmk__scheduler_private { // Be careful about when each piece of information is available and final char *local_node_name; // Name of node running scheduler (if known) crm_time_t *now; // Time to use when evaluating rules pcmk__output_t *out; // Output object for displaying messages GHashTable *options; // Cluster options const char *fence_action; // Default fencing action guint fence_timeout_ms; // Default fencing action timeout (in ms) guint priority_fencing_ms; // Priority-based fencing delay (in ms) guint shutdown_lock_ms; // How long to lock resources (in ms) guint node_pending_ms; // Pending join times out after this (in ms) // @TODO convert to enum const char *placement_strategy; // Value of placement-strategy property xmlNode *rsc_defaults; // Configured resource defaults xmlNode *op_defaults; // Configured operation defaults GList *resources; // Resources in cluster GHashTable *templates; // Key = template ID, value = resource list GHashTable *tags; // Key = tag ID, value = element list GList *actions; // All scheduled actions GHashTable *singletons; // Scheduled non-resource actions int next_action_id; // Counter used as ID for actions xmlNode *failed; // History entries of failed actions GList *param_check; // History entries that need to be checked GList *stop_needed; // Containers that need stop actions GList *location_constraints; // Location constraints GList *colocation_constraints; // Colocation constraints GList *ordering_constraints; // Ordering constraints GHashTable *ticket_constraints; // Key = ticket ID, value = pcmk__ticket_t int next_ordering_id; // Counter used as ID for orderings int ninstances; // Total number of resource instances int blocked_resources; // Number of blocked resources in cluster int disabled_resources; // Number of disabled resources in cluster time_t recheck_by; // Hint to controller when to reschedule xmlNode *graph; // Transition graph int synapse_count; // Number of transition graph synapses }; // Group of enum pcmk__warnings flags for warnings we want to log once extern uint32_t pcmk__warnings; /*! * \internal * \brief Log a resource-tagged message at info severity * * \param[in] rsc Tag message with this resource's ID * \param[in] fmt... printf(3)-style format and arguments */ #define pcmk__rsc_info(rsc, fmt, args...) \ crm_log_tag(LOG_INFO, ((rsc) == NULL)? "" : (rsc)->id, (fmt), ##args) /*! * \internal * \brief Log a resource-tagged message at debug severity * * \param[in] rsc Tag message with this resource's ID * \param[in] fmt... printf(3)-style format and arguments */ #define pcmk__rsc_debug(rsc, fmt, args...) \ crm_log_tag(LOG_DEBUG, ((rsc) == NULL)? "" : (rsc)->id, (fmt), ##args) /*! * \internal * \brief Log a resource-tagged message at trace severity * * \param[in] rsc Tag message with this resource's ID * \param[in] fmt... printf(3)-style format and arguments */ #define pcmk__rsc_trace(rsc, fmt, args...) \ crm_log_tag(LOG_TRACE, ((rsc) == NULL)? "" : (rsc)->id, (fmt), ##args) /*! * \internal * \brief Log an error and remember that current scheduler input has errors * * \param[in,out] scheduler Scheduler data * \param[in] fmt... printf(3)-style format and arguments */ #define pcmk__sched_err(scheduler, fmt...) do { \ pcmk__set_scheduler_flags((scheduler), \ pcmk__sched_processing_error); \ crm_err(fmt); \ } while (0) /*! * \internal * \brief Log a warning and remember that current scheduler input has warnings * * \param[in,out] scheduler Scheduler data * \param[in] fmt... printf(3)-style format and arguments */ #define pcmk__sched_warn(scheduler, fmt...) do { \ pcmk__set_scheduler_flags((scheduler), \ pcmk__sched_processing_warning); \ crm_warn(fmt); \ } while (0) /*! * \internal * \brief Set scheduler flags * * \param[in,out] scheduler Scheduler data * \param[in] flags_to_set Group of enum pcmk__scheduler_flags to set */ #define pcmk__set_scheduler_flags(scheduler, flags_to_set) do { \ (scheduler)->flags = pcmk__set_flags_as(__func__, __LINE__, \ LOG_TRACE, "Scheduler", crm_system_name, \ (scheduler)->flags, (flags_to_set), #flags_to_set); \ } while (0) /*! * \internal * \brief Clear scheduler flags * * \param[in,out] scheduler Scheduler data * \param[in] flags_to_clear Group of enum pcmk__scheduler_flags to clear */ #define pcmk__clear_scheduler_flags(scheduler, flags_to_clear) do { \ (scheduler)->flags = pcmk__clear_flags_as(__func__, __LINE__, \ LOG_TRACE, "Scheduler", crm_system_name, \ (scheduler)->flags, (flags_to_clear), #flags_to_clear); \ } while (0) void pcmk__set_scheduler_defaults(pcmk_scheduler_t *scheduler); time_t pcmk__scheduler_epoch_time(pcmk_scheduler_t *scheduler); void pcmk__update_recheck_time(time_t recheck, pcmk_scheduler_t *scheduler, const char *reason); void pcmk__add_param_check(const xmlNode *rsc_op, pcmk_resource_t *rsc, pcmk_node_t *node, enum pcmk__check_parameters); void pcmk__foreach_param_check(pcmk_scheduler_t *scheduler, void (*cb)(pcmk_resource_t*, pcmk_node_t*, const xmlNode*, enum pcmk__check_parameters)); void pcmk__free_param_checks(pcmk_scheduler_t *scheduler); #ifdef __cplusplus } #endif #endif // PCMK__CRM_COMMON_SCHEDULER_INTERNAL__H