Install self-managed workers

Navigate to the Boundary releases page and download the latest Boundary Enterprise binary for your operating system.

For Linux there are multiple versions of the binary available, based on distro and architecture. Select the correct package to download the zip to your local machine. Then, extract the boundary binary.

Alternatively, refer to the examples below for installing the latest version of the boundary-enterprise package using a package manager.

$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
$ sudo apt update && sudo apt install boundary-enterprise -y

$ sudo yum install -y yum-utils
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
$ sudo yum -y install boundary-enterprise

$ sudo dnf install -y dnf-plugins-core
$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
$ sudo dnf -y install boundary-enterprise

$ sudo yum install -y yum-utils shadow-utils
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
$ sudo yum -y install boundary-enterprise

After downloading the binary, ensure the boundary version matches the HCP Boundary control plane's version in order to benefit from the latest HCP Boundary features.

Use the following command to verify the version:

$ boundary version

Version information:
  Build Date:          2024-11-18T16:04:45Z
  Git Revision:        d648fb7e0fe80d45df04faa165161ede74014888
  Metadata:            ent
  Version Number:      0.18.1+ent

Navigate to the Boundary boundary releases page, and download the latest Boundary Enterprise binary for your operating system.

For MacOS there are two versions of the binary available, based on whether your processor is AMD64 (x86_64) or ARM64.

Select the correct package to download the boundary zip to your local machine. Then extract the boundary binary.

Alternatively, you can use the following commands to download the boundary binary.

Note that this example uses an AMD64 processor and the 0.11.2 version of the HCP Boundary control plane. Update these values to match the binary needed for your environment.

$ wget -q https://releases.hashicorp.com/boundary/0.13.0+ent/boundary_0.13.0+ent_darwin_amd64.zip ;\
/usr/bin/unzip *.zip

After downloading the binary, ensure the boundary version matches the HCP Boundary control plane's version in order to benefit from the latest HCP Boundary features.

Use the following command to verify the version:

$ ./boundary version

Version information:
  Build Date:          2024-11-18T16:04:45Z
  Git Revision:        d648fb7e0fe80d45df04faa165161ede74014888
  Metadata:            ent
  Version Number:      0.18.1+ent

Navigate to the Boundary boundary releases page, and download the latest Boundary Enterprise binary for your operating system.

For Windows there are two versions of the binary available, based on whether your processor is AMD64 (x86_64) or i386.

Select the correct package to download the boundary zip to your local machine. Then extract the boundary binary.

Alternatively, you can use the following command to download and extract the boundary binary. Note that this example uses an AMD64 processor and the 0.13.0 version of the HCP Boundary control plane. Update these values to match the binary needed for your environment.

$ Invoke-WebRequest -OutFile boundary.zip https://releases.hashicorp.com/boundary/0.13.0+ent/boundary_0.13.0+ent_windows_amd64.zip ;
Expand-Archive -Path boundary.zip -DestinationPath .

After downloading the binary, ensure the boundary version matches the HCP Boundary control plane's version in order to benefit from the latest HCP Boundary features.

Use the following command to verify the version:

$ .\boundary.exe version

Version information:
  Build Date:          2024-11-18T16:04:45Z
  Git Revision:        d648fb7e0fe80d45df04faa165161ede74014888
  Metadata:            ent
  Version Number:      0.18.1+ent

If you want to install boundary as a system-wide executable, update your system's global path to include the path to boundary.exe.

Create a new file to store the worker configuration.

$ touch worker.hcl

Open the worker.hcl file with a text editor, such as Vi. Paste the following configuration information into the worker.hcl file:

disable_mlock = true

hcp_boundary_cluster_id = "<cluster-id>"

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

worker {
  auth_storage_path = "/home/myusername/worker"
  tags {
    type = ["worker", "linux"]
  }
}

Update the configuration fields in the worker.hcl file as necessary. You can specify the following configuration fields for self-managed workers:

• The hcp_boundary_cluster_id field accepts a Boundary cluster ID and is used by the worker when it initially connects to HCP Boundary. You configure this field externally to the worker stanza.

  The cluster ID is the UUID in the HCP Boundary cluster URL. For example, the cluster ID is c3a7a20a-f663-40f3-a8e3-1b2f69b36254, if your cluster URL is:

  https://c3a7a20a-f663-40f3-a8e3-1b2f69b36254.boundary.hashicorp.cloud

• The listener stanza in the example above sets the address port to 0.0.0.0:9202. This port should already be configured by the AWS security group for this instance to accept inbound TCP connections. If you want to use a custom listener port, you can specify it in this field.

• If set, the public_addr field should match the public IP or DNS name of your self-managed worker instance. The public_addr does not need to be set if the worker has outbound access to an upstream worker or controller. In the unlikely event that you deploy the Boundary client and worker on the same local machine, you should omit the public_addr attribute.

  For an example of the Boundary client and worker being deployed on the same local machine, refer to the Configure the worker section of the self-managed worker tutorial.

• The auth_storage_path is a local path where the worker stores its credentials. You should not share storage between workers. This field should match the full path to the /worker/ directory, such as:

  /home/ubuntu/worker

