Irena RindosandDan Heath
b4a8032649
* docs: Update website to include SIGHUP, SIGTERM, and SIGINT behaviour Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
105 lines
4.5 KiB
Plaintext
105 lines
4.5 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Overview/Top-Level Parameters
|
||
description: Boundary configuration reference.
|
||
---
|
||
|
||
# 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 OSS 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"`.
|
||
|
||
## OSS-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).
|