=========== /etc/Cluster.ini ================

This file describes all the "customer facing" 
machines in the cluster. This will be at most
two machines.

The initial conversion from the old way of 
provisioning to this way is done by 
build_ini.pl in the OPS package
SatSystem-config - see Kerry if there
are problems with conversion.


***** File structure

/etc/Cluster.ini is a text file containing
lines - it does not have provisions for comments.


Example of a complete file that describes one node
with no VIPs:

---------- cut here ---------------
PhysNode.1.IpAddr.1.addr=172.16.101.223
PhysNode.1.IpAddr.1.dev=eth0
PhysNode.1.IpAddr.1.gate=172.16.0.1
PhysNode.1.IpAddr.1.mask=16
PhysNode.1.PrivateIpAddr.0.dev=lo
nameservers=192.168.0.201 192.168.1.201
nssearchpath=lab.nocpulse.net nocpulse.net
smonaddr=172.16.100.23
smontestaddr=172.16.100.23
sshaddr=0.0.0.0
sshmask=0.0.0.0
smonfqdn=smon.dev.nocpulse.net
smontestfqdn=smon.dev.nocpulse.net
sshfqdn=smon.dev.nocpulse.net
haFailoverEnabled=0
---------- cut here ---------------

Here's an example of a two node cluster
with ha failover enabled (using a VIP):

---------- cut here ---------------
PhysNode.1.IpAddr.1.addr=172.16.101.223
PhysNode.1.IpAddr.1.dev=eth0
PhysNode.1.IpAddr.1.gate=172.16.0.1
PhysNode.1.IpAddr.1.mask=16
PhysNode.1.PrivateIpAddr.0.dev=eth2
PhysNode.2.IpAddr.1.addr=172.16.101.224
PhysNode.2.IpAddr.1.dev=eth0
PhysNode.2.IpAddr.1.gate=172.16.0.1
PhysNode.2.IpAddr.1.mask=16
PhysNode.2.PrivateIpAddr.0.dev=eth2
VIP.1.addr=172.16.101.225
VIP.1.dev=eth0
VIP.1.gate=172.16.0.1
VIP.1.mask=16
VIP.1.network=172.16.0.0
nameservers=192.168.0.201 192.168.1.201
nssearchpath=lab.nocpulse.net nocpulse.net
smonaddr=172.16.100.23
smontestaddr=172.16.100.23
sshaddr=0.0.0.0
sshmask=0.0.0.0
smonfqdn=smon.dev.nocpulse.net
smontestfqdn=smon.dev.nocpulse.net
sshfqdn=smon.dev.nocpulse.net
haFailoverEnabled=1
---------- cut here ---------------

Lines take the general form:

<name>=<value>[ <value> [<value>]]...

Where <name> describes the name of a variable
within a context.  Thus, names are constructed as:

[<context>.]<varname>

<context> is optional - if it is missing it applies to
the entire cluster.

Where context is specified, it takes the form:

<entity>.<id#>[.<entity>.<id#>[.<entity>.<id#>]]...

such that a fully qualified name in a context 
would look like this:

Thing.1.component.2.color

...which translates to "The color of the second
component of the first Thing".


***** Sections within the file

Cluster.ini consists of four "sections", two
of which are required:

Cluster globals (required)
Node/real definitions (required)
VIP definitions (optional)
"Off-net route" definitions (optional)

The sections are constructed as follows:


*** Cluster globals

haFailoverEnabled: Either 1 or 0.  If 1, 
nodes 1 and 2 will run ClusterLeader under
Heartbeat.

nameservers: this is a space-delimited list
of name server IP addresses that the cluster
should defer to for name resolution.

Example: 
nameservers=192.168.0.201 192.168.1.201


nssearchpath: this is a space delimited list
of domain names that the cluster should 
search before declaring a name unresolved
in a DNS lookup.

Example:
nssearchpath=lab.nocpulse.net nocpulse.net


smonaddr: this is the IP address of the  NOCpulse
machine/vip/whatever that MOC traffic (all
dequeued data, sput lite polling, etc) will 
go to.

Example: 
smonaddr=172.16.100.23

smontestaddr: this is the IP address of the NOCpulse
machine/vip/whatever that secondary https traffic
(spread bridge data, connects on port 443 to detect a network failure
(after which the ppp dialup daemon would take over communication
to the MOC)) etc. occur.

Example:
smontestaddr=172.16.100.23


sshaddr: the address from which ssh connections should
be allowed to come in from.

