Provided by: corosync_2.3.5-3ubuntu1_i386 bug

NAME

       corosync_overview - Corosync overview

OVERVIEW

       The corosync project's purpose is to implement and support a production
       quality Revised BSD licensed implementation of a high  performance  low
       overhead high availability development toolkit.

       Faults occur for various reasons:

       * Application Faults

       * Middleware Faults

       * Operating System Faults

       * 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  Corosync.   Corosync  is  designed for applications to
       replicate their state to up  to  16  processors.   The  processors  all
       contain a replica of the application state.

       The  corosync  project  provides  a  group message API called CPG.  The
       project developers recommend CPG be used for  most  applications.   The
       CPG  service  implements  a  closed  group  messaging  model presenting
       extended virtual synchrony guarantees.

       To manage conditions where the process executing  the  CPG  application
       exchange  fails,  we  provide  the Simple Availability Manager (sam) to
       provide simple application restart.

QUICKSTART

       The corosync executive must be configured.  In the  directory  conf  in
       the  source  distribution  are several files that must be copied to the
       /etc/corosync directory.  If corosync is packaged by a distro, this may
       be complete.

       The  directory  contains  the  file  corosync.conf.   Please  read  the
       corosync.conf(5) man page for details  on  the  configuration  options.
       The  corosync  project  will  work  out  of  the  box  with the default
       configuration options, although the administrator may desire  different
       options.

       The   corosync   executive  uses  cryptographic  techniques  to  ensure
       authenticity and privacy of the messages.  In order for corosync 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# corosync-keygen
       Corosync Cluster Engine Authentication key generator.
       Gathering 1024 bits for key from /dev/random.
       Press keys on your keyboard to generate entropy.
       Writing corosync key to /etc/corosync/authkey.

       After  this  operation,  a  private   key   will   be   in   the   file
       /etc/corosync/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/corosync/authkey

       If  a message "Invalid digest" appears from the corosync executive, the
       keys are not consistent between processors.

       Finally run the corosync executive.  If corosync  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  corosync  must  be
       enabled.

USING LIBRARIES

       The  corosync libraries have header files which must be included in the
       developer's  application.   Once  the  header  file  is  included,  the
       developer can reference the corosync interfaces.

       The  corosync  project  recommends to distros to place include files in
       /usr/include/corosync.

IPv6

       The corosync project supports both IPv4  and  IPv6  network  addresses.
       The  entire  cluster  must  use  either  IPv4  or  IPv6 for the cluster
       communication mechanism.  In order to use IPv6, IPv6 addresses must  be
       specified  in the bindnetaddr and mcastaddr fields in the configuration
       file.  The nodeid field must also be set.

       An example of this is: nodeid: 2 bindnetaddr:  fec0::1:a800:4ff:fe00:20
       mcastaddr: ff05::1

       To  configure  a  host  for  IPv6,  use  the  ifconfig  program  to add
       interfaces: box20: ifconfig eth0 add fec0::1:a800:4ff:fe00:20/64 box30:
       ifconfig eth0 add fec0::1:a800:4ff:fe00:30/64

       If  the  /64 is not specified, a route for the IPv6 network will not be
       configured which will cause significant problems.  Make sure a route is
       available for IPv6 traffic.

ARCHITECTURE

       The  corosync  libraries  are  a  thin  IPC  interface  to the corosync
       executive.  The corosync executive implements the functionality of  the
       corosync APIs for distributed coming.

       The  corosync  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.

ENVIRONMENT VARIABLES

       The  corosync  executive process uses four environment variables during
       startup.  If these environment variables are not set, defaults will  be
       used.

       COROSYNC_MAIN_CONFIG_FILE
              This   specifies  the  fully  qualified  path  to  the  corosync
              configuration file.

              The default is /etc/corosync/corosync.conf.

       COROSYNC_TOTEM_AUTHKEY_FILE
              This specifies the fully qualified path to the shared  key  used
              to authenticate and encrypt data used within the Totem protocol.

              The default is /etc/corosync/authkey.

SECURITY

       The  corosync  executive optionally encrypts all messages sent over the
       network using the AES-128 cipher.  The corosync executive uses HMAC and
       SHA1 to authenticate all messages.  The corosync executive library uses
       NSS as a pseudo random number generator.

       If membership messages can be captured by intruders, it is possible  to
       execute  a  denial of service attack on the cluster.  In this scenario,
       the cluster is likely already compromised and a DOS attack is the least
       of the administration's worries.

       The security in corosync does not offer perfect forward secrecy because
       the keys are reused.  It may be possible for an intruder  by  capturing
       packets  in  an automated fashion to determine the shared key.  No such
       automated attack has been published as of yet.  In this  scenario,  the
       cluster is likely already compromised to allow the long-term capture of
       transmitted data.

       For security reasons, the corosync executive  binary  should  NEVER  be
       setuid or setgid in the filesystem.

BUGS

       None that are known.

SEE ALSO

       corosync.conf(5), corosync-keygen(8), cpg_overview(8), sam_overview(8)