diff --git a/doc/sphinx/Pacemaker_Administration/configuring.rst b/doc/sphinx/Pacemaker_Administration/configuring.rst
index 8cdfb6eabe..295c96a89a 100644
--- a/doc/sphinx/Pacemaker_Administration/configuring.rst
+++ b/doc/sphinx/Pacemaker_Administration/configuring.rst
@@ -1,265 +1,265 @@
.. index::
single: configuration
single: CIB
Configuring Pacemaker
---------------------
Pacemaker's configuration, the CIB, is stored in XML format. Cluster
administrators have multiple options for modifying the configuration either via
the XML, or at a more abstract (and easier for humans to understand) level.
Pacemaker reacts to configuration changes as soon as they are saved.
Pacemaker's command-line tools and most higher-level tools provide the ability
to batch changes together and commit them at once, rather than make a series of
small changes, which could cause avoid unnecessary actions as Pacemaker
responds to each change individually.
Pacemaker tracks revisions to the configuration and will reject any update
older than the current revision. Thus, it is a good idea to serialize all
changes to the configuration. Avoid attempting simultaneous changes, whether on
the same node or different nodes, and whether manually or using some automated
configuration tool.
.. note::
It is not necessary to update the configuration on all cluster nodes.
Pacemaker immediately synchronizes changes to all active members of the
cluster. To reduce bandwidth, the cluster only broadcasts the incremental
updates that result from your changes and uses checksums to ensure that each
copy is consistent.
Configuration Using Higher-level Tools
######################################
Most users will benefit from using higher-level tools provided by projects
separate from Pacemaker. Some of the most commonly used include the crm shell,
hawk, and pcs. [#]_
See those projects' documentation for details on how to configure Pacemaker
using them.
Configuration Using Pacemaker's Command-Line Tools
##################################################
Pacemaker provides lower-level, command-line tools to manage the cluster. Most
configuration tasks can be performed with these tools, without needing any XML
knowledge.
To enable STONITH for example, one could run:
.. code-block:: none
# crm_attribute --name stonith-enabled --update 1
Or, to check whether **node1** is allowed to run resources, there is:
.. code-block:: none
# crm_standby --query --node node1
Or, to change the failure threshold of **my-test-rsc**, one can use:
.. code-block:: none
# crm_resource -r my-test-rsc --set-parameter migration-threshold --parameter-value 3 --meta
Examples of using these tools for specific cases will be given throughout this
document where appropriate. See the man pages for further details.
See :ref:`cibadmin` for how to edit the CIB using XML.
See :ref:`crm_shadow` for a way to make a series of changes, then commit them
all at once to the live cluster.
.. index::
single: configuration; CIB properties
single: CIB; properties
single: CIB property
Working with CIB Properties
___________________________
Although these fields can be written to by the user, in
most cases the cluster will overwrite any values specified by the
user with the "correct" ones.
To change the ones that can be specified by the user, for example
``admin_epoch``, one should use:
.. code-block:: none
# cibadmin --modify --xml-text ''
A complete set of CIB properties will look something like this:
.. topic:: XML attributes set for a cib element
.. code-block:: xml
.. index::
single: configuration; cluster options
Querying and Setting Cluster Options
____________________________________
Cluster options can be queried and modified using the ``crm_attribute`` tool.
To get the current value of ``cluster-delay``, you can run:
.. code-block:: none
# crm_attribute --query --name cluster-delay
which is more simply written as
.. code-block:: none
# crm_attribute -G -n cluster-delay
If a value is found, you'll see a result like this:
.. code-block:: none
# crm_attribute -G -n cluster-delay
scope=crm_config name=cluster-delay value=60s
If no value is found, the tool will display an error:
.. code-block:: none
# crm_attribute -G -n clusta-deway
scope=crm_config name=clusta-deway value=(null)
Error performing operation: No such device or address
To use a different value (for example, 30 seconds), simply run:
.. code-block:: none
# crm_attribute --name cluster-delay --update 30s
To go back to the cluster's default value, you can delete the value, for example:
.. code-block:: none
# crm_attribute --name cluster-delay --delete
Deleted crm_config option: id=cib-bootstrap-options-cluster-delay name=cluster-delay
When Options are Listed More Than Once
______________________________________
If you ever see something like the following, it means that the option you're
modifying is present more than once.
.. topic:: Deleting an option that is listed twice
.. code-block:: none
# crm_attribute --name batch-limit --delete
Please choose from one of the matches below and supply the 'id' with --id
Multiple attributes match name=batch-limit in crm_config:
Value: 50 (set=cib-bootstrap-options, id=cib-bootstrap-options-batch-limit)
Value: 100 (set=custom, id=custom-batch-limit)
In such cases, follow the on-screen instructions to perform the requested
action. To determine which value is currently being used by the cluster, refer
to the "Rules" chapter of *Pacemaker Explained*.
.. index::
single: configuration; remote
.. _remote_connection:
Connecting from a Remote Machine
################################
Provided Pacemaker is installed on a machine, it is possible to connect to the
cluster even if the machine itself is not in the same cluster. To do this, one
simply sets up a number of environment variables and runs the same commands as
when working on a cluster node.
.. list-table:: **Environment Variables Used to Connect to Remote Instances of the CIB**
:class: longtable
:widths: 2 2 5
:header-rows: 1
* - Environment Variable
- Default
- Description
* - .. index::
single: CIB_user
single: environment variable; CIB_user
CIB_user
- |CRM_DAEMON_USER_RAW|
- - The user to connect as. Needs to be part of the ``haclient`` group on
- the target host.
+ - The user to connect as. Needs to be part of the |CRM_DAEMON_GROUP| group
+ on the target host.
* - .. index::
single: CIB_passwd
single: environment variable; CIB_passwd
CIB_passwd
-
- The user's password. Read from the command line if unset.
* - .. index::
single: CIB_server
single: environment variable; CIB_server
CIB_server
- localhost
- The host to contact
* - .. index::
single: CIB_port
single: environment variable; CIB_port
CIB_port
-
- The port on which to contact the server; required
* - .. index::
single: CIB_encrypted
single: environment variable; CIB_encrypted
CIB_encrypted
- true
- Whether to encrypt network traffic
So, if **c001n01** is an active cluster node and is listening on port 1234
-for connections, and **someuser** is a member of the **haclient** group,
+for connections, and **someuser** is a member of the |CRM_DAEMON_GROUP| group,
then the following would prompt for **someuser**'s password and return
the cluster's current configuration:
.. code-block:: none
# export CIB_port=1234; export CIB_server=c001n01; export CIB_user=someuser;
# cibadmin -Q
For security reasons, the cluster does not listen for remote connections by
default. If you wish to allow remote access, you need to set the
``remote-tls-port`` (encrypted) or ``remote-clear-port`` (unencrypted) CIB
properties (i.e., those kept in the ``cib`` tag, like ``num_updates`` and
``epoch``). Encrypted communication is keyless, which makes it subject to
man-in-the-middle attacks, and thus either option should be used only on
protected networks.
.. important::
The Pacemaker version on the administration host must be the same or greater
than the version(s) on the cluster nodes. Otherwise, it may not have the
schema files necessary to validate the CIB.
.. rubric:: Footnotes
.. [#] For a list, see "Configuration Tools" at
https://clusterlabs.org/components.html
diff --git a/doc/sphinx/Pacemaker_Explained/acls.rst b/doc/sphinx/Pacemaker_Explained/acls.rst
index 52473c50a4..c3de39d0de 100644
--- a/doc/sphinx/Pacemaker_Explained/acls.rst
+++ b/doc/sphinx/Pacemaker_Explained/acls.rst
@@ -1,460 +1,460 @@
.. index::
single: Access Control List (ACL)
.. _acl:
Access Control Lists (ACLs)
---------------------------
-By default, the ``root`` user or any user in the ``haclient`` group can modify
-Pacemaker's CIB without restriction. Pacemaker offers *access control lists
-(ACLs)* to provide more fine-grained authorization.
+By default, the ``root`` user or any user in the |CRM_DAEMON_GROUP| group can
+modify Pacemaker's CIB without restriction. Pacemaker offers *access control
+lists (ACLs)* to provide more fine-grained authorization.
.. important::
Being able to modify the CIB's resource section allows a user to run any
executable file as root, by configuring it as an LSB resource with a full
path.
ACL Prerequisites
#################
In order to use ACLs:
* The ``enable-acl`` :ref:`cluster option ` must be set to
true.
-* Desired users must have user accounts in the ``haclient`` group on all
+* Desired users must have user accounts in the |CRM_DAEMON_GROUP| group on all
cluster nodes in the cluster.
* If your CIB was created before Pacemaker 1.1.12, it might need to be updated
to the current schema (using ``cibadmin --upgrade`` or a higher-level tool
equivalent) in order to use the syntax documented here.
* Prior to the 2.1.0 release, the Pacemaker software had to have been built
with ACL support. If you are using an older release, your installation
supports ACLs only if the output of the command ``pacemakerd --features``
contains ``acls``. In newer versions, ACLs are always enabled.
.. index::
single: Access Control List (ACL); acls
pair: acls; XML element
ACL Configuration
#################
ACLs are specified within an ``acls`` element of the CIB. The ``acls`` element
may contain any number of ``acl_role``, ``acl_target``, and ``acl_group``
elements.
.. index::
single: Access Control List (ACL); acl_role
pair: acl_role; XML element
ACL Roles
#########
An ACL *role* is a collection of permissions allowing or denying access to
particular portions of the CIB. A role is configured with an ``acl_role``
element in the CIB ``acls`` section.
.. table:: **Properties of an acl_role element**
:widths: 1 3
+------------------+-----------------------------------------------------------+
| Attribute | Description |
+==================+===========================================================+
| id | .. index:: |
| | single: acl_role; id (attribute) |
| | single: id; acl_role attribute |
| | single: attribute; id (acl_role) |
| | |
| | A unique name for the role *(required)* |
+------------------+-----------------------------------------------------------+
| description | .. index:: |
| | single: acl_role; description (attribute) |
| | single: description; acl_role attribute |
| | single: attribute; description (acl_role) |
| | |
| | Arbitrary text (not used by Pacemaker) |
+------------------+-----------------------------------------------------------+
An ``acl_role`` element may contain any number of ``acl_permission`` elements.
.. index::
single: Access Control List (ACL); acl_permission
pair: acl_permission; XML element
.. table:: **Properties of an acl_permission element**
:widths: 1 3
+------------------+-----------------------------------------------------------+
| Attribute | Description |
+==================+===========================================================+
| id | .. index:: |
| | single: acl_permission; id (attribute) |
| | single: id; acl_permission attribute |
| | single: attribute; id (acl_permission) |
| | |
| | A unique name for the permission *(required)* |
+------------------+-----------------------------------------------------------+
| description | .. index:: |
| | single: acl_permission; description (attribute) |
| | single: description; acl_permission attribute |
| | single: attribute; description (acl_permission) |
| | |
| | Arbitrary text (not used by Pacemaker) |
+------------------+-----------------------------------------------------------+
| kind | .. index:: |
| | single: acl_permission; kind (attribute) |
| | single: kind; acl_permission attribute |
| | single: attribute; kind (acl_permission) |
| | |
| | The access being granted. Allowed values are ``read``, |
| | ``write``, and ``deny``. A value of ``write`` grants both |
| | read and write access. |
+------------------+-----------------------------------------------------------+
| object-type | .. index:: |
| | single: acl_permission; object-type (attribute) |
| | single: object-type; acl_permission attribute |
| | single: attribute; object-type (acl_permission) |
| | |
| | The name of an XML element in the CIB to which the |
| | permission applies. (Exactly one of ``object-type``, |
| | ``xpath``, and ``reference`` must be specified for a |
| | permission.) |
+------------------+-----------------------------------------------------------+
| attribute | .. index:: |
| | single: acl_permission; attribute (attribute) |
| | single: attribute; acl_permission attribute |
| | single: attribute; attribute (acl_permission) |
| | |
| | If specified, the permission applies only to |
| | ``object-type`` elements that have this attribute set (to |
| | any value). If not specified, the permission applies to |
| | all ``object-type`` elements. May only be used with |
| | ``object-type``. |
+------------------+-----------------------------------------------------------+
| reference | .. index:: |
| | single: acl_permission; reference (attribute) |
| | single: reference; acl_permission attribute |
| | single: attribute; reference (acl_permission) |
| | |
| | The ID of an XML element in the CIB to which the |
| | permission applies. (Exactly one of ``object-type``, |
| | ``xpath``, and ``reference`` must be specified for a |
| | permission.) |
+------------------+-----------------------------------------------------------+
| xpath | .. index:: |
| | single: acl_permission; xpath (attribute) |
| | single: xpath; acl_permission attribute |
| | single: attribute; xpath (acl_permission) |
| | |
| | An `XPath `_ |
| | specification selecting an XML element in the CIB to |
| | which the permission applies. Attributes may be specified |
| | in the XPath to select particular elements, but the |
| | permissions apply to the entire element. (Exactly one of |
| | ``object-type``, ``xpath``, and ``reference`` must be |
| | specified for a permission.) |
+------------------+-----------------------------------------------------------+
.. important::
* Permissions are applied to the selected XML element's entire XML subtree
(all elements enclosed within it).
* Write permission grants the ability to create, modify, or remove the
element and its subtree, and also the ability to create any "scaffolding"
elements (enclosing elements that do not have attributes other than an
ID).
* Permissions for more specific matches (more deeply nested elements) take
precedence over more general ones.
* If multiple permissions are configured for the same match (for example, in
different roles applied to the same user), any ``deny`` permission takes
precedence, then ``write``, then lastly ``read``.
ACL Targets and Groups
######################
ACL targets correspond to user accounts on the system.
.. index::
single: Access Control List (ACL); acl_target
pair: acl_target; XML element
.. table:: **Properties of an acl_target element**
:widths: 1 3
+------------------+-----------------------------------------------------------+
| Attribute | Description |
+==================+===========================================================+
| id | .. index:: |
| | single: acl_target; id (attribute) |
| | single: id; acl_target attribute |
| | single: attribute; id (acl_target) |
| | |
| | A unique identifier for the target (if ``name`` is not |
| | specified, this must be the name of the user account) |
| | *(required)* |
+------------------+-----------------------------------------------------------+
| name | .. index:: |
| | single: acl_target; name (attribute) |
| | single: name; acl_target attribute |
| | single: attribute; name (acl_target) |
| | |
| | If specified, the user account name (this allows you to |
| | specify a user name that is already used as the ``id`` |
| | for some other configuration element) *(since 2.1.5)* |
+------------------+-----------------------------------------------------------+
ACL groups correspond to groups on the system. Any role configured for these
groups apply to all users in that group *(since 2.1.5)*.
.. index::
single: Access Control List (ACL); acl_group
pair: acl_group; XML element
.. table:: **Properties of an acl_group element**
:widths: 1 3
+------------------+-----------------------------------------------------------+
| Attribute | Description |
+==================+===========================================================+
| id | .. index:: |
| | single: acl_group; id (attribute) |
| | single: id; acl_group attribute |
| | single: attribute; id (acl_group) |
| | |
| | A unique identifier for the group (if ``name`` is not |
| | specified, this must be the group name) *(required)* |
+------------------+-----------------------------------------------------------+
| name | .. index:: |
| | single: acl_group; name (attribute) |
| | single: name; acl_group attribute |
| | single: attribute; name (acl_group) |
| | |
| | If specified, the group name (this allows you to specify |
| | a group name that is already used as the ``id`` for some |
| | other configuration element) |
+------------------+-----------------------------------------------------------+
Each ``acl_target`` and ``acl_group`` element may contain any number of ``role``
elements.
.. note::
If the system users and groups are defined by some network service (such as
LDAP), the cluster itself will be unaffected by outages in the service, but
affected users and groups will not be able to make changes to the CIB.
.. index::
single: Access Control List (ACL); role
pair: role; XML element
.. table:: **Properties of a role element**
:widths: 1 3
+------------------+-----------------------------------------------------------+
| Attribute | Description |
+==================+===========================================================+
| id | .. index:: |
| | single: role; id (attribute) |
| | single: id; role attribute |
| | single: attribute; id (role) |
| | |
| | The ``id`` of an ``acl_role`` element that specifies |
| | permissions granted to the enclosing target or group. |
+------------------+-----------------------------------------------------------+
.. important::
The ``root`` and |CRM_DAEMON_USER| user accounts always have full access to
the CIB, regardless of ACLs. For all other user accounts, when ``enable-acl``
is true, permission to all parts of the CIB is denied by default (permissions
must be explicitly granted).
ACL Examples
############
.. code-block:: xml
In the above example, the user ``alice`` has the minimal permissions necessary
to run basic Pacemaker CLI tools, including using ``crm_mon`` to view the
cluster status, without being able to modify anything. The user ``bob`` can
view the entire configuration and status of the cluster, but not make any
changes. The user ``carol`` can read everything, and change selected cluster
properties as well as resource roles and location constraints. Finally,
``dave`` has full read and write access to the entire CIB.
Looking at the ``minimal`` role in more depth, it is designed to allow read
access to the ``cib`` tag itself, while denying access to particular portions
of its subtree (which is the entire CIB).
This is because the DC node is indicated in the ``cib`` tag, so ``crm_mon``
will not be able to report the DC otherwise. However, this does change the
security model to allow by default, since any portions of the CIB not
explicitly denied will be readable. The ``cib`` read access could be removed
and replaced with read access to just the ``crm_config`` and ``status``
sections, for a safer approach at the cost of not seeing the DC in status
output.
For a simpler configuration, the ``minimal`` role allows read access to the
entire ``crm_config`` section, which contains cluster properties. It would be
possible to allow read access to specific properties instead (such as
``stonith-enabled``, ``dc-uuid``, ``have-quorum``, and ``cluster-name``) to
restrict access further while still allowing status output, but cluster
properties are unlikely to be considered sensitive.
ACL Limitations
###############
Actions performed via IPC rather than the CIB
_____________________________________________
ACLs apply *only* to the CIB.
That means ACLs apply to command-line tools that operate by reading or writing
the CIB, such as ``crm_attribute`` when managing permanent node attributes,
``crm_mon``, and ``cibadmin``.
However, command-line tools that communicate directly with Pacemaker daemons
-via IPC are not affected by ACLs. For example, users in the ``haclient`` group
-may still do the following, regardless of ACLs:
+via IPC are not affected by ACLs. For example, users in the |CRM_DAEMON_GROUP|
+group may still do the following, regardless of ACLs:
* Query transient node attribute values using ``crm_attribute`` and
``attrd_updater``.
* Query basic node information using ``crm_node``.
* Erase resource operation history using ``crm_resource``.
* Query fencing configuration information, and execute fencing against nodes,
using ``stonith_admin``.
ACLs and Pacemaker Remote
_________________________
ACLs apply to commands run on Pacemaker Remote nodes using the Pacemaker Remote
node's name as the ACL user name.
The idea is that Pacemaker Remote nodes (especially virtual machines and
containers) are likely to be purpose-built and have different user accounts
from full cluster nodes.