Example:
sshaddr=0.0.0.0


sshmask: the network mask for sshaddr (above). *IMPORTANT*: in 
stage and prod this should always be 255.255.255.255 and the
sshaddr should always be a host (not network) IP.

Example:
sshmask=0.0.0.0


otherHosts: a list of host entries to build into the hosts file. 
These might include customer host names, etc.  It takes this form:
<ip> <hostname>[,<hostname>[,<hostname>]] <ip> <hostname> etc.

Example:

otherHosts=129.101.22.200 jibe01b.nocpulse.com  1.2.3.4 me,me.com


ntpServers: a list of ip addresses from which NTP (network time
protocol) synchronization should occur.

Example: 

ntpServers=1.2.3.4 5.6.7.8


*** Node/"real" definitions

Nodes, and their subtending "real" ip's are 
described in this section with context style
names as described above.  

Note that there must be at least one PhysNode
with at least one IpAddr and at least
one PrivateIpAddr defined here.

Note also that each node in the cluster must
have a PhysNode.x.PrivateIpAddr.0.dev entry.

PhysNode.x.IpAddr.y.addr: This is an ip address
that will present on the customer network as a 
"real" address (non-vip).  It (x) is specifically
tied to a particular node (either 1 or 2).

Example:
PhysNode.1.IpAddr.1.addr=172.16.101.223


PhysNode.x.IpAddr.y.dev: This is the device
on which PhysNode.x.IpAddr.y.addr should reside.

Example:
PhysNode.1.IpAddr.1.dev=eth0


PhysNode.x.IpAddr.y.mask: This is the network
mask (CIDR or "slash notation") for PhysNode.x.IpAddr.y.addr
on interface PhysNode.x.IpAddr.y.dev.

Example:
PhysNode.1.IpAddr.1.mask=16

PhysNode.x.IpAddr.y.gate: This is the default
gateway for the *node* - there MUST be ONLY
one of these defined for the entire node.  It is
bound through whatever interface it's defined for.

Example:
PhysNode.1.IpAddr.1.gate=172.16.0.1

PhysNode.x.IpAddr.y.speed: This optional parameter
provides for an override of auto-negotiated link speed.
Note that you only need to specify this once for a given
device (even if you're assigning multiple IPs to the device).

If provided, it must be one of: 

100baseT4, 100baseTx, 100baseTx-FD,
100baseTx-HD, 10baseT, 10baseT-FD, 10baseT-HD

Example:
PhysNode.1.IpAddr.1.speed=100baseTx


PhysNode.x.PrivateIpAddr.0.dev: This must be
defined for each node.  The PrivateIpAddr's 
id must always be zero (0).  This names the
device on which the private network is to 
live.  It can be "lo" - if it is, extra
logic kicks in to ensure that we don't break
the loopback interface.

Examples:
PhysNode.1.PrivateIpAddr.0.dev=lo
PhysNode.1.PrivateIpAddr.0.dev=eth1

*** VIP definitions

VIP definitions only apply to configurations where
HA is being used.  If HA is being used, at least 
one VIP must be defined.

VIPs take the same form as Node/real IP definitions
with the exeption that the PhysNode context is dropped,
and the IpAddr context is replaced with VIP, thus:

VIP.1.addr=172.16.101.223

As with real ips, there must be one and only one
"gate" definition supplied.

VIPs have an additional variable that must be set
that defines the route to the network the VIP is
present on. It takes the form:

VIP.x.network=a.b.c.d

where a.b.c.d is the network number/address in question
(the network part of the IP address assigned to the VIP).

Example:
VIP.1.network=172.16.0.0

*** "Off-net route" definitions

"Off-net" routes are routes to customer networks other
than the one(s) that the box is directly connected to.
You can define zero or more of this as follows:

OffNetRoute.x.net: The address of the network to which
the route connects

Example:
OffNetRoute.1.net=127.0.0.0

OffNetRoute.x.mask: The netmask for the net

Example:
OffNetRoute.1.mask=8


OffNetRoute.x.dev: The device to which the route
is bound

Example:
OffNetRoute.1.dev=eth0


OffNetRoute.x.gate: The IP address of the gatway to
use to get to the network.

Example:
OffNetRoute.1.gate=192.168.0.1


OffNetRoute.x.vip: The numeric ID of the VIP through
which traffic to this network should be sourced.  This
is required only if the cluster will be running in 
HA mode  with VIPs defined.

Example:
OffNetRoute.1.vip=1

