Configuration

Outside of development mode, Boundary controllers and workers are configured using a file. The format of this file is HCL. In this section you'll find configuration block examples for Boundary controllers and workers.

After the configuration is written, use the -config flag to specify a local path to the file.

HCP Boundary-only parameters

hcp_boundary_cluster_id (string) - The ID of an HCP Boundary cluster. Setting this allows discovery of upstream addresses for self-managed workers to connect to the cluster.

Shared self-managed and HCP Boundary parameters

worker: Worker specific configuration. If present, boundary server will start a Worker subprocess.
listener: Configures the listeners on which Boundary serves traffic (API, cluster, and proxy).
Controllers must have at least two listener blocks defined: one marked for api purpose and the other marked for cluster purpose.
Workers will have only one listener, marked for proxy purpose.
Optionally, the ops purpose listener block serves as a higher-level listener where Boundary's operational endpoints live (eg: /health).
kms: Configures KMS blocks for various purposes.
events: Configures event (observability, audit, error) handling.
disable_mlock (bool: false) – Disables the server from executing the mlock syscall, which prevents memory from being swapped to disk. This is fine for local development and testing; in production, it is not recommended unless the systems running Boundary only use encrypted swap or do not use swap at all. Boundary only supports memory locking on UNIX-like systems that support the mlock() syscall (Linux, FreeBSD, etc).
On Linux, to give the Boundary executable the ability to use the mlock syscall without running the process as root, run:
```
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))
```
If you use a Linux distribution with a modern version of systemd, you can add the following directive to the "[Service]" configuration section:
```
LimitMEMLOCK=infinity
```
log_level (string: "info") – (Deprecated: this is being phased out in favor of observability and is currently only used as a backup if eventing fails.) Specifies the log level to use; overridden by CLI and env var parameters. Supported log levels: Trace, Debug, Error, Warn, Info.
log_format (string: "") – (Deprecated: this is being phased out in favor of observability and is currently only used as a backup if eventing fails.) Specifies the log format to use; overridden by CLI and env var parameters. Supported log formats: "standard", "json".

Self-managed Boundary-only parameters

controller: Controller specific configuration. If present, boundary server will start a Controller subprocess.
plugins: Configures options for plugins.

Signals

The SIGHUP signal causes worker and controller processes to reload their configuration files to pick up updated values.

Note: You cannot reload all configuration values using the SIGHUP signal. Refer to the configuration pages for workers and controllers for details on which values can be reloaded on SIGHUP.

The SIGTERM and SIGINT signals cause worker and controller processes to enter graceful shutdown. A graceful shutdown for a controller closes listeners and servers before shutting down the controller. A graceful shutdown for a worker waits for any sessions to drain before shutting down the worker. Workers in a graceful shutdown state do not receive any new work, including session proxying, from the control plane.

Example configurations

For complete example configurations see the sections for controller and worker.