diff --git a/modules/run-vault/README.md b/modules/run-vault/README.md index b2f1e1e0..bd581f66 100644 --- a/modules/run-vault/README.md +++ b/modules/run-vault/README.md @@ -50,40 +50,49 @@ See the [root example](https://github.com/hashicorp/terraform-aws-vault/tree/mas - ## Command line Arguments The `run-vault` script accepts the following arguments: -* `--tls-cert-file` (required): 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. See [How do you handle encryption?](#how-do-you_handle-encryption) for more info. -* `--tls-key-file` (required): Specifies the path to the private key for the certificate. See [How do you handle - encryption?](#how-do-you_handle-encryption) for more info. -* `--port` (optional): The port Vault should listen on. Default is `8200`. -* `--log-level` (optional): The log verbosity to use with Vault. Default is `info`. -* `--systemd-stdout` (optional): The StandardOutput option of the systemd unit. If not specified, it will use systemd's default (journal). -* `--systemd-stderr` (optional): The StandardError option of the systemd unit. If not specified, it will use systemd's default (inherit). -* `--cluster-port` (optional): The port Vault should listen on for server-to-server communication. Default is - `--port + 1`. -* `--api-addr`: The full address to use for [Client Redirection](https://www.vaultproject.io/docs/concepts/ha.html#client-redirection) when running Vault in HA mode. Defaults to "https://[instance_ip]:8200". Optional. -* `config-dir` (optional): The path to the Vault config folder. Default is to take the absolute path of `../config`, - relative to the `run-vault` script itself. -* `user` (optional): The user to run Vault as. Default is to use the owner of `config-dir`. -* `skip-vault-config` (optional): If this flag is set, don't generate a Vault configuration file. This is useful if you - have a custom configuration file and don't want to use any of of the default settings from `run-vault`. -* `--enable-s3-backend` (optional): If this flag is set, an S3 backend will be enabled in addition to the HA Consul backend. -* `--s3-bucket` (optional): Specifies the S3 bucket to use to store Vault data. Only used if `--enable-s3-backend` is set. -* `--s3-bucket-path` (optional): Specifies the S3 bucket path to use to store Vault data. Default is `""`. Only used if `--enable-s3-backend` is set. -* `--s3-bucket-region` (optional): Specifies the AWS region where `--s3-bucket` lives. Only used if `--enable-s3-backend` is set. - -Optional Arguments for enabling the AWS KMS seal (Vault Enterprise only): - * `--enable-auto-unseal`: If this flag is set, enable the AWS KMS Auto-unseal feature. Default is false. - * `--auto-unseal-kms-key-id`: The key id of the AWS KMS key to be used for encryption and decryption. Required if `--enable-auto-unseal` is enabled. - * `--auto-unseal-kms-key-region`: The AWS region where the encryption key lives. Required if --enable-auto-unseal is enabled. - * `--auto-unseal-endpoint`: The KMS API endpoint to be used to make AWS KMS requests. Optional. Defaults to `""`. Only used if --enable-auto-unseal is enabled. - -Example: +### Options for Vault Server + +* `--tls-cert-file` (required) Specifies the path to the certificate for TLS. Required. To use a CA certificate, concatenate the primary certificate and the CA certificate together. See [How do you handle encryption?](#how-do-you_handle-encryption) for more info. +* `--tls-key-file` (required) Specifies the path to the private key for the certificate. Required. See [How do you handle encryption?](#how-do-you_handle-encryption) for more info. +* `--port` The port for Vault to listen on. Optional. Default is `8200`. +* `--cluster-port` The port for Vault to listen on for server-to-server requests. Optional. Default is `--port + 1`. +* `--api-addr` The full address to use for [Client Redirection](https://www.vaultproject.io/docs/concepts/ha.html#client-redirection) when running Vault in HA mode. Defaults to "https://[instance_ip]:8200". Optional. +* `--config-dir` The path to the Vault config folder. Optional. Default is the absolute path of `../config`, relative to this script. +* `--bin-dir` The path to the folder with Vault binary. Optional. Default is the absolute path of the parent folder of this script. +* `--log-level` The log verbosity to use with Vault. Optional. Default is `info`. +* `--systemd-stdout` The StandardOutput option of the systemd unit. Optional. If not configured, uses systemd's default (journal). +* `--systemd-stderr` The StandardError option of the systemd unit. Optional. If not configured, uses systemd's default (inherit). +* `--user` The user to run Vault as. Optional. Default is to use the owner of `--config-dir`. +* `--skip-vault-config` If this flag is set, don't generate a Vault configuration file. Optional. Default is false. This is useful if you have a custom configuration file and don't want to use any of of the default settings from `run-vault`. +* `--enable-s3-backend` If this flag is set, an S3 backend will be enabled in addition to the HA Consul backend. Default is false. +* `--s3-bucket` Specifies the S3 bucket to use to store Vault data. Only used if `--enable-s3-backend` is set. +* `--s3-bucket-path` Specifies the S3 bucket path to use to store Vault data. Only used if `--enable-s3-backend` is set. +* `--s3-bucket-region` Specifies the AWS region where `--s3-bucket` lives. Only used if `--enable-s3-backend` is set. + +### Options for Vault Agent (`--agent`) + +* `--agent` If set, run in Vault Agent mode. If not set, run as a regular Vault server. Optional. +* `--agent-vault-address` The hostname or IP address of the Vault server to connect to. Optional. Default is `vault.service.consul` +* `--agent-vault-port` The port of the Vault server to connect to. Optional. Default is `8200` +* `--agent-ca-cert-file` Specifies the path to a CA certificate to verify the Vault server's TLS certificate. Optional. +* `--agent-client-cert-file` Specifies the path to a certificate to use for TLS authentication to the Vault server. Optional. +* `--agent-client-key-file` Specifies the path to the private key for the client certificate used for TLS authentication to the Vault server. Optional. +* `--agent-auth-mount-path` The Vault mount path to the auth method used for auto-auth. Optional. Defaults to `auth/aws` +* `--agent-auth-type` The Vault AWS auth type to use for auto-auth. Required with `--agent`. Must be either `iam` or `ec2` +* `--agent-auth-role` The Vault role to authenticate against. Required with `--agent` + +### Options for enabling [AWS KMS auto-unseal](https://learn.hashicorp.com/vault/operations/ops-autounseal-aws-kms) (Vault Enterprise or 1.0 and above) + +* `--enable-auto-unseal` If this flag is set, enable the AWS KMS Auto-unseal feature. Default is false. +* `--auto-unseal-kms-key-id` The key id of the AWS KMS key to be used for encryption and decryption. Required if `--enable-auto-unseal` is enabled. +* `--auto-unseal-kms-key-region` The AWS region where the encryption key lives. Required if `--enable-auto-unseal` is enabled. +* `--auto-unseal-endpoint` The KMS API endpoint to be used to make AWS KMS requests. Optional. Defaults to `""`. Only used if `--enable-auto-unseal` is enabled. + +### Examples ``` /opt/vault/bin/run-vault --tls-cert-file /opt/vault/tls/vault.crt.pem --tls-key-file /opt/vault/tls/vault.key.pem diff --git a/modules/run-vault/run-vault b/modules/run-vault/run-vault index 211ad972..f92188f1 100755 --- a/modules/run-vault/run-vault +++ b/modules/run-vault/run-vault @@ -25,7 +25,7 @@ function print_usage { echo echo "This script is used to configure and run Vault on an AWS server." echo - echo "Options:" + echo "Options for Vault Server:" echo echo -e " --tls-cert-file\tSpecifies the path to the certificate for TLS. Required. To use a CA certificate, concatenate the primary certificate and the CA certificate together." echo -e " --tls-key-file\tSpecifies the path to the private key for the certificate. Required." @@ -45,9 +45,9 @@ function print_usage { echo -e " --s3-bucket-region\tSpecifies the AWS region where '--s3-bucket' lives. Only used if '--enable-s3-backend' is set." echo -e " --enable-dynamo-backend\tIf this flag is set, DynamoDB will be enabled as the backend storage (HA)" echo -e " --dynamo-region\tSpecifies the AWS region where --dynamo-table lives. Only used if '--enable-dynamo-backend is on'" - echo -e " --dynamo--table\tSpecifies the DynamoDB table to use for HA Storage. Only used if '--enable-dynamo-backend is on'" + echo -e " --dynamo-table\tSpecifies the DynamoDB table to use for HA Storage. Only used if '--enable-dynamo-backend is on'" echo - echo "Options for Vault Agent:" + echo "Options for Vault Agent (--agent):" echo echo -e " --agent\t\t\tIf set, run in Vault Agent mode. If not set, run as a regular Vault server. Optional." echo -e " --agent-vault-address\t\tThe hostname or IP address of the Vault server to connect to. Optional. Default is $DEFAULT_AGENT_VAULT_ADDRESS" @@ -56,8 +56,8 @@ function print_usage { echo -e " --agent-client-cert-file\tSpecifies the path to a certificate to use for TLS authentication to the Vault server. Optional." echo -e " --agent-client-key-file\tSpecifies the path to the private key for the client certificate used for TLS authentication to the Vault server. Optional." echo -e " --agent-auth-mount-path\tThe Vault mount path to the auth method used for auto-auth. Optional. Defaults to $DEFAULT_AGENT_AUTH_MOUNT_PATH" - echo -e " --agent-auth-type\t\tThe Vault AWS auth type to use for auto-auth. Required. Must be either iam or ec2" - echo -e " --agent-auth-role\t\tThe Vault role to authenticate against. Required." + echo -e " --agent-auth-type\t\tThe Vault AWS auth type to use for auto-auth. Required with --agent. Must be either iam or ec2" + echo -e " --agent-auth-role\t\tThe Vault role to authenticate against. Required with --agent." echo echo "Optional Arguments for enabling the AWS KMS seal (Vault Enterprise or 1.0 and above):" echo @@ -564,7 +564,8 @@ function run { agent_vault_port="$2" shift ;; - --agent-ca-cert_file) + --agent-ca-cert_file | --agent-ca-cert-file) + # Both versions of this flag are supported for backward compatibility (see https://github.com/hashicorp/terraform-aws-vault/issues/191 ) assert_not_empty "$key" "$2" agent_ca_cert_file="$2" shift