diff --git a/doc/sphinx/Pacemaker_Administration/configuring.rst b/doc/sphinx/Pacemaker_Administration/configuring.rst
index e4d70c4828..8979c4fa3b 100644
--- a/doc/sphinx/Pacemaker_Administration/configuring.rst
+++ b/doc/sphinx/Pacemaker_Administration/configuring.rst
@@ -1,226 +1,228 @@
.. index::
single: configuration
single: CIB
Configuring Pacemaker
---------------------
Pacemaker's configuration, the CIB, is stored in XML format. Cluster
administrators have multiple options for modifying the configuration either via
the XML, or at a more abstract (and easier for humans to understand) level.
Pacemaker reacts to configuration changes as soon as they are saved.
Pacemaker's command-line tools and most higher-level tools provide the ability
to batch changes together and commit them at once, rather than make a series of
small changes, which could cause avoid unnecessary actions as Pacemaker
responds to each change individually.
Pacemaker tracks revisions to the configuration and will reject any update
older than the current revision. Thus, it is a good idea to serialize all
changes to the configuration. Avoid attempting simultaneous changes, whether on
the same node or different nodes, and whether manually or using some automated
configuration tool.
.. note::
It is not necessary to update the configuration on all cluster nodes.
Pacemaker immediately synchronizes changes to all active members of the
cluster. To reduce bandwidth, the cluster only broadcasts the incremental
updates that result from your changes and uses checksums to ensure that each
copy is consistent.
Configuration Using Higher-level Tools
######################################
Most users will benefit from using higher-level tools provided by projects
-separate from Pacemaker. Some of the most commonly used include the crm shell,
-hawk, and pcs. [#]_
+separate from Pacemaker. Popular ones include the crm shell and pcs. [#]_
See those projects' documentation for details on how to configure Pacemaker
using them.
Configuration Using Pacemaker's Command-Line Tools
##################################################
Pacemaker provides lower-level, command-line tools to manage the cluster. Most
configuration tasks can be performed with these tools, without needing any XML
knowledge.
To enable STONITH for example, one could run:
.. code-block:: none
# crm_attribute --name stonith-enabled --update 1
Or, to check whether **node1** is allowed to run resources, there is:
.. code-block:: none
# crm_standby --query --node node1
Or, to change the failure threshold of **my-test-rsc**, one can use:
.. code-block:: none
# crm_resource -r my-test-rsc --set-parameter migration-threshold --parameter-value 3 --meta
Examples of using these tools for specific cases will be given throughout this
document where appropriate. See the man pages for further details.
See :ref:`cibadmin` for how to edit the CIB using XML.
See :ref:`crm_shadow` for a way to make a series of changes, then commit them
all at once to the live cluster.
.. index::
single: configuration; CIB properties
single: CIB; properties
single: CIB property
Working with CIB Properties
___________________________
Although these fields can be written to by the user, in
most cases the cluster will overwrite any values specified by the
user with the "correct" ones.
To change the ones that can be specified by the user, for example
``admin_epoch``, one should use:
.. code-block:: none
# cibadmin --modify --xml-text ''
A complete set of CIB properties will look something like this:
.. topic:: XML attributes set for a cib element
.. code-block:: xml
.. index::
single: configuration; cluster options
Querying and Setting Cluster Options
____________________________________
Cluster options can be queried and modified using the ``crm_attribute`` tool.
To get the current value of ``cluster-delay``, you can run:
.. code-block:: none
# crm_attribute --query --name cluster-delay
which is more simply written as
.. code-block:: none
# crm_attribute -G -n cluster-delay
If a value is found, you'll see a result like this:
.. code-block:: none
# crm_attribute -G -n cluster-delay
scope=crm_config name=cluster-delay value=60s
If no value is found, the tool will display an error:
.. code-block:: none
# crm_attribute -G -n clusta-deway
scope=crm_config name=clusta-deway value=(null)
Error performing operation: No such device or address
To use a different value (for example, 30 seconds), simply run:
.. code-block:: none
# crm_attribute --name cluster-delay --update 30s
To go back to the cluster's default value, you can delete the value, for example:
.. code-block:: none
# crm_attribute --name cluster-delay --delete
Deleted crm_config option: id=cib-bootstrap-options-cluster-delay name=cluster-delay
When Options are Listed More Than Once
______________________________________
If you ever see something like the following, it means that the option you're
modifying is present more than once.
.. topic:: Deleting an option that is listed twice
.. code-block:: none
# crm_attribute --name batch-limit --delete
Please choose from one of the matches below and supply the 'id' with --id
Multiple attributes match name=batch-limit in crm_config:
Value: 50 (set=cib-bootstrap-options, id=cib-bootstrap-options-batch-limit)
Value: 100 (set=custom, id=custom-batch-limit)
In such cases, follow the on-screen instructions to perform the requested
action. To determine which value is currently being used by the cluster, refer
to the "Rules" chapter of *Pacemaker Explained*.
.. index::
single: configuration; remote
.. _remote_connection:
Connecting from a Remote Machine
################################
-Provided Pacemaker is installed on a machine, it is possible to connect to the
-cluster even if the machine itself is not in the same cluster. To do this, one
-simply sets the following environment variables and runs the same commands as
-when working on a cluster node:
+It is possible to run configuration commands from a machine that is not part of
+the cluster.
+
+For security reasons, this capability is disabled by default. If you wish to
+allow remote access, set the ``remote-tls-port`` (encrypted) or
+``remote-clear-port`` (unencrypted) CIB properties (attributes of the ``cib``
+element). Encrypted communication is keyless, which makes it subject to
+man-in-the-middle attacks, so either option should be used only on protected
+networks.
+
+The administrator's machine simply needs Pacemaker installed. To connect to the
+cluster, set the following environment variables:
* :ref:`CIB_port ` (required)
* :ref:`CIB_server `
* :ref:`CIB_user `
* :ref:`CIB_passwd `
* :ref:`CIB_encrypted `
-So, if **c001n01** is an active cluster node and is listening on port 1234
-for connections, and **someuser** is a member of the |CRM_DAEMON_GROUP| group,
-then the following would prompt for **someuser**'s password and return
-the cluster's current configuration:
+Only the Pacemaker daemon user (|CRM_DAEMON_USER|) may be used as ``CIB_user``.
+
+As an example, if **node1** is a cluster node, and the CIB is configured with
+``remote-tls-port`` set to 1234, the administrator could read the current
+cluster configuration using the following commands, and would be prompted for
+the daemon user's password:
.. code-block:: none
- # export CIB_port=1234; export CIB_server=c001n01; export CIB_user=someuser;
+ # export CIB_server=node1; export CIB_port=1234; export CIB_encrypted=true
# cibadmin -Q
-For security reasons, the cluster does not listen for remote connections by
-default. If you wish to allow remote access, you need to set the
-``remote-tls-port`` (encrypted) or ``remote-clear-port`` (unencrypted) CIB
-properties (i.e., those kept in the ``cib`` tag, like ``num_updates`` and
-``epoch``). Encrypted communication is keyless, which makes it subject to
-man-in-the-middle attacks, and thus either option should be used only on
-protected networks.
-
-.. important::
-
- The Pacemaker version on the administration host must be the same or greater
- than the version(s) on the cluster nodes. Otherwise, it may not have the
- schema files necessary to validate the CIB.
+.. note::
+ Pacemaker must have been built with PAM support in order for Pacemaker to
+ authenticate the user credentials. In a build without PAM support, all
+ remote connections are accepted without authentication. You can check for
+ PAM support *(since 2.1.9)* by running ``pacemakerd --features``. If the
+ output contains **pam**, authentication is supported.
.. rubric:: Footnotes
.. [#] For a list, see "Configuration Tools" at
https://clusterlabs.org/components.html