# $Id$


RSFmon is controlled by a number of files in the /opt/HAC/RSF-1/etc directory.
These are:

1) /opt/HAC/RSF-1/etc/access	For filtering out client requests by IP address
2) /opt/HAC/RSF-1/etc/passwd	For authorising users issuing client requests
3) /opt/HAC/RSF-1/etc/config	Defines the hosts & services in the cluster
4) /opt/HAC/RSF-1/etc/license.<ID>  Holds the license key for the given host ID
5) /opt/HAC/RSF-1/etc/.rsfrelease   Alternative version string to report
6) /etc/services		Holds the RSF heartbeat & control service ports

RSF also maintains a number files containing internal state information.
These should not normally be of interest, but for completeness they are:

7) /etc/rsfmon.pid
8) /opt/HAC/RSF-1/etc/<machine>.<service>



1) /opt/HAC/RSF-1/etc/access	Client access control by IP address

   If this file does not exist or can't be read, all connections are
   permitted, for compatibility with earlier versions.

   NB. If the file does exist and a host cannot be found in it, access
   will be denied to that host. Thus an empty access file will deny
   access to ALL hosts. Remember to allow access to the local machine
   using the loopback interface, eg. using "ALLOW 127.0.0.1/8" or
   rsfcli will fail with the message:
      "error while identifying server: error transfering data"

   The file is to be maintained manually, using an editor.

   If present, the file should contain lines of the form:

      [ALLOW | DENY] <Hostname or address> ['/'<netbits> | <netmask>] # Comment

   That is
      a) A keyword, "Allow" or "Deny", case is not significant.
      b) A host address specifier; either a hostname or numeric address
      c) A slash & a decimal number counting the network bits to use from (b)
	 OR a netmask specified conventionally as a dotted quad.
      d) An optional comment which starts with a '#' character

   eg. The following lines are all equivalent:

      DENY 193.62.192.131 255.255.255.192
      DENY 193.62.192.128 255.255.255.192	# low bits in 131 are masked out
      DENY 193.62.192.128/26			# 255.255.255.192 is 26 1s+6 0s
      DENY net.bio.net/26			# net.bio.net is 193.62.192.131

   When an incoming call from a client is received, and this file can be read,
   the IP address of the incoming call is matched against each line in turn.
   The scan stops at the first match, and the call is then allowed or denied
   according to the keyword at the start of the line. The most exact matches,
   that is the matches with the smallest range, should therefore appear at the
   start of the file. This can be understood by considering what happens when
   the addresses 1.2.3.4 and 1.2.8.9 is checked using the file

	# We want to deny access to all 1.2.*.* except 1.2.3.*
	ALLOW 1.2.3.0/24   # Matches & allows 1.2.3.4, doesn't match 1.2.8.9
	DENY  1.2.0.0/16   # Matches & denies 1.2.8.9

   If the entries were reversed:

	DENY  1.2.0.0/16   # Matches & denies both 1.2.3.4 and 1.2.8.9
	ALLOW 1.2.3.0/24   # Never reached, the line above always matches first

   Individual hosts can be specified by using a netmask with all bits set, ie.
   255.255.255.255 or /32.

   If an address is looked up which doesn't match any line in the file, access
   is denied. To grant default access to every host in the world, a line with
   a netmask of 0 may be used to match every possible address, ie.

	ALLOW 0.0.0.0/0 # Matches everything.
	# No bits in the address are checked, so the address may be anything



2) /opt/HAC/RSF-1/etc/passwd	Names & passwords required for cluster control.

   Once a network call has been accepted, all information gathering commands
   are allowed. However to change the state of the cluster (Change service
   modes, stop services etc.) a username & password is needed. The list of
   usernames & passwords is kept in this file. The passwords are encrypted in
   this file, and so the rsfpasswd utility is needed to maintain it. Note that
   these usernames & passwords do not need to match those in /etc/passwd.



