Networking Directives

The following directives configure the RealityServer clustering.

network

The default value of off disables cluster networking (multiple server hosts working together) and on enables it. The HTTP and admin ports are not affected. When enabling, make sure that your network switch is multicast-capable (or configure the network mode to use unicast); see the hardware requirements section of the manual for details. The default is off because consumer-class and even certain larger switches are often not suitable for the high network throughputs of RealityServer, and could cause very slow startups and problems during operation.

cluster_base_address

The first cluster multicast address. For n clusters, n+1 consecutive addresses will be used, starting with the specified one. This is useful if multiple RealityServers in the same subnet should coexist: RealityServer hosts with the same cluster base address detect one another's presence (if the version number matches) and form a combined cluster network. Care should be taken to avoid range overlaps. This only applies to the UDP protocol; TCP does not use this variable. See cluster_interface below for protocol selection.

Using IPv6 the address need to be surrounded with brackets, like in ``[FF00::FF02:1]''.

multicast_ttl

The time to live or number of hops multicast packets should have. This can be useful to set to a higher value if nodes in a cluster are separated by a router which does not forward multicast packets because of the default TTL value of 1.

cluster_interface

The IP address of the interface to listen on for UDP cluster packets. 0.0.0.0 or absence means all interfaces. This is useful if the host has more than one network card, and one should be dedicated to internal cluster communication and the other for a file server, or for HTTP and admin web connections. More than one such statement can be specified.

The string may begin with udp/ (default) or tcp/ to select the transmission protocol. UDP multicasting is more efficient in large clusters but places higher demands on the IP switch that connects the cluster; TCP does not scale to many hosts but works with (almost) any switch. TCP requires a host list or usage of the discovery mode.

The string may end with : and a port number to select which port to listen to for UDP and TCP unicasting. If no port is set and unicast only mode is set, port 10000 will be used.

The IP address of the interface can also be specified as a sub net using the CIDR notation a.b.c.d/xx. If there is an interface on the host with an address inside this range it will be used. This is useful for example when sharing a configuration file between several hosts. This means that on a host which have address 192.168.1.1, specifying the interface as tcp/192.168.0.0/16:10000 would make the host use TCP networking, binding to the 192.168.1.1 address on port 10000. Some more examples are

                # UDP, bind on all interfaces, default port 10000
                cluster_interface ""
                # TCP, bind on all interfaces, port 7777
                cluster_interface tcp/:7777
                # UDP, bind to IP 10.0.10.10, port 9999
                cluster_interface udp/10.0.10.10:9999
                # UDP, bind first address matching net 10.0.0.0/24, default port
                cluster_interface 10.0.0.0/24
                # UDP, bind first address matching net 10.0.0.0/24, port 9999
                cluster_interface 10.0.0.0/24:9999
                # TCP, bind first address matching net 192.168.0.0/15, port 9999
                cluster_interface tcp/192.168.0.0/16:9999
            

IPv6 addresses need to be surrounded by brackets but can otherwise be used just like its IPv4 counterparts mentioned above. The address [::] means the "any IPv6 interface" address.

When using TCP there is also the option of the Discovery mode. This is a method of populating the cluster_host list automatically using multicast. Discovery mode only makes sense when using TCP unicasting. This mode is specified by prepending the "tcp/" specifier with "disc+". Two examples follow.

                # IPv6, TCP, Discovery, bind on the IPv6 any interface, port 7777
                cluster_interface disc+tcp/[::]:7777
                # IPv6, TCP, Discovery, bind address matching net fd00:172:16::/64 on
                # port 9999
                cluster_interface disc+tcp/[fd00:172:16::]/64:9999
            

cluster_hosts

A comma-separated list of host names or host IP addresses. If specified, only the listed hosts will be allowed to join the network. If not specified then any host can join. If the cluster_interface specifies TCP, the cluster_hosts list may not be empty (unless automatic host discovery is enabled with the cluster_interface specifier "disc+").

cluster_discnet_address

The default multicast address used for discovery can be changed by setting this variable. Notice that a port have to be set as well. If this address is a unicast address it will be considered the master node and the list of other hosts will be fetched from it. The master node will be the one node which has its own address configured as the cluster_discnet_address. Using IPv6 the address need to be surrounded with brackets, like in "[FF05::FF05:1]:12009".

cluster_discnet_version

To make sure that no other nodes accidently join your cluster using the same discovery address, specify a unique version string that all joining nodes have to be configured with.

cluster_compression_level

If used bandwidth is becoming an issue, enabling compression of the data being sent between hosts in the cluster can help. 0 is default and means no compression at all. Setting it to any number between 1 and 9 means varying grades of compression is being used where 9 is the most costly CPU wise. A good compromise is setting it to 6.

cluster_redundancy_level

The number of times every database element is stored on the network. 1 means no redundancy, 4 means four hosts have copies so three can fail simultaneously without loss of data. This number should be chosen based on the failure rate on large networks. Four is the maximum and a very conservative number; small networks can lower this to achieve a slightly lower network load if scenes are very large.