Sun Secure Global Desktop 4.5 Gateway Administration GuideTable Of Contents Previous ChapterNext ChapterNo Book Index


C H A P T E R  2

Configuring the SGD Gateway

This chapter describes how to configure the SGD Gateway for typical deployment scenarios. How to start and stop the SGD Gateway is also covered in this chapter, along with instructions on how to remove the SGD Gateway software.

This chapter includes the following topics:

Deploying the SGD Gateway

This section describes the following SGD Gateway deployment scenarios:

Basic Deployment

This section describes the configuration tasks for a basic deployment of the SGD Gateway.

A basic deployment uses a single SGD Gateway, as shown in FIGURE 2-1.

FIGURE 2-1   Basic Deployment Using a Single SGD Gateway

Network Diagram Showing a Basic Deployment Using a Single SGD Gateway


Configuring a basic deployment involves configuring the connections shown in TABLE 2-1.


TABLE 2-1   Connections For a Basic Deployment of the SGD Gateway
Connection Configuration Steps
Client device to SGD Gateway

  1. Configure the ports and connections used by the SGD Gateway. You configured these settings when you installed the SGD Gateway. See How to Configure the Ports and Connections for the SGD Gateway if you want to change the configuration of the SGD Gateway.

  2. On the SGD Gateway, install a Secure Sockets Layer (SSL) certificate for client connections. See How to Install an SSL Certificate for Client Connections Into the Client Keystore.
SGD Gateway to SGD servers

  1. Enable SGD security services for the array. The SGD servers must be running in secure mode. Firewall traversal is not supported. See “Setting Up Secure Client Connections (Manual Configuration)” in Chapter 1 of the Sun Secure Global Desktop 4.5 Administration Guide for details of how to do this.

  2. On the SGD Gateway, install security certificates for the SGD servers. Use the gateway server command to import CA certificates and SSL certificates for the SGD servers in the array into the SGD Gateway keystore. See How to Install SGD Server Certificates.

  3. Set up the SGD servers in the array to use the SGD Gateway. Install the SGD Gateway certificate on the SGD array, and use the tarantella gateway add command to register the SGD Gateway with the SGD array. See How to Install SGD Gateway Certificates on the SGD Array.

  4. Configure which SGD Client connections can use the SGD Gateway. See How to Configure SGD Client Connections.

Load-Balanced Deployment

This section describes the configuration tasks for a load-balanced deployment of SGD Gateway.

A load-balanced deployment uses multiple SGD Gateways and a load balancer as the network entry point, as shown in FIGURE 2-2.

FIGURE 2-2   Network Deployment Using Multiple SGD Gateways and a Load Balancer

Network Diagram Showing a Load-Balanced Deployment Using Multiple SGD Gateways and a Load Balancer


Configuring a load-balanced deployment involves configuring the connections shown in TABLE 2-1.


TABLE 2-2   Connections For a Load-Balanced Deployment of the SGD Gateway
Connection Configuration tasks
Client device to load balancer

  1. Enable incoming connections from client devices. Typically, this uses Transmission Control Protocol (TCP) port 443. See your load balancer documentation for details of how to do this.

  2. (Optional) On the load balancer, install the SSL certificate used by the SGD Gateways for client connections. See your load balancer documentation for details of how to do this.
Load balancer to SGD Gateway

  1. Configure your load balancer to forward connections to the SGD Gateway. See your load balancer documentation for details of how to do this.

  2. Configure the ports and connections used by the SGD Gateway. Set the network entry point to the address of the load balancer. You configured these settings when you installed the SGD Gateway. See How to Configure the Ports and Connections for the SGD Gateway if you want to change the configuration of the SGD Gateway.

  3. On each SGD Gateway, install an SSL certificate for client connections. See How to Install an SSL Certificate for Client Connections Into the Client Keystore.
SGD Gateway to SGD servers

  1. Enable SGD security services for the SGD array. The SGD servers must be running in secure mode. Firewall traversal is not supported. See “Setting Up Secure Client Connections (Manual Configuration)” in Chapter 1 of the Sun Secure Global Desktop 4.5 Administration Guide for details of how to do this.

  2. On the SGD Gateway, install security certificates for the SGD servers. Use the gateway server command to import CA certificates and SSL certificates for the SGD servers in the array into the SGD Gateway keystore. See How to Install SGD Server Certificates.

  3. Set up the SGD servers in the array to use the SGD Gateways. Install SGD Gateway certificates on the SGD array, and use the tarantella gateway add command to register the SGD Gateways with the SGD array. See How to Install SGD Gateway Certificates on the SGD Array.

  4. Configure which SGD Client connections can use the SGD Gateways. See How to Configure SGD Client Connections.

