QUICKSTART

   1 Application Interface Specification Quckstart Guide
   2 ---------------------------------------------------
   3
   4 ***
   5 All cryptographic software in this package is subject to the following legal
   6 notice:
   7 This package includes publicly available encryption source code which,
   8 together with object code resulting from the compiling of publicly
   9 available source code, may be exported from the United States under License
  10 Exception TSU prsuant to 15 C.F.R Section 740.13(e).
  11 ***
  12
  13 This openais package is broken into four parts.  The exec directory contains
  14 all of the code responsible for serving the APIs.  The lib directory contains
  15 APIs the to which the user may link.  The test directory contains some simple
  16 test programs which exercise the APIs.  The directory conf contains example
  17 configuration files which can be copied directly onto the target system.
  18
  19 The API implements SA Forum APIs for Cluster Membership (CLM), Availabilty
  20 Management Framework (AMF), Checkpointing (CKPT), and Eventing (EVT).
  21
  22 The API also contains an extended virtual synchrony API which can be used
  23 in distributed applications.
  24
  25 Configuring the openais executive:
  26 ---------------------------------
  27 The openais executive will automatically determine cluster membership by
  28 communicating on a specified multicast address and port.
  29
  30 The directory conf contains the file openais.conf
  31
  32 totem {
  33         bindnetaddr: 192.168.1.0
  34         mcastaddr: 226.94.1.1
  35         mcastport: 5405
  36 }
  37
  38 logging {
  39         logoutput: file
  40         logoutput: stderr
  41         logoutput: syslog
  42         logfile: /tmp/ais
  43         debug: on
  44         timestamp: on
  45 }
  46
  47 timeout {
  48         token: 200
  49         token_retransmit: 50
  50         hold: 30
  51         retransmits_before_loss: 4
  52         join: 100
  53         consensus: 200
  54         merge: 200
  55         downcheck: 1000
  56         fail_recv_const: 250
  57 }
  58
  59 The totem section contains three values.  All three values must be set
  60 or the openais executive wll exit with an error.
  61
  62 bindnetaddr specifies the address which the openais Executive should bind to.
  63 This address should always end in zero.  If the local interface taffic
  64 should routed over is 192.168.5.92, set bindnetaddr to 192.168.5.0.
  65
  66 mcastaddr is a multicast address.  The default should work but you may have
  67 a different network configuration.  Avoid 224.x.x.x because this is a "config"
  68 multicast address.
  69
  70 mcastport specifies the UDP port number.  It is possible to use the same
  71 multicast address on a network with the openais services configured for different
  72 UDP ports.
  73
  74 The logging section contains values.  These values do not have to be set in which
  75 case the system defaults to logging to syslog and stderr with timestamping and debug.
  76
  77 It is possible to select 3 destinations for logs: files, stderr, and syslog.  One or
  78 more may be selected at the same time.  If file is selected as a destination, the file
  79 name must be specified via the logfile option or the openais executive will exit.
  80
  81 The debug option prints out internal debugging information during runtime which may
  82 be helpful for developers.
  83
  84 The timestamp option prints the date and time on each log message.
  85
  86 The timeout section contains seven values.  This section is not normally used, but
  87 rather used to override the program defaults for the purposes of fine tuning for
  88 a given networking/processor combination or for debugging purposes. Be careful to
  89 use the same timeout values on each of the nodes in the cluster or unpredictable
  90 results may occur.
  91
  92 All timeout values except fail_recv_const are miliseconds. fail_recv_const is
  93 a message count. Until the man page is done you'll have to check the code and the
  94 totem spec for the function and usage of the timeouts.
  95
  96
  97 The directory conf contains the file amf.conf which specifies the failover
  98 groups, service units, components, and policies to be used by the AMF.  The
  99 configuration file matches the testamf1-6 programs in the test directory and
 100 can be copied directly.
 101
 102 These two files should be placed in the /etc/ais directory.
 103
 104 A few notes about the config files:
 105 1) Do not use DOS style termination.  This breaks the parser.
 106 2) Do not have blank lines in the amf.conf file.  This breaks the amf configuration
 107    file parser.  We are working on fixing these bugs, but for the moment, it is
 108    easy to simply avoid them.
 109
 110 Building openais
 111 ----------------
 112 openais requires GCC, LD, and a Linux 2.4/2.6 kernel.  openais has been tested on
 113 Debian Sarge(i386), Redhat 9(i386), Fedora Core 2(i386), Fedora Core
 114 4(i386,x86_64) and MontaVista Carrier Grade Edition 3.1(i386, x86_64,
 115 classic ppc, ppc970, xscale).
 116
 117 Compile openais by running make in the root directory.  Make can also be run
 118 in the individual directories.  Nothing is installed by make.  If install
 119 is desired, the files must be copied manually.
 120
 121 Configure Host
 122 --------------
 123 For security reasons, the openais only allows a process that had the EGID/GID
 124 of "ais" to connect to it.  To make development easier, it is recommended to
 125 create an "ais" user with the "ais" group.
 126
 127 [root@slickdeal root]# adduser ais -g ais
 128
 129 Set the ais user's password:
 130
 131 [root@slickdeal root]# passwd ais
 132 Changing password for user ais.
 133 New password:
 134 Retype new password:
 135 passwd: all authentication tokens updated successfully.
 136
 137 Generate a private key
 138 ----------------------
 139 openais uses cryptographic techniques to ensure authenticity and privacy of
 140 messages.  A private key must be generated and shared by all processors for
 141 correct operation.
 142
 143 First generate the key on one of the nodes:
 144
 145 unix# exec/keygen
 146 Openopenais Authentication key generator.
 147 Gathering 1024 bits for key from /dev/random.
 148 Writing openais key to /etc/ais/authkey.
 149
 150
 151 After this is complete, a private key will be in the file /etc/ais/authkey.
 152 This private key must be copied to every processor that will be a member of
 153 the cluster.  If the private key isn't the same for every node, those nodes
 154 with nonmatching private keys will not be able to join the same configuration.
 155
 156 Copy the key to some transportable storage or use ssh to transmit the key
 157 from node to node.  Then install the key with the command:
 158
 159 unix# install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/ais/authkey
 160
 161 If the message invalid digest appears, the keys are not the same on each node.
 162
 163 Run the openais executive
 164 -------------------------
 165 Get one or more nodes and run the openais executive on each node.  A list of
 166 node IPs should be logged when the nodes join a configuration.  Run the
 167 aisexec program after following the previous directions.
 168
 169 A final note on permissions:
 170 It is not absolutely required that openais executive runs as root.  If
 171 it runs as root, it schedules at the highest round robin realtime
 172 priority and locks all of it's pages into ram in case a swap would cause a
 173 delay in the real-time nature of the protocol.  The warning "not
 174 able to lock pages" is simply a warning and can be ignored if you choose
 175 to run as a non root user.
 176
 177 The ais user/group is required because applications are authenticated
 178 against the ais user and group.  If an application(/library) is not root
 179 or ais, then the application cannot connect to the ais executive.
 180
 181 please read SECURITY to understand the threat model assumed by openais
 182 and the techniques openais use to overcome these threats.
 183
 184 Before running any of the test programs
 185 ---------------------------------------
 186 The openais executive will ensure security by only allowing the ais group (or
 187 uid root) to connect to the service.  Switch to the ais group before
 188 running any applications linked to the ais apis, or the applications will
 189 not be authenticated and won't be able to access services.
 190
 191 [sdake@slickdeal sdake]$ su ais
 192 Password:
 193 [ais@slickdeal sdake]$ id
 194 uid=501(ais) gid=502(ais) groups=502(ais)
 195
 196 Try out the openais CLM functionality
 197 -------------------------------------
 198 After aisexec is running
 199
 200 su to ais user
 201
 202 Run test/testclm on one node.  Then kill and add nodes.  This will cause
 203 callbacks to be called in the testclm application which will print out
 204 the node state changes.  The testclm program will not print any output
 205 after it is started and has printed the current configuration until nodes
 206 are added to or deleted from the configuration by starting and stopping
 207 aisexec on other nodes.
 208
 209 Killing aisexec on the node the testclm is connected will cause the
 210 API to return error codes indicating the system has failed.
 211
 212 Try out the openais AMF functionality
 213 -------------------------------------
 214 After aisexec is running
 215
 216 su to ais user
 217
 218 The test/testamf{1-6} implement three seperate service units (SU).  SU #1
 219 consists of testamf1, testamf2.  SU #2 consists of testamf3, testamf4.
 220 SU #3 consists of testamf5, testamf6.  The active and backup directives
 221 in amf.conf define how many SU's become active and how many
 222 become standby in the service group (SG).
 223
 224 To test the openais AMF, run testamf3 and testamf4 on one node.  Both
 225 components become in service and active.  Then run testamf1.  Nothing
 226 appears to happen, because testamf1 is not placed in service (and made
 227 standby) until testamf2 is registered.  Running testamf2 will show
 228 a variety of state changes.  testamf1 will match these state changes.
 229 testamf2 is special because is reports an error, and later cancels
 230 the error, causing the entire SU to go out of service, then back in
 231 service.  This behavior is expected by the openais specification and the
 232 code in testamf2.c can be read for a clearer understanding of what
 233 is happening.
 234
 235 Pressing ctrl-z to background the task (which causes the healthcheck to
 236 timeout) on a component will cause the remaining component to go
 237 out of service.  If ctrl-z is pressed on the active SU, the standby
 238 SU will become active.  CTRL-C on these tests behaves the same way.
 239 A crash behaves the same way.
 240
 241 Try out the openais CKPT functionality
 242 --------------------------------------
 243 su to ais user
 244
 245 run testckpt.  This will execute various checkpoint API operations.
 246
 247 run ckptbench.  This will execute non-threaded write benchmarks.
 248
 249 run ckptbenchth.  This will execute threaded write benchmarks.
 250
 251 The benchmark configuration (how many threads to run, how many writes
 252 per benchmark run, and data write size are specified in the ckptbench.c
 253 and ckptbenchth.c programs.
 254
 255 Two node clusters should approach 8.5 MB/sec on 100 mbit networks for
 256 larger checkpoint sizes with encryption and authentication.  If you are not
 257 seeing these results, please report to the mailing list.
 258
 259 Try out the openais EVT functionality
 260 -------------------------------------
 261 su to ais user
 262
 263 run testevt.  This will execute various eventing API operations.
 264
 265 Try out the openais EVS functionality
 266 -------------------------------------
 267 su to ais user
 268 run testevs.  This will generate multicast messages and self deliver them
 269
 270 run evsbench.  This will display the benchmark performance of the evs service.
 271
 272 Write your own applications
 273 ---------------------------
 274 Without real applications, finding the hard bugs will be difficult.  Please
 275 port or write apps and let us know of the progress!
 276
 277 Contribute!
 278 -----------
 279 Code, examples, documentation, bug reports, testing are all appreciated.
 280 Read the TODO or the ask on the mailing lists for ways to contribute.