Install self-managed workers

HCP Boundary allows organizations to register and manage their own workers. You can deploy these self-managed workers in private networks, and they can communicate with an upstream HCP Boundary cluster.

For a step-by-step example of configuring a self-managed worker instance, refer to the self-managed workers tutorial.

To install and configure a self-managed worker, complete the procedures below.

Download the Boundary Enterprise binary

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

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:          2023-06-07T16:41:10Z
  Git Revision:        fb4ed58459d555d480e70ddc20d2639c26ad0f8f
  Metadata:            ent
  Version Number:      0.13.0+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:          2023-06-07T16:41:10Z
  Git Revision:        fb4ed58459d555d480e70ddc20d2639c26ad0f8f
  Metadata:            ent
  Version Number:      0.13.0+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:          2023-06-07T16:41:10Z
  Git Revision:        fb4ed58459d555d480e70ddc20d2639c26ad0f8f
  Metadata:            ent
  Version Number:      0.13.0+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 the self-managed worker configuration file

Next, create a self-managed worker configuration file. Refer to the complete configuration example to view all valid configuration options.

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:

worker.hcl

1 2 3 4 5 6 7 8 9 101112131415disable_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:

worker.hcl

1 2 3 4 5 6 7 8 9 101112131415disable_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:

worker.hcl

1 2 3 4 5 6 7 8 9 101112131415disable_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/myusername/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.

Start the self-managed worker

Once the configuration file is created, you can start the worker server. Use the following command to start the server. You must provide the full path to the worker configuration file, for example /home/worker.hcl.

Note the Worker Auth Registration Request: value on line 12. You can also locate this value in the auth_request_token file. You must provide this value when you Register a new worker with HCP.

Enter the following command to start the worker:

worker.hcl

1 2 3 4 5 6 7 8 9 101112131415161718$ ./boundary-worker server -config="/home/myusername/worker.hcl"

==> Boundary server configuration:

                             Cgo: disabled
                      Listener 1: tcp (addr: "0.0.0.0:9202", max_request_duration: "1m30s", purpose: "proxy")
                       Log Level: info
                           Mlock: supported: true, enabled: false
                         Version: Boundary v0.11.2+hcp
                     Version Sha: f0006502c93b51291896b4c9a1d2d5290796f9ce
      Worker Auth Current Key Id: knoll-unengaged-twisting-kite-envelope-dock-liftoff-legend
Worker Auth Registration Request: GzusqckarbczHoLGQ4UA25uSR7RQJqCjDfxGSJZvEpwQpE7HzYvpDJ88a4QMP3cUUeBXhS5oTgck3ZvZ3nrZWD3HxXzgq4wNScpy7WE7JmNrrGNLNEFeqqMcyhjqGJVvg2PqiZA6arL6zYLNLNCEFtRhcvG5LLMeHc3bthkrbwLg7R7TNswTjDJWmwh4peYpnKuQ9qHEuTK9fapmw4fdvRTiTbrq78ju4asvLByFTCTR3nbk62Tc15iANYsUAn9JLSxjgRXTsuTBkp4QoqBqz89pEi258Wd1ywcACBHRT3
        Worker Auth Storage Path: /home/ubuntu/worker
        Worker Public Proxy Addr: 52.90.177.171:9202

==> Boundary server started! Log data will stream in below:

{"id":"l0UQKrAg7b","source":"https://hashicorp.com/boundary/ip-172-31-86-85/worker","specversion":"1.0","type":"system","data":{"version":"v0.1","op":"worker.(Worker).StartControllerConnections","data":{"msg":"Setting HCP Boundary cluster address 6f40d99c-ed7a-4f22-ae52-931a5bc79c03.proxy.boundary.hashicorp.cloud:9202 as upstream address"}},"datacontentype":"application/cloudevents","time":"2023-01-10T04:34:52.616180263Z"}

worker.hcl

1 2 3 4 5 6 7 8 9 101112131415161718$ ./boundary-worker server -config="/Users/myusername/worker.hcl"

