194 lines
6.4 KiB
Plaintext
194 lines
6.4 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Server Configuration
|
||
sidebar_title: Configuration
|
||
description: Boundary configuration reference.
|
||
---
|
||
|
||
# Configuration
|
||
|
||
[listener]: /docs/configuration/listener
|
||
[telemetry]: /docs/configuration/telemetry
|
||
[controller]: /docs/configuration/controller
|
||
[worker]: /docs/configuration/worker
|
||
[kms]: /docs/configuration/kms
|
||
|
||
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.
|
||
|
||
## Parameters
|
||
|
||
- `controller` <tt>([Controller][controller]: \<required\>)</tt> - Controller specific configuration. Only required when running a `boundary controller`.
|
||
|
||
- `worker` <tt>([Worker][worker]: \<required\>)</tt> - Worker specific configuration. Only required when running a `boundary worker`.
|
||
|
||
- `listener` <tt>([Listener][listener]: \<required\>)</tt> – Configures the Boundary server
|
||
options for controllers and workers.
|
||
|
||
Controllers will have two listener blocks, one for the API server and the other for the data-plane
|
||
server. By default, controller API server runs on :9200 and the data-plane (which is used for
|
||
worker communication) uses :9201.
|
||
|
||
Workers will have only one listener.
|
||
|
||
- `kms` <tt>([KMS][kms]: \<required\>)</tt> – Configures KMS blocks for root, worker authentication, and recovery keys.
|
||
|
||
- `disable_mlock` `(bool: false)` – Disables the server from executing the
|
||
`mlock` syscall. `mlock` prevents memory from being swapped to disk. Disabling
|
||
`mlock` is not recommended in production, but is fine for local development
|
||
and testing.
|
||
|
||
Disabling `mlock` is not recommended unless the systems running Vault 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).
|
||
Non UNIX-like systems (e.g. Windows, NaCL, Android) lack the primitives to keep a
|
||
process's entire memory address space from spilling to disk and is therefore
|
||
automatically disabled on unsupported platforms.
|
||
|
||
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 vault))
|
||
```
|
||
|
||
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
|
||
```
|
||
|
||
- `telemetry` <tt>([Telemetry][telemetry]: <none>)</tt> – Not yet implemented.
|
||
|
||
- `log_level` `(string: "")` – Specifies the log level to use; overridden by
|
||
CLI and env var parameters. Supported log levels: Trace, Debug, Error, Warn, Info.
|
||
|
||
- `log_format` `(string: "")` – Specifies the log format to use; overridden by
|
||
CLI and env var parameters. Supported log formats: "standard", "json".
|
||
|
||
## Example Configurations
|
||
|
||
The following examples are broken down for controllers and workers. If you're running an all-in-one deployment with the controller and worker on the same host via `boundary server`, then concatonate these files together.
|
||
|
||
### Controller Configuration
|
||
|
||
```hcl
|
||
# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
|
||
disable_mlock = true
|
||
|
||
telemetry {
|
||
# TODO: prometheus is not currently implemented
|
||
prometheus_retention_time = "24h"
|
||
disable_hostname = true
|
||
}
|
||
|
||
# Controller configuration block
|
||
controller {
|
||
# This name attr must be unique!
|
||
name = "demo-controller-${count.index}"
|
||
# Description of this controller
|
||
description = "A controller for a demo!"
|
||
}
|
||
|
||
# API listener configuration block
|
||
listener "tcp" {
|
||
# Should be the address of the NIC that the controller server will be reached on
|
||
address = "${self.private_ip}:9200"
|
||
# The purpose of this listener block
|
||
purpose = "api"
|
||
# Should be enabled for production installs
|
||
tls_disable = true
|
||
# TODO
|
||
# proxy_protocol_behavior = "allow_authorized"
|
||
# TODO
|
||
# proxy_protocol_authorized_addrs = "127.0.0.1"
|
||
# Enable CORS for the Admin UI
|
||
cors_enabled = true
|
||
cors_allowed_origins = ["*"]
|
||
}
|
||
|
||
# Data-plane listener configuration block (used for worker coordination)
|
||
listener "tcp" {
|
||
# Should be the IP of the NIC that the worker will connect on
|
||
address = "${self.private_ip}:9201"
|
||
# The purpose of this listener
|
||
purpose = "cluster"
|
||
# Should be enabled for production installs
|
||
tls_disable = true
|
||
# TODO
|
||
# proxy_protocol_behavior = "allow_authorized"
|
||
# TODO
|
||
# proxy_protocol_authorized_addrs = "127.0.0.1"
|
||
}
|
||
|
||
# Root KMS configuration block: this is the root key for Boundary
|
||
# Use a production KMS such as AWS KMS in production installs
|
||
kms "aead" {
|
||
purpose = "root"
|
||
aead_type = "aes-gcm"
|
||
key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
|
||
key_id = "global_root"
|
||
}
|
||
|
||
# Worker authorization KMS
|
||
# Use a production KMS such as AWS KMS for production installs
|
||
# This key is the same key used in the worker configuration
|
||
kms "aead" {
|
||
purpose = "worker-auth"
|
||
aead_type = "aes-gcm"
|
||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||
key_id = "global_worker-auth"
|
||
}
|
||
|
||
# Recovery KMS block: configures the recovery key for Boundary
|
||
# Use a production KMS such as AWS KMS for production installs
|
||
kms "aead" {
|
||
purpose = "recovery"
|
||
aead_type = "aes-gcm"
|
||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||
key_id = "global_recovery"
|
||
}
|
||
|
||
# Database URL for postgres. This can be a direct "postgres://"
|
||
# URL, or it can be "file://" to read the contents of a file to
|
||
# supply the url, or "env://" to name an environment variable
|
||
# that contains the URL.
|
||
database {
|
||
url = "postgresql://boundary:boundarydemo@${aws_db_instance.boundary.endpoint}/boundary"
|
||
}
|
||
```
|
||
|
||
### Worker Configuration
|
||
|
||
```hcl
|
||
listener "tcp" {
|
||
purpose = "proxy"
|
||
tls_disable = true
|
||
#proxy_protocol_behavior = "allow_authorized"
|
||
#proxy_protocol_authorized_addrs = "127.0.0.1"
|
||
}
|
||
|
||
worker {
|
||
# Name attr must be unique
|
||
name = "demo-worker-${count.index}"
|
||
description = "A default worker created demonstration"
|
||
controllers = [
|
||
"${aws_instance.controller[0].private_ip}",
|
||
"${aws_instance.controller[1].private_ip}",
|
||
"${aws_instance.controller[2].private_ip}"
|
||
]
|
||
}
|
||
|
||
# must be same key as used on controller config
|
||
kms "aead" {
|
||
purpose = "worker-auth"
|
||
aead_type = "aes-gcm"
|
||
key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
|
||
key_id = "global_worker-auth"
|
||
}
|
||
```
|