Exit Print View

Oracle Secure Global Desktop Gateway Administration Guide for Version 4.6

Document Information

Preface

1.  Installing the SGD Gateway

2.  Configuring the SGD Gateway

A.  SGD Gateway Architecture Overview

B.  Command-Line Reference

The gateway Command

Syntax

Description

Examples

gateway start

Syntax

Description

Examples

gateway stop

Syntax

Description

Examples

gateway restart

Syntax

Description

Examples

gateway config

Syntax

Description

Examples

gateway config create

Syntax

Description

Examples

gateway config list

Syntax

Description

Examples

gateway config edit

Syntax

Description

Examples

gateway config enable

Syntax

Description

Examples

gateway config disable

Syntax

Description

Examples

gateway server

Syntax

Description

Examples

gateway server add

Syntax

Description

Examples

gateway server remove

Syntax

Description

Examples

gateway server list

Syntax

Description

Examples

gateway status

Syntax

Description

Examples

gateway version

Syntax

Description

Examples

gateway sslcert

Syntax

Description

Examples

gateway sslcert export

Syntax

Description

Examples

gateway sslcert print

Syntax

Description

Examples

gateway sslkey

Syntax

Description

Examples

gateway sslkey import

Syntax

Description

Examples

gateway sslkey export

Syntax

Description

Examples

gateway cert export

Syntax

Description

Examples

gateway key import

Syntax

Description

Examples

gateway setup

Syntax

Description

Examples

gateway uninstall

Syntax

Description

Examples

The tarantella gateway Command

Syntax

Description

Examples

tarantella gateway add

Syntax

Description

Examples

tarantella gateway list

Syntax

Description

Examples

tarantella gateway remove

Syntax

Description

Examples

The --security-gateway Attribute

C.  Advanced Configuration

D.  Troubleshooting the SGD Gateway

The gateway Command

Use the gateway command to configure and control the SGD Gateway.


Note - The full path of the gateway command is /opt/SUNWsgdg/bin/gateway.


Syntax

gateway start | stop | restart | config | server | status | setup | version | sslcert | sslkey | cert | key | setup | uninstall

Description

The available gateway commands are shown in the following table.

Command
Description
More Information
gateway start
Starts the SGD Gateway
gateway stop
Stops the SGD Gateway
gateway restart
Stops and then restarts the SGD Gateway
gateway config
Configures the SGD Gateway, and updates the Apache reverse proxy configuration files
gateway server
Installs SGD server security certificates and configures load balancing for the SGD array
gateway status
Displays the current status for the SGD Gateway
gateway version
Displays the version number of the SGD Gateway
gateway sslcert
Exports and prints the Secure Sockets Layer (SSL) certificate in the client keystore
gateway sslkey
Manages the private key and certificate in the client keystore
gateway cert export
Exports the SGD Gateway certificate from the SGD Gateway keystore
gateway key import
Imports a private key and certificate into the SGD Gateway keystore
gateway setup
Runs the SGD Gateway setup program
gateway uninstall
Uninstalls the SGD Gateway software

Note - All gateway commands include a --help option. You can use this option to display help for the command.


Examples

The following example starts the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway start

The following example means that the SGD server server.example.com is not authorized to use the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway server remove --server server.example.com

gateway start

Starts the SGD Gateway.

Syntax
gateway start
Description

Starts the SGD Gateway.

Examples

The following example starts the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway start
SGD Gateway started successfully

gateway stop

Stops the SGD Gateway.

Syntax
gateway stop [--force]
Description

Stops the SGD Gateway, after prompting the user for confirmation.

The --force option stops the SGD Gateway, without asking for confirmation.

Examples

The following example stops the SGD Gateway, prompting the user for confirmation.

# /opt/SUNWsgdg/bin/gateway stop

gateway restart

Stops and then restarts the SGD Gateway.

Syntax
gateway restart [--force]
Description