==> Boundary server configuration:

                             Cgo: disabled
                      Listener 1: tcp (addr: "0.0.0.0:9202", max_request_duration: "1m30s", purpose: "proxy")
                       Log Level: info
                           Mlock: supported: true, enabled: false
                         Version: Boundary v0.11.2+hcp
                     Version Sha: f0006502c93b51291896b4c9a1d2d5290796f9ce
      Worker Auth Current Key Id: knoll-unengaged-twisting-kite-envelope-dock-liftoff-legend
Worker Auth Registration Request: GzusqckarbczHoLGQ4UA25uSRmUHY1BGSRA6cePp8RWHQFUYSrf3hnDw4ETPswFnMrcxx6tq7BUWD5azGULzPecPicuYGD6qg3qYvaGRgHgKwvh9FLY9Gu891KSj8hAef19JjHog8d7qpo9f9KoiwrhfcV2YxGyVu1P943656iNGCFHWiBR3ofsyTatQ7fzcMV2ciKtuYYGfx4FfiRStnkAzoE98RdR2LeCk2huRkFt7ayeeWVfD7Awm8xaZfFJn4pYRJwu2LRBeNs915warEBaS8XHXSKoi3cRUYif8Qu
        Worker Auth Storage Path: /Users/myusername/worker
        Worker Public Proxy Addr: 52.90.177.171:9202

==> Boundary server started! Log data will stream in below:

{"id":"l0UQKrAg7b","source":"https://hashicorp.com/boundary/ip-172-31-86-85/worker","specversion":"1.0","type":"system","data":{"version":"v0.1","op":"worker.(Worker).StartControllerConnections","data":{"msg":"Setting HCP Boundary cluster address 6f40d99c-ed7a-4f22-ae52-931a5bc79c03.proxy.boundary.hashicorp.cloud:9202 as upstream address"}},"datacontentype":"application/cloudevents","time":"2023-01-10T04:34:52.616180263Z"}

worker.hcl

1 2 3 4 5 6 7 8 9 101112131415161718$ .\boundary-worker.exe server -config="C:\Users\myusername\worker.hcl"

==> Boundary server configuration:

                             Cgo: disabled
                      Listener 1: tcp (addr: "0.0.0.0:9202", max_request_duration: "1m30s", purpose: "proxy")
                       Log Level: info
                           Mlock: supported: true, enabled: false
                         Version: Boundary v0.11.2+hcp
                     Version Sha: f0006502c93b51291896b4c9a1d2d5290796f9ce
      Worker Auth Current Key Id: knoll-unengaged-twisting-kite-envelope-dock-liftoff-legend
Worker Auth Registration Request: GzusqckarbczHoLGQ4UA25uSRmUHY1BGSRA6cePp8RWHQFUYSrf3hnDw4ETPswFnMrcxx6tq7BUWD5azGULzPecPicuYGD6qg3qYvaGRgHgKwvh9FLY9Gu891KSj8hAef19JjHog8d7qpo9f9KoiwrhfcV2YxGyVu1P943656iNGCFHWiBR3ofsyTatQ7fzcMV2ciKtuYYGfx4FfiRStnkAzoE98RdR2LeCk2huRkFt7ayeeWVfD7Awm8xaZfFJn4pYRJwu2LRBeNs915warEBaS8XHXSKoi3cRUYif8Qu
        Worker Auth Storage Path: C:\Users\myusername\worker
        Worker Public Proxy Addr: 52.90.177.171:9202

==> Boundary server started! Log data will stream in below:

{"id":"l0UQKrAg7b","source":"https://hashicorp.com/boundary/ip-172-31-86-85/worker","specversion":"1.0","type":"system","data":{"version":"v0.1","op":"worker.(Worker).StartControllerConnections","data":{"msg":"Setting HCP Boundary cluster address 6f40d99c-ed7a-4f22-ae52-931a5bc79c03.proxy.boundary.hashicorp.cloud:9202 as upstream address"}},"datacontentype":"application/cloudevents","time":"2023-01-10T04:34:52.616180263Z"}

The worker starts and outputs its authorization token as Worker Auth Registration Request. It is also saved to a file, auth_request_token, defined by the auth_storage_path in the worker configuration file.

After you install and start the self-managed worker, you must register it with HCP in your environment's admin console.