The reflection service is a collection of RESTful web services used by the routing proxy component of the SGD Gateway. Using the reflection service, an SGD Gateway Administrator can configure routes, services, logging levels, and connections, and show status information for the routing proxy.
This section includes the following reflection service topics:
By default, the reflection service is not enabled for the SGD Gateway.
You enable the reflection service for one or more of the following access methods:
Unauthorized access – Users do not need to authenticate.
By default, unauthorized access is only available from the SGD Gateway host.
See Section C.9.1.1, “How to Enable Unauthorized Access to the Reflection Service” for details of how to enable unauthorized access.
Authorized access – Users must authenticate before accessing the reflection service.
See Section C.9.1.2, “How to Enable Authorized Access to the Reflection Service” for details of how to enable authorized access.
Log in as superuser (root) on the SGD Gateway host.
Enable unauthorized access to the reflection service.
# /opt/SUNWsgdg/bin/gateway config enable --services-reflection
(Optional) Change the interface used by the reflection service.
By default, unauthenticated access to the reflection service is only available from the SGD Gateway host. Enabling unauthenticated access on other interfaces can present a security risk.
The default interface used for unauthorized access to the
reflection service is the localhost
loopback interface. The following example shows how to
enable unauthorized access on all interfaces:
# /opt/SUNWsgdg/bin/gateway config edit \ --services-reflection-binding *:81
(Optional) Change the port used by the reflection service.
The default port used for unauthorized access to the reflection service is TCP port 81. You can change this to another port that is not in use, as follows:
# /opt/SUNWsgdg/bin/gateway config edit \
--services-reflection-binding localhost:portnum
where portnum
is the port
number used by the reflection service.
Restart the SGD Gateway.
# /opt/SUNWsgdg/bin/gateway restart
Access the reflection service.
On the SGD Gateway host, you can start a
browser and go to
http://localhost:81
.
The home page for the reflection service is shown.
On the SGD Gateway host, log in as superuser (root).
Export the certificate and private key for the reflection service.
The certificate and private key for the reflection service
are stored in the reflection service keystore, at
/opt/SUNWsgdg/proxy/etc/keystore.reflection
.
This keystore is created automatically during installation
of the SGD Gateway.
By default, the reflection service keystore contains a single, self-signed certificate and key pair.
Export the certificate for the reflection service.
# /opt/SUNWsgdg/java/default/bin/keytool -exportcert \ -aliasserver-name
-rfc \ -keystore /opt/SUNWsgdg/proxy/etc/keystore.reflection \ -storepass "$(cat /opt/SUNWsgdg/etc/password)" \ -fileclient.pem
where server-name
is the
alias used for the reflection service certificate in
the reflection keystore and
client.pem
is the file name
of the exported certificate.
See the JDK Tools and Utilities documentation for details on how to use the keytool application.
Export the private key for the reflection service.
Use the KeyManager application included with the SGD Gateway.
# /opt/SUNWsgdg/java/default/bin/java \ -jar /opt/SUNWsgdg/proxy/KeyManager.jar export \ --keyfileclient.key
\ --keystore /opt/SUNWsgdg/proxy/etc/keystore.reflection \ --keyaliasalias-name
\ --keypass "$(cat /opt/SUNWsgdg/etc/password)" \ --storepass "$(cat /opt/SUNWsgdg/etc/password)"
where alias-name
is the
alias used for the reflection service key in the
reflection keystore and
client.key
is the file name
of the exported key.
Install the certificate and private key on the client device.
The certificate and private key are used by the client device to authorize to the reflection service.
To import the certificate and key into a browser certificate store you must first convert the certificate and key into a PKCS12 format file. For example:
# openssl pkcs12 -export -inmycert.crt
-inkeymycert_key.pem
-outmycert.p12
This command converts the certificate file
mycert.crt
and associated private key
mycert_key.pem
into a PKCS12 format
certificate file mycert.p12
.
For more details of how to import a PKCS12 format certificate into your browser, see the online documentation for your browser.
Enable authorized access to the reflection service.
On the SGD Gateway host, run the following command:
# /opt/SUNWsgdg/bin/gateway config enable --services-reflection-auth
(Optional) Change the interface and port used by the reflection service.
The default binding used for authorized access to the reflection service is TCP port 82 on all interfaces. You can change this to another interface and a port that is not in use, as follows:
# /opt/SUNWsgdg/bin/gateway config edit \ --services-reflection-bindingint
:portnum
where int
is the interface, and
portnum
is the port number used
by the reflection service.
Restart the SGD Gateway.
# /opt/SUNWsgdg/bin/gateway restart
Connect to the reflection service from the client device, using the certificate and private key.
Using the curl command:
$ curl --certclient.pem
--keyclient.key
-k -X GET https://gateway.example.com
:82
In this example, the curl command
is used to access the home page of the reflection
service at
https://
,
where gateway.example.com
:82gateway.example.com
is the name of the SGD Gateway. The
certificate and private key for the reflection service
are client.pem
and
client.key
.
Using a browser:
Go to
https://
,
where gateway.example.com
:82gateway.example.com
is the name of the SGD Gateway.
The home page for the reflection service is shown.
Use a client application to access the RESTful web services provided by the reflection service. Examples of suitable client applications include the following:
Browser. Using a browser
is the simplest method of accessing the reflection service.
However, a browser only supports HTTP GET
requests and therefore limits access to only those RESTful
web services that retrieve information. In practice, using a
browser is helpful for tasks such as displaying status
information and listing routes and services for the routing
proxy.
curl. This is a
command-line tool for UNIX and Linux platforms that supports
HTTP GET
, PUT
,
POST
, and DELETE
requests. This means that the full range of RESTful web
services for the reflection service can be used. Output from
this tool can be redirected to a file, or to another program
for further processing.
Alternatively, if you have your own client application that supports RESTful web services, you can use it to access the reflection service.
You do not need to restart the SGD Gateway when you use the reflection service to change the configuration of the routing proxy.
Data can be returned from the reflection service in the following output formats:
ASCII. This is the default output format. Data is returned in tab-delimited ASCII format. This output format is useful if the data is to undergo further processing, such as parsing.
HTML. Data is returned in
HTML format, suitable for displaying in a browser. To return
HTML output, append /html
to the end of
the web service Uniform Resource Identifier (URI).
Table C.1, “RESTful Web Services for the SGD Gateway Reflection Service” lists the RESTful web services for the SGD Gateway reflection service.
Table C.1. RESTful Web Services for the SGD Gateway Reflection Service
Relative URI | HTTP Request Method | Description |
---|---|---|
|
| Shows high-level information for the routing proxy, such as the uptime. |
|
| Lists the available services. A service represents an entry point from which the routing proxy creates incoming connections. |
|
|
Lists information for a service, identified by
|
|
|
Starts a service, identified by
|
|
|
Stops a service, identified by
|
|
| Lists the available clients. A client represents an exit point on which the routing proxy constructs outgoing connections. |
|
|
Lists information for a client, identified by
|
|
| Lists the available routes. A route represents a path through the routing proxy, from incoming connections through services to outgoing connections through clients. |
|
|
Lists information for a route, identified by
|
|
|
Starts a route, identified by
|
|
|
Stops a route, identified by
|
|
|
Lists the connections for a specific route,
identified by |
|
|
Terminates a connection, identified by
|
|
| Lists all currently running connections, for all routes. |
|
| Shows the global logging level. |
|
| Sets the routing proxy's global logging level. |
|
| Shows the logging level for a specific component of the routing proxy. |
|
| Sets the logging level for a specific component of the routing proxy. |
To access a RESTful web service, append the relative URI for the web service to the URL of the reflection service.
For example, to list the available routes for an
SGD Gateway,
gateway.example.com
, append
/route
to the URL of the reflection
service, as follows:
$ curl --certclient.pem
--keyclient.key
-k -X GET https://gateway.example.com
:82/route
where client.pem
and
client.key
are the certificate and
private key for the reflection service. In this example, the
client is authorized before accessing the reflection service.
All of the following examples use the curl command as a client application to access the reflection service.
The examples use authenticated access to the reflection
service on an SGD Gateway called
gateway.example.com
. The client is
authorized using a certificate,
client.pem
, and a private key,
client.key
.
To list the available services for the SGD Gateway:
$ curl --certclient.pem
--keyclient.key
-k \ -X GET https://gateway.example.com
:82/service
To stop a route, specify the Route Id that the reflection service uses for the route:
$ curl --certclient.pem
--keyclient.key
-k \ -X GET https://gateway.example.com
:82/route Route Id Route Uptime Service Id ... 0 21h18m20s743m ssgd-route-service ... 1 21h18m20s736m shttp-ssl-service ... $ curl --certclient.pem
--keyclient.key
-k \ -X DELETE https://gateway.example.com
:82/route/1
To set the global logging level to FINER:
$ curl --certclient.pem
--keyclient.key
-k \ -X PUT https://gateway.example.com
:82/logging/level/FINER