Skip to content

Peer Nodes

A Peer Node is a separate 12Port application node, typically deployed in a remote or isolated network. It can be used by the primary deployment for tasks such as remote sessions or delegated script execution.

A typical use case for a peer node involves delegating script execution or establishing secure remote sessions to endpoints or devices within remote, isolated networks that cannot be directly accessed by the current deployment. In this situation, creating a trusted connection between the main node and the remote peer node enables management of devices that the main node cannot access. Peer nodes are valuable for overseeing devices across multiple isolated datacenters or virtual cloud networks from a single location. They are also beneficial in managed service provider (MSP) scenarios, where each peer node can manage devices for independent MSP clients.

Note

Communication between the Main Node and Peer Node occurs over HTTPS, using the designated port for each 12Port deployment (e.g., 443, 6443). Ensure this traffic is allowed between nodes; whether directly, through a virtual connection, or via a tunnel.

Configuring a Peer Node For Job Execution (Job Runner)

A Peer Node connection supports two separate 12Port deployments, one acting as the Main node while the other as the Peer node. The Peer node should be deployed in a location with appropriate connectivity to communicate with any devices or endpoints that are not directly accessible by the Main node.

After the Peer Node is deployed and running, you can begin the configuration to establish connectivity from this node.

Step 1: Configure the Peer Node

  1. Log in to the Peer Node using an Administrator account. Use the specific Tenant and Site for this connection (do not use the /base tenant) where the Main Node will be made.
  2. Navigate to Management > Users and create a new Local Directory User. This Local Directory User account will be used as a Service account for authentication from the Main Node. If you want to use a user account from an external directory like Active Directory or EntraID, you can skip this step. Do not use a group for Service accounts.
  3. Go to Management > Site Roles, click Grant, and assign the Service role to the user from step 2 or your external user. Click Grant to apply. Site Role Service Assignment
  4. Navigate to Management > API Tokens, click Add, and select the Service user. Set the Expiration date, Filter, and Description. Toggle Enabled, then click Save. This API token will be used for authentication purposes from the Main node to this Peer node in the next steps.
  5. After saving, access the token using Show Details > Unlock Token under JWT, then click Copy to save it to your clipboard. Use Lock Token to secure it again. API Token Copy to Clipboard

Step 2: Configure the Main Node

Now we will begin the configuration from the Main node.

  1. Log in to the Main Node using an Administrator or Configuration Manager account. Use the Tenant and Site where the Peer Node connection will be established. Do not use the /base tenant.
  2. Go to Configuration > Peer Nodes, then click Add.
  3. Configure the following parameters:
    • Peer Name: A unique, identifiable name for this connection. It will be used when assigning the Peer Node to assets.
    • Toggle on Includes Job Runner.
    • URL: Enter the URL of the Peer Node that was used for configuration in the previous section. Use the format like this: https://host:port/ztna/<tenant>/<site> where <tenant> and <site> are the tenant and site designated on the Peer Node for connectivity purposes.
    • Access Token: Enter or Paste the API Token that was created and copied from the Peer Node in the previous section.
    • Toggle on Enabled.
  4. Click Verify Trust (Job Runner) to inspect the Peer Node’s certificate. If not trusted, click Establish Trust. Establish Certificate Trust Once trusted, the header turns green. Trust Established Successfully Click Close to continue.
  5. Finally, click Test Connection to confirm connectivity between the Main and Peer nodes.
    Test Connection Success

Assigning Peer Node to Assets for Job Execution


Connectivity between the Main Node and Peer Node has now been established. Next, this Peer Node has to been assigned to specific assets so that they can be processed by the Peer Node rather than the Main Node.

  1. From the Main Node, navigate to the Asset library and identify the asset (Container or Asset) that will have its jobs processed by this Peer Node. If a Peer Node is assigned to a container, all assets within this container will inherit this Peer Node configuration and their jobs will be processed by this Peer Node.
  2. On this container or asset, use Manage > Peer Nodes, then click Add. Access to this option requires a Site Role: Administrator, Site Role: Asset Manager or an Asset Permission of Asset Manager or higher account.
  3. Select the Peer Node from the list by its Name. Asset Peer Node Selection Page
  4. Click Save.

The Peer Node is now assigned and active for this asset by default. To modify the configuration, use the Actions menu.

Verifying Peer Node Job Execution

