(Logical change 1.207)

git-svn-id: http://svn.fedorahosted.org/svn/corosync/trunk@668 fd59a12c-fef9-0310-b244-a6a79926bd2f

man/openais.conf.5

@@ -0,0 +1,176 @@
+.\"/*
+.\" * Copyright (c) 2005 MontaVista Software, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Steven Dake (sdake@mvista.com)
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH OPENAIS_CONF 5 2005-06-08 "openais Man Page" "Openais Programmer's Manual"
+.SH NAME
+openais.conf - openais executive configuration file
+
+.SH SYNOPSIS
+/etc/ais/openais.conf
+
+.SH DESCRIPTION
+The openais.conf instructs the openais executive about various parameters
+needed to control the openais executive.  The configuration file consists of
+bracketed top level directives.  The possible directive choices are
+.IR network { } ", " logging { } ", " timeout { } ".  These directives are
+described below.
+
+.TP
+network { }
+This top level directive contains configuration options for the network.
+.TP
+logging { }
+This top level directive contains configuration options for logging.
+.TP
+timeout { }
+This top level directive contains configuration options for protocol timeouts.
+
+.PP
+.PP
+Within the 
+.B network
+directive, there are three configuration options which are all required:
+.TP
+bindnetaddr
+This specifies the address which the openais executive should bind.
+This address should always end in zero.  If the local interface traffic should
+be routed over 192.168.5.92, set bindnetaddr to 192.168.5.0.
+
+.TP
+mcastaddr
+This is the multicast address used by openais executive.  The default
+should work for most networks, but the network administrator should be queried
+about a multicast address to use.  Avoid 224.x.x.x because this is a "config"
+multicast address.
+
+.TP
+mcastport
+This 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.
+
+.PP
+.PP
+Within the 
+.B logging
+directive, there are four configuration options which are all optional:
+.TP
+logoutput
+This specifies the logging output.  The choices are file, which logs to a file,
+stderr, which logs to stderr, and syslog which logs to the system log.  It is
+possible to have multiple targets by including this directive with different
+options multiple times in the top level directive.
+
+.TP
+logfile
+If the logoutput: file directive is set, this option specifies where the
+log file is written to.  
+
+.TP
+debug
+This specifies whether debug output is logged.  This is generally a bad idea, 
+unless there is some specific bug or problem that must be found in the
+executive.  Set the value to on to debug, off to turn of debugging.
+
+.TP
+timestamp
+This specifies that a timestamp is placed on all log messages.
+.PP
+.PP
+Within the 
+.B timeout
+directive, there are several configuration options which are all optional.
+It is generally not recommended to change any of these values.  Some networks
+may require larger values for token or some applications may require faster
+failure detection times (and lower values for token).
+.TP
+token
+This timeout specifies in milliseconds until a token loss is declared after not
+receiving a token.  This is the time spent detecting a failure of a processor
+in the current configuration.  Reforming a new configuration takes about 50
+milliseconds and is independent of this timeout.
+
+.TP
+token_retransmit
+This timeout specifies in milliseconds after how long before receiving a token
+the token is retransmitted.  This will be automatically calculated if token
+is modified.  It is not recommended to alter this value without guidance from
+the openais community.
+
+.TP
+hold
+This timeout specifies in milliseconds how long the token should be held by
+the representative when the protocol is under low utilization.   It is not
+recommended to alter this value without guidance from the openais community.
+
+.TP
+retransmits_before_loss
+This value identifies how many token retransmits should be attempted before
+forming a new configuration.  If this value is set, retransmit and hold will
+be automatically calculated from retransmits_before_loss and token.
+
+.TP
+join
+This timeout specifies in milliseconds how long to wait for join messages in 
+the membership protocol.
+
+.TP
+consensus
+This timeout specifies in milliseconds how long to wait for consensus to be
+achieved before starting a new round of membership configuration.
+
+.TP
+merge
+This timeout specifies in milliseconds how long to wait before checking for
+a partition when no multicast traffic is being sent.  If multicast traffic
+is being sent, the merge detection happens automatically as a function of
+the protocol.
+
+.TP
+downcheck
+This timeout specifies in milliseconds how long to wait before checking
+that a network interface is back up after it has been downed.
+
+.TP
+fail_recv_const
+This value identifies how many rotations of the token without receiving any
+of the messages may occur before a new configuration is formed.
+
+.SH "FILES"
+.TP
+/etc/ais/openais.conf
+The openais executive configuration file.
+
+.SH "SEE ALSO"
+.BR openais_overview (8)
+.PP

man/openais_overview.8