SGD Gateway Configuration Tasks

This section includes instructions for configuring the connections used by the SGD Gateway.

The following configuration tasks are described:

Client Device to SGD Gateway Connections

Configuring connections between the client device and an SGD Gateway involves the following configuration tasks:

  1. (Optional) Configure the ports and connections used by the SGD Gateway.

    You configure these settings when you install the SGD Gateway.

    To change these settings, see How to Configure the Ports and Connections for the SGD Gateway.

  2. (Optional) On the SGD Gateway, install an SSL certificate for client connections.

    See How to Install an SSL Certificate for Client Connections Into the Client Keystore.

procedure icon  How to Configure the Ports and Connections for the SGD Gateway

You only need to use this procedure if you want to change the settings you made during installation of the SGD Gateway.

  1. Log in as superuser (root) on the SGD Gateway host.

  2. Run the gateway config create command.


    # /opt/SUNWsgdg/bin/gateway config create

    Answer the on-screen questions, to configure the following:

    • SGD Gateway port settings. The interface and port used by the SGD Gateway for incoming connections.

    • Network entry point. The Internet Protocol (IP) address, or Domain Name System (DNS) name, and port that client devices use to connect to the SGD Gateway. This is not always the same as the address of the SGD Gateway. Depending on the configuration of your network, this can be the address of a load balancer or other external device.

    • Secure connections. Whether to secure the connections between the SGD Gateway and the SGD servers in the array. To use secure connections, the SGD servers in the array must be running in secure mode.

  3. Save the connection and port settings.

    The SGD Gateway is configured using the settings you entered.

procedure icon  How to Install an SSL Certificate for Client Connections Into the Client Keystore

The SSL certificate that the SGD Gateway uses for client connections is called the SGD Gateway SSL certificate. The SSL certificate is stored in the client keystore, /opt/SUNWsgdg/proxy/etc/keystore.client.

By default, the SGD Gateway uses a self-signed SGD Gateway SSL certificate for client connections, but you can replace the self-signed SSL certificate with a certificate signed by a certificate authority (CA).

The following procedure assumes you have an SSL certificate signed by a CA.

The private key you install must be in Privacy Enhanced Mail (PEM) format.

  1. Log in as superuser (root) on the SGD Gateway host.

  2. Copy the SSL certificate and the corresponding private key to the SGD Gateway host.

  3. Import the SSL certificate and private key into the client keystore.

    Use the gateway sslkey import command, as follows:


    # /opt/SUNWsgdg/bin/gateway sslkey import \
--keyfile temp.key \
--keyalg RSA \
--certfile example.com.pem

    Here, the certificate file example.com.pem and the corresponding RSA-encoded private key, temp.key, are imported into the client keystore.

    The existing self-signed SSL certificate in the client keystore is overwritten.

  4. Restart the SGD Gateway.


    caution icon

    Caution - Only use this step if you are not performing initial configuration of the SGD Gateway. Restarting the SGD Gateway at this stage during initial configuration displays an error message, because initial configuration of the SGD Gateway has not been completed.


    Restart the SGD Gateway if you are replacing the SSL certificate on an SGD Gateway that is already configured and running.


    Note - Restarting the SGD Gateway disconnects all user sessions and application sessions that are running through the SGD Gateway.


    On the SGD Gateway host, run the following command:


    # /opt/SUNWsgdg/bin/gateway restart

SGD Gateway to SGD Server Connections

The connections between an SGD Gateway and the SGD servers in the array use certificates for mutual authorization. Configuring these connections involves the following configuration tasks:

  1. Install SGD server certificates on the SGD Gateway.

    See How to Install SGD Server Certificates.

  2. Install the SGD Gateway certificate on the SGD array.

    See How to Install SGD Gateway Certificates on the SGD Array.

  3. Configure SGD Client connections for the SGD Gateway.

    See How to Configure SGD Client Connections.

procedure icon  How to Install SGD Server Certificates

