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

IPVS

Piranha is based on Wensong Zhang's Linux Virtual Server (LVS) kernel 
routing patch. This component provides for:  

* 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

The lvs 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 each real server host. Through this process,
the primary LVS node determines whether a host service is alive and
should continue to receive job assignments.

ipvsadm

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

Piranha

The GUI tool for monitoring, configuring, and administering an LVS cluster.
Normally this is the tool you should use to maintain /etc/lvs.cf, 
reconfigure the running daemons, and synchronize files between primary and
backup nodes.  This GTK tool is being obsoleted in liew of a web based
configuration mechanism.

Documentation: lvs.cf(5), lvs(8), fos(8), ipvsadm(8), pulse(8), HOWTO. 




NEW WITH THIS RELEASE OF PIRANHA

    o An HTML interface has been created that will allow for the maintenance
      of the lvs.cf steering file that defines the nature of your LVS cluster.

    o Generic services. In addition to web and ftp, you can now have
      piranha monitor and test any service port on your real servers,
      plus in some cases use communication strings to test if the service
      is functioning.

    o Persistent connections are now supported; along with specifying
      a netmask.

    o Use of tunneling and direct routing supported

    o First release of Failover Services. Provides warm failover functionality
      to a two node cluster.


GENERIC SERVICES

Piranha will now generically monitor any port specified in the virtual
server section of the config file. With a few expections, piranha will
judge the service functional if it is not refused a connection to it.

There are 2 exceptions to this. First; Web services (port 80) are tested
by performing a simple I/O test on the port to ensure the service
is responding. (Note: if you are not using the Apache web service, you
may want to override this by specifying your own send/expect strings).

Second; you can now specify a simple, text "send" and "expect" string
in your virtual server setup. If present, the string will be used
as an I/O test to the socket to see if the service functions. This will
work with user created services, as well as http, lpd, smtp, ftp, ssh,
inetd, and telnet. It will not work with binary services or services
using redirected port connections (like bootp/dhcp or dns). The strings
specified must work equally well on all real services providing the
virtual service.

This is a first implementation of what may become a more advanced
capability in the future. See the nanny and lvs.cf man pages
file for further details.



FAILOVER SERVICES

This release of piranha introduces a new facility called "failover
services". Using only a primary and secondary node, it is possible
to set one system up as a warm 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. 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 mutually exclusive to virtual servers -- you cannot have
both active in the same config (lvs.cf). Pulse can only control one or
the other, not both.

For failover services, pulse controls a daemon called "fos" instead
of the virtual server daemon "lvs". "fos" uses the same nanny daemons
to perform service monitoring that "lvs" does (just with slightly
different run options).

See the sample.cf, pulse(8), nanny(8), and fos(8) man page for more
information.



HTML INTERFACE

This web front end has been designed to be as close as possiblle,
functionally identical to the GTK version. This was so that previous
users of piranha < 0.3 could seamlessy migrate to the web version.

The web version also contains new parameters for using other
network services (direct routing and tunneling) and for udp.

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.
	
As a result of the security restrictions places around web
servers, nearly all operations are performed as nobody.nobody (though
this will depend on the configuration of your web server setup) which is
a common web server configuration. This has issues because

	a) pulse and lvs require root access to meddle with the networking
	   structures and interfaces in the kernel.
	b) The web server runs in a chrooted enviroment. This normally
	   means that you cannot execute programs outside of the
	   DocumentRoot and so this places some severe restrictions upon
	   running cgi's and external programs. Indeed the fate of the
	   lvs.cf file itself becomes embroiled as it's normal resting
	   place is in /etc
 	c) The suexec module for apache which is supposed to help people
	   around these types of problems is by default only capable of
	   allowing UID's down to 100, though a recompile will allow for
	   use at UID 0.

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