@@ -0,0 +1,204 @@
+.\"/*
+.\" * Copyright (c) 2005 MontaVista Software, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Steven Dake (sdake@mvista.com)
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" * 
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" *   this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" *   this list of conditions and the following disclaimer in the documentation
+.\" *   and/or other materials provided with the distribution.
+.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
+.\" *   contributors may be used to endorse or promote products derived from this
+.\" *   software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH OPENAIS_OVERVIEW 8 2005-06-08 "openais Man Page" "Openais Programmer's Manual"
+.SH OVERVIEW
+The openais project is a project to implement a production quality "Revised BSD"
+licensed implementation of the most recent SA Forum's Application Interface
+Specification.  The Application Interface Specification is a software API and
+policies which are used to develop applications that maintain service during
+faults.  The API consists of Availability Management Framework (AMF) which
+provides application failover, Cluster Membership (CLM), Checkpointing (CKPT),
+Eventing (EVT), Messaging (MSG), and Distributed Locking (DLOCK).
+
+Currently Messaging and Distributed Locking are unimplemented.
+
+Faults occur for various reasons:
+.PP
+* Application Faults
+.PP
+* Middleware Faults
+.PP
+* Operating System Faults
+.PP
+* Hardware Faults
+
+The major focus of high availability in the past has been to mask hardware
+faults. Faults in other components of the system have gone unsolved until
+AIS. AIS can mask many types of faults in applications, middleware,
+operating systems, or even hardware by providing a simple framework
+for allowing developers to create redundant applications. These redundant
+applications can be distributed over multiple nodes such that if any one
+node faults, another node can recover.
+
+Application programmers develop applications to periodically record their
+state using the checkpointing service. When an active application fails,
+a standby application recovers the state of the application. This
+technique, called stateful application failover, provides the fundamental
+difference between openais and other systems that have come before it.
+With stateful application failover, the end-application user doesn't
+have to reload the application or redial a telephone. The full state
+is recorded, so the end-application user sees no interruption in service.
+
+Because programmers can now distribute applications across multiple
+processes or nodes, a mechanism must exist for them to communicate.
+This mechanism is provided by two services. The event service provides
+a publish/subscribe model for events. The messaging service provides
+end to end messaging. Finally a mechanism to synchronize access is
+provided by the distributed lock service. 
+
+The openais project also provides a group messaging toolkit called EVS.
+The EVS service implements a messaging model known as Extended Virtual
+Synchrony.  This model allows one sender to transmit to many receivers.
+Certain guarantees are provided for message and membership delivery
+which make virtual synchrony ideal for developing distributed applications.
+
+.SH QUICKSTART
+The openais executive must be configured.  In the directory conf in the
+source distribution are several files that must be copied to the /etc/ais
+directory.  If openais is packaged by a distro, this may be complete.
+
+The directory contains the file openais.conf.  Please read the openais.conf(5)
+man page for details on the configuration options.  The openais project will
+work out of the box with the default configuration options, although the
+administrator may desire different options.
+
+An user and group of the name "ais" must be added to the system.  If openais
+is packaged from a distro, this step should already be completed.
+This can be achieved by executing:
+
+[root@slickdeal root]# adduser ais -g ais
+
+The openais executive uses cryptographic techniques to ensure authenticity
+and privacy of the messages.  In order for openais to be secure and operate,
+a private key must be generated and shared to all processors.
+
+First generate the key on one of the nodes:
+
+unix# ais-keygen
+openais authentication key generator.
+.PP
+Gathering 1024 bits for key from /dev/random.
+.PP
+Writing openais key to /etc/ais/authkey.
+.PP
+
+After this operation, a private key will be in the file /etc/ais/authkey.
+This private key must be copied to every processor in 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 security 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 a message "Invalid digest" appears from the openais executive, the keys
+are not consistent between processors.
+
+Finally run the openais executive.  If openais is packaged from a distro, it
+may be set to start on system start.  It may also be turned off by default in
+which case the init script for openais must be enabled.
+
+After running aisexec, a list of all processors IP addresses running the ais
+executive and configured on the same multicast address will appear.  If they
+don't appear, there may be a problem with multicast in the distro or hardware.
+If this happens, participation in the openais mailing list may help solve the
+problem.  The email address is openais@lists.osdl.org.
+
+.SH USING LIBRARIES
+The openais AIS libraries have header files which must be included in the
+developer's application.  Once the header file is included, the developer can
+reference the AIS interfaces.
+
+The openais project recommends to distros to place include files in
+/usr/include/openais.  The following include lines must be added to
+the application to use each of the following services: 
+
+#include <openais/saClm.h> For the Cluster Membership B.01.01 service.
+.PP
+#include <openais/saCkpt.h> For the Checkpointing B.01.01 service.
+.PP
+#include <openais/saEvt.h> For the Eventing B.01.01 service.
+.PP
+#include <openais/ais_amf.h> For the AMF A.01.01 service.
+.PP
+
+The openais project recommends to distros to place library files in
+/usr/lib.  The following link lines must be added to the LDFLAGS section
+of the makefile.
+
+-lsaClm For the Cluster Membership B.01.01 service
+.PP
+-lsaCkpt For the Checkpointing B.01.01 service
+.PP
+-lsaEvt For the Eventing B.01.01 service
+.PP
+-lsaAmf For the AMF A.01.01 service
+.PP
+-lais Specify this to get access to all AIS libraries without specifying
+each library individually.
+
+.SH ARCHITECTURE
+The AIS libraries are a thin IPC interface to the openais executive.  The
+openais executive provides services for the SA Forum AIS libraries as well
+as the EVS library.
+
+The openais executive uses the Totem extended virtual synchrony protocol.  The
+advantage to the end user is excellent performance characteristics and a proven
+protocol with excellent reliability.  This protocol connects the processors
+in a configuration together so they may communicate.
+
+.SH SECURITY
+The openais executive encrypts all messages sent over the network using the
+SOBER-128 stream cipher.  The openais executive uses HMAC and SHA1 to
+authenticate all messages.  The openais executive library uses SOBER-128
+as a pseudo random number generator.  The EVS library feeds the PRNG using
+the /dev/random Linux device.
+.PP
+.SH BUGS
+The openais libraries are not particularly compliant with every aspect of the
+SA Forum's AIS specification.  The APIs themselves are consistent, but some of
+the return values and other details are not quite right yet.  The project does
+intend to be fully compliant with SAF specifications in 2005.
+
+The AMF that is currently available is AMF A.01.01.  The rest of the services
+are of the B.01.01 specification.  This is a limitation for those developers that
+desire AMF B.01.01.  The project intends to resolve this inconsistently in 2005.
+
+The openais project does not currently implement the messaging service or
+distributed locking service.
+.SH "SEE ALSO"
+.BR openais.conf (5),
+.BR evs_overview (8)
+.PP