Stops and then restarts the SGD Gateway. Before stopping the SGD Gateway, the user is prompted for confirmation.

The --force option stops the SGD Gateway, without asking for confirmation.

Examples

The following example stops and restarts the SGD Gateway, prompting the user for confirmation.

# /opt/SUNWsgdg/bin/gateway restart

gateway config

Configures the SGD Gateway. The gateway config command configures secure connections, ports, and reverse proxy server settings for the SGD Gateway.

Syntax
gateway config create | show
Description

The following table shows the available subcommands for this command.

Subcommand
Description
More Information
create
Creates a new configuration for the SGD Gateway
list
Lists the current configuration for the SGD Gateway
edit
Edits the current configuration for the SGD Gateway
enable
Enables an SGD Gateway service
disable
Disables an SGD Gateway service
Examples

The following example lists the current configuration for the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway config list

gateway config create

Creates a new configuration for the SGD Gateway, overwriting the current configuration.

Syntax
gateway config create { [ --interface interface:port ]
                        [ --entry-point ip-address:port ]
                        [ --out plaintext | ssl ]
                       } | --file file
Description

The following table shows the available options for this command.

Option
Description
--interface
Interface and port that the SGD Gateway listens on for incoming proxy connections. The default is Transmission Control Protocol (TCP) port 443, on all interfaces.
--entry-point
Entry point for the network. This is the Internet Protocol (IP) address, and port that clients use to connect to the SGD Gateway. You can specify a Domain Name System (DNS) address instead of an IP address.
--out
Format of outgoing traffic from the SGD Gateway to the SGD servers in the array. If you are using secure connections, choose ssl.
--file
Specifies a file containing configuration settings.

Note - If no options are specified for the gateway config create command, a series of online prompts are displayed, enabling you to type in the required settings.


If you use the --file option for gateway config create, the specified file must be of the same format as the /opt/SUNWsgdg/etc/gatewayconfig.xml file. This file is created during initial configuration of the SGD Gateway, as described in How to Configure the Ports and Connections for the SGD Gateway.

Examples

The following example configures an SGD Gateway to listen on TCP port 443 for connections from the network entry point, at 192.168.0.1. Secure connections are used between the SGD Gateway and the SGD servers in the array.

# /opt/SUNWsgdg/bin/gateway config create --interface *:443 \
--entry-point 192.168.0.1:443 --out ssl

gateway config list

Lists the current SGD Gateway configuration.

Syntax
gateway config list [ --binding ]
                    [ --routes-http-maxcon ]
                    [ --routes-aip-maxcon ]
                    [ --routes-reverseproxy-redirect ]
                    [ --services-reflection-binding ]
                    [ --services-reflection-auth-binding ]
Description

The command-line options enable you to list specific configuration settings. If no options are specified, the full configuration details for the SGD Gateway are displayed.

The current SGD Gateway configuration is stored in the /opt/SUNWsgdg/etc/gatewayconfig.xml file.

The following table shows the available options for this command.

Option
Description
--binding
Interface and port that the SGD Gateway listens on for incoming proxy connections
--routes-http-maxcon
Maximum number of Hypertext Transfer Protocol (HTTP) connections
--routes-aip-maxcon
Maximum number of Adaptive Internet Protocol (AIP) connections
--routes-reverseproxy-redirect
HTTP redirection port
--services-reflection-binding
Interface and port used for unauthenticated access to the SGD Gateway reflection service
--services-reflection-auth-binding
Interface and port used for authenticated access to the SGD Gateway reflection service
Examples

The following example shows binding configuration and the maximum number of AIP connections for the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway config list --binding --routes-aip-maxcon
binding: *:443
routes-aip-maxcon: 2920

The following example shows full details for the current SGD Gateway configuration.

# /opt/SUNWsgdg/bin/gateway config list
binding: *:443
routes-http-maxcon: 100
routes-aip-maxcon: 2920
routes-reverseproxy-redirect: null
services-reflection-binding: localhost:81
services-reflection-auth-binding: *:82

