Configure multi-hop sessions for HCP Boundary

Enterprise

This feature requires HCP Boundary.

Many organizations have strict network policies that prohibit all inbound traffic into their networks. In these scenarios, you can use HCP-managed workers as the ingress workers. A self-managed worker inside the private network initiates an outbound connection to the HCP-managed worker, which creates a persistent connection that Boundary uses in both directions.

When an end user connects to a target, the session traverses the following chain:

The Boundary client connects to the HCP-managed worker, which acts as the ingress worker.
The HCP-managed worker connects to the self-managed worker, which acts as the egress worker or an intermediate worker in multi-hop deployments.
The egress worker connects to the target.

If you need to reach further into a private network, you can add intermediate workers between the ingress and egress workers. Refer to Multi-hop sessions for more information about the worker roles.

Requirements

Before you configure multi-hop sessions for HCP Boundary, you must have:

An HCP Boundary cluster, and the cluster ID from its URL.
At least one host inside the private network with the Boundary Enterprise binary installed. Refer to Install Boundary.
Outbound network access from the self-managed worker to the HCP-managed workers on port 9202.
Permission to register workers in the global scope.

You do not need inbound network rules. The self-managed worker initiates the connection to the HCP-managed workers.

Allow outbound network traffic to HCP-managed workers

Some organizations require explicit destination addresses in their network firewall rules for any outbound traffic. In this scenario, use the fully qualified domain name (FQDN) of the HCP-managed workers:

<cluster_uuid>.proxy.boundary.hashicorp.cloud

The cluster_uuid value is the HCP Boundary cluster ID, which you can find in the HCP Boundary cluster's URL. The Boundary cluster ID is derived from the Boundary address. For example, if your cluster URL is:

https://abcd1234-e567-f890-1ab2-cde345f6g789.boundary.hashicorp.cloud

Then your cluster id is abcd1234-e567-f890-1ab2-cde345f6g789.

Configure the workers

An HCP Boundary multi-hop chain uses HCP-managed workers for ingress and at least one self-managed worker for egress. The following sections describe the role each worker performs and the configuration it requires.

Ingress workers

HCP Boundary deploys HCP-managed workers with your cluster, and those workers act as the ingress workers. You do not create or configure them.

Egress worker configuration

Configure the self-managed worker that connects to the HCP-managed workers and reaches the target. Set the following parameters:

hcp_boundary_cluster_id - The HCP Boundary cluster ID. Set this parameter at the top level of the file, outside the worker stanza.
Omit the public_addr parameter. The self-managed worker initiates the connection to the HCP-managed workers, so it does not need a reachable address.
Omit the initial_upstreams parameter. The hcp_boundary_cluster_id parameter already identifies the HCP-managed workers as the upstream.
Include a worker tag in the worker stanza. You use this tag to select multi-hop routes for each target.

/etc/boundary.d/egress-worker.hcl

hcp_boundary_cluster_id = "abcd1234-e567-f890-1ab2-cde345f6g789"

listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

worker {
  auth_storage_path = "/var/lib/boundary"

  tags {
    type = ["multihop", "egress"]
  }
}

Warning

Do not set both hcp_boundary_cluster_id and initial_upstreams in the same configuration file. The two parameters are mutually exclusive, and the worker fails to start:

Initial upstreams and HCPB cluster ID are mutually exclusive fields

Intermediate worker configuration

If the target sits deeper in the private network, you can add intermediate workers between the self-managed worker that connects to HCP Boundary and the worker that reaches the target.

The worker that connects to the HCP-managed workers is the one that sets hcp_boundary_cluster_id. Each worker below it sets initial_upstreams to the address of the worker above it, and omits hcp_boundary_cluster_id.

Refer to Configure multi-hop sessions for Boundary Enterprise for the intermediate and egress worker configurations. Those workers connect to an upstream worker rather than to HCP Boundary, so they use the same configuration as they do in a self-managed deployment.

Start and register the worker

Start the worker on its host:

$ boundary server -config=/etc/boundary.d/egress-worker.hcl

Refer to Start and verify a worker to run the worker under systemd or in a container.

