audit enable

Enable a new audit device.

$ vault audit enable [flags] <device_type> [options] [<config_argument=value>...]

$ vault audit enable [-help | -h]

Description

audit enable creates and enables an audit device at the given path or returns an error if an audit device already exists at the given path. The device configuration parameters depend on the audit device type.

Related API endpoints

EnableAuditDevice - POST:/sys/audit/{mount-path}

Limitations and warnings

None

Command arguments

device_type (enum : <required>)

The audit device type to create.

Enum	Description
`file`	Write log entries to a file on the Vault server.
`socket`	Write log entries to an existing TCP, UDP, or UNIX socket.
`syslog`	Write log entries using the existing system logging protocol.

Each audit device type also has a set of configuration arguments:

$ vault audit enable [flags] file [options] \
    file_path=<path/to/log/file>            \
    [mode=<file_permissions>]

file_path (string : <required>)

Location on the audit log on the Vault server. Must be one of the following:

Value	Description
Relative or absolute path	Write or append audit entries to the target file
`stdout`	Streams audit data to `stdout` on the Vault server
`discard`	Discards audit output instead of writing to a device

Example: file_path='/logs/kv-audit.log'

mode (string : "0600")

The chmod-style octal permissions for the audit file. Set mode to "0000" to prevent Vault from modifying the file mode.

Example: mode="0755"

$ vault audit enable [flags] socket [options] \
    [address=<server_address>]                \
    [socket_type=<protocol>]                  \
    [write_timeout=<wait_time>]

address (string : "")

Location of the socket as a server IP and port or a local path.

Example: address="/tmp/audit.sock"

socket_type (string : "tcp")

Communication protocol expected by the socket. Vault can write to any net.Dialer-compatible socket. If a TCP socket stops responding, Vault may become unresponsive due to a blocked audit device error.

Example: socket_type="udp"

write_timeout (string : "2s")

Duration in seconds that Vault will wait for a write to complete over the socket. Setting write_timeout to 0 disables time outs and forces Vault to always wait until the write completes.

Example: write_timeout=0

$ vault audit enable [flags] syslog [options] \
    [facility=<process_entry_source>]         \
    [tag=<program_entry_source>]

facility (string : "AUTH")

The process that generated the syslog entry (the syslog facility).

Example: facility="AUTO-AUTH"

tag (string : "vault")

The program that generated the syslog entry.

Example: tag="vault-agent"

Command options

elide_list_responses (bool : false)

Replace the details for response.data.keys and response.data.key_info with the number of entries to reduce the size of audit records. See Eliding list response bodies for more details.

Example: elide_list_responses=true

exclude (string : "") Enterprise

Remove any fields matching the provided exclusion filtering rules from the audit entry before writing to the audit device.

Example: exclude='[{ "condition": "/request/mount_type" == transit", "fields": [ "request/data" ] }]'

Tip

Write your exclude rules to a JSON file and use @ notation to pass the rule definitions to exclude:

$  vault audit enable exclude=@rules.json file file_path="/var/logs/vault/audit.log"'

fallback (bool : false) Enterprise

The audit device is the fallback for filtering purposes. Vault only supports one fallback audit device at a time.

Example: fallback=true

filter (string : "") Enterprise

Only write audit log entries matching the provided filtering expression to the audit device.

Example: filter='mount_type == "kv-v2"'

format (enum : json)

Write audit log entries in the provided format.

Enum	Description
`json`	Structure audit entries as JSON data
`jsonx`	Structure audit entries as XML data

Example: format=jsonx

hmac_accessor (bool : true)

Hash all token accessor data before writing to the audit device.

Example: hmac_accessor=false

log_raw (bool : false)

Hash all sensitive security information before writing to the audit device.

Example: log_raw=true

prefix (string : "")

Prepend the provided string to each log entry when writing to the audit device.

Example: prefix="KV Request :: "

Command flags

-description (string : "")

A human-friendly string that explains the purpose of the audit device.

Example: -description "KV request auditing"

-local (bool : false)

Indicates that the audit device is local to the Vault server and ignored by replication.

Example: -local

-path (string : "/<device_type>")

The internal path where Vault will access the audit device. Audit device paths must be unique across all audit devices.

Example: -path "/audit/kv-file"

Standard flags

[-address | VAULT_ADDR] (string : 'https://127.0.0.1:8200')

Address of the Vault server.

Examples:

CLI flag: -address "https://mydomain/vault:8200"
Environment variable: export VAULT_ADDR="https://mydomain/vault:8200"

[-agent-address | VAULT_AGENT_ADDR] (string : "")

Address of the Vault Agent, if used.

Examples:

CLI flag: -agent-address "https://mydomain/vault-agent:8200"
Environment variable: export VAULT_AGENT_ADDR="https://mydomain/vault-agent:8200"

[-ca-cert | VAULT_CA_CERT] (string : "")

Path to a PEM-encoded CA certificate file on the local disk. Used to verify SSL certificates for the server. Takes precedence over -ca_path.