gateway config edit

Edits the current SGD Gateway configuration.

Syntax
gateway config edit [ --binding int:port ]
                    [ --routes-http-maxcon num ]
                    [ --routes-aip-maxcon num ]
                    [ --routes-reverseproxy-redirect port ]
                    [ --services-reflection-binding int:port ]
                    [ --services-reflection-auth-binding int:port ]
Description

The command-line options enable you to edit specific configuration settings. You must specify at least one command-line option.

The current SGD Gateway configuration is stored in the /opt/SUNWsgdg/etc/gatewayconfig.xml file.

You must restart the SGD Gateway to enable any configuration changes you make.

The following table shows the available options for this command.

Option
Description
--binding
Interface and port that the SGD Gateway listens on for incoming proxy connections. The default is TCP port 443, on all interfaces.
--routes-http-maxcon
Maximum number of HTTP connections. The default value is configured at install time and depends on the memory resources available on the SGD Gateway. See Tuning the SGD Gateway.
--routes-aip-maxcon
Maximum number of AIP connections. The default value is configured at install time and depends on the memory resources available on the SGD Gateway. See Tuning the SGD Gateway.
--routes-reverseproxy-redirect
HTTP redirection port. The default is TCP port 8080.
--services-reflection-binding
Interface and port used for unauthenticated access to the SGD Gateway reflection service. The default is TCP port 81 on the localhost loopback interface.
--services-reflection-auth-binding
Interface and port used for authenticated access to the SGD Gateway reflection service. The default is TCP port 82 on all interfaces.
Examples

The following example changes the maximum number of HTTP and AIP connections for the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway config edit --routes-http-maxcon 200
# /opt/SUNWsgdg/bin/gateway config edit --routes-aip-maxcon 3000

gateway config enable

Enables one or more SGD Gateway services.

Syntax
gateway config enable [ --services-reflection ]
                      [ --services-reflection-auth ]
                      [ --routes-http-redirect ]
Description

Use the command line options to enable specific SGD Gateway services. You must specify at least one command-line option.


Note - After using this command to enable a service, you must restart the SGD Gateway to start the service.


The following table shows the available options for this command.

Option
Description
--services-reflection
Enables unauthenticated access to the SGD Gateway reflection service.

By default, this service is disabled.

See The Reflection Service for more details about the SGD Gateway reflection service.

--services-reflection-auth
Enables authenticated access to the SGD Gateway reflection service.

By default, this service is disabled.

See The Reflection Service for more details about the SGD Gateway reflection service.

--routes-http-redirect
Enables the HTTP redirection service.

By default, this service is disabled.

Examples

The following example enables authenticated access to the SGD Gateway reflection service.

# /opt/SUNWsgdg/bin/gateway config enable --services-reflection-auth

gateway config disable

Disables one or more SGD Gateway services.

Syntax
gateway config disable [ --services-reflection ]
                       [ --services-reflection-auth ]
                       [ --routes-http-redirect ]
Description

Use the command line options to disable specific SGD Gateway services. You must specify at least one command-line option.


Note - After using this command to disable a service, you must restart the SGD Gateway to stop the service.


The following table shows the available options for this command.

Option
Description
--services-reflection
Disables unauthenticated access to the SGD Gateway reflection service.

By default, this service is disabled.

See The Reflection Service for more details about the SGD Gateway reflection service.

--services-reflection-auth
Disables authenticated access to the SGD Gateway reflection service.

By default, this service is disabled.

See The Reflection Service for more details about the SGD Gateway reflection service.

--routes-http-redirect
Disables the HTTP redirection service.

By default, this service is disabled.

Examples

The following example disables authenticated access to the SGD Gateway reflection service.

# /opt/SUNWsgdg/bin/gateway config disable --services-reflection-auth

gateway server

