diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 55bc3ded28..99f8b9c5ac 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -36,7 +36,35 @@ export default [ }, { category: 'installing', - content: ['dev-mode'], + content: ['dev-mode', 'production'], + }, + { + category: 'configuration', + content: [ + { + category: 'listener', + content: ['tcp'], + }, + { + category: 'kms', + content: [ + 'aead', + 'awskms', + 'alicloudkms', + 'azurekeyvault', + 'gcpckms', + 'ocikms', + 'transit', + ], + }, + { + category: 'controller', + }, + { + category: 'worker', + }, + 'telemetry', + ], }, { category: 'admin-console', diff --git a/website/pages/docs/configuration/controller/index.mdx b/website/pages/docs/configuration/controller/index.mdx new file mode 100644 index 0000000000..47a97b55f3 --- /dev/null +++ b/website/pages/docs/configuration/controller/index.mdx @@ -0,0 +1,22 @@ +--- +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" +} +``` + +- `name` - Specifies a unique name of this controller within the Boundary controller cluster. + +- `description` - Specifies a friendly description of this controller. diff --git a/website/pages/docs/configuration/index.mdx b/website/pages/docs/configuration/index.mdx new file mode 100644 index 0000000000..3755fd81ab --- /dev/null +++ b/website/pages/docs/configuration/index.mdx @@ -0,0 +1,71 @@ +--- +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` ([Controller][controller]: \) - Controller specific configuration. Only required when running a `boundary controller`. + +- `worker` ([Worker][worker]: \) - Worker specific configuration. Only required when running a `boundary worker`. + +- `listener` ([Listener][listener]: \) – 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` ([KMS][kms]: \) – 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` ([Telemetry][telemetry]: <none>) – 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". diff --git a/website/pages/docs/configuration/kms/aead.mdx b/website/pages/docs/configuration/kms/aead.mdx new file mode 100644 index 0000000000..d760e270e1 --- /dev/null +++ b/website/pages/docs/configuration/kms/aead.mdx @@ -0,0 +1,24 @@ +--- +layout: docs +page_title: KMS AEAD - Configuration +sidebar_title: KMS AEAD +description: |- + The KMS AEAD configures KMS-specifc parameters. +--- + +```hcl +kms "aead" { + purpose = "worker-auth" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "global_worker-auth" +} +``` + +- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `root`, and `recovery`. + +- `aead_type` - The type of encryption this KMS uses. + +- `key` - Optional, a hard coded key if not using an external KMS. + +- `key_id` - The unique name of this key. diff --git a/website/pages/docs/configuration/kms/alicloudkms.mdx b/website/pages/docs/configuration/kms/alicloudkms.mdx new file mode 100644 index 0000000000..4490815d62 --- /dev/null +++ b/website/pages/docs/configuration/kms/alicloudkms.mdx @@ -0,0 +1,72 @@ +--- +layout: docs +page_title: AliCloud KMS - KMSs - Configuration +sidebar_title: AliCloud KMS +description: >- + The AliCloud KMS configures Boundary to use AliCloud KMS for key management. +--- + +# `alicloudkms` KMS + +The AliCloud KMS configures Boundary to use AliCloud KMS for key management. +The AliCloud KMS is activated by one of the following: + +- The presence of a `kms "alicloudkms"` block in Boundary's configuration file. + +## `alicloudkms` Example + +This example shows configuring AliCloud KMS through the Boundary configuration file +by providing all the required values: + +```hcl +kms "alicloudkms" { + region = "us-east-1" + access_key = "0wNEpMMlzy7szvai" + secret_key = "PupkTg8jdmau1cXxYacgE736PJj4cA" + kms_key_id = "08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4fb73" +} +``` + +## `alicloudkms` Parameters + +These parameters apply to the `kms` stanza in the Boundary configuration file: + +- `region` `(string: "us-east-1")`: The AliCloud region where the encryption key + lives. May also be specified by the `ALICLOUD_REGION` + environment variable. + +- `domain` `(string: "kms.us-east-1.aliyuncs.com")`: If set, overrides the endpoint + AliCloud would normally use for KMS for a particular region. May also be specified + by the `ALICLOUD_DOMAIN` environment variable. + +- `access_key` `(string: )`: The AliCloud access key ID to use. May also be + specified by the `ALICLOUD_ACCESS_KEY` environment variable or as part of the + AliCloud profile from the AliCloud CLI or instance profile. + +- `secret_key` `(string: )`: The AliCloud secret access key to use. May + also be specified by the `ALICLOUD_SECRET_KEY` environment variable or as + 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` + environment variable. + +## Authentication + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +~> **Note:** Although the configuration file allows you to pass in +`ALICLOUD_ACCESS_KEY` and `ALICLOUD_SECRET_KEY` as part of the 's parameters, it +is _strongly_ recommended to set these values via environment variables. + +```text +AliCloud authentication values: + +* `ALICLOUD_REGION` +* `ALICLOUD_ACCESS_KEY` +* `ALICLOUD_SECRET_KEY` +``` + +Note: The client uses the official AliCloud SDK and will use environment credentials, +the specified credentials, or RAM role credentials in that order. diff --git a/website/pages/docs/configuration/kms/awskms.mdx b/website/pages/docs/configuration/kms/awskms.mdx new file mode 100644 index 0000000000..97dbc66cd7 --- /dev/null +++ b/website/pages/docs/configuration/kms/awskms.mdx @@ -0,0 +1,95 @@ +--- +layout: docs +page_title: AWS KMS - KMSs - Configuration +sidebar_title: AWS KMS +description: |- + The AWS KMS configures Boundary to use AWS KMS for key management. + mechanism. +--- + +# `awskms` + +The AWS KMS configures Boundary to use AWS KMS for key management. + +## `awskms` Example + +This example shows configuring AWS KMS through the Boundary configuration file +by providing all the required values: + +```hcl +kms "awskms" { + region = "us-east-1" + access_key = "AKIAIOSFODNN7EXAMPLE" + secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} +``` + +## `awskms` Parameters + +These parameters apply to the `kms` stanza in the Boundary configuration file: + +- `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, + or from instance metadata. + +- `access_key` `(string: )`: The AWS access key ID to use. May also be + specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the + AWS profile from the AWS CLI or instance profile. + +- `session_token` `(string: "")`: Specifies the AWS session token. This can + also be provided via the environment variable `AWS_SESSION_TOKEN`. + +- `secret_key` `(string: )`: The AWS secret access key to use. May + also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as + 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` + environment variable. + +- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS + requests. May also be specified by the `AWS_KMS_ENDPOINT` environment + variable. This is useful, for example, when connecting to KMS over a [VPC + Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html). + If not set, Boundary will use the default API endpoint for your region. + +## Authentication + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +~> **Note:** Although the configuration file allows you to pass in +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the KMS's parameters, it +is _strongly_ recommended to set these values via environment variables. + +AWS authentication values: + +- `AWS_REGION` or `AWS_DEFAULT_REGION` +- `AWS_ACCESS_KEY_ID` +- `AWS_SECRET_ACCESS_KEY` + +Note: The client uses the official AWS SDK and will use the specified +credentials, environment credentials, shared file credentials, or IAM role/ECS +task credentials in that order, if the above AWS specific values are not +provided. + +Boundary needs the following permissions on the KMS key: + +- `kms:Encrypt` +- `kms:Decrypt` +- `kms:DescribeKey` + +These can be granted via IAM permissions on the principal that Boundary uses, on +the KMS key policy for the KMS key, or via KMS Grants on the key. + +## Key Rotation + +This KMS supports rotating the master keys defined in AWS KMS +[doc](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). Both automatic +rotation and manual rotation is supported for KMS since the key information is stored with the +encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data. +Any new or updated data will be encrypted with the current key defined in the KMS configuration +or set to current under a key alias. diff --git a/website/pages/docs/configuration/kms/azurekeyvault.mdx b/website/pages/docs/configuration/kms/azurekeyvault.mdx new file mode 100644 index 0000000000..3c6515fe2c --- /dev/null +++ b/website/pages/docs/configuration/kms/azurekeyvault.mdx @@ -0,0 +1,63 @@ +--- +layout: docs +page_title: Azure Key Vault - Seals - Configuration +sidebar_title: Azure Key Vault +description: >- + The Azure Key Vault seal configures Boundary to use Azure Key Vault for key management. +--- + +# `azurekeyvault` KMS + +The Azure Key Vault KMS configures Vault to use Azure Key Vault for key management. +The Azure Key Vault KMS is activated by one of the following: + +- The presence of a `seal "azurekeyvault"` block in Boundary's configuration file. + +## `azurekeyvault` Example + +This example shows configuring Azure Key Vault KMS through the Boundary +configuration file by providing all the required values: + +```hcl +kms "azurekeyvault" { + tenant_id = "46646709-b63e-4747-be42-516edeaf1e14" + client_id = "03dc33fc-16d9-4b77-8152-3ec568f8af6e" + client_secret = "DUJDS3..." + vault_name = "hc-vault" + key_name = "vault_key" +} +``` + +## `azurekeyvault` Parameters + +These parameters apply to the `kms` stanza in the Vault configuration file: + +- `tenant_id` `(string: )`: The tenant id for the Azure Active Directory organization. May + also be specified by the `AZURE_TENANT_ID` environment variable. + +- `client_id` `(string: )`: The client id for credentials to query the Azure APIs. + May also be specified by the `AZURE_CLIENT_ID` environment variable. + +- `client_secret` `(string: )`: The client secret for credentials to query the Azure APIs. + May also be specified by the `AZURE_CLIENT_SECRET` environment variable. + +- `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API endpoints to use. May also + 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. + +- `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. + +## Authentication + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +Azure authentication values: + +- `AZURE_TENANT_ID` +- `AZURE_CLIENT_ID` +- `AZURE_CLIENT_SECRET` +- `AZURE_ENVIRONMENT` diff --git a/website/pages/docs/configuration/kms/gcpckms.mdx b/website/pages/docs/configuration/kms/gcpckms.mdx new file mode 100644 index 0000000000..53792ae3a4 --- /dev/null +++ b/website/pages/docs/configuration/kms/gcpckms.mdx @@ -0,0 +1,60 @@ +--- +layout: docs +page_title: GCP Cloud KMS - KMSs - Configuration +sidebar_title: GCP Cloud KMS +description: >- + The GCP Cloud KMS configures Boundary to use GCP Cloud KMS for key management. +--- + +# `gcpckms` KMS + +The GCP Cloud KMS configures Boundary to use GCP Cloud KMS for key management. + +The GCP Cloud KMS seal is activated by the presence of a `seal "gcpckms"` block in Boundary's configuration file. + +## `gcpckms` Example + +This example shows configuring GCP Cloud KMS through the Boundary +configuration file by providing all the required values: + +```hcl +kms "gcpckms" { + credentials = "/usr/boundary/boundary-project-user-creds.json" + project = "boundary-project" + region = "global" + key_ring = "boundary-keyring" + crypto_key = "boundary-key" +} +``` + +## `gcpckms` Parameters + +These parameters apply to the `kms` stanza in the Boundary configuration file: + +- `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 + running under Google App Engine, Google Compute Engine or Google Kubernetes + Engine. + +- `project` `(string: )`: The GCP project ID to use. May also be + specified by the `GOOGLE_PROJECT` environment variable. + +- `region` `(string: "us-east-1")`: The GCP region/location where the key ring + lives. May also be specified by the `GOOGLE_REGION` environment variable. + +- `key_ring` `(string: )`: The GCP CKMS key ring to use. + +- `crypto_key` `(string: )`: The GCP CKMS crypto key to use for + encryption and decryption. + +## Authentication & Permissions + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +GCP authentication values: + +- `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` +- `GOOGLE_PROJECT` +- `GOOGLE_REGION` diff --git a/website/pages/docs/configuration/kms/index.mdx b/website/pages/docs/configuration/kms/index.mdx new file mode 100644 index 0000000000..a6cb45d47d --- /dev/null +++ b/website/pages/docs/configuration/kms/index.mdx @@ -0,0 +1,32 @@ +--- +layout: docs +page_title: KMS - Configuration +sidebar_title: kms +description: |- + The KMS stanza configures KMS-specifc parameters. +--- + +# `kms` Stanza + +The `kms` stanza configures Boundary kms-specific parameters. + +For more examples, please choose a specific KMS technology from the sidebar. + +## Configuration + +KMS configuration can be done through the Vault configuration file using the +`kms` stanza: + +```hcl +kms [NAME] { + # ... +} +``` + +For example: + +```hcl +kms "pkcs11" { + # ... +} +``` diff --git a/website/pages/docs/configuration/kms/ocikms.mdx b/website/pages/docs/configuration/kms/ocikms.mdx new file mode 100644 index 0000000000..eb937cc2cc --- /dev/null +++ b/website/pages/docs/configuration/kms/ocikms.mdx @@ -0,0 +1,99 @@ +--- +layout: docs +page_title: OCI KMS - KMSs - Configuration +sidebar_title: OCI KMS +description: |- + The OCI KMS configures Boundary to use OCI KMS for key management. +--- + +# `ocikms` KMS + +The OCI KMS configures Boundary to use OCI KMS for key management. + +The OCI KMS is activated by the presence of a `kms "ocikms"` block in Boundary's configuration file. + +## `ocikms` Example + +This example shows configuring the OCI KMS through the Boundary configuration file +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" +} +``` + +## `ocikms` Parameters + +These parameters apply to the `kms` stanza in the Boundary configuration file: + +- `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. +- `management_endpoint` `(string: )`: The OCI KMS management endpoint (or control plane endpoint) + to be used to make OCI KMS key management requests. +- `auth_type_api_key` `(boolean: false)`: Specifies if using API key to authenticate to OCI KMS service. + If it is `false`, Boundary authenticates using the instance principal from the compute instance. See Authentication section for details. Default is `false`. + +## Authentication + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +If you want to use Instance Principal, add section configuration below and add further configuration settings as detailed in the [configuration docs](/docs/configuration/). + +```hcl +kms "ocikms" { + crypto_endpoint = "" + management_endpoint = "" + key_id = "" +} +``` + +If you want to use User Principal, the plugin will take the API key you defined for OCI SDK, often under `~/.oci/config`. + +```hcl +kms "ocikms" { + auth_type_api_key = true + crypto_endpoint = "" + management_endpoint = "" + key_id = "" +} +``` + +To grant permission for a compute instance to use OCI KMS service, write policies for KMS access. + +- Create a [Dynamic Group][oci-dg] in your OCI tenancy. +- Create a policy that allows the Dynamic Group to use or manage keys from OCI KMS. There are multiple ways to write these policies. The [OCI Identity Policy][oci-id] can be used as a reference or starting point. + +The most common policy allows a dynamic group of tenant A to use KMS's keys in tenant B: + +```text +define tenancy tenantB as + +endorse dynamic-group to use keys in tenancy tenantB + +``` + +```text +define tenancy tenantA as + +define dynamic-group as + +admit dynamic-group of tenancy tenantA to use keys in compartment + +``` + +## `ocikms` Rotate OCI KMS Master 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 +[oci-kms-rotation]: https://docs.cloud.oracle.com/iaas/Content/KeyManagement/Tasks/managingkeys.htm diff --git a/website/pages/docs/configuration/kms/transit.mdx b/website/pages/docs/configuration/kms/transit.mdx new file mode 100644 index 0000000000..a28b34b4e8 --- /dev/null +++ b/website/pages/docs/configuration/kms/transit.mdx @@ -0,0 +1,107 @@ +--- +layout: docs +page_title: Vault Transit - Seals - Configuration +sidebar_title: Vault Transit +description: |- + The Transit configures Boundary to use Vault's Transit Secret Engine for key management. +--- + +# `transit` Seal + +The Transit configures Boundary to use Vault's Transit Secret Engine for key management. + +The Transit KMS is activated by the presence of a `kms "transit"` block in Boundary's configuration file + +## `transit` Example + +This example shows configuring Transit KMS through the Boundary configuration file +by providing all the required values: + +```hcl +kms "transit" { + address = "https://vault:8200" + token = "s.Qf1s5zigZ4OX6akYjQXJC1jY" + disable_renewal = "false" + + // Key configuration + key_name = "transit_key_name" + mount_path = "transit/" + namespace = "ns1/" + + // TLS Configuration + tls_ca_cert = "/etc/vault/ca_cert.pem" + tls_client_cert = "/etc/vault/client_cert.pem" + tls_client_key = "/etc/vault/ca_cert.pem" + tls_server_name = "vault" + tls_skip_verify = "false" +} +``` + +## `transit` Parameters + +These parameters apply to the `kms` stanza in the Vault configuration file: + +- `address` `(string: )`: The full address to the Vault cluster. + This may also be specified by the `VAULT_ADDR` environment variable. + +- `token` `(string: )`: The Vault token to use. This may also be + 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` + 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 + variable. + +- `namespace` `(string: "")`: The namespace path to the transit secret engine. + This may also be supplied using the `VAULT_NAMESPACE` environment variable. + +- `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. + +- `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 + `VAULT_CA_CERT` environment variable. + +- `tls_client_cert` `(string: "")`: Specifies the path to the client certificate + for communication with the Vault server. This may also be specified using the + `VAULT_CLIENT_CERT` environment variable. + +- `tls_client_key` `(string: "")`: Specifies the path to the private key for + communication with the Vault server. This may also be specified using the + `VAULT_CLIENT_KEY` environment variable. + +- `tls_server_name` `(string: "")`: Name to use as the SNI host when connecting + to the Vault server via TLS. This may also be specified via the + `VAULT_TLS_SERVER_NAME` environment variable. + +- `tls_skip_verify` `(bool: "false")`: Disable verification of TLS certificates. + Using this option is highly discouraged and decreases the security of data + transmissions to and from the Vault server. This may also be specified using the + `VAULT_SKIP_VERIFY` environment variable. + +## Authentication + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +~> **Note:** Although the configuration file allows you to pass in +`VAULT_TOKEN` as part of the KMS's parameters, it is _strongly_ recommended +to set these values via environment variables. + +The Vault token used to authenticate needs the following permissions on the +transit key: + +```hcl +path "/encrypt/" { + capabilities = ["update"] +} + +path "/decrypt/" { + capabilities = ["update"] +} +``` diff --git a/website/pages/docs/configuration/listener/index.mdx b/website/pages/docs/configuration/listener/index.mdx new file mode 100644 index 0000000000..c482a8a428 --- /dev/null +++ b/website/pages/docs/configuration/listener/index.mdx @@ -0,0 +1,15 @@ +--- +layout: docs +page_title: Listeners - Configuration +sidebar_title: listener +description: |- + The listener stanza configures the addresses and ports on which Boundary will + respond to requests. +--- + +# `listener` Stanza + +The `listener` stanza configures the addresses and ports on which Boundary will +respond to requests. At this time, there is only one listener - [TCP][tcp]. + +[tcp]: /docs/configuration/listener/tcp diff --git a/website/pages/docs/configuration/listener/tcp.mdx b/website/pages/docs/configuration/listener/tcp.mdx new file mode 100644 index 0000000000..110f5d0d74 --- /dev/null +++ b/website/pages/docs/configuration/listener/tcp.mdx @@ -0,0 +1,181 @@ +--- +layout: docs +page_title: TCP - Listeners - Configuration +sidebar_title: TCP +description: |- + The TCP listener configures Boundary to listen on the specified TCP address and + port. +--- + +# `tcp` Listener + +The TCP listener configures Boundary to listen on a TCP address/port. + +```hcl +listener "tcp" { + 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. + +## `tcp` Listener Parameters + +- `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 + of `http_read_header_timeout` is used. This is specified using a label suffix + like `"30s"` or `"1h"`. + +- `http_read_header_timeout` `(string: "10s")` - Specifies the amount of time + allowed to read request headers. This is specified using a label suffix like + `"30s"` or `"1h"`. + +- `http_read_timeout` `(string: "30s")` - Specifies the maximum duration for + reading the entire request, including the body. This is specified using a + label suffix like `"30s"` or `"1h"`. + +- `http_write_timeout` `string: "0")` - Specifies the maximum duration before + timing out writes of the response and is reset whenever a new request's header + is read. The default value of `"0"` means inifinity. This is specified using a + label suffix like `"30s"` or `"1h"`. + +- `max_request_size` `(int: 33554432)` – Specifies a hard maximum allowed + request size, in bytes. Defaults to 32 MB. Specifying a number less than or + equal to `0` turns off limiting altogether. + +- `max_request_duration` `(string: "90s")` – Specifies the maximum + request duration allowed before Boundary cancels the request. This overrides + `default_max_request_duration` for this listener. + +- `proxy_protocol_behavior` `(string: "")` – When specified, enables a PROXY + protocol version 1 behavior for the listener. + Accepted Values: + + - _use_always_ - The client's IP address will always be used. + - _allow_authorized_ - If the source IP address is in the + `proxy_protocol_authorized_addrs` list, the client's IP address will be used. + If the source IP is not in the list, the source IP address will be used. + - _deny_unauthorized_ - The traffic will be rejected if the source IP + address is not in the `proxy_protocol_authorized_addrs` list. + +- `proxy_protocol_authorized_addrs` `(string: or array: )` – + Specifies the list of allowed source IP addresses to be used with the PROXY protocol. + Not required if `proxy_protocol_behavior` is set to `use_always`. Source IPs should + be comma-delimited if provided as a string. At least one source IP must be provided, + `proxy_protocol_authorized_addrs` cannot be an empty array or string. + +- `tls_disable` `(string: "false")` – Specifies if TLS will be disabled. Boundary + assumes TLS by default, so you must explicitly disable TLS to opt-in to + insecure communication. + +- `tls_cert_file` `(string: , reloads-on-SIGHUP)` – + Specifies the path to the certificate for TLS. To configure the listener to + use a CA certificate, concatenate the primary certificate and the CA + certificate together. The primary certificate should appear first in the + combined file. On `SIGHUP`, the path set here _at Boundary startup_ will be used + for reloading the certificate; modifying this value while Boundary is running + will have no effect for `SIGHUP`s. + +- `tls_key_file` `(string: , reloads-on-SIGHUP)` – + Specifies the path to the private key for the certificate. If the key file + is encrypted, you will be prompted to enter the passphrase on server startup. + The passphrase must stay the same between key files when reloading your + configuration using `SIGHUP`. On `SIGHUP`, the path set here _at Boundary + startup_ will be used for reloading the certificate; modifying this value + while Boundary is running will have no effect for `SIGHUP`s. + +- `tls_min_version` `(string: "tls12")` – Specifies the minimum supported + version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13". + + ~> **Warning**: TLS 1.1 and lower are generally considered insecure. + +- `tls_cipher_suites` `(string: "")` – Specifies the list of supported + ciphersuites as a comma-separated-list. The list of all available ciphersuites + is available in the [Golang TLS documentation][golang-tls]. + +- `tls_prefer_server_cipher_suites` `(string: "false")` – Specifies to prefer the + server's ciphersuite over the client ciphersuites. + +- `tls_require_and_verify_client_cert` `(string: "false")` – Turns on client + authentication for this listener; the listener will require a presented + client cert that successfully validates against system CAs. + +- `tls_client_ca_file` `(string: "")` – PEM-encoded Certificate Authority file + used for checking the authenticity of client. + +- `tls_disable_client_certs` `(string: "false")` – Turns off client + authentication for this listener. The default behavior (when this is false) + is for Boundary to request client certificates when available. + +- `x_forwarded_for_authorized_addrs` `(string: )` – + Specifies the list of source IP CIDRs for which an X-Forwarded-For header + will be trusted. Comma-separated list or JSON array. This turns on + X-Forwarded-For support. + +- `x_forwarded_for_hop_skips` `(string: "0")` – The number of addresses that will be + skipped from the _rear_ of the set of hops. For instance, for a header value + of `1.2.3.4, 2.3.4.5, 3.4.5.6`, if this value is set to `"1"`, the address that + will be used as the originating client IP is `2.3.4.5`. + +- `x_forwarded_for_reject_not_authorized` `(string: "true")` – If set false, + if there is an X-Forwarded-For header in a connection from an unauthorized + address, the header will be ignored and the client connection used as-is, + rather than the client connection rejected. + +- `x_forwarded_for_reject_not_present` `(string: "true")` – If set false, if + there is no X-Forwarded-For header or it is empty, the client address will be + used as-is, rather than the client connection rejected. + +### `telemetry` Parameters + +- `unauthenticated_metrics_access` `(string: "false")` - If set to true, allows + unauthenticated access to the `/v1/sys/metrics` endpoint. + +## `tcp` Listener Examples + +### Configuring TLS + +This example shows enabling a TLS listener. + +```hcl +listener "tcp" { + tls_cert_file = "/etc/certs/Boundary.crt" + tls_key_file = "/etc/certs/Boundary.key" +} +``` + +### Listening on Multiple Interfaces + +This example shows Boundary listening on a private interface, as well as localhost. + +```hcl +listener "tcp" { + address = "127.0.0.1:9200" +} + +listener "tcp" { + 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 +[api-addr]: /docs/configuration#api_addr +[cluster-addr]: /docs/configuration#cluster_addr diff --git a/website/pages/docs/configuration/telemetry.mdx b/website/pages/docs/configuration/telemetry.mdx new file mode 100644 index 0000000000..a7b56fa135 --- /dev/null +++ b/website/pages/docs/configuration/telemetry.mdx @@ -0,0 +1,12 @@ +--- +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/pages/docs/configuration/worker/index.mdx b/website/pages/docs/configuration/worker/index.mdx new file mode 100644 index 0000000000..27b69a77ec --- /dev/null +++ b/website/pages/docs/configuration/worker/index.mdx @@ -0,0 +1,25 @@ +--- +layout: docs +page_title: Worker - Configuration +sidebar_title: worker +description: |- + The worker stanza configures worker-specifc parameters. +--- + +# `worker` Stanza + +The `worker` stanza configures Boundary worker-specific parameters. + +```hcl +worker { + name = "example-worker" + description = "An example worker" + public_addr = "5.1.23.198" +} +``` + +- `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 environemnts that do not bind a publically accessible IP to a NIC on the host directly, such as an Amazon EIP. diff --git a/website/pages/docs/installing/production.mdx b/website/pages/docs/installing/production.mdx new file mode 100644 index 0000000000..92c6756cc7 --- /dev/null +++ b/website/pages/docs/installing/production.mdx @@ -0,0 +1,246 @@ +--- +layout: docs +page_title: Production Installation +sidebar_title: Production Install +description: |- + How to install Boundary in a production environment +--- + +# Production Installation + +Installing Boundary in a production setting requires prerequisits for infrastructure. At the most basic level, Boundary operators should run a minimum of 3 controllers and 3 workers. Running 3 of each server type gives a fundamental level of high availability for the control plane (controller), as well as bandwith for number of sessions on the data plane (worker). Both server type should be ran in a fault tolerant setting, that is, in a self-healing environmnet such as an auto-scaling group. The documentation here does not cover self-healing infrastructure and assumes the operator has their preferred scheduling methods for these environments. + +## Network Requirements + +- Client -> Controller port is :9200 +- Controller -> Worker port is :9201 +- Client must have access to Controller on :9200 +- :9201 must be open between Worker and Controller +- Workers must have a route and port access to the targets which they service + +## Architecture + +The general architecture for the server infrastructure requires 3 controllers and 3 workers. The documentation here uses virtual machines running on Amazon EC2 as the example environment, but this use +case can be extrapolated to almost any cloud platform to suit operator needs: + +![](/img/production.png) + +As shown above, Boundary is broken up into its controller and worker server components across 3 [EC2 instances](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance), in +3 separate [subnets](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/subnet), in three separate [availability zones](), with the controller API and UI being publically exposed by an [application load balancer (ALB)](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb). The worker and controller VM's are in independant [auto-scaling groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group), allowing them to maintain their exact capacity. + +Boundary requires an external [Postgres](https://www.postgresql.org/) and [KMS](https://aws.amazon.com/kms/). In the example above, we're using AWS managed services for these components. For Postgres, we're using [RDS](https://aws.amazon.com/rds/) and for KMS we're using Amazon's [Key Management Service](https://aws.amazon.com/kms/). + +## Architecture Breakdown + +### API and Console Load Balancer + +Load balancing the controller allows operators to secure the ingress to the Boundary system. We recommend placing all Boundary server's in private networks and using load balancing tecniques to expose services such as the API and administrative console to public networks. In the production architecture, we recommend load balancing using a layer 7 load balancer and further constraining ingress to that load balancer with layer 4 constraints such as [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) or [IP tables](https://wiki.archlinux.org/index.php/Iptables). + +For general configuration, we recommend the following: + +- HTTPS listener with valid TLS certificate for the domain it's serving or TLS passthrough +- Health check port should use :9200 with TCP protocol + +### Controller Configuration + +When running Boundary controller as a service we recommend storing the file at `/etc/boundary-controller.hcl`. A `boundary` user and group should exist to manage this configuration file and to further restrict who can read and modify it. + +Example 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, can be overridden with PG_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" +} +``` + +name must be unique! + +### Installation + +`TYPE` below can be either `worker` or `controller`. + +1. `/etc/boundary-${TYPE}.hcl`: Configuration file for the boundary service + See above example configurations. + +2. `/usr/local/bin/boundary`: The Boundary binary + Can build from https://github.com/hashicorp/boundary or download binary from our release pages. + +3. `/etc/systemd/system/boundary-${TYPE}.service`: Systemd unit file for the Boundary service + Example: + +``` +[Unit] +Description=${NAME} ${TYPE} + +[Service] +ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl +User=boundary +Group=boundary +LimitMEMLOCK=infinity +Capabilities=CAP_IPC_LOCK+ep +CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK + +[Install] +WantedBy=multi-user.target +``` + +Here's a simple install script that creates the boundary group and user, installs the +systemd unit file and enables it at startup: + +``` +#!/bin/bash +# Installs the boundary as a service for systemd on linux +# Usage: ./install.sh + +TYPE=$1 +NAME=boundary + +sudo cat << EOF > /etc/systemd/system/${NAME}-${TYPE}.service +[Unit] +Description=${NAME} ${TYPE} + +[Service] +ExecStart=/usr/local/bin/${NAME} ${TYPE} -config /etc/${NAME}-${TYPE}.hcl +User=boundary +Group=boundary +LimitMEMLOCK=infinity +Capabilities=CAP_IPC_LOCK+ep +CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK + +[Install] +WantedBy=multi-user.target +EOF + +# Add the boundary system user and group to ensure we have a no-login +# user capable of owning and running Boundary +sudo adduser --system --group boundary || true +sudo chown boundary:boundary /etc/${NAME}-${TYPE}.hcl +sudo chown boundary:boundary /usr/local/bin/boundary + +# Make sure to initialize the DB before starting the service. This will result in +# a database already initizalized warning if another controller or worker has done this +# already, making it a lazy, best effort initialization +if [ "${TYPE}" = "controller" ]; then + sudo /usr/local/bin/boundary database init -config /etc/${NAME}-${TYPE}.hcl || true +fi + +sudo chmod 664 /etc/systemd/system/${NAME}-${TYPE}.service +sudo systemctl daemon-reload +sudo systemctl enable ${NAME}-${TYPE} +sudo systemctl start ${NAME}-${TYPE} +``` + +### Postgres Configuration + +TBD + +### KMS Configuration + +TBD diff --git a/website/public/img/production.png b/website/public/img/production.png new file mode 100644 index 0000000000..27de1b7410 Binary files /dev/null and b/website/public/img/production.png differ