diff --git a/internal/cmd/base/servers.go b/internal/cmd/base/servers.go index fb2dae702..6f4bef1a7 100644 --- a/internal/cmd/base/servers.go +++ b/internal/cmd/base/servers.go @@ -312,7 +312,8 @@ func (b *Server) SetupListeners(ui cli.Ui, config *configutil.SharedConfig, allo if lnConfig.MaxRequestSize == 0 { lnConfig.MaxRequestSize = globals.DefaultMaxRequestSize } - props["max_request_size"] = fmt.Sprintf("%d", lnConfig.MaxRequestSize) + // TODO: We don't actually limit this yet. + //props["max_request_size"] = fmt.Sprintf("%d", lnConfig.MaxRequestSize) if lnConfig.MaxRequestDuration == 0 { lnConfig.MaxRequestDuration = globals.DefaultMaxRequestDuration diff --git a/website/content/docs/configuration/controller.mdx b/website/content/docs/configuration/controller.mdx index aa570dc0d..321d3c6ae 100644 --- a/website/content/docs/configuration/controller.mdx +++ b/website/content/docs/configuration/controller.mdx @@ -26,7 +26,7 @@ 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 the migrations, as that + - `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 diff --git a/website/content/docs/configuration/index.mdx b/website/content/docs/configuration/index.mdx index ae39cd209..7a518287e 100644 --- a/website/content/docs/configuration/index.mdx +++ b/website/content/docs/configuration/index.mdx @@ -21,38 +21,37 @@ After the configuration is written, use the `-config` flag to specify a local pa ## Parameters -- `controller` ([Controller][controller]: \) - Controller specific configuration. Only required when running a `boundary controller`. +- [`controller`](/docs/configuration/controller): Controller specific +configuration. If present, `boundary server` will start a Controller subprocess. -- `worker` ([Worker][worker]: \) - Worker specific configuration. Only required when running a `boundary worker`. +- [`worker`](/docs/configuration/worker): Worker specific configuration. If +present, `boundary server` will start a Worker subprocess. -- `listener` ([Listener][listener]: \) – Configures the Boundary server - options for controllers and workers. +- [`listener`](/docs/configuration/listener): Configures the listeners on which +Boundary serves traffic (API, cluster, and proxy). - 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. + Controllers will have two listener blocks: one marked for `api` purpose and + the other marked for `cluster` purpose. By default, the API listener runs on + :9200 and the cluster listener (currently used for worker communication) uses + :9201. - Workers will have only one listener. + Workers will have only one listener, marked for `proxy` purpose. -- `kms` ([KMS][kms]: \) – Configures KMS blocks for root, worker authentication, and recovery keys. +- [`kms`](/docs/configuration/kms): Configures KMS blocks [for various +purposes](/docs/concepts/security/data-encryption). - `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. + `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 vault)) + 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 @@ -62,13 +61,11 @@ After the configuration is written, use the `-config` flag to specify a local pa LimitMEMLOCK=infinity ``` -- `telemetry` ([Telemetry][telemetry]: <none>) – Not yet implemented. - -- `log_level` `(string: "")` – Specifies the log level to use; overridden by +- `log_level` `(string: "info")` – 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". + CLI and env var parameters. Supported log formats: `"standard"`, `"json"`. ## Example Configurations diff --git a/website/content/docs/configuration/kms/aead.mdx b/website/content/docs/configuration/kms/aead.mdx index 854810342..01ff1ace7 100644 --- a/website/content/docs/configuration/kms/aead.mdx +++ b/website/content/docs/configuration/kms/aead.mdx @@ -1,11 +1,16 @@ --- layout: docs -page_title: KMS AEAD - Configuration -sidebar_title: KMS AEAD +page_title: AEAD - Configuration +sidebar_title: AEAD description: |- - The KMS AEAD configures KMS-specifc parameters. + The AEAD KMS configures AEAD-specifc parameters. --- +~> This is mostly used for `dev` workflows or testing. The key will be exposed +to anyone that can view the configuration file. If using this KMS, consider +using `boundary config encrypt` to encrypt all but the `config` KMS and using an +external KMS for `config` purposes. + ```hcl kms "aead" { purpose = "worker-auth" @@ -15,10 +20,10 @@ kms "aead" { } ``` -- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, and `recovery`. +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, `recovery`, or `config`. -- `aead_type` - The type of encryption this KMS uses. +- `aead_type` - The type of encryption this KMS uses. Currently only `aes-gcm` is implemented. -- `key` - Optional, a hard coded key if not using an external KMS. +- `key` - The base64-encoded 256-bit encryption key. - `key_id` - The unique name of this key. diff --git a/website/content/docs/configuration/kms/alicloudkms.mdx b/website/content/docs/configuration/kms/alicloudkms.mdx index 4490815d6..9e4eaf297 100644 --- a/website/content/docs/configuration/kms/alicloudkms.mdx +++ b/website/content/docs/configuration/kms/alicloudkms.mdx @@ -20,6 +20,7 @@ by providing all the required values: ```hcl kms "alicloudkms" { + purpose = "root" region = "us-east-1" access_key = "0wNEpMMlzy7szvai" secret_key = "PupkTg8jdmau1cXxYacgE736PJj4cA" @@ -31,6 +32,8 @@ kms "alicloudkms" { These parameters apply to the `kms` stanza in the Boundary configuration file: +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, `recovery`, or `config`. + - `region` `(string: "us-east-1")`: The AliCloud region where the encryption key lives. May also be specified by the `ALICLOUD_REGION` environment variable. @@ -48,7 +51,7 @@ These parameters apply to the `kms` stanza in the Boundary configuration file: part of the AliCloud profile from the AliCloud CLI or instance profile. - `kms_key_id` `(string: )`: The AliCloud KMS key ID to use for encryption - and decryption. May also be specified by the `VAULT_ALICLOUDKMS_SEAL_KEY_ID` + and decryption. May also be specified by the `ALICLOUDKMS_WRAPPER_KEY_ID` environment variable. ## Authentication diff --git a/website/content/docs/configuration/kms/awskms.mdx b/website/content/docs/configuration/kms/awskms.mdx index 97dbc66cd..f179730c5 100644 --- a/website/content/docs/configuration/kms/awskms.mdx +++ b/website/content/docs/configuration/kms/awskms.mdx @@ -18,6 +18,7 @@ by providing all the required values: ```hcl kms "awskms" { + purpose = "root" region = "us-east-1" access_key = "AKIAIOSFODNN7EXAMPLE" secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" @@ -30,6 +31,9 @@ kms "awskms" { These parameters apply to the `kms` stanza in the Boundary configuration file: +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, +`recovery`, or `config`. + - `region` `(string: "us-east-1")`: The AWS region where the encryption key lives. If not provided, may be populated from the `AWS_REGION` or `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file, @@ -47,7 +51,7 @@ These parameters apply to the `kms` stanza in the Boundary configuration file: part of the AWS profile from the AWS CLI or instance profile. - `kms_key_id` `(string: )`: The AWS KMS key ID to use for encryption - and decryption. May also be specified by the `VAULT_AWSKMS_SEAL_KEY_ID` + and decryption. May also be specified by the `AWSKMS_WRAPPER_KEY_ID` environment variable. - `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS diff --git a/website/content/docs/configuration/kms/azurekeyvault.mdx b/website/content/docs/configuration/kms/azurekeyvault.mdx index 3c6515fe2..4e30870b4 100644 --- a/website/content/docs/configuration/kms/azurekeyvault.mdx +++ b/website/content/docs/configuration/kms/azurekeyvault.mdx @@ -20,6 +20,7 @@ configuration file by providing all the required values: ```hcl kms "azurekeyvault" { + purpose = "root" tenant_id = "46646709-b63e-4747-be42-516edeaf1e14" client_id = "03dc33fc-16d9-4b77-8152-3ec568f8af6e" client_secret = "DUJDS3..." @@ -32,6 +33,8 @@ kms "azurekeyvault" { These parameters apply to the `kms` stanza in the Vault configuration file: +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, `recovery`, or `config`. + - `tenant_id` `(string: )`: The tenant id for the Azure Active Directory organization. May also be specified by the `AZURE_TENANT_ID` environment variable. @@ -45,10 +48,10 @@ These parameters apply to the `kms` stanza in the Vault configuration file: be specified by the `AZURE_ENVIRONMENT` environment variable. - `vault_name` `(string: )`: The Key Vault vault to use the encryption keys for encryption and - decryption. May also be specified by the `VAULT_AZUREKEYVAULT_VAULT_NAME` environment variable. + decryption. May also be specified by the `AZUREKEYVAULT_WRAPPER_VAULT_NAME` environment variable. - `key_name` `(string: )`: The Key Vault key to use for encryption and decryption. May also be specified by the - `VAULT_AZUREKEYVAULT_KEY_NAME` environment variable. + `AZUREKEYVAULT_WRAPPER_KEY_NAME` environment variable. ## Authentication diff --git a/website/content/docs/configuration/kms/gcpckms.mdx b/website/content/docs/configuration/kms/gcpckms.mdx index 53792ae3a..1b3c7b6e7 100644 --- a/website/content/docs/configuration/kms/gcpckms.mdx +++ b/website/content/docs/configuration/kms/gcpckms.mdx @@ -19,6 +19,7 @@ configuration file by providing all the required values: ```hcl kms "gcpckms" { + purpose = "root" credentials = "/usr/boundary/boundary-project-user-creds.json" project = "boundary-project" region = "global" @@ -31,6 +32,8 @@ kms "gcpckms" { These parameters apply to the `kms` stanza in the Boundary configuration file: +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, `recovery`, or `config`. + - `credentials` `(string: )`: The path to the credentials JSON file to use. May be also specified by the `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if diff --git a/website/content/docs/configuration/kms/ocikms.mdx b/website/content/docs/configuration/kms/ocikms.mdx index eb937cc2c..b5d03061f 100644 --- a/website/content/docs/configuration/kms/ocikms.mdx +++ b/website/content/docs/configuration/kms/ocikms.mdx @@ -19,10 +19,11 @@ by providing all the required values: ```hcl kms "ocikms" { - key_id = "ocid1.key.oc1.iad.afnxza26aag4s.abzwkljsbapzb2nrha5nt3s7s7p42ctcrcj72vn3kq5qx" - crypto_endpoint = "https://afnxza26aag4s-crypto.kms.us-ashburn-1.oraclecloud.com" - management_endpoint = "https://afnxza26aag4s-management.kms.us-ashburn-1.oraclecloud.com" - auth_type_api_key = "true" + purpose = "root" + key_id = "ocid1.key.oc1.iad.afnxza26aag4s.abzwkljsbapzb2nrha5nt3s7s7p42ctcrcj72vn3kq5qx" + crypto_endpoint = "https://afnxza26aag4s-crypto.kms.us-ashburn-1.oraclecloud.com" + management_endpoint = "https://afnxza26aag4s-management.kms.us-ashburn-1.oraclecloud.com" + auth_type_api_key = "true" } ``` @@ -30,6 +31,7 @@ kms "ocikms" { These parameters apply to the `kms` stanza in the Boundary configuration file: +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, `recovery`, or `config`. - `key_id` `(string: )`: The OCI KMS key ID to use. - `crypto_endpoint` `(string: )`: The OCI KMS cryptographic endpoint (or data plane endpoint) to be used to make OCI KMS encryption/decryption requests. @@ -47,9 +49,10 @@ If you want to use Instance Principal, add section configuration below and add f ```hcl kms "ocikms" { - crypto_endpoint = "" - management_endpoint = "" - key_id = "" + purpose = "root" + crypto_endpoint = "" + management_endpoint = "" + key_id = "" } ``` @@ -57,10 +60,11 @@ If you want to use User Principal, the plugin will take the API key you defined ```hcl kms "ocikms" { - auth_type_api_key = true - crypto_endpoint = "" - management_endpoint = "" - key_id = "" + purpose = "root" + auth_type_api_key = true + crypto_endpoint = "" + management_endpoint = "" + key_id = "" } ``` @@ -87,12 +91,10 @@ admit dynamic-group of tenancy tenantA to use keys in compa ``` -## `ocikms` Rotate OCI KMS Master Key +## `ocikms` Rotate OCI KMS Key For the [OCI KMS key rotation feature][oci-kms-rotation], OCI KMS will create a new version of key internally. This process is independent from Boundary, and boundary still uses the same `key_id` without any interruption. -If you want to change the `key_id`: migrate to Shamir, change `key_id`, and then migrate to OCI KMS with the new `key_id`. - [oci-sdk]: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm [oci-dg]: https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managingdynamicgroups.htm [oci-id]: https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policies.htm diff --git a/website/content/docs/configuration/kms/transit.mdx b/website/content/docs/configuration/kms/transit.mdx index a28b34b4e..a55f8ef12 100644 --- a/website/content/docs/configuration/kms/transit.mdx +++ b/website/content/docs/configuration/kms/transit.mdx @@ -19,6 +19,7 @@ by providing all the required values: ```hcl kms "transit" { + purpose = "root" address = "https://vault:8200" token = "s.Qf1s5zigZ4OX6akYjQXJC1jY" disable_renewal = "false" @@ -41,6 +42,9 @@ kms "transit" { These parameters apply to the `kms` stanza in the Vault configuration file: +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, +`recovery`, or `config`. + - `address` `(string: )`: The full address to the Vault cluster. This may also be specified by the `VAULT_ADDR` environment variable. @@ -48,11 +52,11 @@ These parameters apply to the `kms` stanza in the Vault configuration file: specified by the `VAULT_TOKEN` environment variable. - `key_name` `(string: )`: The transit key to use for encryption and - decryption. This may also be supplied using the `VAULT_TRANSIT_SEAL_KEY_NAME` + decryption. This may also be supplied using the `TRANSIT_WRAPPER_KEY_NAME` environment variable. - `mount_path` `(string: )`: The mount path to the transit secret engine. - This may also be supplied using the `VAULT_TRANSIT_SEAL_MOUNT_PATH` environment + This may also be supplied using the `TRANSIT_WRAPPER_MOUNT_PATH` environment variable. - `namespace` `(string: "")`: The namespace path to the transit secret engine. @@ -61,7 +65,7 @@ These parameters apply to the `kms` stanza in the Vault configuration file: - `disable_renewal` `(string: "false")`: Disables the automatic renewal of the token in case the lifecycle of the token is managed with some other mechanism outside of Vault, such as Vault Agent. This may also be specified using the - `VAULT_TRANSIT_SEAL_DISABLE_RENEWAL` environment variable. + `TRANSIT_WRAPPER_DISABLE_RENEWAL` environment variable. - `tls_ca_cert` `(string: "")`: Specifies the path to the CA certificate file used for communication with the Vault server. This may also be specified using the diff --git a/website/content/docs/configuration/listener/tcp.mdx b/website/content/docs/configuration/listener/tcp.mdx index 56ab836ba..8b3f7dcba 100644 --- a/website/content/docs/configuration/listener/tcp.mdx +++ b/website/content/docs/configuration/listener/tcp.mdx @@ -13,27 +13,23 @@ The TCP listener configures Boundary to listen on a TCP address/port. ```hcl listener "tcp" { + purpose = "api" address = "127.0.0.1:9200" } ``` The `listener` stanza may be specified more than once to make Boundary listen on -multiple interfaces. If you configure multiple listeners you also need to -specify [`api_addr`][api-addr] and [`cluster_addr`][cluster-addr] so Boundary will -advertise the correct address to other nodes. +multiple interfaces; however, only one listener marked for `cluster` purpose is +allowed. ## `tcp` Listener Parameters +- `purpose` `(string: "")` - Specifies the purpose. Can be `api`, `cluster`, or +`proxy`. + - `address` `(string: "127.0.0.1:9200")` – Specifies the address to bind to for listening. -- `cluster_address` `(string: "127.0.0.1:9201")` – Specifies the address to bind - to for cluster server-to-server requests. This defaults to one port higher - than the value of `address`. This does not usually need to be set, but can be - useful in case Boundary servers are isolated from each other in such a way that - they need to hop through a TCP load balancer or some other scheme in order to - talk. - - `http_idle_timeout` `(string: "5m")` - Specifies the maximum amount of time to wait for the next request when keep-alives are enabled. If `http_idle_timeout` is zero, the value of `http_read_timeout` is used. If both are zero, the value @@ -53,9 +49,11 @@ advertise the correct address to other nodes. is read. The default value of `"0"` means inifinity. This is specified using a label suffix like `"30s"` or `"1h"`. + - `max_request_duration` `(string: "90s")` – Specifies the maximum request duration allowed before Boundary cancels the request. This overrides @@ -100,6 +98,7 @@ advertise the correct address to other nodes. - `tls_client_ca_file` `(string: "")` – PEM-encoded Certificate Authority file used for checking the authenticity of client. + ## `tcp` Listener Examples @@ -132,6 +132,7 @@ This example shows enabling a TLS listener. ```hcl listener "tcp" { + purpose = "api" tls_cert_file = "/etc/certs/Boundary.crt" tls_key_file = "/etc/certs/Boundary.key" } @@ -143,16 +144,14 @@ This example shows Boundary listening on a private interface, as well as localho ```hcl listener "tcp" { + purpose = "api" address = "127.0.0.1:9200" } listener "tcp" { + purpose = "cluster" address = "10.0.0.5:9200" } - -# Advertise the non-loopback interface -api_addr = "https://10.0.0.5:9200" -cluster_addr = "https://10.0.0.5:9201" ``` [golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go diff --git a/website/content/docs/configuration/telemetry.mdx b/website/content/docs/configuration/telemetry.mdx deleted file mode 100644 index 7aa8cecf7..000000000 --- a/website/content/docs/configuration/telemetry.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: docs -page_title: Telemetry - Configuration -sidebar_title: telemetry -description: |- - The telemetry stanza specifies various configurations for Boundary to publish - metrics to upstream systems. ---- - -# `telemetry` Stanza - -NOT YET IMPLEMENTED diff --git a/website/content/docs/configuration/worker.mdx b/website/content/docs/configuration/worker.mdx index 7ba5c07a6..7eaf57230 100644 --- a/website/content/docs/configuration/worker.mdx +++ b/website/content/docs/configuration/worker.mdx @@ -3,7 +3,7 @@ layout: docs page_title: Worker - Configuration sidebar_title: worker description: |- - The worker stanza configures worker-specifc parameters. + The worker stanza configures worker-specific parameters. --- # `worker` Stanza @@ -18,17 +18,23 @@ worker { } ``` -- `name` - Specifies a unique name of this worker within the Boundary worker cluster. +- `name` - Specifies a unique name of this worker within the Boundary worker +cluster. - `description` - Specifies a friendly description of this worker. -- `public_addr` - Specifies the public IP address for the worker to be reached on. This is useful for cloud environments that do not bind a publicly accessible IP to a NIC on the host directly, such as an Amazon EIP. +- `public_addr` - Specifies the public host or IP address (and optionally port) +at which the worker can be reached _by clients for proxying_. This defaults to +the address of the listener marked for `proxy` 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. -- `controllers` - A list of IP addresses for reaching controllers on port :9202. +- `controllers` - A list of hosts/IP addresses and optionally ports for reaching +controllers. The port will default to :9201 if not specified. -- KMS block designated for `worker-auth` - This is the KMS configuration for authentication between the workers and controllers and must be present. Example: -```hcl -kms "aead" { +- KMS block designated for `worker-auth` - This is the KMS configuration for +authentication between the workers and controllers and must be present. Example (not safe for production!): +```hcl kms "aead" { purpose = "worker-auth" aead_type = "aes-gcm" key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" @@ -45,16 +51,18 @@ listener "tcp" { } worker { - # Name attr must be unique across workers if running in HA mode - name = "demo-worker-1" - description = "A default worker created demonstration" + # Name attr must be unique across workers + name = "demo-worker-1" + description = "A default worker created demonstration" # Workers must be able to reach controllers on :9202 - controllers = [ + controllers = [ "10.0.0.1", "10.0.0.2", "10.0.0.3", ] + + public_addr = "myhost.mycompany.com" } # must be same key as used on controller config diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index e4cb393c8..0d2ec4f7a 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -77,7 +77,6 @@ export default [ }, 'controller', 'worker', - 'telemetry', ], }, {