Audit log: fix syslog config description (#4036)

tarantool · Feb 9, 2024 · c9e9c81 · c9e9c81
1 parent 4b018aa
commit c9e9c81
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 60 deletions.
diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml
@@ -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
 

diff --git a/doc/enterprise/security.rst b/doc/enterprise/security.rst
@@ -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:
 

diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst
@@ -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:
 
@@ -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.
@@ -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.
@@ -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.
@@ -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,
@@ -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::
 
@@ -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