Application Interface Specification Quckstart Guide --------------------------------------------------- *** All cryptographic software in this package is subject to the following legal notice: This package includes publicly available encryption source code which, together with object code resulting from the compiling of publicly available source code, may be exported from the United States under License Exception TSU prsuant to 15 C.F.R Section 740.13(e). *** This openais 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 openais executive: ------------------------------ The openais executive will automatically determine cluster membership by communicating on a specified multicast address and port. The directory conf contains the file openais.conf network { bindnetaddr: 192.168.1.0 mcastaddr: 226.94.1.1 mcastport: 5405 } logging { logoutput: file logoutput: stderr logoutput: syslog logfile: /tmp/ais debug: on timestamp: on } The network section contains three values. All three values must be set or the openais executive wll exit with an error. bindnetaddr specifies the address which the openais 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.5.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 openais services configured for different UDP ports. The logging section contains values. These values do not have to be set in which case the system defaults to logging to syslog and stderr with timestamping and debug. It is possible to select 3 destinations for logs: files, stderr, and syslog. One or more may be selected at the same time. If file is selected as a destination, the file name must be specified via the logfile option or the openais executive will exit. The debug option prints out internal debugging information during runtime which may be helpful for developers. The timestamp option prints the date and time on each log message. 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 openais ---------------- openais requires GCC, LD, and a Linux 2.4 kernel. openais has been tested on Debian Sarge, MontaVista Carrier Grade Edition 3.1, and Redhat 9, and Fedora Core 2. Compile openais 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 openais 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 openais 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 openais work properly. Generate a private key ---------------------- openais uses cryptographic techniques to ensure authenticity and privacy of messages. In order for openais to work, a private key must be generated and shared to all processors. First generate the key on one of the nodes: unix# exec/keygen Openopenais Authentication key generator. Gathering 1024 bits for key from /dev/random. Writing openais key to /etc/ais/authkey. After this is complete, a private key will be in the directory /etc/ais/authkey. This private key must be copied to every processor that will be a member of the cluster. If the private key isn't the same for every node, those nodes with nonmatching private keys will not be able to join the same configuration. Copy the key to some transportable storage or use ssh to transmit the key from node to node. Then install the key with the command: unix# install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/ais/authkey If the message invalid digest appears, the keys are not the same on each node. Run the openais executive ------------------------- Get one or more nodes and run the openais executive on each node. A list of node IPs should be logged when the nodes join a configuration. Run the aisexec program after following the previous directions. Before running any of the test programs --------------------------------------- The openais 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 openais 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 after it is started and has printed the current configuration until nodes are added to or deleted from the configuration by starting and stopping aisexec on other nodes. Killing aisexec on the node the testclm is connected will cause the API to return error codes indicating the system has failed. Try out the openais AMF functionality --------------------------------- After aisexec is running su to ais user The test/testamf{1-6} implement three seperate service units (SU). SU #1 consists of testamf1, testamf2. SU #2 consists of testamf3, testamf4. SU #3 consists of testamf5, testamf6. The active and backup directives in groups.conf define how many SU's become active and how many become standby in the service group (SG). To test the openais AMF, run testamf3 and testamf4 on one node. Both components become in service and active. Then run testamf1. Nothing appears to happen, because testamf1 is not placed in service (and made standby) until testamf2 is registered. Running testamf2 will show a variety of state changes. testamf1 will match these state changes. testamf2 is special because is reports an error, and later cancels the error, causing the entire SU to go out of service, then back in service. This behavior is expected by the openais specification and the code in testamf2.c can be read for a clearer understanding of what is happening. Pressing ctrl-z to background the task (which causes the heartbeat to timeout) on a component will cause the remaining component to go out of service. If ctrl-z is pressed on the active SU, the standby SU will become active. CTRL-C on these tests behaves the same way. A crash behaves the same way. Try out the openais CKPT functionality -------------------------------------- su to ais user run testckpt. This will execute various checkpoint API operations. run ckptbench. This will execute non-threaded write benchmarks. run ckptbenchth. This will execute threaded write benchmarks. The benchmark configuration (how many threads to run, how many writes per benchmark run, and data write size are specified in the ckptbench.c and ckptbenchth.c programs. Two node clusters should approach 8.5 MB/sec on 100 mbit networks for larger checkpoint sizes with encryption and authentication. If you are not seeing these results, please report to the mailing list. 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.