README
-------------------------------------------------------------------------
The components of Piranha are described below.


LINUX VIRTUAL SERVER (LVS)
--------------------------

Based on Wensong Zhang's Linux Virtual Server (LVS) kernel routing patch.
LVS provides for cluster configurations involving 3 or more nodes, were some
of the nodes provide load balanced services (such as http) and appear as a
single node and tcp/ip address.

Red Hat's Piranha software enhances this service even further to increase
load balancing abilities, and to provide automatic detection and failover
over of faulty servers.



FAILOVER SERVICES (FOS)
-----------------------

Using only a 2 node cluster (primary and secondary node), it is
possible to set one system up as a standby for certain IP services
running on the other. Services will automatically be started and
stopped by the failover process, and "move" the virtual IP address
of each service as needed. No load balancing exists in this setup.
A typical use for this service would be for web or ftp servers.

Both systems must be identically configured linux systems. Failover
Services are defined very must like virtual servers except that some
parameters are not applicable, and there are no "real servers". Failover
Services are currently mutually exclusive to virtual servers -- you cannot
have both active in the same config (lvs.cf).


PIRANHA COMPONENTS
------------------

IPVS (used oply by LVS)

  * Building virtual servers: floating IP addresses where requests for service
    arrive from the public internet.

  * Routing service requests from virtual servers to a pool of real Web and
    FTP servers on a private network. 

  * Migrating floating IP addresses and routing services from a failed primary
    node to a backup node.

  * Load-balancing modules: round-robin and least connections, which weighted
    versions of both. 

  * TCP or UDP connections, and persistence.


lvs (used onl by LVS)

  The lvs daemon runs on the primary and backup nodes. This process controls
  Piranha and supports communication among its components.


fos (used only by FOS)

  The fos daemon runs on the primary and backup nodes. This process controls
  Piranha and supports communication among its components.


/etc/lvs.cf

  This is the configuration file that, on startup, the lvs daemon reads.


pulse

  The pulse daemon runs on the primary and backup nodes. Through this process,
  the backup cluster node determines whether the primary node is alive. 


/etc/rc.d/init.d/pulse

  This is the pulse startup script.


nanny

  The nanny daemon runs on cluster nodes, and is used to monitor active
  services for failure. Through this process, the active cluster node
  continues to grant or forward service requests, or to treat the
  service as failed.


ipvsadm (unsed only by LVS)

  The command line tool for setting up and administering an LVS cluster.


send_arps

  Utility program used to notifiy network ARP tables that a virtual
  TCP/IP address has changed a MAC address.


Piranha

  The GUI tool for configuring q piranha cluster.
  Normally this is the tool you should use to maintain /etc/lvs.cf file.



See the sample.cf and HOWTO files, and/or the lvs.cf(5), pulse(8), nanny(8),
lvs (8), and fos(8) man pages for more information.



HTML INTERFACE
--------------
The decision to move to the web based front end for the configuration
was taken because the web interface provides a globally accepted stateless
enviroment which better fits the design of HA clustering. It also
means that you can configure a cluster remotely and with any OS that sports
a web browser. Also; if you are using the virtual ip address of your
servers, then your configuration tool will failover if/when the
servers failover.

Due to the stateless nature of HTML it is conviently possible to be
directly informed of changes in the system without  a reload of the web
page. In the control panel, a degree of statefulness is provided though
an auto-reload function of the web page. This provides what can only be
described as basic polling of the health of your LVS cluster.
	
INSTALLATION NOTES:

    1) Apache and PHP must be installed on the system in order to
       install/upgrade piranha.

    2) If you are installing Apache and/or PHP for the first time,
       you must remember to uncomment the PHP settings and mime
       types in /etc/httpd/conf/httpd.conf (and possibly in
       /etc/httpd/conf/srm.conf for earlier apache releases).
       Then (re)start Apache. You will not be able to view the
       piranha php files until this is done.
       Detailed instructions on this are covered in the php INSTALL
       file.

    3) For the web tool (and indeed the gtk tool version)
       you will need to setup the intended cluster servers
       to allow remote login of user piranha from each other
       either via ssh or (less securely) rsh

    4) Connect your web browser to the primary IP on your active/master
       node as in http://test.host.name/piranha


FAILOVER SERVICE NOTES:

In failover services, the failure  of a single service causes the entire
cluster node to perform a failover. When you monitor multiple services
(such as web AND ftp), if one of the services fails the node will failover.
If on the now active node one of those services does not come up, then
you will end up with a "ping-ponging" cluster.

Because of the nature of failover services as it is written, it is also easy
to create a non-functional "ping ponging" setup if you are not careful
with your configuration files. Almost all causes of a disfunctional system
are because of configuration errors.

Here are some steps to ensure a functional setup:

1. Make sure the lvs.cf files are exactly the same on both systems! The
   most common problem is mismatched config files.

2. If you are monitoring http, make sure that the port number specified
   in lvs.cf is also being used by httpd. In other words, if you are
   using apache for example, make sure your httpd configuration is
   using port 1010 instead of 80 if you specified 1010 in lvs.cf

3. Before you start piranha fos for the first time in a new configuration,
   start the service (ftp, http, etc.) manually and use telnet on the
   local and partner systems to see if that service REALLY is reachable.
   IF telnet CANNOT REACH A SERVICE, THEN IT IS LIKELY THAT PIRANHA CAN'T.

   For example (if you are monitoring http on port 1010); start httpd, then
   do a "telnet localhost 1010" and see if you get refused or not. If
   not, then try the same telnet from your partner computer to make sure that
   it can reach that service also. Make sure this works before starting
   piranha.

4. Piranha must control the starting and stopping of the services. This
   means that a failover takes time, depending on the service and computer
   speeds. Avoid using too small a heartbeat interval. If you are
   experiencing problems where failovers are interrupted or bounse back and
   forth, try using a larger heartbeat interval. Values between 5 and 10
   seconds are usually sufficient unless the compuers are very slow.

5. If you are monitoring a service controlled by inetd (such as ftp),
   remember that this means inetd will be started and stopped by piranha.
   This means, for example, that rsh will not be usable and you may have
   to use ssh instead (for file copies, etc.).
