Private Network Agent type

Use the Private Network Agent type to create a configuration object (or agent) that a deployed Toolkit integration requires to connect to an application in a private network. This configuration object provides connectivity details to enable port forwarding from the deployed integration to the remote port and host of the application in the private network.


Summary of key details for the configuration type

File name or type Contains secrets Path extracted/imported to Maximum allowed per integration runtime
switchclient.json Yes /home/aceuser/ace-server/config/switch/switchclient.json 1

About the switchclient.json file

The Private Network Agent type requires a switchclient.json file that specifies connectivity details for port forwarding, which allows connections through an SSH tunnel to a remote port and host in a private network. In this file, you supply a local listening port to open for the integration runtime, and the remote port and host to forward messages or requests to.

Only one switchclient.json file can be specified per integration runtime. The file is placed in the /home/aceuser/ace-server/config/switch directory for the integration runtime.

You can construct the switchclient.json file as part of the sequence for configuring a private network connection, which requires you to set up an App Connect secure agent that runs on your computer. You can use the switchclient.json file with completed endpoint details as your starting template.

To construct a switchclient.json file with connectivity details for port forwarding, complete the following steps:

  1. Make a copy of the switchclient.json file that you downloaded and completed when you configure a private network connection from App Connect Designer or the App Connect Dashboard. The completed file contains endpoint information that includes host, port, and certificate details for the remote connection, and details of the switch server location and certificates.
    An example of a completed file is as follows.
    {
  "id": "fbda61eb-0e17-4bd2-a61d-9d202c1b2303",
  "admin": "disabled",
  "callableFlows": "disabled",
  "endpoints": [
    {
      "name": "My DB2 endpoint descriptive name",       "hostname": "203.0.113.10",       "port": 30041,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],
  "switch": {
    "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
}
    Note: The id and displayName entries are omitted if you downloaded the switchclient.json file for the default private network agent named switchServerName-privatenetworkagent.
  2. Make a note of the hostname and port values in the endpoints array in this file.
  3. Edit the file to remove the id, admin, and callableFlow entries, and the endpoints array lines. The final result is similar to the following example.
    {
  "switch": {
    "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
}
    Warning: If you leave the endpoints in the configuration, the hostname and port must not match an endpoint that is configured in an on-premises secure client that is connected to the same switch server.
  4. Insert the following lines for a listeners array directly after the opening brace, {, where:
    • localPortNumber is a local port number of your choice, on which the agent listens, and through which all connections to the remote database server port on the private network are forwarded.
    • remoteHost is the hostname or IP address that you copied from the initial switchclient.json file. Requests are forwarded to this host.
    • remotePortNumber is the port number that you copied from the initial switchclient.json file. Requests are forwarded to this port.
    • useTLS accepts a value of true or false (to enable or disable TLS), but can be ignored together with the certs object. No additional security settings are needed between the listener agent and the integration runtime, which run in the same pod.

      "listeners": [
    {
      "localPort": localPortNumber,
      "remoteHostname": "remoteHost",
      "remotePort": remotePortNumber,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true,
        "requestCert": true
      }
    }
  ],

    The following example shows a completed file for a single listener. These settings indicate that connections to local port 9000 will be forwarded to the remote port 30041 on which host 203.0.113.10 listens.

    {
  "listeners": [
    {
      "localPort": 9000,
      "remoteHostname": "203.0.113.10",
      "remotePort": 30041,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true,
        "requestCert": true
      }
    }
  ],
  "switch": {
    "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
}

    You can add multiple listener objects if you require multiple connections.

    • Example of two listener definitions within the listeners array

        "listeners": [
    {
      "localPort": 9000,
      "remoteHostname": "203.0.113.10",
      "remotePort": 30041,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true,
        "requestCert": true
      }
    }
    {
      "localPort": 8000,
      "remoteHostname": "203.0.113.0",
      "remotePort": 1234,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true,
        "requestCert": true
      }
    }
  ],
  5. Save and close the file.

Creating a configuration for the Private Network Agent type by using the configuration panel

You can create a Private Network Agent-type configuration when you create an integration runtime, or independently, as follows.

  1. Open the Configuration page by clicking the Configuration icon Configuration icon in the navigation pane. Then, click Create configuration. For more information, see Creating configurations on the Configurations page.
  2. From the Create configuration panel, select Private Network Agent from the Type list.
  3. In the Name field, specify a name for this configuration.
  4. In the Description field, specify text that might help you identify the function of the configuration.
    Create configuration panel
  5. In the Private Network Agent section, paste the content of your switchclient.json file directly into the text editor.
    Private Network Agent text editor with pasted contents
  6. Click Create. The configuration is added to the configurations table and can be selected for use with an integration runtime.

Updating or deleting a configuration

If you need to update the content or settings in a configuration, or delete a configuration that's no longer needed, see Creating configurations on the Configurations page.