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.

Note:

Configuration objects of type Private Network Agent, which a deployed Designer integration requires to connect to a private network, are automatically generated in the following ways:

  • When you create a switch server, a private network agent and a corresponding configuration object are created by default. You can see this private network agent on a Private network connections page, which is added to any App Connect Designer or App Connect Dashboard instance in the same namespace.
  • When you create a private network agent from the Private network connections page in an App Connect Designer or App Connect Dashboard instance, a corresponding configuration object is created by default.

From the Private network connections page, you can download a switchclient.json file and then use it to configure a private network agent (and a secure agent) by providing endpoint information for one or more private network connections. When you deploy a Designer integration, you can then apply the configuration object of type Private Network Agent that was created by default when the private network agent was created. This configuration object automatically enables port forwarding from a local listening port that is opened for the deployed integration to a remote port on which the remote host listens. For more information, see Connecting to a private network from the App Connect Dashboard.

Restriction: Configuration objects of type Private Network Agent are not supported in Kubernetes environments.


Summary of key details for the configuration type

File name or type Contains secrets Path extracted/imported to Maximum allowed per integration server or 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 server or integration runtime, and the remote port and host to forward messages or requests to.

Only one switchclient.json file can be specified per integration server or integration runtime. The file is placed in the /home/aceuser/ace-server/config/switch directory for the integration server or 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.

    For more information, see Designer: Configuring a private network connection and Dashboard: Configuring a private network connection.

    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 server or 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.

    •   "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.

For examples of how to use this configuration type, see Tutorials and examples.

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 server or integration runtime, or independently, as follows.

  1. Open the Configuration page by clicking the Configuration icon Configuration icon in the navigation pane, or go to the Configuration view of an integration server or integration runtime that you are creating. Then, click Create configuration. For more information, see Managing configuration objects from the Configuration 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 server or 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 Managing configuration objects from the Configuration page.