diff --git a/INSTALL b/INSTALL index 004323c7..d7c6e208 100644 --- a/INSTALL +++ b/INSTALL @@ -10,6 +10,22 @@ together with object code resulting from the compiling of publicly available source code, may be exported from the United States under License Exception TSU prsuant to 15 C.F.R Section 740.13(e). +--------------------------------- +* Platforms Built and Tested On * +--------------------------------- +Corosync has been tested on: +Linux: Fedora 11, Debian Lenny, Red Hat Enterprise Linux 5 +Solaris: version 10 CSW +BSD: FreeBSD and OpenBSD +MacOSX: Darwin latest update + +It should build and run properly on the tested platforms as well as possibly +others with minimal effort. Corosync requires a coherent mmap() system call +and will not operate on platforms which don't support coherent mmap(). + +Corosync has been tested with recent gcc compilers and Intel's C compiler. +SunStudio compilers fail to build with various internal compiler errors. + ---------------------------- * Building from subversion * ---------------------------- @@ -46,6 +62,29 @@ Step 2: Install the binaries balance:~/corosync/trunk% su balance:~/corosync/trunk# make install +------------------------------- +* A notice about dependencies * +------------------------------- +We have strived very hard to avoid dependencies as much as possible, and in +fact corosync can be compiled without any dependencies. The one optional +dependency corosync has today is the nss package when built with support for +nss encryption. NSS encryption performs more poorly then the default +encryption, but may be a good choice if your organization has policies +regarding encryption technology requiring the use of a common cryptographic +library such as Netscape Security Services. + +To enable nss during building: +balance:~/corosync/trunk% ./configure --enable-nss + +To disable nss during buildling: +balance:~/corosync/trunk% ./configure --disable-nss + +The nss packages required to build corosync with nss support can usually be +found by installing the "nss-devel" and "nspr-devel" packages for your +distribution. Note nss is enabled by default, so if you don't want nss support +or don't want to install nss devel packages, make sure to set the appropriate +configure option as described above. + ------------------------ * Configuring Corosync * ------------------------ @@ -100,22 +139,6 @@ or unpredictable results may occur. Do not use DOS style termination. This breaks the parser. -Configure Host --------------- -For security reasons, corosync only allows a process that had the EGID/GID -of "ais" to connect to it. To make development easier, it is recommended to -create an "ais" user with the "ais" group. - -[root@balance root]# adduser ais -g ais - -Set the ais user's password: - -[root@balance root]# passwd ais -Changing password for user ais. -New password: -Retype new password: -passwd: all authentication tokens updated successfully. - Generate a private key ---------------------- corosync uses cryptographic techniques to ensure authenticity and privacy of @@ -124,7 +147,7 @@ correct operation. First generate the key on one of the nodes: -unix# exec/keygen +balance# corosync-keygen Corosync Authentication key generator. Gathering 1024 bits for key from /dev/random. Writing corosync key to /etc/ais/authkey. @@ -137,14 +160,13 @@ with nonmatching private keys will not be able to join the same configuration. Copy the key to some 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/ais/authkey +balance# install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/ais/authkey If the message invalid digest appears, the keys are not the same on each node. Run the corosync executive ------------------------- -Get one or more nodes and run the corosync executive on each node. A list of -node IPs should be logged when the nodes join a configuration. Run the +Get one or more nodes and run the corosync executive on each node. Run the corosync daemon after following the previous directions. The daemon must be run as UID 0(root). @@ -153,21 +175,27 @@ and the techniques corosync use to overcome these threats. Before running any of the test programs --------------------------------------- -The corosync executive will ensure security by only allowing the ais group (or -uid root) to connect to the service. Switch to the ais group before -running any applications linked to the ais apis, or the applications will -not be authenticated and won't be able to access services. +The corosync executive will ensure security by only allowing the UID 0(root) or +GID 0(root) to connect to it. To allow other users to access the corosync +executive, create a directory called /etc/corosync/uidgid.d and place a file in +it named in some way that is identifiable to you. All files in this directory +will be scanned and their contents added to the allowed uid gid database. The +contents of this file should be +uidgid { + uid: username + gid: groupname +} -[sdake@balance sdake]$ su ais -Password: -[ais@balance sdake]$ id -uid=501(ais) gid=502(ais) groups=502(ais) +Please note that these users then have full ability to transmit and receive +messages in the cluster and are not bound by the threat model described in +SECURITY. Try out the corosync cpg functionality -------------------------------------- After corosync is running -su to ais user - Run test/testcpg on multiple nodes or on the same node. Messages can be typed which will then be sent to other testcpg applications in the cluster. + +To see a hashed verified output of data on all nodes, test/cpgverify can be +run.