After the Peer Node configuration is complete, it is time to test and verify its use. The following section will confirm that the Peer Node is being used for remote job execution as intended.

  1. On an asset with this enabled Peer Node, use the Execute menu to run a job like Windows Status Check or Unix Status Check. For containers, use a child asset.
  2. After the job completes, go to Reports > Jobs and locate the completed job.
  3. Use the Actions > Show Details option of this Job to review its metadata. Locate the Node Signature parameter and observe that it displays the Peer Node, Peer Tenant and Peer Site as defined in the previous configuration sections.

    As an example, here is how the Node Signature appears for a Peer Node job execution, where:
    Node Signature Example
    (1) is the Node name 12P-remotePeer-dev of the Peer Node, followed by a :: separator;
    (2) is the Tenant Name proxm-27 where the Peer Node was created, followed by a :: separator; and
    (3) is the Site Name root in this tenant where the Peer Node was created.


This confirms that the Main Node asset and its job was executed using the Peer Node from this asset's configuration.

Note

When two or more enabled Peer Nodes are assigned to an asset, whether through inheritance from a parent container, direct assignment or both, 12Port will randomly select one of the peer nodes to use for each remote job execution.

Configuring a Peer Node for Remote Sessions (Gateway)

The setup process for remote sessions is similar. A Peer Node must be reachable by endpoints not accessible from the Main Node.

After the Peer Node is deployed and running, you can begin the configuration to establish connectivity from this node.

  1. From the Main Node, log in with an Administrator or a Configuration Manager account. You will login to this Main Node's Tenant and Site (do not use the /base tenant) where the connectivity with the Peer Node will be established.
  2. Navigate to Configuration > Peer Nodes and click Add.

Note

A single Peer Node can support both job execution and remote sessions. If already configured for one, simply configure the other.

  1. Configure the following parameters:
    • Peer Name: Enter a unique and recognizable name to assign to this connection. This name will be used when assigning this connection to assets.
    • Toggle on Includes Gateway.
    • Gateway Address: Enter the remote gateway address of the Peer Node. The address will be in the format server:port like: 12port.contoso.com:4822 where 12port.contoso.com is the server address and 4822 is the open server port used by the gateway for session connectivity.
    • Toggle on Enabled.
  2. Click Verify Trust (Gateway). If the certificate is not trusted, click Establish Trust. Establish Certificate Trust The header will turn green once trust is established. Trust Established Successfully Click Close to continue.


Connectivity between the Main Node and Peer Node has now been established. Next, this Peer Node has to been assigned to specific assets so that they can be processed by the Peer Node rather than the Main Node.

Assigning Peer Node to Assets for Remote Sessions

  1. From the Main Node, navigate to the Asset library and identify the asset (Container or Asset) that will have its sessions established by this Peer Node. If a Peer Node is assigned to a container, all assets within this container will inherit this Peer Node configuration and their jobs will be processed by this Peer Node.
  2. On this container or asset, use the Manage > Peer Nodes option and click Add. Access to this option requires a Site Role: Administrator, Site Role: Asset Manager or an Asset Permission of Asset Manager or higher account.
  3. Select the Peer Node from the list by its Name. Asset Peer Node Selection Page
  4. Click Save.

The Peer Node is now assigned and enabled for remote session use. Use the Actions menu to edit, disable, or remove the configuration.

Verifying Peer Node Remote Sessions

After the Peer Node configuration is complete, it is time to test and verify its use. The following section will confirm that the Peer Node is being used for remote sessions as intended.

  1. From the Asset where the Peer Node is enabled, click the Access button to start a remote session.
  2. Once the session is active, wait a few seconds, then end the session.
  3. Go to Reports > Sessions and locate the completed session.
  4. For the session, use the Actions > Show Details option to review its metadata. Locate the Gateway parameter and observe that it displays the Gateway Address defined in the earlier configuration.

Reported Session Gateway Example


This confirms that the Main Node asset and its session was established using the Peer Node from this asset's configuration.

Note

When two or more enabled Peer Nodes are assigned to an asset, whether through inheritance from a parent container, direct assignment or both, 12Port will randomly select one of the peer nodes to use for each remote job execution.

Configuring a Peer Node For Proxy Sessions (HTTP Proxy)

A Peer Node connection supports two separate 12Port deployments, one acting as the Main node while the other as the Peer node. The Peer node should be deployed in a location with appropriate connectivity to communicate with any devices or endpoints that are not directly accessible by the Main node.

In deployments where a Peer Node is used to provide Proxy-based access (RDP or SSH Proxy Sessions) to isolated network segments, the HTTP Proxy must be enabled on the remote peer node tenant. This setup allows the Main Node to broker remote proxy access connections to target assets through the Peer Node.

For setup instructions, please review the steps listed in the Native Remote Sessions article.