Gateways

Clients connect to the server through a gateway. A Union server can have many gateways deployed but must have at least one.

Union includes a TCP-based (i.e., internet-access) gateway named TCP. Union's TCP gateway is based on the MINA library, and supports the following types of communications:

  • Persistent TCP/IP socket connections
  • HTTP socket connections
  • Flash policy file requests

A TCP gateway is deployed in the default configuration (union.xml) shipped with Union Server.

Recommended Gateways

To allow Union clients to bypass firewalls when connecting to Union Server, Union Server should be configured with gateways listening on ports 80, 443, and 9100. When communicating over port 80 using HTTP, Union client requests are considered valid HTTP traffic by firewalls, and are permitted to pass through to Union Server. For an example showing how to deploy a gateway on port 80, see "Deploying a Gateway," following.

Deploying a Gateway

To deploy a new Union Server gateway, follow these steps:

  1. In Union's home directory, edit the file named "union.xml".
  2. In the <gateways> element, add a new <gateway> element with the "type" attribute set to "TCP", the "id" attribute set to the desired gateway name, and an optional nested <ip> element set to the IP address on which the gateway will listen (omit for all local IPs). In nested <port> and <policy_file> elements, specify the gateway's port and policy file location.

    For example, to deploy gateways on port 80 and port 443 listening on all local IP addresses, add the following code to the <gateways> element:

    1
    2
    3
    4
    5
    6
    7
    8
    <gateway id="WebGateway" type="TCP">
        <port>80</port>
        <policy_file>policy.xml</policy_file>
    </gateway>
    <gateway id="SSLGateway" type="TCP">
        <port>443</port>
        <policy_file>policy.xml</policy_file>
    </gateway>
  3. Save "union.xml".
  4. Restart Union Server.
Note: Deploying a gateway on a port under 1024 requires root privileges.

To deploy Union Server and a web server on the same machine, both listening on port 80, configure the web server to listen to port 80 on one ip address, and configure a Union gateway to listen on port 80 on a different IP address. For example, the following code deploys a gateway on port 80 on the fictional IP address "1.2.3.4":

1
2
3
4
5
<gateway id="WebGateway" type="TCP">
    <ip>1.2.3.4</ip>
    <port>80</port>
    <policy_file>policy.xml</policy_file>
</gateway>

Cross-Origin Resource Sharing

For HTTP and websocket connections the TCP gateway supports Cross-Origin Resource Sharing with the access_control_allow_origin element the value of which is a comma-separated list of origins that should be allowed access. Do not use spaces after the commas in the list. If the access_control_allow_origin element is omitted the value is assumed to be "*". If the origin of a request matches an origin in the access_control_allow_origin list or access_control_allow_origin is set to "*" then the origin will be set in the Access-Control-Allow-Origin response header.

Cross-Origin Resource Sharing Example

With the following configuration in union.xml:

1
2
3
4
5
        <gateway id="PrimaryGateway" type="TCP">
            <port>9100</port>
            <policy_file>policy.xml</policy_file>
            <access_control_allow_origin>http://user1.net,http://unionplatform.com</access_control_allow_origin>
        </gateway>

If the request origin is not http://user1.net nor http://unionplatform.com then the Access-Control-Allow-Origin header will be empty. If the request origin is http://user1.net then the Access-Control-Allow-Origin header will have the value http://user1.net.