Authorizes SGD servers to use the SGD Gateway.

Syntax
gateway server add | remove | list
Description

The following table shows the available subcommands for this command.

Subcommand
Description
More Information
add
Authorizes an SGD server to use the SGD Gateway
remove
Removes authorization for an SGD server to use the SGD Gateway
list
Lists the SGD servers authorized to use the SGD Gateway
Examples

The following example removes authorization to use the SGD Gateway for the SGD server sgd.example.com.

# /opt/SUNWsgdg/bin/gateway server remove --server sgd.example.com

gateway server add

Authorizes an SGD server to use the SGD Gateway.

Syntax
gateway server add --server server-name 
                   --certfile cert-file 
                   --url server-url 
                 [ --ssl-certfile ssl-cert ]
Description

The following table shows the available options for this command.

Option
Description
--server
DNS name of the SGD server
--cert-file
Certificate Authority (CA) certificate for the SGD server
--url
Uniform Resource Locator (URL) for the SGD web server
--ssl-certfile
SSL certificate for the SGD server

The gateway server add command does the following:


Note - After using gateway server add, you must restart the SGD Gateway for any changes to take effect.


Examples

The following example adds the CA certificate PeerCAcert.pem to the SGD Gateway keystore, using the alias sgd.example.com. The SSL certificate cert.pem is also added to the keystore, using the alias sgd.example.com-ssl.

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

In this example, the URL for the SGD web server, https://sgd.example.com, is added to the reverse proxy load balancing group and a configuration file is created at /opt/SUNWsgdg/httpd/apache-version/conf/extra/gateway/servers/conf/sgd.example.com.conf.

gateway server remove

Removes authorization for an SGD server to use the SGD Gateway.

Syntax
gateway server remove --server server-name
Description

The CA certificate and SSL certificate for the SGD server are removed from the SGD Gateway keystore.


Note - After using gateway server remove, you must restart the SGD Gateway for any changes to take effect.


Examples

The following example removes authorization for the SGD server sgd.example.com to use the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway server remove --server sgd.example.com

gateway server list

Shows details for the SGD servers authorized to use the SGD Gateway.

Syntax
gateway server list
Description

This command shows certificate details and URLs for the SGD servers that are authorized to use the SGD Gateway.

Examples

The following example lists details of the authorized SGD servers for the SGD Gateway.

# /opt/SUNWsgdg/bin/gateway server list

gateway status

Displays the current status of the SGD Gateway.

Syntax
gateway status
Description

This command indicates if the SGD Gateway is started, stopped, or if there is a problem.

Examples

The following example displays status information for the SGD Gateway. In this example, the SGD Gateway is stopped.

# /opt/SUNWsgdg/bin/gateway status
SGD Gateway status: STOPPED

gateway version

Displays the version number of the SGD Gateway software.

Syntax
gateway version
Description

Displays the version number of the SGD Gateway.

Examples

The following example displays the SGD Gateway version installed on the host where the command is run.

# /opt/SUNWsgdg/bin/gateway version
Oracle Secure Global Desktop Gateway 4.50.301

gateway sslcert

Print or exports the SGD Gateway SSL certificate stored in the client keystore.

Syntax
gateway sslcert export | print 
Description

The following table shows the available subcommands for this command.

Subcommand
Description
More Information
export
Exports the SGD Gateway SSL certificate from the client keystore
print
Prints the SGD Gateway SSL certificate stored in the client keystore
Examples

The following example prints the SGD Gateway SSL certificate stored in the client keystore.

# /opt/SUNWsgdg/bin/gateway sslcert print

gateway sslcert export

Exports the SGD Gateway SSL certificate from the client keystore.

Syntax
gateway sslcert export --certfile cert-file
Description

Exports the SGD Gateway SSL certificate from the client keystore, at /opt/SUNWsgdg/proxy/etc/keystore.client. The certificate is written to the file specified by the --certfile option.

