mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-15 19:17:02 +02:00
107 lines
4.0 KiB
Plaintext
107 lines
4.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: events - Command
|
|
description: |-
|
|
The "events" command interacts with the Vault events subsystem.
|
|
---
|
|
|
|
# events
|
|
|
|
Use the `events` command to get a real-time display of
|
|
[events](/vault/docs/concepts/events) generated by Vault and subscribe to Vault
|
|
events. 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 events, 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 events:
|
|
|
|
```shell-session
|
|
$ vault events subscribe '*'
|
|
```
|
|
|
|
Subscribe to all KV events:
|
|
|
|
```shell-session
|
|
$ vault events subscribe 'kv*'
|
|
```
|
|
|
|
Subscribe to all `kv-v2/data-write` events:
|
|
|
|
```shell-session
|
|
$ vault events subscribe kv-v2/data-write
|
|
```
|
|
|
|
Subscribe to all KV events 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.
|
|
|
|
- `-filter` `(string: "")` - Filter expression used to select events to be sent
|
|
through the WebSocket.
|
|
|
|
Refer to the [Filter expressions](/boundary/docs/concepts/filtering) guide
|
|
in the Boundary documentation for a complete list of filtering options and an
|
|
explanation on how we evaluate 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, e.g., `write`.
|
|
- `source_plugin_mount`: the mount of the plugin that produced the event,
|
|
e.g., `secret/`
|
|
- `data_path`: the API path that can be used to access the data of the secret related to the event, e.g., `secret/data/foo`
|
|
- `namespace`: the path of the namespace that created the event, e.g., `ns1/`
|
|
|
|
The filter string is empty by default. Unfiltered subscription requests match to
|
|
all events 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 events provided in the response.
|
|
|
|
Filters can be straightforward path matches like
|
|
`data_path == secret/data/foo`, which specifies that Vault should pass
|
|
return events 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
|
|
```
|
|
|
|
|
|
### Enterprise options
|
|
|
|
<EnterpriseAlert product="vault" />
|
|
|
|
- `-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 events 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 events in the requesting namespace.
|
|
|
|
<Note>
|
|
To subscribe to events 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>
|