When running multiple MyTimetable instances off the same user preferences database - either on the same or different servers, it is necessary to configure the cache clustering feature of MyTimetable. This way, we can be sure the users always see an up-to-date profile, since the cache clustering feature allows for the cache of all nodes to be invalidated if any of the nodes makes an update to the data.

Internally, MyTimetable's cache relies on Infinispan, which uses JGroups for cache replication. The default JGroups configuration in use is a TCP + TCPPING configuration, which means unicast communication is used and the list of nodes in use should be preconfigured on each node. This configuration permits all possible network configurations, and is a good choice considering the small number of nodes (usually not more than 2) necessary to run MyTimetable. Other configurations are possible by editing jgroups.xml in the MyTimetable source package; our support department will create a customised configuration on request.

Activating clustering

To activate clustering in your MyTimetable installation, take the following steps:

  1. Activate the Spring profile clustered. This can be done by adding clustered to the spring.profiles.active environment property in your MyTimetable Tomcat configuration file (usually called ROOT.xml). If the spring.profiles.active property is currently not present, the default value can be found in the file web.xml in the MyTimetable source tree. This value depends on the features in use, and is different for every customer. When in doubt, please ask our support department for the right value.
  2. Adjust the configuration values if necessary (see below). The default configuration variables are meant for a dual-deployment on the same server (e.g., to two different paths or hosts).
  3. Open the firewall on the host machine if necessary. By default, the first instance of MyTimetable listens on TCP port 7800 and 7850 for incoming traffic, the second instance listens on TCP port 7801 and 7851, et cetera. All MyTimetable hosts should have unrestricted access to these ports.

Configuring clustering

The following configurations options are available to configure clustering. When deploying MyTimetable over multiple hosts, at least the properties cluster.bind_addr and cluster.initial_hosts should be changed. These properties can be configured in the MyTimetable configuration file (ROOT.xml by default), under the scheduleviewer/server namespace (replace any dots in the name with a slash when configuring using Tomcat Environment variables).

Configuration keyDefault valueDescription
cluster.namemytimetableName of the Infinispan/JGroups cluster. Normally does not require changing, unless you are running multiple MyTimetable clusters in the same JGroups cluster.

The address to bind the JGroups server sockets on, this is the loopback interface by default. Specify an IP address to listen on a specific interface, or specify one of the following special values:

  • NON_LOOPBACK: picks any non-loopback address (preferred value if not specifying an IP)
  • GLOBAL: picks a global (public) address
  • SITE_LOCAL: an address starting with 192.168.x.x or 10.0.x.x
  • LINK_LOCAL: a link local address, ie. starting with 169.x.x.x or 254.x.x.x
cluster.bind_port7800TCP port to bind the JGroups communication server socket on. If multiple instances are active on the current host, the second instance is bound to bind_port + 1, et cetera (max 6 instances are supported).
cluster.initial_hosts127.0.0.1[7800],[7801]List of all cluster hosts (including the current host), in the format as specified for the default value (comma–delimited host[port] list).
cluster.bind_port_fd7850TCP port to bind the JGroups failure detection heartbeat server socket on. If multiple instances are active on the current host, the second instance is bound to bind_port_fd + 1, et cetera (max 6 instances are supported).

By default, the JVM prefers IPv6 connections over IPv4 connections. When the IPv6 stack of an host is active, but you want to refer to cluster hosts by IPv4 address or IPv4-based hostname, you should specify the following JVM option to prefer IPv4 over IPv6: -Djava.net.preferIPv4Stack=true

Security considerations

Currently, the JGroups communication is unencrypted and unauthenticated. For this reason, only trusted hosts should have access to the JGroups listen ports (TCP 7800 and 7850 by default) and the JGroups communication should only be run over a trusted network. If an attacker gains access to these ports, in the worst case scenario it would be possible to overwrite user profiles or subscriptions. Encryption and/or authentication of the cluster communications is only partially supported by JGroups; in case of doubt over the security of your cluster configuration please contact our support department.

  • No labels