To access the client keystore, this command uses the password in /opt/SUNWsgdg/etc/password. If this file is not present, the command prompts for a password.

Examples

The following example exports the SGD Gateway SSL certificate from the client keystore to the file, gateway-ssl.pem.

# /opt/SUNWsgdg/bin/gateway sslcert export --certfile gateway-ssl.pem

gateway sslcert print

Prints the SGD Gateway SSL certificate.

Syntax
gateway sslcert print 
Description

Prints the SGD Gateway SSL certificate stored in the client keystore, at /opt/SUNWsgdg/proxy/etc/keystore.client.

The command writes details of the certificate to the terminal window.

To access the client keystore, this command uses the password in /opt/SUNWsgdg/etc/password. If this file is not present, the command prompts for a password.

Examples

The following example prints the SGD Gateway SSL certificate stored in the client keystore.

# /opt/SUNWsgdg/bin/gateway sslcert print

gateway sslkey

Manages SSL key and certificate entries in the client keystore.

Syntax
gateway sslkey import | export 
Description

The following table shows the available subcommands for this command.

Subcommand
Description
More Information
import
Imports a private key and certificate into the client keystore
export
Exports a private key from the client keystore
Examples

The following example exports the SGD Gateway SSL certificate stored in the client keystore.

# /opt/SUNWsgdg/bin/gateway sslkey export --keyfile gateway-ssl.key

gateway sslkey import

Imports an SSL key and certificate into the client keystore.

Syntax
gateway sslkey import --keyfile key-file 
                    [ --keyalg RSA|DSA ]
                    { --certfile cert-file |
                      --certfile cert-file.. [ --cacertfile ca-cert-file ] }
                    [ --alwaysoverwrite ]
Description

Imports an SSL private key, and the corresponding SSL certificate, into the client keystore, at /opt/SUNWsgdg/proxy/etc/keystore.client. By default, this keystore contains a single self-signed certificate.

If the client keystore already has an entry, this command overwrites it. By default, a confirmation prompt is shown before overwriting the keystore entry.

To access the client keystore, this command uses the password in /opt/SUNWsgdg/etc/password. If this file is not present, the command prompts for a password.

The following table shows the available options for this command.

Option
Description
--keyfile
File containing the SSL private key. The key must be in Privacy Enhanced Mail (PEM) format.
--keyalg
Encoding algorithm used by the private key. Options are RSA and Digital Signature Algorithm (DSA). By default, RSA is selected.
--certfile
SSL certificate file.
--cacertfile
CA certificate or root certificate file.
--alwaysoverwrite
Do not prompt before overwriting the entry in the client keystore.

To import a certificate chain, use the --cacertfile option to specify the Intermediate CA certificate. All certificates in the chain must be in PEM format.

If a certificate chain uses multiple CA certificates, combine all the CA certificates in the chain into a single file. The CA certificate used to sign the server certificate must appear first, for example:

-----BEGIN CERTIFICATE-----
...Intermediate CA’s certificate...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...CA root certificate...
-----END CERTIFICATE-----
Examples

The following example imports an RSA-encoded SSL private key gateway1-ssl.key, and the corresponding SSL certificate gateway1-ssl.pem, into the client keystore.

# /opt/SUNWsgdg/bin/gateway sslkey import \
--keyfile gateway1-ssl.key \
--certfile gateway1-ssl.pem

The following example imports an RSA-encoded SSL private key and an SSL certificate chain into the client keystore. The Intermediate CA certificate is gateway1-ca.pem.

# /opt/SUNWsgdg/bin/gateway sslkey import \
--keyfile gateway1-ssl.key \
--certfile gateway1-ssl.pem \
--cafile gateway1-ca.pem

gateway sslkey export

Exports the SGD Gateway SSL private key from the client keystore.

Syntax
gateway sslkey export --keyfile key-file [ --keypass passwd ]
Description

