mirror of
https://git.proxmox.com/git/mirror_corosync
synced 2025-08-15 00:43:24 +00:00
(Logical change 1.207)
git-svn-id: http://svn.fedorahosted.org/svn/corosync/trunk@668 fd59a12c-fef9-0310-b244-a6a79926bd2f
This commit is contained in:
Steven Dake
parent
cfbdb93051
commit
eae1ab58e8
@ -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
|
||||
@ -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
|
||||
Loading…
Reference in New Issue
Block a user