| copyright | lastupdated | ||
|---|---|---|---|
|
2018-10-04 |
{:screen: .screen} {:codeblock: .codeblock} {:pre: .pre}
There are a few ways to interact with the client:
- Through terminal command line prior to startup
- After startup, using the client's interactive command line
- After startup, using the client's local UI
{: #startup}
{: #startup-args}
The following table describes all of the available options that can be provided alongside the startup command for the client. Using these will allow complete configuration of the client prior to startup rather than requiring individual setup once the client is running.
| Parameter and Arguments | Description |
|---|---|
| <gateway ID> | Connect to {{site.data.keyword.Bluemix_notm}} by using the gateway ID that is provided |
| -F, --aclfile <file> | Access control List file |
| -g, --gateway <hostname:port> | Used to manually select a specific gateway destination (advanced use only) |
| -l, --loglevel <level> | Change the log level to ERROR, INFO, DEBUG or TRACE |
| -p, --logpath <file> | Direct logging to a specific file |
| -t, --sectoken <security token> | The security token to use for this gateway connection |
| -P, --port <port> | The port for the UI to run on. Defaults to port 9003 |
| -w, --password <password> | The password to protect the UI with. Defaults to no password |
| -x, --proxy <proxy agent> | The proxy for the port 9000 connection |
| --noUI | Prevent the UI from starting up automatically |
| --allow | Allows all connections to the client. Is overridden by the ACL file, if provided |
| --service | After an initial connection, the parent will restart within 60s if all child clients are terminated |
Note: --service, --allow, and --noUI flags should be the last parameters in the command line arguments.
The most basic use case is to start with a single client connection with the default settings:
<gateway_id> -t <security_token>
{: pre}
These options can be extended to support the automatic connection of multiple clients, as well. In order to pass these to multiple client connections, they must be passed in using a specific format. The gateway IDs can be passed in the same way as with the single client connection (with each gateway ID separated by a space); however, the order of these IDs determine the order the rest of the arguments must follow. When passing in any of the other arguments, they must be separated by -- in order to be picked up correctly. If nothing is passed in for a particular flag, it is assumed to not apply to any of the clients.
If there aren't enough arguments supplied to fulfill all of the gateway IDs, then they will be applied in order until there are no more arguments. For example, if two gateway IDs are passed in and a single security token is passed in, then the token will be applied to the first gateway ID and not the second one.
If gateway IDs are provided that require different arguments, then the keyword none should be designated in the place of any particular argument that a gateway is not enforcing/supplying. For example, if three gateway IDs are passed in and the user would like to specify a loglevel for the first and third, the argument would look like --loglevel DEBUG--none--TRACE. In this case, none would then default to INFO.
{: #startup-examples}
Single client connection, custom loglevel, no UI:
node lib/secgwclient.js <gateway_id> -t <security_token> -l <loglevel> --noUI
{: pre}
Multiple client connections, default options:
node lib/secgwclient.js <gateway_id_1> <gateway_id_2> -t <security_token_1>--<security_token_2>
{: pre}
Multiple client connections, all custom settings:
node lib/secgwclient.js <myGatewayID_1> <myGatewayID_2> -t none--<token for gateway 2> -l DEBUG--TRACE -p <full path to log file for gateway 1>--<full path to log file for gateway 2> -F <full path to ACL file for gateway 1>
{: pre}
Return to Getting Started - Adding a Client.
{: #interactive}
{: #interactive-commands}
The {{site.data.keyword.SecureGateway}} client has a command line interface (cli) and shell prompt for easy configuration and control. The interactive environment supports a richer sets of capabilities than the command line arguments, this is to facilitate better interactive control over the client.
| Interactive Commands | Description |
|---|---|
| A, acl allow <hostname:port> <worker ID> | Access control list allow |
| D, acl deny <hostname:port> <worker ID> | Access control list deny |
| N, no acl <hostname:port> <worker ID> | Remove an access control list entry |
| S, show acl <worker ID> | Show all access control list entries |
| F, acl file <file> <worker ID> | Access control List file |
| C, displayconfig <worker ID> | Display the current {{site.data.keyword.SecureGateway}} configuration, if available |
| a, authorize <worker ID> | Toggle the override of the rejectUnauthorized parameter for outbound TLS connections for the specified worker |
| t, sectoken <security token> | The security token to use for the next gateway connection |
| c, connect <gateway ID> | Connect to {{site.data.keyword.Bluemix_notm}} by using the gateway ID that is provided |
| l, loglevel <level> <worker ID> | Change the log level to ERROR, INFO, DEBUG or TRACE |
| p, logpath <file> <worker ID> | Direct logging to a specific file |
| r, reverse <worker ID> | List the ports the client is currently listening on for reverse destinations |
| k, kill <worker ID> | Terminate the specified worker |
| e, select <worker ID> | Specifies a worker to perform commands on unless otherwise specified |
| d, deselect | Deselects the previously specified worker. Issue select command to specify another |
| w, password <old password> <new password> | Set the UI password. If <new password> is blank, no password will be enforced. <old password> required on password update. Passwords must contain only letters |
| P, port <new port> | Change the port that the UI is listening on |
| u, uistart <initial password> <port> | Starts the UI on localhost:<port>/dashboard. If <initial password> is blank and no other password has been set for the session, no UI password will be enforced. If <port> is blank the UI will be reachable on 9003 |
| U, uistop | Closes the UI associated with this client session. The session will only be accessible via CLI until a new UI is manually started |
| R, revoke | Clears all UI authorizations associated with this client session |
| q, quit | Disconnect and exit |
| s, status <worker ID> | Print the status details of the tunnel and its connections |
| L, list | Displays a list of the currently associated workers |
Note: If a connection has been specified with the select command and another command is called without providing a worker ID, the command will attempt to run on the connection specified by select.
For more details on configuring the Access Control List, click here.
Return to Getting Started - Adding a Client.
{: #ui}
Note: The Client UI is not supported when using Docker on Windows or MacOS.
The client UI provides a local web interface for the user to interact with the {{site.data.keyword.SecureGateway}} Client rather than the CLI. By default, this UI is available at localhost:9003/dashboard The UI is split into the following pages:
{: #ui-connect}
This is the initial landing page for the UI where a user can provide a gateway ID and security token to connect their first client.
{: #ui-login}
This page will be displayed if the UI has been password protected. If this page is reached while no password is being enforced, please refresh the page to be redirected.
{: #ui-dashboard}
This is the main page once a client has been connected. From here, you can access the View Logs page, the Access Control List page, and the Connection Info page. At the bottom, you can also choose to disconnect one/many of the connected clients. On the top of the page, the currently selected client will be displayed as well as an option to connect additional clients.
{: #ui-logs}
This page will allow you to see the logs being generated by the selected client (shown in the upper right of the page). The displayed logs can be filtered by the check boxes below the logs.
{: #ui-acl}
This page will allow you to manipulate the Access Control List for the selected client (shown in the upper right of the page). Rules can be individually added to the allow/deny tables or a file can be uploaded at the bottom of the page.
{: #ui-info}
This page will show the current connection information for the selected client (shown in the upper right of the page). Information such as gateway description, number of current connections, and reverse destination listeners can be seen here.
Return to Getting Started - Adding a Client.
{: #remote}
If a client has been provided an ID, then it can be remotely terminated via the SG UI or through the SG API. If you terminate a client that is running as a service, the client will restart and obtain a new client ID; however, if the service has multiple clients connected, the terminated client will not restart until all of the remaining clients have been terminated.
{: #limits}
{: #limits-conn}
The SG gatewway can only handle 250 concurrent connections. If the number of concurrent requests exceeds the limit, it can result in the connection attempts being rejected and lead to latency. An easy way to fix this is to use connection pooling on the calling app. Please note that the limit of 250 concurrent connections is on the gateway and not client or destination. This limit will be shared across all the client and destinations on the gateway.
{: #limits-datapower}
The {{site.data.keyword.SecureGateway}} DataPower Client is in the process of being updated to match the capabilities of the rest of our clients. It currently has the following limitations:
- ACL will default to ALLOW ALL
- Enabling and disabling gateways or destinations from the {{site.data.keyword.SecureGateway}} UI is not supported. However, the Administrative State option in the DataPower UI functions as an on/off switch for that particular client.
- Connection status polling for real-time connected and disconnected gateway status updates is not supported.
- Full certificate chains with destination-side TLS are not supported prior to DataPower version 7.5.1.0
- Cloud destinations are not supported prior to DataPower version 7.5.1.0
- The log level can't be changed to TRACE level