3) /opt/HAC/RSF-1/etc/config	Defines the hosts & services in the cluster

   This describes the configuration of the entire cluster, and consists
   of definition lines, blank lines & comments. Spaces & tabs may be
   used freely between all elements in a line.

   A definition line consists of a leading keyword (all keyword must be in
   upper case), the parameters for that keyword, and an optional comment.
   Comments start with a hash ('#') and extend to the end of the line.

   The parameters required by each keyword may contain names, strings or
   numbers. Names are alphanumeric, starting with a letter, and followed
   by more letters, digits, dots ('.'), underscores ('_'), or dashes
   ('-'). Numbers are decimal integers. Strings which contain no special
   characters (so that they could be used as names) need not be quoted.
   Any string which contains special characters must be quoted. This is
   frequently needed when specifying a network device, eg. "hme0:1".


   The configuration file contains 3 main sections, which must appear in
   order. The sections are:

   1) A optional "global" section, from the start of the from up to the
      first MACHINE keyword. This defines cluster wide parameters & defaults.

   2) A machines section, from the first MACHINE keyword to the first
      SERVICE keyword. This contains a number of MACHINE definitions,
      which define heartbeats sent by each machine, and can provide some
      default parameter values for all services which can run on that
      machine.

   3) A services section, from the first SERVICE keyword to the end of
      the file. This contains a number of SERVICE definitions, which
      define all the parameters needed for each service in the cluster.

   The global section may contain any of these definitions:

   CLUSTER_NAME	Unnamed_cluster_XXXX # A name to identify the cluster, XXXX=CRC
   POLL_TIME		2	    # Seconds between each new heartbeat
   SCRIPT_TRIES		10	    # How many times to try failing scripts
   SCRIPT_TIMEOUT	900	    # Service script timeout (900s = 15 minutes)
   SYSLOG_FACILITY	LOG_LOCAL0  # Facility code for syslog messages
   OPTION		name=value  # Options to make available to clients,
				    # value is a name, int or quoted string.
   SERIAL		-1	    # Edit serial number for rsfgui config
   DISC_HB_DYNAMIC_OPENS 0	    # Default 3 on AIX, 0 otherwise.
				    # If non-zero, attemps to make to open,
                                    # do I/O, and close the device for
                                    # each heartbeat I/O operation. This is
				    # only needed on AIX, which will not do
				    # real I/O from it's disc cache without it.

   The following items are cluster wide defaults, which may be overridden
   in the individual MACHINE sections.

DIS[CK]_HB_DYNAMIC_OPENS

   DISC_HB_BACKOFF  450,8,32720	# Default disc heartbeat backoff parameters
   REALTIME		1	# Default realtime scheduling level.
   PRIORITY		4	# Default priority boost for rsfmon processes
   NETBEAT_TRANSMITS	2	# Default transmit count for each UDP heartbeat

   Both REALTIME and PRIORITY may be specified, but if REALTIME scheduling
   is selected, the PRIORITY value is not used. If REALTIME scheduling is
   not selected for any reason, (eg. not implemented on this machine, or
   some error), then the PRIORITY value will be used. (The failure to use
   realtime scheduling will be noted in the log).

   The machines section defines the machines which appear in the cluster.
   Each machine is named in a MACHINE definition line, and is followed by
   parameter & heartbeat definitions for that machine. The MACHINE line can
   contain just the name of the machine, or both a name and a host ID. The
   host ID, if given, should be a hexadecimal number, preceded by "0x". If
   the host ID is present, it is used to identify which host this section
   applies to. If the host ID is not present, the MACHINE name is compared
   with the hosts "hostname". In either case the name given on the MACHINE
   line is used by RSF-1 to identify the host. Note that identifying
   machines by host ID allows several hosts in a cluster to have the same
   hostname. This sequence is repeated for each machine in the cluster.
   MACHINE section definitions are:

   MACHINE machine_name [[0xID]	address] # gives this machine's name, &
					 # optionally rsf_hostid & IP address
    REALTIME		1	# Realtime scheduling level. -1 disables
    PRIORITY		4	# (Optional) Priority boot on this machine
    NETBEAT_TRANSMITS	2	# (Optional) Net heartbeat transmit count
    DISC_HB_BACKOFF 450,8,32720	# Disc heartbeat backoff parameters

    # SERIAL, DISC (or DISK), and NET define heartbeats on this machine

    SERIAL remote_machine_name serial_port_string

    DISC   remote_machine_name read_device:read_block, \
			       write_device:write_block[:check_block]
    DISC   remote_machine_name read&write_device_name:read_block: \
			       write_block[:check_block]
    NET	   remote_machine_name	# remote_machine_name is also the address
    NET	   remote_machine_name remote_address_string


   SERVICE  service_name  floating_ip_name  "Service description string"
       INITIMEOUT 65		# Default bootup timeout (optional)
       RUNTIMEOUT 35		# Default normal timeout (optional)
       IPDEVICE	"le0:2"		# Default network interface (optional)
       MOUNT_POINT "mountpoint"	# 1st default mount point to check
       MOUNT_POINT "mountpoint"	# 2nd default mount point to check
     SERVER	machine_name	# 1st choice machine for this service
       INITIMEOUT 65		# Override bootup timeout for this server
       RUNTIMEOUT 35		# Override network interface for this server
       IPDEVICE	"le0:2"		# Override  timeout for this server
       MOUNT_POINT "mountpoint"	# 1st override mount point to check
       MOUNT_POINT "mountpoint"	# 2nd override mount point to check
     SERVER	machine_name	# 2nd choice machine for this service
     SERVER	machine_name	# 3rd choice machine for this service



