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

---
layout: docs
page_title: Top-level configuration parameters
description: >-
  Learn about the parameters that make up the Boundary HCL configuration file. View parameters for HCP and self-managed installations.
---

# Configuration

[listener]: /boundary/docs/configuration/listener
[controller]: /boundary/docs/configuration/controller
[worker]: /boundary/docs/configuration/worker
[kms]: /boundary/docs/configuration/kms
[plugins]: /boundary/docs/configuration/plugins
[events]: /boundary/docs/configuration/events

Outside of development mode, Boundary controllers and workers are configured
using a file. The format of this file is
[HCL](https://github.com/hashicorp/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`](/boundary/docs/configuration/worker): Worker specific configuration. If
  present, `boundary server` will start a Worker subprocess.

- [`listener`](/boundary/docs/configuration/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`](/boundary/docs/configuration/kms): Configures KMS blocks [for various
  purposes](/boundary/docs/concepts/security/data-encryption).

- [`events`](/boundary/docs/configuration/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:

  ```shell
  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:

  ```ini
  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`](/boundary/docs/configuration/controller): Controller specific
  configuration. If present, `boundary server` will start a Controller subprocess.

- [`plugins`](/boundary/docs/configuration/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](/boundary/docs/configuration/worker/) and [controllers](/boundary/docs/configuration/controller) 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](/boundary/docs/configuration/controller) and
[worker](/boundary/docs/configuration/worker).