man/openais_overview.8

   1 .\"/*
   2 .\" * Copyright (c) 2005 MontaVista Software, Inc.
   3 .\" * Copyright (c) 2006 Red Hat, Inc.
   4 .\" *
   5 .\" * All rights reserved.
   6 .\" *
   7 .\" * Author: Steven Dake (sdake@mvista.com)
   8 .\" *
   9 .\" * This software licensed under BSD license, the text of which follows:
  10 .\" *
  11 .\" * Redistribution and use in source and binary forms, with or without
  12 .\" * modification, are permitted provided that the following conditions are met:
  13 .\" *
  14 .\" * - Redistributions of source code must retain the above copyright notice,
  15 .\" *   this list of conditions and the following disclaimer.
  16 .\" * - Redistributions in binary form must reproduce the above copyright notice,
  17 .\" *   this list of conditions and the following disclaimer in the documentation
  18 .\" *   and/or other materials provided with the distribution.
  19 .\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
  20 .\" *   contributors may be used to endorse or promote products derived from this
  21 .\" *   software without specific prior written permission.
  22 .\" *
  23 .\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  24 .\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  27 .\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  28 .\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  29 .\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  30 .\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  31 .\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32 .\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  33 .\" * THE POSSIBILITY OF SUCH DAMAGE.
  34 .\" */
  35 .TH OPENAIS_OVERVIEW 8 2006-05-10 "openais Man Page" "Openais Programmer's Manual"
  36 .SH OVERVIEW
  37 The openais project is a project to implement a production quality "Revised BSD"
  38 licensed implementation of the most recent SA Forum's Application Interface
  39 Specification.  The Application Interface Specification is a software API and
  40 policies which are used to develop applications that maintain service during
  41 faults.  The API consists of Availability Management Framework (AMF) which
  42 provides application failover, Cluster Membership (CLM), Checkpointing (CKPT),
  43 Eventing (EVT), Messaging (MSG), and Distributed Locking (DLOCK).
  44
  45 Currently Messaging is unimplemented.
  46
  47 Faults occur for various reasons:
  48 .PP
  49 * Application Faults
  50 .PP
  51 * Middleware Faults
  52 .PP
  53 * Operating System Faults
  54 .PP
  55 * Hardware Faults
  56
  57 The major focus of high availability in the past has been to mask hardware
  58 faults. Faults in other components of the system have gone unsolved until
  59 AIS. AIS can mask many types of faults in applications, middleware,
  60 operating systems, or even hardware by providing a simple framework
  61 for allowing developers to create redundant applications. These redundant
  62 applications can be distributed over multiple nodes such that if any one
  63 node faults, another node can recover.
  64
  65 Application programmers develop applications to periodically record their
  66 state using the checkpointing service. When an active application fails,
  67 a standby application recovers the state of the application. This
  68 technique, called stateful application failover, provides the fundamental
  69 difference between openais and other systems that have come before it.
  70 With stateful application failover, the end-application user doesn't
  71 have to reload the application or redial a telephone. The full state
  72 is recorded, so the end-application user sees no interruption in service.
  73
  74 Because programmers can now distribute applications across multiple
  75 processes or nodes, a mechanism must exist for them to communicate.
  76 This mechanism is provided by two services. The event service provides
  77 a publish/subscribe model for events. The messaging service provides
  78 end to end messaging. Finally a mechanism to synchronize access is
  79 provided by the distributed lock service.
  80
  81 The openais project also provides a group messaging toolkit called EVS.
  82 The EVS service implements a messaging model known as Extended Virtual
  83 Synchrony.  This model allows one sender to transmit to many receivers.
  84 Certain guarantees are provided for message and membership delivery
  85 which make virtual synchrony ideal for developing distributed applications.
  86
  87 .SH QUICKSTART
  88 The openais executive must be configured.  In the directory conf in the
  89 source distribution are several files that must be copied to the /etc/ais
  90 directory.  If openais is packaged by a distro, this may be complete.
  91
  92 The directory contains the file openais.conf.  Please read the openais.conf(5)
  93 man page for details on the configuration options.  The openais project will
  94 work out of the box with the default configuration options, although the
  95 administrator may desire different options.
  96
  97 An user and group of the name "ais" must be added to the system.  If openais
  98 is packaged from a distro, this step should already be completed.
  99 This can be achieved by executing:
 100
 101 [root@slickdeal root]# adduser ais -g ais
 102
 103 The openais executive uses cryptographic techniques to ensure authenticity
 104 and privacy of the messages.  In order for openais to be secure and operate,
 105 a private key must be generated and shared to all processors.
 106
 107 First generate the key on one of the nodes:
 108
 109 unix# ais-keygen
 110 openais authentication key generator.
 111 .PP
 112 Gathering 1024 bits for key from /dev/random.
 113 .PP
 114 Writing openais key to /etc/ais/authkey.
 115 .PP
 116
 117 After this operation, a private key will be in the file /etc/ais/authkey.
 118 This private key must be copied to every processor in the cluster.  If the
 119 private key isn't the same for every node, those nodes with nonmatching private
 120 keys will not be able to join the same configuration.
 121
 122 Copy the key to some security transportable storage or use ssh to transmit the
 123 key from node to node.  Then install the key with the command:
 124
 125 unix#: install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/ais/authkey
 126
 127 If a message "Invalid digest" appears from the openais executive, the keys
 128 are not consistent between processors.
 129
 130 Finally run the openais executive.  If openais is packaged from a distro, it
 131 may be set to start on system start.  It may also be turned off by default in
 132 which case the init script for openais must be enabled.
 133
 134 After running aisexec, a list of all processors IP addresses running the ais
 135 executive and configured on the same multicast address will appear.  If they
 136 don't appear, there may be a problem with multicast in the distro or hardware.
 137 If this happens, participation in the openais mailing list may help solve the
 138 problem.  The email address is openais@lists.osdl.org.
 139
 140 .SH USING LIBRARIES
 141 The openais AIS libraries have header files which must be included in the
 142 developer's application.  Once the header file is included, the developer can
 143 reference the AIS interfaces.
 144
 145 The openais project recommends to distros to place include files in
 146 /usr/include/openais.  The following include lines must be added to
 147 the application to use each of the following services:
 148
 149 #include <openais/saClm.h> For the Cluster Membership B.01.01 service.
 150 .PP
 151 #include <openais/saCkpt.h> For the Checkpointing B.01.01 service.
 152 .PP
 153 #include <openais/saEvt.h> For the Eventing B.01.01 service.
 154 .PP
 155 #include <openais/ais_amf.h> For the AMF A.01.01 service.
 156 .PP
 157
 158 The openais project recommends to distros to place library files in
 159 /usr/lib.  The following link lines must be added to the LDFLAGS section
 160 of the makefile.
 161
 162 -lsaClm For the Cluster Membership B.01.01 service
 163 .PP
 164 -lsaCkpt For the Checkpointing B.01.01 service
 165 .PP
 166 -lsaEvt For the Eventing B.01.01 service
 167 .PP
 168 -lsaAmf For the AMF A.01.01 service
 169 .PP
 170 -lais Specify this to get access to all AIS libraries without specifying
 171 each library individually.
 172
 173 .SH IPv6
 174 The openais project supports both IPv4 and IPv6 network addresses.  The entire
 175 cluster must use either IPv4 or IPv6 for the cluster communication mechanism.
 176 In order to use IPv6, IPv6 addresses must be specified in the bindnetaddr and
 177 mcastaddr fields in the configuration file.  The nodeid field must also be
 178 set.
 179
 180 An example of this is:
 181 nodeid: 2
 182 bindnetaddr: fec0::1:a800:4ff:fe00:20
 183 mcastaddr: ff05::1
 184
 185 To configure a host for IPv6, use the ifconfig program to add interfaces:
 186 box20: ifconfig eth0 add fec0::1:a800:4ff:fe00:20/64
 187 box30: ifconfig eth0 add fec0::1:a800:4ff:fe00:30/64
 188
 189 If the /64 is not specified, a route for the IPv6 network will not be configured
 190 which will cause significant problems.  Make sure a route is available for
 191 IPv6 traffic.
 192
 193 .SH ARCHITECTURE
 194 The AIS libraries are a thin IPC interface to the openais executive.  The
 195 openais executive provides services for the SA Forum AIS libraries as well
 196 as the EVS and CPG libraries.
 197
 198 The openais executive uses the Totem extended virtual synchrony protocol.  The
 199 advantage to the end user is excellent performance characteristics and a proven
 200 protocol with excellent reliability.  This protocol connects the processors
 201 in a configuration together so they may communicate.
 202
 203 .SH ENVIRONMENT VARIABLES
 204 The openais executive process uses four environment variables during startup.
 205 If these environment variables are not set, defaults will be used.
 206
 207 .TP
 208 OPENAIS_MAIN_CONFIG_FILE
 209 This specifies the fully qualified path to the openais configuration file.
 210
 211 The default is /etc/ais/openais.conf.
 212
 213 .TP
 214 OPENAIS_AMF_CONFIG_FILE
 215 This specifies the fully qualified path to the openais Availability Management
 216 Framework configuration file.
 217
 218 The default is /etc/ais/amf.conf.
 219
 220 .TP
 221 OPENAIS_DEFAULT_CONFIG_IFACE
 222 This specifies the LCRSO that is used to parse the configuration file.  This
 223 allows other configuration file parsers to be implemented within the system.
 224
 225 The default is to use the default openais configuration file parser which
 226 parses the format specified in openais.conf (5).
 227
 228 .TP
 229 OPENAIS_TOTEM_AUTHKEY_FILE
 230 This specifies the fully qualified path to the shared key used to
 231 authenticate and encrypt data used within the Totem protocol.
 232
 233 The default is /etc/ais/authkey.
 234
 235 .SH SECURITY
 236 The openais executive optionally encrypts all messages sent over the network
 237 using the SOBER-128 stream cipher.  The openais executive uses HMAC and SHA1 to
 238 authenticate all messages.  The openais executive library uses SOBER-128
 239 as a pseudo random number generator.  The EVS library feeds the PRNG using
 240 the /dev/random Linux device.
 241
 242 If membership messages can be captured by intruders, it is possible to execute
 243 a denial of service attack on the cluster.  In this scenario, the cluster is
 244 likely already compromised and a DOS attack is the least of the administration's
 245 worries.
 246
 247 The security in openais does not offer perfect forward secrecy because the keys
 248 are reused.  It may be possible for an intruder by capturing packets in an
 249 automated fashion to determine the shared key.  No such automated attack has
 250 been published as of yet.  In this scenario, the cluster is likely already
 251 compromised to allow the long-term capture of transmitted data.
 252
 253 For security reasons, the openais executive binary aisexec should NEVER
 254 be setuid or setgid in the filesystem.
 255
 256 .PP
 257 .SH SAFTEST COMPLIANCE
 258 The openais libraries are now nearly compliant with every aspect of the SA
 259 Forum's AIS specification.  The AMF service, however, is not compliant with the
 260 B.01.01 specification.  The remaining services pass most of the tests of the
 261 saftest suite against the B.01.01 specification.
 262
 263 .SH BUGS
 264 The messaging service is partially implemented and not suitable for deployment.
 265 The distributed locking service is buggy and not suitable for deployment.
 266 The Availability Management Framework is under development and not suitable for
 267 deployment..
 268
 269 .SH "SEE ALSO"
 270 .BR openais.conf (5),
 271 .BR evs_overview (8)
 272 .PP