COROSYNC_OVERVIEW(8)				    Corosync Cluster Engine Programmer's Manual 			      COROSYNC_OVERVIEW(8)

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 con-
       tain 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 com-
       mand:

       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 commu-
       nication  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 charac-
       teristics 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 sce-
       nario, 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 captur-
       ing 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)

corosync Man Page						    2012-02-13						      COROSYNC_OVERVIEW(8)