Union User Guide

Configuration

To configure the server, edit the union.xml file, found in the UNION_HOME directory. Note: the server must be restarted before changes to union.xml file will take effect.

The union.xml file has 5 major sections.

  • Server Section: to configure the admin and server wide settings.
  • Gateways Section: to configure how clients can connect to the server.
  • Modules Section: to configure modules deployed at startup.
  • Rooms Section: to configure rooms deployed at startup.
  • Security Section: to configure the security for the server.

Following is an example union.xml file that includes most configuration options currently available.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<union>
    <server>
        <admin>
            <ip>1.2.3.4</ip>
            <port>9110</port>
            <password>password</password>
        </admin>
        <client_timeout>30</client_timeout>
        <attributes>
            <attribute name="serverAttribute">serverAttributeValue</attribute>
        </attributes>
    </server>
    <gateways>
        <gateway id="PrimaryGateway" type="TCP">
            <ip>1.2.3.4</ip>
            <port>9100</port>
            <policy_file>policy.xml</policy_file>
            <access_control_allow_origin>http://example1.com,http://example2.com</access_control_allow_origin>
        </gateway>              
    </gateways>
    <modules>
        <module>
            <id>serverStatsServerModule</id>
            <source type="class">net.user1.union.servermodule.ServerStatsServerModule</source>
            <attributes>
                <attribute name="interval">300</attribute>
            </attributes>
        </module>  
    </modules>
    <rooms>
        <room>
            <id>aRoomID</id>
            <attributes>
                <attribute name="roomAttribute">roomAttributeValue</attribute>
            </attributes>
            <modules>
                <module>
                     <source type="class">mymodules.StartupModule</source>
                     <attributes>
                        <attribute name="roomModuleAttribute">roomModuleValue</attribute>
                     </attributes>
                </module>  
                <module>
                    <source type="script">MyRoomModule.js</source>
                </module>                                
            </modules>
        </room>
    </rooms>
</union>

And now a line by line explanation.

  1. Start of union.xml.
  2. Start server section.
  3. Start admin settings.
  4. The local IP address to bind to. If omitted, binds to all local IP addresses.
  5. The port that the admin will bind to for admin connections.
  6. The admin password. When changing the server password, be sure to also change password in stopserver.sh, otherwise, the server will refuse attempts to stop the server, and will output the following error message: Login refused [AUTHORIZATION_FAILED].
  7. End admin settings.
  8. The number of seconds a client is allowed to remain connected without sending a message to Union Server. If a client does not send a message at least every client_timeout seconds, Union Server disconnects that client. Note that by default, client_timeout is set to 30 seconds, and Reactor clients automatically send a heartbeat message to Union Server every 10 seconds. Therefore, in the default case, the only Reactor clients Union Server will disconnect due to inactivity are those that experience network lag longer than client_timeout's specified value. If omitted, clients that do not send messages to Union Server are allowed to remain connected indefinitely.
  9. Start of setting server attributes.
  10. A server attribute. In this example the name of the attribute is "serverAttribute" and the value is "serverAttributeValue").
  11. End of setting server attributes.
  12. End server section.
  13. Start gateways section. Note: while the types of gateways is optional at least 1 gateway must be deployed.
  14. Deploy a new gateway using Java NIO over TCP.
  15. The local IP address to bind to. If omitted, binds to all local IP addresses.
  16. The port the gateway will bind to for connections.
  17. The policy file the gateway will use to respond ot policy file requests.
  18. Comma separated list (no spaces) of domains permitted to communicate with Union Server over HTTP or WebSocket via a web browser. Use * for all domains.
  19. End new gateway deployment.
  20. End gateways section.
  21. Start modules section.
  22. Deploy a new module.
  23. The id of the module used to identify the module within the server.
  24. Specify the source of the module. In this example, the type is a Java class and the class to load is "net.user1.union.servermodule.ServerStatsServerModule".
  25. Start of setting attributes for the module.
  26. An attribute for the module. In this example, the name of the attribute is "interval" and the value is "300".
  27. End attributes for the module.
  28. End deploying the module.
  29. End modules section.
  30. Start rooms section.
  31. Deploy a new room.
  32. The id of the room used to identify the room within the server.
  33. Start of setting attributes for the room.
  34. An attribute for the room. In this example, the name of the attribute is "roomAttribute" and the value is "roomAttributeValue".
  35. End attributes for the room.
  36. Start of room modules for the room.
  37. Deploy a room module to the room.
  38. Specify the source of the room module. In this example, the type is a Java class and the class to load is "mymodules.StartupModule".
  39. Start setting attributes for the room module.
  40. An attribute for the room module. In this example, the name of the attribute is "roomModuleAttribute" and the value is "roomModuleValue".
  41. End attributes for the room module.
  42. End deploying the room module.
  43. Deploy a room module to the room.
  44. Specify the source of the room module. In this example, the type is Javascript and the script to load is the file "MyRoomModule.js".
  45. End deploying the room module.
  46. End of room modules for the room.
  47. End deploying the room.
  48. End rooms section.
  49. End of union.xml.