INSTALL

   1 ----------------------------------------------
   2 The Corosync Cluster Engine Installation Guide
   3 ----------------------------------------------
   4 Please read LICENSE for a description of the licensing of this software.
   5
   6 All cryptographic software in this package is subject to the following legal
   7 notice:
   8 This package includes publicly available encryption source code which,
   9 together with object code resulting from the compiling of publicly
  10 available source code, may be exported from the United States under License
  11 Exception TSU prsuant to 15 C.F.R Section 740.13(e).
  12
  13 ---------------------------------
  14 * Platforms Built and Tested On *
  15 ---------------------------------
  16 Corosync has been tested on:
  17 Linux: Fedora 11, Fedora 12 (rawhide), Debian Lenny, Debian Unstable,
  18        Ubuntu Hardy, Red Hat Enterprise Linux 5
  19 Solaris: version 10 CSW
  20 BSD: FreeBSD and OpenBSD
  21 MacOSX: Darwin latest update
  22
  23 It should build and run properly on the tested platforms as well as possibly
  24 others with minimal effort.  Corosync requires a coherent mmap() system call
  25 and will not operate on platforms which don't support coherent mmap().
  26
  27 Corosync has been tested with recent gcc compilers and Intel's C compiler.
  28 SunStudio compilers fail to build with various internal compiler errors.
  29
  30 ----------------------------
  31 * Building from subversion *
  32 ----------------------------
  33 When building and installing from subversion, automake 2.61 or later is
  34 required.  Prior versions will result in build failures.
  35
  36 Step 1: check out a read only copy of the repository
  37 svn checkout http://svn.fedoraprojects.org/svn/corosync
  38
  39 Find the version you want to build.  Usually this will be the "trunk" version
  40 located in the trunk directory.  If you want to build a specific released
  41 version check in the tags directory.
  42
  43 Step 2: Generate the makefiles
  44 balance:~/corosync/trunk% ./autogen.sh
  45
  46 Step 3: Run the configure script
  47 balance:~/corosync/trunk% ./configure
  48
  49 Step 4: Install the binaries
  50 balance:~/corosync/trunk% su
  51 balance:~/corosync/trunk# make install
  52
  53 -------------------------
  54 * Building from tarball *
  55 -------------------------
  56 The tarball is distributed with pregenerated makefiles.  There is no need
  57 to run the autogen.sh script in this case.
  58
  59 Step 1: Run the configure script
  60 balance:~/corosync/trunk% ./configure
  61
  62 Step 2: Install the binaries
  63 balance:~/corosync/trunk% su
  64 balance:~/corosync/trunk# make install
  65
  66 -------------------------------
  67 * A notice about dependencies *
  68 -------------------------------
  69 We have strived very hard to avoid dependencies as much as possible, and in
  70 fact corosync can be compiled without any dependencies.
  71
  72 Optional dependencies are support for NSS and support for Infiniband RDMA.
  73
  74 NSS encryption performs more poorly then the default encryption, but may be
  75  a good choice if your organization has policies regarding encryption technology
  76 requiring the use of a common cryptographic library such as Netscape Security Services.
  77
  78 To enable nss during building:
  79 balance:~/corosync/trunk% ./configure --enable-nss
  80
  81 To disable nss during buildling:
  82 balance:~/corosync/trunk% ./configure --disable-nss
  83
  84 The nss packages required to build corosync with nss support can usually be
  85 found by installing the "nss-devel" and "nspr-devel" packages for your
  86 distribution.  Note nss is enabled by default, so if you don't want nss support
  87 or don't want to install nss devel packages, make sure to set the appropriate
  88 configure option as described above.
  89
  90 -----------------------------------------
  91 * Building with Infiniband RDMA support *
  92 -----------------------------------------
  93 Infiniband RDMA build support is disabled by default.  To enable rdma during
  94 building:
  95 balance:~/corosync/trunk% ./configure --enable-rdma
  96
  97 Infiniband rdma support requires the libibverbs and librdmacm packages (and
  98 their -devel counterparts).  Corosync requires the use of pkgconfig in these
  99 packages.  The Corosync maintainers have sent patches for this feature upstream
 100 to the Infiniband maintainers.
 101
 102 If your version of these packages don't have pkgconfig support, you will see an
 103 error during configure such as:
 104
 105 checking for ibverbs... configure: error: Package requirements (ibverbs) were not met:
 106
 107 No package 'ibverbs' found
 108
 109 Consider adjusting the PKG_CONFIG_PATH environment variable if you
 110 installed software in a non-standard prefix.
 111
 112 Alternatively, you may set the environment variables ibverbs_CFLAGS
 113 and ibverbs_LIBS to avoid the need to call pkg-config.
 114 See the pkg-config man page for more details.
 115
 116 ** Follow the directions:
 117 balance:~/corosync/trunk% export ibverbs_CFLAGS=-I/usr/include/infiniband
 118 balance:~/corosync/trunk% export ibverbs_LIBS=-libverbs
 119 balance:~/corosync/trunk% export rdmacm_CFLAGS=-I/usr/include/rdma
 120 balance:~/corosync/trunk% export rdmacm_LIBS=-lrdmacm
 121 balance:~/corosync/trunk% ./configure --enable-rdma
 122
 123 Hopefully pkgconfig support is added in your distribution's version of
 124 libibverbs and librdmacm soon if you run into this problem.
 125
 126 -----------------------------------------
 127 * Building with SNMP/DBUS support *
 128 -----------------------------------------
 129
 130 You can get SNMP traps on the following corosync events:
 131 1) node joine/leave
 132 2) application connect/dissconnect from corosync
 133 3) quorum gain/lost
 134
 135 There are 2 modes of achieving this DBUS + foghorn and snmp-agentx.
 136
 137 Setting up to get dbus events.
 138 ------------------------------
 139 foghorn (http://git.fedorahosted.org/git/foghorn.git) converts
 140 dbus signals into snmp traps. So install foghorn.
 141
 142 $ ./configure --enable-dbus
 143 $ make && sudo make install
 144 $ /etc/init.d/corosync start
 145 $ echo "OPTIONS=\"-d\"" > /etc/sysconfig/corosync-notifyd
 146 $ /etc/init.d/corosync-notifyd start
 147 Start foghorn
 148
 149 to see the dbus signals getting sent try:
 150 $ dbus-monitor --system
 151
 152 Setting up snmp-agentx.
 153 -----------------------
 154 If you don't want to use dbus then you can use snmp-agentx.
 155
 156 $ ./configure --enable-snmp
 157 $ make && sudo make install
 158 $ /etc/init.d/corosync start
 159 $ vim /etc/snmp/snmptrapd.conf
 160
 161 Add the following:
 162 authCommunity   log,execute,net public
 163 $ /etc/init.d/snmptrapd start
 164 $ echo "OPTIONS=\"-s\"" > /etc/sysconfig/corosync-notifyd
 165 $ /etc/init.d/corosync-notifyd start
 166
 167 I start up wireshark to see if there are any snmp traps been sent
 168 as I am too lazy to setup a manager to receive traps.
 169
 170 run a program that talks to corosync e.g.
 171 $ corosync-cmapctl
 172
 173 And you should get traps
 174
 175
 176 ------------------------
 177 * Configuring Corosync *
 178 ------------------------
 179 The corosync executive will automatically determine cluster membership by
 180 communicating on a specified multicast address and port.
 181
 182 The directory conf contains the file corosync.conf.example
 183
 184 # Please read the corosync.conf.5 manual page
 185 totem {
 186         version: 2
 187         secauth: off
 188         threads: 0
 189         interface {
 190                 ringnumber: 0
 191                 bindnetaddr: 192.168.1.1
 192                 mcastaddr: 226.94.1.1
 193                 mcastport: 5405
 194         }
 195 }
 196
 197 logging {
 198         fileline: off
 199         to_stderr: yes
 200         to_file: yes
 201         to_syslog: yes
 202         logfile: /tmp/corosync.log
 203         debug: off
 204         timestamp: on
 205 }
 206
 207 The totem section contains three values.  All three values must be set
 208 or the corosync executive wll exit with an error.
 209
 210 bindnetaddr specifies the address which the corosync Executive should bind to.
 211 This address should always end in zero.  If the local interface taffic
 212 should routed over is 192.168.5.92, set bindnetaddr to 192.168.5.0.
 213
 214 mcastaddr is a multicast address.  The default should work but you may have
 215 a different network configuration.  Avoid 224.x.x.x because this is a "config"
 216 multicast address.
 217
 218 mcastport specifies the UDP port number.  It is possible to use the same
 219 multicast address on a network with the corosync services configured for
 220 different UDP ports.
 221
 222 The timeout section contains seven values.  This section is not normally used,
 223 but rather used to override the program defaults for the purposes of fine
 224 tuning for a given networking/processor combination or for debugging purposes.
 225 Be careful to use the same timeout values on each of the nodes in the cluster
 226 or unpredictable results may occur.
 227
 228 Do not use DOS style termination.  This breaks the parser.
 229
 230 Generate a private key
 231 ----------------------
 232 corosync uses cryptographic techniques to ensure authenticity and privacy of
 233 messages.  A private key must be generated and shared by all processors for
 234 correct operation.
 235
 236 First generate the key on one of the nodes:
 237
 238 balance# corosync-keygen
 239 Corosync Authentication key generator.
 240 Gathering 1024 bits for key from /dev/random.
 241 Writing corosync key to /etc/corosync/authkey.
 242
 243 After this is complete, a private key will be in the file /etc/corosync/authkey.
 244 This private key must be copied to every processor that will be a member of
 245 the cluster.  If the private key isn't the same for every node, those nodes
 246 with nonmatching private keys will not be able to join the same configuration.
 247
 248 Copy the key to some transportable storage or use ssh to transmit the key
 249 from node to node.  Then install the key with the command:
 250
 251 balance# install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/corosync/authkey
 252
 253 If the message invalid digest appears, the keys are not the same on each node.
 254
 255 Run the corosync executive
 256 -------------------------
 257 Get one or more nodes and run the corosync executive on each node.  Run the
 258 corosync daemon after following the previous directions.  The daemon must be
 259 run as UID 0(root).
 260
 261 please read SECURITY to understand the threat model assumed by corosync
 262 and the techniques corosync use to overcome these threats.
 263
 264 Before running any of the test programs
 265 ---------------------------------------
 266 The corosync executive will ensure security by only allowing the UID 0(root) or
 267 GID 0(root) to connect to it.  To allow other users to access the corosync
 268 executive, create a directory called /etc/corosync/uidgid.d and place a file in
 269 it named in some way that is identifiable to you.  All files in this directory
 270 will be scanned and their contents added to the allowed uid gid database.  The
 271 contents of this file should be
 272 uidgid {
 273         uid: username
 274         gid: groupname
 275 }
 276
 277 Please note that these users then have full ability to transmit and receive
 278 messages in the cluster and are not bound by the threat model described in
 279 SECURITY.
 280
 281 Try out the corosync cpg functionality
 282 --------------------------------------
 283 After corosync is running
 284
 285 Run test/testcpg on multiple nodes or on the same node.  Messages can be typed
 286 which will then be sent to other testcpg applications in the cluster.
 287
 288 To see a hashed verified output of data on all nodes, test/cpgverify can be
 289 run.