Skip to content

audit log: fix syslog config description #4036

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
audit_log:
to: syslog
syslog_server: 'unix:/dev/log'
syslog_facility: 'user'
syslog_identity: 'tarantool'
syslog:
server: 'unix:/dev/log'
facility: 'user'
identity: 'tarantool_audit'
filter: 'audit,auth,priv,password_change,access_denied'
extract_key: false

Expand Down
15 changes: 7 additions & 8 deletions doc/enterprise/security.rst
Original file line number Diff line number Diff line change
Expand Up @@ -92,17 +92,16 @@ The audit log contains:

* timestamps
* usernames of users who performed actions
* event types (e.g. ``user_create``, ``user_enable``, ``disconnect``, etc)
* event types (for example, ``user_create``, ``user_enable``, ``disconnect``)
* descriptions

You can configure the following audit log parameters:
You can configure the following audit log options:

* ``audit_log = <PATH_TO_FILE>`` which is similar to the
:ref:`log <cfg_logging-log>`
parameter. This parameter tells Tarantool to record audit events to a specific file.
* ``audit_nonblock`` which is similar to the
:ref:`log_nonblock <cfg_logging-log_nonblock>`
parameter.
* :ref:`audit_log.to <configuration_reference_audit_to>` -- enable audit logging and define the log location (file, pipe, or syslog).
The option is similar to the :ref:`log <cfg_logging-log>`.

* :ref:`audit_log.nonblock <configuration_reference_audit_nonblock>` -- specify the logging behavior if the system is not ready to write.
The option is similar to the :ref:`log_nonblock <cfg_logging-log_nonblock>`.

For more information on logging, see the following:

Expand Down
105 changes: 56 additions & 49 deletions doc/reference/configuration/configuration_reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,19 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi
``audit_log`` can be defined in any :ref:`scope <configuration_scopes>`.


* :ref:`audit_log.extract_key <configuration_reference_audit_extract_key>`
* :ref:`audit_log.file <configuration_reference_audit_file>`
* :ref:`audit_log.filter <configuration_reference_audit_filter>`
* :ref:`audit_log.format <configuration_reference_audit_format>`
* :ref:`audit_log.nonblock <configuration_reference_audit_nonblock>`
* :ref:`audit_log.pipe <configuration_reference_audit_pipe>`
* :ref:`audit_log.spaces <configuration_reference_audit_spaces>`
* :ref:`audit_log.syslog_facility <configuration_reference_audit_syslog-facility>`
* :ref:`audit_log.syslog_identity <configuration_reference_audit_syslog-identity>`
* :ref:`audit_log.syslog_server <configuration_reference_audit_syslog-server>`
* :ref:`audit_log.to <configuration_reference_audit_to>`
* :ref:`audit_log.extract_key <configuration_reference_audit_extract_key>`
* :ref:`audit_log.file <configuration_reference_audit_file>`
* :ref:`audit_log.filter <configuration_reference_audit_filter>`
* :ref:`audit_log.format <configuration_reference_audit_format>`
* :ref:`audit_log.nonblock <configuration_reference_audit_nonblock>`
* :ref:`audit_log.pipe <configuration_reference_audit_pipe>`
* :ref:`audit_log.spaces <configuration_reference_audit_spaces>`
* :ref:`audit_log.to <configuration_reference_audit_to>`
* :ref:`audit_log.syslog.* <configuration_reference_audit_syslog>`

- :ref:`audit_log.syslog.facility <configuration_reference_audit_syslog-facility>`
- :ref:`audit_log.syslog.identity <configuration_reference_audit_syslog-identity>`
- :ref:`audit_log.syslog.server <configuration_reference_audit_syslog-server>`

.. _configuration_reference_audit_extract_key:

Expand Down Expand Up @@ -207,9 +209,44 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi
| Default: box.NULL
| Environment variable: TT_AUDIT_LOG_SPACES

.. _configuration_reference_audit_to:

.. confval:: audit_log.to

Enable audit logging and define the log location.
This option accepts the following values:

- ``devnull``: disable audit logging.
- ``file``: write audit logs to a file (see :ref:`audit_log.file <configuration_reference_audit_file>`).
- ``pipe``: start a program and write audit logs to it (see :ref:`audit_log.pipe <configuration_reference_audit_pipe>`).
- ``syslog``: write audit logs to a system logger (see :ref:`audit_log.syslog.* <configuration_reference_audit_syslog>`).

By default, audit logging is disabled.

**Example**

