C.9. 反射服务

反射服务是 SGD Gateway 路由代理组件使用的一组 RESTful Web 服务。使用反射服务,SGD Gateway 管理员可以配置路由、服务、日志记录级别以及连接,并显示路由代理的状态信息。

本节包括以下反射服务主题:

C.9.1. 启用反射服务

默认情况下,不会为 SGD Gateway 启用反射服务。

可以为反射服务启用下面的一种或两种访问方法:

C.9.1.1. 如何对反射服务启用未授权访问

  1. 在 SGD Gateway 主机上,以超级用户 (root) 身份登录。

  2. 对反射服务启用未授权访问。

    # /opt/SUNWsgdg/bin/gateway config enable --services-reflection
  3. (可选)更改反射服务使用的接口。

    小心

    默认情况下,仅可以从 SGD Gateway 主机对反射服务进行未经验证的访问。在其他接口上启用未经验证的访问可能会带来安全风险。

    对反射服务进行未授权访问的默认接口为 localhost 回送接口。以下示例显示了如何在所有接口上启用未授权访问:

    # /opt/SUNWsgdg/bin/gateway config edit \
    --services-reflection-binding *:81
  4. (可选)更改反射服务使用的端口。

    对反射服务进行未授权访问的默认端口为 TCP 端口 81。您可以将此端口更改为其他未使用的端口,如下所示:

    # /opt/SUNWsgdg/bin/gateway config edit \
    --services-reflection-binding localhost:portnum
    

    其中,portnum 是反射服务使用的端口号。

  5. 重新启动 SGD Gateway。

    # /opt/SUNWsgdg/bin/gateway restart
  6. 访问反射服务。

    在 SGD Gateway 主机上,可以启动浏览器并转至 http://localhost:81

    此时将显示反射服务的主页。

C.9.1.2. 如何对反射服务启用授权访问

  1. 在 SGD Gateway 主机上,以超级用户 (root) 身份登录。

  2. 导出反射服务的证书和私钥。

    反射服务的证书和私钥存储在反射服务密钥库中,位于 /opt/SUNWsgdg/proxy/etc/keystore.reflection。此密钥库是在安装 SGD Gateway 期间自动创建的。

    默认情况下,反射服务密钥库包含一个自签名证书和一个密钥对。

    1. 导出反射服务的证书。

      # /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
      

      其中,server-name 是反射密钥库中反射服务证书的别名,client.pem 是导出的证书的文件名。

      有关如何使用 keytool 应用程序的详细信息,请参见 JDK Tools and Utilities(JDK 工具和实用程序)文档。

    2. 导出反射服务的私钥。

      使用 SGD Gateway 随附的 KeyManager 应用程序。

      # /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)"
      

      其中,alias-name 是反射密钥库中反射服务密钥的别名,client.key 是导出的密钥的文件名。

  3. 在客户端设备上安装证书和私钥。

    证书和私钥供客户端设备用来对反射服务进行授权。

    要将证书和密钥导入到浏览器证书库中,必须先将证书和密钥转换为 PKCS12 格式的文件。例如:

    # openssl pkcs12 -export -in mycert.crt -inkey mycert_key.pem -out mycert.p12

    此命令将证书文件 mycert.crt 和关联的私钥 mycert_key.pem 转换为 PKCS12 格式的证书文件 mycert.p12

    有关如何将 PKCS12 格式的证书导入到浏览器中的更多详细信息,请参见所用浏览器的联机文档。

  4. 对反射服务启用授权访问。

    在 SGD Gateway 主机上,运行以下命令:

    # /opt/SUNWsgdg/bin/gateway config enable --services-reflection-auth
  5. (可选)更改反射服务使用的接口和端口。

    用于对反射服务进行授权访问的默认绑定为所有接口上的 TCP 端口 82。您可以将其更改为其他未使用的接口和端口,如下所示:

    # /opt/SUNWsgdg/bin/gateway config edit \
    --services-reflection-binding int:portnum
    

    其中,intportnum 分别为反射服务使用的接口和端口号。

  6. 重新启动 SGD Gateway。

    # /opt/SUNWsgdg/bin/gateway restart
  7. 使用证书和私钥从客户端设备连接到反射服务。

    • 使用 curl 命令:

      $ curl --cert client.pem --key client.key -k -X GET https://gateway.example.com:82
      

      在此示例中,curl 命令用于访问反射服务的主页,网址为:https://gateway.example.com:82,其中 gateway.example.com 为 SGD Gateway 的名称。反射服务的证书和私钥分别为 client.pemclient.key

    • 使用浏览器:

      转至 https://gateway.example.com:82,其中 gateway.example.com 为 SGD Gateway 的名称。

      此时将显示反射服务的主页。

