The audit stanza configures the Nomad agent to configure Audit logging behavior.
Audit logging is an Enterprise-only feature.
audit{enabled=true}
audit{enabled=true}
When enabled, each HTTP request made to a nomad agent (client or server) will
generate two audit log entries. These two entries correspond to a stage,
OperationReceived and OperationComplete. Audit logging will generate a
OperationReceived event before the request is processed. An OperationComplete
event will be sent after the request has been processed, but before the response
body is returned to the end user.
By default, with a minimally configured audit stanza (audit { enabled = true })
The following default sink will be added with no filters.
The sink will create an audit.log file located within the defined data_dir
directory inside an audit directory. delivery_guarantee will be set to
"enforced" meaning that all requests must successfully be written to the sink
in order for HTTP requests to successfully complete.
enabled(bool: false) - Specifies if audit logging should be enabled.
When enabled, audit logging will occur for every request, unless it is
filtered by a filter.
sink(sink: default) - Configures a sink
for audit logs to be sent to.
filter(array<filter>: []) - Configures a filter
to exclude matching events from being sent to audit logging sinks.
type(string: "file", required) - Specifies the type of sink to create.
Currently only "file" type is supported.
delivery_guarantee(string: "enforced", required) - Specifies the
delivery guarantee that will be made for each audit log entry. Available
options are "enforced" and "best-effort". "enforced" will
halt request execution if the audit log event fails to be written to its sink.
"best-effort" will not halt request execution, meaning a request could
potentially be un-audited.
format(string: "json", required) - Specifies the output format to be
sent to a sink. Currently only "json" format is supported.
mode(string: "0600") - Specifies the permissions mode for the audit log
files using octal notation.
path(string: "[data_dir]/audit/audit.log") - Specifies the path and file
name to use for the audit log. By default Nomad will use its configured
data_dir for a combined path of
/data_dir/audit/audit.log. If rotate_bytes or rotate_duration are set
file rotation will occur. In this case the filename will be post-fixed with
a timestamp "filename-{timestamp}.log"
rotate_bytes(int: 0) - Specifies the number of bytes that should be
written to an audit log before it needs to be rotated. Unless specified,
there is no limit to the number of bytes that can be written to a log file.
rotate_duration(duration: "24h") - Specifies the maximum duration a
audit log should be written to before it needs to be rotated. Must be a
duration value such as 30s.
rotate_max_files(int: 0) - Specifies the maximum number of older audit
log file archives to keep. If 0, no files are ever deleted.
The filter stanza is used to create filters to filter out matching events
from being written to the audit log. By default, all events will be sent to an
audit log for all stages (OperationReceived and OperationComplete). Filters
are useful for operators who want to limit the performance impact of audit
logging as well as reducing the amount of events generated.
endpoints, stages, and operations support globbed pattern matching.
Query parameters are ignored when evaluating filters.
audit{enabled=true# Filter out all requests and all stages for /v1/metrics
filter "default"{type="HTTPEvent"endpoints=["/v1/metrics"]stages=["*"]operations=["*"]}# Filter out requests where endpoint matches globbed pattern
filter "globbed example"{type="HTTPEvent"endpoints=["/v1/evaluation/*/allocations"]stages=["*"]operations=["*"]}# Filter out OperationReceived GET requests for all endpoints
filter "OperationReceived GETs"{type="HTTPEvent"endpoints=["*"]stages=["OperationReceived"]operations=["GET"]}}
audit{enabled=true# Filter out all requests and all stages for /v1/metrics filter "default"{type="HTTPEvent"endpoints=["/v1/metrics"]stages=["*"]operations=["*"]}# Filter out requests where endpoint matches globbed pattern filter "globbed example"{type="HTTPEvent"endpoints=["/v1/evaluation/*/allocations"]stages=["*"]operations=["*"]}# Filter out OperationReceived GET requests for all endpoints filter "OperationReceived GETs"{type="HTTPEvent"endpoints=["*"]stages=["OperationReceived"]operations=["GET"]}}
type(string: "HTTPEvent", required) - Specifies the type of filter to
create. Currently only HTTPEvent is supported.
endpoints(array<string>: []) - Specifies the list of endpoints to apply
the filter to.
stages(array<string>: []) - Specifies the list of stages
("OperationReceived", "OperationComplete", "*") to apply the filter to
for a matching endpoint.
operations(array<string>: []) - Specifies the list of operations to
apply the filter to for a matching endpoint. For HTTPEvent types this
corresponds to an HTTP verb (GET, PUT, POST, DELETE...).
Below are two audit log entries for a request made to /v1/job/web/summary. The
first entry is for the OperationReceived stage. The second entry is for the
OperationComplete stage and includes the contents of the OperationReceived
stage plus a response key.
