diff --git a/doc/Pacemaker_Remote/en-US/Ch-Alternatives.txt b/doc/Pacemaker_Remote/en-US/Ch-Alternatives.txt
new file mode 100644
index 0000000000..d2fd9f42fd
--- /dev/null
+++ b/doc/Pacemaker_Remote/en-US/Ch-Alternatives.txt
@@ -0,0 +1,77 @@
+= Alternative Configurations =
+
+These alternative configurations may be appropriate in limited cases, such as a
+test cluster, but are not the best method in most situations. They are
+presented here for completeness and as an example of pacemaker's flexibility
+to suit your needs.
+
+== Virtual Machines as Cluster Nodes ==
+
+The preferred use of virtual machines in a pacemaker cluster is as a
+cluster resource, whether opaque or as a guest node. However, it is
+possible to run the full cluster stack on a virtual node instead.
+
+This is commonly used to set up test environments; a single physical host
+(that does not participate in the cluster) runs two or more virtual machines,
+all running the full cluster stack. This can be used to simulate a
+larger cluster for testing purposes.
+
+In a production environment, fencing becomes more complicated, especially
+if the underlying hosts run any services besides the clustered VMs.
+If the VMs are not guaranteed a minimum amount of host resources,
+CPU and I/O contention can cause timing issues for cluster components.
+
+Another situation where this approach is sometimes used is when
+the cluster owner leases the VMs from a provider and does not have
+direct access to the underlying host. The main concerns in this case
+are proper fencing (usually via a custom resource agent that communicates
+with the provider's APIs) and maintaining a static IP address between reboots,
+as well as resource contention issues.
+
+== Virtual Machines as Remote Nodes ==
+
+Virtual machines may be configured following the process for remote nodes
+rather than guest nodes (i.e., using an *ocf:pacemaker:remote* resource
+rather than letting the cluster manage the VM directly).
+
+This is mainly useful in testing, to use a single physical host to simulate a
+larger cluster involving remote nodes. Pacemaker's Cluster Test Suite (CTS)
+uses this approach to test remote node functionality.
+
+== Containers as Guest Nodes ==
+
+Containers,footnote:[https://en.wikipedia.org/wiki/Operating-system-level_virtualization]
+and in particular Linux containers (LXC) and Docker, have become a popular
+method of isolating services in a resource-efficient manner.
+
+The preferred means of integrating containers into Pacemaker is as a
+cluster resource, whether opaque or using Pacemaker's built-in
+resource isolation support.footnote:[Documentation for this support is planned
+but not yet available.]
+
+However, it is possible to run `pacemaker_remote` inside a container,
+following the process for guest nodes. This is not recommended but can
+be useful, for example, in testing scenarios, to simulate a large number of
+guest nodes.
+
+The configuration process is very similar to that described for guest nodes
+using virtual machines. Key differences:
+
+* The underlying host must install the libvirt driver for the desired container
+ technology -- for example, the +libvirt-daemon-lxc+ package to get the
+ http://libvirt.org/drvlxc.html:[libvirt-lxc] driver for LXC containers.
+
+* Libvirt XML definitions must be generated for the containers. The
+ +pacemaker-cts+ package includes a helpful script for this purpose,
+ +/usr/share/pacemaker/tests/cts/lxc_autogen.sh+. Run it with the
+ `--help` option for details on how to use it. Of course, you can create
+ XML definitions manually, following the appropriate libvirt driver
+ documentation.
+
+* To share the authentication key, either share the host's +/etc/pacemaker+
+ directory with the container, or copy the key into the container's
+ filesystem.
+
+* The *VirtualDomain* resource for a container will need
+ *force_stop="true"* and an appropriate hypervisor option,
+ for example *hypervisor="lxc:///"* for LXC containers.
diff --git a/doc/Pacemaker_Remote/en-US/Ch-KVM-Tutorial.txt b/doc/Pacemaker_Remote/en-US/Ch-KVM-Tutorial.txt
index 33c49eb457..328a52eb0f 100644
--- a/doc/Pacemaker_Remote/en-US/Ch-KVM-Tutorial.txt
+++ b/doc/Pacemaker_Remote/en-US/Ch-KVM-Tutorial.txt
@@ -1,492 +1,477 @@
= Guest Node Walk-through =
*What this tutorial is:* An in-depth walk-through of how to get Pacemaker to
manage a KVM guest instance and integrate that guest into the cluster as a
guest node.
*What this tutorial is not:* A realistic deployment scenario. The steps shown
here are meant to get users familiar with the concept of guest nodes as quickly
as possible.
== Configure the Physical Host ==
=== SElinux and Firewall ===
In order to simplify this tutorial, we will disable SELinux and the local
firewall on the host. 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.
----
# setenforce 0
# sed -i.bak "s/SELINUX=enforcing/SELINUX=permissive/g" /etc/selinux/config
# systemctl disable firewalld.service
# systemctl stop firewalld.service
# iptables --flush
----
=== Install Cluster Software ===
----
# yum install -y pacemaker corosync pcs resource-agents
----
=== Configure Corosync ===
Corosync handles pacemaker's cluster membership and messaging. The corosync
config file is located in /etc/corosync/corosync.conf. That config file must be
initialized with information about the cluster nodes before pacemaker can
start.
To initialize the corosync config file, execute the following pcs command on both nodes filling in the information in <> with your nodes' information.
----
# pcs cluster setup --force --local --name mycluster <node1 ip or hostname> <node2 ip or hostname>
----
=== Verify Cluster Software ===
Start the cluster
----
# pcs cluster start
----
Verify corosync membership
----
# pcs status corosync
Membership information
Nodeid Votes Name
1795270848 1 example-host (local)
----
Verify pacemaker status. At first, the output will look like this:
----
# pcs status
Last updated: Thu Mar 14 12:26:00 2013
Last change: Thu Mar 14 12:25:55 2013 via crmd on example-host
Stack: corosync
Current DC:
Version: 1.1.10
1 Nodes configured, unknown expected votes
0 Resources configured.
----
After about a minute you should see your host as a single node in the cluster.
----
# pcs status
Last updated: Thu Mar 14 12:28:23 2013
Last change: Thu Mar 14 12:25:55 2013 via crmd on example-host
Stack: corosync
Current DC: example-host (1795270848) - partition WITHOUT quorum
Version: 1.1.8-9b13ea1
1 Nodes configured, unknown expected votes
0 Resources configured.
Online: [ example-host ]
----
Go ahead and stop the cluster for now after verifying everything is in order.
----
# pcs cluster stop
----
=== Install Virtualization Software ===
----
# yum install -y kvm libvirt qemu-system qemu-kvm bridge-utils virt-manager
# systemctl enable libvirtd.service
----
reboot the host
[NOTE]
======
While KVM is used in this example, any virtualization platform with a Pacemaker
resource agent can be used to create a guest node. The resource agent needs
only to support usual commands (start, stop, etc.); Pacemaker implements the
*remote-node* meta-attribute, independent of the agent.
======
== Configure the KVM guest ==
=== Create Guest ===
I am not going to outline the installation steps required to create a KVM
guest. There are plenty of tutorials available elsewhere that do that.
=== Configure Guest Network ===
Run the commands below to set up a static ip address (192.168.122.10) and hostname (guest1).
----
export remote_hostname=guest1
export remote_ip=192.168.122.10
export remote_gateway=192.168.122.1
yum remove -y NetworkManager
rm -f /etc/hostname
cat << END >> /etc/hostname
$remote_hostname
END
hostname $remote_hostname
cat << END >> /etc/sysconfig/network
HOSTNAME=$remote_hostname
GATEWAY=$remote_gateway
END
sed -i.bak "s/.*BOOTPROTO=.*/BOOTPROTO=none/g" /etc/sysconfig/network-scripts/ifcfg-eth0
cat << END >> /etc/sysconfig/network-scripts/ifcfg-eth0
IPADDR0=$remote_ip
PREFIX0=24
GATEWAY0=$remote_gateway
DNS1=$remote_gateway
END
systemctl restart network
systemctl enable network.service
systemctl enable sshd
systemctl start sshd
echo "checking connectivity"
ping www.google.com
----
To simplify the tutorial we'll go ahead and disable selinux on the guest. We'll also need to poke a hole through the firewall on port 3121 (the default port for pacemaker_remote) so the host can contact the guest.
----
# setenforce 0
# sed -i.bak "s/SELINUX=enforcing/SELINUX=permissive/g" /etc/selinux/config
# firewall-cmd --add-port 3121/tcp --permanent
----
If you still encounter connection issues, just disable firewalld on the guest
like we did on the host, to guarantee you'll be able to contact the guest from
the host.
At this point you should be able to ssh into the guest from the host.
=== Configure pacemaker_remote ===
On the 'host' machine, run these commands to generate an authkey and copy it to
the /etc/pacemaker folder on both the host and guest.
----
# mkdir -p --mode=0750 /etc/pacemaker
# chgrp haclient /etc/pacemaker
# dd if=/dev/urandom of=/etc/pacemaker/authkey bs=4096 count=1
# scp -r /etc/pacemaker root@192.168.122.10:/etc/
----
Now on the 'guest', install the pacemaker-remote package, and enable the daemon
to run at startup. In the commands below, you will notice the pacemaker
package is also installed. It is not required; the only reason it is being
-installed for this tutorial is because it contains the a Dummy resource agent
+installed for this tutorial is because it contains the Dummy resource agent
that we will use later for testing.
----
# yum install -y pacemaker pacemaker-remote resource-agents
# systemctl enable pacemaker_remote.service
----
Now start pacemaker_remote on the guest and verify the start was successful.
----
# systemctl start pacemaker_remote.service
# systemctl status pacemaker_remote
pacemaker_remote.service - Pacemaker Remote Service
Loaded: loaded (/usr/lib/systemd/system/pacemaker_remote.service; enabled)
Active: active (running) since Thu 2013-03-14 18:24:04 EDT; 2min 8s ago
Main PID: 1233 (pacemaker_remot)
CGroup: name=systemd:/system/pacemaker_remote.service
└─1233 /usr/sbin/pacemaker_remoted
Mar 14 18:24:04 guest1 systemd[1]: Starting Pacemaker Remote Service...
Mar 14 18:24:04 guest1 systemd[1]: Started Pacemaker Remote Service.
Mar 14 18:24:04 guest1 pacemaker_remoted[1233]: notice: lrmd_init_remote_tls_server: Starting a tls listener on port 3121.
----
=== Verify Host Connection to Guest ===
Before moving forward, it's worth verifying that the host can contact the guest
on port 3121. Here's a trick you can use. Connect using ssh from the host. The
connection will get destroyed, but how it is destroyed tells you whether it
worked or not.
First add guest1 to the host machine's /etc/hosts file if you haven't already. This is required unless you have dns setup in a way where guest1's address can be discovered.
----
# cat << END >> /etc/hosts
192.168.122.10 guest1
END
----
If running the ssh command on one of the cluster nodes results in this
output before disconnecting, the connection works.
----
# ssh -p 3121 guest1
ssh_exchange_identification: read: Connection reset by peer
----
If you see this, the connection is not working.
----
# ssh -p 3121 guest1
ssh: connect to host guest1 port 3121: No route to host
----
Once you can successfully connect to the guest from the host, shutdown the guest. Pacemaker will be managing the virtual machine from this point forward.
== Integrate Guest into Cluster ==
Now the fun part, integrating the virtual machine you've just created into the cluster. It is incredibly simple.
=== Start the Cluster ===
On the host, start pacemaker.
----
# pcs cluster start
----
Wait for the host to become the DC. The output of `pcs status` should look
similar to this after about a minute.
----
Last updated: Thu Mar 14 16:41:22 2013
Last change: Thu Mar 14 16:41:08 2013 via crmd on example-host
Stack: corosync
Current DC: example-host (1795270848) - partition WITHOUT quorum
Version: 1.1.10
1 Nodes configured, unknown expected votes
0 Resources configured.
Online: [ example-host ]
----
Now enable the cluster to work without quorum or stonith. This is required
just for the sake of getting this tutorial to work with a single cluster node.
----
# pcs property set stonith-enabled=false
# pcs property set no-quorum-policy=ignore
----
=== Integrate as Guest Node ===
If you didn't already do this earlier in the verify host to guest connection section, add the KVM guest's ip to the host's /etc/hosts file so we can connect by hostname. The command below will do that if you used the same ip address I used earlier.
----
# cat << END >> /etc/hosts
192.168.122.10 guest1
END
----
We will use the *VirtualDomain* resource agent for the management of the
virtual machine. This agent requires the virtual machine's XML config to be
dumped to a file on disk. To do this, pick out the name of the virtual machine
you just created from the output of this list.
....
# virsh list --all
Id Name State
----------------------------------------------------
- guest1 shut off
....
In my case I named it guest1. Dump the xml to a file somewhere on the host using the following command.
----
# virsh dumpxml guest1 > /root/guest1.xml
----
Now just register the resource with pacemaker and you're set!
----
# pcs resource create vm-guest1 VirtualDomain hypervisor="qemu:///system" config="/root/guest1.xml" meta remote-node=guest1
----
Once the *vm-guest1* resource is started you will see *guest1* appear in the
`pcs status` output as a node. The final `pcs status` output should look
something like this.
----
Last updated: Fri Mar 15 09:30:30 2013
Last change: Thu Mar 14 17:21:35 2013 via cibadmin on example-host
Stack: corosync
Current DC: example-host (1795270848) - partition WITHOUT quorum
Version: 1.1.10
2 Nodes configured, unknown expected votes
2 Resources configured.
Online: [ example-host guest1 ]
Full list of resources:
vm-guest1 (ocf::heartbeat:VirtualDomain): Started example-host
----
=== Starting Resources on KVM Guest ===
The commands below demonstrate how resources can be executed on both the
guest node and the cluster node.
Create a few Dummy resources. Dummy resources are real resource agents used just for testing purposes. They actually execute on the host they are assigned to just like an apache server or database would, except their execution just means a file was created. When the resource is stopped, that the file it created is removed.
----
# pcs resource create FAKE1 ocf:pacemaker:Dummy
# pcs resource create FAKE2 ocf:pacemaker:Dummy
# pcs resource create FAKE3 ocf:pacemaker:Dummy
# pcs resource create FAKE4 ocf:pacemaker:Dummy
# pcs resource create FAKE5 ocf:pacemaker:Dummy
----
Now check your `pcs status` output. In the resource section, you should see
something like the following, where some of the resources started on the
cluster node, and some started on the guest node.
----
Full list of resources:
vm-guest1 (ocf::heartbeat:VirtualDomain): Started example-host
FAKE1 (ocf::pacemaker:Dummy): Started guest1
FAKE2 (ocf::pacemaker:Dummy): Started guest1
FAKE3 (ocf::pacemaker:Dummy): Started example-host
FAKE4 (ocf::pacemaker:Dummy): Started guest1
FAKE5 (ocf::pacemaker:Dummy): Started example-host
----
The guest node, *guest1*, reacts just like any other node in the cluster. For
example, pick out a resource that is running on your cluster node. For my
purposes, I am picking FAKE3 from the output above. We can force FAKE3 to run
on *guest1* in the exact same way we would any other node.
----
# pcs constraint FAKE3 prefers guest1
----
Now, looking at the bottom of the `pcs status` output you'll see FAKE3 is on
*guest1*.
----
Full list of resources:
vm-guest1 (ocf::heartbeat:VirtualDomain): Started example-host
FAKE1 (ocf::pacemaker:Dummy): Started guest1
FAKE2 (ocf::pacemaker:Dummy): Started guest1
FAKE3 (ocf::pacemaker:Dummy): Started guest1
FAKE4 (ocf::pacemaker:Dummy): Started example-host
FAKE5 (ocf::pacemaker:Dummy): Started example-host
----
=== Testing Recovery and Fencing ===
Pacemaker's policy engine is smart enough to know fencing guest nodes
associated with a virtual machine means shutting off/rebooting the virtual
machine. No special configuration is necessary to make this happen. If you
are interested in testing this functionality out, trying stopping the guest's
pacemaker_remote daemon. This would be equivalent of abruptly terminating a
cluster node's corosync membership without properly shutting it down.
ssh into the guest and run this command.
----
# kill -9 `pidof pacemaker_remoted`
----
After a few seconds or so, you'll see this in your `pcs status` output. The
*guest1* node will be show as offline as it is being recovered.
----
Last updated: Fri Mar 15 11:00:31 2013
Last change: Fri Mar 15 09:54:16 2013 via cibadmin on example-host
Stack: corosync
Current DC: example-host (1795270848) - partition WITHOUT quorum
Version: 1.1.10
2 Nodes configured, unknown expected votes
7 Resources configured.
Online: [ example-host ]
OFFLINE: [ guest1 ]
Full list of resources:
vm-guest1 (ocf::heartbeat:VirtualDomain): Started example-host
FAKE1 (ocf::pacemaker:Dummy): Stopped
FAKE2 (ocf::pacemaker:Dummy): Stopped
FAKE3 (ocf::pacemaker:Dummy): Stopped
FAKE4 (ocf::pacemaker:Dummy): Started example-host
FAKE5 (ocf::pacemaker:Dummy): Started example-host
Failed actions:
guest1_monitor_30000 (node=example-host, call=3, rc=7, status=complete): not running
----
Once recovery of the guest is complete, you'll see it automatically get
re-integrated into the cluster. The final `pcs status` output should look
something like this.
----
Last updated: Fri Mar 15 11:03:17 2013
Last change: Fri Mar 15 09:54:16 2013 via cibadmin on example-host
Stack: corosync
Current DC: example-host (1795270848) - partition WITHOUT quorum
Version: 1.1.10
2 Nodes configured, unknown expected votes
7 Resources configured.
Online: [ example-host guest1 ]
Full list of resources:
vm-guest1 (ocf::heartbeat:VirtualDomain): Started example-host
FAKE1 (ocf::pacemaker:Dummy): Started guest1
FAKE2 (ocf::pacemaker:Dummy): Started guest1
FAKE3 (ocf::pacemaker:Dummy): Started guest1
FAKE4 (ocf::pacemaker:Dummy): Started example-host
FAKE5 (ocf::pacemaker:Dummy): Started example-host
Failed actions:
guest1_monitor_30000 (node=example-host, call=3, rc=7, status=complete): not running
----
=== Accessing Cluster Tools from Guest Node ===
Besides allowing the cluster to manage resources on a guest node,
pacemaker_remote has one other trick. The pacemaker_remote daemon allows
nearly all the pacemaker tools (`crm_resource`, `crm_mon`, `crm_attribute`,
`crm_master`, etc.) to work on guest nodes natively.
Try it: Run `crm_mon` on the guest after pacemaker has
integrated the guest node into the cluster. These tools just work. This
means resource agents such as master/slave resources which need access to tools
like `crm_master` work seamlessly on the guest nodes.
Higher-level command shells such as `pcs` may have partial support
on guest nodes, but it is recommended to run them from a cluster node.
-
-[NOTE]
-======
-It is possible to run `pacemaker_remote` inside an LXC container instead of
-a virtual machine, following a similar process. This approach is deprecated
-since Pacemaker now has built-in support for managing containers and services
-inside containers.
-
-It can still be a useful alternative however, especially in testing scenarios,
-to simulate a large number of guest nodes. The *pacemaker-cts* packages includes
-a helpful script, +/usr/share/pacemaker/tests/cts/lxc_autogen.sh+, for generating
-libvirt XML files for LXC containers. The configuration is otherwise very similar
-to guest nodes; the *VirtualDomain* resource for a container will need the options
-*force_stop="true" hypervisor="lxc:///"*.
-======
diff --git a/doc/Pacemaker_Remote/en-US/Pacemaker_Remote.xml b/doc/Pacemaker_Remote/en-US/Pacemaker_Remote.xml
index 74086ce046..3867314a33 100644
--- a/doc/Pacemaker_Remote/en-US/Pacemaker_Remote.xml
+++ b/doc/Pacemaker_Remote/en-US/Pacemaker_Remote.xml
@@ -1,16 +1,17 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Pacemaker_Remote.ent">
%BOOK_ENTITIES;
]>
<book>
<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="Ch-Intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Ch-Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Ch-Options.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Ch-KVM-Tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Ch-Baremetal-Tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Ch-Alternatives.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<index></index>
</book>