Configuring a Relay Server for Production

Configure a relay server to forward client requests to a server cluster.

Prerequisites Install one or more relay servers, each on its own machine. If you install multiple relay servers, also install a load balancer to distribute client requests to an available relay server. See either of these topics, based on the platform for your relay server:

Installing the Relay Server components to IIS on Windows
Installing the Relay Server components to Apache on Linux

Note: If you plan to use a relay server, configure it early in the development cycle. After you add a relay server, you must regenerate code for existing clients, and redeploy them.

On a machine where Unwired Platform is installed, configure a relay server by editing relayserver.properties, then running a script to store the property values in the clusterdb database. The following sample displays the default property values:

#########################
# Unwired Server cluster
#------------------------------------------------
cluster.name=%COMPUTERNAME%
#
# All relay servers that service the same Unwired Server cluster must be the same type.
#
relayserver.type               = IIS
#-----------------------------------------------
# Load balancer
#
# If there is a farm of relay servers and a load balancer, 
# enter the host, and HTTP and HTTPS port numbers for the load balancer
#------------------------------------------------
relayserver.host              = AFARIA-DEMO
relayserver.http_port      = 80
relayserver.https_port    = 443
relayserver.farm_name   = %COMPUTERNAME%.SUPFarm
relayserver.token            = 91ae78ca50b90b02cef494c869c6
relayserver.protocol        = http
#
# If your relay server uses a self-signed certificate or a certificate from
# a non-trusted CA, set to the location of a trusted certificate file.
# If the server certificate is signed by a trusted CA, leave blank. 
#----------------------------------------------------------
relayserver.trusted_certs  =

In the Unwired Server installation directory, use a text editor to open relayserver.properties.
Set the value of cluster.name to the name of the Unwired Server cluster to which the relay server directs client requests. By default, cluster.name is assigned the name of the local machine.
Set the value of relayserver.host according to your relay-server architecture:
- If you are running a single relay server, without a load balancer, set relayserver.host to the name of the relay server.
- If you are using a load balancer, set the value of relayserver.host to the name or IP address of the load balancer.
Note: The relay-server host must be visible to systems inside your intranet, and to clients synchronizing from the Internet.
Set the value of relayserver.type based on your Web server. If your relay server is running in:
- IIS on Windows, set the value to "IIS".
- Apache on Linux, set the value to "Unix".
Set relayserver.http_port and relayserver.https_port to the port numbers on which IIS, Apache, or the load balancer is listening. The default values (80 and 443) are typical.
To enable clients and RSOEs to use HTTPS for synchronizing through the relay server:
1. Set the value of relayserver.protocol to "https".
2. For relayserver.trusted_certs, if your relay server uses:
  - A server certificate that is signed by a trusted Certificate Authority (CA), leave the value blank.
  - A self-signed certificate or a certificate from a non-trusted CA, set to the location of a trusted certificate file. The path must be relative to the Sybase Unwired Platform installation directory.
Save your changes, and close relayserver.properties.

Run regRelayServer.bat. Run this only once, from any of the Unwired Server cluster-member installations.

regRelayServer.bat:

Reads the configuration property values in relayserver.properties, and writes them into the clusterdb database.
Generates a configuration script (rs.config) for a basic relay-server architecture: one relay server and one Unwired Server installation.

Based on the sample relayserver.properties, above, replacing %COMPUTERNAME% with "abcXP," the contents of rs.config looks like this:

#-------------------------------------
# Relay server with auto start option
#-------------------------------------
[options]
start = auto
verbosity = 1
#
# When start=auto and the relay server host is active, the default log 
# file name is %temp%\ias_relay_server_host.log. When you shut down 
# the relay-server host, the log file is renamed to YYMMDDNN.log.

#--------------------
# Relay server peers
#--------------------
[relay_server]
enable           = yes
host               = UADEMO-AFARIA
http_port       = 80
https_port     = 443
description    = Relay Server #1 in RS farm

#---------------
# Backend farms
#---------------
[backend_farm]
enable                    = yes
id                            = abcXP.SUPFarm
#client_security      = off
#backend_security = on
description              = abcXP SUP Server Farm

#-----------------
# Backend servers
#-----------------
[backend_server]
enable  = yes
farm      = abcXP.SUPFarm
id          = abcXPSUPServer1
mac      = 00-13-ce-52-a1-5f
token   = 91ae78ca50b90b02cef494c869c6

When you restart Unwired Server, it detects that a relay server has been configured, and passes the relevant information to Eclipse and Visual Studio. Subsequently, when developers generate client code, the code includes the information that clients need to synchronize through the relay server.

If you have a single relay server and a single installation of Unwired Server:
1. Copy rs.config into the Server directory on the relay-server machine.
2. On the relay-server machine, open a command window, and run:
```
rshost -f rs.config -q -qc -u
```
If you have more than one installation of Unwired Server in a single cluster, restart each server.
Each server generates its own copy of rs.config, which contains the correct configuration for this server and one relay server.

To update the relay-server configuration:
1. For each Unwired Server installation, copy the [backend_server] section from rs.config, and paste it into rs.config on the relay-server machine. Paste each section at the bottom of the file.
2. On the relay-server machine, run:
```
rshost -f rs.config -q -qc -u
```

If you have an Afaria server cluster, in rs.config on the relay-server machine:

Create a [backend_farm] section, and set id to the name of the Afaria server farm.

For each Afaria server installation, create a [backend_server] section, and set:

Property	Value
enable	yes
farm	Name of the Afaria server farm.
id	In the Windows registry, the value of HKEY_LOCAL_MACHINE\Software\Afaria\Afaria\Server\TransmitterId.
mac	Physical address of the machine on which the Afaria server is installed. Note: To find the address, run ipconfig/all in a command window.
token	Any value. It is known only to the relay server and the RSOE, which makes it difficult for someone to pose as an RSOE and intercept sync data. If left blank, Unwired Platform generates a value.

Run:
```
rshost -f rs.config -q -qc -u
```

If your relay-server architecture includes either of the following, see The Relay Server User Guide for configuration details:
- Multiple relay servers
- Multiple Unwired Server clusters