Register the worker with your HCP Boundary cluster using the worker-led or controller-led method. You cannot combine the external KMS method with the hcp_boundary_cluster_id parameter. You also cannot configure a worker-auth KMS key for a worker that connects directly to the HCP-managed workers.

If you add intermediate workers, start and register them in order from the top of the chain down. A downstream worker cannot connect until its upstream is running and authorized.

Verify the chain

Use the following command to list the workers that are registered with the controller:

$ boundary workers list

Boundary returns each registered worker, its address, and its release version:

Worker information:
  ID:                        w_UJ3Qq63Jx0
    Version:                 1
    Address:                 10.0.0.10:9202
    ReleaseVersion:          Boundary v1.0.0+ent
    Last Status Time:        Fri, 07 Aug 2026 19:45:12 UTC
    Authorized Actions:
      no-op
      read
      update
      delete
      add-worker-tags
      set-worker-tags
      remove-worker-tags

A recent Last Status Time value indicates that the worker is connected to its upstream and reporting status.

Use the following command to view the details for a specific worker:

$ boundary workers read -id w_UJ3Qq63Jx0

Boundary returns the worker's configuration tags, storage state, and connected downstream workers:

Worker information:
  Active Connection Count:   0
  Address:                   10.0.0.10:9202
  Created Time:              Fri, 07 Aug 2026 13:44:30 MDT
  ID:                        w_UJ3Qq63Jx0
  Last Status Time:          2026-08-07 19:45:22.616245 +0000 UTC
  Local Storage State:       not configured
  Release Version:           Boundary v1.0.0+ent
  Type:                      pki
  Updated Time:              Fri, 07 Aug 2026 13:45:22 MDT
  Version:                   1

  Scope:
    ID:                      global
    Name:                    global
    Type:                    global

  Tags:
    Configuration:
      type: ["worker1" "ingress"]
    Canonical:
      type: ["worker1" "ingress"]

  Authorized Actions:
    no-op
    read
    update
    delete
    add-worker-tags
    set-worker-tags
    remove-worker-tags

The output includes the following fields that indicate worker health:

Last Status Time - The time the worker last reported status to a controller.
Local Storage State - The state of the worker's local storage. The value is not configured unless you configure the worker for session recording.
Release Version - The Boundary version the worker runs.
Tags - The Configuration tags come from the worker configuration file. The Canonical tags include both configuration tags and any API tags you add.

In a chain with more than one self-managed worker, the Directly Connected Downstream Workers field confirms the shape of the chain. Read each worker in turn and check that it lists the worker below it. The worker at the end of the chain has no downstream workers.

Route target traffic through the chain

To route traffic through the HCP-managed workers, set the egress worker filter on each target to match the tag you set in the self-managed worker's configuration file. You do not need to set an ingress worker filter, because the HCP-managed workers already act as the ingress workers.

Log in to Boundary.
Select the org, and then select the project that contains the target.
Select Targets, and then select the target.
Select the Workers tab.
Beside Egress workers, click Add Worker Filter, and enter a filter that matches the self-managed worker's tags:
```
"egress" in "/tags/type"
```
Click Save.

Multi-hop egress worker filter

The button reads Add Worker Filter when the target has no filter for that role, and Edit Worker Filter when a filter already exists.

Tip

The filter editor includes a generator that formats the filter for you from a worker tag or a worker name. Refer to Generate a filter in the Admin UI.

Apply the following Terraform configuration:

resource "boundary_target" "private_web" {
  type                 = "tcp"
  name                 = "private-web"
  description          = "Multi-hop target"
  scope_id             = boundary_scope.project.id
  default_port         = 443
  egress_worker_filter = "\"egress\" in \"/tags/type\""
}

Refer to Configure a worker filter for more filter examples.

Test the connection

Connect to the target to confirm that the session traverses the chain:

$ boundary connect -target-id ttcp_uPVxp2NGiD

If the session fails because no workers match the filter, refer to Troubleshoot workers.

Next steps

After you configure the chain, you can:

Verify SSH host identity on the worker that connects to targets.
Manage workers to reload configuration or drain sessions.
Configure self-managed workers for HCP Boundary for installation and sizing guidance.