To use this procedure, the SGD servers in the array must be running in secure mode.


Note - Do not use the tarantella security enable command to configure secure connections automatically for the SGD servers in this array. This command turns on firewall forwarding, which is not supported by the SGD Gateway. Instead, configure secure connections manually using the tarantella security start command.


See “Setting Up Secure Client Connections (Manual Configuration)” in Chapter 1 of the Sun Secure Global Desktop 4.5 Administration Guide for more information about how to enable security services on an SGD server.

Repeat the following procedure for each SGD server in the array.

  1. Log in as superuser (root) on the SGD host.

  2. Copy the CA certificate from the SGD server to the SGD Gateway keystore directory.

    The CA certificate for an SGD server is at /opt/tarantella/var/info/certs/PeerCAcert.pem on the SGD host.


    Note - This is the same CA certificate that the SGD server uses for secure intra-array communication.


    The SGD Gateway keystore directory is /opt/SUNWsgdg/proxy/etc.

  3. Copy the SSL certificate from the SGD server to the SGD Gateway keystore directory.

    The SSL certificate for an SGD server running in secure mode is at /opt/tarantella/var/tsp/cert.pem on the SGD host.

    The SGD Gateway keystore directory is /opt/SUNWsgdg/proxy/etc.

  4. Log in as superuser (root) on the SGD Gateway host.

  5. Import the certificates into the SGD Gateway keystore.


    # /opt/SUNWsgdg/bin/gateway server add --server sgd-server1 \
--certfile /opt/SUNWsgdg/proxy/etc/PeerCAcert.pem --url https://sgd1.example.com \
--ssl-certfile /opt/SUNWsgdg/proxy/etc/cert.pem

    The --server option defines the alias names used when storing the certificates in the keystore. In this example, the CA certificate is stored using an alias of sgd-server1, the SSL certificate is stored using an alias of sgd-server1-ssl.

    https://sgd1.example.com is the Uniform Resource Locator (URL) of the SGD web server.

  6. Restart the SGD Gateway.


    Note - Restarting the SGD Gateway disconnects all user sessions and application sessions that are running through the SGD Gateway.


    On the SGD Gateway host, run the following command:


    # /opt/SUNWsgdg/bin/gateway restart

procedure icon  How to Install SGD Gateway Certificates on the SGD Array

Repeat the following procedure for each SGD Gateway.

  1. Export the SGD Gateway certificate.

    1. Log in as superuser (root) on the SGD Gateway host.

    2. Export the SGD Gateway certificate from the SGD Gateway keystore.

      Use the gateway cert export command, as follows:


      # /opt/SUNWsgdg/bin/gateway cert export --certfile gateway1.pem

      The certificate is exported to the file gateway1.pem.

    3. Copy the certificate to the /opt/tarantella/var/tsp directory on the primary SGD server in the array.

  2. Register the SGD Gateway with the SGD array.

    1. On the primary SGD server, log in as superuser (root).

    2. Import the SGD Gateway certificate.


      $ tarantella gateway add --name sgd-gateway1 \
--certfile /opt/tarantella/var/tsp/gateway1.pem

      where sgd-gateway1 is a name used by SGD to identify the SGD Gateway, and gateway1.pem is the SGD Gateway certificate file name.

      To register multiple SGD Gateways at the same time, use the --file option of the tarantella gateway add command. See The tarantella gateway Command for more details.

      Configuration changes made using tarantella gateway add are replicated to the other SGD servers in the array.

procedure icon  How to Configure SGD Client Connections

  •   Configure the SGD Client connections that use the SGD Gateway.

    On the primary SGD server, set the --security-gateway global attribute to define which SGD Clients can use the SGD Gateway, based on their IP address or DNS name.

    To specify that all SGD Client connections are routed through TCP port 443 of a single SGD Gateway gateway1.example.com, use the following command:


    $ tarantella config edit --security-gateway \
"*:sgdg:gateway1.example.com:443"

    To specify that all SGD Client connections are routed through TCP port 443 of an external load balancer lb.example.com, use the following command:


    $ tarantella config edit --security-gateway \
"*:sgdg:lb.example.com:443"


    Note - Changes to the --security-gateway attribute affect all SGD servers in the array. The changes only apply to new user sessions.


    See The security-gateway Attribute for more details about how to use the --security-gateway attribute to define multiple SGD Client connection filters.

