threshold/website/content/docs/workers/index.mdx

---
layout: docs
page_title: Worker configuration overview
description: >-
  Learn about worker configuration for proxies, storage, and tags. Understand how multi-hop configurations let you chain workers together in private networks.
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

# Overview of workers

Workers are primarily used as network proxies for Boundary sessions, they allow you to access private targets. Instead of exposing a private network to the public, or allowing users to have access to entire private networks, workers create a direct network tunnel between users and targets.

Workers are services that can run on a container or virtual machine. You should deploy them strategically within networks to provide access to targets.
In all editions of Boundary, workers are fully self-managed and can be deployed anywhere.
In HCP Boundary, HCP-managed workers are automatically deployed with the cluster.

All workers within Boundary use certificates and encryption keys to identify
themselves and protect data in transit. However, there are three different
ways to register them so that registration of workers can fit into any workflow: controller-led, worker-led, and via external KMS.

You must register workers using the worker-led or controller-led methods in the system with an API call. These workers require storage on disk to store the current set of credentials. Workers using an external KMS auto-register after authenticating. This makes them an easy mechanism to use for automatic scaling.
This also means they do not need to store
credentials locally; the KMS re-authenticates them each time they connect.

<Note title="Important">

Before version 0.15 of Boundary, there were two different types of workers, PKI & KMS workers.
If you are using pre-0.15 workers with pre-0.15 upstream configurations, please switch the documentation version to `0.13.x` - `0.14.x`. This will ensure you have the correct information.

</Note>

## Signals

The `SIGHUP` signal causes a worker to reload its configuration file to pick up any updates for the `initial_upstreams` and `tags` values.
Boundary ignores other updated values.

The `SIGTERM` and `SIGINT` signals initiate a graceful shutdown on a worker. The worker waits for any sessions to drain
before shutting down. Workers in a graceful shutdown state do not receive any new work, including session proxying, from the control plane.

## Session recording

<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>

Session recording requires at least one worker with access to local and remote storage.
Workers used for session recording require an accessible directory defined by `recording_storage_path` for storing in-progress session recordings. On session closure, a local session recording is moved to remote storage and deleted locally.

The `recording_storage_minimum_available_capacity` value determines the minimum amount of storage space that is required for workers to perform session recording operations. If a worker is at or below the storage threshold, Boundary does not use the worker to record sessions or play back recordings.

Development example:

```hcl
worker {
  auth_storage_path="/var/lib/boundary"
  initial_upstreams = ["10.0.0.1"]
  recording_storage_path="/local/storage/directory"
  recording_storage_minimum_available_capacity="500MB"
}
```

## Multi-hop sessions

<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>

Multi-hop capabilities, including multi-hop sessions and Vault private access,
is when a session or Vault credential request goes through more than one worker.
To enable this, you must connect two or more workers to each other in some
configuration. There are no limits on the number of workers allowed in a
multi-hop session configuration.

It helps to think of “upstream” and “downstream” nodes in the context of
multi-hop. If you view controllers as the “top” node of a multi-hop chain, any
worker connected to a node is "downstream" of that node. The node that any
particular worker connects to (whether another worker or a controller) is the
"upstream" of that node. For example, in the diagram below, Worker 2’s upstream
is Worker 1, and its downstream is Worker 3.

![multi-hop workers](/img/multi-hop-workers.png)

You can deploy multi-hop workers in scenarios where inbound network traffic is
not allowed. A worker in a private network can send outbound communication to
its upstream worker, and create a reverse proxy to establish a session.

You can configure target worker filters with multi-hop workers to allow for
fine-grained control on which workers handle ingress and egress for session
traffic to a target. Ingress worker filters specify the workers you use to initiate a session, and egress worker filters specify the workers you use to access targets.

## Common worker parameters

@include '/configuration-reference/workers/common-worker-parameters.mdx'


## Complete configuration example

@include '/configuration-reference/workers/complete-configuration-example.mdx'

## Tutorials

Refer to the [worker management](/boundary/tutorials/worker-management) tutorials for practice managing workers, configuring multi-hop sessions, and creating worker-aware targets.

Refer to the [Self-managed worker registration with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-workers) tutorial to learn how to register and manage workers.

Refer to the [Manage multi-hop sessions with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-multi-hop) tutorial to learn how to configure a multi-hop session.

## More information

Refer to [Filtering and listing resources](/boundary/docs/filtering) for more information about Boundary's filter syntax and best practices.

To configure and register a worker, refer to the following topics:

- [Create the worker configuration](/boundary/docs/workers/create)
- [Register workers](/boundary/docs/workers/registration)

Refer to the following topics for more information about configuring workers for specific applications or workflows:

- [Overview of multi-hop sessions](/boundary/docs/workers/multi-hop)
  - [Configure multi-hop sessions for Boundary Enterprise](/boundary/docs/workers/multi-hop/enterprise)
  - [Configure multi-hop sessions for HCP Boundary](/boundary/docs/workers/multi-hop/hcp)
- [Overview of session recording](/boundary/docs/session-recording)
  - [Configure workers for session recording](/boundary/docs/session-recording/configuration/configure-worker-storage)
- [Configure workers for access to Vault](/boundary/docs/workers/filters#example-worker-filter-for-vault-credential-store)
- [Configure workers for dynamic host discovery from cloud providers](/boundary/docs/hosts)
- [Route traffic through a worker](/boundary/docs/workers/worker-tags)
- [Configure a worker filter](/boundary/docs/workers/filters)
- [Configure self-managed workers for HCP Boundary](/hcp/docs/boundary/self-managed-workers)