• The initial_upstreams value indicates the address or addresses a worker uses when initially connecting to Boundary. You can use initial_upstreams in the worker stanza as an alternative to the hcp_boundary_cluster_id.

  For most use cases, the hcp_boundary_cluster_id is sufficient for ensuring that connectivity is always available, even if the HCP-managed upstream workers change. You should only configure an initial_upstreams value if you want to connect this worker to another self-managed or HCP-managed worker as part of a multi-hop sessions topology. Make sure to use hcp_boundary_cluster_id to connect self-managed workers to HCP Boundary.

  The example above uses the auth_storage_path and the hcp_boundary_cluster_id values. If you want to configure initial_upstreams instead, you should omit the hcp_boundary_cluster_id.

Save the worker.hcl file.

Create a new file to store the worker configuration.

$ touch worker.hcl

Open the worker.hcl file with a text editor, such as Vi. Paste the following configuration information into the worker.hcl file:

disable_mlock = true

hcp_boundary_cluster_id = "<cluster-id>"

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

worker {
  auth_storage_path = "/Users/myusername/worker"
  tags {
    type = ["worker", "macos"]
  }
}

Update the configuration fields in the worker.hcl file as necessary. You can specify the following configuration fields for self-managed workers:

• The hcp_boundary_cluster_id field accepts a Boundary cluster ID and is used by the worker when it initially connects to HCP Boundary. You configure this field externally to the worker stanza.

  The cluster ID is the UUID in the HCP Boundary cluster URL. For example, the cluster ID is c3a7a20a-f663-40f3-a8e3-1b2f69b36254, if your cluster URL is:

  https://c3a7a20a-f663-40f3-a8e3-1b2f69b36254.boundary.hashicorp.cloud

• The listener stanza in the example above sets the address port to 0.0.0.0:9202. This port should already be configured by the AWS security group for this instance to accept inbound TCP connections. If you want to use a custom listener port, you can specify it in this field.

• If set, the public_addr field should match the public IP or DNS name of your self-managed worker instance. The public_addr does not need to be set if the worker has outbound access to an upstream worker or controller. In the unlikely event that you deploy the Boundary client and worker on the same local machine, you should omit the public_addr attribute.

  For an example of the Boundary client and worker being deployed on the same local machine, refer to the Configure the worker section of the self-managed worker tutorial.

• The auth_storage_path is a local path where the worker stores its credentials. You should not share storage between workers. This field should match the full path to the /worker/ directory, such as:

  /home/ubuntu/worker

• The initial_upstreams value indicates the address or addresses a worker uses when initially connecting to Boundary. You can use initial_upstreams in the worker stanza as an alternative to the hcp_boundary_cluster_id.

  For most use cases, the hcp_boundary_cluster_id is sufficient for ensuring that connectivity is always available, even if the HCP-managed upstream workers change. You should only configure an initial_upstreams value if you want to connect to another self-managed worker. Make sure to use hcp_boundary_cluster_id to connect self-managed workers to HCP Boundary.

  The example above uses the auth_storage_path and the hcp_boundary_cluster_id values. If you want to configure initial_upstreams instead, you should omit the hcp_boundary_cluster_id.

Save the worker.hcl file.

Create a new file named worker.hcl:

$ touch worker.hcl

Open the worker.hcl file with a text editor. Paste the following configuration information into the worker.hcl file:

disable_mlock = true

hcp_boundary_cluster_id = "<cluster-id>"

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

worker {
  auth_storage_path = "C:/Users/myusername/worker"
  tags {
    type = ["worker", "windows"]
  }
}

Update the configuration fields in the worker.hcl file as necessary. You can specify the following configuration fields for self-managed workers:

• The hcp_boundary_cluster_id field accepts a Boundary cluster ID and is used by the worker when it initially connects to HCP Boundary. You configure this field externally to the worker stanza.

  The cluster ID is the UUID in the HCP Boundary cluster URL. For example, the cluster ID is c3a7a20a-f663-40f3-a8e3-1b2f69b36254, if your cluster URL is:

  https://c3a7a20a-f663-40f3-a8e3-1b2f69b36254.boundary.hashicorp.cloud

• The listener stanza in the example above sets the address port to 0.0.0.0:9202. This port should already be configured by the AWS security group for this instance to accept inbound TCP connections. If you want to use a custom listener port, you can specify it in this field.

• If set, the public_addr field should match the public IP or DNS name of your self-managed worker instance. The public_addr does not need to be set if the worker has outbound access to an upstream worker or controller. In the unlikely event that you deploy the Boundary client and worker on the same local machine, you should omit the public_addr attribute.

  For an example of the Boundary client and worker being deployed on the same local machine, refer to the Configure the worker section of the self-managed worker tutorial.

• The auth_storage_path is a local path where the worker stores its credentials. You should not share storage between workers. This field should match the full path to the /worker/ directory, such as:

  C:/Users/Administrator/worker

• The initial_upstreams value indicates the address or addresses a worker uses when initially connecting to Boundary. You can use initial_upstreams in the worker stanza as an alternative to the hcp_boundary_cluster_id.

  For most use cases, the hcp_boundary_cluster_id is sufficient for ensuring that connectivity is always available, even if the HCP-managed upstream workers change. You should only configure an initial_upstreams value if you want to connect to another self-managed worker. Make sure to use hcp_boundary_cluster_id to connect self-managed workers to HCP Boundary.

  The example above uses the auth_storage_path and the hcp_boundary_cluster_id values. If you want to configure initial_upstreams instead, you should omit the hcp_boundary_cluster_id.

Save the worker.hcl file.