Tribblix: manual page: corosync

COROSYNC_OVERVIEW(8) Corosync Cluster Engine Programmer's Manual

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.