A.2. Components of the SGD Gateway

The SGD Gateway consists of the following components:

A.2.1. About Routing Tokens

The SGD Gateway uses a routing token to manage an AIP connection. A routing token is a signed, encrypted message which identifies the origin and destination SGD server for a route. The routing token includes a time stamp, which is used to limit the token lifetime.

Outgoing routing tokens are:

  • Signed on the SGD server, using the private key for the SGD server.

  • Encrypted on the SGD server, using the SGD Gateway certificate.

  • Sent to the SGD Client on the client device.

Incoming routing tokens are:

  • Decrypted on the SGD Gateway, using the SGD Gateway private key.

  • Verified on the SGD Gateway, using the CA certificate for the origin SGD server.

  • Discarded on the SGD Gateway. The connection presenting the routing token is routed to the destination SGD server.

A.2.2. Keystores Used By the SGD Gateway

The SGD Gateway uses private keys and certificates to digitally sign and verify routing tokens, to secure connections to the SGD servers in the array, to secure client connections to the SGD Gateway, and to authorize access to the reflection service.

The certificates and private keys used by the SGD Gateway are stored in keystores in the /opt/SUNWsgdg/proxy/etc directory.

This directory contains the following keystores:

  • SGD Gateway keystore. The SGD Gateway keystore, keystore, contains the SGD Gateway certificate and private key, CA certificates for the SGD servers in the array, and SGD server SSL certificates for secure connections to the SGD servers in the array.

    To add, remove, and list entries for the SGD Gateway keystore, use the gateway command.

  • Client keystore. The client keystore, keystore.client, contains a single SGD Gateway SSL certificate and private key used for securing connections between the client device and the SGD Gateway. By default, this keystore contains a self-signed certificate. You can replace this certificate with a certificate signed by a Certificate Authority (CA).

  • Reflection service keystore. The reflection service keystore, keystore.reflection, contains a certificate and private key used to authorize access to the reflection service on the SGD Gateway. By default, this keystore contains a self-signed certificate and private key.

The keystores are created automatically when you run the gateway setup command after installing the SGD Gateway.

Note

All keystores use the same password, which is defined in the /opt/SUNWsgdg/etc/password file. The password is a random password created automatically when the keystores are first created. The password file is only readable by superuser (root).

A.2.3. Routing Proxy Configuration File

The routing proxy configuration file is /opt/SUNWsgdg/etc/gateway.xml. This is an XML file that configures routes, depending on the data protocol type. The file also configures the keystore locations and passwords required for routing and SSL protocols.

The routing proxy configuration file is created automatically when you install the SGD Gateway and is updated when you use the gateway config commands to change the configuration of the SGD Gateway.

Caution

Use the gateway config commands to configure the Gateway. If possible, avoid editing the gateway.xml file manually. Incorrect configuration in the gateway.xml file might cause the SGD Gateway to stop working.

The default routing proxy configuration file uses the password in the /opt/SUNWsgdg/etc/password file to access the keystores used by the SGD Gateway. If you do not want to store this password on disk, make a note of the entry in the password file. Delete the password file, and delete the password entries for all <keystore> elements in the gateway.xml file. You are then prompted for the keystore password when you next start the SGD Gateway.

To change the password for a keystore used by the SGD Gateway, use the -storepasswd option of the keytool command. For example, to change the password for the keystore.client keystore run the following command:

# /opt/SUNWsgdg/java/default/bin/keytool -storepasswd \
-keystore /opt/SUNWsgdg/proxy/etc/keystore.client 

See the JDK Tools and Utilities documentation for details on how to use the keytool application.

Note

The /opt/SUNWsgdg/etc directory also contains other .xml and .template files. These files are used internally by the gateway config command to update the gateway.xml file. Do not edit these files manually.

A.2.4. Apache Web Server Configuration Files

Configuration files for the Apache web server configured for use with the SGD Gateway are in the /opt/SUNWsgdg/httpd/apache-version/conf directory.

The configuration files in this directory are used to configure reverse proxy operation and load balancing for the Apache web server.

A.2.4.1. Configuring Reverse Proxying and Load Balancing

Files for configuring reverse proxy operation and load balancing are in the extra/gateway subdirectory. These files are enabled by the following Include directive in the main httpd.conf file:

# SGD Reverse Proxy/Load Balance settings
Include conf/extra/gateway/httpd-gateway.conf

The httpd-gateway.conf file configures reverse proxying and load balancing for the Apache web server. The members of the load balancing group are defined using an Include directive in the httpd-gateway.conf file, as follows:

<Proxy Balancer://mysgdservers/>
Include conf/extra/gateway/servers/*.conf
</Proxy>

The extra/gateway/servers directory contains configuration files for each of the SGD web servers in the load balancing group. The configuration files are named server-name.conf, where server-name is the server name used in the gateway server add command. See Section B.12, “gateway server add” for more details about this command.

The SGD Gateway uses sticky session HTTP load balancing. This means that the Apache reverse proxy sets a cookie in the client browser, to ensure that the browser always returns to the SGD web server that was selected by load balancing. The cookie expires at the end of the user session.

Sticky session cookies are enabled by the Header add Set-Cookie directive in the httpd-gateway.conf file, as follows:

Header add Set-Cookie "BALANCEID=balanceworker.%{BALANCER_WORKER_ROUTE}e; path=/" \
env=BALANCER_ROUTE_CHANGED

where BALANCEID is the name of the cookie, and BALANCER_WORKER_ROUTE and BALANCER_ROUTE_CHANGED are environment variables exported by the Apache mod_proxy_balancer module. See the Apache mod_proxy_balancer documentation for more information about these environment variables.

A.2.5. Apache Modules Used by the SGD Gateway

The Apache web server supplied with the SGD Gateway uses the standard Apache modules for reverse proxying and load balancing. The modules are installed as Dynamic Shared Object (DSO) modules.

The modules are enabled by LoadModule directives in the httpd.conf Apache configuration file, at /opt/SUNWsgdg/httpd/apache-version/conf/httpd.conf.