2. Configuring the SGD Gateway
A. SGD Gateway Architecture Overview
The tarantella 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.
gateway start | stop | restart | config | server | status | setup | version | sslcert | sslkey | cert | key | setup | uninstall
The available gateway commands are shown in the following table.
|
Note - All gateway commands include a --help option. You can use this option to display help for the command.
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
Starts the SGD Gateway.
gateway start
Starts the SGD Gateway.
The following example starts the SGD Gateway.
# /opt/SUNWsgdg/bin/gateway start SGD Gateway started successfully
Stops the SGD Gateway.
gateway stop [--force]
Stops the SGD Gateway, after prompting the user for confirmation.
The --force option stops the SGD Gateway, without asking for confirmation.
The following example stops the SGD Gateway, prompting the user for confirmation.
# /opt/SUNWsgdg/bin/gateway stop
Stops and then restarts the SGD Gateway.
gateway restart [--force]
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.
The following example stops and restarts the SGD Gateway, prompting the user for confirmation.
# /opt/SUNWsgdg/bin/gateway restart
Configures the SGD Gateway. The gateway config command configures secure connections, ports, and reverse proxy server settings for the SGD Gateway.
gateway config create | show
The following table shows the available subcommands for this command.
|
The following example lists the current configuration for the SGD Gateway.
# /opt/SUNWsgdg/bin/gateway config list
Creates a new configuration for the SGD Gateway, overwriting the current configuration.
gateway config create { [ --interface interface:port ] [ --entry-point ip-address:port ] [ --out plaintext | ssl ] } | --file file
The following table shows the available options for this command.
|
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.
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
Lists the current SGD Gateway configuration.
gateway config list [ --binding ] [ --routes-http-maxcon ] [ --routes-aip-maxcon ] [ --routes-reverseproxy-redirect ] [ --services-reflection-binding ] [ --services-reflection-auth-binding ]
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.
|
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
Edits the current SGD Gateway configuration.
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 ]
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.
|
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
Enables one or more SGD Gateway services.
gateway config enable [ --services-reflection ] [ --services-reflection-auth ] [ --routes-http-redirect ]
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.
|
The following example enables authenticated access to the SGD Gateway reflection service.
# /opt/SUNWsgdg/bin/gateway config enable --services-reflection-auth
Disables one or more SGD Gateway services.
gateway config disable [ --services-reflection ] [ --services-reflection-auth ] [ --routes-http-redirect ]
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.
|
The following example disables authenticated access to the SGD Gateway reflection service.
# /opt/SUNWsgdg/bin/gateway config disable --services-reflection-auth
Authorizes SGD servers to use the SGD Gateway.
gateway server add | remove | list
The following table shows the available subcommands for this command.
|
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
Authorizes an SGD server to use the SGD Gateway.
gateway server add --server server-name --certfile cert-file --url server-url [ --ssl-certfile ssl-cert ]
The following table shows the available options for this command.
|
The gateway server add command does the following:
Imports the CA certificate for the SGD server into the SGD Gateway keystore, at /opt/SUNWsgdg/proxy/etc/keystore. The CA certificate is stored to the keystore using an alias with the same name as the SGD server specified by the --server option.
Imports the SSL certificate for the SGD server into the SGD Gateway keystore, at /opt/SUNWsgdg/proxy/etc/keystore. The SSL certificate is stored to the keystore using an alias constructed by appending “-ssl” to the SGD server name specified by the --server option.
Adds the SGD server to the load balancing group used by the Apache reverse proxy server
Note - After using gateway server add, you must restart the SGD Gateway for any changes to take effect.
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.
Removes authorization for an SGD server to use the SGD Gateway.
gateway server remove --server server-name
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.
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
Shows details for the SGD servers authorized to use the SGD Gateway.
gateway server list
This command shows certificate details and URLs for the SGD servers that are authorized to use the SGD Gateway.
The following example lists details of the authorized SGD servers for the SGD Gateway.
# /opt/SUNWsgdg/bin/gateway server list
Displays the current status of the SGD Gateway.
gateway status
This command indicates if the SGD Gateway is started, stopped, or if there is a problem.
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
Displays the version number of the SGD Gateway software.
gateway version
Displays the version number of the SGD Gateway.
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
Print or exports the SGD Gateway SSL certificate stored in the client keystore.
gateway sslcert export | print
The following table shows the available subcommands for this command.
|
The following example prints the SGD Gateway SSL certificate stored in the client keystore.
# /opt/SUNWsgdg/bin/gateway sslcert print
Exports the SGD Gateway SSL certificate from the client keystore.
gateway sslcert export --certfile cert-file
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.
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
Prints the SGD Gateway SSL certificate.
gateway sslcert print
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.
The following example prints the SGD Gateway SSL certificate stored in the client keystore.
# /opt/SUNWsgdg/bin/gateway sslcert print
Manages SSL key and certificate entries in the client keystore.
gateway sslkey import | export
The following table shows the available subcommands for this command.
|
The following example exports the SGD Gateway SSL certificate stored in the client keystore.
# /opt/SUNWsgdg/bin/gateway sslkey export --keyfile gateway-ssl.key
Imports an SSL key and certificate into the client keystore.
gateway sslkey import --keyfile key-file [ --keyalg RSA|DSA ] { --certfile cert-file | --certfile cert-file.. [ --cacertfile ca-cert-file ] } [ --alwaysoverwrite ]
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.
|
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-----
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
Exports the SGD Gateway SSL private key from the client keystore.
gateway sslkey export --keyfile key-file [ --keypass passwd ]
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.
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
Exports the SGD Gateway certificate from the SGD Gateway keystore.
gateway cert export --certfile file-name
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.
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
Imports an SGD Gateway key and SGD Gateway certificate into the SGD Gateway keystore.
gateway key import --keyfile key-file [ --keyalg RSA|DSA ] { --certfile cert-file | --certfile cert-file.. [ --cacertfile ca-cert-file ] } [ --alwaysoverwrite ]
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.
|
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-----
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
Runs the setup program for the SGD Gateway.
gateway setup
Answer the on-screen questions to configure ports, interfaces, and security settings used by the SGD Gateway.
The following example runs the SGD Gateway setup program.
# /opt/SUNWsgdg/bin/gateway setup
Uninstalls the SGD Gateway software.
gateway uninstall
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.
The following example uninstalls the SGD Gateway software from the host where the command is run.
# /opt/SUNWsgdg/bin/gateway uninstall