[role="xpack"]
== System Module

beta[]

The `system` module collects various security related information about
a system. All datasets send both periodic state information (e.g. all currently
running processes) and real-time changes (e.g. when a new process starts
or stops).

The module is fully implemented for Linux. Some datasets are also available
for macOS (Darwin) and Windows.

[float]
=== How it works

Each dataset sends two kinds of information: state and events.

State information is sent periodically and (for some datasets) on startup.
A state update will consist of one event per object that is currently
active on the system (e.g. a process). All events belonging to the same state
update will share the same UUID in `event.id`.

The frequency of state updates can be controlled for all datasets using the
`state.period` configuration option. Overrides are available per dataset.
The default is `12h`.

Event information is sent as the events occur (e.g. a process starts or stops).
All datasets are currently using a poll model to retrieve their data.
The frequency of these polls is controlled by the `period` configuration
parameter.

[float]
==== Example dashboard

The module comes with a sample dashboard:

[role="screenshot"]
image::./images/auditbeat-system-overview-dashboard.png[Auditbeat System Overview Dashboard]

[float]
=== Configuration options

This module has some configuration options for controlling its behavior. The
following example shows all configuration options with their default values for
Linux.

NOTE: It is recommended to configure some datasets separately. See below for a
sample suggested configuration.

[source,yaml]
----
- module: system
  datasets:
    - host
    - login
    - package
    - process
    - socket
    - user
  period: 10s
  state.period: 12h

  socket.include_localhost: false

  user.detect_password_changes: true
----

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

*`state.period`*:: The interval at which the datasets send full state information.
This option can be overridden per dataset using `{dataset}.state.period`.

*`user.detect_password_changes`*:: If the `user` dataset is configured and
this option is set to `true`, Auditbeat will read password information in `/etc/passwd`
and `/etc/shadow` to detect password changes. A hash will be kept locally in
the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` file
should be readable only by the root user and be treated similar to the shadow file
itself.

include::{docdir}/auditbeat-options.asciidoc[]

[float]
=== Suggested configuration

Processes and sockets can be short-lived, so the chance of missing an update
increases if the polling interval is too large.

On the other hand, host and user information is unlikely to change frequently,
so a longer polling interval can be used.

[source,yaml]
----
- module: system
  datasets:
    - host
    - login
    - package
    - user
  period: 1m

  user.detect_password_changes: true

- module: system
  datasets:
    - process
    - socket
  period: 1s
----
