diff --git a/website/content/docs/api-clients/cli.mdx b/website/content/docs/api-clients/cli.mdx deleted file mode 100644 index b2e89cc02..000000000 --- a/website/content/docs/api-clients/cli.mdx +++ /dev/null @@ -1,253 +0,0 @@ ---- -layout: docs -page_title: CLI -description: |- - Boundary's CLI behavior ---- - -# CLI - -Boundary's CLI has predictable behavior throughout its various commands. This -page details the common patterns used in order to help users make better use -of the CLI. - -## CLI command structure - -There are a number of command and subcommand options available. -To see all available command options, run `boundary -h` -and to see all available subcommand options run `boundary -h`. - -Below is the typical structure for most Boundary CLI commands: - -```text -boundary [options] [args] -``` - -- `options` - [Client](/boundary/docs/api-clients/cli#client-options) and [connection](/boundary/docs/api-clients/cli#connection-options) options to specify additional settings -- `args` - API arguments specific to the operation - -### Examples - -The following shows use of the [`-addr`](/boundary/docs/api-clients/cli#addr) flag to specify which Boundary controller to send the request to. - -```shell-session -$ boundary authenticate password \ - -addr=https://boundary.example.com:9200 \ - -auth-method-id=ampw_1234567890 -``` - -Instead of specifying the `-addr` flag for every command, you can set an environment variable `BOUNDARY_ADDR=https://boundary.controller.com:9200`. - -## Completion - -Before detailing how parameters work, it's useful to note that Boundary's CLI -supports autocompletion, which allows tab completion of commands, flags, and in -some cases the parameters to those flags. - -This can be installed via the CLI itself: - -`boundary config autocomplete install` - -If you want to install it manually, for Bash, the following line in a -`~/.bash_profile` or similar file will work: - -`complete -C /path/to/boundary boundary` - -## Keyring token storage - -Boundary uses various mechanisms, depending on platform, to allow for secure -storage of authentication tokens for later use. Each platform has a -platform-specific option (which on Windows and macOS are the default); -[pass](https://www.passwordstore.org/) is also available on all platforms. On -all platforms, setting `-keyring-type` to `none` (or setting it via -`BOUNDARY_KEYRING_TYPE`) disables storage and retrieval of the token. - -Additionally, more than one token can be stored or retrieved at once via the -`-token-name` flag or `BOUNDARY_TOKEN_NAME` env var. This allows for storing -tokens used by different Boundary installations, or other needs. - -### Windows - -On Windows, the Windows credential store (`wincred`) is used. - -Available keyring types: - -- `wincred` (default) -- `pass` -- `none` - -### macOS - -On macOS, Keychain is used via `/usr/bin/security`. (Using this binary allows us -to keep the Boundary binary statically linked, which we prefer.) - -Available keyring types: - -- `keychain` (default) -- `pass` -- `none` - -### Other platforms - -On all other platforms, the default is `pass`. However, if an implementation of -the [freedesktop.org secret -service](https://specifications.freedesktop.org/secret-service/latest/) is -available (via `gnome-keyring`, `kwallet`, or others) it can be used. - -Available keyring types: - -- `pass` (default) -- `secret-service` -- `none` - -## Map to collections and sub-types - -Generally speaking, Boundary's CLI commands map to the collections they operate -on. For instance, when operating on roles, the command will be `boundary roles ...`. - -As a result, the patterns for reading, deleting, and listing are predictable: - -- `boundary read` -- `boundary delete` -- `boundary list` - -`read` and `delete` will always operate on a particular resource identifier, so -will always take in an `-id` parameter. `list` operates on collections so will -either take a `-scope-id` parameter or, depending on type, a higher level -resource identifier, e.g. `-auth-method-id`. - -Creating and updating resources may take an extra parameter if the resource type -is abstract, that is, if the type cannot be operated on directly but must be -operated on through an implementation. As an example, a role is not an abstract -type, and does not have various implementations of it. As a result, a role can -be operated on directly: - -- `boundary roles create` -- `boundary roles update`. - -However, a target can be one of many types of targets, and a concrete -implementation of a target is a `tcp` type of target. Therefore an extra -parameter is required when creating or updating a target: - -- `boundary targets create tcp` -- `boundary targets update tcp` - -This allows the CLI to perform proper presentation and validation of parameters -and functions for the given type. - -Similar to `read`, `update` operates on an existing target so will always take -an `-id` parameter. Similar to `list`, `create` operates on a collection so will -either take a `-scope-id` parameter or a parameter defining the parent resource. - -## Parameter handling - -All parameters specified on the CLI are specified as a Go-style flag with a -single dash, e.g. `-id`. The arguments to those flags can be specified via an -equals sign, as in `-id=r_1234567890`, or a space, like `-id r_1234567890`. - -To see available parameters, pass the `-h` flag to any command. - -Flags are semi-position dependent. The flags must come _after_ the command -definition, but are otherwise order independent. - -For instance, the following are equivalent: - -- `boundary roles create -scope-id global -name foo` -- `boundary roles create -name foo -scope-id global` - -But the following results in an error: - -- `boundary roles -name foo -scope-id global create` - -This applies to `-h` as well! - -### Clear/default values - -On the CLI, you can use `null` as a value to indicate to Boundary that you want -to unset a value, reverting to Boundary's default. In many cases this default -will be empty (e.g. for a `name` or `description` parameter) but in other cases -it's not. For instance, for a password auth method's minimum password length, -the default is not `0` but rather `8`. Additionally, attempting to set string -values to the empty string `""` is usually not an allowed operation, since when -set to a specific value it must be non-empty. Using `null` to clear a value -ensures you'll revert to Boundary's recommended default. - -~> **Note:** `null` is used because of the fact that the API is JSON. Using `null` as the -value causes the key for the parameter to be inserted into the eventual API -call's JSON object but with the value set to the JSON `null`. This in turn -informs the Controller that this value should be set to its default. Keep in -mind that this is not a direct translation to database `NULL` semantics! - -### Connection options - -Every command that results in an API call contains a set of flags that control -connection options, which control TLS and other settings for the connection. -You can also run `boundary dev -h` to see the available connection options. - -- `-addr=`: Address of the Boundary controller, as a complete URL (e.g. - https://boundary.example.com:9200). Instead of passing the `-addr` argument with every command, - the `BOUNDARY_ADDR` environment variable can be set. In both cases, the value denotes the address - of the Boundary environment (specifically the controller) you wish to send CLI commands to. - -- `-ca-cert=`: Path on the local disk to a single PEM-encoded CA certificate to - verify the Controller or Worker's server's SSL certificate. This - takes precedence over -ca-path. This can also be specified via the - `BOUNDARY_CACERT` environment variable. - -- `-ca-path=`: Path on the local disk to a directory of PEM-encoded CA certificates to - verify the SSL certificate of the Controller. This can also be specified - via the `BOUNDARY_CAPATH` environment variable. - -- `-client-cert=`: Path on the local disk to a single PEM-encoded CA certificate to use - for TLS authentication to the Boundary Controller. If this flag is - specified, -client-key is also required. This can also be specified via - the `BOUNDARY_CLIENT_CERT` environment variable. - -- `-client-key=`: Path on the local disk to a single PEM-encoded private key matching the - client certificate from -client-cert. This can also be specified via the - `BOUNDARY_CLIENT_KEY` environment variable. - -- `-tls-insecure`: Disable verification of TLS certificates. Using this option is highly - discouraged as it decreases the security of data transmissions to - and from the Boundary server. The default is false. This can also be - specified via the `BOUNDARY_TLS_INSECURE` environment variable. - -- `-tls-server-name=`: Name to use as the SNI host when connecting to the Boundary server - via TLS. This can also be specified via the `BOUNDARY_TLS_SERVER_NAME` - environment variable. - - -### Client options - -Every command that results in an API call contains a set of flags that control -client options. Some notable options: - -- `output-curl-string`: This will format the command that would have been run as - a string using `curl` that can be used directly on the command line. This is a - great way to discover how CLI functions map to API calls. - -- `token-name`: When the CLI authenticates, it stores the token in the - platform-specific OS credential store. By using the `token-name` parameter, more - than one token can be stored at a time. Specifying this parameter at - authentication time uses the given name as part of the key for storage; - specifying it for any other command will cause the corresponding token to be - used for that call. - -- `recovery-config`: This is used to specify a configuration file that contains - the information necessary to access a KMS configured to be used for the recovery - workflow within a Boundary controller. - -### Output options - -Nearly every command supports having its success output be formatted as JSON via -`-format json`. For commands that result in an API call, the JSON output will be -the exact output from the controller. If using the output of the CLI in scripts -or as parameters to other tools, _always_ use formatted output. The default text -output is meant for human users and the formatting or the information included -within that output from the original JSON may change at any time. - -Note that using `-format json` on a `boundary authenticate` command results in -Boundary not saving the token to the system password store. In this case, the -authentication information will only be printed to your terminal in JSON format. -You can use the `BOUNDARY_TOKEN` environment variable or `-token` flag to -provide the token in subsequent commands. diff --git a/website/content/docs/api-clients/index.mdx b/website/content/docs/api-clients/index.mdx index 6aff60d29..b5e9dd636 100644 --- a/website/content/docs/api-clients/index.mdx +++ b/website/content/docs/api-clients/index.mdx @@ -5,8 +5,8 @@ description: |- An introduction to Boundary's API and clients. --- -# Clients +# API and clients Boundary is a purely-API-driven system. This section contains information describing its API norms and the clients that HashiCorp provide (apart from the -web UI), which include a CLI, a Go SDK, and a Desktop client. +web UI), which include a Go SDK and a Desktop client. diff --git a/website/content/docs/commands/accounts/change-password.mdx b/website/content/docs/commands/accounts/change-password.mdx new file mode 100644 index 000000000..d96bc8389 --- /dev/null +++ b/website/content/docs/commands/accounts/change-password.mdx @@ -0,0 +1,82 @@ +--- +layout: docs +page_title: accounts change-password - Command +description: |- + The "accounts change-password" command lets Boundary admin change the password for an account. +--- + +# accounts change-password + +Command: `boundary accounts change-password` + +The `accounts change-password` command resets the password on account resources, if the types match and the operation is allowed by the given account type. +You must verify the current password to complete the password reset. + +## Examples + +The following example changes the password on a password-type account. If you execute the command without the `-current-password` and ` -new-password` parameters, you are +prompted to enter the password values. + +```shell-session +$ boundary accounts change-password -id acctpw_1234567890 +Please enter the current password (it will be hidden): +Please enter the new password (it will be hidden): +Please enter it one more time for confirmation: +``` + +**Example output:** + + + +```plaintext +Account information: + Auth Method ID: ampw_1234567890 + Created Time: Wed, 12 Jul 2023 12:20:54 PDT + ID: acctpw_1234567890 + Type: password + Updated Time: Wed, 12 Jul 2023 22:29:59 PDT + Version: 5 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: admin +``` + + + + +## Usage + + + +```shell-session +$ boundary accounts change-password [options] [args] +``` + + + + +### Command options + +- `-current-password` `(string: "")` - The current password for the account. If + you do not specify the current password, the command prompts you to enter the password in a non-echoing way. + +- `-id` `(string: "")` - The ID of the account for which to change the password. + +- `-new-password` `(string: "")` - The new account password. If you do not specify a new password, the command prompts you to enter the password in a non-echoing way. + +- `-version` `(int: 0)` The version of the account against which to perform the password reset operation. If you do not specify a version, the command automatically performs a check-and-set. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/accounts/create.mdx b/website/content/docs/commands/accounts/create.mdx new file mode 100644 index 000000000..1ed892491 --- /dev/null +++ b/website/content/docs/commands/accounts/create.mdx @@ -0,0 +1,190 @@ +--- +layout: docs +page_title: accounts create - Command +description: |- + The "accounts create" command lets Boundary admin create a new account resource. +--- + +# accounts create + +Command: `boundary accounts create` + +The `accounts create` command lets you create an account associated with one of the following auth methods: + +- LDAP +- OIDC +- Password + +## Example + +The following example creates an account named `test_account`. In this example, you provide a password when prompted: + +```shell-session +$ boundary accounts create password \ + -auth-method-id=ampw_1234567890 \ + -login-name="tester01" \ + -name=test_account \ + -description="Test password account" +``` + +**Example output:** + + + +```plaintext +Please enter the password (it will be hidden): + +Account information: + Auth Method ID: ampw_ZbB6UXpW3B + Created Time: Fri, 27 May 2022 11:16:47 MDT + Description: Test password account + ID: acctpw_A8R1escktO + Name: test_account + Type: password + Updated Time: Fri, 27 May 2022 11:16:47 MDT + Version: 1 + + Scope: + ID: o_u54jrD6ydN + Name: IT_Support + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: tester01 +``` + + + + +## Usage + + + +```shell-session +$ boundary accounts create [type] [options] [args] +``` + + + +### Command options + +- `-auth-method-id` `(string: "")` - The auth-method resource to use for the + operation. You can also specify the auth-method using the **BOUNDARY_AUTH_METHOD_ID** + environment variable. +- `-description` `(string: "")` - The description to set for the account. +- `-name` `(string: "")` - The name to set on the account. + + +### Usages by type + +You can create `ldap`, `oidc`, and `password` type accounts. + + + + +The `boundary accounts create ldap` command creates an account of `ldap` type. + +#### Example + +The example below creates an LDAP account with the login name `prodops` and the description `ldap account for ProdOps`: + +```shell-session +$ boundary accounts create ldap -login-name prodops \ + -description "ldap account for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary accounts create ldap [options] [args] +``` + + + +#### LDAP account option + +The following option is LDAP-specific, in addition to the command options: + +- `-login-name` `(string: "")` - The login name for the account. + + + + +The `boundary accounts create oidc` command creates an account of `oidc` type. + +#### Example + +The following example creates an OIDC account with the subject `prodops` and the description `Oidc account for ProdOps`: + +```shell-session +$ boundary accounts create oidc -subject "prodops" \ + -description "Oidc account for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary accounts create oidc [options] [args] +``` + + + +#### OIDC account options + +The following options are OIDC-specific, in addition to the command options: + +- `-issuer` `(string: "")` - The issuer for the account. +- `-subject` `(string: "")` - The subject for this account on the OIDC provider. + + + + +The `boundary accounts create password` command creates an account of `password` type. + +#### Example + +The following example creates a password-type account with the login name `prodops` and the description `Password account for ProdOps`: + +```shell-session +$ boundary accounts create password -login-name prodops \ + -description "Password account for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary accounts create password [options] [args] +``` + + + +#### Password account options + +The following options are password-specific, in addition to the command +options: + +- `-login-name` `(string: "")` - The login name for the account +- `-password` `(string: "")` - The password for the account. If blank, the + command prompts you to enter the password interactively in a + non-echoing way. Otherwise, this value can refer to a file on disk (`file://`) or an environment variable (`env://`) from which the password is read. + + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/accounts/delete.mdx b/website/content/docs/commands/accounts/delete.mdx new file mode 100644 index 000000000..ca7bc0cce --- /dev/null +++ b/website/content/docs/commands/accounts/delete.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: accounts delete - Command +description: |- + The "accounts delete" command lets Boundary admin delete an account resource. +--- + +# accounts delete + +Command: `boundary accounts delete` + +The `accounts delete` command lets you delete an existing account. + + +## Examples + +The following example deletes an account with the ID `acctpw_0987654321`. + +```shell-session +$ boundary accounts delete -id=acctpw_0987654321 +The delete operation completed successfully. +``` + +## Usage + + + +```shell-session +$ boundary accounts delete [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the account you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/accounts/index.mdx b/website/content/docs/commands/accounts/index.mdx new file mode 100644 index 000000000..50899223a --- /dev/null +++ b/website/content/docs/commands/accounts/index.mdx @@ -0,0 +1,87 @@ +--- +layout: docs +page_title: accounts - Command +description: |- + The "accounts" command lets Boundary admin create and manage account resources. +--- + +# accounts + +Command: `boundary accounts` + +The `accounts` command lets you create and manage accounts resources in Boundary. +You can associate Boundary users with one or more account resources using auth methods. +Accounts represent external notions of a particular entity. +Among other use cases, accounts provide an easy way to switch users to new IdPs within the organization that deploys Boundary. + +## Examples + +The following example retrieves account information for a given account ID, `acctpw_1234567890`: + +```shell-session +$ boundary accounts read -id acctpw_1234567890 +``` + +**Example output:** + + + +```plaintext +Account information: + Auth Method ID: ampw_1234567890 + Created Time: Wed, 12 Jul 2023 12:20:54 PDT + ID: acctpw_1234567890 + Type: password + Updated Time: Wed, 12 Jul 2023 12:20:54 PDT + Version: 1 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: admin +``` + + + +## Usage + + + +```shell-session +Usage: boundary accounts [sub command] [options] [args] + + # ... + +Subcommands: + change-password Change the password on an account + create Create an account + delete Delete an account + list List an account + read Read an account + set-password Directly set the password on an account + update Update an account +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/accounts/create) +- [delete](/boundary/docs/commands/accounts/delete) +- [read](/boundary/docs/commands/accounts/read) +- [update](/boundary/docs/commands/accounts/update) +- [list](/boundary/docs/commands/accounts/list) +- [set-password](/boundary/docs/commands/accounts/set-password) +- [change-password](/boundary/docs/commands/accounts/change-password) diff --git a/website/content/docs/commands/accounts/list.mdx b/website/content/docs/commands/accounts/list.mdx new file mode 100644 index 000000000..216e1812b --- /dev/null +++ b/website/content/docs/commands/accounts/list.mdx @@ -0,0 +1,71 @@ +--- +layout: docs +page_title: accounts list - Command +description: |- + The "accounts list" command lets Boundary admin list an account resource. +--- + +# accounts list + +Command: `boundary accounts list` + +The `accounts list` command lists all accounts created for a given auth method. + +## Example + +The following example lists all accounts for an auth method with ID, `ampw_1234567890`: + +```shell-session +$ boundary accounts list -auth-method-id ampw_1234567890 +``` + +**Example output:** + + + +```plaintext +Account information: + ID: acctpw_0987654321 + Version: 1 + Type: password + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + ID: acctpw_1234567890 + Version: 5 + Type: password + Authorized Actions: + no-op + read + update + delete + set-password + change-password +``` + + + +## Usage + + + +```shell-session +$ boundary accounts list [options] [args] +``` + + + +### Command options + +- `-auth-method-id` `(string: "")` - The auth-method resource from which to list accounts. You can also specify the auth-method resource using the **BOUNDARY_AUTH_METHOD_ID** + environment variable. +- `-filter` `(string: "")` - If set, the list operation is filtered before + being returned. The filter operates against each item in the list. We recommend using + single quotes, because filters contain double quotes. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/accounts/read.mdx b/website/content/docs/commands/accounts/read.mdx new file mode 100644 index 000000000..1703f5eb7 --- /dev/null +++ b/website/content/docs/commands/accounts/read.mdx @@ -0,0 +1,70 @@ +--- +layout: docs +page_title: accounts read - Command +description: |- + The "accounts read" command lets Boundary admin read an account resource. +--- + +# accounts read + +Command: `boundary accounts read` + +The `accounts read` command retrieves the account details for a given account ID. + + +## Examples + +The following example reads any account information with the ID `acctpw_1234567890`: + +```shell-session +$ boundary accounts read -id acctpw_1234567890 +``` + +**Example output:** + + + +```plaintext +Account information: + Auth Method ID: ampw_1234567890 + Created Time: Wed, 12 Jul 2023 12:20:54 PDT + ID: acctpw_1234567890 + Type: password + Updated Time: Wed, 12 Jul 2023 22:29:59 PDT + Version: 5 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: admin +``` + + + +## Usage + + + +```shell-session +$ boundary accounts read [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the account to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/accounts/set-password.mdx b/website/content/docs/commands/accounts/set-password.mdx new file mode 100644 index 000000000..861cc6f49 --- /dev/null +++ b/website/content/docs/commands/accounts/set-password.mdx @@ -0,0 +1,80 @@ +--- +layout: docs +page_title: accounts set-password - Command +description: |- + The "accounts set-password" command lets Boundary admin set the password for an account. +--- + +# accounts set-password + +Command: `boundary accounts set-password` + +The `accounts set-password` command lets you set the password on account-type +resources, if the types match and the operation is allowed by the given account +type. + +## Examples + +The following example sets the password on a password-type account. If you execute the command +without the `-password` parameter, you are prompted to enter the password +value. + +```shell-session +$ boundary accounts set-password -id acctpw_1234567890 +Please enter the password (it will be hidden): +Please enter it one more time for confirmation: +``` + +**Example output:** + + + +```plaintext +Account information: + Auth Method ID: ampw_1234567890 + Created Time: Wed, 12 Jul 2023 12:20:54 PDT + ID: acctpw_1234567890 + Type: password + Updated Time: Wed, 12 Jul 2023 22:08:12 PDT + Version: 2 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: admin +``` + + + +The output displays the account information. + +## Usage + + + +```shell-session +$ boundary accounts set-password [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the account on which to set a password. +- `-password` `(string: "")` - The password for the account. Use this value with `env://` or `file://` syntax. If you do not specify a password, the command prompts you to enter the password in a non-echoing way. +- `-version` `(int: 0)` - The version of the account against which to perform an + update operation. If you do no specify a version, the command performs a check-and-set + automatically. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/accounts/update.mdx b/website/content/docs/commands/accounts/update.mdx new file mode 100644 index 000000000..e68448575 --- /dev/null +++ b/website/content/docs/commands/accounts/update.mdx @@ -0,0 +1,188 @@ +--- +layout: docs +page_title: accounts update - Command +description: |- + The "accounts update" command lets Boundary admin update an account resource. +--- + +# accounts update + +Command: `boundary accounts update` + +The `accounts update` command updates an existing account's information for +the LDAP, OIDC, or password auth method. + +## Examples + +The following example updates an existing password-type account with the ID `acctpw_w3N3PlV34D`: + +```plaintext +ID: acctpw_w3N3PlV34D + Version: 1 + Type: password + Name: test_account + Description: Test password account + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: tester01 +``` + +This command updates the name, login name, and description: + +```shell-session +$ boundary accounts update password -id=acctpw_w3N3PlV34D \ + -name="tester" \ + -login-name="test-engineer" \ + -description="Only to be used for testing" +``` + +**Example output:** + + + +```plaintext +Account information: + Auth Method ID: ampw_1234567890 + Created Time: Thu, 13 Jul 2023 22:30:53 PDT + Description: Only to be used for testing + ID: acctpw_w3N3PlV34D + Name: tester + Type: password + Updated Time: Thu, 13 Jul 2023 22:40:48 PDT + Version: 3 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + set-password + change-password + + Attributes: + Login Name: test-engineer +``` + + + +## Usage + + + +```shell-session +$ boundary accounts update [type] [options] [args] +``` + + + +### Command options + +- `-description` `(string: "")` - The description to set on the account. +- `-id` `(string: "")` - The ID of the account to update. +- `-name` `(string: "")` - The name to set on the account. +- `-version` `(string: "")` - The version of the account against which to + perform an update operation. If you do not specify a version, the command performs a + check-and-set automatically. + +### Usages by type + +The available types are: `ldap`, `oidc`, and `password`. + + + + +The `boundary accounts update ldap` command updates an LDAP account. + +#### Example + +The following example updates an LDAP account with the ID `acctldap_1234567890` to add the name `devops` and the description `ldap account for DevOps`: + +```shell-session +$ boundary accounts update ldap -id acctldap_1234567890 \ + -name "devops" \ + -description "ldap account for DevOps" +``` +#### Usage + + + +```shell-session +$ boundary accounts update ldap [options] [args] +``` + + + + + + +The `boundary accounts update oidc` command updates an OIDC account. + +#### Example + +The folloiwng example updates an OIDC account with the ID `acctoidc_1234567890` to add the name `devops` and the description `Oidc account for DevOps`: + +```shell-session +$ boundary accounts update oidc -id acctoidc_1234567890 \ + -name "devops" \ + -description "Oidc account for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary accounts update oidc [options] [args] +``` + + + + + + + +The `boundary accounts update password` command updates a Password type account. + +#### Example + +The following example updates a password account with the ID `acctpw_1234567890` to add the name `devops` and the description `Password account for DevOps`: + +```shell-session +$ boundary accounts update password -id acctpw_1234567890 \ + -name "devops" \ + -description "Password account for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary accounts update password [options] [args] +``` + + + +#### Password account option + +The following option is specific to password accounts, in addition to the command +options: + +- `-login-name` `(string: "")` - The login name for the account. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-methods/change-state.mdx b/website/content/docs/commands/auth-methods/change-state.mdx new file mode 100644 index 000000000..72386eed6 --- /dev/null +++ b/website/content/docs/commands/auth-methods/change-state.mdx @@ -0,0 +1,133 @@ +--- +layout: docs +page_title: auth-methods change-state - Command +description: |- + The "auth-methods change-state" command lets Boundary admin change the state of an auth method. +--- + +# auth-methods change-state + +Command: `boundary auth-methods change-state` + +The `auth-methods change-state` command changes the active and visibility state +of an OIDC-type auth method given its ID. + +An OIDC auth method can be in one of several different states: Inactive, Active +Private, and Active Public. The current state of an OIDC auth method +affects how endpoints respond to requests and, sometimes, whether access to +an endpoint requires authentication. + +- **MakeInactive** transitions an OIDC auth method from either the **Active Private** + or the **Active Public** state into the **Inactive** state. +- **MakePrivate** transitions an OIDC auth method from either the **Inactive** or the + **Active Public** state into the **Active Private** state. If the transition is from the + **Inactive** state, it will only succeed if the configuration is + valid. +- **MakePublic** transitions an OIDC auth method from either the **Inactive** or the + **Active Private** state into the **Active Public** state. If the transition is from the + **Inactive** state, it will only succeed if the configuration is + valid. + +Before you change the state of an auth-method, Boundary retrieves the provider’s discovery document for the auth method’s issuer and attempts to +validate the auth-method’s configuration against this published information. If +Boundary is unable to validate the configuration, an error is returned and the +state change is not successful. + +## Examples + +The following example changes the OIDC auth method's state to `active-public`: + +```shell-session +$ boundary auth-methods change-state oidc -id amoidc_oHt4HQFCrN \ + -state active-public +``` + +**Example output:** + + + +```plaintext +Auth Method information: + Created Time: Fri, 09 Sep 2022 11:11:55 MDT + ID: amoidc_oHt4HQFCrN + Name: auth0 + Type: oidc + Updated Time: Fri, 09 Sep 2022 11:41:33 MDT + Version: 3 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + change-state + authenticate + + Authorized Actions on Auth Method's Collections: + accounts: + create + list + managed-groups: + create + list + + Attributes: + api_url_prefix: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud + callback_url: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback + client_id: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx + client_secret_hmac: Qc3i8NdnTP6rl4JANIg-a2GXgRW5rEKTp2ReIK_BOng + issuer: https://dev-1vdl8c0q.us.auth0.com/ + max_age: 0 + signing_algorithms: [RS256] + state: active-public +``` + + + +## Usage + + + +```shell-session +$ boundary auth-methods change-state oidc [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the oidc-type auth method on which to operate. + +### OIDC auth method options + +- `-disable-discovered-config-validation` - Disables validating + the given auth method against configuration from the authorization server's + discovery URL. You must specify this value every time an auth method that cannot be validated + is updated or state changed. Not specifying a value is equivalent to setting the value to + `false`. The default is `false`. + +- `-state` `(string: "")` - The desired operational state of the auth method. + Three different states exist for an authentication method: + + - `inactive` users can not authenticate with inactive auth methods and the + inactive auth methods are not listed for unauthenticated users. + - `active-private` users can authenticate with active-private auth methods + and active-private auth methods are not listed for unauthenticated users. + - `active-public` users can authenticate with active-public auth methods and + active-public auth methods are listed for unauthenticated users. + +If you change an auth method from `active-public` or `active-private` to `inactive`, all +in-flight authentications will succeed unless the auth method’s configuration is +modified while the request is in-flight. + +When you change an auth method's state using `boundary auth-methods change-state`, +Boundary uses the `-disable-discovered-config-validation` flag to disable validation +against the provider’s published discovery document. This allows for the very +rare occurrence when the Provider has published an invalid discovery document. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-methods/create.mdx b/website/content/docs/commands/auth-methods/create.mdx new file mode 100644 index 000000000..1061dd995 --- /dev/null +++ b/website/content/docs/commands/auth-methods/create.mdx @@ -0,0 +1,278 @@ +--- +layout: docs +page_title: auth-methods create - Command +description: |- + The "auth-methods create" command lets Boundary admin create an auth method. +--- + +# auth-methods create + +Command: `boundary auth-methods create` + +The `auth-methods create` command lets you create Boundary auth +method resources. The available auth method types are: LDAP, OIDC, and password. + +## Examples + +The following example creates an OIDC auth method by passing the OIDC provider's domain (`-issuer`), client ID, and client secret: + +```shell-session +$ boundary auth-methods create oidc \ + -issuer "https://dev-1sdl8c0z.us.auth0.com" \ + -client-id "zaxJLTZh3n14WqSQ7qQ9onuIVRDaZdzz;" \ + -client-secret "t35c9NNw1aZ8haEKFJbJF0lauMOSp5UNPovUJXo8Ea2sPZAR1DszEowX-6-lg-Xr" \ + -signing-algorithm RS256 \ + -api-url-prefix "http://localhost:9200" \ + -name "auth0" +``` + +**Example output:** + + + +```plaintext +Auth Method information: + Created Time: Thu, 06 May 2021 16:39:33 MDT + ID: amoidc_oHt4HQFCrN + Name: auth0 + Type: oidc + Updated Time: Thu, 06 May 2021 16:39:33 MDT + Version: 1 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + change-state + authenticate + + Authorized Actions on Auth Method's Collections: + accounts: + create + list + + Attributes: + api_url_prefix: http://localhost:9200 + callback_url: http://localhost:9200/v1/auth-methods/oidc:authenticate:callback + client_id: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx + client_secret_hmac: ayJRYSCphzxcHiKJvBrnDVtz1yiR958ejQuRGdQJMeM + issuer: https://dev-1vdl8c0q.us.auth0.com + signing_algorithms: [RS256] + state: inactive +``` + + + + +## Usage + + + +```shell-session +$ boundary auth-methods create [type] [sub command] [options] [args] +``` + + + +### Command options: + +- `-description` `(string: "")` - The description to set on the auth method. +- `-name` `(string: "")` - The name to set on the auth method. +- `-scope-id` `(string: "")` - The scope in which to make the request. The default + is `global`. You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' + +### Usages by type + +The available types are: `ldap`, `oidc`, and `password`. + + + + +The `boundary auth-methods create ldap` command creates an LDAP auth method. + +#### Example + +The following example creates an LDAP auth method with the name `prodops` and the description `LDAP auth-method for ProdOps`: + +```shell-session +$ boundary auth-methods create ldap -name prodops \ + -description "LDAP auth-method for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary auth-methods create ldap [options] [args] +``` + + + +#### LDAP auth method options + +The following are LDAP-specific options in addition to the command +options: + +- `-anon-group-search` - Uses anon bind when performing LDAP + group searches (optional). The default is `false`. + +- `-bind-dn` `(string: "")` - Uses the distinguished name of entry to bind when + performing user and group searches (optional). + +- `-bind-password` `(string: "")` - Indicates the password to use along with bind-dn + performing user and group searches (optional). + +- `-certificate` `(string: "")` - Specifies a PEM-encoded X.509 CA certificate in ASN.1 DER + form that can be used as a trust anchor when connecting to an LDAP + server(optional). You can specify this value multiple times. + +- `-client-certificate` `(string: "")` - Specifies a PEM-encoded X.509 client certificate in + ASN.1 DER form that can be used to authenticate against an LDAP server + (optional). + +- `-client-certificate-key` `(string: "")` - Specifies a PEM-encoded X.509 client + certificate key in PKCS #8, ASN.1 DER form used with the client certificate + (optional). + +- `-discover-dn` - Uses anon bind to discover the bind DN of a + user (optional). The default value is `false`. + +- `-enable-groups` - Finds the authenticated user's groups during + authentication (optional). The default is `false`. + +- `-group-attr` `(string: "")` - Indicates the attribute that enumerates a user's group + membership from entries returned by a group search (optional). + +- `-group-dn` `(string: "")` - Specifies the base DN under which to perform group search. + +- `-group-filter` `(string: "")` - Indicates a go template used to construct a LDAP group + search filter (optional). + +- `-insecure-tls` - Skips the LDAP server SSL certificate + validation (optional). Use this option with caution; it is insecure. The default value is `false`. + +- `-start-tls` - Issues the StartTLS command after connecting + (optional). The default value is `false`. + +- `-state` `(string: "")` - Indicates the desired operational state of the auth method. + +- `-upn-domain` `(string: "")` - Specifies the userPrincipalDomain used to construct the + UPN string for the authenticating user (optional). + +- `-urls` `(string: "")` - Indicates the LDAP URLs that specify LDAP servers to connect to + (required). You can specify this value multiple times. + +- `-use-token-groups` - Uses the Active Directory tokenGroups + constructed attribute of the user to find the group memberships (optional). + The default value is `false`. + +- `-user-attr` `(string: "")` - Specifies the attribute on user entry that matches the + username that is passed during authentication (optional). + +- `-user-dn` `(string: "")` - Indicates the base DN under which to perform user search +(optional). + +- `-user-filter` `(string: "")` - Specifies a go template used to construct a LDAP user +search filter (optional). + + + + +The `boundary auth-methods create oidc` command creates an OIDC auth method. + +#### Example + +The following example creates an OIDC auth method with the name `prodops` and the description `Oidc auth-method for ProdOps`: + +```shell-session +$ boundary auth-methods create oidc -name prodops \ + -description "Oidc auth-method for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary auth-methods create oidc [options] [args] +``` + + + +#### OIDC auth method options + +The following are OIDC-specific options in addition to the command options: + +- `-account-claim-maps` `(string: "")` - Specifies the optional account claim maps from + custom claims to the standard claims of sub, name and email. These maps are + represented as key=value where the key equals the Provider from-claim and the + value equals the Boundary to-claim. For example "oid=sub". You may specify this value + multiple times for different to-claims. + +- `-allowed-audience` `(string: "")` - Indicates the acceptable audience ("aud") claim. + You may specify this value multiple times. + +- `-api-url-prefix` `(string: "")` - Specifies the URL prefix used by the OIDC provider in + the authentication flow. + +- `-claims-scopes` `(tring: "")` - Indicates the optional claims scope requested. You may specify this value multiple times. + +- `-client-id` `(string: "")` - Specifies the OAuth 2.0 Client Identifier this auth method + should use with the provider. + +- `-client-secret` `(string: "")` - Indicates the corresponding client secret. + +- `-idp-ca-cert` `(string: "")` - Specifies an optional PEM-encoded X.509 CA certificate that + can be used as trust anchors when connecting to an OIDC provider. You may specify this value multiple times. + +- `-issuer` `(string: "")` - Indicates the provider's issuer URL. + +- `-max-age` `(string: "")` - Indicates the OIDC "max_age" parameter that is sent to the provider. + +- `-signing-algorithm` `(string: "")` - Indicates the allowed signing algorithm. You may specify this multiple times for multiple values. + + + + + + +The `boundary auth-methods create password` command creates a Password type auth method. + +#### Example + +The following example creates a Password type auth method with the name `prodops` and the description `Password auth-method for ProdOps`: + +```shell-session +$ boundary auth-methods create password -name prodops \ + -description "Password auth-method for ProdOps" +``` +#### Usage + + + +```shell-session +$ boundary accounts create password [options] [args] +``` + + + +#### Password auth method options + +The following are password auth method specific options in addition to the +command options: + +- `-min-login-name-length` `(string: "")` - The minimum length of login names. + +- `-min-password-length` `(string: "")` - The minimum length of passwords. + + + diff --git a/website/content/docs/commands/auth-methods/delete.mdx b/website/content/docs/commands/auth-methods/delete.mdx new file mode 100644 index 000000000..5a55bbbe5 --- /dev/null +++ b/website/content/docs/commands/auth-methods/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: auth-methods delete - Command +description: |- + The "auth-methods delete" command lets Boundary admin delete an auth method. +--- + +# auth-methods delete + +Command: `boundary auth-methods delete` + +The `auth-methods delete` command deletes an auth method given its ID. + +## Example + +The following example deletes an auth method with the ID, `moidc_oHt4HQFCrN`. + +```shell-session +$ boundary auth-methods delete -id amoidc_oHt4HQFCrN +``` + +## Usage + + + +```shell-session +$ boundary auth-methods delete [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the auth method to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-methods/index.mdx b/website/content/docs/commands/auth-methods/index.mdx new file mode 100644 index 000000000..e94918161 --- /dev/null +++ b/website/content/docs/commands/auth-methods/index.mdx @@ -0,0 +1,109 @@ +--- +layout: docs +page_title: auth-methods - Command +description: |- + The "auth-methods" command lets you create and manage Boundary authentication method configuration. +--- + +# auth-methods + +Command: `boundary auth-methods` + +The `auth-methods` command lets you manage the auth method resource in Boundary. The auth +method resource provides a mechanism for users to authenticate to +Boundary. An auth method contains accounts which link an individual user to a +set of credentials. They also contain managed groups which group accounts that satisfy +specific criteria, and can be used as principals in roles. + +## Examples + +The following example configures an OIDC auth method where the Boundary cluster +address is stored in the `BOUNDARY_ADDR`, the OIDC provider's client ID is +stored in the `CLIENT_ID`, and the client secret is stored in the +`CLIENT_SECRET` environment variables. + +```shell-session +$ boundary auth-methods create oidc \ + -issuer "https://dev-1sdl8c0z.us.auth0.com" \ + -client-id "$CLIENT_ID" \ + -client-secret "$CLIENT_SECRET" \ + -signing-algorithm RS256 \ + -api-url-prefix "$BOUNDARY_ADDR" \ + -name "auth0" +``` + +**Example output:** + + + +```plaintext +Auth Method information: + Created Time: Fri, 09 Sep 2022 11:11:55 MDT + ID: amoidc_40fr5jkLpk + Name: auth0 + Type: oidc + Updated Time: Fri, 09 Sep 2022 11:11:55 MDT + Version: 1 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + change-state + authenticate + + Authorized Actions on Auth Method's Collections: + accounts: + create + list + managed-groups: + create + list + + Attributes: + api_url_prefix: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud + callback_url: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback + client_id: zaxJLTZh3n14WqSQ7qQ9onuIVRDaZdzz + client_secret_hmac: Qc3i8NdnTP6rl4JANIg-a2GXgRW5rEKTp2ReIK_BOng + issuer: https://dev-1sdl8c0z.us.auth0.com + signing_algorithms: [RS256] + state: inactive +``` + + + +## Usage + + + +```shell-session +Usage: boundary auth-methods [sub command] [options] [args] + + # ... + +Subcommands: + change-state + create Create an auth method + delete Delete an auth method + list List an auth method + read Read an auth method + update Update an auth method +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [change-state](/boundary/docs/commands/auth-methods/change-state) +- [create](/boundary/docs/commands/auth-methods/create) +- [delete](/boundary/docs/commands/auth-methods/delete) +- [list](/boundary/docs/commands/auth-methods/list) +- [read](/boundary/docs/commands/auth-methods/read) +- [update](/boundary/docs/commands/auth-methods/update) diff --git a/website/content/docs/commands/auth-methods/list.mdx b/website/content/docs/commands/auth-methods/list.mdx new file mode 100644 index 000000000..7e21efd69 --- /dev/null +++ b/website/content/docs/commands/auth-methods/list.mdx @@ -0,0 +1,99 @@ +--- +layout: docs +page_title: auth-methods list - Command +description: |- + The "auth-methods list" command lets Boundary admin list available auth methods. +--- + +# auth-methods list + +Command: `boundary auth-methods list` + +The `auth-methods list` command lists auth methods within an enclosing scope or +resource. + + +## Examples + +The following example lists auth methods from the default `global` scope recursively from any child scopes, if applicable: + +```shell-session +$ boundary auth-methods list -recursive +``` + +**Example output:** + + + +```plaintext +Auth Method information: + ID: amoidc_1234567890 + Scope ID: global + Version: 1 + Type: oidc + Name: Generated global scope initial oidc auth method + Description: Provides initial administrative and unprivileged authentication into Boundary + Authorized Actions: + no-op + read + update + delete + change-state + authenticate + + ID: ampw_1234567890 + Scope ID: global + Version: 1 + Type: password + Name: Generated global scope initial password auth method + Description: Provides initial administrative and unprivileged authentication into Boundary + Is Primary For Scope: true + Authorized Actions: + no-op + read + update + delete + authenticate + + ID: ampw_ZbB6UXpW3B + Scope ID: o_u54jrD6ydN + Version: 1 + Type: password + Name: org_auth_method + Description: Org auth method + Authorized Actions: + no-op + read + update + delete + authenticate +``` + + + +## Usage + + + +```shell-session +$ boundary auth-methods list [options] [args] +``` + + + + +### Command options + +- `-filter` `(string: "")` - If set, the list operation is filtered before + being returned. The filter operates against each item in the list. We recommend using + single quotes, because filters contain double quotes. + +- `-recursive` - If set, the list operation is applied + recursively into child scopes, if supported by the type. The default value is + `false`. + +- `-scope-id` `(string: "")` - The scope in which to make the request. The default + scope is `global`. You can also specify a scope using the **BOUNDARY_SCOPE_ID** environment + variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-methods/read.mdx b/website/content/docs/commands/auth-methods/read.mdx new file mode 100644 index 000000000..188aca820 --- /dev/null +++ b/website/content/docs/commands/auth-methods/read.mdx @@ -0,0 +1,81 @@ +--- +layout: docs +page_title: auth-methods read - Command +description: |- + The "auth-methods read" command lets Boundary admin read an auth method. +--- + +# auth-methods read + +Command: `boundary auth-methods read` + +The `auth-methods read` command reads an auth method given its ID. + +## Examples + +The following example reads the auth method details for an auth method with the ID `amoidc_AliCbVihqv`. + +```shell-session +$ boundary auth-methods read -id amoidc_AliCbVihqv +``` + +**Example output:** + + + +```plaintext +Auth Method information: + Created Time: Thu, 13 May 2021 17:01:02 MDT + Description: OIDC auth method for Auth0 + ID: amoidc_AliCbVihqv + Name: Auth0 + Type: oidc + Updated Time: Thu, 13 May 2021 17:01:02 MDT + Version: 2 + + Scope: + ID: o_1234567890 + Name: Generated org scope + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + change-state + authenticate + + Authorized Actions on Auth Method's Collections: + accounts: + create + list + + Attributes: + api_url_prefix: http://localhost:9200 + callback_url: http://localhost:9200/v1/auth-methods/oidc:authenticate:callback + client_id: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx + client_secret_hmac: AhyxTBqlZpnny78iA9M7QHKAKocI17bjwvS70B1ccg0 + issuer: https://dev-1vdl8c0q.us.auth0.com/ + signing_algorithms: [RS256] + state: active-public +``` + + + +## Usage + + + +```shell-session +$ boundary auth-methods read [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the auth method to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-methods/update.mdx b/website/content/docs/commands/auth-methods/update.mdx new file mode 100644 index 000000000..4d7946c77 --- /dev/null +++ b/website/content/docs/commands/auth-methods/update.mdx @@ -0,0 +1,293 @@ +--- +layout: docs +page_title: auth-methods update - Command +description: |- + The "auth-methods update" command lets Boundary admin update an auth method. +--- + +# auth-methods update + +Command: `boundary auth-methods update` + +The `auth-methods update` command lets you update Boundary auth method resources. + +## Examples + +The following example updates an auth method to set the `-max-age` option to `0`. +This update forces the user to reauthenticate, if they are already logged in with the current browser session: + +```shell-session +$ boundary auth-methods update oidc -id amoidc_oHt4HQFCrN \ + -issuer "https://dev-1vdl8c0q.us.auth0.com/" \ + -max-age 0 +``` + +**Example output:** + + + +```plaintext +Auth Method information: + Created Time: Thu, 06 May 2021 16:39:33 MDT + ID: amoidc_oHt4HQFCrN + Name: auth0 + Type: oidc + Updated Time: Thu, 06 May 2021 16:58:21 MDT + Version: 2 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + update + delete + change-state + authenticate + + Authorized Actions on Auth Method's Collections: + accounts: + create + list + + Attributes: + api_url_prefix: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud + callback_url: https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud/v1/auth-methods/oidc:authenticate:callback + client_id: zbaJLTZh3n14WqSV7qQ9onuIVRDaZdzx + client_secret_hmac: ayJRYSCphzxcHiKJvBrnDVtz1yiR958ejQuRGdQJMeM + issuer: https://dev-1vdl8c0q.us.auth0.com/ + max_age: 0 + signing_algorithms: [RS256] + state: inactive +``` + + + + +## Usage + + + +```shell-session +$ boundary auth-methods update [type] [sub command] [options] [args] +``` + + + +### Command options: + +- `-description` `(string: "")` - The description to set on the auth method. +- `-id` `(string: "")` - The ID of the auth method to update. +- `-name` `(string: "")` - The name to set on the auth method. +- `-version` `(int: 0)` - The version of the auth method to update. + If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' + +### Usages by type + +The available types are: `ldap`, `oidc`, and `password`. + + + + +The `boundary auth-methods update ldap` command lets you update an LDAP auth method. + +#### Example + +The following example updates an LDAP auth method with the ID `amldap_1234567890` to add the name `devops` and the description `LDAP auth-method for DevOps`: + +```shell-session +$ boundary auth-methods update ldap -id amldap_1234567890 \ + -name "devops" \ + -description "LDAP auth-method for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary auth-methods update ldap [options] [args] +``` + + + +#### LDAP auth method options + +The following are LDAP-specific options in addition to the command +options. + +- `-anon-group-search` - Uses anon bind when performing LDAP + group searches (optional). The default value is `false`. + +- `-bind-dn` `(string: "")` - Uses the distinguished name of entry to bind when + performing user and group searches (optional). + +- `-bind-password` `(string: "")` - Indicates the password to use along with bind-dn + when performing user and group searches (optional). + +- `-certificate` `(string: "")` - Specifies a PEM-encoded X.509 CA certificate in ASN.1 DER + form that can be used as a trust anchor when connecting to an LDAP + server(optional). You can specify this value multiple times. + +- `-client-certificate` `(string: "")` - Specifies a PEM-encoded X.509 client certificate in + ASN.1 DER form that can be used to authenticate against an LDAP server + (optional). + +- `-client-certificate-key` `(string: "")` - Specifies a PEM-encoded X.509 client + certificate key in PKCS #8, ASN.1 DER form used with the client certificate + (optional). + +- `-discover-dn` - Uses anon bind to discover the bind DN of a + user (optional). The default value is `false`. + +- `-enable-groups` - Finds the authenticated user's groups during + authentication (optional). The default is `false`. + +- `-group-attr` `(string: "")` - Specifies the attribute that enumerates a user's group + membership from entries returned by a group search (optional). + +- `-group-dn` `(string: "")` - Specifies the base DN under which to perform group search. + +- `-group-filter` `(string: "")` - Indicates a go template used to construct a LDAP group + search filter (optional). + +- `-insecure-tls` - Skips the LDAP server SSL certificate + validation (optional). Use this option with caution, it is insecure. The default value is `false`. + +- `-start-tls` - Issues the StartTLS command after connecting + (optional). The default is `false`. + +- `-state` `(string: "")` - Indicates the desired operational state of the auth method. + +- `-upn-domain` `(string: "")` - Indicates the userPrincipalDomain used to construct the + UPN string for the authenticating user (optional). + +- `-urls` `(string: "")` - Indicates the LDAP URLs that specify LDAP servers to connect to + (required). You may specify this value multiple times. + +- `-use-token-groups` - Uses the Active Directory tokenGroups + constructed attribute of the user to find the group memberships (optional). + The default value is `false`. + +- `-user-attr` `(string: "")` - Indicates the attribute on user entry matching the + username that is passed during authentication (optional). + +- `-user-dn` `(string: "")` - Specifies the base DN under which to perform user search + (optional). + +- `-user-filter` `(string: "")` - Specifies a go template used to construct a LDAP user + search filter (optional). + + + + +The `boundary auth-methods update oidc` command lets you update OIDC auth methods. + +#### Example + +The following example updates an OIDC auth method with the ID `amoidc_1234567890` to add the name `devops` and the description `Oidc auth-method for DevOps`: + +```shell-session +$ boundary auth-methods update oidc -id amoidc_1234567890 \ + -name "devops" \ + -description "Oidc auth-method for DevOps" +``` +#### Usage + + + +```shell-session +$ boundary auth-methods update oidc [options] [args] +``` + + + +#### OIDC auth method options + +The following are options are specific to OIDC auth-methods in addition to the command options. + +- `-account-claim-maps` `(string: "")` - Indicates the optional account claim maps from + custom claims to the standard claims of sub, name and email. These maps are + represented as key=value where the key equals the Provider from-claim and the + value equals the Boundary to-claim. For example "oid=sub". You may specify this value + multiple times for different to-claims. + +- `-allowed-audience` `(string: "")` - Indicates the acceptable audience ("aud") claim. + You may specify this value multiple times. + +- `-api-url-prefix` `(string: "")` - Indicates the URL prefix used by the OIDC provider in + the authentication flow. + +- `-claims-scopes` `(tring: "")` - Specifies the optional claims scope requested. You may specify this value multiple times. + +- `-client-id` `(string: "")` - Indicates the OAuth 2.0 Client Identifier this auth method + should use with the provider. + +- `-client-secret` `(string: "")` - Indicates the corresponding client secret. + +- `-idp-ca-cert` `(string: "")` - Specifies an optional PEM-encoded X.509 CA certificate that + can be used as trust anchors when connecting to an OIDC provider. May be + specified multiple times. + +- `-disable-discovered-config-validation` - Disables validating + the given auth method against configuration from the authorization server's + discovery URL. This must be specified every time an unvalidatable auth method + is updated or state changed; not specifying it is equivalent to setting it to + false. The default is false. + +- `-dry-run` - Performs all completeness and validation checks + with any newly-provided values without persisting the changes. The default is + false. + +- `-idp-ca-cert` `(tring: "")` - Indicates an optional PEM-encoded X.509 CA certificate that + can be used as trust anchors when connecting to an OIDC provider. You may specify this value multiple times. + +- `-issuer` `(string: "")` - Indicates the provider's Issuer URL. + +- `-max-age` `(string: "")` - Indicates the OIDC "max_age" parameter sent to the provider. + +- `-signing-algorithm` `(string: "")` - Indicates the allowed signing algorithm. You may specify this value multiple times for multiple values. + + + + + + +The `boundary auth-methods update password` command lets you update a Password-type auth method. + +#### Example + +The following example updates a Password-type auth method with the ID `ampw_1234567890` to add the name `devops` and the description `Password auth-method for DevOps`: + +```shell-session +$ boundary auth-methods update password -id ampw_1234567890 \ + -name "devops" \ + -description "Password auth-method for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary auth-methods update password [options] [args] +``` + + + +### Password auth method options + +The following options are specific to the Passwor-type auth method in addition to the +command options. + +- `-min-login-name-length` `(string: "")` - The minimum length of login names. + +- `-min-password-length` `(string: "")` - The minimum length of passwords. + + + diff --git a/website/content/docs/commands/auth-tokens/delete.mdx b/website/content/docs/commands/auth-tokens/delete.mdx new file mode 100644 index 000000000..e6e747d18 --- /dev/null +++ b/website/content/docs/commands/auth-tokens/delete.mdx @@ -0,0 +1,38 @@ +--- +layout: docs +page_title: auth-tokens delete - Command +description: |- + The "auth-tokens delete" command allows Boundary admin to delete an auth token. +--- + +# auth-tokens delete + +Command: `boundary auth-tokens delete` + +The `auth-tokens delete` command deletes an auth token given its ID. + +## Example + +The following command deletes an auth token with the ID `at_LvUqeYz80B`: + +```shell-session +$ boundary auth-tokens delete -id at_LvUqeYz80B +The delete operation completed successfully. +``` + +## Usage + + + +```shell-session +$ boundary auth-tokens delete [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the auth token to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-tokens/index.mdx b/website/content/docs/commands/auth-tokens/index.mdx new file mode 100644 index 000000000..87686984a --- /dev/null +++ b/website/content/docs/commands/auth-tokens/index.mdx @@ -0,0 +1,75 @@ +--- +layout: docs +page_title: auth-tokens - Command +description: |- + The "auth-tokens" command allows operations on Boundary auth token resources. +--- + +# auth-tokens + +Command: `boundary auth-tokens` + +The `auth-tokens` command lets you manage auth token resources in Boundary. + +## Example + +The following example command lists existing auth tokens recursively: + +```shell-session +$ boundary auth-tokens list -recursive + +Auth Token information: + ID: at_LvUqeYz80B + Scope ID: global + Approximate Last Used Time: Sun, 13 Aug 2023 17:22:59 PDT + Auth Method ID: ampw_1234567890 + Created Time: Sun, 13 Aug 2023 17:22:59 PDT + Expiration Time: Sun, 20 Aug 2023 17:22:59 PDT + Updated Time: Sun, 13 Aug 2023 17:22:59 PDT + User ID: u_1234567890 + Authorized Actions: + no-op + read + read:self + delete + delete:self + + ID: at_TXmYwSqnnO + Scope ID: global + Approximate Last Used Time: Sun, 13 Aug 2023 17:23:16 PDT + Auth Method ID: ampw_1234567890 + Created Time: Sun, 13 Aug 2023 17:23:16 PDT + Expiration Time: Sun, 20 Aug 2023 17:23:16 PDT + Updated Time: Sun, 13 Aug 2023 17:23:16 PDT + User ID: u_1234567890 + Authorized Actions: + no-op + read + read:self + delete + delete:self +``` + +## Usage + + + +```shell-session +Usage: boundary auth-tokens [sub command] [options] [args] + + # ... + +Subcommands: + delete Delete an auth tokn + list List an auth token + read Read an auth token +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [delete](/boundary/docs/commands/auth-tokens/delete) +- [list](/boundary/docs/commands/auth-tokens/list) +- [read](/boundary/docs/commands/auth-tokens/read) diff --git a/website/content/docs/commands/auth-tokens/list.mdx b/website/content/docs/commands/auth-tokens/list.mdx new file mode 100644 index 000000000..16a84fe00 --- /dev/null +++ b/website/content/docs/commands/auth-tokens/list.mdx @@ -0,0 +1,87 @@ +--- +layout: docs +page_title: auth-tokens list - Command +description: |- + The "auth-tokens list" command allows Boundary admin to list available auth tokens. +--- + +# auth-tokens list + +Command: `boundary auth-tokens list` + +The `auth-tokens list` command lists all auth tokens within an enclosing scope or +resource. + + +## Examples + +The following command lists all auth tokens recursively from any child scopes, if applicable: + +```shell-session +$ boundary auth-tokens list +``` + +**Example output:** + + + +```plaintext +Auth Token information: + ID: at_TXmYwSqnnO + Approximate Last Used Time: Sun, 13 Aug 2023 18:03:51 PDT + Auth Method ID: ampw_1234567890 + Created Time: Sun, 13 Aug 2023 17:23:16 PDT + Expiration Time: Sun, 20 Aug 2023 17:23:16 PDT + Updated Time: Sun, 13 Aug 2023 18:03:51 PDT + User ID: u_1234567890 + Authorized Actions: + no-op + read + read:self + delete + delete:self + + ID: at_Gvd3jsqSO2 + Approximate Last Used Time: Sun, 13 Aug 2023 18:04:34 PDT + Auth Method ID: ampw_1234567890 + Created Time: Sun, 13 Aug 2023 18:04:34 PDT + Expiration Time: Sun, 20 Aug 2023 18:04:34 PDT + Updated Time: Sun, 13 Aug 2023 18:04:34 PDT + User ID: u_1234567890 + Authorized Actions: + no-op + read + read:self + delete + delete:self +``` + + + + +## Usage + + + +```shell-session +$ boundary auth-tokens list [options] [args] +``` + + + + +### Command options + +- `-filter` `(string: "")` - If set, the list operation is filtered before it is returned. +The filter operates against each item in the list. +We recommend that you use single quotes, as filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. + +- `-recursive` - If set, the list operation is applied recursively into child scopes, if the type supports it. +The default value is `false`. + +- `-scope-id` `(string: "")` - The scope from which to list the auth tokens. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-tokens/read.mdx b/website/content/docs/commands/auth-tokens/read.mdx new file mode 100644 index 000000000..1e26deeb3 --- /dev/null +++ b/website/content/docs/commands/auth-tokens/read.mdx @@ -0,0 +1,65 @@ +--- +layout: docs +page_title: auth-tokens read - Command +description: |- + The "auth-tokens read" command allows Boundary admin to read an auth token. +--- + +# auth-tokens read + +Command: `boundary auth-tokens read` + +The `auth-tokens read` command reads an auth token given its ID. + +## Examples + +The following example reads the auth token details for an auth token with the ID `at_Gvd3jsqSO2`: + +```shell-session +$ boundary auth-tokens read -id at_Gvd3jsqSO2 +``` + +**Example output:** + + + +```plaintext +Auth Token information: + Approximate Last Used Time: Sun, 13 Aug 2023 18:04:34 PDT + Auth Method ID: ampw_1234567890 + Created Time: Sun, 13 Aug 2023 18:04:34 PDT + Expiration Time: Sun, 20 Aug 2023 18:04:34 PDT + ID: at_Gvd3jsqSO2 + Updated Time: Sun, 13 Aug 2023 18:04:34 PDT + User ID: u_1234567890 + + Scope: + ID: global + Name: global + Type: global + + Authorized Actions: + no-op + read + read:self + delete + delete:self +``` + + + +## Usage + + + +```shell-session +$ boundary auth-tokens read [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the auth token to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/authenticate/index.mdx b/website/content/docs/commands/authenticate/index.mdx new file mode 100644 index 000000000..623298f16 --- /dev/null +++ b/website/content/docs/commands/authenticate/index.mdx @@ -0,0 +1,64 @@ +--- +layout: docs +page_title: authenticate - Command +description: |- + The "authenticate" command authenticates the Boundary command line client using a specified auth method. +--- + +# authenticate + +Command: `boundary authenticate` + +The `authenticate` command authenticates the Boundary command line client using the auth method that you specify. + + +## Examples + +The following example authenticates the Boundary CLI using a configured OIDC auth method where the auth method ID is `amoidc_q7jAdI1QgA`: + + +```shell-session +$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgA +``` + +**Example output:** + + + +```plaintext +Opening returned authentication URL in your browser... + +Authentication information: + Account ID: acctoidc_oztPFBFesH + Auth Method ID: amoidc_oHt4HQFCrN + Expiration Time: Thu, 13 May 2021 17:01:11 MDT + User ID: u_JCRQP3ID7l + +The token was successfully stored in the chosen keyring and is not displayed here. +``` + + + +## Usage + + + +```shell-session +Usage: boundary authenticate [sub command] [options] [args] + + # ... + +Subcommands: + ldap Invoke the ldap auth method to authenticate with Boundary + oidc Invoke the OIDC auth method to authenticate with Boundary + password Invoke the password auth method to authenticate with Boundary +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [ldap](/boundary/docs/commands/authenticate/ldap) +- [oidc](/boundary/docs/commands/authenticate/oidc) +- [password](/boundary/docs/commands/authenticate/password) diff --git a/website/content/docs/commands/authenticate/ldap.mdx b/website/content/docs/commands/authenticate/ldap.mdx new file mode 100644 index 000000000..8c7cbdbe7 --- /dev/null +++ b/website/content/docs/commands/authenticate/ldap.mdx @@ -0,0 +1,48 @@ +--- +layout: docs +page_title: authenticate ldap - Command +description: |- + The "authenticate ldap" command invokes the ldap auth method to authenticate the Boundary CLI. +--- + +# authenticate ldap + +Command: `boundary authenticate ldap` + +The `authenticate ldap` command lets you invokes the LDAP auth method to authenticate the +Boundary CLI. + +## Example + +The following example uses an LDAP auth method with the ID `amldap_1234567890` and the login name `foo` to authenticate the Boundary CLI: + +```shell-session +$ boundary authenticate ldap -auth-method-id amldap_1234567890 -login-name foo +``` + +## Usage + + + +```shell-session +$ boundary authenticate ldap [options] [args] +``` + + + +### Command options + +- `-auth-method-id` `(string: "")` - The auth-method resource you want to use for authentication. +You can also specify the auth method resource using the **BOUNDARY_AUTH_METHOD_ID** environment variable. + +- `-login-name` `(string: "")` - A login name that corresponds to an account within the given auth method. +You can also specify a login name using the **BOUNDARY_AUTHENTICATE_PASSWORD_LOGIN_NAME** environment variable. + +- `-password` `(string: "")` - The password that is associated with the login name. +If this value is blank, the command prompts you to enter the password interactively in a non-echoing way. +Otherwise, this value can refer to a file on disk (`file://`) from which a password is read or an environment variable (`env://`) from which the password is read. You can also specify the password using the **BOUNDARY_AUTHENTICATE_PASSWORD_PASSWORD** environment variable. + +- `-scope-id` `(string: "")` - The scope ID to use for the operation. +You can also specify the scope ID using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/authenticate/oidc.mdx b/website/content/docs/commands/authenticate/oidc.mdx new file mode 100644 index 000000000..6c2a8d067 --- /dev/null +++ b/website/content/docs/commands/authenticate/oidc.mdx @@ -0,0 +1,63 @@ +--- +layout: docs +page_title: authenticate oidc - Command +description: |- + The "authenticate oidc" command invokes the OIDC auth method to authenticate the Boundary CLI. +--- + +# authenticate oidc + +Command: `boundary authenticate oidc` + +The `authenticate oidc` command lets you invoke the OIDC auth method to authenticate the +Boundary CLI. + +The OIDC authentication method lets Boundary users delegate authentication +to an OIDC provider. OIDC authentication allows Boundary to integrate with widely +adopted identity providers like Okta, cloud-hosted active directory services +with an OIDC frontend, and cloud identity management systems such as AWS IAM. + +## Examples + +The following command authenticates the Boundary CLI using an OIDC auth method with the ID `amoidc_q7jAdI1QgA`: + +```shell-session +$ boundary authenticate oidc -auth-method-id amoidc_q7jAdI1QgA +Opening returned authentication URL in your browser... +``` + +**Example output:** + + + +```plaintext +Authentication information: + Account ID: acctoidc_f0wWsno9jQ + Auth Method ID: amoidc_q7jAdI1QgA + Expiration Time: Wed, 21 Apr 2021 15:02:38 MDT + User ID: u_zAfnbL9b7y + +The token was successfully stored in the chosen keyring and is not displayed here. +``` + + + +## Usage + + + +```shell-session +$ boundary authenticate oidc [options] [args] +``` + + + +### Command options + +- `-auth-method-id` `(string: "")` - The auth method resource you want to use for the authentication. +You can also specify the auth method resource using the **BOUNDARY_AUTH_METHOD_ID** environment variable. + +- `-scope-id` `(string: "")` - The scope ID to use for the operation. +You can also specify the scope ID using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/authenticate/password.mdx b/website/content/docs/commands/authenticate/password.mdx new file mode 100644 index 000000000..d798d0ef1 --- /dev/null +++ b/website/content/docs/commands/authenticate/password.mdx @@ -0,0 +1,64 @@ +--- +layout: docs +page_title: authenticate password - Command +description: |- + The "authenticate password" command invokes the password auth method to authenticate the Boundary CLI. +--- + +# authenticate password + +Command: `boundary authenticate password` + +The `authenticate password` command lets you invoke the password auth method to +authenticate the Boundary CLI. + + +## Examples + +The following example authenticates the Boundary CLI using the password auth method and specifying the username: + +```shell-session +$ boundary authenticate password -login-name user1 +Please enter the password (it will be hidden): + +Authentication information: + Account ID: acctpw_JQXp0QHxQL + Auth Method ID: ampw_xxF3EIBn4k + Expiration Time: Thu, 26 May 2022 11:36:27 MDT + User ID: u_RlkqMP6jUv + +The token was successfully stored in the chosen keyring and is not displayed here. +``` + +## Usage + + + +```shell-session +$ boundary authenticate password [options] [args] +``` + + + + +### Command options + +- `-auth-method-id` `(string: "")` - The auth-method resource you want to use for the + authentication. + You can also specify the auth method resource using the **BOUNDARY_AUTH_METHOD_ID** environment variable. + +- `-login-name` `(string: "")` - A login name that corresponds to an account + within the given auth method. + You can also specify a login name using the **BOUNDARY_AUTHENTICATE_PASSWORD_LOGIN_NAME** environment variable. + +- `-password` `(string: "")` - The password that is associated with the login name. + If this value is blank, the command prompts you to enter the password interactively + in a non-echoing way. Otherwise, this value can refer to a file on disk (`file://`) + from which a password is read or an environment variable (`env://`) from which the + password is read. You can also specify the password using the + **BOUNDARY_AUTHENTICATE_PASSWORD_PASSWORD** environment variable. + +- `-scope-id` `(string: "")` - The scope ID to use for the operation. You can also specify the scope ID using the **BOUNDARY_SCOPE_ID** environment variable. + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/config/autocomplete.mdx b/website/content/docs/commands/config/autocomplete.mdx new file mode 100644 index 000000000..f916d92c9 --- /dev/null +++ b/website/content/docs/commands/config/autocomplete.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: config autocomplete - Command +description: |- + The "config autocomplete" command installs or uninstalls autocompletion support for Boundary's CLI. +--- + +# config autocomplete + +Command: `boundary config autocomplete` + +The `config autocomplete` command lets you install or uninstall autocompletion support +for Boundary's CLI. + + +## Examples + +The following command installs autocompletion support for Boundary's CLI: + +```shell-session +$ boundary config autocomplete install +``` + +The following command uninstalls autocompletion support from Boundary's CLI: + +```shell-session +$ boundary config autocomplete uninstall +``` + +## Usage + +**Install:** + + + +```shell-session +$ boundary config autocomplete install [options] [args] +``` + + + +**Uninstall:** + + + +```shell-session +$ boundary config autocomplete uninstall [options] [args] +``` + + + + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/config/decrypt.mdx b/website/content/docs/commands/config/decrypt.mdx new file mode 100644 index 000000000..70ba986ed --- /dev/null +++ b/website/content/docs/commands/config/decrypt.mdx @@ -0,0 +1,65 @@ +--- +layout: docs +page_title: config decrypt - Command +description: |- + The "config decrypt" command decrypts sensitive values in a Boundary's configuration file. These values must be marked with {{decrypt()}} as appropriate. +--- + +# config decrypt + +Command: `boundary config decrypt` + +The `config decrypt` command decrypts sensitive values in a Boundary +configuration file. You must mark these values with `{{decrypt()}}` as +appropriate, for example: `key = {{decrypt(encrypted_value)}}`. + +## Examples + +The following command overwrites the existing configuration file using the `-overwrite` flag: + +```shell-session +$ boundary config decrypt -overwrite config.hcl +``` + +In order for this command to perform its task, you must define a "kms" block within the configuration file: + +```hcl +kms "aead" { + purpose = "config" + aead_type = "aes-gcm" + key = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs=" +} +``` + +You can define the "kms" block in the configuration file or using the `-config` +flag. If you define it in the configuration file, only string parameters are +supported, and the markers must be inside the quotation marks that delimit the string. +Additionally, if you define the block inline, do not use an "aead" block with +the key defined in the configuration file, as it provides no protection. + +## Usage + + + +```shell-session +$ boundary config decrypt [options] [args] +``` + + + + +### Command options + +- `-config` `(string: "")` - The configuration file to decrypt. + +- `-config-kms` `(string: "")` - If set, the given file is parsed for + a "kms" block with purpose `config` to determine whether it should be used to perform the command. + If you do not configure this value, the command expects a block to be defined inline with the configuration file, and will only be able to support quoted string parameters. + +- `-overwrite` - If set, overwrites the existing file. The default value is + `false`. + +- `-strip` - If set, strips the declarations from the file afterwards. + The default value is `false`. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/config/encrypt.mdx b/website/content/docs/commands/config/encrypt.mdx new file mode 100644 index 000000000..1b4b1e5a7 --- /dev/null +++ b/website/content/docs/commands/config/encrypt.mdx @@ -0,0 +1,66 @@ +--- +layout: docs +page_title: config encrypt - Command +description: |- + The "config encrypt" command encrypts sensitive values in a Boundary's configuration file. These values must be marked with {{encrypt()}} as appropriate. +--- + +# config encrypt + +Command: `boundary config encrypt` + +The `config encrypt` command encrypts sensitive values in a Boundary +configuration file. You must mark these values with `{{encrypt()}}` as +appropriate, for example: `key = {{encrypt(key_value)}}`. + + +## Examples + +The following command overwrites the existing configuration file use the `-overwrite` flag: + +```shell-session +$ boundary config encrypt -overwrite config.hcl +``` + +In order for this command to perform its task, you must define a "kms" block within a configuration file: + +```hcl +kms "aead" { + purpose = "config" + aead_type = "aes-gcm" + key = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs=" +} +``` + +You can define the "kms" block in the configuration file or using the `-config` +flag. If you define it in the configuration file, only string parameters are +supported, and the markers must be inside the quotation marks that delimit the string. +Additionally, if you define the block inline, do not use an "aead" block with +the key defined in the configuration file as it provides no protection. + +## Usage + + + +```shell-session +$ boundary config encrypt [options] [args] +``` + + + + +### Command options + +- `-config` `(string: "")` - The configuration file to encrypt. + +- `-config-kms` `(string: "")` - If set, the given file is parsed for + a "kms" block with purpose `config` to determine whether it should be used to perform the command. + If you do not configure this value, the command expects a block to be defined inline with the configuration file, and will only be able to support quoted string parameters. + +- `-overwrite` - If set, overwrites the existing file. The default value is + `false`. + +- `-strip` - If set, strips the declarations from the file afterwards. + The default value is `false`. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/config/get-token.mdx b/website/content/docs/commands/config/get-token.mdx new file mode 100644 index 000000000..94852dbcd --- /dev/null +++ b/website/content/docs/commands/config/get-token.mdx @@ -0,0 +1,92 @@ +--- +layout: docs +page_title: config get-token - Command +description: |- + The "config get-token" command fetches a token stored by the Boundary CLI. +--- + +# config get-token + +Command: `boundary config get-token` + +The `config get-token` command fetches a token stored by the Boundary CLI. + +## Examples + +The following command gets the token stored by the Boundary CLI: + +```shell-session +$ boundary config get-token +``` + +**Example output:** + + + +```plaintext +at_yczA5UPS7Y_s13B5PWh7KENvtKQKgDxaEvP682FMfq5eXrpzKNTpmaHgLS2ucRexrTQ7ueMhDFY5MdFvNuzuTWzUzYgacitnSBaPo75b3XZU4Zp6wmdsXqmkPNY3U +``` + + + +This command can be useful in various situations. For example, developers could share a line such as the following in a shell script, such that each +developer on their own machine executes the script using their own +Boundary token: + + + +```shell-session +$ curl --header "Authorization: Bearer $(boundary config get-token)" \ + --header "Content-Type: application/json" \ + http://127.0.0.1:9200/v1/roles/r_1234567890 +``` + + + +This command keeps parity with the behavior of other Boundary commands; if you set the +`BOUNDARY_TOKEN` environment variable, it overrides the value loaded +from the system store. Not only does this keep parity, but it also allows +examples such as the one above to work even if there is no stored token, but you specified +an environment variable. + +## Usage + + + +```shell-session +$ boundary config get-token [options] [args] +``` + + + +### Command options + +- `-account-id` - Prints out the account ID + associated with the token instead of the token itself, if specified. The default value is + `false`. + +- `-auth-method-id` - Prints out the auth method ID + associated with the token instead of the token itself, if specified. The default value is `false`. + +- `-keyring-type` `(string: "")` - Indicates the type of keyring to use. This value defaults to + `auto` which uses the Windows credential manager, OSX keychain, or + cross-platform password store depending on the platform. Set this value to `none` to disable + keyring functionality. The following keyring types are available, depending on platform: + + - `wincred` + - `keychain` + - `pass` + - `secret-service` + + You can also specify the keyring type using the **BOUNDARY_KEYRING_TYPE** environment + variable. + +- `-token-name` `(string: "")` - Indicates whether the given value should be used as + the name when loading the token from the system credential store. This value must + correspond to a name used when authenticating. You can also specify the token name using + the **BOUNDARY_TOKEN_NAME** environment variable. + +- `-user-id` - Prints out the user ID associated + with the token instead of the token itself, if specified. The default value is `false`. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/config/index.mdx b/website/content/docs/commands/config/index.mdx new file mode 100644 index 000000000..38168a81a --- /dev/null +++ b/website/content/docs/commands/config/index.mdx @@ -0,0 +1,60 @@ +--- +layout: docs +page_title: config - Command +description: |- + The "config" command groups subcommands for operators to interact with Boundary's configuration files. +--- + +# config + +Command: `boundary config` + +The `config` command groups subcommands for operators to interact with +Boundary's configuration files. + +## Examples + +The following command encrypts sensitive values in a configuration file: + +```shell-session +$ boundary config encrypt config.hcl +``` + +The following command decrypts sensitive values in a configuration file: + +```shell-session +$ boundary config decrypt config.hcl +``` + +The following command reads a stored token's output. + +```shell-session +$ boundary config get-token +``` + + +## Usage + + + +```shell-session +Usage: boundary config [options] [args] + + # ... + +Subcommands: + autocomplete Install or uninstall autocompletion for Boundary's CLI + decrypt Decrypt sensitive values in Boundary's configuration file + encrypt Encrypt sensitive values in Boundary's configuration file + get-token Get the stored token, or its properties +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [autocomplete](/boundary/docs/commands/config/autocomplete) +- [decrypt](/boundary/docs/commands/config/decrypt) +- [encrypt](/boundary/docs/commands/config/encrypt) +- [get-token](/boundary/docs/commands/config/get-token) diff --git a/website/content/docs/commands/connect/http.mdx b/website/content/docs/commands/connect/http.mdx new file mode 100644 index 000000000..3149520b5 --- /dev/null +++ b/website/content/docs/commands/connect/http.mdx @@ -0,0 +1,64 @@ +--- +layout: docs +page_title: connect http - Command +description: |- + The "connect http" command command performs a target authorization or consumes an existing authorization token, and launches a proxied http connection. +--- + +# connect http + +Command: `boundary connect http` + +The `connect http` command authorizes a session against a target and invokes an +HTTP client for the connection. +The command fills in the local address and port. + +@include 'cmd-connect-env-vars.mdx' + +## Example + +The following example authorizes a session to a target with the ID `ttcp_1234567890` and invokes the default HTTP client, `curl`: + +```shell-session +$ boundary connect http -target-id=ttcp_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary connect http [options] [args] +``` + + + +This command performs a target authorization or consumes an existing authorization token, and launches a proxied HTTP connection. + +@include 'cmd-connect-command-options.mdx' + +### HTTP options: + +- `-host` `(string: "")` - The host value to use. + This setting overrides the endpoint address from the session information. + Boundary passes the specified host name through to the client for use in the host header and TLS SNI value, if supported. + You can also specify the host value using the **BOUNDARY_CONNECT_HTTP_HOST** environment variable. + +- `-method` `(string: "")` - The HTTP method to use. +If you don't set a method, Boundary uses the client's default. +You can also specify a method using a the **BOUNDARY_CONNECT_HTTP_METHOD** environment variable. + +- `-path` `(string: "")` - The path that is appended to the + generated URL. + You can also specify a path using the **BOUNDARY_CONNECT_HTTP_PATH** environment variable. + +- `-scheme` `(string: "")` - The scheme to use. +The default scheme is `https`. +You can also specify the scheme using the **BOUNDARY_CONNECT_HTTP_SCHEME** environment variable. + +- `-style` `(string: "")` - How the CLI attempts to invoke an HTTP client. +This value also sets a suitable default for `-exec`, if you did not specify a value. +The default and currently-understood value is `curl`. +You can also specify how the CLI attempts to invoke the HTTP client using the **BOUNDARY_CONNECT_HTTP_STYLE** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/connect/index.mdx b/website/content/docs/commands/connect/index.mdx new file mode 100644 index 000000000..3eb513a30 --- /dev/null +++ b/website/content/docs/commands/connect/index.mdx @@ -0,0 +1,91 @@ +--- +layout: docs +page_title: connect - Command +description: |- + The "connect" command allows Boundary admin to authorize a target and launch a proxied connection. +--- + +# connect + +Command: `boundary connect` + +Every command that results in an API call contains a set of flags that control connection options, which include TLS and other settings. +Boundary provides connect helpers that can facilitate access to certain protocols like HTTP, RDP, and SSH. +One example is the Boundary helper for SSH that automatically accepts host SSH key prompts for you. +You run these connect helpers using the command `boundary connect `. +You can run `boundary connect -h` to see the available helpers, options, and arguments. + +## Examples + +The following example connects to a target `ttcP_INY0BCD2VF` and shows the use of the +[`-listen-addr`](/boundary/docs/commands//connect#-listen-port) and +[`-listen-port`](/boundary/docs/commands//connect#-listen-addr) flags +to specify the listening address and port used that Boundary will attempt to use +for every connection. This example uses the address `127.0.0.1` and +the port `8872`: + +```shell-session +$ boundary connect ssh \ + -listen-addr=127.0.0.1 \ + -listen-port=8872 + -target_id=ttcp_INY0BCD2VF +``` + +## Usage + + + +```text +Usage: boundary connect [options] [args] + # ... +Subcommands: + http Authorize a session against a target and invoke an HTTP client to connect + kube Authorize a session against a target and invoke a Kubernetes client to connect + postgres Authorize a session against a target and invoke a Postgres client to connect + rdp Authorize a session against a target and invoke an RDP client to connect + ssh Authorize a session against a target and invoke an SSH client to connect +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [http](/boundary/docs/commands/connect/http) +- [kube](/boundary/docs/commands/connect/kube) +- [postgres](/boundary/docs/commands/connect/postgres) +- [rdp](/boundary/docs/commands/connect/rdp) +- [ssh](/boundary/docs/commands/connect/ssh) + +### Command options + +- `-addr` `(string: "")` - The address of the Boundary controller as a complete URL, for example https://boundary.example.com:9200. + Instead of passing the `-addr` argument with every command, you can configure the **BOUNDARY_ADDR** environment variable. + In both cases, the value denotes the address of the Boundary environment you want to send CLI commands to. +- `-ca-cert` `(string: "")` - The path on the local disk to a single PEM-encoded CA certificate that should be used to verify the controller or worker server's SSL certificate. + This value takes precedence over `-ca-path`. + You can also specify the path using the **BOUNDARY_CACERT** environment variable. +- `-ca-path` `(string: "")` - The path on the local disk to a directory of PEM-encoded CA certificates that should be used to verify the controller's SSL certificate. + You can also specify the path using the **BOUNDARY_CAPATH** environment variable. +- `-client-cert` `(string: "")` - The path on the local disk to a single PEM-encoded CA certificate that should be used for TLS authentication to the Boundary controller. + If you configure this flag, the `-client-key` value is also required. + You can also specify the path using the **BOUNDARY_CLIENT_CERT** environment variable. +- `-client-key` `(string: "")` - The path on the local disk to a single PEM-encoded private key that matches the client certificate you referenced with `-client-cert`. + You can also specify the path using the **BOUNDARY_CLIENT_KEY** environment variable. +- `-listen-addr` `(string: "")` - If set, the CLI attempts to bind its listening address to the given value, which must be an IP address. + If it cannot bind the listening address, the command produces an error. + If you do not set this value, Boundary defaults to the most common IPv4 loopback address, 127.0.0.1. + You can also specify a listening address using the **BOUNDARY_CONNECT_LISTEN_ADDR** environment variable. +- `-listen-port` `(string: "")` - If set, the CLI attempts to bind its listening port to the given value. + If it cannot bind the listening port, the command produces error. + You can also specify a listening address using the **BOUNDARY_CONNECT_LISTEN_PORT** environment variable. +- `-tls-insecure` - If set, this option disables verification of TLS certificates. + We highly discourage using this option as it decreases the security of data transmissions to + and from the Boundary server. + The default value is `false`. + You can also disable TLS certificate validation using the **BOUNDARY_TLS_INSECURE** environment variable. +- `-tls-server-name` `(string: "")` - A name to use as the SNI host when you connect to the Boundary server using TLS. + You can also specify the SNI host using the **BOUNDARY_TLS_SERVER_NAME** environment variable. + + +@include 'cmd-connect-command-options.mdx' diff --git a/website/content/docs/commands/connect/kube.mdx b/website/content/docs/commands/connect/kube.mdx new file mode 100644 index 000000000..359297e67 --- /dev/null +++ b/website/content/docs/commands/connect/kube.mdx @@ -0,0 +1,58 @@ +--- +layout: docs +page_title: connect kube - Command +description: |- + The "connect kube" command command performs a target authorization or consumes an existing authorization token, and launches a proxied kube connection. +--- + +# connect kube + +Command: `boundary connect kube` + +The `connect kube` command authorizes a session against a target and invokes a +Kubernetes client for the connection. +The command fills in the local address and port. + +@include 'cmd-connect-env-vars.mdx' + +## Examples + +The following example authorizes a session to a target with the ID `ttcp_1234567890` and runs the `get nodes` command using the default `kubectl` client: + +```shell-session +$ boundary connect kube \ + -target-id ttcp_t12345 \ + -- get nodes +``` + +## Usage + + + +```shell-session +$ boundary connect kube [options] [args] +``` + + + +This command performs a target authorization or consumes an existing authorization token, and launches a proxied Kube connection. + +@include 'cmd-connect-command-options.mdx' + +### Kubernetes options: + +- `-host` `(string: "")` - The host value to use. + If set, this value overrides the endpoint address from the session information. + Boundary passes the specified host name through to the client for use in the TLS SNI value, if supported. + You can also specify the host value using the **BOUNDARY_CONNECT_KUBE_HOST** environment variable. + +- `-scheme` `(string: "")` - The scheme to use. +The default value is `https`. +You can also specify the scheme using the **BOUNDARY_CONNECT_KUBE_SCHEME** environment variable. + +- `-style` `(string: "")` - How the CLI attempts to invoke a Kubernetes client. +This value also sets a suitable default for `-exec`, if you did not specify a value. +The default and currently-understood value is `kubectl`. +You can also specify how the CLI attempts to invoke a Kubernetes client using the `BOUNDARY_CONNECT_KUBE_STYLE` environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/connect/postgres.mdx b/website/content/docs/commands/connect/postgres.mdx new file mode 100644 index 000000000..de37e4f37 --- /dev/null +++ b/website/content/docs/commands/connect/postgres.mdx @@ -0,0 +1,69 @@ +--- +layout: docs +page_title: connect postgres - Command +description: |- + The "connect postgres" command performs a target authorization or consumes an existing authorization token, and launches a proxied postgres connection. +--- + +# connect postgres + +Command: `boundary connect postgres` + +The `connect postgres` command authorizes a session against a target and invokes a Postgres client for the connection. +The command fills in the local address and port. + +@include 'cmd-connect-env-vars.mdx' + + +## Examples + +The following example shows how to connect to a target with the ID `ttcp_eTcMueUYv` using a Postgres helper: + +```shell-session +$ boundary connect postgres -target-id=ttcp_eTcZMueUYv \ + -dbname=northwind \ + -username=superuser \ + -format=table +``` + +When prompted, you must enter the password for the user, "superuser": + + + +```plaintext +Password for user superuser: +psql (14.2, server 13.2 (Debian 13.2-1.pgdg100+1)) +Type "help" for help. + +postgres=# +``` + + + +## Usage + + + +```shell-session +$ boundary connect postgres [options] [args] +``` + + + +@include 'cmd-connect-command-options.mdx' + +### Postgres options: + +- `-dbname` `(string: "")` - The database name you want to pass through to the client. +You can also specify the database name using the **BOUNDARY_CONNECT_DBNAME** environment variable. + +- `-style` `(string: "")` - How the CLI attempts to invoke a Postgres client. +This value also sets a suitable default for `-exec`, if you did not specify a value. +The default and currently-understood value is `psql`. +You can also specify how the CLI attempts to invoke a Postgres client using the **BOUNDARY_CONNECT_POSTGRES_STYLE** environment variable. + +- `-username` `(string: "")` - The username you want to pass through to the client. +This value may be overridden by credentials sourced from a credential store. +You can also specfiy a username using the **BOUNDARY_CONNECT_USERNAME** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/connect/rdp.mdx b/website/content/docs/commands/connect/rdp.mdx new file mode 100644 index 000000000..8e0d6d73f --- /dev/null +++ b/website/content/docs/commands/connect/rdp.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: connect rdp - Command +description: |- + The "connect rdp" command command performs a target authorization or consumes an existing authorization token, and launches a proxied rdp connection. +--- + +# connect rdp + +Command: `boundary connect rdp` + +The `connect rdp` command authorizes a session against a target and invokes an RDP client for the connection. +The command fills in the local address and port. + +@include 'cmd-connect-env-vars.mdx' + +## Examples + +The following example authorizes a session to a target with the ID `ttcp_1234567890` and invokes an RDP session with the built-in Windows RDP client, `mstsc`: + +```shell-session +$ boundary connect rdp \ + -target-id ttcp_1234567890 +``` + +The following example authorizes a session to a target with the ID `ttcp_123457890` and invokes a custom command for the RDP macOS client: + +```shell-session +$ boundary connect rdp \ + -target-id ttcp_1234567890 + -exec bash \ + -- -c "open rdp://full%20address=s={{boundary.addr}} && sleep 600" +``` + +## Usage + + + +```shell-session +$ boundary connect rdp [options] [args] +``` + + + +This command performs a target authorization or consumes an existing authorization token, and launches a proxied RDP connection. + +@include 'cmd-connect-command-options.mdx' + +### RDP options: + +- `-style` `(string: "")` - How the CLI attempts to invoke an RDP client. +This value also sets a suitable default for `-exec`, if you did not specify a value. +The currently-understood value is `mstsc`, which is the default on Windows and launches the Windows client. +It is also the default on Mac, and launches an rdp://URL. +You can also specify how the CLI attempts to invoke an RDP client using the **BOUNDARY_CONNECT_RDP_STYLE** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/connect/ssh.mdx b/website/content/docs/commands/connect/ssh.mdx new file mode 100644 index 000000000..571463121 --- /dev/null +++ b/website/content/docs/commands/connect/ssh.mdx @@ -0,0 +1,90 @@ +--- +layout: docs +page_title: connect ssh - Command +description: |- + The "connect ssh" command command performs a target authorization or consumes an existing authorization token, and launches a proxied SSH connection. +--- + +# connect ssh + +Command: `boundary connect ssh` + +The `connect ssh` command authorizes a session against a target and invokes an SSH client for the connection. +The command fills in the local address and port. +You can specify your SSH client of choice using the `-style` option. + +@include 'cmd-connect-env-vars.mdx' + +The SSH helper command sets the host key `Alias`. +When an `Alias` is set, SSH does not use `localhost:` for host key validation, but instead uses one of the following: + +- For connections to a target that has an attached host set, the SSH helper command sets the `HostID` as the alias. +- For connections directly to a host, the SSH helper command sets the `HostID` as the alias. +- For connections to a target that has an address field configured, the SSH helper command sets the `TargetID` as the alias. + +## Examples + +The following example authorizes a session to a target with the ID `ttcp_eTcZMueUYv` and invokes the default SSH client without any additional options: + + + +```shell-session +$ boundary connect ssh -target-id ttcp_eTcZMueUYv +``` + + + +The following example authorizes a session to a target with the ID `ttcp_eTcZMueUYv`, and pipes arguments directly to the invoked SSH binary. +Any SSH arguments after the double hyphen are sent directly to the binary: + + + +```shell-session +$ boundary connect ssh -target-id ttcp_eTcZMueUYv -- -A +``` + + + + + +```shell-session +$ boundary connect ssh -target-scope-name Helpdesk -target-name ubuntu-server -- -A +``` + + + + + +```shell-session +$ boundary connect ssh -target-id=ttcp_Gymo7Vcq7Y \ + -host-id=hst_FrdNPd9Zm9 -- -l ubuntu -i private_key.pem +``` + + + +## Usage + + + +```shell-session +$ boundary connect ssh [options] [args] +``` + + + +This command performs a target authorization or consumes an existing authorization token, and launches a proxied SSH connection. + +@include 'cmd-connect-command-options.mdx' + +### SSH options: + +- `style` `(string: "")` - How the CLI attempts to invoke an SSH + client. + This value also sets a suitable default for `-exec`, if you did not specify a value. + Currently understood values are `ssh` and `putty`. + The default is `ssh`. + You can also specify how the CLI attempts to invoke the SSH client using the **BOUNDARY_CONNECT_SSH_STYLE** environment variable. + +- `username` `(string: "")` - The username you want to pass through to the + client. + You can also specify a username using the **BOUNDARY_CONNECT_USERNAME** environment variable. diff --git a/website/content/docs/commands/credential-libraries/create.mdx b/website/content/docs/commands/credential-libraries/create.mdx new file mode 100644 index 000000000..e4917c6a3 --- /dev/null +++ b/website/content/docs/commands/credential-libraries/create.mdx @@ -0,0 +1,192 @@ +--- +layout: docs +page_title: credential-libraries create - Command +description: |- + The "credential-libraries create" command lets you create Boundary credential library resources. +--- + +# credential-libraries create + +Command: `boundary credential-libraries create` + +The `credential-libraries create` command lets you create a credential library resource in Boundary. + +## Examples + +The following example creates a credential library for database credentials where Vault's database secrets engine provides dynamic credentials: + +```shell-session +$ boundary credential-libraries create vault-generic \ + -credential-store-id csvlt_5fvkRjCjou \ + -vault-path "database/creds/dba" \ + -name "northwind dba" +``` + +**Example output:** + + + +```plaintext +Credential Library information: + Created Time: Wed, 28 Sep 2022 08:50:32 MDT + Credential Store ID: csvlt_Xqa6V6QwfM + ID: clvlt_Ex17uiP7FO + Name: northwind dba + Type: vault + Updated Time: Wed, 28 Sep 2022 08:50:32 MDT + Version: 1 + + Scope: + ID: p_EZaXO0OZPX + Name: db-project + Parent Scope ID: o_R1QFYcO743 + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + HTTP Method: GET + Path: database/creds/dba +``` + + + + +## Usage + + + +```shell-session +$ boundary credential-libraries create [type] [sub command] [options] [args] +``` + + + +### Command options + +- `-credential-store-id` `(string: "")` - The credential store resource to use + for the operation. You can also specify the credential store using the + **BOUNDARY_CREDENTIAL_STORE_ID** environment variable. +- `-description` `(string: "")` - A description of the credential library. +- `-name` `(string: "")` - The name of the credential library. + + +### Usages by type + +The available types are `vault-generic` and `vault-ssh-certificate`. + + + +A credential library type, `vault` is deprecated, so use `vault-generic` type instead. + + + + + + + +The `credential-libraries create vault-generic` command lets you create a generic Vault credential library. + +#### Example + +The following example creates a generic Vault credential library using a credential store with the ID `csvlt_1234567890`: + +```shell-session +$ boundary credential-libraries create vault-generic \ + -credential-store-id csvlt_1234567890 \ + -vault-path "database/creds/dba" +``` + +#### Usage + + + +```shell-session +$ boundary credential-libraries create vault-generic [options] [args] +``` + + + +#### Vault credential library options + +The following are specific Vault credential library options in addition to the command options: + +- `-credential-mapping-override` - An override for credential mapping. +- `-credential-type` `(string: "")` - The type of credential this library issues. +The default value is `Unspecified`. +- `-vault-http-method` `(string: "")` - The HTTP method the library should use when it communicates with Vault. +- `-vault-http-request-body` `(string: "")` - The HTTP request body the credential library uses to communicate with Vault. +This value can be the HTTP request body value itself, it can refer to a file on disk (`file://`) from which the value is read, or it can refer to an environment variable (`env://`) from which the value is read. +- `-vault-path` `(string: "")` - The path in Vault to request credentials from. + + + + + +The `credential-libraries create vault-ssh-certificate` command lets you create a Vault SSH certificate credential library. + +#### Example + +The following example creates a Vault SSH certificate credential library with the ID `csvlt_1234567890`: + +```shell-session +$ boundary credential-libraries create vault-ssh-certificate \ + -credential-store-id csvlt_1234567890 \ + -vault-path "/ssh/sign/role" \ + -username user +``` + +#### Usage + + + +```shell-session +$ boundary credential-libraries create vault-ssh-certificate [options] [args] +``` + + + +#### Vault SSH certificate credential library options + +The following are options are specific to the Vault SSH certificate credential library, in addition to the command options: + +- `-critical-option` - A key=value pair to add to the request's + critical-options map. + It can also be a key value only which sets a JSON null as the value. + If you provide a value, Boundary infers the type automatically. + You can use `-string-critical-option`, `-bool-critical-option`, or `-num-critical-option` to override the type. + You can specify values for this option multiple times. + This option supports sourcing values from files using `file://` and environment variables using `env://`. +- `-critical-options` `(string: "")` - A JSON map value to use as the entirety of the request's critical-options map. +Usually this value is sourced from a file using the `file://` syntax. +This value is exclusive with the other critical-option flags. +- `-extension` - A key=value pair to add to the request's extensions map. +It can also be a key value only which will set a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can use `-string-extension`, `-bool-extension`, or `-num-extension` to override the type. +You can specify values for this option multiple times. +This option supports sourcing values from files using `file://` and environment variables using `env://`. +- `-extensions` `(string: "")` - A JSON map value to use as the entirety of + the request's extensions map. + Usually this value is sourced from a file using the `file://` syntax. + This option is exclusive with the other extension flags. +- `-key-bits` `(string: "")` - The number of bits to use when the SSH private key is generated. +The value depends on the `key_type`. +If you use a `ed25519` key, you should not set a value or set the value to `0`. +If you use a `ecdsa` key, you should set the value to `256`, `384`, or `521`. +If you use an `rsa` key, you should set the value to `2048`, `3072`, or `4096`. +- `-key-id` `(string: "")` - Specifies the created certificate's key id. +- `-key-type` `(string: "")` - Specifies the key type for the generated ssh private key. +Supported values include `ed25519`, `ecdsa`, and `rsa`. +- `-ttl` `(string: "")` - The generated certificate's time-to-live. +- `-username` `(string: "")` - The username to use with the SSH certificate. +- `-vault-path` `(string: "")` - The path in Vault to request credentials from. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-libraries/delete.mdx b/website/content/docs/commands/credential-libraries/delete.mdx new file mode 100644 index 000000000..09a133b8c --- /dev/null +++ b/website/content/docs/commands/credential-libraries/delete.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: credential-libraries delete - Command +description: |- + The "credential-libraries delete" command lets Boundary admin delete a credential library resource. +--- + +# credential-libraries delete + +Command: `boundary credential-libraries delete` + +The `credential-libraries delete` command lets you delete an existing credential library resource. + +## Example + +The following example deletes a credential library with the ID `csvlt_5fvkRjCjou`: + +```shell-session +$ boundary credential-libraries delete -id csvlt_5fvkRjCjou +``` + +## Usage + + + +```shell-session +$ boundary credential-libraries delete [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the credential library to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-libraries/index.mdx b/website/content/docs/commands/credential-libraries/index.mdx new file mode 100644 index 000000000..3be2a2adc --- /dev/null +++ b/website/content/docs/commands/credential-libraries/index.mdx @@ -0,0 +1,89 @@ +--- +layout: docs +page_title: credential-libraries - Command +description: |- + The "credential-libraries" command lets Boundary admin create and manage credential libraries. +--- + +# credential-libraries + +Command: `boundary credential-libraries` + +The `credential-libraries` command lets you perform operations on Boundary credential library resources. +A credential library provides credentials for sessions. +All credentials returned by a library must be equivalent from an access control perspective. + +A credential library is responsible for managing the lifecycle of the credentials it returns. +For dynamic secrets, this includes creation, renewal, and revocation. +For rotating credentials, this includes check-out, check-in, and rotation of secrets. +The system retrieves credentials from a library for a session and notifies the library when the session has been terminated. +A credential library belongs to a single credential store. + +## Examples + +The following example retrieves information for a credential library with the ID, `clvlt_QYnQPAjA24`: + +```shell-session +$ boundary credential-libraries read -id clvlt_QYnQPAjA24 +``` + +**Example output:** + + + +```plaintext +Credential Library information: + Created Time: Fri, 18 Aug 2023 16:22:29 PDT + Credential Store ID: csvlt_5fvkRjCjou + ID: clvlt_QYnQPAjA24 + Name: northwind dba + Type: vault-generic + Updated Time: Fri, 18 Aug 2023 16:22:29 PDT + Version: 1 + + Scope: + ID: p_tnqESc86qE + Name: db-project + Parent Scope ID: o_4VUR6ZATqW + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + HTTP Method: GET + Path: database/creds/dba +``` + + + +## Usage + + + +```shell-session +Usage: boundary credential-libraries [sub command] [options] [args] + + # ... + +Subcommands: + create Create a credential library + delete Delete a credential library + list List a credential library + read Read a credential library + update Update a credential library +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/credential-libraries/create) +- [delete](/boundary/docs/commands/credential-libraries/delete) +- [list](/boundary/docs/commands/credential-libraries/list) +- [read](/boundary/docs/commands/credential-libraries/read) +- [update](/boundary/docs/commands/credential-libraries/update) diff --git a/website/content/docs/commands/credential-libraries/list.mdx b/website/content/docs/commands/credential-libraries/list.mdx new file mode 100644 index 000000000..7d1be8cea --- /dev/null +++ b/website/content/docs/commands/credential-libraries/list.mdx @@ -0,0 +1,62 @@ +--- +layout: docs +page_title: credential-libraries list - Command +description: |- + The "credential-libraries list" command lists credential libraries within an enclosing scope or resource. +--- + +# credential-libraries list + +Command: `boundary credential-libraries list` + +The `credential-libraries list` command lists credential libraries within an enclosing scope or resource. + +## Examples + +The following example lists all credential libraries for a credential store with the ID `clvlt_QYnQPAjA24`: + +```shell-session +$ boundary credential-libraries list \ + -credential-store-id +``` + +**Example output:** + + + +```plaintext +Credential Library information: + ID: clvlt_QYnQPAjA24 + Version: 1 + Type: vault-generic + Name: northwind dba + Authorized Actions: + no-op + read + update + delete +``` + + + +## Usage + + + +```shell-session +$ boundary credential-libraries list [options] [args] +``` + + + + +### Command options + +- `-credential-store-id` `(string: "")` - The credential store resource to list credential libraries for. +You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_ID** environment variable. +- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-libraries/read.mdx b/website/content/docs/commands/credential-libraries/read.mdx new file mode 100644 index 000000000..b3692c80a --- /dev/null +++ b/website/content/docs/commands/credential-libraries/read.mdx @@ -0,0 +1,71 @@ +--- +layout: docs +page_title: credential-libraries read - Command +description: |- + The "credential-libraries read" command lets Boundary admin read credential library information. +--- + +# credential-libraries read + +Command: `boundary credential-libraries read` + +The `credential-libraries read` command reads the credential library information for a specific credential library ID. + + +## Examples + +The following example retrieves credential library information for a credential library with the ID `clvlt_QYnQPAjA24`: + +```shell-session +$ boundary credential-libraries read -id clvlt_QYnQPAjA24 +``` + +**Example output:** + + + +```plaintext +Credential Library information: + Created Time: Fri, 18 Aug 2023 16:22:29 PDT + Credential Store ID: csvlt_5fvkRjCjou + ID: clvlt_QYnQPAjA24 + Name: northwind dba + Type: vault-generic + Updated Time: Fri, 18 Aug 2023 16:22:29 PDT + Version: 1 + + Scope: + ID: p_tnqESc86qE + Name: db-project + Parent Scope ID: o_4VUR6ZATqW + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + HTTP Method: GET + Path: database/creds/dba +``` + + + +## Usage + + + +```shell-session +$ boundary credential-libraries read [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the credential library from which to read information. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-libraries/update.mdx b/website/content/docs/commands/credential-libraries/update.mdx new file mode 100644 index 000000000..220e63055 --- /dev/null +++ b/website/content/docs/commands/credential-libraries/update.mdx @@ -0,0 +1,190 @@ +--- +layout: doc +page_title: credential-libraries update - Command +description: |- + The "credential-libraries update" command lets Boundary admin update a credential library resource. +--- + +# credential-libraries update + +Command: `boundary credential-libraries update` + +The `credential-libraries update` command lets you update Boundary credential library resources. + +## Examples + +The following example updates an existing Vault credential library with the ID `csvlt_5fvkRjCjou` to point to a new Vault secrets engine path: + +```shell-session +$ boundary credential-libraries update vault-generic \ + -id csvlt_5fvkRjCjou \ + -vault-path "database/creds/db-mysql" +``` + +**Example output:** + + + +```plaintext +Credential Library information: + Created Time: Fri, 18 Aug 2023 16:22:29 PDT + Credential Store ID: csvlt_5fvkRjCjou + ID: clvlt_QYnQPAjA24 + Name: northwind dba + Type: vault-generic + Updated Time: Fri, 18 Aug 2023 20:04:27 PDT + Version: 2 + + Scope: + ID: p_tnqESc86qE + Name: db-project + Parent Scope ID: o_4VUR6ZATqW + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + HTTP Method: GET + Path: database/creds/db-mysql +``` + + + + +## Usage + + + +```shell-session +$ boundary credential-libraries update vault [options] [args] +``` + + + +### Command options + +- `-description` `(string: "")` - A description to set on the credential library. +- `-id` `(string: "")` - The ID of the credential library to update. +- `-name` `(string: "")` - A name to set on the credential library. +- `-version` `(int: 0)` - The version of the credential library against which to perform the update operation. +If you don't specify a version, the command performs a check-and-set automatically. + +#### Usages by type + +The available types are `vault-generic` and `vault-ssh-certificate`. + + + +A credential library type, `vault` is deprecated, so use `vault-generic` type +instead. + + + + + + +The `credential-libraries update vault-generic` command lets you update a generic Vault credential library. + +#### Example + +The following example updates a generic Vault credential library with the ID `clvlt_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary credential-libraries update vault-generic \ + -id clvlt_1234567890 \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credential-libraries create vault-generic [options] [args] +``` + + + +#### Vault credential library options + +The following are specific Vault credential library options in addition to the command options: + +- `-credential-mapping-override` - An override for credential mapping. +- `-vault-http-method` `(string: "")` - The HTTP method the library should use when it communicates with Vault. +- `-vault-http-request-body` `(strinboundary credential-libraries update vault-ssh-certificate -id clvsclt_1234567890 -name devops -description "For DevOps usage": "")` - The HTTP request body the credential library uses to communicate with Vault. +This value can be the HTTP request body itself, it can refer to a file on disk (`file://`) from which the value is read, or it can refer to an environment variable (`env://`) from which the value is read. +- `-vault-path` `(string: "")` - The path in Vault to request credentials from. + + + + + +The `credential-libraries update vault-ssh-certificate` command lets you update a Vault SSH certificate credential library. + +#### Example + +The following example updates a Vault SSH certificate credential library with the ID `clvsclt_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary credential-libraries update vault-ssh-certificate \ + -id clvsclt_1234567890 \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credential-libraries update vault-ssh-certificate [options] [args] +``` + + + +#### Vault SSH certificate credential library options + +The following are options specific to the Vault SSH certificate credential library, in addition to the command options: + +- `-critical-option` - A key=value pair to add to the request's + critical-options map. + It can also be a key value only which sets a JSON null as the value. + If you provide a value, Boundary infers the type automatically. + You can use `-string-critical-option`, `-bool-critical-option`, or `-num-critical-option` to override the type. + You can specify values for this option multiple times. + This option supports sourcing values from files using `file://` and environment variables using `env://`. +- `-critical-options` `(string: "")` A JSON map value to use as the entirety of the request's critical-options map. +Usually this value is sourced from a file using the `file://` syntax. +This value is exclusive with the other critical-option flags. +- `-extension` - A key=value pair to add to the request's extensions map. +It can also be a key value only which will set a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can use `-string-extension`, `-bool-extension`, or `-num-extension` to override the type. +You can specify values for this option multiple times. +This option supports sourcing values from files using `file://` and environment variables using `env://`. +- `-extensions` `(string: "")` - A JSON map value to use as the entirety of + the request's extensions map. + Usually this value is sourced from a file using the `file://` syntax. + This option is exclusive with the other extension flags. +- `-key-bits` `(string: "")` - The number of bits to use when the SSH private key is generated. +The value depends on the `key_type`. +If you use a `ed25519` key, you should not set a value or set the value to `0`. +If you use a `ecdsa` key, you should set the value to `256`, `384`, or `521`. +If you use an `rsa` key, you should set the value to `2048`, `3072`, or `4096`. +- `-key-id` `(string: "")` - Specifies the certificate's key id. +- `-key-type` `(string: "")` - Specifies the key type for the ssh private key. +Supported values include `ed25519`, `ecdsa`, and `rsa`. +- `-ttl` `(string: "")` - The generated certificate's time-to-live. +- `-username` `(string: "")` - The username to use with the SSH certificate. +- `-vault-path` `(string: "")` - The path in Vault to request credentials from. + + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-stores/create.mdx b/website/content/docs/commands/credential-stores/create.mdx new file mode 100644 index 000000000..e90d6dd1c --- /dev/null +++ b/website/content/docs/commands/credential-stores/create.mdx @@ -0,0 +1,156 @@ +--- +layout: docs +page_title: credential-stores create - Command +description: |- + The "credential-stores create" command lets you create Boundary credential store resources. +--- + +# credential-stores create + +Command: `boundary credential-stores create` + +The `credential-stores create` command lets you create a Boundary credential store resource. + +## Examples + +The following example creates a credential store resource in a project scope with the ID `p_tnqESc86qE`: + +```shell-session +$ boundary credential-stores create vault -scope-id p_tnqESc86qE \ + -vault-address $VAULT_ADDR \ + -vault-token $VAULT_TOKEN \ + -vault-namespace $VAULT_NAMESPACE +``` + +**Example output:** + + + +```plaintext +Credential Store information: + Created Time: Thu, 28 Jul 2022 15:08:12 MDT + ID: csvlt_ytzGHsfp3r + Type: vault + Updated Time: Thu, 28 Jul 2022 15:08:12 MDT + Version: 1 + + Scope: + ID: p_jd7lspegXk + Name: ssh-project + Parent Scope ID: o_SN2K0DAGpi + Type: project + + Authorized Actions: + no-op + read + update + delete + + Authorized Actions on Credential Store's Collections: + credential-libraries: + create + list + + Attributes: + Address: https://vault-cluster-boundary.vault.11eb3a47-8920-4714-ba99-0242ac11000e.aws.hashicorp.cloud:8200 + Token HMAC: NZJWT74Jyq09gLQfP4RiK5eDWfY7NWXYHoKL4nKQFDY +``` + + + + +## Usage + + + +```shell-session +$ boundary credential-stores create [type] [sub command] [options] [args] +``` + + + +### Command options + +- `-description` `(string: "")` - The description to set on the credential store. +- `-name` `(string: "")` - The name to set on the credential store. +- `-scope-id` `(string: "")` - The scope in which to make the request. +The default scope is `global`. +You can also indicate the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +### Usages by type + +The available types are `static` and `vault`. + + + + +The `credential-stores create static` command lets you create a static-type credential store. + +#### Example + +The following example creates a static credential score in a scope with the ID `p_1234567890`: + +```shell-session +$ boundary credential-stores create static -scope-id p_1234567890 +``` + +#### Usage + + + +```shell-session +$ boundary credential-stores create static [options] [args] +``` + + + + + + + +The `credential-stores create vault` command lets you create a Vault credential store. + +#### Example + +The following example creates a Vault credential store: + +```shell-session +$ boundary credential-stores create vault \ + -vault-address "http://127.0.0.1:8200" \ + -vault-token "" +``` + +#### Usage + + + +```shell-session +$ boundary credential-stores create vault [options] [args] +``` + + + +#### Vault credential stores options + +The following options are specific to Vault credential stores in addition to the command options: + +- `-vault-address` `(string: "")` - The address of the Vault server. +The address should be a complete URL such as https://127.0.0.1:8200. +- `-vault-ca-cert` `(string: "")` - The CA certificate to use when you connect to Vault. +This value can be the CA certificate itself, or it can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-vault-client-certificate` `(string: "")` - The client certificate to use when Boundary connects to Vault for this credential store. +This value can be the client certificate itself, or it can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-vault-client-certificate-key` `(string: "")` - The private key the client certificate should use when Boundary connects to Vault for this store. +This value can be the private key itself, or it can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-vault-namespace` `(string: "")` - The Vault namespace the credential store should use. +- `-vault-tls-server-name` `(string: "")` - The name to use as the SNI host when you connect using TLS. +- `-vault-tls-skip-verify` - If set, skips TLS verification. +The default value is `false`. +- `-vault-token` `(string: "")` - The Vault token to use when Boundary connects to Vault for this credential store. +- `-worker-filter` `(string: "")` - A Boolean expression to filter which workers can process Vault commands for this credential store. + + + + + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credential-stores/delete.mdx b/website/content/docs/commands/credential-stores/delete.mdx new file mode 100644 index 000000000..c103d09bd --- /dev/null +++ b/website/content/docs/commands/credential-stores/delete.mdx @@ -0,0 +1,38 @@ +--- +layout: docs +page_title: credential-stores delete - Command +description: |- + The "credential-stores delete" command lets Boundary admin delete a credential store resource. +--- + +# credential-stores delete + +Command: `boundary credential-stores delete` + +The `credential-stores delete` command deletes a credential store given its ID. + +## Examples + +The following example deletes a credential store with the ID `csvlt_5fvkRjCjou`: + +```shell-session +$ boundary credential-stores delete -id csvlt_5fvkRjCjou +The delete operation completed successfully. +``` + +## Usage + + + +```shell-session +$ boundary credential-stores delete [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the credential store to delete. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credential-stores/index.mdx b/website/content/docs/commands/credential-stores/index.mdx new file mode 100644 index 000000000..95da35d76 --- /dev/null +++ b/website/content/docs/commands/credential-stores/index.mdx @@ -0,0 +1,70 @@ +--- +layout: docs +page_title: credential-stores - Command +description: |- + The "credential-stores" command lets Boundary admin create and manage credential stores. +--- + +# credential-stores + +Command: `boundary credential-stores` + +The `credential-stores` command lets you manage Boundary credential store resources. + +A credential store is a resource that can retrieve, store, and potentially generate credentials of differing types and differing access levels. +They belong to projects and support the principle of least privilege by limiting the credentials that can be accessed to the minimum necessary for the project. +A credential store can also contain credential libraries. + +## Examples + +The following example lists all credential stores for a scope with the ID `p_tnqESc86qE`: + +```shell-session +$ boundary credential-stores list -scope-id p_tnqESc86qE +``` + +**Example output:** + + + +```plaintext +Credential Store information: + ID: csvlt_5fvkRjCjou + Version: 1 + Type: vault + Authorized Actions: + no-op + read + update + delete +``` + + + +## Usage + + + +```shell-session +Usage: boundary credential-stores [sub command] [options] [args] + + # ... + +Subcommands: + create Create a credential store + delete Delete a credential store + list List a credential store + read Read a credential store + update Update a credential store +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/credential-stores/create) +- [delete](/boundary/docs/commands/credential-stores/delete) +- [list](/boundary/docs/commands/credential-stores/list) +- [read](/boundary/docs/commands/credential-stores/read) +- [update](/boundary/docs/commands/credential-stores/update) diff --git a/website/content/docs/commands/credential-stores/list.mdx b/website/content/docs/commands/credential-stores/list.mdx new file mode 100644 index 000000000..2437b63f7 --- /dev/null +++ b/website/content/docs/commands/credential-stores/list.mdx @@ -0,0 +1,63 @@ +--- +layout: docs +page_title: credential-stores list - Command +description: |- + The "credential-stores list" command lists credential stores within an enclosing scope or resource. +--- + +# credential-stores list + +Command: `boundary credential-stores list` + +The `credential-stores list` command lists any credential stores within an enclosing scope or resource. + +## Examples + +The following example lists all credential stores for a scope with the ID `p_tnqESc86qE`: + +```shell-session +$ boundary credential-stores list -scope-id p_tnqESc86qE +``` + +**Example output:** + + + +```plaintext +Credential Store information: + ID: csvlt_5fvkRjCjou + Version: 1 + Type: vault + Authorized Actions: + no-op + read + update + delete +``` + + + +## Usage + + + +```shell-session +$ boundary credential-stores list [options] [args] +``` + + + + +### Command options + +- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-recursive` - If set, the list operation is applied recursively into child scopes, if supported by the type. +The default value is `false`. +- `-scope-id ``(string: "")` - The scope in which to make the request. +The default value is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-stores/read.mdx b/website/content/docs/commands/credential-stores/read.mdx new file mode 100644 index 000000000..29ad09eb7 --- /dev/null +++ b/website/content/docs/commands/credential-stores/read.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: credential-stores read - Command +description: |- + The "credential-stores read" command lets Boundary admin read credential store information. +--- + +# credential-stores read + +Command: `boundary credential-stores read` + +The `credential-stores read` command reads credential store information for a credential store with a specific ID. + +## Examples + +The following example retrieves credential store information for a credential store with the ID `csvlt_5fvkRjCjou`: + +```shell-session +$ boundary credential-stores read -id csvlt_5fvkRjCjou +``` + +**Example output:** + + + +```plaintext +Credential Store information: + Created Time: Fri, 18 Aug 2023 16:22:02 PDT + ID: csvlt_5fvkRjCjou + Type: vault + Updated Time: Fri, 18 Aug 2023 16:22:02 PDT + Version: 1 + + Scope: + ID: p_tnqESc86qE + Name: db-project + Parent Scope ID: o_4VUR6ZATqW + Type: project + + Authorized Actions: + no-op + read + update + delete + + Authorized Actions on Credential Store's Collections: + credential-libraries: + create + list + + Attributes: + Address: http://127.0.0.1:8200 + Token Status: expired + Worker Filter: "worker" in "/tags/type" +``` + + + +## Usage + + + +```shell-session +$ boundary credential-stores read [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the credential store for which to read information. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credential-stores/update.mdx b/website/content/docs/commands/credential-stores/update.mdx new file mode 100644 index 000000000..57d1d6e1a --- /dev/null +++ b/website/content/docs/commands/credential-stores/update.mdx @@ -0,0 +1,159 @@ +--- +layout: doc +page_title: credential-stores update - Command +description: |- + The "credential-stores update" command lets Boundary admin update a credential store resource. +--- + +# credential-stores update + +Command: `boundary credential-stores update` + +The `credential-stores update` command lets you update Boundary credential store resources. + +## Examples + +The following example updates an existing Vault credential store with the ID `csvlt_5fvkRjCjou` to add the description `For DevOps usage`, and the Vault namespace `devops`: + +```shell-session +$ boundary credential-stores update vault -id csvlt_5fvkRjCjou \ + -description "For DevOps usage" \ + -vault-namespace "devops" +``` + +**Example output:** + + + +```plaintext +Credential Store information: + Created Time: Fri, 18 Aug 2023 16:22:02 PDT + Description: For DevOps usage + ID: csvlt_5fvkRjCjou + Type: vault + Updated Time: Sun, 20 Aug 2023 22:21:25 PDT + Version: 2 + + Scope: + ID: p_tnqESc86qE + Name: db-project + Parent Scope ID: o_4VUR6ZATqW + Type: project + + Authorized Actions: + no-op + read + update + delete + + Authorized Actions on Credential Store's Collections: + credential-libraries: + create + list + + Attributes: + Address: http://127.0.0.1:8200 + Namespace: devops + Token Status: current + Worker Filter: "worker" in "/tags/type" +``` + + + + +## Usage + + + +```shell-session +$ boundary credential-stores update vault [options] [args] +``` + + + +### Command options + +- `-description` `(string: "")` - The description to set on the credential store. +- `-id` `(string: "")` - The ID of the credential store to update. +- `-name` `(string: "")` - The name to set on the credential store. +- `-version` `(int: 0)` - The version of the credential store against which to perform an update operation. +If you do not specify a version, the command performs a check-and-set automatically. + +#### Usages by type + +The available types are `static` and `vault`. + + + + +The `credential-stores update static` command lets you update information for a static credential store. + +#### Example + +The following example updates a static credential store with the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary credential-stores update static \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credential-stores update static [options] [args] +``` + + + + + + +The `credential-stores update vault` command lets you update a Vault credential store. + +#### Example + +The following example updates a Vault credential store with the ID `csvlt_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary credential-stores update vault \ + -id csvlt_1234567890 \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credential-stores update vault [options] [args] +``` + + + +#### Vault credential store options + +The following options are specific to Vault credential stores in addition to the command options: + +- `-vault-address` `(string: "")` - The address of the Vault server. +The address should be a complete URL such as https://127.0.0.1:8200. +- `-vault-ca-cert` `(string: "")` - The CA certificate to use when you connect to Vault. +This value can be the CA certificate itself, or it can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-vault-client-certificate` `(string: "")` - The client certificate to use when Boundary connects to Vault for this credential store. +This value can be the client certificate itself, or it can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-vault-client-certificate-key` `(string: "")` - The private key the client certificate should use when Boundary connects to Vault for this store. +This value can be the private key itself, or it can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-vault-namespace` `(string: "")` - The Vault namespace the credential store should use. +- `-vault-tls-server-name` `(string: "")` - The name to use as the SNI host when you connect using TLS. +- `-vault-tls-skip-verify` - If set, skips TLS verification. +The default value is `false`. +- `-vault-token` `(string: "")` - The Vault token to use when Boundary connects to Vault for this credential store. +- `-worker-filter` `(string: "")` - A Boolean expression to filter which workers can process Vault commands for this credential store. + + + + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credentials/create.mdx b/website/content/docs/commands/credentials/create.mdx new file mode 100644 index 000000000..41c356516 --- /dev/null +++ b/website/content/docs/commands/credentials/create.mdx @@ -0,0 +1,205 @@ +--- +layout: docs +page_title: credentials create - Command +description: |- + The "credentials create" command lets you create Boundary credential resources. +--- + +# credentials create + +Command: `boundary credentials create` + +The `credentials create` command lets you create Boundary credential resources. + +## Examples + +The following example defines a new username password credential within a static credential store with the ID `credup_J15mtU4qmy`: + +```shell-session +$ boundary credentials create username-password \ + -name ssh-user \ + -credential-store-id credup_J15mtU4qmy\ + -username ssh-user \ + -password env://SSH_USER_PASS +``` + +**Example output:** + + + +```plaintext +Credential information: + Created Time: Tue, 22 Aug 2023 15:56:07 PDT + Credential Store ID: csst_5GGWwRngd7 + ID: credup_J15mtU4qmy + Name: ssh-user + Type: username_password + Updated Time: Tue, 22 Aug 2023 15:56:07 PDT + Version: 1 + + Scope: + ID: p_1zMlAwGHtH + Name: quick-start-project + Parent Scope ID: o_R0wbo0H6Zl + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + Password HMAC: bXhHJHgaGz6fpolEpQPd0azcICSgmbVuSLfyhJhmqJY + Username: ssh-user +``` + + + + +## Usage + + + +```shell-session +$ boundary credentials create [type] [sub command] [options] [args] +``` + + + +### Command options + +- `-credential-store-id` `(string: "")` - The credential-store resource in which to create the credential. +You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_ID** environment variable. +- `-description` `(string: "")` - A description to set on the credential. +- `-name` `(string: "")` - A name to set on the credential. + +#### Usages by type + +The available types are `json`, `ssh-private-key`, and `username-password`. + + + + +The `credentials create json` command lets you create a JSON type credential. + +#### Example + +The following example creates a JSON credential in a credential store with the ID `csst_1234567890`: + +```shell-session +$ boundary credentials create json \ + -credential-store-id csst_1234567890 \ + -object file:///home/user/secret +``` +#### Usage + + + +```shell-session +$ boundary credentials create json [options] [args] +``` + + + +#### JSON object credential options + +The following options are specific to JSON credentials in addition to the command options: + +- `-bool-kv` `(map: {})` – A key=value Boolean value to add to the request's object map. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-kv` `(map: {})` – A key=value pair to add to the request's object map. +This option can also be a key value only which will set a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +Use `-string-kv`,`-bool-kv`, or `-num-kv` to override the type. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-num-kv` `(map: {})` – A key=value numeric value to add to the request's object map. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-object` `(string: "")` - A JSON map value to use as the entirety of the request's object map. +Usually this is sourced from a file using `file://` syntax. +This option is exclusive with the other kv flags. +- `-string-kv` `(map: {})` – A key=value string value to add to the request's object map. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. + + + + +The `credentials create ssh-private-key` command lets you create an SSH private key credential type. + +#### Example + +The following example creates an SSH private key credential in a credential store with the ID `csvlt_1234567890`: + +```shell-session +$ boundary credentials create ssh-private-key \ + -credential-store-id csvlt_1234567890 \ + -username user \ + -private-key file:///home/user/.ssh/id_ed25519 +``` + +#### Usage + + + +```shell-session +$ boundary credentials create ssh-private-key [options] [args] +``` + + + +#### SSH private key credential options + +The following options are specific to SSH private key credentials in addition to the command options: + +- `-private-key` `(string: "")` - The SSH private key associated with the + credential. + This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-private-key-passphrase` `(string: "")` - The passphrase associated with the + SSH private key. + Boundary ingores this value if the private key does not require a passphrase or if you do not supply a private key. + This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. + If you leave this option empty, and the key requires a passphrase, you can enter it manually. +- `-username` `(string: "")` - The username associated with the credential. + + + + +The `credentials create username-password` command lets you create a username password type credential. + +#### Example + +The following example creates a username password credential in a credential store with the ID `csvlt_1234567890`: + +```shell-session +$ boundary credentials create username-password \ + -credential-store-id csvlt_1234567890 \ + -username user -password pass +``` + +#### Usage + + + +```shell-session +$ boundary credentials create username-password -credential-store-id [options] [args] +``` + + + + +#### Username password credential options + +The following options are specific to username password credentials in addition to the command options: + +- `-password` `(string: "")` - The password associated with the credential. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-username` `(string: "")` - The username associated with the credential. + + + + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credentials/delete.mdx b/website/content/docs/commands/credentials/delete.mdx new file mode 100644 index 000000000..4eb4a477a --- /dev/null +++ b/website/content/docs/commands/credentials/delete.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: credentials delete - Command +description: |- + The "credentials delete" command lets Boundary admin delete a credential resource. +--- + +# credentials delete + +Command: `boundary credentials delete` + +The `credentials delete` command lets you delete a credential given its ID. + +## Examples + +The following example deletes a credential with the ID `credup_6zHHwQWvUS`: + +```shell-session +$ boundary credentials delete -id credup_6zHHwQWvUS +The delete operation completed successfully. +``` + +## Usage + + + +```shell-session +$ boundary credentials delete [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the credential to delete. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credentials/index.mdx b/website/content/docs/commands/credentials/index.mdx new file mode 100644 index 000000000..428bd956c --- /dev/null +++ b/website/content/docs/commands/credentials/index.mdx @@ -0,0 +1,83 @@ +--- +layout: docs +page_title: credentials - Command +description: |- + The "credentials" command lets you create and manage Boundary credential resources. +--- + +# credentials + +Command: `boundary credentials` + +The `credentials` command lets you create and manage Boundary credential resources. + +A credential is a data structure containing one or more secrets that bind an identity to a set of permissions or capabilities on a host for a session. + +## Examples + +The following example retrieves information about a credential with the ID `credup_J15mtU4qmy`: + +```shell-session +$ boundary credentials read -id credup_J15mtU4qmy +``` + +**Example output:** + + + +```plaintext +Credential information: + Created Time: Tue, 22 Aug 2023 15:56:07 PDT + Credential Store ID: csst_5GGWwRngd7 + ID: credup_J15mtU4qmy + Name: ssh-user + Type: username_password + Updated Time: Tue, 22 Aug 2023 15:56:07 PDT + Version: 1 + + Scope: + ID: p_1zMlAwGHtH + Name: quick-start-project + Parent Scope ID: o_R0wbo0H6Zl + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + Password HMAC: bXhHJHgaGz6fpolEpQPd0azcICSgmbVuSLfyhJhmqJY + Username: ssh-user +``` + + + +## Usage + + + +```shell-session +Usage: boundary credentials [sub command] [options] [args] + + # ... + +Subcommands: + create Create a credential + delete Delete a credential + list List a credential + read Read a credential + update Update a credential +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/credentials/create) +- [delete](/boundary/docs/commands/credentials/delete) +- [list](/boundary/docs/commands/credentials/list) +- [read](/boundary/docs/commands/credentials/read) +- [update](/boundary/docs/commands/credentials/update) diff --git a/website/content/docs/commands/credentials/list.mdx b/website/content/docs/commands/credentials/list.mdx new file mode 100644 index 000000000..c39ba94a2 --- /dev/null +++ b/website/content/docs/commands/credentials/list.mdx @@ -0,0 +1,81 @@ +--- +layout: docs +page_title: credentials list - Command +description: |- + The "credentials list" command lists credentials within an enclosing scope or resource. +--- + +# credentials list + +Command: `boundary credentials list` + +The `credentials list` command lists credentials within an enclosing scope or resource. + +## Examples + +The following example lists all credentials for a credential store with the ID `csst_5GGWwRngd7`: + +```shell-session +$ credentials list -credential-store-id csst_5GGWwRngd7 +``` + +**Example output:** + + + +```plaintext +Credential information: + ID: credup_29IUJANN59 + Version: 1 + Type: username_password + Name: tester + Authorized Actions: + no-op + read + update + delete + + ID: credup_6zHHwQWvUS + Version: 1 + Type: username_password + Name: support-eng + Authorized Actions: + no-op + read + update + delete + + ID: credup_J15mtU4qmy + Version: 1 + Type: username_password + Name: ssh-user + Authorized Actions: + no-op + read + update + delete +``` + + + +## Usage + + + +```shell-session +$ boundary credentials list [options] [args] +``` + + + + +### Command options + +- `-credential-store-id` `(string: "")` - The credential store resource that contains the credentials you want to list. +You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_ID** environment variable. +- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credentials/read.mdx b/website/content/docs/commands/credentials/read.mdx new file mode 100644 index 000000000..03f740b76 --- /dev/null +++ b/website/content/docs/commands/credentials/read.mdx @@ -0,0 +1,70 @@ +--- +layout: docs +page_title: credentials read - Command +description: |- + The "credentials read" command reads information for a credential given its ID. +--- + +# credentials read + +Command: `boundary credentials read` + +The `credentials read` command retrieves information about a credential with a specified ID. + +## Examples + +The following example retrieves credential information for a credential with the ID `credup_29IUJANN59`: + +```shell-session +$ boundary credentials read -id credup_29IUJANN59 +``` + +**Example output:** + + + +```plaintext +Credential information: + Created Time: Tue, 22 Aug 2023 18:26:06 PDT + Credential Store ID: csst_5GGWwRngd7 + ID: credup_29IUJANN59 + Name: tester + Type: username_password + Updated Time: Tue, 22 Aug 2023 18:26:06 PDT + Version: 1 + + Scope: + ID: p_1zMlAwGHtH + Name: quick-start-project + Parent Scope ID: o_R0wbo0H6Zl + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + Password HMAC: bXhHJHgaGz6fpolEpQPd0azcICSgmbVuSLfyhJhmqJY + Username: tester +``` + + + +## Usage + + + +```shell-session +$ boundary credentials read [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the credential for which you want to retrieve information. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/credentials/update.mdx b/website/content/docs/commands/credentials/update.mdx new file mode 100644 index 000000000..9ab27adbc --- /dev/null +++ b/website/content/docs/commands/credentials/update.mdx @@ -0,0 +1,208 @@ +--- +layout: doc +page_title: credentials update - Command +description: |- + The "credentials update" command lets Boundary admin update a credential resource. +--- + +# credentials update + +Command: `boundary credentials update` + +The `credentials update` command lets you update Boundary credential resources. + +## Examples + +The following example updates an existing user password credential with a new password: + +```shell-session +$ export NEW_SSH_USER_PASSWORD="my-new-long-password" + +$ boundary credentials update username-password -id credup_J15mtU4qmy \ + -password env://NEW_SSH_USER_PASSWORD +``` + +**Example output:** + + + +```plaintext +Credential information: + Created Time: Tue, 22 Aug 2023 15:56:07 PDT + Credential Store ID: csst_5GGWwRngd7 + Description: Ops admin who needs to access the machine + ID: credup_J15mtU4qmy + Name: ssh-user + Type: username_password + Updated Time: Tue, 22 Aug 2023 21:26:34 PDT + Version: 2 + + Scope: + ID: p_1zMlAwGHtH + Name: quick-start-project + Parent Scope ID: o_R0wbo0H6Zl + Type: project + + Authorized Actions: + no-op + read + update + delete + + Attributes: + Password HMAC: JxqSB5DJ_dBlTCJAfkX6k-o-6CwjgEDmmnbrTxvQ7_g + Username: ssh-user +``` + + + + +## Usage + + + +```shell-session +$ boundary credentials update [type] [sub command] [options] [args] +``` + + + +### Command options + +- `-description` `(string: "")` - A description to set on the credential. +- `-id` `(string: "")` - The ID of the credential to update. +- `-name` `(string: "")` - A name to set on the credential. +- `-version` `(int: 0)` - The version of the credential to update. +If you don't specify a version, the command performs a check-and-set automatically. + +#### Usages by type + +The available types are `json`, `ssh-private-key`, and `username-password`. + + + + +The `credentials update json` command lets you update a JSON credential. + +#### Example + +The following example updates a JSON credential with the ID `csst_1234567890`: + +```shell-session +$ boundary credentials update json \ + -id csst_1234567890 \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credentials update json [options] [args] +``` + + + +#### JSON object credential options + +The following options are specific to JSON credentials in addition to the command options: + +- `-bool-kv` `(map: {})` – A key=value Boolean value to add to the request's object map. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-kv` `(map: {})` – A key=value pair to add to the request's object map. +This option can also be a key value only which will set a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +Use `-string-kv`,`-bool-kv`, or `-num-kv` to override the type. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-num-kv` `(map: {})` – A key=value numeric value to add to the request's object map. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-object` `(string: "")` - A JSON map value to use as the entirety of the request's object map. +Usually this is sourced from a file using `file://` syntax. +This option is exclusive with the other kv flags. +- `-string-kv` `(map: {})` – A key=value string value to add to the request's object map. +You can specify this option multiple times. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. + + + + +The `credentials update ssh-private-key` lets you update an SSH private key credential. + +#### Example + +The following example updates an SSH private key with the ID `clvlt_1234567890`: + +```shell-session +$ boundary credentials update ssh-private-key \ + -id clvlt_1234567890 \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credentials update ssh-private-key [options] [args] +``` + + + +#### SSH private key credential options + +The following options are specific to SSH private key credentials in addition to the command options: + +- `-private-key` `(string: "")` - The SSH private key associated with the + credential. + This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-private-key-passphrase` `(string: "")` - The passphrase associated with the + SSH private key. + Boundary ingores this value if the private key does not require a passphrase or if you do not supply a private key. + This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. + If you leave this option empty, and the key requires a passphrase, you can enter it manually. +- `-username` `(string: "")` - The username associated with the credential. + + + + +The `credentials update username-password` command lets you update a username password type. + +#### Example + +The following example updates a username password credential with the ID `clvlt_1234567890`: + +```shell-session +$ boundary credentials update username-password \ + -id clvlt_1234567890 \ + -name devops \ + -description "For DevOps usage" +``` + +#### Usage + + + +```shell-session +$ boundary credentials update username-password [options] [args] +``` + + + +#### Username password credential options + +The following options are specific to username password credentials in addition to the command options: + +- `-password` `(string: "")` - The password associated with the credential. +This value can be a reference to a file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the value. +- `-username` `(string: "")` - The username associated with the credential. + + + + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/database/index.mdx b/website/content/docs/commands/database/index.mdx new file mode 100644 index 000000000..a655f3cab --- /dev/null +++ b/website/content/docs/commands/database/index.mdx @@ -0,0 +1,54 @@ +--- +layout: docs +page_title: database - Command +description: |- + The "database" command allows operations on Boundary's database. +--- + +# database + +Command: `boundary database` + +The `database` command lets you perform operations on Boundary's database. + +Boundary manages its state and configuration in a relational database management system (RDBMS), namely PostgreSQL. +You must create, set up, and make the PostgreSQL database accessible to the Boundary controller nodes before you configure the nodes themselves. + +## Examples + +The following example initializes the Boundary database: + +```shell-session +$ boundary database init \ + -skip-auth-method-creation \ + -skip-host-resources-creation \ + -skip-scopes-creation \ + -skip-target-creation \ + -config /etc/boundary.d/controller.hcl +``` + +Before you can start Boundary, you must initialize the database from one Boundary controller. +This operation is only required once. +It will execute the required database migrations for the Boundary cluster to operate. + +## Usage + + + +```shell-session +Usage: boundary database [sub command] [options] [args] + + # ... + +Subcommands: + init Initialize Boundary's database + migrate Migrate Boundary's database to the most recent schema supported by this binary. +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [init](/boundary/docs/commands/database/init) +- [migrate](/boundary/docs/commands/database/migrate) diff --git a/website/content/docs/commands/database/init.mdx b/website/content/docs/commands/database/init.mdx new file mode 100644 index 000000000..bb7ccadae --- /dev/null +++ b/website/content/docs/commands/database/init.mdx @@ -0,0 +1,128 @@ +--- +layout: docs +page_title: database init - Command +description: |- + The "database init" command initializes Boundary's database. +--- + +# database init + +Command: `boundary database init` + +The `database init` command initializes Boundary's database. + +## Examples + +The following example initializes a Boundary's database with the configuration specified in the `/etc/boundary/controller.hcl` file: + +```shell-session +$ boundary database init -config=/etc/boundary/controller.hcl +``` + +The `controller.hcl` file contains the database URL. + + + +```hcl +...snip... + +# Controller configuration block +controller { + # This name attr must be unique across all controller instances if running in HA mode + name = "boundary-controller-1" + description = "Boundary controller number one" + + # This is the public hostname or IP where the workers can reach the + # controller. This should typically be a load balancer address + public_cluster_addr = "example-cluster-lb.example.com" + + # Enterprise license file, can also be the raw value or env:// value + license = "file:///path/to/license/file.hclic" + + # After receiving a shutdown signal, Boundary will wait 10s before initiating the shutdown process. + graceful_shutdown_wait_duration = "10s" + + # Database URL for postgres. This is set in boundary.env and + #consumed via the “env://” notation. + database { + url = "env://POSTGRESQL_CONNECTION_STRING" + } +} + +...snip... +``` + + + + +## Usage + + + +```shell-session +$ boundary database init [options] [args] +``` + + + +Some initial resources are created in the following order, and in the indicated scopes: + +- Initial login role (global) +- Password-type auth method (global) +- Org scope (global) +- Project scope (org) + - Static-type host catalog (project) + - Static-type host set + - Static-type host + - Target (project) + + + +You can use flags to prevent Boundary from creating these resources. +If you use flags to skip any of these resources, any resources that would be created afterwards are also skipped. +Refer to the following [init options](#init-options) for the available flags. + + + +### Command options + +- `-config` `(string: "")` - The path to the configuration file. +- `-config-kms` `(string: "")` - The path to a configuration file containing a `kms` block marked for the `config` purpose. +The KMS block performs decryption of the main configuration file. +If you don't set a `kms` block, Boundary looks for such a block in the main configuration file, which has some drawbacks; see the help output for `boundary config encrypt -h` for details. +- `-log-format` `(string: "")` - The log format. +Supported values are `standard` and `json`. +- `-log-level` `(string: "")` - The log verbosity level. Supported values include the following in order of more detail to less: + + - `trace` + - `debug` + - `info` + - `warn` + - `err` + + You can also specify a log level using the **BOUNDARY_LOG_LEVEL** environment variable. + +### Init options: + +- `-migration-url` `(string: "")` - If set, this value overrides the migration URL set in the configuration file, and specifies the URL used to connect to the database for initialization. +Configuring this option can allow different permissions for the user running initialization vs. standard operations. +This value can refer to a direct database URL, or it can refer to file on disk (`file://`) or an environment variable (`env://`) from which Boundary reads the URL. + +- `-skip-auth-method-creation` - If not set, skips the creation of an auth method as part of initialization. +If you set this value, the recovery KMS is required to perform any actions. +The default value is `false`. + +- `-skip-host-resources-creation` - If not set, skips the creation of host resources as part of the initialization, inlcuding host catalog, host set, and hosts. +The default value is `false`. + +- `-skip-initial-login-role-creation` - If not set, skips the creation of a default role allowing necessary grants for logging in as part of initialization. +If you set this value, the recovery KMS is required to perform any actions. +The default value is `false`. + +- `-skip-scopes-creation` - If not set, skips the creation of scopes as part of initialization. +The default value is `false`. + +- `-skip-target-creation` - If not set, skips the creation of a target as part of initialization. +The default value is `false`. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/database/migrate.mdx b/website/content/docs/commands/database/migrate.mdx new file mode 100644 index 000000000..978a5d7a4 --- /dev/null +++ b/website/content/docs/commands/database/migrate.mdx @@ -0,0 +1,59 @@ +--- +layout: docs +page_title: database migrate - Command +description: |- + The "database migrate" command migrates database within an enclosing scope or resource. +--- + +# database migrate + +Command: `boundary database migrate` + +The `database migrate` command migrates the Boundary database within an enclosing scope or resource. + +## Examples + +The following example migrates Boundary's database to the database URL specified in the controller configuration file: + +```shell-session +$ boundary database migrate -config=/etc/boundary/controller.hcl +``` + +## Usage + + + +```shell-session +$ boundary database migrate [options] +``` + + + + +### Command options + +- `-config` `(string: "")` - The path to the configuration file. +- `-config-kms` `(string: "")` - The path to a configuration file containing a `kms` block marked for the `config` purpose. +The KMS block performs decryption of the main configuration file. +If you don't set a `kms` block, Boundary looks for such a block in the main configuration file, which has some drawbacks; see the help output for `boundary config encrypt -h` for details. +- `-log-format` `(string: "")` - The log format. Supported values are `standard` and `json`. +- `-log-level` `(string: "")` - The log verbosity level. Supported values include the following in order of more detail to less: + + - `trace` + - `debug` + - `info` + - `warn` + - `err` + + You can also specify a log level using the **BOUNDARY_LOG_LEVEL** environment variable. + +### Migration options: + +- `-migration-url` `(string: "")` - If set, this value overrides the migration URL set in the configuration file, and specifies the URL use to connect to the database for migration. +Configuring this option can allow different permissions for the user running initialization or migration vs. a standard operation. +This value can refer to a direct database URL, or it can refer to a file on disk (`file://`) or an environment variable (env://) from which Boundary reads the URL. +- `-repair` `(string: "")` - If set, runs the repair function for the provided migration + version. + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/dev.mdx b/website/content/docs/commands/dev.mdx new file mode 100644 index 000000000..76c572039 --- /dev/null +++ b/website/content/docs/commands/dev.mdx @@ -0,0 +1,257 @@ +--- +layout: docs +page_title: dev - Command +description: |- + The `dev` command starts a Boundary instance in a dev mode. Dev mode provides admin credentials for password authentication. +--- + +# dev + +Command: `boundary dev` + +The `dev` command starts a Boundary instance in a dev mode. Dev mode +provides admin credentials for password authentication. + +Dev mode brings up a fully functioning instance of Boundary which includes: + +- A controller server +- A worker server +- A Postgres database + +These components are ephemeral; therefore, data is not persisted. +Setting up an environment in dev mode is a convenient method for quick testing. + +## Examples + +The following example starts a Boundary instance in a dev mode: + +```shell-session +$ boundary dev +``` + +**Example output:** + + + +```plaintext +==> Boundary server configuration: + + [Bsr] AEAD Key Bytes: McoUxn6XMdaYdS8lb2bqjgvrZIaLWML0 + [Controller] AEAD Key Bytes: SA+ccZA42hj/7XRwYeq4c7OEeSoYT4Ds + [Recovery] AEAD Key Bytes: 9KJyjHcC35MPcz6VsfGczZn4KLCNXhz5 + [Worker-Auth] AEAD Key Bytes: Pgr4AbL+S6hThU6B0cyVOI7cqtoyCVrS + [Bsr] AEAD Type: aes-gcm + [Recovery] AEAD Type: aes-gcm + [Root] AEAD Type: aes-gcm + [Worker-Auth-Storage] AEAD Type: aes-gcm + [Worker-Auth] AEAD Type: aes-gcm + Cgo: disabled + Controller Public Cluster Addr: 127.0.0.1:9201 + Dev Database Container: infallible_mahavira + Dev Database Url: postgres://postgres:password@localhost:32769/boundary?sslmode=disable + Generated Admin Login Name: admin + Generated Admin Password: password + Generated Host Catalog Id: hcst_1234567890 + Generated Host Id: hst_1234567890 + Generated Host Set Id: hsst_1234567890 + Generated Ldap Auth Method Base Search DNs: users="ou=people,dc=example,dc=org" groups="ou=groups,dc=example,dc=org" + Generated Ldap Auth Method Host:Port: 127.0.0.1:64160 (does not have a root DSE; use simple bind) + Generated Ldap Auth Method Id: amldap_1234567890 + Generated Oidc Auth Method Id: amoidc_1234567890 + Generated Org Scope Id: o_1234567890 + Generated Password Auth Method Id: ampw_1234567890 + Generated Project Scope Id: p_1234567890 + Generated Target With Address Id: ttcp_1234567890 + Generated Target With Host Source Id: ttcp_0987654321 + Generated Unprivileged Login Name: user + Generated Unprivileged Password: password + Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api") + Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster") + Listener 3: tcp (addr: "127.0.0.1:9203", max_request_duration: "1m30s", purpose: "ops") + Listener 4: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy") + Log Level: info + Mlock: supported: false, enabled: false + Version: Boundary v0.13.1 + Version Sha: db01791662a7126fbf4ea0a27b23b70acd20b17b + Worker Auth Current Key Id: september-viewing-rubdown-wrench-sliceable-valid-chute-retrace + Worker Auth Storage Path: (in-memory) + Worker Public Proxy Addr: 127.0.0.1:9202 + +==> Boundary server started! Log data will stream in below: +... +``` + + + +The generated admin username is `admin` and the password is `password`. + +## Usage + + + +```shell-session +$ boundary dev [options] +``` + + + + +### Command options + + +- `-api-listen-address` `(string: "")` - The address to bind for controller "api" + purposes. If the address begins with a forward slash, Boundary assumes it is a Unix + domain socket path. You can also specify an address using the + **BOUNDARY_DEV_CONTROLLER_API_LISTEN_ADDRESS** environment variable. + +- `-audit-events` `(string: "")` - If set, indicates whether you want to emit audit events. Supported values are `true` and `false`. + +- `-bsr-key` `(string: "")` - A valid, base64-encoded AES key to be used + for session recording. You can also specify the BSR key using the **BOUNDARY_DEV_BSR_KEY** + environment variable. + +- `-cluster-listen-address` `(string: "")` - The address to bind for controller + "cluster" purposes. If the address begins with a forward slash, Boundary assumes it is a Unix domain socket path. You can also specify an address using the + **BOUNDARY_DEV_CONTROLLER_CLUSTER_LISTEN_ADDRESS** environment variable. + +- `-combine-logs` - If set, sends both startup information and logs to stdout. + If you do not set this value, startup information goes + to stdout and logs are sent to stderr. The default is `false`. + +- `-container-image` `(string: "")` - A container image to use. + This value must be in `:` format + +- `-controller-only` - If set, indicates that only a dev controller should be + started instead of both a dev controller and dev worker. The default value is `false`. + +- `-controller-public-cluster-address` `(string: "")` - The public address at which + the controller is reachable for cluster tasks, such as worker connections. + You can also specify the public address using the **BOUNDARY_DEV_CONTROLLER_PUBLIC_CLUSTER_ADDRESS** environment variable. + +- `-database-url` `(string: "")` - The URL that Boundary uses to connect to + the database for initialization, otherwise a Docker container is + started. This URL can refer to a file on disk (`file://`) from which a URL is read, an environment variable (`env://`) from which the URL is read, or a direct database URL. + +- `-disable-database-destruction` - If set, creates a database automatically in Docker. + The database is not removed when the dev server is shut down. + The default value is `false`. + +- `-event-allow-filter` `(string: "")` - An optional allow filter for every event. + You can specfiy this value multiple times. + +- `-event-deny-filter` `(string: "")` - An optional deny filter for every event. + You can specify this value multiple times. + +- `-event-format` `(string: "")` - The event format. + The following values are supported: + + - `cloudevents-json` + - `cloudevents-text` + - `hclog-json` + - `hclog-text` + +- `-host-address` `(string: "")` - The address to use for the default host that is + created. This value must be a bare host or IP address, it cannot be a port. The default value is `localhost`. You can also specify a host address using the **BOUNDARY_DEV_HOST_ADDRESS** environment variable. + +- `-id-suffix` `(string: "")` - If set, designates that auto-created resources use this + suffix value for their identifier, along with any resource-specific prefix, if set. This value must be 10 alphanumeric characters. As an example, if this is set to `1234567890`, + the generated password auth method ID is `ampw_1234567890`, the + generated TCP target ID is `ttcp_1234567890`, and so on. + + This value must be different from any `-secondary-id-suffix` or **BOUNDARY_DEV_SECONDARY_ID_SUFFIX** value. + The default is `1234567890`. You can also configure a suffix using the **BOUNDARY_DEV_ID_SUFFIX** environment variable. + +- `-log-format` `(string: "")` - The log format. Supported values are `standard` and + `json`. + +- `-log-level` `(string: "")` - The desired log verbosity level. + Supported values, in order of more detail to less, are: + + - `trace` + - `debug` + - `info` + - `warn` + - `err` + + You can also specify log verbosity level using the **BOUNDARY_LOG_LEVEL** environment variable. + +- `-login-name` `(string: "")` - The initial admin login name. If you set this value to an empty + string, Boundary autogenerates a login name. The default value is `admin`. You can also specify a login name using the **BOUNDARY_DEV_LOGIN_NAME** environment variable. + +- `-observation-events` `(string: "")` - If set, indicates whether you want Boundary to emit observation events. Supported values are `true` and `false`. + +- `-ops-listen-address` `(string: "")` - An address to bind to for "ops" purpose. + If the address begins with a forward slash, Boundary assumes it is a Unix domain + socket path. You can also specify an address using the + **BOUNDARY_DEV_OPS_LISTEN_ADDRESS** environment variable. + +- `-password` `(string: "")` - The initial admin login password. If you set this value to an empty + string, Boundary autogenerates a password. The default value is `password`. You can also specify an initial admin login password using the **BOUNDARY_DEV_PASSWORD** environment variable. + +- `-plugin-execution-dir` `(string: "")` - The directory where Boundary should write + plugins that it executes. + If you do not set a value, Boundary defaults to using the system temp directory. + You can also specify a directory using the **BOUNDARY_DEV_PLUGIN_EXECUTION_DIR** + environment variable. + +- `-proxy-listen-address` `(string: "")` - The address to bind for worker "proxy" + purposes. You can also specify an address using the + **BOUNDARY_DEV_WORKER_PROXY_LISTEN_ADDRESS** environment variable. + +- `-recovery-key` `(string: "")` - The base64'd 256-bit AES key to use + for recovery operations. You can also specify a recovery key using the + **BOUNDARY_DEV_RECOVERY_KEY** environment variable. + +- `-secondary-id-suffix` `(string: "")` - If set, indicates that secondary auto-created + resources should use the given value for their identifier, along with their + resource-specific prefix, if set. This value must be 10 alphanumeric characters. Currently it is only used for the target resource. The secondary suffix must be different from the `-id-suffix` and **BOUNDARY_DEV_ID_SUFFIX** values. The default value is `0987654321`. You can also specify a secondary suffix using the **BOUNDARY_DEV_SECONDARY_ID_SUFFIX** environment variable. + +- `-system-events` `(string: "")` - If set, indicates whether you want Boundary to emit system events. Supported values are `true` and `false`. + +- `-target-default-port` `(int: 0)` - The default port to use for the default target + that is created. The default value is `22`. You can also specify a default target port using the **BOUNDARY_DEV_TARGET_DEFAULT_PORT** environment variable. + +- `-target-session-connection-limit` `(int: 0)` - The maximum number of connections + per session to set on the default target. A value of `-1` means unlimited. The default is + `-1`. You can also specify the maximum number of connections using the + **BOUNDARY_DEV_TARGET_SESSION_CONNECTION_LIMIT** environment variable. + +- `-target-session-max-seconds` `(int: 0)` - The maximum number of seconds to use for sessions on the default target. +You can also specify the maximum number of seconds using the **BOUNDARY_DEV_TARGET_SESSION_MAX_SECONDS** environment variable. + +- `-ui-passthrough-dir` `(string: "")` - A passthrough directory in the + webserver at /. You can also specify a passthrough directory using the + **BOUNDARY_DEV_UI_PASSTHROUGH_DIR** environment variable. + +- `-unprivileged-login-name` `(string: "")` - The initial unprivileged user's name. If + you set this value to an empty string, Boundary automatically generates the user name. The default value is `user`. + You can also specify the user name using the **BOUNDARY_DEV_UNPRIVILEGED_LOGIN_NAME** + environment variable. + +- `-unprivileged-password` `(string: "")` - The initial unprivileged user login + password. If you set this value to an empty string, Boundary automatically generates the password. The default value is `password`. You can also specify the password using the + **BOUNDARY_DEV_UNPRIVILEGED_PASSWORD** environment variable. + +- `-worker-auth-enable-debugging` - If set, turns on debug logging for the + worker authentication process. The default value is `false`. + +- `-worker-auth-key` `(string: "")` - A valid, base64-encoded AES key to + use for worker-auth purposes You can also specify a key using the + **BOUNDARY_DEV_WORKER_AUTH_KEY** environment variable. + +- `-worker-auth-method` `(string: "")` - If set, lets you specify how the generated + worker authenticates to the controller. The default is `random`. + +- `-worker-auth-storage-dir` `(string: "")` - The directory in which to store + worker authentication credentials when in dev mode. If you do not set this value, Boundary uses in-memory storage or a temporary directory. + +- `-worker-auth-storage-skip-cleanup` - If set, prevents deletion of + worker credential storage directory, if set. This value has no effect unless + you specfiy a `worker-auth-storage-dir` value. The default value is `false`. + +- `-worker-public-address` `(string: "")` - The public address at which the worker + is reachable for session proxying. You can also specify an address using the + **BOUNDARY_DEV_WORKER_PUBLIC_ADDRESS** environment variable. + +- `-worker-recording-storage-dir` `(string: "")` - The directory in which to + store worker session recordings when in dev mode. If you do not specify a directory, Boundary creates a temporary directory. Session recording is only available for Boundary Enterprise and HCP Boundary. \ No newline at end of file diff --git a/website/content/docs/commands/groups/add-members.mdx b/website/content/docs/commands/groups/add-members.mdx new file mode 100644 index 000000000..67c02d945 --- /dev/null +++ b/website/content/docs/commands/groups/add-members.mdx @@ -0,0 +1,75 @@ +--- +layout: docs +page_title: groups add-members - Command +description: |- + The "groups add-members" command lets Boundary admin add members (users) to a group. +--- + +# groups add-members + +Command: `boundary groups add-members` + +The `groups add-members` command lets you add users as members of a group. + +## Examples + +The following example adds a user with ID, `u_qboadM3Q25` to the group with ID, `g_XzlDiNLgoz`: + +```shell-session +$ boundary groups add-members -id g_XzlDiNLgoz -member u_qboadM3Q25 +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 09:51:44 PDT + Description: A test group + ID: g_XzlDiNLgoz + Name: group01 + Updated Time: Thu, 24 Aug 2023 11:12:31 PDT + Version: 2 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members + + Members: + ID: u_qboadM3Q25 + Scope ID: o_R0wbo0H6Zl +``` + + + + +## Usage + + + +```shell-session +$ boundary groups add-members [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the group you want to add a member to. +- `-member` `(string: "")` - The ID of the user you want to add to the group. +You can specify the `-member` flag multiple times. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/groups/create.mdx b/website/content/docs/commands/groups/create.mdx new file mode 100644 index 000000000..e41f29c2a --- /dev/null +++ b/website/content/docs/commands/groups/create.mdx @@ -0,0 +1,75 @@ +--- +layout: docs +page_title: groups create - Command +description: |- + The "groups create" command lets Boundary admin create a group. +--- + +# groups create + +Command: `boundary groups create` + +The `groups create` command lets you create a new group. + +## Examples + +The following example creates a group, `group01` in the scope `o_R0wbo0H6Zl`: + +```shell-session +$ boundary groups create -name "group01" \ + -description "A test group" \ + -scope-id o_R0wbo0H6Zl +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 09:51:44 PDT + Description: A test group + ID: g_XzlDiNLgoz + Name: group01 + Updated Time: Thu, 24 Aug 2023 09:51:44 PDT + Version: 1 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members +``` + + + + +## Usage + + + +```shell-session +$ boundary groups create [options] [args] +``` + + + + +### Command options + +- `-description` `(string: "")` - A description to set on the new group. +- `-name` `(string: "")` - A name to set on the new group. +- `-scope-id` `(string: "")` - The scope in which to create the group. +The default value is `global`. +You can also specify a scope using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/groups/delete.mdx b/website/content/docs/commands/groups/delete.mdx new file mode 100644 index 000000000..acc1d0f3f --- /dev/null +++ b/website/content/docs/commands/groups/delete.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: groups delete - Command +description: |- + The "groups delete" command lets Boundary admin delete a group resource. +--- + +# groups delete + +Command: `boundary groups delete` + +The `groups delete` command lets you delete an existing group. + + +## Examples + +The following example deletes a group with the given ID, `g_FNVVhAd0on`. + +```shell-session +$ boundary groups delete -id g_FNVVhAd0on +The delete operation completed successfully. +``` + +## Usage + + + +```shell-session +$ boundary groups delete [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the group to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/groups/index.mdx b/website/content/docs/commands/groups/index.mdx new file mode 100644 index 000000000..2f95dc267 --- /dev/null +++ b/website/content/docs/commands/groups/index.mdx @@ -0,0 +1,92 @@ +--- +layout: docs +page_title: groups - Command +description: |- + The "groups" command lets Boundary admin create and manage group resources. +--- + +# groups + +Command: `boundary groups` + +The `groups` command lets you create and manage group resources in Boundary. + +A group in Boundary is a resource that represents a collection of users that are treated equally for the purposes of access control. +A group is a principal, which means it can be assigned to roles. +Roles assigned to a group are indirectly assigned to the users in the group, and users receive all permissions of the assigned roles. +You can define groups at the global, organization, or project scope. + +## Examples + +The following example creates a group, `group01` in a scope with the id `o_R0wbo0H6Zl`: + +```shell-session +$ boundary groups create -name "group01" \ + -description "A test group" \ + -scope-id o_R0wbo0H6Zl +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 09:51:44 PDT + Description: A test group + ID: g_XzlDiNLgoz + Name: group01 + Updated Time: Thu, 24 Aug 2023 09:51:44 PDT + Version: 1 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members +``` + + + +## Usage + + + +```shell-session +Usage: boundary groups [sub command] [options] [args] + + # ... + +Subcommands: + add-members Add members to a group + create Create a group + delete Delete a group + list List a group + read Read a group + remove-members Remove members from a group + set-members Set the full contents of the members on a group + update Update a group +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [add-members](/boundary/docs/commands/groups/add-members) +- [create](/boundary/docs/commands/groups/create) +- [delete](/boundary/docs/commands/groups/delete) +- [list](/boundary/docs/commands/groups/list) +- [read](/boundary/docs/commands/groups/read) +- [remove-members](/boundary/docs/commands/groups/remove-members) +- [set-members](/boundary/docs/commands/groups/set-members) +- [update](/boundary/docs/commands/groups/update) diff --git a/website/content/docs/commands/groups/list.mdx b/website/content/docs/commands/groups/list.mdx new file mode 100644 index 000000000..d9bebb79b --- /dev/null +++ b/website/content/docs/commands/groups/list.mdx @@ -0,0 +1,93 @@ +--- +layout: docs +page_title: groups list - Command +description: |- + The "groups list" command lets Boundary admin list groups within an enclosing scope or resource. +--- + +# groups list + +Command: `boundary groups list` + +The `groups list` command lists all groups within an enclosing scope or resource. + +## Examples + +The following example lists all groups defined within the scope `o_R0wbo0H6Zl`: + +```shell-session +$ boundary groups list -scope-id o_R0wbo0H6Zl +``` + +**Example output:** + + + +```plaintext +Group information: + ID: g_XzlDiNLgoz + Version: 2 + Name: group01 + Description: A test group + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members + + ID: g_FNVVhAd0on + Version: 1 + Name: webdev + Description: Web dev group + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members + + ID: g_9SpLKOoTse + Version: 1 + Name: support + Description: Support engineering group + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members +``` + + + +## Usage + + + +```shell-session +$ boundary groups list [options] [args] +``` + + + + +### Command options + +- `-filter` `(string: "")` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `-scope-id ``(string: "")` - The scope from which to list the groups. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/groups/read.mdx b/website/content/docs/commands/groups/read.mdx new file mode 100644 index 000000000..4573f93b0 --- /dev/null +++ b/website/content/docs/commands/groups/read.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: groups read - Command +description: |- + The "groups read" command lets Boundary admin read a group resource. +--- + +# groups read + +Command: `boundary groups read` + +The `groups read` command retrieves the group details for a given ID. + + +## Examples + +The following example retrieves the group information for a group with the ID, `g_XzlDiNLgoz`: + +```shell-session +$ boundary groups read -id g_XzlDiNLgoz +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 09:51:44 PDT + Description: A test group + ID: g_XzlDiNLgoz + Name: group01 + Updated Time: Thu, 24 Aug 2023 11:12:31 PDT + Version: 2 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members + + Members: + ID: u_qboadM3Q25 + Scope ID: o_R0wbo0H6Zl +``` + + + +## Usage + + + +```shell-session +$ boundary groups read [options] [args] +``` + + + + +### Command options + +- `-id` `(string: "")` - The ID of the group to retrieve information for. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/groups/remove-members.mdx b/website/content/docs/commands/groups/remove-members.mdx new file mode 100644 index 000000000..55c19c4ea --- /dev/null +++ b/website/content/docs/commands/groups/remove-members.mdx @@ -0,0 +1,76 @@ +--- +layout: docs +page_title: groups remove-members - Command +description: |- + The "groups remove-members" command lets Boundary admin remove members (users) from a group given its ID. +--- + +# groups remove-members + +Command: `boundary groups remove-members` + +The `groups remove-members` command removes users from a group, given its ID. + +## Examples + +The following example removes a user with the ID `u_J5l9FWB7yq` from a group with the ID `g_FNVVhAd0on`: + +```shell-session +$ boundary groups remove-members -id g_FNVVhAd0on \ + -member u_J5l9FWB7yq +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 13:58:23 PDT + Description: Web dev group + ID: g_FNVVhAd0on + Name: webdev + Updated Time: Thu, 24 Aug 2023 14:21:05 PDT + Version: 3 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members + + Members: + ID: u_ad8tbsXHJP + Scope ID: o_R0wbo0H6Zl +``` + + + +The output displays the group information. + +## Usage + + + +```shell-session +$ boundary groups remove-members [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the group from which to remove a member. +- `-member` `(string: "")` - The ID of the user to be removed from the group. +You can specify the `-member` flag multiple times. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/groups/set-members.mdx b/website/content/docs/commands/groups/set-members.mdx new file mode 100644 index 000000000..7d31784f6 --- /dev/null +++ b/website/content/docs/commands/groups/set-members.mdx @@ -0,0 +1,80 @@ +--- +layout: docs +page_title: groups set-members - Command +description: |- + The "groups set-members" command lets Boundary admin configure a complete set of members (users) on a group given its ID. +--- + +# groups set-members + +Command: `boundary groups set-members` + +The `groups set-members` command lets you configure the complete set of users in a group. + +## Examples + +The following example set users with the IDs, "`u_ad8tbsXHJP`" and "`u_J5l9FWB7yq`" as group members in a group with the group ID `g_FNVVhAd0on`: + +```shell-session +$ boundary groups set-members -id g_FNVVhAd0on \ + -member u_ad8tbsXHJP \ + -member u_J5l9FWB7yq +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 13:58:23 PDT + Description: Web dev group + ID: g_FNVVhAd0on + Name: webdev + Updated Time: Thu, 24 Aug 2023 14:12:35 PDT + Version: 2 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members + + Members: + ID: u_ad8tbsXHJP + Scope ID: o_R0wbo0H6Zl + + ID: u_J5l9FWB7yq + Scope ID: o_R0wbo0H6Z +``` + + + +The output displays the group information. + +## Usage + + + +```shell-session +$ boundary groups set-members [options] [args] +``` + + + +### Command options + +- `-id` `(string: "")` - The ID of the group on which to set members. +- `-member` `(string: "")` - The ID of the user or users you want to add to the group. +You can specify the `-member` flag multiple times. + +@include 'cmd-option-note.mdx' diff --git a/website/content/docs/commands/groups/update.mdx b/website/content/docs/commands/groups/update.mdx new file mode 100644 index 000000000..e94e831b1 --- /dev/null +++ b/website/content/docs/commands/groups/update.mdx @@ -0,0 +1,91 @@ +--- +layout: docs +page_title: groups update - Command +description: |- + The "groups update" command lets Boundary admin update a group resource. +--- + +# groups update + +Command: `boundary groups update` + +The `groups update` command lets you update an existing group's information. + +## Examples + +In this example, an existing group (`g_9SpLKOoTse`) has the following details: + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 13:58:50 PDT + Description: Support engineering group + ID: g_9SpLKOoTse + Name: support + Updated Time: Thu, 24 Aug 2023 13:58:50 PDT + Version: 3 + +...snip... +``` + + + +The following command updates the group's `description` and `version`: + +```shell-session +$ boundary groups update -id g_9SpLKOoTse \ + -description "Customer support for product XXX" \ + -version 4 +``` + +**Example output:** + + + +```plaintext +Group information: + Created Time: Thu, 24 Aug 2023 13:58:50 PDT + Description: Customer support for product XXX + ID: g_9SpLKOoTse + Name: support + Updated Time: Thu, 24 Aug 2023 14:33:18 PDT + Version: 4 + + Scope: + ID: o_R0wbo0H6Zl + Name: quick-start-org + Parent Scope ID: global + Type: org + + Authorized Actions: + no-op + read + update + delete + add-members + set-members + remove-members +``` + + + +## Usage + + + +```shell-session +$ boundary groups update [options] [args] +``` + + + +### Command options + +- `-description` `(string: "")` - The description to set on the group. +- `-id` `(string: "")` - The ID of the group to update. +- `-name` `(string: "")` - The name to set on the group. +- `-version` `(string: "")` - The version of the group to update. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/create.mdx b/website/content/docs/commands/host-catalogs/create.mdx new file mode 100644 index 000000000..06d46fce0 --- /dev/null +++ b/website/content/docs/commands/host-catalogs/create.mdx @@ -0,0 +1,152 @@ +--- +layout: docs +page_title: host-catalogs create - Command +description: |- + The "host-catalogs create" command lets you create a new host catalog. +--- + +# host-catalogs create + +Command: `host-catalogs create` + +The `host-catalogs create` command lets you create a new host catalog. + +## Example + +This example creates a static host catalog with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary host-catalogs create static -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +$ boundary host-catalogs create [type] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + plugin Create a plugin-type host catalog + static Create a static-type host catalog +``` + + + +### Usages by type + +You can create plugin or static host catalog types. + + + + +The `boundary host-catalogs create plugin` command lets you create a plugin type host catalog. + +#### Example + +This example creates a plugin type host catalog with the name `prodops` and the description `Plugin host-catalog for ProdOps`, and adds it to a scope with the ID `p_1234567890`. + +```shell-session +$ boundary host-catalogs create plugin -scope-id p_1234567890 -name prodops -description "Plugin host-catalog for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-catalogs create plugin [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the plugin host catalog. +- `-name=` - The name to set on the plugin host catalog. +- `-plugin-id=` - The ID of the plugin associated with the host catalog you want to create. +- `-plugin-name=` - The name of the plugin associated with the host catalog you want to create. +- `-scope-id=` - The scope in which you want to create the host catalog. +The default scope is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +#### Attribute options + +- `-attr` - A key=value pair to add to the request's attribute map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-attr`, `-bool-attr`, or `-num-attr`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-attributes=` - A JSON map value that you can use as the entirety of the request's attributes map. +Usually this value is sourced from a file using the `file://` syntax. +This option is exclusive with other `attr` flags. +- `-bool-attr` - A key=value Boolean value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-attr` - A key=value numeric value that you can add to the request's attributes map. +You can specify this value multiple times. +This attribute supports referencing values from files using `file://` and environment variables using `env://`. +- `-string-attr` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + +#### Secrets options + +- `-bool-secret` - A key=value Boolean value that you can add to the request's secrets map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-secret` - A key=value numeric value that you can add to the request's secrets map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-secret` - A key=value pair that you can add to the request's secrets map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-secret`, `-bool-secret`, or `-num-secret`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-secrets=` - A JSON map value that you can use as the entirety of the request's secrets map. +Usually this value is sourced from file using `file://` syntax. +This option is exclusive with other secret flags. +- `-string-secret` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + + + + + +The `boundary host-catalogs create static` command lets you create a static type host catalog. + +#### Example + +This example creates a static type host catalog with the name `prodops` and the description `Static host-catalog for ProdOps` and adds it to the scope `p_1234567890`: + +```shell-session +$ boundary host-catalogs create static -scope-id p_1234567890 -name prodops -description "Static host-catalog for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-catalogs create static [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the static host catalog. +- `-name=` - The name to set on the static host catalog. +- `-scope-id=` - The scope in which to create the static host catalog. +The default scope is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable, + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/delete.mdx b/website/content/docs/commands/host-catalogs/delete.mdx new file mode 100644 index 000000000..4cf47ff53 --- /dev/null +++ b/website/content/docs/commands/host-catalogs/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: host-catalogs delete - Command +description: |- + The "host-catalogs delete" command lets you delete a host catalog. +--- + +# host-catalogs delete + +Command: `host-catalogs delete` + +The `host-catalogs delete` command lets you delete an existing host catalog by providing the ID. + +## Example + +This example deletes a host catalog with the ID `_1234567890`: + +```shell-session +$ boundary host-catalogs delete -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary host-catalogs delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the host catalog to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/index.mdx b/website/content/docs/commands/host-catalogs/index.mdx new file mode 100644 index 000000000..c3dd569d4 --- /dev/null +++ b/website/content/docs/commands/host-catalogs/index.mdx @@ -0,0 +1,46 @@ +--- +layout: docs +page_title: host-catalogs - Command +description: |- + The "host-catalogs" command lets you perform operations on Boundary host catalog resources. +--- + +# host-catalogs + +Command: `boundary host-catalogs` + +The `host-catalogs` command lets you perform operations on Boundary host catalog resources. + +## Example + +The following example reads the information from a host catalog with the ID `hcst_1234567890`: + +```shell-session +$ boundary host-catalogs read -id hcst_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary host-catalogs [options] [args] + # ... +Subcommands: + create Create a host catalog + delete Delete a host catalog + list List a host catalog + read Read a host catalog + update Update a host catalog +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/host-catalogs/create) +- [delete](/boundary/docs/commands/host-catalogs/delete) +- [list](/boundary/docs/commands/host-catalogs/list) +- [read](/boundary/docs/commands/host-catalogs/read) +- [update](/boundary/docs/commands/host-catalogs/update) \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/list.mdx b/website/content/docs/commands/host-catalogs/list.mdx new file mode 100644 index 000000000..effd23d48 --- /dev/null +++ b/website/content/docs/commands/host-catalogs/list.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: host-catalogs list - Command +description: |- + The "host-catalogs list" command lists the host catalogs within a given scope or resource. +--- + +# host-catalogs list + +Command: `boundary host-catalogs list` + +The `boundary host-catalogs list` command lets you list the Boundary host catalogs within a given scope or resource. + +## Example + +This example lists all host catalogs in the scope `_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary host-catalogs list -scope-id _1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary host-catalogs list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +- `-scope-id=` - The scope from which you want to list host catalogs. +The default scope is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/read.mdx b/website/content/docs/commands/host-catalogs/read.mdx new file mode 100644 index 000000000..3219ff5bb --- /dev/null +++ b/website/content/docs/commands/host-catalogs/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: host-catalogs read - Command +description: |- + The "host-catalogs read" command lets you read host catalog information with a given host catalog ID. +--- + +# host-catalogs read + +Command: `boundary host-catalogs read` + +The `boundary host-catalogs read` command lets you read information about a Boundary host catalog using its given ID. + +## Example + +This example reads the details for a host catalog with the ID `_1234567890`: + +```shell-session +$ boundary host-catalogs read -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary host-catalogs read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the host catalog whose information you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/update.mdx b/website/content/docs/commands/host-catalogs/update.mdx new file mode 100644 index 000000000..5addc5dc1 --- /dev/null +++ b/website/content/docs/commands/host-catalogs/update.mdx @@ -0,0 +1,150 @@ +--- +layout: docs +page_title: host-catalogs update - Command +description: |- + The "host-catalogs update" command lets you update an existing host catalog. +--- + +# host-catalogs update + +Command: `host-catalogs update` + +The `host-catalogs update` command lets you update an existing host catalog. + +## Example + +This example updates a static host catalog with the ID `hcst_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary host-catalogs update static -id hcst_1234567890 -name devops -description "For DevOps usage" +``` + +## Usage + + + +```shell-session +$ boundary host-catalogs update [type] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + plugin Update a plugin-type host catalog + static Update a static-type host catalog +``` + + + +### Usages by type + +You can update plugin or static host set types. + + + + +The `boundary host-catalogs update plugin` command lets you update a plugin type host catalog. + +#### Example + +This example updates a plugin type host catalog with the ID `hc_1234567890` to add the name `devops` and the description `Plugin host-catalog for DevOps`. + +```shell-session +$ boundary host-catalogs update plugin -id hc_1234567890 -name "devops" -description "Plugin host-catalog for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-catalogs update plugin [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the plugin host catalog. +- `-id=` - The ID of the plugin type host catalog to update. +- `-name=` - The name to set on the plugin host catalog. +- `-version=` - The version of the plugin host catalog to update. +If you do not specify a version, the command automatically performs a check-and-set. + +#### Attribute options + +- `-attr` - A key=value pair to add to the request's attribute map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-attr`, `-bool-attr`, or `-num-attr`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-attributes=` - A JSON map value that you can use as the entirety of the request's attributes map. +Usually this value is sourced from a file using the `file://` syntax. +This option is exclusive with other `attr` flags. +- `-bool-attr` - A key=value Boolean value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-attr` - A key=value numeric value that you can add to the request's attributes map. +You can specify this value multiple times. +This attribute supports referencing values from files using `file://` and environment variables using `env://`. +- `-string-attr` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + +### Secrets options + +- `-bool-secret` - A key=value Boolean value that you can add to the request's secrets map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-secret` - A key=value numeric value that you can add to the request's secrets map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-secret` - A key=value pair that you can add to the request's secrets map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-secret`, `-bool-secret`, or `-num-secret`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-secrets=` - A JSON map value that you can use as the entirety of the request's secrets map. +Usually this value is sourced from file using `file://` syntax. +This option is exclusive with other secret flags. +- `-string-secret` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + + + + + +The `boundary host-catalogs update static` command lets you update a static type host catalog. + +#### Example + +This example updates a static type host catalog with the ID `hcst_1234567890` to add the name `devops` and the description `Static host-catalog for DevOps`: + +```shell-session +$ boundary host-catalogs update static -id hcst_1234567890 -name "devops" -description "Static host-catalog for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-catalogs update static [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the static host catalog. +- `-id=` - The ID of the static type host catalog you want to update. +- `-name=` - The name to set on the static host catalog. +- `-version=` - The version of the static type host catalog you want to update. +If you do not specify a version, the command automatically performs a check-and-set. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/add-hosts.mdx b/website/content/docs/commands/host-sets/add-hosts.mdx new file mode 100644 index 000000000..4a05541e9 --- /dev/null +++ b/website/content/docs/commands/host-sets/add-hosts.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: host-sets add-hosts - Command +description: |- + The "host-sets add-hosts" command lets you add hosts to host set resources, if the types match and the operation is allowed by the host set type. +--- + +# host-sets add-hosts + +Command: `host-sets add-hosts` + +The `host-sets add-hosts` command lets you add hosts to host sets, if the types match and it is allowed by the host set type. + +## Example + +This example adds the hosts `hst_1234567890` and `hst_0987654321` to the host set `hsst_1234567890`: + +```shell-session +$ boundary host-sets add-hosts -id hsst_1234567890 -host hst_1234567890 -host hst_0987654321 +``` + +## Usage + + + +```shell-session +$ boundary host-sets add-hosts [options] [args] +``` + + + +### Command options + +- `-host=` - The hosts you want to add to the host set. +You can specify multiple hosts. +- `-id=` - The ID of the host set you want to add hosts to. +- `-version=` The version of the host set you want to add hosts to. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/create.mdx b/website/content/docs/commands/host-sets/create.mdx new file mode 100644 index 000000000..ee50cd48f --- /dev/null +++ b/website/content/docs/commands/host-sets/create.mdx @@ -0,0 +1,141 @@ +--- +layout: docs +page_title: host-sets create - Command +description: |- + The "host-sets create" command lets you create a new host set. +--- + +# host-sets create + +Command: `host-sets create` + +The `host-sets create` command lets you create a new host set. + +## Example + +This example creates a static host set with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary host-sets create static -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +$ boundary host-sets create [type] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + plugin Create a plugin-type host set + static Create a static-type host set +``` + + + +### Usages by type + +You can create plugin or static type host sets. + + + + +The `boundary host-sets create plugin` command lets you create a plugin type host set. + +#### Example + +This example creates a plugin type host set with the name `prodops` and the description `Plugin host-set for ProdOps`, and adds it to a host catalog with the ID `hcst_1234567890`. + +```shell-session +$ boundary host-sets create plugin -host-catalog-id hcst_1234567890 -name prodops -description "Plugin host-set for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-sets create plugin [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the plugin host set. +- `-host-catalog-id=` - The host catalog resource to use for the operation. +You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. +- `-name=` - The name to set on the plugin host set. + +#### Attribute options + +- `-attr` - A key=value pair to add to the request's attribute map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-attr`, `-bool-attr`, or `-num-attr`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-attributes=` - A JSON map value that you can use as the entirety of the request's attributes map. +Usually this value is sourced from a file using the `file://` syntax. +This option is exclusive with other `attr` flags. +- `-bool-attr` - A key=value Boolean value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-attr` - A key=value numeric value that you can add to the request's attributes map. +You can specify this value multiple times. +This attribute supports referencing values from files using `file://` and environment variables using `env://`. +- `-string-attr` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + +#### Plugin host-set options + +- `-preferred-endpoint=` - If set, indicates which IP address or DNS name out of a host's available options is preferred as an endpoint. +You can specify your preference using `cidr:` or `dns:`. +You can specify multiple preferences to create an order of preferences. +If you do not specify a preference, Boundary chooses a value from all available values using a built-in priority order. +The endpoint preference option may not be valid for all plugin types. +- `-sync-interval=` - The interval of time between sync operations on the host set. +You can enter an integer number of seconds or a string such as `400s`, `5m`, or `6h`. +The interval is applied to the end of the previous sync operation, not the beginning. +If you set the interval to a negative value, it disables synchronization for that host set. +If you set the interval to null, Boundary uses the default value. +The default value may change between releases. + + + + + +The `boundary host-sets create static` command lets you create a static type host set. + +#### Example + +This example creates a static type host set with the name `prodops` and the description `Static host for ProdOps`: + +```shell-session +$ boundary host-sets create static -name prodops -description "Static host-set for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-sets create static [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the static host set. +- `-host-catalog-id=` - The host catalog resource to use for the operation. +You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. +- `-name=` - The name to set on the static host set. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/delete.mdx b/website/content/docs/commands/host-sets/delete.mdx new file mode 100644 index 000000000..29e7ab3d7 --- /dev/null +++ b/website/content/docs/commands/host-sets/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: host-sets delete - Command +description: |- + The "host-sets delete" command lets you delete a host set. +--- + +# host-sets delete + +Command: `host-sets delete` + +The `host-sets delete` command lets you delete an existing host set by providing the ID. + +## Example + +This example deletes a host set with the ID `_1234567890`: + +```shell-session +$ boundary host-sets delete -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary host-sets delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the host set you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/index.mdx b/website/content/docs/commands/host-sets/index.mdx new file mode 100644 index 000000000..f4c49ac7c --- /dev/null +++ b/website/content/docs/commands/host-sets/index.mdx @@ -0,0 +1,52 @@ +--- +layout: docs +page_title: host-sets - Command +description: |- + The "host-sets" command lets you perform operations on Boundary host set resources. +--- + +# host-sets + +Command: `boundary host-sets` + +The `host-sets` command lets you perform operations on Boundary host set resources. + +## Example + +The following command reads the details of a host set with the ID `hsst_1234567890`: + +```shell-session +$ boundary host-sets read -id hsst_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary host-sets [options] [args] + # ... +Subcommands: + add-hosts Add hosts to the specified host set + create Create a host set + delete Delete a host set + list List a host set + read Read a host set + remove-hosts Remove hosts from the specified host set + set-hosts Set the full contents of the hosts on the specified host set + update Update a host set +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [add-hosts](/boundary/docs/commands/host-sets/add-hosts) +- [create](/boundary/docs/commands/host-sets/create) +- [delete](/boundary/docs/commands/host-sets/delete) +- [list](/boundary/docs/commands/host-sets/list) +- [read](/boundary/docs/commands/host-sets/read) +- [remove-hosts](/boundary/docs/commands/host-sets/remove-hosts) +- [set-hosts](/boundary/docs/commands/host-sets/set-hosts) +- [update](/boundary/docs/commands/host-sets/update) \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/list.mdx b/website/content/docs/commands/host-sets/list.mdx new file mode 100644 index 000000000..2bf1ccabd --- /dev/null +++ b/website/content/docs/commands/host-sets/list.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: host-sets list - Command +description: |- + The "host-sets list" command lists the host sets within a given scope or resource. +--- + +# host-sets list + +Command: `boundary host-sets list` + +The `boundary host-sets list` command lets you list the Boundary host sets within a given scope or resource. + +## Example + +This example lists all host sets within the host catalog `_1234567890`: + +```shell-session +$ boundary host-sets list -host-catalog-id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary host-sets list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-host-catalog-id=` - The host catalog resource to use to produce the list. +You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/read.mdx b/website/content/docs/commands/host-sets/read.mdx new file mode 100644 index 000000000..d6669ae6c --- /dev/null +++ b/website/content/docs/commands/host-sets/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: host-sets read - Command +description: |- + The "host-sets read" command lets you read the details of a host set resource using its given ID. +--- + +# host-sets read + +Command: `boundary host-sets read` + +The `boundary host-sets read` command lets you read the details of a Boundary host set using its given ID. + +## Example + +This example reads host set details for a host set with the ID `_1234567890`: + +```shell-session +$ boundary host-sets read -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary host-sets read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the host set whose information you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/remove-hosts.mdx b/website/content/docs/commands/host-sets/remove-hosts.mdx new file mode 100644 index 000000000..46dd230b6 --- /dev/null +++ b/website/content/docs/commands/host-sets/remove-hosts.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: host-sets remove-hosts - Command +description: |- + The "host-sets remove-hosts" command lets you remove hosts from host set resources, if the types match and the operation is allowed by the host set type. +--- + +# host-sets remove-hosts + +Command: `host-sets remove-hosts` + +The `host-sets remove-hosts` command lets you remove hosts from host sets, if the types match and it is allowed by the host set type. + +## Example + +This example removes the host `hst_0987654321` from the host set `hsst_1234567890`: + +```shell-session +$ boundary host-sets remove-hosts -id hsst_1234567890 -host hst_0987654321 +``` + +## Usage + + + +```shell-session +$ boundary host-sets remove-hosts [options] [args] +``` + + + +### Command options + +- `-host=` - The hosts you want to remove from the host set. +You can specify multiple hosts. +- `-id=` - The ID of the containing host set you want to remove hosts from. +- `-version=` - The version of the host set you want to remove hosts from. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/set-hosts.mdx b/website/content/docs/commands/host-sets/set-hosts.mdx new file mode 100644 index 000000000..d8424e61c --- /dev/null +++ b/website/content/docs/commands/host-sets/set-hosts.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: host-sets set-hosts - Command +description: |- + The "host-sets set-hosts" command lets you configure the complete set of hosts on host source resources, if the types match and the operation is allowed by the host set type. +--- + +# host-sets set-hosts + +Command: `host-sets set-hosts` + +The `host-sets set-hosts` command lets you configure the complete set of hosts on a host set resource, if the types match and it is allowed by the host set type. + +## Example + +This example sets the host `hst_1234567890` on the host set `hsst_1234567890`: + +```shell-session +$ boundary host-sets set-hosts -id hsst_1234567890 -host hst_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary host-sets set-hosts [options] [args] +``` + + + +### Command options + +- `-host=` - The hosts to configure on the host set. +You can specify multiple hosts. +- `-id=` - The ID of the host set to set hosts on. +- `-version=` The version of the host set you want to set hosts on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/update.mdx b/website/content/docs/commands/host-sets/update.mdx new file mode 100644 index 000000000..470fd6c60 --- /dev/null +++ b/website/content/docs/commands/host-sets/update.mdx @@ -0,0 +1,143 @@ +--- +layout: docs +page_title: host-sets update - Command +description: |- + The "host-sets update" command lets you update an existing host set. +--- + +# host-sets update + +Command: `host-sets update` + +The `host-sets update` command lets you update an existing host set. + +## Example + +This example updates a static host set with the ID `hsst_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary host-sets update static -id hsst_1234567890 -name devops -description "For DevOps usage" +``` + +## Usage + + + +```shell-session +$ boundary host-sets update [type] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + plugin Update a plugin-type host set + static Update a static-type host set +``` + + + +### Usages by type + +You can update plugin or static host set types. + + + + +The `boundary host-sets update plugin` command lets you update a plugin type host set. + +#### Example + +This example updates a plugin type host set with the ID `hsplg_1234567890` to add the name `devops` and the description `Plugin host-set for DevOps`. + +```shell-session +$ boundary host-sets update plugin -id hsplg_1234567890 -name "devops" -description "Plugin host-set for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-sets update plugin [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the plugin host set. +- `-id=` - The ID of the plugin type host set to update. +- `-name=` - The name to set on the plugin host set. +- `-version=` - The version of the plugin host set to update. +If you do not specify a version, the command automatically performs a check-and-set. + +#### Attribute options + +- `-attr` - A key=value pair to add to the request's attribute map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-attr`, `-bool-attr`, or `-num-attr`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-attributes=` - A JSON map value that you can use as the entirety of the request's attributes map. +Usually this value is sourced from a file using the `file://` syntax. +This option is exclusive with other `attr` flags. +- `-bool-attr` - A key=value Boolean value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-attr` - A key=value numeric value that you can add to the request's attributes map. +You can specify this value multiple times. +This attribute supports referencing values from files using `file://` and environment variables using `env://`. +- `-string-attr` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + +#### Plugin host-set options + +- `-preferred-endpoint=` - If set, specifies which IP address or DNS name out of a host's available options is preferred as an endpoint. +You can specify your preference using `cidr:` or `dns:`. +You can specify multiple preferences to create an order of preferences. +If you do not specify a preference, Boundary chooses a value from all available values using a built-in priority order. +The endpoint preference option may not be valid for all plugin types. +- `-sync-interval=` - The interval of time between sync operations on the host set. +You can enter an integer number of seconds or a string such as `400s`, `5m`, or `6h`. +The interval is applied to the end of the previous sync operation, not the beginning. +If you set the interval to a negative value, it disables synchronization for that host set. +If you set the interval to null, Boundary uses the default value. +The default value may change between releases. + + + + + +The `boundary host-sets update static` command lets you update a static type host set. + +#### Example + +This example updates a static type host set with the ID `hsst_1234567890` to add the name `devops` and the description `Static host-set for DevOps`: + +```shell-session +$ boundary host-sets update static -id hsst_1234567890 -name "devops" -description "Static host-set for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary host-sets update static [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the static host set. +- `-id=` - The ID of the static type host set to update. +- `-name=` - The name to set on the static host set. +- `-version=` - The version of the static type host set to update. +If you do not specify a version, the command automatically performs a check-and-set. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/hosts/create.mdx b/website/content/docs/commands/hosts/create.mdx new file mode 100644 index 000000000..4980ac84f --- /dev/null +++ b/website/content/docs/commands/hosts/create.mdx @@ -0,0 +1,70 @@ +--- +layout: docs +page_title: hosts create - Command +description: |- + The "hosts create" command lets you create a new host. +--- + +# hosts create + +Command: `hosts create` + +The `hosts create` command lets you create a new host. + +## Example + +This example creates a static host with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary hosts create static -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +$ boundary hosts create [type] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + static Create a static type host. +``` + + + +### Usages by type + +The `boundary hosts create static` command lets you create a static type host. + +#### Example + +This example creates a static type host with the name `prodops`, the description `Static host for ProdOps`, and the address `127.0.0.1`. + +```shell-session +$ boundary hosts create static -name prodops -description "Static host for ProdOps" -address "127.0.0.1" +``` + +#### Usage + + + +```shell-session +$ boundary hosts create static [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the host. +- `-host-catalog-id=` - The host catalog resource to use for the operation. +You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. +- `-name=` - The name to set on the host. + +#### Static host options + +- `-address=` - The address of the static host. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/hosts/delete.mdx b/website/content/docs/commands/hosts/delete.mdx new file mode 100644 index 000000000..3893becfa --- /dev/null +++ b/website/content/docs/commands/hosts/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: hosts delete - Command +description: |- + The "hosts delete" command lets you delete a host. +--- + +# hosts delete + +Command: `hosts delete` + +The `hosts delete` command lets you delete an existing host by providing the ID. + +## Example + +This example deletes a host with the ID `h_1234567890`: + +```shell-session +$ boundary hosts delete -id h_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary hosts delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the host you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/hosts/index.mdx b/website/content/docs/commands/hosts/index.mdx new file mode 100644 index 000000000..12a4fcafe --- /dev/null +++ b/website/content/docs/commands/hosts/index.mdx @@ -0,0 +1,46 @@ +--- +layout: docs +page_title: hosts - Command +description: |- + The "hosts" command lets you perform operations on Boundary host resources. +--- + +# hosts + +Command: `boundary hosts` + +The `hosts` command lets you perform operations on Boundary host resources. + +## Example + +The following command reads the details of a host with the ID `hst_1234567890`: + +```shell-session +$ boundary hosts read -id hst_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary hosts [options] [args] + # ... +Subcommands: + create Create a host + delete Delete a host + list List a host + read Read a host + update Update a host +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/hosts/create) +- [delete](/boundary/docs/commands/hosts/delete) +- [list](/boundary/docs/commands/hosts/list) +- [read](/boundary/docs/commands/hosts/read) +- [update](/boundary/docs/commands/hosts/update) diff --git a/website/content/docs/commands/hosts/list.mdx b/website/content/docs/commands/hosts/list.mdx new file mode 100644 index 000000000..730f5c494 --- /dev/null +++ b/website/content/docs/commands/hosts/list.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: hosts list - Command +description: |- + The "hosts list" command lists the hosts within a given scope or resource. +--- + +# hosts list + +Command: `boundary hosts list` + +The `boundary hosts list` command lets you list the Boundary hosts within a given scope or resource. + +## Example + +This example lists all hosts within the host catalog `_1234567890`: + +```shell-session +$ boundary hosts list -host-catalog-id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary hosts list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-host-catalog-id=` - The host catalog resource to use to produce the list. +You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/hosts/read.mdx b/website/content/docs/commands/hosts/read.mdx new file mode 100644 index 000000000..5ba2c95f4 --- /dev/null +++ b/website/content/docs/commands/hosts/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: hosts read - Command +description: |- + The "hosts read" command lets you read information about a host with a given ID. +--- + +# hosts read + +Command: `boundary hosts read` + +The `boundary hosts read` command lets you read information about a Boundary host using its given ID. + +## Example + +This example reads the information about a host with the ID `h_1234567890`: + +```shell-session +$ boundary hosts read -id h_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary hosts read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the host whose information you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/hosts/update.mdx b/website/content/docs/commands/hosts/update.mdx new file mode 100644 index 000000000..56d0c1954 --- /dev/null +++ b/website/content/docs/commands/hosts/update.mdx @@ -0,0 +1,71 @@ +--- +layout: docs +page_title: hosts update - Command +description: |- + The "hosts update" command lets you update a host. +--- + +# hosts update + +Command: `hosts update` + +The `hosts update` command lets you update an existing host. + +## Example + +This example updates a host with the ID `hst_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary hosts update -id hst_1234567890 -name devops -description "For DevOps usage" +``` + +## Usage + + + +```shell-session +$ boundary hosts update [type] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + static Update a static type host. +``` + + + +### Usages by type + +The `boundary hosts update static` command lets you update a static type host. + +#### Example + +This example updates a static type host with the ID `hst_1234567890` to add the name `devops`, the description `Static host for DevOps`, and the address `10.20.30.40`. + +```shell-session +$ boundary hosts update static -id hst_1234567890 -name "devops" -description "Static host for DevOps" -address "10.20.30.40" +``` + +#### Usage + + + +```shell-session +$ boundary hosts update static [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set on the host. +- `-id=` - The ID of the host you want to update. +- `-name=` - The name to set on the host. +- `-version=` - The version of the host to update. +If you do not specify a version, the command performs a check-and-set automatically. + +#### Static host options + +- `-address=` - The address of the static host. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/index.mdx b/website/content/docs/commands/index.mdx new file mode 100644 index 000000000..b5262218f --- /dev/null +++ b/website/content/docs/commands/index.mdx @@ -0,0 +1,421 @@ +--- +layout: docs +page_title: Commands (CLI) +description: |- + Boundary's CLI behavior +--- + +# CLI + +Boundary's CLI has predictable behavior throughout its various commands. This +page details the common patterns used to help you make better use +of the CLI. + +## CLI command structure + +There are a number of command and subcommand options available. +To see all available command options, run `boundary -h`, +and to see all available subcommand options, run `boundary -h`. + +Below is the typical structure for most Boundary CLI commands: + + + +```text +boundary [options] [args] +``` + + + +- `options` - [Client](#client-options) and [connection](#connection-options) options to specify additional settings +- `args` - API arguments specific to the operation + +### Examples + +The following example shows the use of the [`-addr`](/boundary/docs/api-clients/cli#addr) flag to specify which Boundary controller to send a request to: + +```shell-session +$ boundary authenticate password \ + -addr=https://boundary.example.com:9200 \ + -auth-method-id=ampw_1234567890 +``` + +Instead of specifying the `-addr` flag for every command, you can set an environment variable `BOUNDARY_ADDR=https://boundary.controller.com:9200`. + +## Autocompletion + +Boundary's CLI supports autocompletion, which allows tab completion of commands, +flags, and in some case, the parameters to those flags. + +Run the following command to install autocompletion to the CLI: + +```shell-session +$ boundary config autocomplete install +``` + +If you want to install autocompletion manually using Bash, add the following line in a +`~/.bash_profile` or a similar file: + +```shell-session +complete -C /path/to/boundary boundary +``` + +## Keyring token storage + +Boundary uses various mechanisms, depending on platform, to allow for secure +storage of authentication tokens for later use. Each platform has a +platform-specific option. +On Windows and macOS, the platform-specific options are the defaults. +The Unix password manager [pass](https://www.passwordstore.org/) is available on all platforms. +You can also set `-keyring-type` to `none` or use the environment variable **BOUNDARY_KEYRING_TYPE** to disable storage and retrieval of the token on all platforms. + +Additionally, you can store or retrieve more than one token at once using the +`-token-name` flag or **BOUNDARY_TOKEN_NAME** environment variable. +Configuring multiple tokens lets you store tokens used by different Boundary installations, or other needs. + + + + +On Windows, Boundary uses the default Windows credential store, `wincred`. + +Available keyring types include: + +- `wincred` (default) +- `pass` +- `none` + + + + +On macOS, Boundary uses Keychain via `/usr/bin/security`. +Using this binary lets us keep the Boundary binary statically linked, which we prefer. + +Available keyring types include: + +- `keychain` (default) +- `pass` +- `none` + + + + +On all other platforms, the default is `pass`. +However, you can use an implementation of the [freedesktop.org secret service](https://specifications.freedesktop.org/secret-service/latest/) if it is available via `gnome-keyring`, `kwallet`, or other applications. + +Available keyring types include: + +- `pass` (default) +- `secret-service` +- `none` + + + + + +## Map to collections and sub-types + +Generally speaking, Boundary's CLI commands map to the collections they operate +on. For example, when you operate on roles, the command is `boundary roles ...`. + +As a result, the patterns for reading, deleting, and listing are predictable: + +- `boundary read` +- `boundary delete` +- `boundary list` + +The `read` and `delete` commands always operate on a particular resource identifier, so +they require an `-id` parameter. +The `list` command operates on collections, so it requires either a `-scope-id` parameter or, depending on the type, a higher level resource identifier, such as `-auth-method-id`. + +Creating and updating resources may require an extra parameter, if the resource type +is abstract. +An abstract resource type cannot be operated on directly, but must be operated on through an implementation. +As an example, a role is not an abstract type, and does not have various implementations. +Therefore, you can operate directly on a role as demonstrated in the following examples: + +- `boundary roles create` +- `boundary roles update`. + +However, a target can be one of many types of targets, and a concrete +implementation of a target is a `tcp` type of target. Therefore, an extra +parameter is required when you create or update a target: + +- `boundary targets create tcp` +- `boundary targets update tcp` + +This format allows the CLI to perform proper presentation and validation of parameters +and functions for the given type. + +Similar to `read`, the `update` command operates on an existing target, so it always requires +an `-id` parameter. Similar to `list`, the `create` command operates on a collection, so it always either requires a `-scope-id` parameter or a parameter that defines the parent resource. + +## Parameter handling + +All parameters specified on the CLI are specified as a Go-style flag with a +single dash, e.g. `-id`. You can specify the arguments to those flags using an +equals sign, as in `-id=r_1234567890`, or a space, like `-id r_1234567890`. + +To see the available parameters, pass the `-h` flag to any command. + +Flags are semi-position dependent. The flags must come **after** the command +definition, but are otherwise order independent. + +For example, the following commands are equivalent: + +- `boundary roles create -scope-id global -name foo` +- `boundary roles create -name foo -scope-id global` + +But the following example results in an error: + +- `boundary roles -name foo -scope-id global create` + +This structure applies to using the `-h` command as well. + +### Clear/default values + +On the CLI, you can use `null` as a value to indicate to Boundary that you want +to unset a value, and revert it to Boundary's default value. +In many cases this default value is empty, but in other cases it's not. +For example, a `name` or `description` parameter is empty by default, but a password auth method's minimum password length is not `0`, but rather `8`. + +Additionally, you are not typically allowed to set string values to the empty string `""`, since specific values must be non-empty. +You should use `null` to clear a value to ensure that you revert it to Boundary's recommended default value. + + + +Boundary uses `null` because the API is JSON. Using `null` as the +value causes the key for the parameter to be inserted into the eventual API +call's JSON object, but with the value set to the JSON `null`. This in turn +informs the controller that the value should be set to its default. Keep in +mind that this is not a direct translation to database `NULL` semantics. + + + +### Connection options + +Every command that results in an API call contains a set of flags that control +connection options, which control TLS and other settings for the connection. + +To print out all available CLI command options, run the command with `-help` or +the `-h` flag. + +```shell-session +$ boundary dev -help +``` + +- `-addr` `(string: "")` - The address of the Boundary controller, as a complete URL, for example `https://boundary.example.com:9200`. You can also specify the address + using the **BOUNDARY_ADDR** environment variable. + +- `-ca-cert` `(string: "")` - The path on the local disk to a single PEM-encoded CA + certificate that is used to verify the controller or worker's server's SSL certificate. + This value takes precedence over `-ca-path`. You can also specify the path using the **BOUNDARY_CACERT** environment variable. + +- `-ca-path` `(string: "")` - The path on the local disk to a directory of + PEM-encoded CA certificates to verify the controller's SSL certificate. + You can also specify the path using the **BOUNDARY_CAPATH** environment variable. + +- `-client-cert` `(string: "")` - The path on the local disk to a single PEM-encoded + CA certificate to use for TLS authentication to the Boundary controller. If + you specify this flag, the `-client-key` flag is also required. You can also specify the path using the **BOUNDARY_CLIENT_CERT** environment variable. + +- `-client-key` `(string: "")` - The path on the local disk to a single PEM-encoded + private key matching the client certificate from `-client-cert`. You can also specify the path using the **BOUNDARY_CLIENT_KEY** environment variable. + +- `-tls-insecure` - If set, disables verification of TLS certificates. + Using this option is highly discouraged as it decreases the security of data + transmissions to and from the Boundary server. The default is `false`. You can also disable verification of TLS certificates using the **BOUNDARY_TLS_INSECURE** environment variable. + +- `-tls-server-name` `(string: "")` - The name to use as the SNI host when + you connect to the Boundary server using TLS. You can also specify the SNI host name using the + **BOUNDARY_TLS_SERVER_NAME** environment variable. + +### Client options + +Every command that results in an API call contains a set of flags that control +client options. Some notable options include the following: + +- `-keyring-type` `(string: "")` - The type of keyring to use. The default value is + `auto`, which uses the Windows credential manager, OSX keychain, or + cross-platform password store, depending on platform. Set this value to `none` to disable + keyring functionality. Available keyring types, depending on platform, are: + + - `wincred` + - `keychain` + - `pass` + - `secret-service` + + You can also specify the keyring type using the **BOUNDARY_KEYRING_TYPE** environment variable. + +- `-output-curl-string` - If set, formats the command that + would have been run as a string using `curl` that you can use directly on the + command line. This is a great way to discover how CLI functions map to API + calls. The default is `false`. + +- `-recovery-config` `(string: "")` - If set, specifies a configuration + file that contains the information necessary to access a KMS configured to be + used for the recovery workflow within a Boundary controller. You can also specify the configuration file using the **BOUNDARY_RECOVERY_CONFIG** environment variable. + +- `-token` `(string: "")` - A URL that points to a file on disk `(file://)` or an environment variable `(env://)` from which the token is read. This value overrides the `token-name` parameter. + +- `-token-name` `(string: "")` - The name of the token. When the CLI authenticates, it stores the token + in the platform-specific OS credential store. You can use the `token-name` + parameter to store more than one token at a time. When you specify this + parameter during authentication, Boundary uses the given name as part of the key for + storage. If you specify it for any other command, Boundary uses the corresponding + token for that call. You can also specify the token name using the + **BOUNDARY_TOKEN_NAME** environment variable. + +### Output options + +Nearly every command supports having its success output be formatted as JSON via +`-format json`. For commands that result in an API call, the JSON output is +the exact output from the controller. If you use the output of the CLI in scripts +or as parameters to other tools, **always** use the formatted output. The default text +output is meant for human users, and the formatting or the information included +within that output from the original JSON may change at any time. + +Note that using `-format json` on a `boundary authenticate` command results in +Boundary not saving the token to the system password store. In this case, the +authentication information is only printed to your terminal in JSON format. +You can use the `BOUNDARY_TOKEN` environment variable or `-token` flag to +provide the token in subsequent commands. + + - `-format` `(string: "")` - The given format to print the output. Valid + formats are `table` or `json`. The default value is `table`. You can also specify the format using the `BOUNDARY_CLI_FORMAT` environment variable. + + +## Environment variables + +The CLI reads the following environment variables to set behavioral defaults. +Environment variables can alleviate the need to repetitively type a flag. Flags always take +precedence over the environment variables. + +### Connection options + +Boundary includes the following environment variables to help you configure connection options. + +### `BOUNDARY_ADDR` + +The address of the Boundary controller as a complete URL, for example `https://boundary.example.com:9200`. + +### `BOUNDARY_CACERT` + +The path on the local disk to a single PEM-encoded CA certificate to verify the controller +or worker's SSL certificate. This variable takes precedence over the `BOUNDARY_CAPATH` variable or `-ca-path` connection option, if specified. + +### `BOUNDARY_CAPATH` + +The path on the local disk to a directory of PEM-encoded CA certificates to verify the SSL +certificate of the controller. + +### `BOUNDARY_CLIENT_CERT` + +The path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication +to the Boundary controller. If you set the path, you must also specify a client key using the `BOUNDARY_CLIENT_KEY` variable or `-client-key` connection option. + +### `BOUNDARY_CLIENT_KEY` + +The path on the local disk to a single PEM-encoded private key that matches the client certificate +specified by the `BOUNDARY_CLIENT_CERT` variable or the `-client-cert` connection option. + +### `BOUNDARY_TLS_INSECURE` + +If set, disables verification of TLS certificates. Using this option is highly discouraged as it +decreases the security of data transmissions to and from the Boundary server. The default value is `false`. + +### `BOUNDARY_TLS_SERVER_NAME` + +The name to use as the SNI host when you connect to the Boundary server using TLS. + +### Client options + +Boundary includes the following environment variables to help you configure client options. + +### `BOUNDARY_KEYRING_TYPE` + +The type of keyring to use. Defaults to `auto` which uses the Windows credential manager, +OSX keychain, or cross-platform password store, depending on the platform. +Set the value to `none` to disable keyring +functionality. Available keyring types, depending on the platform, include: + +- `wincred` +- `keychain` +- `pass` +- `secret-service` + +### `BOUNDARY_RECOVERY_CONFIG` + +If set, determines if the given config file is parsed for a "kms" block with the purpose `recovery`. +If you specify a value, Boundary uses the recovery mechanism to authorize the call. + +### `BOUNDARY_TOKEN_NAME` + +The token name when stored in the system credential store. +You can specify a token name to allow switching user identities for different commands. + +### Connect options + +Boundary includes the following environment variables to help you configure connect options. + +### `BOUNDARY_CONNECT_AUTHZ_TOKEN` + +The authorization string returned from the Boundary controller when an "authorize-session" action is used against a target. +If you set the string to `-`, the command attempts to read in the authorization string from standard input. + +### `BOUNDARY_CONNECT_EXEC` + +If set, executes the given binary after connecting to the worker. +This enviornment variable should be a binary on your path or an absolute path. +If you follow any command flags with ` -- ` (space, two hyphens, space), then any arguments that follow are set directly to the binary. + +### `BOUNDARY_CONNECT_LISTEN_ADDR` + +If set, attempts to bind the listening address to the given value, which must be an IP address. +If the CLI cannot bind the address, the command produces an error. +If you don't set this value, it defaults to the most common IPv4 loopback address, 127.0.0.1. + +### `BOUNDARY_CONNECT_LISTEN_PORT` + +If set, attempts to bind the listening port to the given value, if you set this variable. +If the CLI cannot bind the address, the command produces an error. + +### `BOUNDARY_CONNECT_TARGET_SCOPE_ID` + +The target scope ID, if you authorize the session using scope parameters and target name. +This variable is mutually exclusive with `BOUNDARY_CONNECT_TARGET_SCOPE_NAME`. + +### `BOUNDARY_CONNECT_TARGET_SCOPE_NAME` + +The target scope name, if you authorize the session using scope parameters and target name. +This variable is mutually exclusive with `BOUNDARY_CONNECT_TARGET_SCOPE_ID`. + +### Command options + +Boundary includes the following environment variables to help you configure command options. + +### `BOUNDARY_AUTH_METHOD_ID` + +An auth method ID. + +### `BOUNDARY_LOG_LEVEL` + +The log verbosity level, mostly as a fallback for events. +Supported values, listed in order of more detail to less, are: + +- `trace` +- `debug` +- `info` +- `warn` +- `err` + +### `BOUNDARY_SCOPE_ID` + +The scope to use for the operation. + +### Output options + +Boundary includes the following environment variables to help you configure output options. + +### `BOUNDARY_CLI_FORMAT` + +The given format in which to print the output. Valid formats are `table` and `json`. The default value is `table`. diff --git a/website/content/docs/commands/logout.mdx b/website/content/docs/commands/logout.mdx new file mode 100644 index 000000000..9a814694d --- /dev/null +++ b/website/content/docs/commands/logout.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: logout - Command +description: |- + The `logout` command deletes the current token from Boundary and removes it from the local store. +--- + +# logout + +Command: `boundary logout` + +The `logout` command deletes the current token from Boundary and removes it from the local store. + +## Examples + +The following example logs out the current user and removes the token from the credential store: + +```shell-session +$ boundary logout +The token was successfully deleted within the Boundary controller. +The token was successfully removed from the local credential store. +``` + +## Usage + + + +```shell-session +$ boundary logout [options] +``` + + + + +### Command options + +- `-keyring-type` `(string: "")` - The type of keyring to use. + This value defaults to `auto` and uses the Windows credential manager, OSX keychain, or + cross-platform password store, depending on the platform. + Set this value to `none` to disable keyring functionality. + Depending on the platform, the following types of keyring are supported: + + - `wincred` + - `keychain` + - `pass` + - `secret-service` + + You can also specify the keyring using the **BOUNDARY_KEYRING_TYPE** environment + variable. + +- `-token-name` `(string: "")` - The name to use when Boundary loads the token from the system credential store. + If you specify a token name, it must correspond to the name you use for authentication. + You can also be specify a token name using the **BOUNDARY_TOKEN_NAME** environment variable. \ No newline at end of file diff --git a/website/content/docs/commands/managed-groups/create.mdx b/website/content/docs/commands/managed-groups/create.mdx new file mode 100644 index 000000000..fb4051b3e --- /dev/null +++ b/website/content/docs/commands/managed-groups/create.mdx @@ -0,0 +1,110 @@ +--- +layout: docs +page_title: managed-groups create - Command +description: |- + The "managed-groups create" command lets you create a new managed group. +--- + +# managed-groups create + +Command: `managed-groups create` + +The `managed-groups create` command lets you create a new managed group. + +## Example + +This example creates a managed group with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary managed-groups create -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +$ boundary managed-groups create [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + ldap Create an ldap managed group + oidc Create an oidc managed group +``` + + + +### Usages by type + +You can create LDAP or OIDC managed groups. + + + + +The `boundary managed-groups create ldap` command lets you create LDAP managed groups. + +#### Example + +This example creates a LDAP managed group using the LDAP group name `admin` and the description `Ldap managed group for ProdOps`: + +```shell-session +$ boundary managed-groups create ldap -group-names admin -description "Ldap managed group for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary managed-groups create ldap [options] [args] +``` + + + +#### Command options + +- `-auth-method-id=` - The auth-method resource to use for creating the managed group. +You can also specify the auth-method resource using the **BOUNDARY_AUTH_METHOD_ID** environment variable. +- `-description=` - The description to set for the LDAP managed group. +- `-group-names=` - The LDAP group names against which an LDAP account's associated groups are evaluated to determine membership. +Boundary evaluates managed group membership when you log in. +You can specify multiple group names. +- `-name=` - The name for the LDAP managed group. + + + + +The `boundary managed-groups create oidc` command lets you create OIDC managed groups. + +#### Example + +This example creates a OIDC managed group using a filter and the description `Oidc managed group for ProdOps`: + +```shell-session +$ boundary managed-groups create oidc -filter '"/token/email" == "doe@example.com"' -description "Oidc managed group for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary managed-groups create oidc [options] [args] +``` + + + +#### Command options + +- `-auth-method-id=` - The auth-method resource to use for creating the managed group. +You can also specify the auth-method resource using the **BOUNDARY_AUTH_METHOD_ID** environment variable. +- `-description=` - The description to set for the OIDC managed group. +- `-filter=` - The filter that defines the criteria against which an account's OIDC token and user info are evaluated to determine if it is a member of the OIDC managed group. +Boundary evaluates managed group membership when you log in. +- `-name=` - The name to set for the OIDC managed group. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/managed-groups/delete.mdx b/website/content/docs/commands/managed-groups/delete.mdx new file mode 100644 index 000000000..5d9e0ad10 --- /dev/null +++ b/website/content/docs/commands/managed-groups/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: managed-groups delete - Command +description: |- + The "managed-groups delete" command lets you delete a managed-group. +--- + +# managed-groups delete + +Command: `managed-groups delete` + +The `managed-groups delete` command lets you delete an existing managed group by providing the ID. + +## Example + +This example deletes a managed group with the ID `_1234567890`: + +```shell-session +$ boundary managed-groups delete -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary managed-groups delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the managed group you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/managed-groups/index.mdx b/website/content/docs/commands/managed-groups/index.mdx new file mode 100644 index 000000000..4043ce498 --- /dev/null +++ b/website/content/docs/commands/managed-groups/index.mdx @@ -0,0 +1,46 @@ +--- +layout: docs +page_title: managed-groups - Command +description: |- + The "managed-groups" command lets you perform operations on Boundary managed group resources. +--- + +# managed-groups + +Command: `boundary managed-groups` + +The `managed-groups` command lets you perform operations on Boundary managed group resources. + +## Example + +The following command creates a managed group with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary managed-groups create -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +Usage: boundary managed-groups [options] [args] + # ... +Subcommands: + create Create a managed group + delete Delete a managed group + list List a managed group + read Read a managed group + update Update a managed group +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/managed-groups/create) +- [delete](/boundary/docs/commands/managed-groups/delete) +- [list](/boundary/docs/commands/managed-groups/list) +- [read](/boundary/docs/commands/managed-groups/read) +- [update](/boundary/docs/commands/managed-groups/update) diff --git a/website/content/docs/commands/managed-groups/list.mdx b/website/content/docs/commands/managed-groups/list.mdx new file mode 100644 index 000000000..6020d40a4 --- /dev/null +++ b/website/content/docs/commands/managed-groups/list.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: managed-groups list - Command +description: |- + The "managed-groups list" command lists the managed groups within a given scope or resource. +--- + +# managed-groups list + +Command: `boundary managed-groups list` + +The `boundary managed-groups list` command lets you list the Boundary managed groups within a given scope or resource. + +## Example + +This example lists all managed groups within the scope `s_1234567890`: + +```shell-session +$ boundary managed-groups list -scope-id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary managed-groups list [options] [args] +``` + + + +### Command options + +- `auth-method-id=` - The auth method resource to use for this operation. +You can also specify the auth method using the **BOUNDARY_AUTH_METHOD_ID** environment variable. +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/managed-groups/read.mdx b/website/content/docs/commands/managed-groups/read.mdx new file mode 100644 index 000000000..72a6af87c --- /dev/null +++ b/website/content/docs/commands/managed-groups/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: managed-groups read - Command +description: |- + The "managed-groups read" command lets you read the details of a managed group with a given ID. +--- + +# managed-groups read + +Command: `boundary managed-groups read` + +The `boundary managed-groups read` command lets you read the details of a Boundary managed group using its given ID. + +## Example + +This example reads the details of a managed group with the ID `_1234567890`: + +```shell-session +$ boundary managed-groups read -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary managed-groups read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the managed group you want to read information for. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/managed-groups/update.mdx b/website/content/docs/commands/managed-groups/update.mdx new file mode 100644 index 000000000..7834aa1e2 --- /dev/null +++ b/website/content/docs/commands/managed-groups/update.mdx @@ -0,0 +1,112 @@ +--- +layout: docs +page_title: managed-groups update - Command +description: |- + The "managed-groups update" command lets you update an existing managed group. +--- + +# managed-groups update + +Command: `managed-groups update` + +The `managed-groups update` command lets you update an existing managed group. + +## Example + +This example updates a managed group with the ID `_1234567890` to include the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary managed-groups update -id _1234567890 -name "prodops" -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +$ boundary managed-groups update [options] [args] + +Please see the managed-groups subcommand help for detailed usage information. + +Subcommands: + ldap Update an ldap managed group + oidc Update an oidc managed group +``` + + + +### Usages by type + +You can update LDAP or OIDC managed groups. + + + + +The `boundary managed-groups update ldap` command lets you update LDAP managed groups. + +#### Example + +This example updates a LDAP managed group with the ID `acctldap_1234567890` to add the name `devops` and the description `Ldap managed group for DevOps`: + +```shell-session +$ boundary managed-groups update ldap -id acctldap_1234567890 -name "devops" -description "Ldap managed group for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary managed-groups update ldap [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set for the LDAP managed group. +- `-group-names=` - The LDAP group names against which an LDAP account's associated groups are evaluated to determine membership. +Boundary evaluates managed group membership when you log in. +You can specify multiple group names. +- `-id=` - The ID of the LDAP managed group to update. +- `-name=` - The name to set for the LDAP managed group. +- `-version=` - The version of the LDAP managed group to update. +If you do not specify a version, the command automatically performs a check-and-set. + + + + +The `boundary managed-groups update oidc` command lets you update OIDC managed groups. + +#### Example + +This example updates an OIDC managed group with the ID `acctoidc_1234567890` to add the name `devops` and the description `Oidc managed group for DevOps`: + +```shell-session +$ boundary managed-groups update oidc -id acctoidc_1234567890 -name "devops" -description "Oidc managed group for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary managed-groups update oidc [options] [args] +``` + + + +#### Command options + +- `-description=` - The description to set for the OIDC managed group. +- `-filter=` - The filter that defines the criteria against which an account's OIDC token and user info are evaluated to determine if it is a member of the OIDC managed group. +Boundary evaluates managed group membership when you log in. +- `-id=` - The ID of the OIDC managed group you want to update. +- `-name=` - The name to set for the OIDC managed group. +- `-version=` - The version of the OIDC managed group to update. +If you do not specify a version, the command performs a check-and-set automatically. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/add-grants.mdx b/website/content/docs/commands/roles/add-grants.mdx new file mode 100644 index 000000000..b622cecb6 --- /dev/null +++ b/website/content/docs/commands/roles/add-grants.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: roles add-grants - Command +description: |- + The "roles add-grants" command lets you add grants to a role. +--- + +# roles add-grants + +Command: `roles add-grants` + +The `roles add-grants` command lets you add grants to a role. +You can specify multiple grants per role. + +## Example + +This example adds a grant which permits read permissions to a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles add-grants -id r_1234567890 -grant "id=*;type=*;actions=read" +``` + +## Usage + + + +```shell-session +$ boundary roles add-grants [options] [args] +``` + + + +### Command options + +- `-grant=` - The grants you want to add. +You can specify grants in compact string format or JSON. +If you use JSON, be sure to escape it properly. +You can optionally specify multiple grants. +- `-id=` - The ID of the role you want to add grants to. +- `-version=` The version of the role to add grants to. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/add-principals.mdx b/website/content/docs/commands/roles/add-principals.mdx new file mode 100644 index 000000000..259ddf991 --- /dev/null +++ b/website/content/docs/commands/roles/add-principals.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: roles add-principals - Command +description: |- + The "roles add-principals" command lets you add principals to a role. Principals can be users or groups. +--- + +# roles add-principals + +Command: `roles add-principals` + +The `roles add-principals` command lets you add principals to a role. +Principals can be users or groups. +You can specify multiple principals per role. + +## Example + +This example adds the principals `$GROUP_ID` to a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles add-principals -id r_1234567890 -principal=$GROUP_ID +``` + +## Usage + + + +```shell-session +$ boundary roles add-principals [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the role you want to add principals to. +- `-principal=` - The principals you want to add to the role. +Principals can be users or groups. +You can optionally specify multiple principals per role. +- `-version=` The version of the role to add principals to. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/create.mdx b/website/content/docs/commands/roles/create.mdx new file mode 100644 index 000000000..f5e5b0409 --- /dev/null +++ b/website/content/docs/commands/roles/create.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: roles create - Command +description: |- + The "roles create" command lets you create a new role. +--- + +# roles create + +Command: `roles create` + +The `roles create` command lets you create a new role. + +## Example + +This example creates a role with the name `prodops` and the description `Role for ProdOps`: + +```shell-session +$ boundary roles create -name prodops -description "Role for ProdOps" +``` + +## Usage + + + +```shell-session +$ boundary roles create [options] [args] +``` + + + +### Command options + +- `-description=` - The description to assign to the role. +- `-grant-scope-id=` - The scope ID for any grants set on the role. +- `-name=` - The name to assign to the role. +- `-scope-id=` - The scope in which you want to create the role. +The default is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/delete.mdx b/website/content/docs/commands/roles/delete.mdx new file mode 100644 index 000000000..f98fb2ee2 --- /dev/null +++ b/website/content/docs/commands/roles/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: roles delete - Command +description: |- + The "roles delete" command lets you delete a role. +--- + +# roles delete + +Command: `roles delete` + +The `roles delete` command lets you delete a role. + +## Example + +This example deletes a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles delete -id r_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary roles delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the role you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/index.mdx b/website/content/docs/commands/roles/index.mdx new file mode 100644 index 000000000..b5b878d54 --- /dev/null +++ b/website/content/docs/commands/roles/index.mdx @@ -0,0 +1,58 @@ +--- +layout: docs +page_title: roles - Command +description: |- + The "roles" command lets you perform operations on Boundary role resources. +--- + +# roles + +Command: `boundary roles` + +The `roles` command lets you perform operations on Boundary role resources. + +## Example + +The following command creates a role with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary roles create -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +Usage: boundary roles [options] [args] + # ... +Subcommands: + add-grants Add grants to a role + add-principals Add principals (users, groups) to a role + create Create a role + delete Delete a role + list List a role + read Read a role + remove-grants Remove grants from a role + remove-principals Remove principals (users, groups) from a role + set-grants Set the full contents of the grants on a role + set-principals Set the full contents of the principals (users, groups) on a role + update Update a role +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [add-grants](/boundary/docs/commands/roles/add-grants) +- [add-principals](/boundary/docs/commands/roles/add-principals) +- [create](/boundary/docs/commands/roles/create) +- [delete](/boundary/docs/commands/roles/delete) +- [list](/boundary/docs/commands/roles/list) +- [read](/boundary/docs/commands/roles/read) +- [remove-grants](/boundary/docs/commands/roles/remove-grants) +- [remove-principals](/boundary/docs/commands/roles/remove-principals) +- [set-grants](/boundary/docs/commands/roles/set-grants) +- [set-principals](/boundary/docs/commands/roles/set-principals) +- [update](/boundary/docs/commands/roles/update) diff --git a/website/content/docs/commands/roles/list.mdx b/website/content/docs/commands/roles/list.mdx new file mode 100644 index 000000000..3d73a1145 --- /dev/null +++ b/website/content/docs/commands/roles/list.mdx @@ -0,0 +1,45 @@ +--- +layout: docs +page_title: roles list - Command +description: |- + The "roles list" command lists the roles within a given scope or resource. +--- + +# roles list + +Command: `boundary roles list` + +The `boundary roles list` command lets you list the Boundary roles within a given scope or resource. + +## Example + +This example lists all roles within the scope `s_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary roles list -scope-id s_1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary roles list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `-scope-id=` - The enclosing scope from which you want to list the roles. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/read.mdx b/website/content/docs/commands/roles/read.mdx new file mode 100644 index 000000000..c7f28183d --- /dev/null +++ b/website/content/docs/commands/roles/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: roles read - Command +description: |- + The "roles read" command lets you read the information about a role with a given ID. +--- + +# roles read + +Command: `boundary roles read` + +The `boundary roles read` command lets you read the information about a Boundary role using its given ID. + +## Example + +This example reads the details of a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles read -id r_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary roles read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the role you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/remove-grants.mdx b/website/content/docs/commands/roles/remove-grants.mdx new file mode 100644 index 000000000..b966d140d --- /dev/null +++ b/website/content/docs/commands/roles/remove-grants.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: roles remove-grants - Command +description: |- + The "roles remove-grants" command lets you remove grants from a role. +--- + +# roles remove-grants + +Command: `roles remove-grants` + +The `roles remove-grants` command lets you remove grants from a role. +You can specify multiple grants per role. + +## Example + +This example removes a grant which permits read permissions from a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles remove-grants -id r_1234567890 -grant "id=*;type=*;actions=read" +``` + +## Usage + + + +```shell-session +$ boundary roles remove-grants [options] [args] +``` + + + +### Command options + +- `-grant=` - The grants you want to remove from the role. +You can specify grants in compact string format or JSON. +If you use JSON, be sure to escape it properly. +You can optionally specify multiple grants. +- `-id=` - The ID of the role you want to remove grants from. +- `-version=` - The version of the role you want to remove grants from. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/remove-principals.mdx b/website/content/docs/commands/roles/remove-principals.mdx new file mode 100644 index 000000000..566f5f124 --- /dev/null +++ b/website/content/docs/commands/roles/remove-principals.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: roles remove-principals - Command +description: |- + The "roles remove-principals" command lets you remove principals from a role. Principals can be users or groups. +--- + +# roles remove-principals + +Command: `roles remove-principals` + +The `roles remove-principals` command lets you remove principals from a role. +Principals can be users or groups. +You can specify multiple principals per role. + +## Example + +This example removes the principals `sg_1234567890` from a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles remove-principals -id r_1234567890 -principal sg_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary roles remove-principals [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the role you want to remove principals from. +- `-principal=` - The principals you want to remove from the role. +Principals can be users or groups. +You can optionally specify multiple principals per role. +- `-version=` The version of the role to remove principals from. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/set-grants.mdx b/website/content/docs/commands/roles/set-grants.mdx new file mode 100644 index 000000000..8a7905007 --- /dev/null +++ b/website/content/docs/commands/roles/set-grants.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: roles set-grants - Command +description: |- + The "roles set-grants" command lets you set the complete set of grants on a role. +--- + +# roles set-grants + +Command: `roles set-grants` + +The `roles set-grants` command lets you set the complete set of grants on a role. +You can specify multiple grants per role. + +## Example + +This example sets multiple grants which allow read and list permissions for a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles set-grants -id r_1234567890 -grant "id=*;type=*;actions=read" -grant + "id=*;type=*;actions=list" +``` + +## Usage + + + +```shell-session +$ boundary roles set-grants [options] [args] +``` + + + +### Command options + +- `-grant=` - The grants you want to set on the role. +You can specify grants in compact string format or JSON. +If you use JSON, be sure to escape it properly. +You can optionally specify multiple grants. +- `-id=` - The ID of the role you want to set grants on. +- `-version=` The version of the role to set grants on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/set-principals.mdx b/website/content/docs/commands/roles/set-principals.mdx new file mode 100644 index 000000000..056077100 --- /dev/null +++ b/website/content/docs/commands/roles/set-principals.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: roles set-principals - Command +description: |- + The "roles set-principals" command lets you set the complete set of principals on a role. Principals can be users or groups. +--- + +# roles set-principals + +Command: `roles set-principals` + +The `roles set-principals` command lets you set the complete set of principals on a role. +Principals can be users or groups. +You can specify multiple principals per role. + +## Example + +This example sets the principals `u_anon` and `sg_1234567890` on a role with the ID `r_1234567890`: + +```shell-session +$ boundary roles set-principals -id r_1234567890 -principal u_anon -principal sg_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary roles set-principals [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the role you want to set principals on. +- `-principal=` - The principals you want to set on the role. +Principals can be users or groups. +You can optionally specify multiple principals per role. +- `-version=` The version of the role to set principals on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/update.mdx b/website/content/docs/commands/roles/update.mdx new file mode 100644 index 000000000..0a906be84 --- /dev/null +++ b/website/content/docs/commands/roles/update.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: roles update - Command +description: |- + The "roles update" command lets you update an existing role. +--- + +# roles update + +Command: `roles update` + +The `roles update` command lets you update an existing role. + +## Example + +This example updates a role with the ID `r_1234567890` to add the name `devops` and the description `Role for DevOps`: + +```shell-session +$ boundary roles update -id r_1234567890 -name "devops" -description "Role for DevOps" +``` + +## Usage + + + +```shell-session +$ boundary roles update [options] [args] +``` + + + +### Command options + +- `-description=` - The description to set on the role. +- `-grant-scope-id=` - The scope ID for any grants set on the role. +- `-id=` - The ID of the role you want to update. +- `-name=` - The name to set on the role. +- `-version=` - The version of the role you want to update. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/create.mdx b/website/content/docs/commands/scopes/create.mdx new file mode 100644 index 000000000..a3f42eca6 --- /dev/null +++ b/website/content/docs/commands/scopes/create.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: scopes create - Command +description: |- + The "scopes create" command lets you create a new scope. +--- + +# scopes create + +Command: `scopes create` + +The `scopes create` command lets you create a new scope. + +## Example + +This example creates a scope with the name `prodops` and the description `Scope for ProdOps`: + +```shell-session +$ boundary scopes create -name prodops -description "Scope for ProdOps" +``` + +## Usage + + + +```shell-session +$ boundary scopes create [options] [args] +``` + + + +### Command options + +- `-description=` - The description to set on the scope. +- `-name=` - The name to set on the scope. +- `-scope-id=` - The scope in which you want to create the scope. +The default is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. +- `-skip-admin-role-creation` - If set, Boundary does not create a role that grants the current user administrative access to the newly created scope. +The default value is `false`. +- `-skip-default-role-creation` - If set, Boundary does not create a role that grants the anonymous user access to log in to auth methods and other actions within the newly created scope. +The default value is `false`. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/delete.mdx b/website/content/docs/commands/scopes/delete.mdx new file mode 100644 index 000000000..303b0ed6d --- /dev/null +++ b/website/content/docs/commands/scopes/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: scopes delete - Command +description: |- + The "scopes delete" command lets you delete a scope. +--- + +# scopes delete + +Command: `scopes delete` + +The `scopes delete` command lets you delete an existing scope by providing the ID. + +## Example + +This example deletes a scope with the ID `o_1234567890`: + +```shell-session +$ boundary scopes delete -id o_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary scopes delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the scope you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/destroy-key-version.mdx b/website/content/docs/commands/scopes/destroy-key-version.mdx new file mode 100644 index 000000000..be4f87b83 --- /dev/null +++ b/website/content/docs/commands/scopes/destroy-key-version.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: scopes destroy-key-version - Command +description: |- + The "scopes destroy-key-version" destroys a key version in the scope. +--- + +# scopes destroy-key-version + +Command: `scopes destroy-key-version` + +The `scopes destroy-key-version` command lets you destroy a key version in the scope. +You cannot destroy the key version that is currently active. +When you run this command, it may start an asynchronous job to re-encrypt any existing data that was encrypted with the key version that you destroy. +You can check the progress of the key destruction job using the [`boundary scopes list-key-version-destruction-jobs`](/boundary/docs/commands/scopes/list-key-version-destruction-jobs) command. + +## Example + +This example destroys a key version with the ID `krkv_123456789` in the scope `global`: + +```shell-session +$ boundary scopes destroy-key-version -scope-id global -key-version-id krkv_123456789 +``` + +## Usage + + + +```shell-session +$ boundary scopes destroy-key-version [args] +``` + + + +### Command options + +- `-key-version-id=` - The ID of the key version you want to destroy. +- `-scope-id=` - The ID of the scope in which the key version you want to destroy exists. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/index.mdx b/website/content/docs/commands/scopes/index.mdx new file mode 100644 index 000000000..c0db33db1 --- /dev/null +++ b/website/content/docs/commands/scopes/index.mdx @@ -0,0 +1,54 @@ +--- +layout: docs +page_title: scopes - Command +description: |- + The "scopes" command lets you perform operations on Boundary scope resources. +--- + +# scopes + +Command: `boundary scopes` + +The `scopes` command lets you perform operations on Boundary scope resources. + +## Example + +The following command creates a scope with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary scopes create -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +Usage: boundary scopes [options] [args] + # ... +Subcommands: + create Create a scope + delete Delete a scope + destroy-key-version Destroy a key version within a scope + list List a scope + list-key-version-destruction-jobs List all pending key version destruction jobs within a scope + list-keys List keys within a scope + read Read a scope + rotate-keys Rotate the keys within a scope + update Update a scope +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/scopes/create) +- [delete](/boundary/docs/commands/scopes/delete) +- [destroy-key-version](/boundary/docs/commands/scopes/destroy-key-version) +- [list](/boundary/docs/commands/scopes/list) +- [list-key-version-destruction-jobs](/boundary/docs/commands/scopes/list-key-version-destruction-jobs) +- [list-keys](/boundary/docs/commands/scopes/list-keys) +- [read](/boundary/docs/commands/scopes/read) +- [rotate-keys](/boundary/docs/commands/scopes/rotate-keys) +- [update](/boundary/docs/commands//scopes/update) \ No newline at end of file diff --git a/website/content/docs/commands/scopes/list-key-version-destruction-jobs.mdx b/website/content/docs/commands/scopes/list-key-version-destruction-jobs.mdx new file mode 100644 index 000000000..0473cface --- /dev/null +++ b/website/content/docs/commands/scopes/list-key-version-destruction-jobs.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: scopes list-key-version-destruction-jobs - Command +description: |- + The "scopes list-key-version-destruction-jobs" lists all pending key version destruction jobs within a scope. +--- + +# scopes list-key-version-destruction-jobs + +Command: `scopes list-key-version-destruction-jobs` + +When the [key version destruction job](/boundary/docs/commands/scopes/destroy-key-version) runs, it asynchronously re-encrypts any existing data within the latest key version before it destroys the key version you selected for destruction. +The `scopes list-key-version-destruction jobs` command lists all pending key version destruction jobs within a scope. + +## Example + +This example lists all pending key version destruction jobs within the scope `global`: + +```shell-session +$ boundary scopes list-key-version-destruction-jobs -scope-id global +``` + +## Usage + + + +```shell-session +$ boundary scopes list-key-version-destruction-jobs [args] +``` + + + +### Command options + +- `-scope-id=` - The ID of the scope from which to list key version destruction jobs. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/list-keys.mdx b/website/content/docs/commands/scopes/list-keys.mdx new file mode 100644 index 000000000..e13d3a6df --- /dev/null +++ b/website/content/docs/commands/scopes/list-keys.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: scopes list-keys - Command +description: |- + The "scopes list-keys" command lists the keys within a given scope or resource. +--- + +# scopes list-keys + +Command: `boundary scopes list-keys` + +The `boundary scopes list-keys` command lets you list the keys within a given scope or resource. + +## Example + +This example lists all keys within the scope `s_1234567890`: + +```shell-session +$ boundary scopes list-keys -scope-id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary scopes list-keys [args] +``` + + + +### Command options + +- `-scope-id=` - The ID of the enclosing scope from which to list the keys. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/list.mdx b/website/content/docs/commands/scopes/list.mdx new file mode 100644 index 000000000..f0d4165ff --- /dev/null +++ b/website/content/docs/commands/scopes/list.mdx @@ -0,0 +1,45 @@ +--- +layout: docs +page_title: scopes list - Command +description: |- + The "scopes list" command lists the scopes within a given scope or resource. +--- + +# scopes list + +Command: `boundary scopes list` + +The `boundary scopes list` command lets you list the Boundary scopes within a given scope or resource. + +## Example + +This example lists all scopes within the scope `s_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary scopes list -scope-id s_1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary scopes list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `-scope-id=` - The enclosing scope from which to list the scopes. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/read.mdx b/website/content/docs/commands/scopes/read.mdx new file mode 100644 index 000000000..0d06f7a25 --- /dev/null +++ b/website/content/docs/commands/scopes/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: scopes read - Command +description: |- + The "scopes read" command lets you read the details about a scope using its given ID. +--- + +# scopes read + +Command: `boundary scopes read` + +The `boundary scopes read` command lets you read the details about a Boundary scope using its given ID. + +## Example + +This example reads the details about a scope with the ID `o_1234567890`: + +```shell-session +$ boundary scopes read -id o_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary scopes read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the scope you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/rotate-keys.mdx b/website/content/docs/commands/scopes/rotate-keys.mdx new file mode 100644 index 000000000..426a68b7f --- /dev/null +++ b/website/content/docs/commands/scopes/rotate-keys.mdx @@ -0,0 +1,38 @@ +--- +layout: docs +page_title: scopes rotate-keys - Command +description: |- + The "scopes rotate-keys" command deactivates a scope's current KEK and DEKs, and activates a new set of keys for the scope. +--- + +# scopes rotate-keys + +Command: `boundary scopes rotate-keys` + +The `boundary scopes rotate-keys` command lets you replace a scope's current KEK and DEKs with a new set of keys. + +## Example + +This example rotates all keys within the scope `s_1234567890`: + +```shell-session +$ boundary scopes rotate-keys -scope-id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary scopes rotate-keys [args] +``` + + + +### Command options + +- `-rewrap` - If set, re-encrypts DEKs with the new KEK. +The default value is `false`. +- `-scope-id=` - The enclosing scope in which you want to rotate the keys. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/update.mdx b/website/content/docs/commands/scopes/update.mdx new file mode 100644 index 000000000..f413b2fd8 --- /dev/null +++ b/website/content/docs/commands/scopes/update.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: scopes update - Command +description: |- + The "scopes update" command lets you update an existing scope. +--- + +# scopes update + +Command: `scopes update` + +The `scopes update` command lets you update an existing scope. + +## Example + +This example updates a scope with the ID `o_1234567890` to include the name `devops` and the description `Scope for DevOps`: + +```shell-session +$ boundary scopes update -id o_1234567890 -name "devops" -description "Scope for DevOps" +``` + +## Usage + + + +```shell-session +$ boundary scopes update [options] [args] +``` + + + +### Command options + +- `-description=` - The description to set on the scope. +- `-id=` - The ID of the scope to update. +- `-name=` - The name to set on the scope. +- `-primary-auth-method-id=` - The primary auth method ID for the scope. +The primary auth method is allowed to create users on the initial login. +It is also used as a source for the account full name and email used for the scope's users. +- `-version=` - The version of the scope to update. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/server.mdx b/website/content/docs/commands/server.mdx new file mode 100644 index 000000000..e56910f5d --- /dev/null +++ b/website/content/docs/commands/server.mdx @@ -0,0 +1,84 @@ +--- +layout: docs +page_title: server - Command +description: |- + The `server` command starts a server (controller, worker, or both) with a configuration file. +--- + +# server + +Command: `boundary server` + +The `server` command starts a server with a configuration file. +You can use it to start a controller, worker, or both. +Refer to the [configuration](/boundary/docs/configuration) page to learn more about configuring Boundary. + +## Examples + +The following example starts the worker server by providing the full path to the worker config file, `/home/ubuntu/boundary/downstream-worker.hcl`: + +```shell-session +$ boundary server -config="/home/ubuntu/boundary/downstream-worker.hcl" +``` + +**Example output:** + + + +```shell-session +==> Boundary server configuration: + + Cgo: disabled + Listener 1: tcp (addr: "0.0.0.0:9202", max_request_duration: "1m30s", purpose: "proxy") + Log Level: info + Mlock: supported: true, enabled: false + Version: Boundary v0.13.0+ent + Version Sha: d8aaf3500f65fb7d605d27db232457fe3a26bf43 + Worker Auth Current Key Id: harddisk-stunt-serve-shininess-essay-courier-manger-deface + Worker Auth Registration Request: GzusqckarbczHoLGQ4UA25uSRvw33DNChURoR2CF1BXRUm7frqLSncV64LeYWxQDCstE25Vj6QSBQ1aGh8BUo1dnz899rt3LgktzRGU4vWYcHmvPQKpsSUTJqA42nJxBfpxopKyCvzxZNxgbTSw5BNN9BUsnoy58niY5ui38NhKPKdmKjVDoU4TRVd4Bvti4F2H5C8pBB3qhY6qyeaSRoKjDcEzdTa7S3JicVzbtmfWnfyMLTJ21jRypH2S5haK4RBhFP319mw6DYNhVo7opBkBoW2FaaJbeowGj8b5wFX + Worker Auth Storage Path: /home/ubuntu/boundary/worker2 + Worker Public Proxy Addr: 44.204.92.85:9202 + +==> Boundary server started! Log data will stream in below: +... +``` + + + + +## Usage + + + +```shell-session +$ boundary server -config=/etc/boundary/controller.hcl +``` + + + + +### Command options + +- `-config` `(string: "")` - The path to the configuration file. +If you use HCL formatting, you can specify multiple configuration files. + +- `-config-kms` `(string: "")` - The path to a configuration file that contains a "kms" + block marked for `config` purpose. + The kms block decrypts the main configuration file. + If you do not set a kms block, Boundary looks for the kms block in the main + configuration file, which has some drawbacks; see the help output for + "boundary config encrypt -h" for details. + +- `-log-format` `(string: "")` - The log format to use, mostly as a fallback for events. + Supported values are `standard` and `json`. + +- `-log-level` `(string: "")` - The log verbosity level to use, mostly as a fallback for + events. The following values are supported, in order of more detail to less. + + - `trace` + - `debug` + - `info` + - `warn` + - `err` + + You can also be specify log verbosity level using the **BOUNDARY_LOG_LEVEL** environment variable. \ No newline at end of file diff --git a/website/content/docs/commands/session-recordings/download.mdx b/website/content/docs/commands/session-recordings/download.mdx new file mode 100644 index 000000000..96567fbc6 --- /dev/null +++ b/website/content/docs/commands/session-recordings/download.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: session-recordings download - Command +description: |- + The "session-recordings download" command lets you download Boundary session recording resources. +--- + +# session-recordings download + +Command: `boundary session-recordings download` + +The `boundary session-recordings download` command lets you download a Boundary session recording. + +## Example + +The following command downloads a session recording with the id `chr_1234567890`: + +```shell-session +$ boundary session-recordings download -id chr_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary session-recordings download [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the session recording resource you want to download. +- `-no-clobber` - If set, prevents downloads from overwriting existing files. +This option is aliased as `-nc`. +The default value is `false`. +- `-output=` - If set, indicates an optional output file for the download. +If you do not provide a value, the recording ID is given a ".cast" extension. +Use `-` for stdout. +This option is aliased as `-o`. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/session-recordings/index.mdx b/website/content/docs/commands/session-recordings/index.mdx new file mode 100644 index 000000000..1775243cd --- /dev/null +++ b/website/content/docs/commands/session-recordings/index.mdx @@ -0,0 +1,42 @@ +--- +layout: docs +page_title: session-recordings - Command +description: |- + The "session-recordings" command lets you perform operations on Boundary session recording resources. +--- + +# session-recordings + +Command: `boundary session-recordings` + +The `session-recordings` command lets you perform operations on Boundary session recording resources. + +## Example + +The following command downloads a session recording with the id `chr_1234567890`: + +```shell-session +$ boundary session-recordings download -id chr_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary session-recordings [options] [args] + # ... +Subcommands: + download Download a session recording + list List a session recording + read Read a session recording +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [download](/boundary/docs/commands/session-recordings/download) +- [list](/boundary/docs/commands/session-recordings/list) +- [read](/boundary/docs/commands/session-recordings/read) \ No newline at end of file diff --git a/website/content/docs/commands/session-recordings/list.mdx b/website/content/docs/commands/session-recordings/list.mdx new file mode 100644 index 000000000..53a7b378e --- /dev/null +++ b/website/content/docs/commands/session-recordings/list.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: session-recordings list - Command +description: |- + The "session-recordings list" command lists the session recordings within a given scope or resource. +--- + +# session-recordings list + +Command: `boundary session-recordings list` + +The `boundary session-recordings list` command lets you list the Boundary session recordings within a given scope or resource. + +## Example + +This example lists all session recordings within the scope `s_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary session-recordings list -scope-id s_1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary session-recordings list [options] [args] +``` + + + +### Command options + +- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `scope-id=` - The scope from which you want to list the session recordings. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/session-recordings/read.mdx b/website/content/docs/commands/session-recordings/read.mdx new file mode 100644 index 000000000..708974a19 --- /dev/null +++ b/website/content/docs/commands/session-recordings/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: session-recordings read - Command +description: |- + The "session-recordings read" command lets you read information about Boundary session recordings by ID. +--- + +# session-recordings read + +Command: `boundary session-recordings read` + +The `boundary session-recordings read` command lets you read information about a Boundary session recording by providing the ID. + +## Example + +This example reads the details of a session recording with the ID `s_1234567890`: + +```shell-session +$ boundary session-recordings read -id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary session-recordings read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the session recording you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/sessions/cancel.mdx b/website/content/docs/commands/sessions/cancel.mdx new file mode 100644 index 000000000..d99653f67 --- /dev/null +++ b/website/content/docs/commands/sessions/cancel.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: sessions cancel - Command +description: |- + The "sessions cancel" command lets you cancel Boundary sessions by ID. +--- + +# sessions cancel + +Command: `boundary sessions cancel` + +The `boundary sessions cancel` command lets you cancel a Boundary session by providing the ID. +If the session is already canceled, the command succeeds with no effect. + +## Example + +This example cancels a session with the ID `s_1234567890`: + +```shell-session +$ boundary sessions cancel -id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary sessions cancel [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the session you want to cancel. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/sessions/index.mdx b/website/content/docs/commands/sessions/index.mdx new file mode 100644 index 000000000..41b5b5780 --- /dev/null +++ b/website/content/docs/commands/sessions/index.mdx @@ -0,0 +1,42 @@ +--- +layout: docs +page_title: sessions - Command +description: |- + The "sessions" command lets you perform operations on Boundary session resources. +--- + +# sessions + +Command: `boundary sessions` + +The `sessions` command lets you perform operations on Boundary session resources. + +## Example + +The following command reads the details of a session with the id `s_1234567890`: + +```shell-session +$ boundary sessions read -id s_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary sessions [options] [args] + # ... +Subcommands: + cancel Cancel a session + list List a session + read Read a session +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [cancel](/boundary/docs/commands/sessions/cancel) +- [list](/boundary/docs/commands/sessions/list) +- [read](/boundary/docs/commands/sessions/read) \ No newline at end of file diff --git a/website/content/docs/commands/sessions/list.mdx b/website/content/docs/commands/sessions/list.mdx new file mode 100644 index 000000000..6b00bb2b8 --- /dev/null +++ b/website/content/docs/commands/sessions/list.mdx @@ -0,0 +1,47 @@ +--- +layout: docs +page_title: sessions list - Command +description: |- + The "sessions list" command lists the sessions within a given scope or resource. +--- + +# sessions list + +Command: `boundary sessions list` + +The `boundary sessions list` command lets you list the Boundary sessions within a given scope or resource. + +## Example + +This example lists all sessions within the scope `s_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary sessions list -scope-id s_1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary sessions list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-include-terminated` - If set, Boundary includes terminated sessions in the `list` results. +The default value is `false`. +- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `scope-id=` - The scope from which to list sessions. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/sessions/read.mdx b/website/content/docs/commands/sessions/read.mdx new file mode 100644 index 000000000..f5cc6a36a --- /dev/null +++ b/website/content/docs/commands/sessions/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: sessions read - Command +description: |- + The "sessions read" command lets you read information about Boundary sessions by ID. +--- + +# sessions read + +Command: `boundary sessions read` + +The `boundary sessions read` command lets you read information a Boundary session by providing the ID. + +## Example + +This example reads the details of a session with the ID `s_1234567890`: + +```shell-session +$ boundary sessions read -id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary sessions read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the session you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/create.mdx b/website/content/docs/commands/storage-buckets/create.mdx new file mode 100644 index 000000000..1d81ed867 --- /dev/null +++ b/website/content/docs/commands/storage-buckets/create.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: storage-buckets create - Command +description: |- + The "storage-buckets create" command lets you create Boundary storage buckets. +--- + +# storage-buckets create + +Command: `boundary storage-buckets create` + +The `boundary storage-buckets create` command lets you create Boundary storage buckets. +Storage buckets are Boundary resources that represent storage resources in an external store. + +## Example + +This example creates a storage bucket with the name `prodops` and the description `storage bucket for ProdOps`: + +```shell-session +$ boundary storage-buckets create -name prodops -description "storage bucket for ProdOps" +``` + +## Usage + + + +```shell-session +$ boundary storage-buckets create [options] [args] +``` + + + +### Command options + +- `-bucket-name=` - The name of the storage bucket in the external store. +- `-bucket-prefix==` - An optional prefix to set on the storage bucket. +- `-worker-filter=` - A Boolean expression to filter which workers can process communication to this storage bucket. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/delete.mdx b/website/content/docs/commands/storage-buckets/delete.mdx new file mode 100644 index 000000000..26210d7d7 --- /dev/null +++ b/website/content/docs/commands/storage-buckets/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: storage-buckets delete - Command +description: |- + The "storage-buckets delete" command lets you delete Boundary storage buckets. +--- + +# storage-buckets delete + +Command: `boundary storage-buckets delete` + +The `boundary storage-buckets delete` command lets you delete Boundary storage buckets. + +## Example + +This example deletes a storage bucket with the ID `_1234567890`: + +```shell-session +$ boundary storage-buckets delete -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary storage-buckets delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the storage bucket you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/index.mdx b/website/content/docs/commands/storage-buckets/index.mdx new file mode 100644 index 000000000..155de5ef0 --- /dev/null +++ b/website/content/docs/commands/storage-buckets/index.mdx @@ -0,0 +1,46 @@ +--- +layout: docs +page_title: storage-buckets - Command +description: |- + The "storage-buckets" command lets you perform operations on Boundary storage bucket resources. +--- + +# storage-buckets + +Command: `boundary storage-buckets` + +The `storage-buckets` command lets you perform operations on Boundary storage bucket resources. + +## Example + +The following command reads the details of a storage bucket with the id `sb_1234567890`: + +```shell-session +$ boundary storage-buckets read -id sb_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary storage-buckets [options] [args] + # ... +Subcommands: + create Create a storage bucket + delete Delete a storage bucket + list List a storage bucket + read Read a storage bucket + update Update a storage bucket +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [create](/boundary/docs/commands/storage-buckets/create) +- [delete](/boundary/docs/commands/storage-buckets/delete) +- [list](/boundary/docs/commands/storage-buckets/list) +- [read](/boundary/docs/commands/storage-buckets/read) +- [update](/boundary/docs/commands/storage-buckets/update) \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/list.mdx b/website/content/docs/commands/storage-buckets/list.mdx new file mode 100644 index 000000000..758ea8d6a --- /dev/null +++ b/website/content/docs/commands/storage-buckets/list.mdx @@ -0,0 +1,45 @@ +--- +layout: docs +page_title: storage-buckets list - Command +description: |- + The "storage-buckets list" command lists the storage buckets within a given scope or resource. +--- + +# storage-buckets list + +Command: `storage-buckets list` + +The `storage-buckets list` command lets you list the storage buckets within a given scope or resource. + +## Example + +This example lists all storage buckets within the scope `s_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary storage-buckets list -scope-id s_1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary storage-buckets list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `scope-id=` - The scope from which to list storage buckets. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/read.mdx b/website/content/docs/commands/storage-buckets/read.mdx new file mode 100644 index 000000000..21c8f404e --- /dev/null +++ b/website/content/docs/commands/storage-buckets/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: storage-buckets read - Command +description: |- + The "storage-buckets read" command lets you read information about Boundary storage buckets. +--- + +# storage-buckets read + +Command: `boundary storage-buckets read` + +The `boundary storage-buckets read` command lets you read information about Boundary storage buckets. + +## Example + +This example reads the details of a storage bucket with the ID `_1234567890`: + +```shell-session +$ boundary storage-buckets read -id _1234567890 +``` + +## Usage + + + +```shell-session +$ boundary storage-buckets read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the storage bucket you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/update.mdx b/website/content/docs/commands/storage-buckets/update.mdx new file mode 100644 index 000000000..f112fee62 --- /dev/null +++ b/website/content/docs/commands/storage-buckets/update.mdx @@ -0,0 +1,86 @@ +--- +layout: docs +page_title: storage-buckets update - Command +description: |- + The "storage-buckets update" command lets you update Boundary storage buckets. +--- + +# storage-buckets update + +Command: `boundary storage-buckets update` + +The `boundary storage-buckets update` command lets you update Boundary storage buckets by ID. + +## Example + +This example updates a storage bucket with the ID `_1234567890` to add the name `devops` and the description `storage bucket for DevOps`: + +```shell-session +$ boundary storage-buckets update -id _1234567890 -name devops -description "storage bucket for DevOps" +``` + +## Usage + + + +```shell-session +$ boundary storage-buckets update [options] [args] +``` + + + +### Command options + +- `-description=` - The description to set for the storage bucket. +- `-id=` - The ID of the storage bucket you want to update. +- `-name=` - The name to set for the storage bucket. +- `-version=` - The version of the storage bucket against which to perform the update operation. +If you do not specify a version, the command performs a check-and-set operation automatically. + +### Attribute options + +- `-attr` - A key=value pair to add to the request's attribute map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-attr`, `-bool-attr`, or `-num-attr`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-attributes=` - A JSON map value that you can use as the entirety of the request's attributes map. +Usually this value is sourced from a file using the `file://` syntax. +This option is exclusive with other `attr` flags. +- `-bool-attr` - A key=value Boolean value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-attr` - A key=value numeric value that you can add to the request's attributes map. +You can specify this value multiple times. +This attribute supports referencing values from files using `file://` and environment variables using `env://`. +- `-string-attr` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + +### Secrets options + +- `-bool-secret` - A key=value Boolean value that you can add to the request's secrets map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-num-secret` - A key=value numeric value that you can add to the request's secrets map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-secret` - A key=value pair that you can add to the request's secrets map. +This option can also be a key value only, which sets a JSON null as the value. +If you provide a value, Boundary automatically infers the type. +You can override the type using `-string-secret`, `-bool-secret`, or `-num-secret`. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. +- `-secrets=` - A JSON map value that you can use as the entirety of the request's secrets map. +Usually this value is sourced from file using `file://` syntax. +This option is exclusive with other secret flags. +- `-string-secret` - A key=value string value that you can add to the request's attributes map. +You can specify this value multiple times. +This option supports referencing values from files using `file://` and environment variables using `env://`. + +### Storage bucket options + +- `-worker-filter=` - A Boolean expression that you can use to filter which workers can process communication to the storage bucket. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/add-credential-sources.mdx b/website/content/docs/commands/targets/add-credential-sources.mdx new file mode 100644 index 000000000..d19f878fe --- /dev/null +++ b/website/content/docs/commands/targets/add-credential-sources.mdx @@ -0,0 +1,46 @@ +--- +layout: docs +page_title: targets add-credential-sources - Command +description: |- + The "targets add-credential-sources" lets you add credential sources to target resources. +--- + +# targets add-credential-sources + +Command: `targets add-credential-sources` + +The `targets add-credential-sources` command lets you add credential sources to target resources. + +## Example + +This example adds the brokered credential sources `clvlt_1234567890` and `clvlt_0987654321` to a TCP target with the ID `ttcp_1234567890`: + +```shell-session +$ boundary targets add-credential-sources -id ttcp_1234567890 -brokered-credential-source clvlt_1234567890 -brokered-credential-source clvlt_0987654321 +``` + +## Usage + + + +```shell-session +$ boundary targets add-credential-sources [options] [args] +``` + + + +### Command options + +- `-application-credential-source=` - This option is deprecated. +Use `-brokered-credential-source` instead. +- `-brokered-credential-source=` - The credential source you want to add. +Boundary returns the credential source to the user when it creates a connection. +You can specify multiple credential sources. +- `-id=` - The ID of the target you want to add the credential source to. +- `-injected-application-credential-source=` - The credential source you want to add. +Boundary injects the credential source when it creates a connection. +You can specify multiple credential sources. +- `-version=` - The version of the target to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/add-host-sources.mdx b/website/content/docs/commands/targets/add-host-sources.mdx new file mode 100644 index 000000000..175ca1edb --- /dev/null +++ b/website/content/docs/commands/targets/add-host-sources.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: targets add-host-sources - Command +description: |- + The "targets add-host-sources" lets you add host sources to target resources. +--- + +# targets add-host-sources + +Command: `targets add-host-sources` + +The `targets add-host-sources` command lets you add host sources to target resources. + +## Example + +This example adds the host sources `hsst_1234567890` and `hsst_0987654321` to a TCP target with the ID `ttcp_1234567890`: + +```shell-session +$ boundary targets add-host-sources -id ttcp_1234567890 -host-source hsst_1234567890 -host-source hsst_0987654321 +``` + +## Usage + + + +```shell-session +$ boundary targets add-host-sources [options] [args] +``` + + + +### Command options + +- `-host-source=` - The host source you want to add. +You may specify multiple host sources. +- `-id=` - The ID of the target you want to add a host source to. +- `-version=` - The version of the target to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/authorize-session.mdx b/website/content/docs/commands/targets/authorize-session.mdx new file mode 100644 index 000000000..33a914d85 --- /dev/null +++ b/website/content/docs/commands/targets/authorize-session.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: targets authorize-session - Command +description: |- + The "targets authorize-session" lets you fetch session authorization credentials for a target. +--- + +# targets authorize-session + +Command: `targets authorize-session` + +The `targets authorize-session` command lets you fetch session authorization credentials for a target so that you can start a session later. + +## Examples + +This example fetches authorization credentials for a target with the ID `ttcp_wtXnow8Krb` and a specific host with the ID `hst_DHei2VpkBH`: + +```shell-session +$ boundary targets authorize-session -id=ttcp_wtXnow8Krb -host-id=hst_DHei2VpkBH +``` + +You can also request an authorized session using the scope ID and target name. +This example requests authorization credentials using the scope ID `o_1234567890` and the target name `prod-ssh`: + +```shell-session +$ boundary targets authorize-session -scope-id o_1234567890 -name prod-ssh +``` + +## Usage + + + +```shell-session +$ boundary targets authorize-session [options] [args] +``` + + + +### Command options + +- `-host-id=` - The ID of a host from the target's host sets. +If you specify a host, Boundary uses that specific host for the connection. +If you do not specify a host, Boundary chooses one at random. +- `-id=` - The ID of the target you want to authorize a session for. +- `-name=` - The name of the target you want to fetch credentials for, if you want to authorize the session using scope parameters and target name. +- `-scope-id=` - The scope ID of the target you want to fetch credentials for, if you want to authorize the session using scope parameters and target name. +Alternatively, you can specify a scope ID using the **BOUNDARY_SCOPE_ID** environment variable. +You cannot specify a scope ID if you specify a `-scope-name`. +- `-scope-name=` - The scope name of the target you want to fetch credentials for, if you want to authorize the session using scope parameters and target name. +Alternatively, you can specify a scope name using the **BOUNDARY_SCOPE_NAME** environment variable. +You cannot specify a scope name if you specify a `-scope-id`. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/create.mdx b/website/content/docs/commands/targets/create.mdx new file mode 100644 index 000000000..56168ce30 --- /dev/null +++ b/website/content/docs/commands/targets/create.mdx @@ -0,0 +1,122 @@ +--- +layout: docs +page_title: targets create - Command +description: |- + The "targets create" command lets you create a new target. +--- + +# targets create + +Command: `targets create` + +The `targets create` command lets you create a new target. + +## Example + +This example creates a TCP target with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary targets create tcp -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +$ boundary targets create [type] [sub command] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + ssh Create a ssh-type target (HCP only) + tcp Create a tcp-type target +``` + + + +### Usages by type + +You can create SSH or TCP targets. + + + + +The `targets create ssh` command lets you create SSH targets. + +#### Example + +This example creates an SSH target with the name `prodops` and the description `SSH target for ProdOps`: + +```shell-session +$ boundary targets create ssh -name prodops -description "SSH target for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary targets create ssh [options] [args] +``` + + + +#### SSH target options + +- `-address=` - An optional valid network address for the target to connect to. +You cannot use an address alongside host sources. +- `-default-client-port=` - The default client port on the target. +- `-default-port=` - The default port on the target. +If you do not specify a default port, Boundary uses port 22. +- `-egress-worker-filter=` - A Boolean expression that filters which egress workers can process sessions for the target. +- `-enable-session-recording=` - A Boolean expression you can use to enable session recording for the target. +- `-ingress-worker-filter=` - A Boolean expression that filters which ingress workers can process sessions for the target. +- `-session-connection-limit=` - The maximum number of connections allowed for a session. +A value of `-1` means the connections are unlimited. +- `-session-max-seconds=` - The maximum lifetime of the session, including all connections. +You can specify an integer number of seconds or a duration string. +- `-storage-bucket-id=` - The public ID of the storage bucket to associate with the target. + + + + + +The `targets create tcp` command lets you create TCP targets. + +#### Example + +This example creates a TCP target with the name `prodops` and the description `TCP target for ProdOps`: + +```shell-session +$ boundary targets create tcp -name prodops -description "TCP target for ProdOps" +``` + +#### Usage + + + +```shell-session +$ boundary targets create tcp [options] [args] +``` + + + +#### TCP target options + +- `-address=` - An optional valid network address for the target to connect to. +You cannot use an address alongside host sources. +- `-default-client-port=` - The default client port on the target. +- `-default-port=` - The default port on the target. +If you do not specify a default port, Boundary uses port 22. +- `-egress-worker-filter=` - A Boolean expression that filters which egress workers can process sessions for the target. +- `-ingress-worker-filter=` - A Boolean expression that filters which ingress workers can process sessions for the target. +- `-session-connection-limit=` - The maximum number of connections allowed for a session. +A value of `-1` means the connections are unlimited. +- `-session-max-seconds=` - The maximum lifetime of the session, including all connections. +You can specify an integer number of seconds or a duration string. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/delete.mdx b/website/content/docs/commands/targets/delete.mdx new file mode 100644 index 000000000..4ba0806c3 --- /dev/null +++ b/website/content/docs/commands/targets/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: targets delete - Command +description: |- + The "targets delete" command lets you delete a target. +--- + +# targets delete + +Command: `targets delete` + +The `targets delete` command lets you delete a target. + +## Example + +This example deletes a target with the ID `t_1234567890`: + +```shell-session +$ boundary targets delete -id t_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary targets delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the target you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/index.mdx b/website/content/docs/commands/targets/index.mdx new file mode 100644 index 000000000..9b2d37ac5 --- /dev/null +++ b/website/content/docs/commands/targets/index.mdx @@ -0,0 +1,62 @@ +--- +layout: docs +page_title: targets - Command +description: |- + The "targets" command performs operations on Boundary target resources. +--- + +# targets + +Command: `boundary targets` + +The `targets` command lets you perform operations on Boundary target resources. + +## Example + +The following command updates the description for a target with the ID `ttcp_1234567890`: + +```shell-session + $ boundary targets update -id ttcp_1234567890 -description "updated postgres target" +``` + +## Usage + + + +```shell-session +boundary targets [sub command] [options] [args] + + # ... + +Subcommands: + add-credential-sources Add credential sources to a target + add-host-sources Add host sources to a target + authorize-session Request session authorization against the target + create Create a target + delete Delete a target + list List a target + read Read a target + remove-credential-sources Remove credential sources from a target + remove-host-sources Remove host sources from a target + set-credential-sources Set the full contents of the credential sources on a target + set-host-sources Set the full contents of the host sources on a target + update Update a target +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [add-credential-sources](/boundary/docs/commands/targets/add-credential-sources) +- [add-host-sources](/boundary/docs/commands/targets/add-host-sources) +- [authorize-session](/boundary/docs/commands/targets/authorize-session) +- [create](/boundary/docs/commands/targets/create) +- [delete](/boundary/docs/commands/targets/delete) +- [list](/boundary/docs/commands/targets/list) +- [read](/boundary/docs/commands/targets/read) +- [remove-credential-sources](/boundary/docs/commands/targets/remove-credential-sources) +- [remove-host-sources](/boundary/docs/commands/targets/remove-host-sources) +- [set-credential-sources](/boundary/docs/commands/targets/set-credential-sources) +- [set-host-sources](/boundary/docs/commands/targets/set-host-sources) +- [update](/boundary/docs/commands/targets/update) \ No newline at end of file diff --git a/website/content/docs/commands/targets/list.mdx b/website/content/docs/commands/targets/list.mdx new file mode 100644 index 000000000..42b99d080 --- /dev/null +++ b/website/content/docs/commands/targets/list.mdx @@ -0,0 +1,45 @@ +--- +layout: docs +page_title: targets list - Command +description: |- + The "targets list" command lists the targets within a given scope or resource. +--- + +# targets list + +Command: `targets list` + +The `targets list` command lets you list the targets within a given scope or resource. + +## Example + +This example lists all targets within the scope `s_1234567890`. +The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable: + +```shell-session +$ boundary targets list -scope-id s_1234567890 -recursive +``` + +## Usage + + + +```shell-session +$ boundary targets list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `scope-id=` - The scope from which to list the targets. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/read.mdx b/website/content/docs/commands/targets/read.mdx new file mode 100644 index 000000000..ebe3ac155 --- /dev/null +++ b/website/content/docs/commands/targets/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: targets read - Command +description: |- + The "targets read" command reads a target with a given ID. +--- + +# targets read + +Command: `targets read` + +The `targets read` command lets you read the details of a target with a given ID. + +## Example + +This example reads the details of a target with the ID `t_1234567890`: + +```shell-session +$ boundary targets read -id t_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary targets read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the target you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/remove-credential-sources.mdx b/website/content/docs/commands/targets/remove-credential-sources.mdx new file mode 100644 index 000000000..96f9dc4b2 --- /dev/null +++ b/website/content/docs/commands/targets/remove-credential-sources.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: targets remove-credential-sources - Command +description: |- + The "targets remove-credential-sources" lets you remove credential sources from target resources. +--- + +# targets remove-credential-sources + +Command: `targets remove-credential-sources` + +The `targets remove-credential-sources` command lets you remove credential sources from target resources. + +## Example + +This example removes the brokered credential sources `clvlt_1234567890` and `clvlt_0987654321` from a TCP target with the ID `ttcp_1234567890`: + +```shell-session +$ boundary targets remove-credential-sources -id ttcp_1234567890 -brokered-credential-source clvlt_1234567890 -brokered-credential-source clvlt_0987654321 +``` + +## Usage + + + +```shell-session +$ boundary targets remove-credential-sources [options] [args] +``` + + + +### Command options + +- `-application-credential-source=` - This option is deprecated. +Use `-brokered-credential-source` instead. +- `-brokered-credential-source=` - The credential source you want to remove. +You may specify multiple credential sources. +- `-id=` - The ID of the target you want to remove the credential source from. +- `-injected-application-credential-source=` - The credential source you want to remove. +You may specify multiple credential sources. +- `-version=` - The version of the target to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/remove-host-sources.mdx b/website/content/docs/commands/targets/remove-host-sources.mdx new file mode 100644 index 000000000..cf298962c --- /dev/null +++ b/website/content/docs/commands/targets/remove-host-sources.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: targets remove-host-sources - Command +description: |- + The "targets remove-host-sources" lets you remove host sources from target resources. +--- + +# targets remove-host-sources + +Command: `targets remove-host-sources` + +The `targets remove-host-sources` command lets you remove host sources from target resources. + +## Example + +This example removes the host sources `hsst_1234567890` and `hsst_0987654321` from a target with the ID `ttcp_1234567890`: + +```shell-session +$ boundary targets remove-host-sources -id ttcp_1234567890 -host-source hsst_1234567890 -host-source hsst_0987654321 +``` + +## Usage + + + +```shell-session +$ boundary target remove-host-sources [options] [args] +``` + + + +### Command options + +- `-host-source=` - The host source you want to remove. +You may specify multiple host sources. +- `-id=` - The ID of the target you want to remove a host source from. +- `-version=` - The version of the target to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/set-credential-sources.mdx b/website/content/docs/commands/targets/set-credential-sources.mdx new file mode 100644 index 000000000..e58c0cd36 --- /dev/null +++ b/website/content/docs/commands/targets/set-credential-sources.mdx @@ -0,0 +1,47 @@ +--- +layout: docs +page_title: targets set-credential-sources - Command +description: |- + The "targets set-credential-sources" lets you set credential sources on target resources. +--- + +# targets set-credential-sources + +Command: `targets set-credential-sources` + +The `targets set-credential-sources` command lets you set credential sources on target resources. + +## Example + +This example sets a brokered credential source `clvlt_1234567890` on a target with the ID `ttcp_1234567890`: + +```shell-session +$ boundary targets set-credential-sources -id ttcp_1234567890 -brokered-credential-source clvlt_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary targets set-credential-sources [options] [args] +``` + + + +### Command options + +- `-application-credential-source=` - This option is deprecated. +Use `-brokered-credential-source` instead. + +- `-brokered-credential-source=` - The brokered credential source you want to set on the target. +Boundary returns the credential source to the user when it creates a connection. +You may specify multiple credential sources. +- `-id=` - The ID of the target you want to set the credential source on. +- `-injected-application-credential-source=` - The injected credential source you want to set on the target. +Boundary injects the credential source when it creates a connection. +You may specify multiple credential sources. +- `-version=` - The version of the target to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/set-host-sources.mdx b/website/content/docs/commands/targets/set-host-sources.mdx new file mode 100644 index 000000000..58d0fbbea --- /dev/null +++ b/website/content/docs/commands/targets/set-host-sources.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: targets set-host-sources - Command +description: |- + The "targets set-host-sources" lets you set host sources on target resources. +--- + +# targets set-host-sources + +Command: `targets set-host-sources` + +The `targets set-host-sources` command lets you set host sources on target resources. + +## Example + +This example sets the host source `hsst_1234567890` on a target with the ID `ttcp_1234567890`: + +```shell-session +$ boundary targets set-host-sources -id ttcp_1234567890 -host-source hsst_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary targets set-host-sources [options] [args] +``` + + + +### Command options + +- `-host-source=` - The host source you want to set on the target. +You may specify multiple host sources. +- `-id=` - The ID of the target you want to set a host source on. +- `-version=` - The version of the target to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/update.mdx b/website/content/docs/commands/targets/update.mdx new file mode 100644 index 000000000..9e22d8bc1 --- /dev/null +++ b/website/content/docs/commands/targets/update.mdx @@ -0,0 +1,124 @@ +--- +layout: docs +page_title: targets update - Command +description: |- + The "targets update" command lets you update a target. +--- + +# targets update + +Command: `targets update` + +The `targets update` command lets you update a target. + +## Example + +This example updates a TCP target with the ID `ttcp_1234567890` to add the name `devops` and the description `For DevOps usage`: + +```shell-session +$ boundary targets update tcp -id ttcp_1234567890 -name devops -description "For DevOps usage" +``` + +## Usage + + + +```shell-session +$ boundary targets update [type] [sub command] [options] [args] + +Please see the typed subcommand help for detailed usage information. + +Subcommands: + ssh Update a ssh-type target (HCP only) + tcp Update a tcp-type target +``` + + + +### Usages by type + +You can update SSH or TCP targets. + + + + +The `targets update ssh` command lets you update SSH targets. + +#### Example + +This example updates an SSH target with the ID `tssh_1234567890` to add the name `devops` and the description `SSH target for DevOps`: + +```shell-session +$ boundary targets update ssh -id tssh_1234567890 -name "devops" -description "SSH target for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary targets update ssh [options] [args] +``` + + + +#### SSH target options + +- `-address=` - An optional valid network address for the target to connect to. +You cannot use an address alongside host sources. +- `-default-client-port=` - The default client port on the target, if set. +- `-default-port=` - The default port on the target, if set. +If you do not specify a default port, Boundary uses port 22. +- `-egress-worker-filter=` - A Boolean expression that filters which egress workers can process sessions for the target. +- `-enable-session-recording=` - A Boolean expression you can use to enable session recording for the target. +- `-ingress-worker-filter=` - A Boolean expression that filters which ingress workers can process sessions for the target. +- `-session-connection-limit=` - The maximum number of connections allowed for a session. +A value of `-1` means the connections are unlimited. +- `-session-max-seconds=` - The maximum lifetime of the session, including all connections. +You can specify an integer number of seconds or a duration string. +- `-storage-bucket-id=` - The public ID of the storage bucket you want to associate with the target. + + + + + +The `targets update tcp` command lets you update TCP targets. + +#### Example + +This example updates a TCP target with the ID `ttcp_1234567890` to add the name `devops` and the description `TCP target for DevOps`: + +```shell-session +$ boundary targets update tcp -id ttcp_1234567890 -name "devops" -description "TCP target for DevOps" +``` + +#### Usage + + + +```shell-session +$ boundary targets update tcp [options] [args] +``` + + + +#### TCP target options + +- `-address=` - An optional valid network address for the target to connect to. +You cannot use an address alongside host sources. +- `-default-client-port=` - The default client port on the target, if set. +- `-default-port=` - The default port on the target, if set. +If you do not specify a default port, Boundary uses port 22. +- `-egress-worker-filter=` - A Boolean expression that filters which egress workers can process sessions for the target. +- `-ingress-worker-filter=` - A Boolean expression that filters which ingress workers can process sessions for the target. +- `-session-connection-limit=` - The maximum number of connections allowed for a session. +A value of `-1` means the connections are unlimited. +- `-session-max-seconds=` - The maximum lifetime of the session, including all connections. +You can specify an integer number of seconds or a duration string. +- `-worker-filter=` - This option is deprecated. +Use the egress or ingress filters instead. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/add-accounts.mdx b/website/content/docs/commands/users/add-accounts.mdx new file mode 100644 index 000000000..0e6bb816d --- /dev/null +++ b/website/content/docs/commands/users/add-accounts.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: users add-accounts - Command +description: |- + The "users add-accounts" command associates accounts with a user. +--- + +# users add-accounts + +Command: `users add-accounts` + +The `users add-accounts` command lets you associate accounts with a user. + +## Example + +This example associates a user `u_1234567890` with an account `a_1234567890`: + +```shell-session +$ boundary users add-accounts -id u_1234567890 -account a_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary users add-accounts [options] [args] +``` + + + +### Command options + +- `-account=` - The account you want to associate with the user. +You can add multiple accounts. +- `-id=` - The ID of the user you want to associate an account with. +- `-version=` - The version of the user to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/create.mdx b/website/content/docs/commands/users/create.mdx new file mode 100644 index 000000000..194144718 --- /dev/null +++ b/website/content/docs/commands/users/create.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: users create - Command +description: |- + The "users create" command lets you create a new user. +--- + +# users create + +Command: `users create` + +The `users create` command lets you create a new user. + +## Example + +This example creates a user `prodops` with the description `User for ProdOps`: + +```shell-session +$ boundary users create -name prodops -description "User for ProdOps" +``` + +## Usage + + + +```shell-session +$ boundary users create [options] [args] +``` + + + +### Command options + +- `-description=` - The description to assign the user. +- `-name=` - The name to assign to the user. +- `-scope-id=` - The scope you want to create the user in. +The default is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/delete.mdx b/website/content/docs/commands/users/delete.mdx new file mode 100644 index 000000000..2243ee681 --- /dev/null +++ b/website/content/docs/commands/users/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: users delete - Command +description: |- + The "users delete" command lets you delete a user. +--- + +# users delete + +Command: `users delete` + +The `users delete` command lets you delete a user. + +## Example + +This example deletes a user with the id `u_1234567890`: + +```shell-session +$ boundary users delete -id u_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary users delete [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the user you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/index.mdx b/website/content/docs/commands/users/index.mdx new file mode 100644 index 000000000..e7d7f44fa --- /dev/null +++ b/website/content/docs/commands/users/index.mdx @@ -0,0 +1,54 @@ +--- +layout: docs +page_title: users - Command +description: |- + The "users" command performs operations on Boundary user resources. +--- + +# users + +Command: `boundary users` + +The `users` command lets you perform operations on Boundary user resources. + +## Example + +The following command creates a user with the name `prodops` and the description `For ProdOps usage`: + +```shell-session +$ boundary users create -name prodops -description "For ProdOps usage" +``` + +## Usage + + + +```shell-session +Usage: boundary users [options] [args] + + # ... + +Subcommands: + add-accounts Add accounts to a user within Boundary + create Create a user + delete Delete a user + list List a user + read Read a user + remove-accounts Remove accounts from a user within Boundary + set-accounts Set the full contents of the accounts on a user within Boundary + update Update a user +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [add-accounts](/boundary/docs/commands/users/add-accounts) +- [create](/boundary/docs/commands/users/create) +- [delete](/boundary/docs/commands/users/delete) +- [list](/boundary/docs/commands/users/list) +- [read](/boundary/docs/commands/users/read) +- [remove-accounts](/boundary/docs/commands/users/remove-accounts) +- [set-accounts](/boundary/docs/commands/users/set-accounts) +- [update](/boundary/docs/commands/users/update) diff --git a/website/content/docs/commands/users/list.mdx b/website/content/docs/commands/users/list.mdx new file mode 100644 index 000000000..0947dd63e --- /dev/null +++ b/website/content/docs/commands/users/list.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: users list - Command +description: |- + The "users list" command lists users from the specified scope or resource. +--- + +# users list + +Command: `users list` + +The `users list` command lets you list the users who belong to a given scope or resource. + +## Example + +This example lists all users in the scope `s_1234567890`: + +```shell-session +$ boundary users list -scope-id s_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary users list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before it is returned. +The filter operates against each item in the list. +We recommend that you use single quotes, as filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `-recursive` - If set, runs the list operation recursively into child scopes, if the type supports it. +The default value is `false`. +- `-scope-id=` - The scope that contains the users you want to list. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/read.mdx b/website/content/docs/commands/users/read.mdx new file mode 100644 index 000000000..5c9ae0382 --- /dev/null +++ b/website/content/docs/commands/users/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: users read - Command +description: |- + The `users read` command lets you read information about users by their user ID. +--- + +# users read + +Command: `users read` + +The `users read` command lets you read information about users by their user ID. + +## Example + +This example reads user details for a user with the ID `u_1234567890`: + +```shell-session +$ boundary users read -id u_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary users read [options] [args] +``` + + + +### Command options + +- `-id=` - The ID of the user you want to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/remove-accounts.mdx b/website/content/docs/commands/users/remove-accounts.mdx new file mode 100644 index 000000000..4b9020368 --- /dev/null +++ b/website/content/docs/commands/users/remove-accounts.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: users remove-accounts - Command +description: |- + The "users remove-accounts" command disassociates accounts from a user. +--- + +# users remove-accounts + +Command: `users remove-accounts` + +The `users remove-accounts` command lets you disassociate accounts from a user. + +## Example + +This example disassociates a user `u_1234567890` from an account `a_1234567890`: + +```shell-session +$ boundary users remove-accounts -id u_1234567890 -account a_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary users remove-accounts [options] [args] +``` + + + +### Command options + +- `-account=` - The account you want to disassociate from the user. +You can specify multiple accounts. +- `-id=` - The ID of the user you want to disassociate from an account. +- `-version=` - The version of the user to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/set-accounts.mdx b/website/content/docs/commands/users/set-accounts.mdx new file mode 100644 index 000000000..278ce5fcc --- /dev/null +++ b/website/content/docs/commands/users/set-accounts.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: users set-accounts - Command +description: |- + The "users set-accounts" command configures the complete set of associated acounts on a user. +--- + +# users set-accounts + +Command: `users set-accounts` + +The `users set-accounts` command lets you configure a complete set of associated accounts on a user. + +## Example + +This example sets the accounts `a_0987654321` and `a_1234567890` on a user `u_1234567890`: + +```shell-session +$ boundary users set-accounts -id u_1234567890 -account a_0987654321 -account a_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary users set-accounts [options] [args] +``` + + + +### Command options + +- `-account=` - The account you want to set on the user. +You can specify multiple accounts. +- `-id=` - The ID of the user you want to set accounts for. +- `-version=` - The version of the user to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/update.mdx b/website/content/docs/commands/users/update.mdx new file mode 100644 index 000000000..c2987ea92 --- /dev/null +++ b/website/content/docs/commands/users/update.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: users update - Command +description: |- + The "users update" command lets you update a user's information. +--- + +# users update + +Command: `users update` + +The `users update` command lets you update a user's information. + +## Example + +This example updates a user with the ID `u_1234567890` to add the name `devops` and the description `User for DevOps`: + +```shell-session +$ boundary users update -id u_1234567890 -name "devops" -description "User for DevOps" +``` + +## Usage + + + +```shell-session +$ boundary users update [options] [args] +``` + + + +### Command options + +- `-description=` - The description to assign the user. +- `-id=` - The ID of the user you want to update. +- `-name=` - The name to assign the user. +- `-version=` - The version of the user to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/add-worker-tags.mdx b/website/content/docs/commands/workers/add-worker-tags.mdx new file mode 100644 index 000000000..8b5760acc --- /dev/null +++ b/website/content/docs/commands/workers/add-worker-tags.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: workers add-worker-tags - Command +description: |- + The "workers add-worker-tags" command lets you add api tags to worker resources. +--- + +# workers add-worker-tags + +Command: `boundary workers add-worker-tags` + +The `boundary workers add-worker-tags` command lets you add API tags to worker resources. + +## Example + +This example adds the API tags `key1=val-a` and `key2=val-b,val-c` to a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers add-worker-tags -id w_1234567890 -tag "key1=val-a" -tag "key2=val-b,val-c" +``` + +## Usage + + + +```shell-session +$ boundary workers add-worker-tags [sub command] [args] +``` + + + + +### Command options + +- `-id=` - The ID of the worker you want to add API tags to. +- `tag=` - The API tag resources you want to add to workers. +- `version=` - The version of the worker to add the API tag to. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/certificate-authority.mdx b/website/content/docs/commands/workers/certificate-authority.mdx new file mode 100644 index 000000000..77a8047ce --- /dev/null +++ b/website/content/docs/commands/workers/certificate-authority.mdx @@ -0,0 +1,79 @@ +--- +layout: docs +page_title: workers certificate-authority - Command +description: |- + The "workers certificate-authority" command lets you manage the certificate authority used to authorize Boundary workers. +--- + +# workers certificate-authority + +Command: `boundary workers certificate-authority` + +The `boundary workers certificate-authority` command lets you manage the certificate authority used to authorize Boundary workers. + +## Example + +This example lets you read information about the current certificate authority: + +```shell-session +$ boundary workers certificate-authority read +``` + +## Usage + + + +```shell-session +$ boundary workers certificate-authority [options] + + # ... + +Subcommands: + read Read the certificate authority used to authorize Boundary workers. + reinitialize Reinitialize the certificate authority used to authorize Boundary workers. +``` + + + +### Usages by type + +You can read or reinitialize certificate authorities. + + + + +The `workers certificate-authority read` command lets you read the details of the certificate authority that is used to authorize Boundary workers. + +#### Usage + +```shell-session +$ boundary workers certificate-authority read [options] [args] +``` + +#### Worker certificate authority options + +- `-scope-id=` - The scope in which to read the certificate authority. +The default scope is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + + + + +The `workers certificate-authority reinitialize` command lets you reinitialize the certificate authority that is used to authorize Boundary workers. + +#### Usage + +```shell-session +$ workers certificate-authority reinitialize [options] [args] +``` + +#### Worker certificate authority options + +- `-scope-id=` - The scope in which to reinitialize the certificate authority. +The default scope is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/create.mdx b/website/content/docs/commands/workers/create.mdx new file mode 100644 index 000000000..1472ba691 --- /dev/null +++ b/website/content/docs/commands/workers/create.mdx @@ -0,0 +1,111 @@ +--- +layout: docs +page_title: workers create - Command +description: |- + The "workers create" command lets you create Boundary workers. +--- + +# workers create + +Command: `boundary workers create` + +The `boundary workers create` command lets you create Boundary workers. + +## Example + +This example creates a worker with the name `prodops` and the description `Worker for ProdOps`: + +```shell-session +$ boundary workers create -name prodops -description "Worker for ProdOps" +``` + +## Usage + + + +```shell-session +$ boundary workers create [options] [args] + + # ... + +Subcommands: + controller-led Create a controller-led type worker. + worker-led Create a worker-led type worker. +``` + + + +### Usages by type + +You can create controller-led or worker-led types of workers. + + + + +The `workers create controller-led` command lets you create a worker by receiving an activation token from a controller. + +#### Example + +This example creates a controller-led worker named `us-east-1-1`: + + + +```shell-session +$ boundary workers create controller-led -name us-east-1-1 +``` + + + +#### Usage + +```shell-session +$ boundary workers create controller-led [options] [args] +``` + +#### Command options + +- `-description=` - A description to set on the controller-led type worker. +- `name=` - A name to set on the controller-led type worker. +- `scope-id=` - The scope in which to make the request. +The default is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + + + + +The `workers create worker-led` command lets you create a worker by providing an auth method from the worker. + +#### Example + +This example specifies a worker-generated auth token and creates a worker named `us-east-1-1`: + + + +```shell-session +$ boundary workers create worker-led -name us-east-1-1 -worker-generated-auth-token +``` + + + +#### Usage + +```shell-session +$ boundary workers create worker-led [options] [args] +``` + +#### Command options + +- `-description=` - A description to set on the worker-led type worker. +- `name=` - A name to set on the worker-led type worker. +- `scope-id=` - The scope in which to make the request. +The default is `global`. +You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. + +#### Worker creation options + +- `worker-generated-auth-token=` - The auth token that is provided by the worker and used to register the worker with Boundary. + + + + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/delete.mdx b/website/content/docs/commands/workers/delete.mdx new file mode 100644 index 000000000..8069d375d --- /dev/null +++ b/website/content/docs/commands/workers/delete.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: workers delete - Command +description: |- + The "workers delete" command lets you delete Boundary workers. +--- + +# workers delete + +Command: `boundary workers delete` + +The `boundary workers delete` command lets you delete a Boundary worker by its given ID. + +## Example + +This example deletes a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers delete -id w_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary workers delete [options] [args] +``` + + + +### Command options + +- `id=` - The ID of the worker you want to delete. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/index.mdx b/website/content/docs/commands/workers/index.mdx new file mode 100644 index 000000000..0c467acf3 --- /dev/null +++ b/website/content/docs/commands/workers/index.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: workers - Command +description: |- + The "workers" command performs operations on Boundary worker resources. +--- + +# workers + +Command: `boundary workers` + +The `workers` command lets you perform operations on Boundary worker resources. + +## Example + +This example reads information about a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers read -id w_1234567890 +``` + +## Usage + + + +```shell-session +Usage: boundary workers [options] [args] + + # ... + +Subcommands: + add-worker-tags Add api tags to the specified worker. + certificate-authority Manage the certificate authority used to authorize Boundary workers + create Create a worker + delete Delete a worker + list List a worker + read Read a worker + remove-worker-tags Remove api tags from the specified worker + set-worker-tags Set api tags for the specified worker + update Update a worker +``` + + + +For more information, examples, and usage, click on the name +of the subcommand in the sidebar or one of the links below: + +- [add-worker-tags](/boundary/docs/commands/workers/add-worker-tags) +- [certificate-authority](/boundary/docs/commands/workers/certificate-authority) +- [create](/boundary/docs/commands/workers/create) +- [delete](/boundary/docs/commands/workers/delete) +- [list](/boundary/docs/commands/workers/list) +- [read](/boundary/docs/commands/workers/read) +- [remove-worker-tags](/boundary/docs/commands/workers/remove-worker-tags) +- [set-worker-tags](/boundary/docs/commands/workers/set-worker-tags) +- [update](/boundary/docs/commands/workers/update) \ No newline at end of file diff --git a/website/content/docs/commands/workers/list.mdx b/website/content/docs/commands/workers/list.mdx new file mode 100644 index 000000000..18d6e6fd4 --- /dev/null +++ b/website/content/docs/commands/workers/list.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: workers list - Command +description: |- + The "workers list" command lets you list Boundary workers in a scope or resource. +--- + +# workers list + +Command: `boundary workers list` + +The `boundary workers list` command lets you list the Boundary workers in a scope or resource. + +## Example + +This example lists all workers in the `global` scope: + +```shell-session +$ boundary workers list +``` + +## Usage + + + +```shell-session +$ boundary workers list [options] [args] +``` + + + +### Command options + +- `-filter=` - If set, Boundary filters the list operation before the results are returned. +The filter operates against each item in the list. +We recommend that you use single quotes, because the filters contain double quotes. +Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it. +The default value is `false`. +- `scope-id=` - The scope from which to list the workers. +The default value is `global`. +You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/read.mdx b/website/content/docs/commands/workers/read.mdx new file mode 100644 index 000000000..9c583d643 --- /dev/null +++ b/website/content/docs/commands/workers/read.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: workers read - Command +description: |- + The "workers read" command lets you read a Boundary worker with a given ID. +--- + +# workers read + +Command: `boundary workers read` + +The `boundary workers read` command lets you read a Boundary worker information for a given ID. + +## Example + +This example reads a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers read -id w_1234567890 +``` + +## Usage + + + +```shell-session +$ boundary workers read [options] [args] +``` + + + +### Command options + +- `id=` - The ID of the worker to read. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/remove-worker-tags.mdx b/website/content/docs/commands/workers/remove-worker-tags.mdx new file mode 100644 index 000000000..616d6a05a --- /dev/null +++ b/website/content/docs/commands/workers/remove-worker-tags.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: workers remove-worker-tags - Command +description: |- + The "workers remove-worker-tags" command lets you remove api tags from worker resources. +--- + +# workers remove-worker-tags + +Command: `boundary workers remove-worker-tags` + +The `boundary workers remove-worker-tags` command lets you remove API tags from worker resources. + +## Example + +This example removes the API tags `key1=val-a` and `key2=val-b,val-c` from a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers remove-worker-tags -id w_1234567890 -tag "key1=val-a" -tag "key2=val-b,val-c" +``` + +## Usage + + + +```shell-session +$ boundary workers remove-worker-tags [sub command] [args] +``` + + + + +### Command options + +- `-id=` - The ID of the worker you want to remove the tag from. +- `tag=` - The API tag resources you want to remove from the worker. +- `version=` - The version of the worker to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/set-worker-tags.mdx b/website/content/docs/commands/workers/set-worker-tags.mdx new file mode 100644 index 000000000..97e712daf --- /dev/null +++ b/website/content/docs/commands/workers/set-worker-tags.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: workers set-worker-tags - Command +description: |- + The "workers set-worker-tags" command lets you set api tags for worker resources. +--- + +# workers set-worker-tags + +Command: `boundary workers set-worker-tags` + +The `boundary workers set-worker-tags` command lets you set API tags for worker resources. + +## Example + +This example sets the API tags `key1=val-a` and `key2=val-b,val-c` for a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers set-worker-tags -id w_1234567890 -tag "key1=val-a" -tag "key2=val-b,val-c" +``` + +## Usage + + + +```shell-session +$ boundary workers set-worker-tags [sub command] [args] +``` + + + + +### Command options + +- `-id=` - The ID of the worker you want to set tags for. +- `tag=` - The API tag resources you want to set on the worker. +- `version=` - The version of the worker to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/workers/update.mdx b/website/content/docs/commands/workers/update.mdx new file mode 100644 index 000000000..c27fb76df --- /dev/null +++ b/website/content/docs/commands/workers/update.mdx @@ -0,0 +1,40 @@ +--- +layout: docs +page_title: workers update - Command +description: |- + The "workers update" command lets you update a Boundary worker. +--- + +# workers update + +Command: `boundary workers update` + +The `boundary workers update` command lets you update a Boundary worker with a given ID. + +## Example + +This example updates the name and description of a worker with the ID `w_1234567890`: + +```shell-session +$ boundary workers update -id w_1234567890 -name "devops" -description "Worker for DevOps" +``` + +## Usage + + + +```shell-session +$ boundary workers update [options] [args] +``` + + + +### Command options + +- `description=` - A description to set on the worker. +- `id=` - The ID of the worker you want to update. +- `name=` - The name to set on the worker. +- `version=` - The version of the worker to perform the operation on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/partials/cmd-connect-command-options.mdx b/website/content/partials/cmd-connect-command-options.mdx new file mode 100644 index 000000000..aa0c6ee0a --- /dev/null +++ b/website/content/partials/cmd-connect-command-options.mdx @@ -0,0 +1,31 @@ +### Connect command options: + +- `-authz-token` `(string: "")` - The authorization string returned from the Boundary controller via an `authorize-session` action against a target. + This option is only required if you don't set a `-target-id`. + If you set the value to `-`, the command attempts to read in the authorization string from standard input. + You can also specify the authorization string using the **BOUNDARY_CONNECT_AUTHZ_TOKEN** environment variable. + +- `-exec` `(string: "")` - If set, specifies that the given binary should be executed after connecting to the worker, if set. + This value should be a binary on your path or an absolute path. + If all command flags are followed by ` -- ` (space, two hyphens, space), then any arguments after that are sent directly to the binary. + You can also specify a binary using the **BOUNDARY_CONNECT_EXEC** environment variable. + +- `-host-id` `(string: "")` - The ID of a specific host to connect to out of + the target's host sets. + If you do not indicate a specific host, Boundary chooses one at random. + +- `-target-id` `(string: "")` - The ID of the target to authorize against. + You cannot use this option with `-authz-token`. + +- `-target-name` `(string: "")` - The target name, if you authorize the session using + scope parameters and target name. + +- `-target-scope-id` `(string: "")` - The target scope ID, if you authorize the + session using scope parameters and target name. + This value is mutually exclusive with `-scope-name`. + You can also specify the target scope ID using the **BOUNDARY_CONNECT_TARGET_SCOPE_ID** environment variable. + +- `-target-scope-name` `(string: "")` - The target scope name, if you authorize the + session using scope parameters and target name. + This value is mutually exclusive with `-scope-id`. + You can also specify the target scope name using the **BOUNDARY_CONNECT_TARGET_SCOPE_NAME** environment variable. diff --git a/website/content/partials/cmd-connect-env-vars.mdx b/website/content/partials/cmd-connect-env-vars.mdx new file mode 100644 index 000000000..bddce7b08 --- /dev/null +++ b/website/content/partials/cmd-connect-env-vars.mdx @@ -0,0 +1,10 @@ +You also have access to some templated values that are substituted into the +command arguments, and these values are additionally injected as environment +variables in the executed command: + +- `{{boundary.ip}}` (`BOUNDARY_PROXIED_IP`): The IP address of the listening + socket that `boundary connect` has opened. +- `{{boundary.port}}` (`BOUNDARY_PROXIED_PORT`): The port of the listening + socket that `boundary connect` has opened. +- `{{boundary.addr}}` (`BOUNDARY_PROXIED_ADDR`): The host:port format of the + address. This is essentially equivalent to `{{boundary.ip}}:{{boundary.port}}`. diff --git a/website/content/partials/cmd-option-note.mdx b/website/content/partials/cmd-option-note.mdx new file mode 100644 index 000000000..075a4d3a0 --- /dev/null +++ b/website/content/partials/cmd-option-note.mdx @@ -0,0 +1,11 @@ + + +In addition to the command specific options, there are options common to all +CLI commands and subcommands: + +- [Connection options](/boundary/docs/commands/#connection-options) +- [Client options](/boundary/docs/commands/#client-options) +- [Output options](/boundary/docs/commands/#output-options) +- [Environment variables](/boundary/docs/commands/#environment-variables) + + \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 302131792..bd9508197 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -527,7 +527,779 @@ ] }, { - "title": "API/clients", + "title": "Commands (CLI)", + "routes": [ + { + "title": "Overview", + "path": "commands" + }, + { + "title": "accounts", + "routes": [ + { + "title": "Overview", + "path": "commands/accounts" + }, + { + "title": "change-password", + "path": "commands/accounts/change-password" + }, + { + "title": "create", + "path": "commands/accounts/create" + }, + { + "title": "delete", + "path": "commands/accounts/delete" + }, + { + "title": "list", + "path": "commands/accounts/list" + }, + { + "title": "read", + "path": "commands/accounts/read" + }, + { + "title": "set-password", + "path": "commands/accounts/set-password" + }, + { + "title": "update", + "path": "commands/accounts/update" + } + ] + }, + { + "title": "auth-methods", + "routes": [ + { + "title": "Overview", + "path": "commands/auth-methods" + }, + { + "title": "change-state", + "path": "commands/auth-methods/change-state" + }, + { + "title": "create", + "path": "commands/auth-methods/create" + }, + { + "title": "delete", + "path": "commands/auth-methods/delete" + }, + { + "title": "list", + "path": "commands/auth-methods/list" + }, + { + "title": "read", + "path": "commands/auth-methods/read" + }, + { + "title": "update", + "path": "commands/auth-methods/update" + } + ] + }, + { + "title": "auth-tokens", + "routes": [ + { + "title": "Overview", + "path": "commands/auth-tokens" + }, + { + "title": "delete", + "path": "commands/auth-tokens/delete" + }, + { + "title": "list", + "path": "commands/auth-tokens/list" + }, + { + "title": "read", + "path": "commands/auth-tokens/read" + } + ] + }, + { + "title": "authenticate", + "routes": [ + { + "title": "Overview", + "path": "commands/authenticate" + }, + { + "title": "ldap", + "path": "commands/authenticate/ldap" + }, + { + "title": "oidc", + "path": "commands/authenticate/oidc" + }, + { + "title": "password", + "path": "commands/authenticate/password" + } + ] + }, + { + "title": "config", + "routes": [ + { + "title": "Overview", + "path": "commands/config" + }, + { + "title": "autocomplete", + "path": "commands/config/autocomplete" + }, + { + "title": "decrypt", + "path": "commands/config/decrypt" + }, + { + "title": "encrypt", + "path": "commands/config/encrypt" + }, + { + "title": "get-token", + "path": "commands/config/get-token" + } + ] + }, + { + "title": "connect", + "routes": [ + { + "title": "Overview", + "path": "commands/connect" + }, + { + "title": "http", + "path": "commands/connect/http" + }, + { + "title": "kube", + "path": "commands/connect/kube" + }, + { + "title": "postgres", + "path": "commands/connect/postgres" + }, + { + "title": "rdp", + "path": "commands/connect/rdp" + }, + { + "title": "ssh", + "path": "commands/connect/ssh" + } + ] + }, + { + "title": "credential-libraries", + "routes": [ + { + "title": "Overview", + "path": "commands/credential-libraries" + }, + { + "title": "create", + "path": "commands/credential-libraries/create" + }, + { + "title": "delete", + "path": "commands/credential-libraries/delete" + }, + { + "title": "list", + "path": "commands/credential-libraries/list" + }, + { + "title": "read", + "path": "commands/credential-libraries/read" + }, + { + "title": "update", + "path": "commands/credential-libraries/update" + } + ] + }, + { + "title": "credential-stores", + "routes": [ + { + "title": "Overview", + "path": "commands/credential-stores" + }, + { + "title": "create", + "path": "commands/credential-stores/create" + }, + { + "title": "delete", + "path": "commands/credential-stores/delete" + }, + { + "title": "list", + "path": "commands/credential-stores/list" + }, + { + "title": "read", + "path": "commands/credential-stores/read" + }, + { + "title": "update", + "path": "commands/credential-stores/update" + } + ] + }, + { + "title": "credentials", + "routes": [ + { + "title": "Overview", + "path": "commands/credentials" + }, + { + "title": "create", + "path": "commands/credentials/create" + }, + { + "title": "delete", + "path": "commands/credentials/delete" + }, + { + "title": "list", + "path": "commands/credentials/list" + }, + { + "title": "read", + "path": "commands/credentials/read" + }, + { + "title": "update", + "path": "commands/credentials/update" + } + ] + }, + { + "title": "database", + "routes": [ + { + "title": "Overview", + "path": "commands/database" + }, + { + "title": "init", + "path": "commands/database/init" + }, + { + "title": "migrate", + "path": "commands/database/migrate" + } + ] + }, + { + "title": "dev", + "path": "commands/dev" + }, + { + "title": "groups", + "routes": [ + { + "title": "Overview", + "path": "commands/groups" + }, + { + "title": "add-members", + "path": "commands/groups/add-members" + }, + { + "title": "create", + "path": "commands/groups/create" + }, + { + "title": "delete", + "path": "commands/groups/delete" + }, + { + "title": "list", + "path": "commands/groups/list" + }, + { + "title": "read", + "path": "commands/groups/read" + }, + { + "title": "remove-members", + "path": "commands/groups/remove-members" + }, + { + "title": "set-members", + "path": "commands/groups/set-members" + }, + { + "title": "update", + "path": "commands/groups/update" + } + ] + }, + { + "title": "host-catalogs", + "routes": [ + { + "title": "Overview", + "path": "commands/host-catalogs" + }, + { + "title": "create", + "path": "commands/host-catalogs/create" + }, + { + "title": "delete", + "path": "commands/host-catalogs/delete" + }, + { + "title": "list", + "path": "commands/host-catalogs/list" + }, + { + "title": "read", + "path": "commands/host-catalogs/read" + }, + { + "title": "update", + "path": "commands/host-catalogs/update" + } + ] + }, + { + "title": "host-sets", + "routes": [ + { + "title": "Overview", + "path": "commands/host-sets" + }, + { + "title": "add-hosts", + "path": "commands/host-sets/add-hosts" + }, + { + "title": "create", + "path": "commands/host-sets/create" + }, + { + "title": "delete", + "path": "commands/host-sets/delete" + }, + { + "title": "list", + "path": "commands/host-sets/list" + }, + { + "title": "read", + "path": "commands/host-sets/read" + }, + { + "title": "remove-hosts", + "path": "commands/host-sets/remove-hosts" + }, + { + "title": "set-hosts", + "path": "commands/host-sets/set-hosts" + }, + { + "title": "update", + "path": "commands/host-sets/update" + } + ] + }, + { + "title": "hosts", + "routes": [ + { + "title": "Overview", + "path": "commands/hosts" + }, + { + "title": "create", + "path": "commands/hosts/create" + }, + { + "title": "delete", + "path": "commands/hosts/delete" + }, + { + "title": "list", + "path": "commands/hosts/list" + }, + { + "title": "read", + "path": "commands/hosts/read" + }, + { + "title": "update", + "path": "commands/hosts/update" + } + ] + }, + { + "title": "logout", + "path": "commands/logout" + }, + { + "title": "managed-groups", + "routes": [ + { + "title": "Overview", + "path": "commands/managed-groups" + }, + { + "title": "create", + "path": "commands/managed-groups/create" + }, + { + "title": "delete", + "path": "commands/managed-groups/delete" + }, + { + "title": "list", + "path": "commands/managed-groups/list" + }, + { + "title": "read", + "path": "commands/managed-groups/read" + }, + { + "title": "update", + "path": "commands/managed-groups/update" + } + ] + }, + { + "title": "roles", + "routes": [ + { + "title": "Overview", + "path": "commands/roles" + }, + { + "title": "add-grants", + "path": "commands/roles/add-grants" + }, + { + "title": "add-principals", + "path": "commands/roles/add-principals" + }, + { + "title": "create", + "path": "commands/roles/create" + }, + { + "title": "delete", + "path": "commands/roles/delete" + }, + { + "title": "list", + "path": "commands/roles/list" + }, + { + "title": "read", + "path": "commands/roles/read" + }, + { + "title": "remove-grants", + "path": "commands/roles/remove-grants" + }, + { + "title": "remove-principals", + "path": "commands/roles/remove-principals" + }, + { + "title": "set-grants", + "path": "commands/roles/set-grants" + }, + { + "title": "set-principals", + "path": "commands/roles/set-principals" + }, + { + "title": "update", + "path": "commands/roles/update" + } + ] + }, + { + "title": "scopes", + "routes": [ + { + "title": "Overview", + "path": "commands/scopes" + }, + { + "title": "create", + "path": "commands/scopes/create" + }, + { + "title": "delete", + "path": "commands/scopes/delete" + }, + { + "title": "destroy-key-version", + "path": "commands/scopes/destroy-key-version" + }, + { + "title": "list", + "path": "commands/scopes/list" + }, + { + "title": "list-key-version-destruction-jobs", + "path": "commands/scopes/list-key-version-destruction-jobs" + }, + { + "title": "list-keys", + "path": "commands/scopes/list-keys" + }, + { + "title": "read", + "path": "commands/scopes/read" + }, + { + "title": "rotate-keys", + "path": "commands/scopes/rotate-keys" + }, + { + "title": "update", + "path": "commands/scopes/update" + } + ] + }, + { + "title": "server", + "path": "commands/server" + }, + { + "title": "session-recordings", + "routes": [ + { + "title": "Overview", + "path": "commands/session-recordings" + }, + { + "title": "download", + "path": "commands/session-recordings/download" + }, + { + "title": "list", + "path": "commands/session-recordings/list" + }, + { + "title": "read", + "path": "commands/session-recordings/read" + } + ] + }, + { + "title": "sessions", + "routes": [ + { + "title": "Overview", + "path": "commands/sessions" + }, + { + "title": "cancel", + "path": "commands/sessions/cancel" + }, + { + "title": "list", + "path": "commands/sessions/list" + }, + { + "title": "read", + "path": "commands/sessions/read" + } + ] + }, + { + "title": "storage-buckets", + "routes": [ + { + "title": "Overview", + "path": "commands/storage-buckets" + }, + { + "title": "create", + "path": "commands/storage-buckets/create" + }, + { + "title": "delete", + "path": "commands/storage-buckets/delete" + }, + { + "title": "list", + "path": "commands/storage-buckets/list" + }, + { + "title": "read", + "path": "commands/storage-buckets/read" + }, + { + "title": "update", + "path": "commands/storage-buckets/update" + } + ] + }, + { + "title": "targets", + "routes": [ + { + "title": "Overview", + "path": "commands/targets" + }, + { + "title": "add-credential-sources", + "path": "commands/targets/add-credential-sources" + }, + { + "title": "add-host-sources", + "path": "commands/targets/add-host-sources" + }, + { + "title": "authorize-session", + "path": "commands/targets/authorize-session" + }, + { + "title": "create", + "path": "commands/targets/create" + }, + { + "title": "delete", + "path": "commands/targets/delete" + }, + { + "title": "list", + "path": "commands/targets/list" + }, + { + "title": "read", + "path": "commands/targets/read" + }, + { + "title": "remove-credential-source", + "path": "commands/targets/remove-credential-sources" + }, + { + "title": "remove-host-sources", + "path": "commands/targets/remove-host-sources" + }, + { + "title": "set-credential-sources", + "path": "commands/targets/set-credential-sources" + }, + { + "title": "set-host-sources", + "path": "commands/targets/set-host-sources" + }, + { + "title": "update", + "path": "commands/targets/update" + } + ] + }, + { + "title": "users", + "routes": [ + { + "title": "Overview", + "path": "commands/users" + }, + { + "title": "add-accounts", + "path": "commands/users/add-accounts" + }, + { + "title": "create", + "path": "commands/users/create" + }, + { + "title": "delete", + "path": "commands/users/delete" + }, + { + "title": "list", + "path": "commands/users/list" + }, + { + "title": "read", + "path": "commands/users/read" + }, + { + "title": "remove-accounts", + "path": "commands/users/remove-accounts" + }, + { + "title": "set-accounts", + "path": "commands/users/set-accounts" + }, + { + "title": "update", + "path": "commands/users/update" + } + ] + }, + { + "title": "workers", + "routes": [ + { + "title": "Overview", + "path": "commands/workers" + }, + { + "title": "add-worker-tags", + "path": "commands/workers/add-worker-tags" + }, + { + "title": "certificate-authority", + "path": "commands/workers/certificate-authority" + }, + { + "title": "create", + "path": "commands/workers/create" + }, + { + "title": "delete", + "path": "commands/workers/delete" + }, + { + "title": "list", + "path": "commands/workers/list" + }, + { + "title": "read", + "path": "commands/workers/read" + }, + { + "title": "remove-worker-tags", + "path": "commands/workers/remove-worker-tags" + }, + { + "title": "set-worker-tags", + "path": "commands/workers/set-worker-tags" + }, + { + "title": "update", + "path": "commands/workers/update" + } + ] + } + ] + }, + { + "title": "API and clients", "routes": [ { "title": "Overview", @@ -537,10 +1309,6 @@ "title": "API", "path": "api-clients/api" }, - { - "title": "CLI", - "path": "api-clients/cli" - }, { "title": "Go SDK", "path": "api-clients/go-sdk"