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 ---------------------
   7 * Building from git *
   8 ---------------------
   9 When building and installing from git, autoconf 2.61, automake 1.11,
  10 libtool 2.2.6 and pkgconfig 0.23  (or later versions) are required.
  11 Prior versions may result in build failures.
  12
  13 Step 1: check out a read only copy of the repository
  14 git clone git://github.com/corosync/corosync.git
  15
  16 Find the version you want to build.  Usually this will be the "master" version.
  17 If you want to build a specific released version, use git checkout VERSION.
  18
  19 Step 2: Generate the makefiles
  20 balance:~/corosync% ./autogen.sh
  21
  22 Step 3: Run the configure script
  23 balance:~/corosync% ./configure
  24
  25 Step 4: Install the binaries
  26 balance:~/corosync% su
  27 balance:~/corosync# make install
  28
  29 -------------------------
  30 * Building from tarball *
  31 -------------------------
  32 The tarball is distributed with pregenerated makefiles.  There is no need
  33 to run the autogen.sh script in this case.
  34
  35 Step 1: Run the configure script
  36 balance:~/corosync% ./configure
  37
  38 Step 2: Install the binaries
  39 balance:~/corosync% su
  40 balance:~/corosync# make install
  41
  42 -------------------------------
  43 * A notice about dependencies *
  44 -------------------------------
  45 We have strived very hard to avoid dependencies as much as possible, but there
  46 are two required libraries: LibQB and NSS.
  47
  48 Optional dependencies are support for DBUS, SNMP and libstatgrab.
  49
  50 The nss packages required to build corosync can usually be found by
  51 installing the "nss-devel" and "nspr-devel" packages (names may vary, please use
  52 distribution's package manager). Also don't forget to install pkgconfig.
  53
  54 -----------------------------------------
  55 * Building with SNMP/DBUS support *
  56 -----------------------------------------
  57
  58 You can get SNMP traps on the following corosync events:
  59 1) node joine/leave
  60 2) application connect/dissconnect from corosync
  61 3) quorum gain/lost
  62
  63 There are 2 modes of achieving this DBUS + foghorn and snmp-agentx.
  64
  65 Setting up to get dbus events.
  66 ------------------------------
  67 foghorn (http://git.fedorahosted.org/git/foghorn.git) converts
  68 dbus signals into snmp traps. So install foghorn.
  69
  70 $ ./configure --enable-dbus
  71 $ make && sudo make install
  72 $ /etc/init.d/corosync start
  73 $ echo "OPTIONS=\"-d\"" > /etc/sysconfig/corosync-notifyd
  74 $ /etc/init.d/corosync-notifyd start
  75 Start foghorn
  76
  77 to see the dbus signals getting sent try:
  78 $ dbus-monitor --system
  79
  80 Setting up snmp-agentx.
  81 -----------------------
  82 If you don't want to use dbus then you can use snmp-agentx.
  83
  84 $ ./configure --enable-snmp
  85 $ make && sudo make install
  86 $ /etc/init.d/corosync start
  87 $ vim /etc/snmp/snmptrapd.conf
  88
  89 Add the following:
  90 authCommunity   log,execute,net public
  91 $ /etc/init.d/snmptrapd start
  92 $ echo "OPTIONS=\"-s\"" > /etc/sysconfig/corosync-notifyd
  93 $ /etc/init.d/corosync-notifyd start
  94
  95 I start up wireshark to see if there are any snmp traps been sent
  96 as I am too lazy to setup a manager to receive traps.
  97
  98 run a program that talks to corosync e.g.
  99 $ corosync-cmapctl
 100
 101 And you should get traps
 102
 103
 104 ------------------------
 105 * Configuring Corosync *
 106 ------------------------
 107 The corosync executive will automatically determine cluster membership by
 108 communicating on a specified multicast address and port.
 109
 110 The directory conf contains the file corosync.conf.example
 111
 112 # Please read the corosync.conf.5 manual page
 113 totem {
 114         version: 2
 115         secauth: off
 116         threads: 0
 117         interface {
 118                 ringnumber: 0
 119                 bindnetaddr: 192.168.1.1
 120                 mcastaddr: 226.94.1.1
 121                 mcastport: 5405
 122         }
 123 }
 124
 125 logging {
 126         fileline: off
 127         to_stderr: yes
 128         to_file: yes
 129         to_syslog: yes
 130         logfile: /tmp/corosync.log
 131         debug: off
 132         timestamp: on
 133 }
 134
 135 The totem section contains three values.  All three values must be set
 136 or the corosync executive wll exit with an error.
 137
 138 bindnetaddr specifies the address which the corosync Executive should bind to.
 139 This address should always end in zero.  If the local interface taffic
 140 should routed over is 192.168.5.92, set bindnetaddr to 192.168.5.0.
 141
 142 mcastaddr is a multicast address.  The default should work but you may have
 143 a different network configuration.  Avoid 224.x.x.x because this is a "config"
 144 multicast address.
 145
 146 mcastport specifies the UDP port number.  It is possible to use the same
 147 multicast address on a network with the corosync services configured for
 148 different UDP ports.
 149
 150 The timeout section contains seven values.  This section is not normally used,
 151 but rather used to override the program defaults for the purposes of fine
 152 tuning for a given networking/processor combination or for debugging purposes.
 153 Be careful to use the same timeout values on each of the nodes in the cluster
 154 or unpredictable results may occur.
 155
 156 Generate a private key
 157 ----------------------
 158 corosync uses cryptographic techniques to ensure authenticity and privacy of
 159 messages.  A private key must be generated and shared by all processors for
 160 correct operation.
 161
 162 First generate the key on one of the nodes:
 163
 164 balance# corosync-keygen
 165 Corosync Authentication key generator.
 166 Gathering 1024 bits for key from /dev/random.
 167 Writing corosync key to /etc/corosync/authkey.
 168
 169 After this is complete, a private key will be in the file /etc/corosync/authkey.
 170 This private key must be copied to every processor that will be a member of
 171 the cluster.  If the private key isn't the same for every node, those nodes
 172 with nonmatching private keys will not be able to join the same configuration.
 173
 174 Copy the key to some transportable storage or use ssh to transmit the key
 175 from node to node.  Then install the key with the command:
 176
 177 balance# install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/corosync/authkey
 178
 179 If the message invalid digest appears, the keys are not the same on each node.
 180
 181 Run the corosync executive
 182 -------------------------
 183 Get one or more nodes and run the corosync executive on each node.  Run the
 184 corosync daemon after following the previous directions.  The daemon must be
 185 run as UID 0(root).
 186
 187 Before running any of the test programs
 188 ---------------------------------------
 189 The corosync executive will ensure security by only allowing the UID 0(root) or
 190 GID 0(root) to connect to it.  To allow other users to access the corosync
 191 executive, create a directory called /etc/corosync/uidgid.d and place a file in
 192 it named in some way that is identifiable to you.  All files in this directory
 193 will be scanned and their contents added to the allowed uid gid database.  The
 194 contents of this file should be
 195 uidgid {
 196         uid: username
 197         gid: groupname
 198 }
 199
 200 Please note that these users then have full ability to transmit and receive
 201 messages in the cluster.
 202
 203 Try out the corosync cpg functionality
 204 --------------------------------------
 205 After corosync is running
 206
 207 Run test/testcpg on multiple nodes or on the same node.  Messages can be typed
 208 which will then be sent to other testcpg applications in the cluster.
 209
 210 To see a hashed verified output of data on all nodes, test/cpgverify can be
 211 run.