Exports the SGD Gateway SSL private key from the client keystore, at /opt/SUNWsgdg/proxy/etc/keystore.client. The private key is written to the file specified by the --keyfile option.

A password for the private key can be specified using the --keypass option. By default, the password from /opt/SUNWsgdg/etc/password is used.

Examples

The following example exports the SGD Gateway SSL private key from the client keystore to the file, gateway-ssl.key.

# /opt/SUNWsgdg/bin/gateway sslkey export --keyfile gateway-ssl.key

gateway cert export

Exports the SGD Gateway certificate from the SGD Gateway keystore.

Syntax
gateway cert export --certfile file-name
Description

Exports the SGD Gateway certificate from the SGD Gateway keystore, at /opt/SUNWsgdg/proxy/etc/keystore. The certificate is written to the file specified by the --certfile option.

To access the SGD Gateway keystore, this command uses the password in /opt/SUNWsgdg/etc/password. If this file is not present, the command prompts for a password.

Examples

The following example exports the SGD Gateway certificate from the SGD Gateway keystore to the file, gateway1.pem.

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

gateway key import

Imports an SGD Gateway key and SGD Gateway certificate into the SGD Gateway keystore.

Syntax
gateway key import --keyfile key-file 
                 [ --keyalg RSA|DSA ]
                 { --certfile cert-file |
                   --certfile cert-file.. [ --cacertfile ca-cert-file ] }
                 [ --alwaysoverwrite ]
Description

Imports a private key, and the corresponding public key certificate, into the SGD Gateway keystore, at /opt/SUNWsgdg/proxy/etc/keystore.

If the keystore already has an SGD Gateway key entry, it is overwritten. By default, a confirmation prompt is shown.

To access the SGD Gateway keystore, this command uses the password in /opt/SUNWsgdg/etc/password. If this file is not present, the command prompts for a password.

The following table shows the available options for this command.

Option
Description
--keyfile
File containing the private key. The key must be in PEM format.
--keyalg
Encoding algorithm used by the private key. Options are RSA and DSA. By default, RSA is selected.
--certfile
SSL certificate file.
--cacertfile
CA or root certificate file.
--alwaysoverwrite
Do not prompt before overwriting an entry in the keystore.

To import a certificate chain, use the --cacertfile option to specify an Intermediate CA certificate. All certificates in the chain must be in PEM format.

If a certificate chain uses multiple CA certificates, combine all the CA certificates in the chain into a single file. The CA certificate used to sign the server certificate must appear first, for example:

-----BEGIN CERTIFICATE-----
...Intermediate CA’s certificate...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...CA root certificate...
-----END CERTIFICATE-----
Examples

The following example imports an RSA-encoded private key gateway1.key, and the corresponding public key certificate gateway1.pem, into the SGD Gateway keystore.

# /opt/SUNWsgdg/bin/gateway key import \
--keyfile gateway1.key \
--certfile gateway1.pem

The following example imports a private key and a certificate chain into the SGD Gateway keystore. The Intermediate CA certificate is gateway1-ca.pem.

# /opt/SUNWsgdg/bin/gateway key import \
--keyfile gateway1.key \
--certfile gateway1.pem \
--cafile gateway1-ca.pem

gateway setup

Runs the setup program for the SGD Gateway.

Syntax
gateway setup
Description

Answer the on-screen questions to configure ports, interfaces, and security settings used by the SGD Gateway.

Examples

The following example runs the SGD Gateway setup program.

# /opt/SUNWsgdg/bin/gateway setup

gateway uninstall

Uninstalls the SGD Gateway software.

Syntax
gateway uninstall
Description

Stops the SGD Gateway and removes the SGD Gateway software, including all configuration information.

Before stopping the SGD Gateway, the command prompts the user for confirmation.

Examples

The following example uninstalls the SGD Gateway software from the host where the command is run.

# /opt/SUNWsgdg/bin/gateway uninstall