A. FIRST STEPS

How to set up a simple test of the rsplib-3.x.y release:

1. If, AND ONLY IF, you would like to use the sctplib/socketapi *userland* SCTP
   implementation, do the following two steps first:

 1.a. Get latest sctplib-****.tar.gz archive and install it by
      - Unpack the Tar/GZip archive
      - ./configure --enable-shared --enable-static
      - make
      - make install
         (as root!)

 1.b. Get latest socketapi-****.tar.gz and install it by
      - Unpack the Tar/GZip archive
      - ./configure --enable-shared --enable-static
      - make
      - make install
         (as root!)

2. Get latest rsplib-****.tar.gz and install it by
      - Unpack the Tar/GZip archive
      - If, AND ONLY IF, you would like to use sctplib/socketapi SCTP
        userland implementation (if unsure, you do *NOT* want this!):
        cmake . -DUSE_KERNEL_SCTP=0
        OTHERWISE (i.e. for kernel SCTP):
        cmake .
      - make
      - make install
         (Only necessary if you want an installation; as root!)

      Optional "cmake" Parameters:
      -DMAX_LOGLEVEL=n Allows for reduction of the maximum logging verbosity to n.
                       Setting a lower value here makes the programs smaller, at
                       cost of reduces logging capabilities (DEFAULT: 9).

      -DENABLE_QT=1: Enables Qt 5.x usage; this is necessary for the Fractal Generator
                     client! Without Qt, the client's compilation will be skipped.
                    (DEFAULT)
      -DENABLE_QT=0: Disables Qt usage; the Fractal Generator client will *not*
                     be available.

      -DENABLE_REGISTRAR_STATISTICS=1: Adds registrar option to write statistics file.
                                       (DEFAULT)
      -DENABLE_REGISTRAR_STATISTICS=0: Do not compile in the statistics option. In this
                                       case, the dependency on libbz2 is removed.

      -DENABLE_HSMGTVERIFY=1: Enable Handlespace Management verification. This is
                              useful for debugging only (makes the PR slow!)
      -DENABLE_HSMGTVERIFY=0: Turns off Handlespace Management verification. (DEFAULT)

      -DENABLE_CSP=1: Enable the Component Status Protocol support (strongly recommended!)
                      (DEFAULT)
      -DENABLE_CSP=0: Turns the Component Status Protocol support off.

      -DBUILD_TEST_PROGRAMS=1: Enable building of test programs.
      -DBUILD_TEST_PROGRAMS=0: Disable building of test programs. (DEFAULT)

3. Ensure that multicast is working!
   - You need a configured network interface with:
        + at least a private address (192.168.x.y; 10.a.b.c; 172.16.n.m - 172.31.i.j)
        + having the multicast flag set (e.g. "ifconfig <dev> multicast")
     even if you want to make tests only via loopback! Multicast-announces do not
     work correctly otherwise!
     If you have a dummy device, configure it appropriately:
     root# ifconfig dummy0 10.255.255.1 netmask 255.255.255.0 broadcast 10.255.255.255 up multicast
   - Ensure that your firewall settings for the ethernet interface allow
     UDP packets to/from the registrar (ASAP Announce/ENRP Presence) as well
     as ASAP/ENRP traffic over SCTP.

4. Start at least one registrar
   ./rspregistrar
   See also Section D for registrar parameters.

5. Start at least one pool element
   ./rspserver -echo
   (You can start multiple pool elements; they may also run on different hosts, of course.
    If it complains about finding no registrar, check the multicast settings!)

6. Start a pool user
   ./rspterminal
   (If it complains about finding no registrar, check the multicast settings!)
   Now, you have to manually enter text lines on standard input.

7. If everything works, you can test RSerPool functionality by stopping the pool
   element and watching the failover.

8. You can monitor the status of each component using the Component Status Protocol
   monitor "cspmonitor". Simply start it by "./cspmonitor". It will listen for status
   messages sent via UDP on port 2960. The components (registrar, rspserver, etc.) accept
   the command line arguments "-cspserver=<Server>:<Port>" and
   "-cspinterval=<Microseconds>". For example, if you want a status update every 300ms
   and your CSP client is listening on port 2960 of host 1.2.3.4, use the arguments
   "-cspserver=1.2.3.4:2960 -cspinterval=300".
   NOTE: You *must* specify address AND interval, otherwise no messages are sent.

