corosync/QUICKSTART

Application Interface Specification Quckstart Guide
---------------------------------------------------
This AIS package is broken into four parts.  The exec directory contains
all of the code responsible for serving the APIs.  The api directory contains
APIs the user can link to.  The test directory contains some simple test
programs which exercise the APIs.  The directory conf contains example
configuration files which can be copied directly onto the target system.

The API implements the Cluster Membership (CLM), Availabilty Management
Framework (AMF) and the Checkpointing (CKPT) APIs.

Configuring the AIS Executive:
------------------------------
The AIS Executive will automatically determine cluster membership by
communicating on a specified multicast address and port.

The directory conf contains the file network.conf

bindnetaddr:192.168.1.0
mcastaddr:226.94.1.1
mcastport:6000

bindnetaddr specifies the address which the AIS Executive should bind to.
This address should always end in zero.  If the local interface taffic
should routed over is 192.168.5.92, set bindnetaddr to 192.168.1.0.

mcastaddr is a multicast address.  The default should work but you may have
a different network configuration.  Avoid 224.x.x.x because this is a "config"
multicast address.

mcastport specifies the UDP port number.  It is possible to use the same
multicast address on a network with the AIS services configured for different
UDP ports.

The directory conf contains the file groups.conf which specifies the failover
groups, service units, components, and policies to be used by the AMF.  The
configuration file matches the testamf1-6 programs in the test directory and
can be copied directly.

These two files should be placed in the /etc/ais directory.

Building AIS
------------
AIS requires GCC, LD, and a Linux 2.4 kernel.  AIS has been tested on
Debian Sarge, MontaVista Carrier Grade Edition 3.1, and Redhat 9.

Compile AIS by running make in the root directory.  Make can also be run
in the individual directories.  Nothing is installed by make.  If install
is desired, the files must be copied manually.

Confiugre Host
--------------
For security reasons, the AIS only allows a process that had the EGID/GID
of "ais" to connect to it.  To make development easier, it is recommended to
create an "ais" user with the "ais" group.

[root@slickdeal root]# adduser ais -g ais

Set the ais user's password to something you can remember:

[root@slickdeal root]# passwd ais
Changing password for user ais.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.

Configure Network
-----------------
Some networks do not automatically configure the default route.  Ensure
the default route is configured or AIS wont be able to communicate with
other nodes.

[sdake@slickdeal sdake]$ /sbin/route
Kernel IP routing table
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
10.0.0.6        *               255.255.255.255 UH    0      0        0 tun0
127.0.0.0       *               255.0.0.0       U     0      0        0 lo
default         192.168.1.1     0.0.0.0         UG    0      0        0 eth0

the word default above specifies the default route.  If the default route
is missing, specify one by

unix# /sbin/route add default gw 192.168.1.1

where 192.168.1.1 is the gateway.  It is possible to specify an invalid 
route which will also make AIS work properly.

Run AIS Executive
-----------------
Get one or more nodes and run the AIS executive on each node.  A list of
node IPs should be displayed on stdout when the nodes join a configuration.
Run the aisexec program after following the previous directions.
(after the default route is setup and the config

Before running any of the test programs
---------------------------------------
The AIS Executive will ensure security by only allowing the ais group (or
uid root) to connect to the service.  Switch to the ais group before
running any applications linked to the saf api, or the applications will
not be authenticated and won't be able to access services.

[sdake@slickdeal sdake]$ su ais
Password:
[ais@slickdeal sdake]$ id
uid=501(ais) gid=502(ais) groups=502(ais)

Try out the AIS CLM functionality
---------------------------------
After aisexec is running

su to ais user

Run test/testclm on one node.  Then kill and add nodes.  This will cause
callbacks to be called in the testclm application which will print out
the node state changes.  The testclm program will not print any output
until nodes are added to or deleted from the configuration by starting
and stopping aisexec on other nodes.

Try out the AIS AMF functionality
---------------------------------
After aisexec is running

su to ais user

Run testamf1 on one node, testamf3 testamf4 on another node.
One will become active one standby.  testamf2 is special in that it shows
reporting and canceling an error.  Run testamf2 on the node testamf1
was run from.  The ha states and readiness states will be shown.

Try out the AIS CKPT functionality
----------------------------------
su to ais user

run ckptstress.  This will write checkpoint data as quickly as possible to
the cluster.

Write your own applications
---------------------------
Without real applications, finding the hard bugs will be difficult.  Please
port or write apps and let us know of the progress!

Contribute!
-----------
Code, examples, documentation, bug reports, testing are all appreciated.
Read the TODO or the ask on the mailing lists for ways to contribute.