C.9.2. 使用反射服务

使用客户端应用程序访问反射服务提供的 RESTful Web 服务。以下列举了一些合适的客户端应用程序:

  • 浏览器。 使用浏览器是访问反射服务的最简单方法。但是,浏览器仅支持 HTTP GET 请求,因此只能用于访问检索信息的 RESTful Web 服务。实际上,浏览器适用于显示状态信息和列出路由代理的路由和服务等任务。

  • curl。 curl 是 UNIX 和 Linux 平台的命令行工具,支持 HTTP GETPUTPOST 以及 DELETE 请求。这意味着可以使用反射服务提供的全部 RESTful Web 服务。该工具的输出可以重定向到某个文件或其他程序做进一步处理。

如果您自己有支持 RESTful Web 服务的客户端应用程序,也可以使用该应用程序来访问反射服务。

注意

使用反射服务来更改路由代理的配置时,无需重新启动 SGD Gateway。

反射服务返回的数据可按以下格式输出:

  • ASCII。 这是默认输出格式。返回的数据采用制表符分隔的 ASCII 格式。如果要进一步处理数据(例如解析),此输出格式很有用。

  • HTML。 返回的数据采用 HTML 格式,适用于在浏览器中显示。要返回 HTML 格式的输出,请将 /html 附加到 Web 服务统一资源标识符 (Uniform Resource Identifier, URI) 的末尾。

C.9.2.1. 关于 RESTful Web 服务

表 C.1 “SGD Gateway 反射服务的 RESTful Web 服务”列出了 SGD Gateway 反射服务的 RESTful Web 服务。

表 C.1. SGD Gateway 反射服务的 RESTful Web 服务

相对 URI

HTTP 请求方法

描述

/

GET

显示路由代理的高级信息,例如运行时间。

/service

GET

列出可用的服务。

服务代表路由代理创建传入连接的入口点。

/service/Service-Id

GET

列出由 Service-Id 标识的服务的信息。

/service/Service-Id

PUT

启动由 Service-Id 标识的服务。

/service/Service-Id

DELETE

停止由 Service-Id 标识的服务。

/client

GET

列出可用的客户端。

客户端代表路由代理构建传出连接的出口点。

/client/Client-Id

GET

列出由 Client-Id 标识的客户端的信息。

/route

GET

列出可用的路由。

路由代表一条通过路由代理的路径,从服务的传入连接到客户端的传出连接。

/route/Route-Id

GET

列出由 Route-Id 标识的路由的信息。

/route/Route-Id

PUT

启动由 Route-Id 标识的路由。

/route/Route-Id

DELETE

停止由 Route-Id 标识的路由。

/route/Route-Id/connection

GET

列出由 Route-Id 标识的特定路由的连接。

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

DELETE

终止由 Connection-Id 标识的连接。

/connection

GET

列出当前运行的所有连接(所有路由)。

/logging/level

GET

显示全局日志记录级别。

/logging/level/Log-Level

PUT

设置路由代理的全局日志记录级别。

/logging/Package/level

GET

显示路由代理的特定组件的日志记录级别。

/logging/Package/level/Log-Level

PUT

设置路由代理的特定组件的日志记录级别。


要访问某个 RESTful Web 服务,请将该 Web 服务的相对 URI 附加到反射服务的 URL。

例如,要列出 SGD Gateway gateway.example.com 的可用路由,请将 /route 附加到反射服务的 URL,如下所示:

$ curl --cert client.pem --key client.key -k -X GET https://gateway.example.com:82/route

其中,client.pemclient.key 分别是反射服务的证书和私钥。在此示例中,客户端需要先获得授权,然后才能访问反射服务。

C.9.2.2. 使用反射服务的示例

以下所有示例均使用 curl 命令作为访问反射服务的客户端应用程序。

这些示例对名为 gateway.example.com 的 SGD Gateway 上的反射服务使用经过验证的访问。客户端使用证书 client.pem 和私钥 client.key 来授权。

要列出 SGD Gateway 的可用服务,请运行以下命令:

$ curl --cert client.pem --key client.key -k \
-X GET https://gateway.example.com:82/service

要停止路由,请指定反射服务对该路由使用的路由 ID:

$ 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

要将全局日志记录级别设置为 FINER,请运行以下命令:

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