CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add client cache documentation (#4244)

Browse Source 
* docs: Add client cache documentation

* docs: Update command documentation

* docs: Add management section

* docs: Update commands and examples

* docs: Fix code examples

* docs: Fix typo

* Apply batch of suggestions from code review

Co-authored-by: Todd <github@quaddi.com>

* docs: Updates from review, rewrite add-token

* Apply batch of suggestions from code review

Co-authored-by: Todd <github@quaddi.com>

* docs: Update commands, add-token

* docs: Change keyring name

* Update website/content/docs/api-clients/client-cache.mdx

Co-authored-by: Todd <github@quaddi.com>

* docs: Update commands

* Update website/content/docs/commands/search/index.mdx

Co-authored-by: Todd <github@quaddi.com>

---------

Co-authored-by: Todd <github@quaddi.com>
This commit is contained in:
Dan HeathandTodd authored and GitHub committed 2024-01-30 20:19:19 -05:00
1 parent cffcc30eda
commit 2005593dc2
8 files changed
+449
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

website/content/docs/api-clients/client-cache.mdx
+70
View File
@@ -0,0 +1,70 @@
---
layout: docs
page_title: Client cache
description: |-
Learn how the client cache enables Boundary to quickly retrieve local information about session and target resources.
---
# Client cache
The Boundary client daemon runs on end users' computers and locally caches session and target resource information from Boundary instances.
The cache helps expedite searches.
## Boundary `list` vs. `search`
You can use the Boundary API or CLI to `list` resources like targets, sessions, hosts, and users.
When you use the `list` command, Boundary searches the control plane to provide a current total of resources when it produces the list of results.
Some Boundary resources can provide a significant number of items in the response.
Because large lists of results may overwhelm your system resources, the client daemon caches the results of the `list` operation.
You can search the local cache instead of the control plane to help protect your system resources.
The Boundary `search` command also produces a list of Boundary resources.
When you use the `search` command, however, Boundary searches the local cache to create the list.
For more information, refer to the [`search`](/boundary/docs/commands/search) command documentation.
## Client cache management
The Boundary client daemon starts automatically in the background when a user runs a CLI command that interacts with a Boundary instance.
If you do not want the daemon to automatically start, you can include the `-skip-cache-daemon` flag or set the **BOUNDARY_SKIP_CACHE_DAEMON** environment variable when you use the Boundary CLI to interact with a Boundary instance.
### Startup and customization
You can start the daemon manually using the `boundary daemon start` command.
By default, the daemon starts in the foreground.
You can start it in the background by adding the `-background` flag.
If you start the daemon manually, you can customize the caching behavior.
Include any of the following options to customize the behavior:
- `max-search-staleness` - The amount of time that can pass since the last refresh before calling `boundary search` results in a blocking refresh from the Boundary instance of the resources being searched.
- `max-search-refresh-timeout` - The amount of time the `boundary search` blocking refresh can take before it times out.
In the event of a timeout, Boundary uses the stale data that is currently in the cache.
- `refresh-interval` - A duration that specifies how frequently the client cache should query Boundary for changes to sessions and targets.
Note that Boundary only searches sessions and targets that the user who ran the command has access to.
For more information, refer to the [`daemon start`](/boundary/docs/commands/daemon/start) command documentation.
### Logging
The client cache stores a log file in the **~/.boundary** directory.
Boundary automatically rotates the log once it reaches 5 MB.
It compresses and keeps the last 3 rotated logs before deleting a log.
### Status
You can check the status of the cache using the `boundary daemon status` command.
The command returns information about the cache including the uptime, user count, user information, and which Boundary resources the cache is tracking.
For more information, refer to the [`daemon status`](/boundary/docs/commands/daemon/status) command documentation.
### Auth tokens
By default, the Boundary CLI tries to use a keyring to store and receive auth tokens.
Whenever you use an auth token to interact with Boundary, the client cache stores the auth token and syncs the data associated with it.
If you authenticate to multiple Boundary instances, the client cache stores multiple auth tokens and syncs the data associated with each token.
To search the client cache for a specific Boundary instance, you can specify the appropriate auth token using the `boundary daemon add-token` command.
For more information, refer to the [`daemon add-token`](/boundary/docs/commands/daemon/add-token) command documentation.
website/content/docs/commands/daemon/add-token.mdx
+64
View File
@@ -0,0 +1,64 @@
---
layout: docs
page_title: daemon add-token - Command
description: |-
The "daemon add-token" command lets you add an auth token to a Boundary daemon that is running.
---
# daemon add-token
Command: `boundary daemon add-token`
The `boundary daemon add-token` command lets you add an auth token from your keyring to a Boundary daemon that is running.
By default, the Boundary CLI tries to use a keyring to store and receive auth tokens.
Whenever you use an auth token to interact with Boundary, the client cache stores the auth token and syncs the data associated with it.
If you authenticate to multiple Boundary instances, the client cache stores multiple auth tokens and syncs the data associated with each token.
By adding auth tokens to your client cache, you can select which specific Boundary instance you want to search.
## Examples
The following command adds an auth token to the client cache from your keyring:
```shell-session
$ boundary daemon add-token
```
The following command specifies the name of the keyring `development` from which you want to add the token:
```shell-session
$ boundary daemon add-token -token-name development
```
## Usage
<CodeBlockConfig hideClipboard>
```shell-session
$ boundary daemon add-token [options]
```
</CodeBlockConfig>
### Command options
- `keyring-type=<string>` - Specifies the type of keyring to use.
The default value is `auto` which uses the Windows credential manager, OS X keychain, or cross-platform password store, depending on your platform.
Use the value `none` to disable keyring functionality.
Depending on your platform, available values include:
- `wincred`
- `keychain`
- `pass`
- `secret-service`
You can also specify the keyring type using the **BOUNDARY_KEYRING_TYPE** environment variable.
- `output-curl-string` - Specifies that Boundary should print an equivalent cURL command string and exit, instead of executing the request.
The default value is `false`.
- `token` = A URL that points to a file on disk (file://) from which Boundary reads a token or an environment variable (env://) from which the token will be read.
If you set this parameter, it overrides the `token-name` parameter.
- `token-name` - If specified, Boundary uses the value in this parameter as the name when it stores the token in the system credential store.
You can use this value to switch user identities for different commands.
You can also specify a token name using the **BOUNDARY_TOKEN_NAME** environment variable.
@include 'cmd-option-note.mdx'
website/content/docs/commands/daemon/index.mdx
+43
View File
@@ -0,0 +1,43 @@
---
layout: docs
page_title: daemon - Command
description: |-
Boundary's "daemon" command lets you manage a local cache of information to facilitate searches and protect your system resources from being overwhelmed.
---
# daemon
Command: `boundary daemon`
The `daemon` command lets you manage the Boundary daemon and perform operations on the local cache of information.
## Example
The following command starts the Boundary daemon in the background:
```shell-session
$ boundary daemon start -background
```
## Usage
<CodeBlockConfig hideClipboard>
```shell-session
Usage: boundary daemon <subcommand> [options] [args]
# ...
Subcommands:
add-token Add an auth token to a Boundary daemon that is currently running.
start Starts the Boundary daemon.
status Gets the status information of a Boundary daemon that is currently running.
stop Stops the Boundary daemon.
```
</CodeBlockConfig>
For more information, examples, and usage, click on the name of the subcommand in the sidebar or one of the links below:
- [add-token](/boundary/docs/commands/daemon/add-token)
- [start](/boundary/docs/commands/daemon/start)
- [status](/boundary/docs/commands/daemon/status)
- [stop](/boundary/docs/commands/daemon/stop)
website/content/docs/commands/daemon/start.mdx
+49
View File
@@ -0,0 +1,49 @@
---
layout: docs
page_title: daemon start - Command
description: |-
The "daemon start" command lets you manually start the Boundary daemon and customize the behavior of the local cache.
---
# daemon start
Command: `boundary daemon start`
The `boundary daemon start` command lets you manually start the Boundary daemon and customize the behavior of the local cache.
## Example
The following command starts the Boundary daemon in the background:
```shell-session
$ boundary daemon start -background
```
## Usage
<CodeBlockConfig hideClipboard>
```shell-session
$ boundary daemon start [options] [args]
```
</CodeBlockConfig>
### Command options
- `background` - Starts the Boundary daemon in the background.
The default value is `false`.
By default, the daemon starts in the foreground.
- `log-format=<string>` - Specifies the log format, mostly as a fallback for events.
Supported values are `standard` and `json`.
- `max-search-refresh-timeout=<duration>` - If a search request triggers a best effort refresh, this value specifies how long the refresh should run before time out.
In the event of a timeout, Boundary uses the stale data that is currently in the cache.
The default value is 7 seconds.
- `max-search-staleness=<duration>` - The amount of time that can pass since the last refresh before the client cache causes a blocking refresh.
The blocking refresh occurs when you perform the `boundary search` command.
It requires Boundary to refresh the local cache using the control plane.
The default value is 30 seconds.
- `refresh-interval` - A duration that specifies how frequently the client cache should query Boundary for changes to sessions and targets.
Note that Boundary only searches sessions and targets that the user who ran the command has access to.
@include 'cmd-option-note.mdx'
website/content/docs/commands/daemon/status.mdx
+52
View File
@@ -0,0 +1,52 @@
---
layout: docs
page_title: daemon status - Command
description: |-
The "daemon status" command lets you manually check the status of the Boundary daemon.
---
# daemon status
Command: `boundary daemon status`
The `boundary daemon status` command lets you manually check the status of the Boundary daemon.
Boundary prints out a status report that includes configuration, user, and resource information.
## Example
The following command checks the status of the Boundary daemon:
```shell-session
$ boundary daemon status
```
**Example output:**
<CodeBlockConfig hideClipboard>
```plaintext
Status:
Domain Socket: /home/my_user/.boundary/socket/daemon.sock
Log Location: /home/my_user/.boundary/cache.log
Uptime: 15m22s
User Count: 1
```
</CodeBlockConfig>
## Usage
<CodeBlockConfig hideClipboard>
```shell-session
$ boundary daemon status [options] [args]
```
</CodeBlockConfig>
### Command options
- `output-curl-string` - Specifies that Boundary should print an equivalent cURL command string and exit, instead of executing the request.
The default value is `false`.
@include 'cmd-option-note.mdx'
website/content/docs/commands/daemon/stop.mdx
+32
View File
@@ -0,0 +1,32 @@
---
layout: docs
page_title: daemon stop - Command
description: |-
The "daemon stop" command lets you manually stop the Boundary daemon.
---
# daemon stop
Command: `boundary daemon stop`
The `boundary daemon stop` command lets you manually stop the Boundary daemon.
## Example
The following command stops the Boundary daemon:
```shell-session
$ boundary daemon stop
```
## Usage
<CodeBlockConfig hideClipboard>
```shell-session
$ boundary daemon stop [options] [args]
```
</CodeBlockConfig>
@include 'cmd-option-note.mdx'
website/content/docs/commands/search/index.mdx
+106
View File
@@ -0,0 +1,106 @@
---
layout: docs
page_title: search - Command
description: |-
The "search" command let's you search the Boundary local cache for information about sessions and targets.
---
# search
Command: `boundary search`
The `search` command lets you search Boundary's local cache for information about sessions and targets.
For more information, refer to [Boundary `list` vs `search`](/boundary/docs/api-clients/client-cache/#boundary-list-vs-search).
## Examples
The following example searches the local cache for all TCP targets that have the word "Generated" in the name.
```shell-session
$ boundary search -resource targets -query 'type="tcp" and name%"Generated"'
```
**Example output:**
<CodeBlockConfig hideClipboard>
```plaintext
Target information:
ID: ttcp_0987654321
Scope ID: p_1234567890
Version: 2
Type: tcp
Name: Generated target using host sources
Description: Provides a target using host sources in Boundary
Authorized Actions:
no-op
read
update
delete
add-host-sources
set-host-sources
remove-host-sources
add-credential-sources
set-credential-sources
remove-credential-sources
authorize-session
ID: ttcp_1234567890
Scope ID: p_1234567890
Version: 1
Type: tcp
Name: Generated target with a direct address
Description: Provides an initial target using an address in Boundary
Address: 127.8.0.1
Authorized Actions:
no-op
read
update
delete
add-host-sources
set-host-sources
remove-host-sources
add-credential-sources
set-credential-sources
remove-credential-sources
authorize-session
```
</CodeBlockConfig>
## Usage
<CodeBlockConfig hideClipboard>
```shell-session
$ boundary search [options]
```
</CodeBlockConfig>
### Command options
- `-resource` `(string: "")` - The type of resource you want to search the cache for.
This is a required field.
You can search for the following:
- `sessions` - Searches for any sessions associated with the user.
- `targets` - Searches for any targets associated with the user.
- `-query` `(optional)` - If set, specifies the [MQL](https://github.com/hashicorp/mql/blob/main/GRAMMAR.md) query you want to use to search for the indexed fields on the resource you specified.
If you do not provide a `-query` value, the search lists all resources of the specified type that have been cached.
The available fields that can be used in the search query for each resource include:
- targets: id, name, description, type, address, scope_id
- sessions: id, type, endpoint, status, scope_id, target_id, user_id
- `token` - A URL that points to a file on disk (file://) from which Boundary reads a token or an environment variable (env://) from which the token will be read.
If you set this parameter, it overrides the `token-name` parameter.
- `token-name` - If specified, Boundary uses the value in this parameter as the name when it stores the token in the system credential store.
You can use this value to switch user identities for different commands.
You can also specify a token name using the **BOUNDARY_TOKEN_NAME** environment variable.
@include 'cmd-option-note.mdx'
website/data/docs-nav-data.json
+33
View File
@@ -837,6 +837,31 @@
}
]
},
{
"title": "daemon",
"routes": [
{
"title": "Overview",
"path": "commands/daemon"
},
{
"title": "add-token",
"path": "commands/daemon/add-token"
},
{
"title": "start",
"path": "commands/daemon/start"
},
{
"title": "status",
"path": "commands/daemon/status"
},
{
"title": "stop",
"path": "commands/daemon/stop"
}
]
},
{
"title": "database",
"routes": [
@@ -1129,6 +1154,10 @@
}
]
},
{
"title": "search",
"path": "commands/search"
},
{
"title": "server",
"path": "commands/server"
@@ -1395,6 +1424,10 @@
{
"title": "Desktop",
"href": "https://learn.hashicorp.com/tutorials/boundary/hcp-getting-started-desktop-app"
},
{
"title": "Client cache",
"path": "api-clients/client-cache"
}
]
},