4) /opt/HAC/RSF-1/etc/license.<ID>  Holds the license key for the given host ID

   This file must be present, and contain a valid license key before rsfmon
   can be used. Note that <ID> is (preferable) the host ID of the machine,
   but may also be the host name. These may appear in the following forms:

     o	The hostname (without domain name) as it is set on the machine,
     o	the hostname in lower case, the hostname in upper case.
     o	The host ID, in hex, with the letters a-f either all upper case or
	all lower case, & with or without leading zeros makeing the ID up to
	8 characters).

   License may also be spelt "licence".

   eg. on a machine HoUnD.domain.name with host ID 0badf1d0, the file may be:

	/opt/HAC/RSF-1/etc/license.HoUnD
	/opt/HAC/RSF-1/etc/license.hound
	/opt/HAC/RSF-1/etc/license.HOUND
	/opt/HAC/RSF-1/etc/license.0badf1d0
	/opt/HAC/RSF-1/etc/license.0BADF1D0
	/opt/HAC/RSF-1/etc/license.badf1d0
	/opt/HAC/RSF-1/etc/license.BADF1D0
	/opt/HAC/RSF-1/etc/licence.HoUnD
	/opt/HAC/RSF-1/etc/licence.hound
	/opt/HAC/RSF-1/etc/licence.HOUND
	/opt/HAC/RSF-1/etc/licence.0badf1d0
	/opt/HAC/RSF-1/etc/licence.0BADF1D0
	/opt/HAC/RSF-1/etc/licence.badf1d0
	/opt/HAC/RSF-1/etc/licence.BADF1D0

   Note that in versions of RSF earlier than version 2.4, only the hostname,
   with any domain name part stripped off, converted to lower case, was valid.
   eg. On machine MyHost.Mydomain.com, the license file name was

	/opt/HAC/RSF-1/etc/license.myhost



5) /opt/HAC/RSF-1/etc/.rsfrelease	Alternative version string to report
   If this file exists, the first line of it is used as the version string
   rsfmon reports when identifying itself.



6) /etc/services		Holds the RSF heartbeat & control service ports
   The port numbers used by rsfmon for RSF heartbeats & control connections
   are looked up using the getservbyname() library call, using the name
   "rsfnet" for the heartbeat port, and "rsfreq" for the control port. If
   getservbyname() can't find sutiable entries, the default ports are both
   numbered 1195.  Note that all machines in a cluster must use the same
   ports. The rsf install process should add these lines to /etc/services:

	rsf-1		1195/udp		# RSF-1 heartbeats
	rsf-1		1195/tcp		# RSF-1 control



7) /etc/rsfmon.pid
   Lock file used to prevent multiple copies of rsfmon from running at the
   same time. The file is locked when rsfmon is running, and is removed on
   normal shutdown.  A system reboot will cause the lock on the file to be
   lost. Contains the PID of the master rsfmon process to allow the rsfctl
   etc. scripts to find out what process to send signals to, and the system
   manager to check that the lock file is still current.



8) /opt/HAC/RSF-1/etc/<machine>.<service>
   These files are internal state files for RSF, and should not normally
   be changed manually (though it is safe to delete state files which
   refer to services which have been removed from the RSF-1 config file,
   once rsfmon is using the new configurtion). If the files must be edited
   to resolve some problem, this should only be done when rsfmon is NOT
   running, and the service state should only be set to one of the stable
   states. Setting a transitional state like starting or stopping will
   prevent rsfmon from handling that service correctly. It is generally
   safer to ensure that the service is not running, then delete the state
   file.

   The service state files contain three (originally two) integers which
   describe the state of the service on the machine where the file is.
   The first number is the service mode: 0 for manual, 1 for automatic.
   The second number is the service state, which corresponds the
   following definition from the file rsflib/rsfcon.h, and the third
   shows wether the service is blocked or not.


   enum service_state
   {
      unknown = 0,	// never been in contact with relevant server
      stopped,		// service is inactive
      starting,		// start scripts are running
      running,		// service running normally
      stopping,		// stop scripts are running
      lock_request,	// not yet implemented
      lock_grant,	// not yet implemented
      panicing,		// split brain detected, panic scripts running
      panicked,		// panic scripts finished
      broken_unsafe,	// repeated/fatal stop script failure
      broken_safe,	// repeated/fatal start failure, abort was OK
      aborting,		// stopping after start failure
      lost,		// service running remote, contact lost
      bouncing,		// stopping, will restart on this machine
      broken_site_safe	// scrip exited broken_site_safe
   };


   If a service state file is missing when rsfmon starts, it will be
   created assuming that the service is in manual mode, unblocked, and
   is not running. This is the normal way for state files to be created
   when a cluster is first started. (A message indicating that the file
   was missing is also logged).
