HOWTO
-------------------------------------------------------------------
This document explains how to use the Red Hat Piranha software to set up and
administer a highly-available Web/FTP site. 


Hardware/Connection Requirements
--------------------------------

LVS Nodes 

You need:

* A server machine that will be the primary LVS node. Minimally, the
machine must have two network adapters, one connecting it to the
Internet and the other to a private network of Web/FTP servers. For avoiding
single points of failure (SPoFs), the node may have additional adapters.

* Another machine that will be the backup LVS node. Functionally the backup
node is optional, but it is required if you want high-availability. This
machine also has two network adapters connecting it to the Internet and to
a private network of Web/FTP servers. Note that the backup LVS node is
purely a stand-by machine.


Web/FTP Server Hosts

Job requests received by the primary LVS node are redirected to a pool
of Web/FTP server hosts. Each will have at least one network adapter
connecting it to a private IP subnet. These may be any kind of computing
platform or HTTPD host with one exception: the weighted least_connection
scheduling method can examine active connections only on Linux Web/FTP
hosts.

During configuration, you will assign weights to these hosts reflecting their
processing capacity (memory, processor speed, number of processors, etc.)
relative to one another. Thus, you should be prepared to make accurate
assignments.


Software Requirements/Prerequisites
-----------------------------------

Kernel

The LVS nodes require Red Hat 6.1, or a Red Hat 6.0 kernel running the LVS
patch version 0.8.3.


Masquerading

Masquerading must be enabled on the LVS nodes. You can do this in two ways:

* In the /etc/sysconf/network script, set FORWARD_IPV4 and DEFRAG_IPV4 to "yes"

* Issue these commands:

	echo 1 > /proc/sys/net/ipv4/ip_forward
	echo 1 > /proc/sys/net/ipv4/ip_always_defrag
	ipchains -A forward -j MASQ -s n.n.n.n/24 -d 0.0.0.0/0
  
  n.n.n.n is the address of the private subnet of the Web/FTP hosts.


IP Addresses

During configuration, you will be asked to supply at least two floating IP
addresses:

* One will be for the NAT router. This will be a secondary address of the
network adapter connecting the LVS nodes to the network of Web/FTP server
hosts.

* One or more will be for virtual servers: the public address(es), including
port number(s), where incoming requests for service from Web/FTP clients
arrive.


Configuring the LVS Cluster
==========================

We assume you will use the Piranha GUI to set up, monitor, and administer
your LVS cluster. The fields on its screens are explained below. If you
prefer to use the command line tools, see the man pages: ipvsadm(8),
lvs(8), pulse(8), nanny(8), lvs.cf(5).

When you start Piranha (type piranha &), its main screen opens. The screen has
four tabs:

Controls/Monitoring. The initial tab. Used to monitor the runtime status and
synchronize configuration on the LVS nodes. See "Control/Monitoring Tab." 

Global Settings. Use to set the IP address of the primary LVS node
and NAT routing. See "Global Setting Tab."

Redundancy: Use to set the address of the backup LVS server and set the
pulse(8) parameters. See "Redundancy Tab."

Virtual Servers. Use to set service addresses and set up routing between 
service addresses and real Web/FTP server hosts. See "Virtual Servers Tab."

Piranha windows have one or more of these buttons along the bottom:

	OK - Apply changes and exit.

	Apply - Apply changes without exiting.

	Close - Exit without applying changes.


Controls/Monitoring Tab (control.png)
------------------------------------

Start
	Click to start the pulse daemon. 

Add pulse daemon to this runlevel
	Select to start pulse at system boot. 

Update information now
	Display current LVS runtime status.

Auto-update
	Select to display LVS runtime status automatically at the specified
	interval.


Global Settings Tab (global.png)
--------------------------------

Primary LVS server IP:
	Contains the public IP address of the primary LVS node.	

NAT Router IP:
	Contains the floating IP address associated with the network adapter
	connecting the node with the Web/FTP server host subnet. If this
	node fails, this address migrates to the backup LVS node.

NAT Router Device:
	Associate the floating NAT router address with the network adapter
	name, which must be the same on both LVS nodes. 

Sync tool:
	Click to select rsh or ssh as the tool used to synchronize files
	on the primary and backup nodes. 


Redundancy (redundancy.png)
---------------------------

Enable redundant server
	Select to enable failover. 

Redundant LVS server IP:
	Contains the public IP address of the backup LVS node. 

Heartbeat interval (seconds):
	Contains the number of seconds between heartbeats: the interval
	at which the backup LVS node checks to see if the primary LVS
	node is alive.

Assume dead after (seconds):
	If this number of seconds lapses without a response from the primary
	LVS node, the backup node initiates failover. 


Virtual Servers (virtual_servers.png)
-------------------------------------

This screen displays a row of information for each currently defined virtual
server. Click a row to select it. The buttons on the right side of the
screen apply to the currently selected virtual server. Click Delete to remove
the selected virtual server.

Status
	Displays Active or Down. Click Disable to take down a selected active
	virtual server; click Activate to enable a selected down virtual
	server.
Name
	The node's name (not the hostname, although it could be).

Port
	The listen port for incoming requests for service.

Protocol
	Currently, only TCP is supported.


Add/Edit a Virtual Server (edit_vs.png)

Click the Add button to create a new, undefined virtual server. Click the
Edit button  (or double-click the row) to define a newly-created virtual server
or change an existing virtual server. Click the Real Servers tab to set up
routing of job requests from this virtual server to the Web/FTP server hosts
that will process the requests (see the next section).

Name:
	Enter a descriptive name.

Application:
	Click to select HTTP or FTP.

Port:
	Enter the listening port for incoming requests.

Address:
	Enter the floating IP address where requests for service arrive.
	If this node fails, the address and port are failed-over to the backup
	LVS node.

Device:
	Associate the floating IP address with the network adapter that
	connects the LVS nodes to the public network. 

Re-entry Time:
	Enter the number of seconds that a failed Web/FTP server host
	associated with this virtual server must remain alive before it
	will be re-added to the pool.

Load monitoring tool:
	Select the tool to use (uptime, rup, or ruptime) for determining
	the workload on Web/FTP server hosts.

Scheduling:
	Select the altorithm for request routing from this virtual server
	to the Web/FTP server hosts that will perform the services:

	Select Weighted least-connections
	Assign more jobs to hosts that are least busy relative to their
	processing capacity.

	Weighted round robin
	Assign more jobs to hosts with greater processing capacity.
	
	Round robin
	Distribute jobs equally among the hosts. 

Real Servers (real_servers.png)

This screen displays a row of information for each currently defined Web/FTP
server. Click a row to select it. The buttons on the right side of the
screen apply to the currently selected server host. Click Delete to remove
the selected host.

Status
	Displays Active or Down. Click Disable to deactivate a selected server 
	host; click Activate to enable a selected down host. 

Name
	The server's name (not the hostname, although it could).

Address:

	The server's IP address.

Add/Edit a Real Server (edit_rs.png)

Click the Add button to create an association with a new, undefined Web/server
host. Click the Edit button  (or double-click the row) to define a new
host or change an existing one.

Name:
	Enter a descriptive name.

Address:
	Enter the Web/FTP server's IP address. The listening port will be
	the one specified for the associated virtual server. 

Weight:
	Assign an integer to indicate this host's processing capacity
	relative to that of other hosts in the pool.

