:compat-mode: legacy

= 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. footnote:[For a list, see "Configuration Tools" at

https://clusterlabs.org/components.html]

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:

----

# crm_attribute --name stonith-enabled --update 1

----

Or, to check whether *node1* is allowed to run resources, there is:

----

# crm_standby --query --node node1

----

Or, to change the failure threshold of *my-test-rsc*, one can use:

----

# 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 <<s-cibadmin>> for how to edit the CIB using XML.

See <<s-crm_shadow>> for a way to make a series of changes, then commit them

all at once to the live cluster.

== 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:

----

# cibadmin --modify --xml-text '<cib admin_epoch="42"/>'

----

A complete set of CIB properties will look something like this:

.XML attributes set for a cib element

======

[source,XML]

-------

   admin_epoch="42" epoch="116" num_updates="1"

   cib-last-written="Mon Jan 12 15:46:39 2015" update-origin="rhel7-1"

   update-client="crm_attribute" have-quorum="1" dc-uuid="1">

-------

======

== Querying and Setting Cluster Options ==

indexterm:[Querying,Cluster Option]

indexterm:[Setting,Cluster Option]

indexterm:[Cluster,Querying Options]

indexterm:[Cluster,Setting Options]

Cluster options can be queried and modified using the `crm_attribute` tool. To

get the current value of +cluster-delay+, you can run:

----

# crm_attribute --query --name cluster-delay

----

which is more simply written as

----

# crm_attribute -G -n cluster-delay

----

If a value is found, you'll see a result like this:

----

# 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:

----

# 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:

----

# crm_attribute --name cluster-delay --update 30s

----

To go back to the cluster's default value, you can delete the value, for example:

----

# 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.

.Deleting an option that is listed twice

=======

------

# crm_attribute --name batch-limit --delete

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)

Please choose from one of the matches above and supply the 'id' with --id

-------

=======

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'.

[[s-remote-connection]]

== Connecting from a Remote Machine ==

indexterm:[Cluster,Remote connection]

indexterm:[Cluster,Remote administration]

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.

.Environment Variables Used to Connect to Remote Instances of the CIB

[width="95%",cols="1m,1,<3",options="header",align="center"]

|=========================================================

|Environment Variable

|Default

|Description

|CIB_user

|$USER

|The user to connect as. Needs to be part of the +haclient+ group on

 the target host.

 indexterm:[Environment Variable,CIB_user]

|CIB_passwd

|

|The user's password. Read from the command line if unset.

 indexterm:[Environment Variable,CIB_passwd]

|CIB_server

|localhost

|The host to contact

 indexterm:[Environment Variable,CIB_server]

|CIB_port

|

|The port on which to contact the server; required.

 indexterm:[Environment Variable,CIB_port]

|CIB_encrypted

|TRUE

|Whether to encrypt network traffic

 indexterm:[Environment Variable,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 *haclient* group,

then the following would prompt for *someuser*'s password and return

the cluster's current configuration:

----

# 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+).

.Extra top-level CIB properties for remote access

[width="95%",cols="1m,1,<3",options="header",align="center"]

|=========================================================

|Field

|Default

|Description

|remote-tls-port

|_none_

|Listen for encrypted remote connections on this port.

 indexterm:[remote-tls-port,Remote Connection Option]

 indexterm:[Remote Connection,Option,remote-tls-port]

|remote-clear-port

|_none_

|Listen for plaintext remote connections on this port.

 indexterm:[remote-clear-port,Remote Connection Option]

 indexterm:[Remote Connection,Option,remote-clear-port]

|=========================================================

[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.

====