mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
106 lines
4.7 KiB
Plaintext
106 lines
4.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: events - Command
|
|
description: |-
|
|
The "events" command interacts with the Vault events notifications subsystem.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# events
|
|
|
|
<EnterpriseAlert product="vault" />
|
|
|
|
Use the `events` command to get a real-time display of
|
|
[event notifications](/vault/docs/concepts/events) generated by Vault and to subscribe to Vault
|
|
event notifications. Note that the `events subscribe` runs indefinitly and will not exit on
|
|
its own unless it encounters an unexpected error. Similar to `tail -f` in the
|
|
Unix world, you must terminate the process from the command line to end the
|
|
`events` command.
|
|
|
|
Specify the desired event types (also called "topics") as a glob pattern. To
|
|
match against multiple event types, use `*` as a wildcard. The command returns
|
|
serialized JSON objects in the default protobuf JSON serialization format with
|
|
one line per event received.
|
|
|
|
## Examples
|
|
|
|
Subscribe to all event notifications:
|
|
|
|
```shell-session
|
|
$ vault events subscribe '*'
|
|
```
|
|
|
|
Subscribe to all KV event notifications:
|
|
|
|
```shell-session
|
|
$ vault events subscribe 'kv*'
|
|
```
|
|
|
|
Subscribe to all `kv-v2/data-write` event notifications:
|
|
|
|
```shell-session
|
|
$ vault events subscribe kv-v2/data-write
|
|
```
|
|
|
|
Subscribe to all KV event notifications in the current and `ns1` namespaces for the secret `secret/data/foo` that do not involve writing data:
|
|
|
|
```shell-session
|
|
$ vault events subscribe -namespaces=ns1 -filter='data_path == secret/data/foo and operation != "data-write"' 'kv*'
|
|
```
|
|
|
|
## Usage
|
|
|
|
`events subscribe` supports the following flags in addition to the [standard set of
|
|
flags](/vault/docs/commands) included on all commands.
|
|
|
|
### Options
|
|
|
|
- `-timeout`: `(duration: "")` - close the WebSocket automatically after the
|
|
specified duration.
|
|
|
|
- `-namespaces` `(string)` - Additional **child** namespaces for the
|
|
subscription. Repeat the flag to add additional namespace patterns to the
|
|
subscription request. Vault automatically prepends the issuing namespace for
|
|
the request to the provided namespace. For example, if you include
|
|
`-namespaces=ns2` on a request made in the `ns1` namespace, Vault will attempt
|
|
to subscribe you to event notifications under the `ns1/ns2` and `ns1` namespaces. You can
|
|
use the `*` character to include wildcards in the namespace pattern. By
|
|
default, Vault will only subscribe to event notifications in the requesting namespace.
|
|
|
|
<Note>
|
|
To subscribe to event notifications across multiple namespaces, you must provide a root
|
|
token or a token associated with appropriate policies across all the targeted
|
|
namespaces. Refer to
|
|
the <a href="/vault/tutorials/enterprise/namespaces">Secure multi-tenancy with
|
|
namespaces</a>tutorial for configuring your Vault instance appropriately.
|
|
</Note>
|
|
|
|
- `-filter` `(string: "")` - Filter expression used to select event notifications to be sent
|
|
through the WebSocket.
|
|
|
|
Refer to the [Filter expressions](/vault/docs/concepts/filtering) guide for a complete
|
|
list of filtering options and an explanation on how Vault evaluates filter expressions.
|
|
|
|
The following values are available in the filter expression:
|
|
- `event_type`: the event type, e.g., `kv-v2/data-write`.
|
|
- `operation`: the operation name that caused the event notification, e.g., `write`.
|
|
- `source_plugin_mount`: the mount of the plugin that produced the event notification,
|
|
e.g., `secret/`
|
|
- `data_path`: the API path that can be used to access the data of the secret related to the event notification, e.g., `secret/data/foo`
|
|
- `namespace`: the path of the namespace that created the event notification, e.g., `ns1/`
|
|
|
|
The filter string is empty by default. Unfiltered subscription requests match to
|
|
all event notifications that the requestor has access to for the target event type. When the
|
|
filter string is not empty, Vault applies the filter conditions after the policy
|
|
checks to narrow the event notifications provided in the response.
|
|
|
|
Filters can be straightforward path matches like
|
|
`data_path == secret/data/foo`, which specifies that Vault should pass
|
|
return event notifications that refer to the `secret/data/foo` secret to the WebSocket.
|
|
Or more complex statements that exclude specific operations. For example:
|
|
```
|
|
data_path == secret/data/foo and operation != write
|
|
```
|