Examples:

CLI flag: -ca-cert "/path/to/certs/mycert.pem"
Environment variable: export VAULT_CA_CERT="/path/to/certs/mycert.pem"

[-ca-path | VAULT_CAPATH] (string : "")

Path to a directory with PEM-encoded CA certificate files on the local disk. Used to verify SSL certificates for the server.

Examples:

CLI flag: -ca-path "/path/to/certs/dir"
Environment variable: export VAULT_CAPATH="/path/to/certs/dir"

[-client-cert | VAULT_CLIENT_CERT] (string : "")

Path to a PEM-encoded CA certificate file on the local disk. Used for TLS communication with the server. The specified certificate must match to the private key specified with -client-cert.

Examples:

CLI flag: -client-cert "/path/to/certs/mycert.pem"
Environment variable: export VAULT_CLIENT_CERT="/path/to/certs/mycert.pem"

[-client-key | VAULT_CLIENT_KEY] (string : "")

Path to a PEM-encoded private key that matches the client certificate set with -client-cert.

Examples:

CLI flag: -client-key "/path/to/keys/myprivatekey.pem"
Environment variable: export VAULT_CLIENT_KEY="/path/to/keys/myprivatekey.pem"

[-disable-redirects | VAULT_DISABLE_REDIRECTS] (bool : false)

Disable the default CLI redirect behavior so the CLI honors the first redirect response from the underlying API instead of following the full HTTP redirect chain.

Examples:

CLI flag: -disable-redirects
Environment variable: export VAULT_DISABLE_REDIRECTS=1

Warning

Disabling the default redirect behavior may cause commands that redirect requests to primary cluster notes (like vault operator raft snapshot) to misbehave.

-header (string : "")

Optional HTTP header in the form "<key>=<value>" for the CLI request. Repeat the -header flag as needed with one string per flag. User-defined headers cannot start with X-Vault-

Example: -header "Cache-Control=max-age=0"

[-mfa | VAULT_MFA] (string : "") Enterprise

A multi-factor authentication (MFA) credential, in the format mfa_method_name[:key[=value]], that the CLI should use to authenticate to Vault. The CLI adds MFA credentials to the X-Vault-MFA header when calling the underlying API endpoint.

Examples:

CLI flag: -mfa "totp:password=12345"
Environment variable: export VAULT_MFA="totp:password=12345"

Note

The VAULT_MFA environment variable only accepts one MFA method specification and one credential for the specified method. To supply multiple credentials or MFA methods, use the -mfa CLI flag and repeat the flag as needed.

[-namespace | -ns | VAULT_NAMESPACE] (string : <unset>)

Root namespace for the CLI command. Setting a default namespace allow relative mount paths.

Examples:

CLI flag: -namespace "admin"
Environment variable: export VAULT_NAMESPACE="admin"

-non-interactive (bool : false)

Prevent the CLI from asking users for input through the terminal.

Example: -non-interactive

-output-curl-string (bool : false)

Print the API call(s) required to execute the CLI command as cURL strings then exit without running the command.

Example: -output-curl-string

-output-policy (bool : false)

Print the Vault policy required to execute the CLI command as HCL then exit without running the command.

Example: -output-policy

-policy-override (bool : false)

Overrides any Sentinel policy where enforcement_level is "soft-mandatory".

Example: -policy-override

[-tls-server-name | VAULT_TLS_SERVER_NAME] (string : "")

Name of the SNI host for TLS handshake resolution for TLS connections to Vault.

Examples:

CLI flag: -tls-server-name "hostname.domain"
Environment variable: export VAULT_TLS_SERVER_NAME="hostname.domain"

[-tls-skip-verify | VAULT_SKIP_VERIFY] (bool : false)

Disable verification for all TLS certificates. Use with caution. Disabling TLS certificate verification decreases the security of data transmissions to and from the Vault server.

Examples:

CLI flag: -tls-skip-verify
Environment variable: export VAULT_SKIP_VERIFY=1

-unlock-key (string : <unset>)

Plaintext key that unlocks the underlying API endpoint for a given namespace.

Example: -unlock-key "7oXtdlmvRQ"

[-wrap-ttl | VAULT_WRAP_TTL] (string : "")

Default time-to-live in <number>[s|m|h|d] format for the Cubbyhole token used to wrap CLI responses. You must use vault unwrap to view response data before the duration expires. Leave wrap_ttl unset to leave CLI responses unwrapped.

Examples:

CLI flag: -wrap-ttl "5m"
Environment variable: export VAULT_WRAP_TTL="5m"

Examples

Enable a file type audit device at the default path, file/:

$ vault audit enable file file_path=/tmp/my-file.txt
Success! Enabled the file audit device at: file/

Enable a file type audit device at the path, audit/file:

$ vault audit enable -path=audit/file file file_path=/tmp/my-file.txt
Success! Enabled the file audit device at: audit/file/