9. You can use Wireshark (https://www.wireshark.org) to observe the RSerPool and demo
   protocol traffic. Coloring rules and filters can be found in the directory
   "rsplib/wireshark" Simply copy "colorfilters", "dfilters" and optionally
   "preferences" to ~/.wireshark (or /root/.wireshark).
   Dissectors for the application protocols are already included in recent Wireshark
   distributions!



B. DEMO POOL ELEMENTS (SERVERS)

All demo servers can be started using the rspserver program. It takes a set of
common parameters as well as some service-specific arguments. These parameters
are explained in the following.

Note: For most of the provided services, the latest version of Wireshark
      (https://www.wireshark.org) already includes the packets dissectors!


B.1 Common Parameters

-loglevel=0-9: Sets the logging verbosity from 0 (none) to 9 (very verbose).

-logcolor=on|off: Turns ANSI colorization of the logging output on or off.

-logfile=filename: Write logging output to a file (default is stdout).

-poolhandle=PH: Sets the PH to a non-default value; otherwise, the default
                setting will be the service-specific default (see below).

-registrar=Address:Port: Adds a static PR entry into the Registrar Table.
                         It is possible to add multiple entries.

-asapannounce=Address:Port: Sets the multicast address and port the ASAP instance
                            listens for ASAP Server Announces on.

-rereginterval=milliseconds: Sets the PE's re-registration interval (in ms).

-runtime=seconds: After the configured amount of seconds, the service is
                  shut down.

-quiet: Do not print startup and shutdown messages.

-policy=Policy...: Sets the pool policy and its parameters:
 Valid Settings:
 - Random
 - WeightedRandom:Weight
 - RoundRobin
 - WeightedRoundRobin:Weight
 - LeastUsed
 - LeastUsedDegradation:Degradation (0 to 1)


B.2 Echo Service

-echo: Selects Echo service. The default PH will be "EchoPool".


B.3 Discard Service

-discard: Selects Discard service. The default PH will be "DiscardPool".


B.4 Daytime Service

-daytime: Selects Daytime service. The default PH will be "DaytimePool".


B.5 Character Generator Service

-chargen: Selects Character Generator service. The default PH will be "ChargenPool".


B.6 Ping Pong Service

-pingpong: Selects Ping Pong service. The default PH will be "PingPongPool".

-pppfailureafter=number: After the set number of packets, the server will terminate
                         the connection in order to test failovers.

-pppmaxthreads=threads: Sets the maximum number of simultaneous sessions.


B.7 Fractal Generator Service

-fractal: Selects the Fractal Generator service. The default PH will be "FractalGeneratorPool".

-fgpcookiemaxtime: Send cookie after given number of milliseconds.

-fgpcookiemaxpackets: Send cookie after given number of Data messages.

-fgptransmittimeout: Set transmit timeout in milliseconds (timeout for rsp_sendmsg()).

-fgptestmode: Generate simple test pattern instead of calculating a fractal
              graphics (useful to conserve CPU power).

-fgpfailureafter=number: After the set number of data packets, the server will
                         terminate the connection in order to test failovers.

-fgpmaxthreads=threads: Sets the maximum number of simultaneous sessions.



C. DEMO POOL USERS (CLIENTS)

C.1 Common Parameters

-loglevel=0-9: Sets the logging verbosity from 0 (none) to 9 (very verbose).

-logcolor=on|off: Turns ANSI colorization of the logging output on or off.

-logfile=filename: Write logging output to a file (default is stdout).

-poolhandle=PH: Sets the PH.


C.2 Terminal (e.g. for Echo, Discard, Daytime and Chargen services)

Start with ./rspterminal; the default PH is EchoPool.


C.3 Fractal Client (for the Fractal Generator service)

./fractalpooluser

-configdir=Directory: Sets a directory to look for FGP config files. From all FGP files
                      (pattern: *.fgp) in this directory, random files are selected for the
                      calculation of requests.

-threads=Count:       Sets the number of parallel sessions for the calculation
                      of an image.

-caption=Title:       Sets the window title.


C.4 Ping Pong Client (for the Fractal Generator service)

./pingpong

-interval=milliseconds: Sets the Ping interval.



D. REGISTRAR

Start the registrar with:

./rspregistrar



D.1 Common Parameters

-loglevel=0-9: Sets the logging verbosity from 0 (none) to 9 (very verbose).

-logcolor=on|off: Turns ANSI colorization of the logging output on or off.

-logfile=filename: Write logging output to a file (default is stdout).

-peer=Address:Port: Adds a static PR entry into the Peer List.
                    It is possible to add multiple entries.


D.2 ASAP Parameters

-asap=auto|address:port{,address}: Sets the ASAP endpoint address(es). Use "auto"
                                   to automatically set it (default).
                                   Examples: -asap=auto
                                             -asap=1.2.3.4:3863
                                             -asap=1.2.3.4:3863,[2000::1:2:3],9.8.7.6

-asapannounce=auto|address:port: Sets the multicast address and UDP port to send
                                 the ASAP Announces to. Use "auto" for default.
                                 Examples: -asapannounce=auto
                                           -asapannounce=239.0.0.1:3863

-maxbadpereports=reports: Sets the maximum number of ASAP Endpoint Unreachable reports before
                          removing a PE.

-endpointkeepalivetransmissioninterval=milliseconds: Sets the ASAP Endpoint Keep Alive interval.

-endpointkeepalivetimeoutinterval=milliseconds: Sets the ASAP Endpoint Keep Alive timeout.

-serverannouncecycle=milliseconds: Sets the ASAP Announce interval.

-autoclosetimeout=seconds: Sets the SCTP autoclose timeout for idle ASAP associations.

-minaddressscope: Sets the minimum address scope acceptable for registered PEs:
                  * loopback: Loopback address (only valid on the same node!)
                  * site-local: Site-local addresses (e.g. 192.168.1.1, etc.)
                  * global: Global addresses

-quiet: Do not print startup and shutdown messages.


D.3 ENRP Parameters

-enrp=auto|address:port{,address}: Sets the ENRP endpoint address(es). Use "auto"
                                   to automatically set it (default).
                                   Examples: -enrp=auto
                                             -enrp=1.2.3.4:9901
                                             -enrp=1.2.3.4:9901,[2000::1:2:3],9.8.7.6

-enrpannounce=auto|address:port: Sets the multicast address and UDP port to send
                                 the ENRP Announces to. Use "auto" for default.
                                 Examples: -enrpannounce=auto
                                           -enrpannounce=239.0.0.1:9901

-peerheartbeatcycle=milliseconds: Sets the ENRP peer heartbeat interval.

-peermaxtimelastheard=milliseconds: Sets the ENRP peer max time last heard.

-peermaxtimenoresponse=milliseconds: Sets the ENRP maximum time without response.

-takeoverexpiryinterval=milliseconds: Sets the ENRP takeover timeout.

-mentorhuntinterval=milliseconds: Sets the mentor PR hunt interval.


E. COMPONENT STATUS PROTOCOL

The Component Status Protocol is a simple UDP-based protocol for RSerPool
components to send their status to a central monitoring component. A
console-based receiver is ./cspmonitor; it receives the status updates by
default on UDP port 2960.

In order to send status information, the registrar as well as all servers and
clients described in section B provide two parameters:

-cspserver=Address:Port: Sets the CSP monitor server's address and port.

-cspinterval=Interval: Sets the interval for the CSP status updates in
                       milliseconds.

Note: Both parameters MUST be provided in order to send status updates!



==================================================================================
Please subscribe to our mailing list and report any problems you discover!
Help us to improve rsplib, the world's first Open Source RSerPool implementation!

Visit https://www.nntb.no/~dreibh/rserpool/ for more information
==================================================================================


04.10.2019 Thomas Dreibholz, thomas.dreibholz@gmail.com