---
layout: docs
page_title: Controller - Configuration
sidebar_title: controller
description: |-
  The controller stanza configures controller-specifc parameters.
---

# `controller` Stanza

The `controller` stanza configures Boundary controller-specific parameters.

```hcl
controller {
  name = "example-controller"
  description = "An example controller"
  database {
    url = "postgresql://<username>:<password>@10.0.0.1:5432/<database_name>"
  }
}
```

- `name` - Specifies a unique name of this controller within the Boundary controller cluster.

- `description` - Specifies a friendly description of this controller.

- `database` - Configuration block with two valid parameters for connecting to Postgres:

  - `url` - Configures the URL for connecting to Postgres
  - `migration_url` - Can be used to specify a different URL for migrations, as that
    usually requires higher privileges.

  Either can refer to a file on disk (file://) from which a URL will be read; an env
  var (env://) from which the URL will be read; or a direct database URL (postgres://).

- `public_cluster_addr` - Specifies the public host or IP address (and
  optionally port) at which the controller can be reached _by workers_. This will
  be used by workers after initial connection to controllers via the worker's
  `controllers` block. This defaults to the address of the listener marked for
  `cluster` purpose. This is especially useful for cloud environments that do not
  bind a publicly accessible IP to a NIC on the host directly, such as an Amazon
  EIP. This value can be a direct address string, can refer to a file on disk (file://)
  from which an address will be read; or an env var (env://) from which the
  address will be read.

- `auth_token_time_to_live` - Maximum time to live (TTL) for all auth tokens globally (pertains
  to all tokens from all auth methods). Valid time units are anything specified by Golang's
  [ParseDuration()](https://golang.org/pkg/time/#ParseDuration) method. Default is 7 days.
- `auth_token_time_to_stale` - Maximum time of inactivity for all auth tokens globally (pertains
  to all tokens from all auth methods). Valid time units are anything specified by Golang's
  [ParseDuration()](https://golang.org/pkg/time/#ParseDuration) method. Default is 1 day.

## KMS Configuration

The controller requires two KMS stanzas for `root` and `worker-auth` purposes:

```kms
# 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"
}
```

And optionally, a KMS stanza for recovery purpose:

```hcl
# 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"
}
```

And optionally, a KMS stanza for configuration encryption purpose:

```hcl
# Configuration encryption block: decrypts sensitive values in the
# configuration file. See `boundary config [encrypt|decrypt] -h`.
kms "aead" {
  purpose   = "config"`
  aead_type = "aes-gcm"
  key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
}
```

Boundary supports many kinds of KMS integrations. For a complete guide to all available
KMS types, see our [KMS documentation](/docs/configuration/kms).

# Complete Configuration Example

```hcl
# Disable memory lock: https://www.man7.org/linux/man-pages/man2/mlock.2.html
disable_mlock = true

# Controller configuration block
controller {
  # This name attr must be unique across all controller instances if running in HA mode
  name = "demo-controller-1"
  description = "A controller for a demo!"

  # 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"
  }
}

# API listener configuration block
listener "tcp" {
  # Should be the address of the NIC that the controller server will be reached on
  address = "10.0.0.1"
  # The purpose of this listener block
  purpose = "api"

  tls_disable = false

  # Uncomment to enable CORS for the Admin UI. Be sure to set the allowed origin(s)
  # to appropriate values.
  #cors_enabled = true
  #cors_allowed_origins = ["yourcorp.yourdomain.com"]
}

# 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 = "10.0.0.1"
  # The purpose of this listener
  purpose = "cluster"

  tls_disable = false
}

# 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"
}
```