1Set up a Cluster
2----------------
3
4Simplify Administration With a Cluster Shell
5############################################
6
7In the dark past, configuring Pacemaker required the administrator to
8read and write XML.  In true UNIX style, there were also a number of
9different commands that specialized in different aspects of querying
10and updating the cluster.
11
12In addition, the various components of the cluster stack (corosync, pacemaker,
13etc.) had to be configured separately, with different configuration tools and
14formats.
15
16All of that has been greatly simplified with the creation of higher-level tools,
17whether command-line or GUIs, that hide all the mess underneath.
18
19Command-line cluster shells take all the individual aspects required for
20managing and configuring a cluster, and pack them into one simple-to-use
21command-line tool.
22
23They even allow you to queue up several changes at once and commit
24them all at once.
25
26Two popular command-line shells are ``pcs`` and ``crmsh``. Clusters from Scratch is
27based on ``pcs`` because it comes with CentOS, but both have similar
28functionality. Choosing a shell or GUI is a matter of personal preference and
29what comes with (and perhaps is supported by) your choice of operating system.
30
31
32Install the Cluster Software
33############################
34
35Fire up a shell on both nodes and run the following to activate the High
36Availability repo.
37
38.. code-block:: none
39
40    # dnf config-manager --set-enabled ha
41
42.. IMPORTANT::
43
44    This document will show commands that need to be executed on both nodes
45    with a simple ``#`` prompt. Be sure to run them on each node individually.
46
47Now, we'll install pacemaker, pcs, and some other command-line tools that will
48make our lives easier:
49
50.. code-block:: none
51
52    # yum install -y pacemaker pcs psmisc policycoreutils-python3
53
54.. NOTE::
55
56    This document uses ``pcs`` for cluster management. Other alternatives,
57    such as ``crmsh``, are available, but their syntax
58    will differ from the examples used here.
59
60Configure the Cluster Software
61##############################
62
63.. index::
64   single: firewall
65
66Allow cluster services through firewall
67_______________________________________
68
69On each node, allow cluster-related services through the local firewall:
70
71.. code-block:: none
72
73    # firewall-cmd --permanent --add-service=high-availability
74    success
75    # firewall-cmd --reload
76    success
77
78.. NOTE ::
79
80    If you are using iptables directly, or some other firewall solution besides
81    firewalld, simply open the following ports, which can be used by various
82    clustering components: TCP ports 2224, 3121, and 21064, and UDP port 5405.
83
84    If you run into any problems during testing, you might want to disable
85    the firewall and SELinux entirely until you have everything working.
86    This may create significant security issues and should not be performed on
87    machines that will be exposed to the outside world, but may be appropriate
88    during development and testing on a protected host.
89
90    To disable security measures:
91
92    .. code-block:: none
93
94        [root@pcmk-1 ~]# setenforce 0
95        [root@pcmk-1 ~]# sed -i.bak "s/SELINUX=enforcing/SELINUX=permissive/g" /etc/selinux/config
96        [root@pcmk-1 ~]# systemctl mask firewalld.service
97        [root@pcmk-1 ~]# systemctl stop firewalld.service
98        [root@pcmk-1 ~]# iptables --flush
99
100Enable pcs Daemon
101_________________
102
103Before the cluster can be configured, the pcs daemon must be started and enabled
104to start at boot time on each node. This daemon works with the pcs command-line interface
105to manage synchronizing the corosync configuration across all nodes in the cluster.
106
107Start and enable the daemon by issuing the following commands on each node:
108
109.. code-block:: none
110
111    # systemctl start pcsd.service
112    # systemctl enable pcsd.service
113    Created symlink from /etc/systemd/system/multi-user.target.wants/pcsd.service to /usr/lib/systemd/system/pcsd.service.
114
115The installed packages will create a **hacluster** user with a disabled password.
116While this is fine for running ``pcs`` commands locally,
117the account needs a login password in order to perform such tasks as syncing
118the corosync configuration, or starting and stopping the cluster on other nodes.
119
120This tutorial will make use of such commands,
121so now we will set a password for the **hacluster** user, using the same password
122on both nodes:
123
124.. code-block:: none
125
126    # passwd hacluster
127    Changing password for user hacluster.
128    New password:
129    Retype new password:
130    passwd: all authentication tokens updated successfully.
131
132.. NOTE::
133
134    Alternatively, to script this process or set the password on a
135    different machine from the one you're logged into, you can use
136    the ``--stdin`` option for ``passwd``:
137
138    .. code-block:: none
139
140        [root@pcmk-1 ~]# ssh pcmk-2 -- 'echo mysupersecretpassword | passwd --stdin hacluster'
141
142Configure Corosync
143__________________
144
145On either node, use ``pcs host auth`` to authenticate as the **hacluster** user:
146
147.. code-block:: none
148
149    [root@pcmk-1 ~]# pcs host auth pcmk-1 pcmk-2
150    Username: hacluster
151    Password:
152    pcmk-2: Authorized
153    pcmk-1: Authorized
154
155Next, use ``pcs cluster setup`` on the same node to generate and synchronize the
156corosync configuration:
157
158.. code-block:: none
159
160    [root@pcmk-1 ~]# pcs cluster setup mycluster pcmk-1 pcmk-2
161    No addresses specified for host 'pcmk-1', using 'pcmk-1'
162    No addresses specified for host 'pcmk-2', using 'pcmk-2'
163    Destroying cluster on hosts: 'pcmk-1', 'pcmk-2'...
164    pcmk-2: Successfully destroyed cluster
165    pcmk-1: Successfully destroyed cluster
166    Requesting remove 'pcsd settings' from 'pcmk-1', 'pcmk-2'
167    pcmk-1: successful removal of the file 'pcsd settings'
168    pcmk-2: successful removal of the file 'pcsd settings'
169    Sending 'corosync authkey', 'pacemaker authkey' to 'pcmk-1', 'pcmk-2'
170    pcmk-1: successful distribution of the file 'corosync authkey'
171    pcmk-1: successful distribution of the file 'pacemaker authkey'
172    pcmk-2: successful distribution of the file 'corosync authkey'
173    pcmk-2: successful distribution of the file 'pacemaker authkey'
174    Sending 'corosync.conf' to 'pcmk-1', 'pcmk-2'
175    pcmk-1: successful distribution of the file 'corosync.conf'
176    pcmk-2: successful distribution of the file 'corosync.conf'
177    Cluster has been successfully set up.
178
179If you received an authorization error for either of those commands, make
180sure you configured the **hacluster** user account on each node
181with the same password.
182
183The final corosync.conf configuration on each node should look
184something like the sample in :ref:`sample-corosync-configuration`.
185
186Explore pcs
187###########
188
189Start by taking some time to familiarize yourself with what ``pcs`` can do.
190
191.. code-block:: none
192
193    [root@pcmk-1 ~]# pcs
194
195    Usage: pcs [-f file] [-h] [commands]...
196    Control and configure pacemaker and corosync.
197
198    Options:
199        -h, --help         Display usage and exit.
200        -f file            Perform actions on file instead of active CIB.
201                           Commands supporting the option use the initial state of
202                           the specified file as their input and then overwrite the
203                           file with the state reflecting the requested
204                           operation(s).
205                           A few commands only use the specified file in read-only
206                           mode since their effect is not a CIB modification.
207        --debug            Print all network traffic and external commands run.
208        --version          Print pcs version information. List pcs capabilities if
209                           --full is specified.
210        --request-timeout  Timeout for each outgoing request to another node in
211                           seconds. Default is 60s.
212        --force            Override checks and errors, the exact behavior depends on
213                           the command. WARNING: Using the --force option is
214                           strongly discouraged unless you know what you are doing.
215
216    Commands:
217        cluster     Configure cluster options and nodes.
218        resource    Manage cluster resources.
219        stonith     Manage fence devices.
220        constraint  Manage resource constraints.
221        property    Manage pacemaker properties.
222        acl         Manage pacemaker access control lists.
223        qdevice     Manage quorum device provider on the local host.
224        quorum      Manage cluster quorum settings.
225        booth       Manage booth (cluster ticket manager).
226        status      View cluster status.
227        config      View and manage cluster configuration.
228        pcsd        Manage pcs daemon.
229        host        Manage hosts known to pcs/pcsd.
230        node        Manage cluster nodes.
231        alert       Manage pacemaker alerts.
232        client      Manage pcsd client configuration.
233        dr          Manage disaster recovery configuration.
234        tag         Manage pacemaker tags.
235
236
237As you can see, the different aspects of cluster management are separated
238into categories. To discover the functionality available in each of these
239categories, one can issue the command ``pcs <CATEGORY> help``.  Below is an
240example of all the options available under the status category.
241
242.. code-block:: none
243
244    [root@pcmk-1 ~]# pcs status help
245
246    Usage: pcs status [commands]...
247    View current cluster and resource status
248    Commands:
249        [status] [--full] [--hide-inactive]
250            View all information about the cluster and resources (--full provides
251            more details, --hide-inactive hides inactive resources).
252
253        resources [--hide-inactive]
254            Show status of all currently configured resources. If --hide-inactive
255            is specified, only show active resources.
256
257        cluster
258            View current cluster status.
259
260        corosync
261            View current membership information as seen by corosync.
262
263        quorum
264            View current quorum status.
265
266        qdevice <device model> [--full] [<cluster name>]
267            Show runtime status of specified model of quorum device provider.  Using
268            --full will give more detailed output.  If <cluster name> is specified,
269            only information about the specified cluster will be displayed.
270
271        booth
272            Print current status of booth on the local node.
273
274        nodes [corosync | both | config]
275            View current status of nodes from pacemaker. If 'corosync' is
276            specified, view current status of nodes from corosync instead. If
277            'both' is specified, view current status of nodes from both corosync &
278            pacemaker. If 'config' is specified, print nodes from corosync &
279            pacemaker configuration.
280
281        pcsd [<node>]...
282            Show current status of pcsd on nodes specified, or on all nodes
283            configured in the local cluster if no nodes are specified.
284
285        xml
286            View xml version of status (output from crm_mon -r -1 -X).
287
288Additionally, if you are interested in the version and supported cluster stack(s)
289available with your Pacemaker installation, run:
290
291.. code-block:: none
292
293    [root@pcmk-1 ~]# pacemakerd --features
294    Pacemaker 2.0.5-4.el8 (Build: ba59be7122)
295    Supporting v3.6.1:  generated-manpages agent-manpages ncurses libqb-logging libqb-ipc systemd nagios  corosync-native atomic-attrd acls cibsecrets
296