Using TIBCO Cloud™ - Proxy Agent

Before starting, you must download and install TIBCO Cloud - Proxy Agent and get an access key, as described in TIBCO Cloud™ - Proxy Agent Prerequisites.

After meeting the prerequisites, perform the following steps:

Step 1: Configure Apps to Associate with an Access Key

You must configure an app to associate it with an Access Key. For example, add an access key for TIBCO Cloud - Proxy Agent to TIBCO Cloud as described in Generating and Revoking Access Keys.

Step 2: Configure the TIBCO Cloud - Proxy Agent with Your Access Key

Before starting TIBCO Cloud - Proxy Agent for the first time, create a profile to configure authentication for the client. You can do this with the tibtunnel configure command and specifying an access key created in TIBCO Cloud, as described in TIBCO Cloud™ - Proxy Agent Prerequisites.

Command to create a profile:

tibtunnel configure [--config-dir <configDir>] [--profile <profileName>] [(--basicauth --user <userName> --password <password>) | --accessKey <accessKeySecret>]

This command writes or updates the credentials file in the configuration directory (by default ~/.tibtunnel) and stores the profiles in a standard INI format file. A profile is created in your home directory, unless the option --config-dir is specified.

You can create multiple profiles for different access keys. If no profile name is specified in this command, a profile default is created.

A profile has the following format:

  • name - Required

  • one of the following fields:

    • accesskey

    • basicauthUser and basicauthPassword

For example,

$ cat ~/.tibtunnel/credentials[default]
accessKey=4Pcg4SAaDiZMghf

[cdash]
basicauthUser=admin
basicauthPassword=foo

Step 3: Establish a Connection with TIBCO Cloud - Proxy Agent and Expose On-Premises Resources

TIBCO Cloud - Proxy Agent establishes tunnels to the app containers when you run the connect command. The profile is an optional argument. If you do not specify a profile, the profile named "default" is used.

tibtunnel connect [-d] [--log-file <logFilePath] [--config-dir <configDir>] [--profile <profileName>] -s <spec> [-s <spec> ...] <ConnectURL> [<ConnectURL> ...]

After you run the command to connect to TIBCO Cloud - Proxy Agent, the on-premises resources that are to be exposed to the app containers running in TIBCO Cloud are listed as “specifications" or “specs” in the following format:

-s <containerPort>:<onPremiseHost>:<onPremisePort>

Some points to remember:

  • The on-premises resource at <onPremiseHost>:<onPremisePort> is reachable from the app container as <onPremiseHost>:<containerPort>. Most of the time the <onPremisePort> and <containerPort> are the same. However, if the on-premises port is not available in the container (if the app is using that port), you can remap it to a different port.

  • For <onPremiseHost> either host names or IP addresses are valid values. Both <containerPort> and <onPremisePort> can be specified as a range of ports. For example, the following specification exposes ports 3000, 3001, 3002, and 3003: "3000-3003:example.com:3000-3003".

Using the Correct On-Premises Address in a Client App

Note that when you use the address for an on-premises resource in a client app, you must use the exact format as exposed in the spec.

For example, if you specified -s 1122:example.com:9991, where 1122 is the port opened in the app container and 9991 is the on-premises port, the address used in the client app must use example.com:1122. Do not substitute hostname or an IP address, even if they do resolve to example.com.

You can use an IP address in your client app only if you also used it in your spec when starting the tunnel.

Tuning Parameters

The following command-line parameters are available for the tibtunnel connect command to help users tweak data size and data ack (acknowledgment) mode:

Command Option Description
--data-ack-mode

Specifies the data ack mode. By default, tibtunnel explicitly uses ack internally to transfer data sequentially. You can use this option to use tibtunnel to transfer data as it is available to send or receive.

Default: true
--data-chunk-size

Sets the maximum size of data (in KB) for a single read-write operation. You can set the size based on the data that you want to transfer.

Default: 32KB

Usage 

tibtunnel connect --data-ack-mode false
tibtunnel connect --data-chunk-size 64

Examples

Basic Usage

To start a single TIBCO Cloud - Proxy Agent instance used by multiple apps associated with an AccessKey that has the access key secret myKey, with connect URL connectURL and specs to Jaeger open tracing on port 14268, Prometheus app metrics monitoring on port 9090, and a MySQL server for designtime and runtime use on port 3306:

    Procedure

  1. Configure the default profile with the access key myKey:

    tibtunnel configure --accessKey myKey

  2. Connect to the app containers:

    tibtunnel connect --spec
14268:localhost:14268 --spec 
9090:localhost:9090 --spec 
3306:localhost:3306 connectURL
Port Mapping

Most of the time, the on-premise port and container port are the same. However, if the app port is not available in the container (for example, when the app is using that port), the port can be re-mapped to a different port.

This means the on-premise resource at onPremiseHost:onPremisePort is reachable from the app container as onPremiseHost:containerPort.

For example, to start TIBCO Cloud - Proxy Agent with the default profile and map example.com:8000 to port 3000 in the container for all the apps associated with an AccessKey My_first_key, use the following command:

tibtunnel connect -s 3000:example.com:8000 https://account.cloud.tibco.com/infra/tunnel/My_first_key.01EH6RRN483DFMXG7MNZ3R09VH
Note: The actual Connect URL differs from the example.
Different Regions

The access keys and connect URLs are region-specific and you must create an access key in the region where your app is running and use the corresponding connect URL.