C.9. The Reflection Service

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:

C.9.1. Enabling the Reflection Service

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:

C.9.1.1. How to Enable Unauthorized Access to the Reflection Service

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

  2. Enable unauthorized access to the reflection service.

    # /opt/SUNWsgdg/bin/gateway config enable --services-reflection
  3. (Optional) Change the interface used by the reflection service.

    Caution

    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
  4. (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.

  5. Restart the SGD Gateway.

    # /opt/SUNWsgdg/bin/gateway restart
  6. 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.

C.9.1.2. How to Enable Authorized Access to the Reflection Service

  1. On the SGD Gateway host, log in as superuser (root).

  2. 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.

    1. Export the certificate for the reflection service.

      # /opt/SUNWsgdg/java/default/bin/keytool -exportcert \
      -alias server-name -rfc \
      -keystore /opt/SUNWsgdg/proxy/etc/keystore.reflection \
      -storepass "$(cat /opt/SUNWsgdg/etc/password)" \
      -file client.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.

    2. 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 \
      --keyfile client.key \
      --keystore /opt/SUNWsgdg/proxy/etc/keystore.reflection \
      --keyalias alias-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.

  3. 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 -in mycert.crt -inkey mycert_key.pem -out mycert.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.

  4. 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
  5. (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-binding int:portnum
    

    where int is the interface, and portnum is the port number used by the reflection service.

  6. Restart the SGD Gateway.

    # /opt/SUNWsgdg/bin/gateway restart
  7. Connect to the reflection service from the client device, using the certificate and private key.

    • Using the curl command:

      $ curl --cert client.pem --key client.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://gateway.example.com:82, where gateway.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://gateway.example.com:82, where gateway.example.com is the name of the SGD Gateway.

      The home page for the reflection service is shown.

C.9.2. Using the Reflection Service

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.

Note

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).

C.9.2.1. About the RESTful Web Services

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

/

GET

Shows high-level information for the routing proxy, such as the uptime.

/service

GET

Lists the available services.

A service represents an entry point from which the routing proxy creates incoming connections.

/service/Service-Id

GET

Lists information for a service, identified by Service-Id.

/service/Service-Id

PUT

Starts a service, identified by Service-Id.

/service/Service-Id

DELETE

Stops a service, identified by Service-Id.

/client

GET

Lists the available clients.

A client represents an exit point on which the routing proxy constructs outgoing connections.

/client/Client-Id

GET

Lists information for a client, identified by Client-Id.

/route

GET

Lists the available routes.

A route represents a path through the routing proxy, from incoming connections through services to outgoing connections through clients.

/route/Route-Id

GET

Lists information for a route, identified by Route-Id.

/route/Route-Id

PUT

Starts a route, identified by Route-Id.

/route/Route-Id

DELETE

Stops a route, identified by Route-Id.

/route/Route-Id/connection

GET

Lists the connections for a specific route, identified by Route-Id.

/route/Route-Id/connection/Connection-Id

DELETE

Terminates a connection, identified by Connection-Id.

/connection

GET

Lists all currently running connections, for all routes.

/logging/level

GET

Shows the global logging level.

/logging/level/Log-Level

PUT

Sets the routing proxy's global logging level.

/logging/Package/level

GET

Shows the logging level for a specific component of the routing proxy.

/logging/Package/level/Log-Level

PUT

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 --cert client.pem --key client.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.

C.9.2.2. Examples of Using 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 --cert client.pem --key client.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 --cert client.pem --key client.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 --cert client.pem --key client.key -k \
-X DELETE https://gateway.example.com:82/route/1

To set the global logging level to FINER:

$ curl --cert client.pem --key client.key -k \
-X PUT https://gateway.example.com:82/logging/level/FINER