| = Multipoint Recommendations |
| :index-group: Discovery and Failover |
| :jbake-date: 2018-12-05 |
| :jbake-type: page |
| :jbake-status: published |
| |
| |
| As mentioned the `initialServers` is only used for bootstrapping the |
| multipoint network. Once running, all servers will dynamically establish |
| direct connections with each other and there is no single point of |
| failure. |
| |
| However to ensure that the bootstrapping process can occur successfully, |
| the `initialServers` property of the `conf/multipoint.properties` file |
| must be set carefully and with a specific server start order in mind. |
| Each server consults its `initialServers` list exactly once in the |
| bootstrapping phase at startup, after that time connections are made |
| dynamically. |
| |
| This means that at least one of the servers listed in `initialServers` |
| must already be running when the server starts or the server might never |
| become introduced and connected to all the other servers in the network. |
| |
| == Failed scenario background |
| |
| As an example of a failed scenario, imagine there are three servers; |
| `server1`, `server2`, `server3`. They are setup only to point to the |
| server in front of them making a chain: |
| |
| * server1; `initialServers = server2` |
| * server2; `initialServers = server3` |
| * server3; `initialServers = *<blank>*` |
| |
| Which is essentially `server1` -> `server2` -> `server3`. This scenario |
| could work, but they servers would have to be started in exactly the |
| opposite order: |
| |
| [arabic] |
| . `server3` starts |
| . `server2` starts |
| [arabic] |
| .. _static:_ connect to `server3` |
| . `server1` starts |
| [arabic] |
| .. _static:_ connect to `server2` |
| .. _dynamic:_ connect to `server3` |
| |
| At this point all servers would be fully connected. But the above setup |
| is flawed and could easily fail. The first flaw is `server3` lists |
| nothing in its `initialServers` list, so if it were restarted it would |
| leave the multipoint network and not know how to get back in. |
| |
| The second flaw is if you started them in any other order, you would |
| also not get a fully connected multipoint network. Say the servers were |
| started in "front" order: |
| |
| [arabic] |
| . `server1` starts |
| [arabic] |
| .. _static:_ connect to `server2` - failed, `server2` not started. |
| . `server2` starts |
| [arabic] |
| .. _static:_ connect to `server3` - failed, `server3` not started. |
| . `server3` starts |
| [arabic] |
| .. no connection attempts, initialServers list is empty. |
| |
| After startup completes, all servers will be completely isolated and |
| failover will not work. The described setup is weaker than it needs to |
| be. Listing just one server means the listed server is a potential point |
| of weakness. As a matter of trivia, it is interesting to point out that |
| you could bring a fourth server online temporarily that lists all three |
| servers. Once it makes the introductions and all servers learn of each |
| other, you could shut it down again. |
| |
| The above setup is easily fixable via better configuration. If `server3` |
| listed both `server1` and `server2` in its initialServers list, rather |
| than listing nothing at all, then all servers would fully discover each |
| other regardless of startup order; assuming all three servers did |
| eventually start. |
| |
| == Bootstrapping Three Servers or Less |
| |
| In a three sever scenario, we recommend simply having all three servers |
| list all three servers. |
| |
| * server1/conf/multipoint.properties |
| ** `initialServers = server1, server2, server3` |
| * server2/conf/multipoint.properties |
| ** `initialServers = server1, server2, server3` |
| * server3/conf/multipoint.properties |
| ** `initialServers = server1, server2, server3` |
| |
| There's no harm to a server listing itself. It gives you one clean list |
| to maintain and it will work even if you decide not to start one of the |
| three servers. |
| |
| == Bootstrapping Four Servers or More |
| |
| In a scenario of four or more, we recommend picking at least to servers |
| and focus on always keeping at least one of them running. Lets refer to |
| them as "root" servers for simplicity sake. |
| |
| * server1/conf/multipoint.properties |
| ** `initialServers = server2` |
| * server2/conf/multipoint.properties |
| ** `initialServers = server1` |
| |
| Root `server1` would list root `server2` so they would always be linked |
| to each other regardless of start order or if one of them went down. |
| `Server1` could be shutdown and reconnect on startup to the full |
| multipoint network through `server2`, and vice versa. |
| |
| All other servers would simply list the root servers (`server1`, |
| `server2`) in their initialServers list. |
| |
| * server3/conf/multipoint.properties |
| ** `initialServers = server1, server2` |
| * server4/conf/multipoint.properties |
| ** `initialServers = server1, server2` |
| * serverN/conf/multipoint.properties |
| ** `initialServers = server1, server2` |
| |
| As long as at least one root server (`server1` or `server2`) was |
| running, you can bring other servers on and offline at will and always |
| have a fully connected graph. |
| |
| Of course all servers once running and connected will have a full list |
| of all other servers in the network, so if at any time the "root" |
| servers weren't around to make initial introductions to new servers it |
| would be no trouble. It's possible to reconfigure new servers to point |
| at any other server in the network as all servers will have the full |
| list. So these "root" servers are no real point of failure in function, |
| but only of convenience. |
| |
| == Setting initialServers overrides |
| |
| Always remember that any property in a |
| `conf/<server-service>.properties` file can be overridden on the command |
| line or via system properties. So it is possible easily set the |
| `initialServers` list in startup scripts. |
| |
| A bash example might look something like: |
| |
| [source,java] |
| ---- |
| !/bin/bash |
| |
| OPENEJB_HOME=/opt/openejb-3.1.3 |
| INITIAL_LIST=$(cat /some/shared/directory/our_initial_servers.txt) |
| |
| $OPENEJB_HOME/bin/openejb start -Dmultipoint.initialServers=$INITIAL_LIST |
| ---- |