Skip to content

Commit

Permalink
[DOCS] Add missing config options to shared file (#15136)
Browse files Browse the repository at this point in the history
* [DOCS] Add missing config options to shared file

* Add fixes from review

* Run mage fmt update to fix build error
  • Loading branch information
dedemorton authored Jan 21, 2020
1 parent 7b2f873 commit 7960c77
Show file tree
Hide file tree
Showing 8 changed files with 111 additions and 20 deletions.
56 changes: 56 additions & 0 deletions auditbeat/docs/auditbeat-options.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Auditbeat modules. Make sure you keep the
//// descriptions generic enough to work for all modules. To include
//// this file, use:
////
//// include::{docdir}/auditbeat-options.asciidoc[]
////
//////////////////////////////////////////////////////////////////////////

[id="module-standard-options-{modulename}"]
[float]
==== Standard configuration options

You can specify the following options for any {beatname_uc} module.

*`module`*:: The name of the module to run.

ifeval::["{modulename}"=="system"]
*`datasets`*:: A list of datasets to execute.
endif::[]

*`enabled`*:: A Boolean value that specifies whether the module is enabled.

ifeval::["{modulename}"=="system"]
*`period`*:: The frequency at which the datasets check for changes. If a system
is not reachable, {beatname_uc} returns an error for each period. This setting
is required. For most datasets, especially `process` and `socket`, a shorter
period is recommended.
endif::[]

*`fields`*:: A dictionary of fields that will be sent with the dataset event. This setting
is optional.

*`tags`*:: A list of tags that will be sent with the dataset event. This setting is
optional.

*`processors`*:: A list of processors to apply to the data generated by the dataset.
+
See <<filtering-and-enhancing-data>> for information about specifying
processors in your config.

*`index`*:: If present, this formatted string overrides the index for events from this
module (for elasticsearch outputs), or sets the `raw_index` field of the event's
metadata (for other outputs). This string can only refer to the agent name and
version and the event timestamp; for access to dynamic fields, use
`output.elasticsearch.index` or a processor.
+
Example value: `"%{[agent.name]}-myindex-%{+yyyy.MM.dd}"` might
expand to +"{beatname_lc}-myindex-2019.12.13"+.

*`keep_null`*:: If this option is set to true, fields with `null` values will be published in
the output document. By default, `keep_null` is set to `false`.

*`service.name`*:: A name given by the user to the service the data is collected from. It can be
used for example to identify information collected from nodes of different
clusters with the same `service.type`.
16 changes: 13 additions & 3 deletions auditbeat/docs/modules/auditd.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
This file is generated! See scripts/docs_collector.py
////

:modulename: auditd

[id="{beatname_lc}-module-auditd"]
== Auditd Module

Expand Down Expand Up @@ -135,6 +137,10 @@ following example shows all configuration options with their default values.
backpressure_strategy: auto
----

This module also supports the
<<module-standard-options-{modulename},standard configuration options>>
described later.

*`socket_type`*:: This optional setting controls the type of
socket that {beatname_uc} uses to receive events from the kernel. The two
options are `unicast` and `multicast`.
Expand Down Expand Up @@ -189,7 +195,8 @@ setting is primarily used for development and debugging purposes.
installed to the kernel. There should be one rule per line. Comments can be
embedded in the string using `#` as a prefix. The format for rules is the same
used by the Linux `auditctl` utility. {beatname_uc} supports adding file watches
(`-w`) and syscall rules (`-a` or `-A`).
(`-w`) and syscall rules (`-a` or `-A`). For more information, see
<<audit-rules>>.

*`audit_rule_files`*:: A list of files to load audit rules from. This files are
loaded after the rules declared in `audit_rules` are loaded. Wildcards are
Expand Down Expand Up @@ -218,10 +225,10 @@ time.
- `none`: No backpressure mitigation measures are enabled.
--

*`keep_null`*:: If this option is set to true, fields with `null` values will be
published in the output document. By default, `keep_null` is set to `false`.
include::{docdir}/auditbeat-options.asciidoc[]

[float]
[[audit-rules]]
=== Audit rules

The audit rules are where you configure the activities that are audited. These
Expand Down Expand Up @@ -304,3 +311,6 @@ auditbeat.modules:
----


:modulename!:

12 changes: 10 additions & 2 deletions auditbeat/docs/modules/file_integrity.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
This file is generated! See scripts/docs_collector.py
////

:modulename: file_integrity

[id="{beatname_lc}-module-file_integrity"]
== File Integrity Module

Expand Down Expand Up @@ -66,6 +68,10 @@ Linux.
recursive: false
----

This module also supports the
<<module-standard-options-{modulename},standard configuration options>>
described later.

*`paths`*:: A list of paths (directories or files) to watch. Globs are
not supported. The specified paths should exist when the metricset is started.

Expand Down Expand Up @@ -122,8 +128,7 @@ of this directories are watched. If `recursive` is set to `true`, the
`file_integrity` module will watch for changes on this directories and all
their subdirectories.

*`keep_null`*:: If this option is set to true, fields with `null` values will be
published in the output document. By default, `keep_null` is set to `false`.
include::{docdir}/auditbeat-options.asciidoc[]


[float]
Expand All @@ -146,3 +151,6 @@ auditbeat.modules:
----


:modulename!:

11 changes: 8 additions & 3 deletions auditbeat/module/auditd/_meta/docs.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,10 @@ following example shows all configuration options with their default values.
backpressure_strategy: auto
----

This module also supports the
<<module-standard-options-{modulename},standard configuration options>>
described later.

*`socket_type`*:: This optional setting controls the type of
socket that {beatname_uc} uses to receive events from the kernel. The two
options are `unicast` and `multicast`.
Expand Down Expand Up @@ -184,7 +188,8 @@ setting is primarily used for development and debugging purposes.
installed to the kernel. There should be one rule per line. Comments can be
embedded in the string using `#` as a prefix. The format for rules is the same
used by the Linux `auditctl` utility. {beatname_uc} supports adding file watches
(`-w`) and syscall rules (`-a` or `-A`).
(`-w`) and syscall rules (`-a` or `-A`). For more information, see
<<audit-rules>>.

*`audit_rule_files`*:: A list of files to load audit rules from. This files are
loaded after the rules declared in `audit_rules` are loaded. Wildcards are
Expand Down Expand Up @@ -213,10 +218,10 @@ time.
- `none`: No backpressure mitigation measures are enabled.
--

*`keep_null`*:: If this option is set to true, fields with `null` values will be
published in the output document. By default, `keep_null` is set to `false`.
include::{docdir}/auditbeat-options.asciidoc[]

[float]
[[audit-rules]]
=== Audit rules

The audit rules are where you configure the activities that are audited. These
Expand Down
7 changes: 5 additions & 2 deletions auditbeat/module/file_integrity/_meta/docs.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ Linux.
recursive: false
----

This module also supports the
<<module-standard-options-{modulename},standard configuration options>>
described later.

*`paths`*:: A list of paths (directories or files) to watch. Globs are
not supported. The specified paths should exist when the metricset is started.

Expand Down Expand Up @@ -117,5 +121,4 @@ of this directories are watched. If `recursive` is set to `true`, the
`file_integrity` module will watch for changes on this directories and all
their subdirectories.

*`keep_null`*:: If this option is set to true, fields with `null` values will be
published in the output document. By default, `keep_null` is set to `false`.
include::{docdir}/auditbeat-options.asciidoc[]
6 changes: 6 additions & 0 deletions auditbeat/scripts/docs_collector.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,9 @@ def collect(base_paths):
os.mkdir(os.path.join(module_docs_path(module_dir), "modules", module))

module_file = generated_note

module_file += ":modulename: " + module + "\n\n"

module_file += "[id=\"{beatname_lc}-module-" + module + "\"]\n"

with open(module_doc) as f:
Expand Down Expand Up @@ -84,6 +87,9 @@ def collect(base_paths):

module_file += "----\n\n"

# Close modulename variable
module_file += "\n:modulename!:\n\n"

module_links = ""
module_includes = ""

Expand Down
14 changes: 9 additions & 5 deletions x-pack/auditbeat/docs/modules/system.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
This file is generated! See scripts/docs_collector.py
////

:modulename: system

[id="{beatname_lc}-module-system"]
[role="xpack"]

== System Module

beta[]
Expand Down Expand Up @@ -72,8 +73,9 @@ sample suggested configuration.
user.detect_password_changes: true
----

*`period`*:: The frequency at which the datasets check for changes. For most
datasets - esp. `process` and `socket` - a shorter period is recommended.
This module also supports the
<<module-standard-options-{modulename},standard configuration options>>
described later.

*`state.period`*:: The frequency at which the datasets send full state information.
This option can be overridden per dataset using `{dataset}.state.period`.
Expand All @@ -85,8 +87,7 @@ the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` f
should be readable only by the root user and be treated similar to the shadow file
itself.

*`keep_null`*:: If this option is set to true, fields with `null` values will be
published in the output document. By default, `keep_null` is set to `false`.
include::{docdir}/auditbeat-options.asciidoc[]

[float]
=== Suggested configuration
Expand Down Expand Up @@ -151,6 +152,9 @@ auditbeat.modules:
login.btmp_file_pattern: /var/log/btmp*
----


:modulename!:

[float]
=== Datasets

Expand Down
9 changes: 4 additions & 5 deletions x-pack/auditbeat/module/system/_meta/docs.asciidoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
[role="xpack"]

== System Module

beta[]
Expand Down Expand Up @@ -67,8 +66,9 @@ sample suggested configuration.
user.detect_password_changes: true
----

*`period`*:: The frequency at which the datasets check for changes. For most
datasets - esp. `process` and `socket` - a shorter period is recommended.
This module also supports the
<<module-standard-options-{modulename},standard configuration options>>
described later.

*`state.period`*:: The frequency at which the datasets send full state information.
This option can be overridden per dataset using `{dataset}.state.period`.
Expand All @@ -80,8 +80,7 @@ the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` f
should be readable only by the root user and be treated similar to the shadow file
itself.

*`keep_null`*:: If this option is set to true, fields with `null` values will be
published in the output document. By default, `keep_null` is set to `false`.
include::{docdir}/auditbeat-options.asciidoc[]

[float]
=== Suggested configuration
Expand Down

0 comments on commit 7960c77

Please sign in to comment.