mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-18 12:37:02 +02:00
ae9ec39d44
This removes the WebSockets endpoint for events (which will be moved to the Enterprise repo) and disables tests that rely on it unless they are running in Enterprise. It also updates documentation to document that events are only available in Vault Enterprise.
103 lines
4.2 KiB
Plaintext
103 lines
4.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: events - Command
|
|
description: |-
|
|
The "events" command interacts with the Vault events notifications subsystem.
|
|
---
|
|
|
|
# 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
|
|
```
|