The basic audit log configuration might look as follows:

.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml
:language: yaml
:start-at: audit_log
:end-at: extract_key: true
:dedent:

|
| Type: string
| Possible values: 'devnull', 'file', 'pipe', 'syslog'
| Default: 'devnull'
| Environment variable: TT_AUDIT_LOG_TO

.. _configuration_reference_audit_syslog:

audit_log.syslog.*
~~~~~~~~~~~~~~~~~~

.. _configuration_reference_audit_syslog-facility:

.. confval:: audit_log.syslog_facility
.. confval:: audit_log.syslog.facility

Specify a system logger keyword that tells `syslogd <https://datatracker.ietf.org/doc/html/rfc5424>`__ where to send the message.
You can enable logging to a system logger using the :ref:`audit_log.to <configuration_reference_audit_to>` option.
Expand All @@ -224,7 +261,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi

.. _configuration_reference_audit_syslog-identity:

.. confval:: audit_log.syslog_identity
.. confval:: audit_log.syslog.identity

Specify an application name to show in logs.
You can enable logging to a system logger using the :ref:`audit_log.to <configuration_reference_audit_to>` option.
Expand All @@ -238,7 +275,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi

.. _configuration_reference_audit_syslog-server:

.. confval:: audit_log.syslog_server
.. confval:: audit_log.syslog.server

Set a location for the syslog server.
It can be a Unix socket path starting with 'unix:' or an ipv4 port number.
Expand All @@ -251,15 +288,15 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml
:language: yaml
:start-at: audit_log:
:end-at: 'tarantool'
:end-at: 'tarantool_audit'
:dedent:

- :ref:`audit_log.syslog_server <configuration_reference_audit_syslog-server>` -- a syslog server location.
- :ref:`audit_log.syslog.server <configuration_reference_audit_syslog-server>` -- a syslog server location.

- :ref:`audit_log.syslog_facility <configuration_reference_audit_syslog-facility>` -- a system logger keyword that tells syslogd where to send the message.
- :ref:`audit_log.syslog.facility <configuration_reference_audit_syslog-facility>` -- a system logger keyword that tells syslogd where to send the message.
The default value is ``local7``.

- :ref:`audit_log.syslog_identity <configuration_reference_audit_syslog-identity>` -- an application name to show in logs.
- :ref:`audit_log.syslog.identity <configuration_reference_audit_syslog-identity>` -- an application name to show in logs.
The default value is ``tarantool``.

These options are interpreted as a message for the `syslogd <https://datatracker.ietf.org/doc/html/rfc5424>`_ program,
Expand All @@ -269,7 +306,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi

.. code-block:: text

09:32:52 tarantool: {"time": "2024-02-08T09:32:52.190+0300", "uuid": "94454e46-9a0e-493a-bb9f-d59e44a43581", "severity": "INFO", "remote": "unix/:(socket)", "session_type": "console", "module": "tarantool", "user": "admin", "type": "space_create", "tag": "", "description": "Create space bands"}
09:32:52 tarantool_audit: {"time": "2024-02-08T09:32:52.190+0300", "uuid": "94454e46-9a0e-493a-bb9f-d59e44a43581", "severity": "INFO", "remote": "unix/:(socket)", "session_type": "console", "module": "tarantool", "user": "admin", "type": "space_create", "tag": "", "description": "Create space bands"}

.. warning::

Expand All @@ -283,36 +320,6 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi
| Default: box.NULL
| Environment variable: TT_AUDIT_LOG_SYSLOG_SERVER

.. _configuration_reference_audit_to:

.. confval:: audit_log.to

Enable audit logging and define the log location.
This option accepts the following values:

- ``devnull``: disable audit logging.
- ``file``: write audit logs to a file (see :ref:`audit_log.file <configuration_reference_audit_file>`).
- ``pipe``: start a program and write audit logs to it (see :ref:`audit_log.pipe <configuration_reference_audit_pipe>`).
- ``syslog``: write audit logs to a system logger (see :ref:`audit_log.syslog <configuration_reference_audit_pipe>`).

By default, audit logging is disabled.

**Example**

The basic audit log configuration might look as follows:

.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml
:language: yaml
:start-at: audit_log
:end-at: extract_key: true
:dedent:

|
| Type: string
| Possible values: 'devnull', 'file', 'pipe', 'syslog'
| Default: 'devnull'
| Environment variable: TT_AUDIT_LOG_TO

.. _configuration_reference_config:

config
Expand Down