Client Device to Load Balancer Connections

Configuring connections between the client device and an external load balancer involves the following configuration tasks:

  1. Configure the load balancer to accept connections from client devices.

    See your load balancer documentation for details of how to do this.

  2. (Optional) Install the SSL certificate for the SGD Gateway on to the load balancer.

    See your load balancer documentation for details of how to do this.

Load Balancer to SGD Gateway Connections

Configuring connections between an external load balancer and the SGD Gateway involves the following configuration tasks:

  1. Configure the ports and connections used by the SGD Gateway.

    See How to Configure the Ports and Connections for the SGD Gateway.

  2. (Optional) On the SGD Gateway, install an SSL certificate for incoming client connections.

    See How to Install an SSL Certificate for Client Connections Into the Client Keystore.

Controlling the SGD Gateway

This section describes how to control the SGD Gateway. The following tasks are described:

Starting the SGD Gateway

To start the SGD Gateway, use the following command:


# /opt/SUNWsgdg/bin/gateway start

Stopping the SGD Gateway


caution icon

Caution - Stopping the SGD Gateway disconnects all user sessions and application sessions that are running through the SGD Gateway. This means that application data can be lost if the SGD Gateway is stopped unexpectedly.


To stop the SGD Gateway, use the following command:


# /opt/SUNWsgdg/bin/gateway stop

When you use the gateway stop command a warning message is displayed, prompting you to confirm that you want to stop the SGD Gateway. Use the --force option of the gateway stop command if you do not want to display this message.


Note - If the SGD Gateway is stopped, users from outside your network cannot connect to SGD using the SGD Gateway. Client devices that have been enabled using the --security-gateway attribute to access SGD directly without going through the SGD Gateway, can still access SGD. See The security-gateway Attribute.


Restarting the SGD Gateway


caution icon

Caution - Restarting the SGD Gateway disconnects all user sessions and application sessions that are running through the SGD Gateway. This means that application data can be lost if the SGD Gateway is restarted unexpectedly.


To restart the SGD Gateway, use the following command:


# /opt/SUNWsgdg/bin/gateway restart

When you use the gateway restart command a warning message is displayed, prompting you to confirm that you want to stop the SGD Gateway. Use the --force option of the gateway restart command if you do not want to display this message.

Removing the SGD Gateway

To remove the SGD Gateway, you remove the software installed on the SGD Gateway host.

procedure icon  How To Remove the SGD Gateway

  1. Log in as superuser (root) on the SGD Gateway host.

  2. Change the SGD Client routing configuration for the SGD array.

    1. Log in as superuser (root) on the primary SGD server.

    2. Edit the --security-gateway attribute for the SGD array.

      For a basic deployment using a single SGD Gateway, run the following command:


      # tarantella config edit --security-gateway ""


      Note - For a load-balanced deployment using multiple SGD Gateways and an external load balancer, you do not need to edit the --security gateway attribute.


  3. Uninstall the SGD Gateway.

    Run the following command:


    # /opt/SUNWsgdg/bin/gateway uninstall

    A warning message is displayed, prompting you to confirm that you want to stop the SGD Gateway.


    caution icon

    Caution - The gateway uninstall command is the only supported method of removing the SGD Gateway. Do not use the pkgrm or rpm commands directly to remove the SGD Gateway.


  4. Remove the SGD Gateway from the list of SGD Gateways registered for the SGD array.

    1. Display the SGD Gateways registered for the SGD array.


      # tarantella gateway list
Installed gateway: gateway1.example.com
Issuer: CN=gateway1.example.com, OU=Marketing, O=Example, L=Boston, ST=Massachusetts, C=US
Serial Number: 1208509056
Subject: CN=gateway2.example.com, OU=Marketing, O=Example, L=Boston, ST=Massachusetts, C=US
Valid from Fri Sep 26 09:57:36 GMT 2008 to Thu Dec 25 09:57:36 GMT 2008

    2. Remove the SGD Gateway from the list of SGD Gateways registered for the SGD array. 


      # tarantella gateway remove --name gateway1.example.com



Sun Secure Global Desktop 4.5 Gateway Administration Guide820-6691-10Table Of Contents Previous ChapterNext ChapterNo Book Index

Copyright © 2009, Sun Microsystems, Inc. All rights reserved.