From 9214ece6cae822d362d08bfce25c8c7c4f07b1b6 Mon Sep 17 00:00:00 2001 From: lenkis Date: Fri, 16 Feb 2024 21:32:56 +0300 Subject: [PATCH 1/8] Add audit log params to box.cfg reference (draft 1) --- doc/reference/configuration/cfg_audit.rst | 304 ++++++++++++++++++++++ doc/reference/configuration/index.rst | 5 + 2 files changed, 309 insertions(+) create mode 100644 doc/reference/configuration/cfg_audit.rst diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst new file mode 100644 index 0000000000..3283a1e797 --- /dev/null +++ b/doc/reference/configuration/cfg_audit.rst @@ -0,0 +1,304 @@ +.. _cfg_audit: + +.. admonition:: Enterprise Edition + :class: fact + + The audit log is available in the `Enterprise Edition `_ only. + + +The ``audit_log`` section defines configuration parameters related to :ref:`audit logging `. + +.. NOTE:: + + ``audit_log`` can be defined in any :ref:`scope `. + +* :ref:`audit_log.extract_key ` +* :ref:`audit_log.file ` +* :ref:`audit_log.filter ` +* :ref:`audit_log.format ` +* :ref:`audit_log.nonblock ` +* :ref:`audit_log.pipe ` +* :ref:`audit_log.spaces ` +* :ref:`audit_log.to ` +* :ref:`audit_log.syslog.* ` + + - :ref:`audit_log.syslog.facility ` + - :ref:`audit_log.syslog.identity ` + - :ref:`audit_log.syslog.server ` + +.. _configuration_reference_audit_extract_key: + +.. confval:: audit_log.extract_key + + **Since:** :doc:`3.0.0 `. + + If set to ``true``, the audit subsystem extracts and prints only the primary key instead of full + tuples in DML events (``space_insert``, ``space_replace``, ``space_delete``). + Otherwise, full tuples are logged. + The option may be useful in case tuples are big. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_EXTRACT_KEY + +.. _configuration_reference_audit_file: + +.. confval:: audit_log.file + + Specify a file for the audit log destination. + You can set the ``file`` type using the :ref:`audit_log.to ` option. + If you write logs to a file, Tarantool reopens the audit log at `SIGHUP `_. + + | + | Type: string + | Default: 'var/log/{{ instance_name }}/audit.log' + | Environment variable: TT_AUDIT_LOG_FILE + +.. _configuration_reference_audit_filter: + +.. confval:: audit_log.filter + + Enable logging for a specified subset of audit events. + This option accepts the following values: + + * Event names (for example, ``password_change``). For details, see :ref:`Audit log events `. + * Event groups (for example, ``audit``). For details, see :ref:`Event groups `. + + The option contains either one value from ``Possible values`` section (see below) or a combination of them. + + To enable :ref:`custom audit log events `, specify the ``custom`` value in this option. + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-at: filter: + :end-at: custom ] + :dedent: + + | + | Type: array + | Possible values: 'all', 'audit', 'auth', 'priv', 'ddl', 'dml', 'data_operations', 'compatibility', + 'audit_enable', 'auth_ok', 'auth_fail', 'disconnect', 'user_create', 'user_drop', 'role_create', 'role_drop', + 'user_disable', 'user_enable', 'user_grant_rights', 'role_grant_rights', 'role_revoke_rights', 'password_change', + 'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert', + 'space_replace', 'space_delete', 'custom' + | Default: 'nil' + | Environment variable: TT_AUDIT_LOG_FILTER + +.. _configuration_reference_audit_format: + +.. confval:: audit_log.format + + Specify a format that is used for the audit log. + + **Example** + + If you set the option to ``plain``, + + .. code-block:: yaml + + audit_log: + to: file + format: plain + + the output in the file might look as follows: + + .. code-block:: text + + 2024-01-17T00:12:27.155+0300 + 4b5a2624-28e5-4b08-83c7-035a0c5a1db9 + INFO remote:unix/:(socket) + session_type:console + module:tarantool + user:admin + type:space_create + tag: + description:Create space Bands + + | + | Type: string + | Possible values: 'json', 'csv', 'plain' + | Default: 'json' + | Environment variable: TT_AUDIT_LOG_FORMAT + +.. _configuration_reference_audit_nonblock: + +.. confval:: audit_log.nonblock + + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. + + .. note:: + + The option only has an effect if the :ref:`audit_log.to ` is set to ``syslog`` + or ``pipe``. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_NONBLOCK + +.. _configuration_reference_audit_pipe: + +.. confval:: audit_log.pipe + + Specify a pipe for the audit log destination. + You can set the ``pipe`` type using the :ref:`audit_log.to ` option. + If log is a program, its pid is stored in the ``audit.pid`` field. + You need to send it a signal to rotate logs. + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: '| cronolog audit_tarantool.log' + :dedent: + + This starts the `cronolog `_ program when the server starts + and sends all ``audit_log`` messages to cronolog standard input (``stdin``). + If the ``audit_log`` string starts with '|', + the string is interpreted as a Unix `pipeline `_. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_PIPE + +.. _configuration_reference_audit_spaces: + +.. confval:: audit_log.spaces + + **Since:** :doc:`3.0.0 `. + + The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``, + ``space_delete``) should be logged. The array accepts string values. + If set to :ref:`box.NULL `, the data operation events are logged for all spaces. + + **Example** + + In the example, only the events of ``bands`` and ``singers`` spaces are logged: + + .. code-block:: yaml + + audit_log: + spaces: [bands, singers] + + | + | Type: array + | 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 `). + - ``pipe``: start a program and write audit logs to it (see :ref:`audit_log.pipe `). + - ``syslog``: write audit logs to a system logger (see :ref:`audit_log.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 + + Specify a system logger keyword that tells `syslogd `__ where to send the message. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + + See also: :ref:`syslog configuration example `. + + | + | Type: string + | Possible values: 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'security', 'syslog', 'user', 'uucp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' + | Default: 'local7' + | Environment variable: TT_AUDIT_LOG_SYSLOG_FACILITY + +.. _configuration_reference_audit_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 ` option. + + See also: :ref:`syslog configuration example `. + + | + | Type: string + | Default: 'tarantool' + | Environment variable: TT_AUDIT_LOG_SYSLOG_IDENTITY + +.. _configuration_reference_audit_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. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + +.. _configuration_reference_audit_syslog-example: + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'tarantool_audit' + :dedent: + + - :ref:`audit_log.syslog.server ` -- a syslog server location. + + - :ref:`audit_log.syslog.facility ` -- a system logger keyword that tells syslogd where to send the message. + The default value is ``local7``. + + - :ref:`audit_log.syslog.identity ` -- an application name to show in logs. + The default value is ``tarantool``. + + These options are interpreted as a message for the `syslogd `_ program, + which runs in the background of any Unix-like platform. + + An example of a Tarantool audit log entry in the syslog: + + .. code-block:: text + + 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:: + + Above is an example of writing audit logs to a directory shared with the system logs. + Tarantool allows this option, but it is not recommended to do this to avoid difficulties + when working with audit logs. System and audit logs should be written separately. + To do this, create separate paths and specify them. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_SYSLOG_SERVER diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index 55b828cb4f..da469b4f4a 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -60,6 +60,11 @@ Logging .. include:: cfg_logging.rst +Audit log +--------- + +.. include:: cfg_audit.rst + Authentication -------------- From 503337027f2c56e48d723d2e2c99dbbc829d2442 Mon Sep 17 00:00:00 2001 From: lenkis Date: Mon, 19 Feb 2024 18:05:01 +0300 Subject: [PATCH 2/8] Revised audit-log-related params for box.cfg 3.x --- doc/reference/configuration/cfg_audit.rst | 303 ++++++++-------------- 1 file changed, 110 insertions(+), 193 deletions(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index 3283a1e797..dd555dc9f1 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -3,32 +3,20 @@ .. admonition:: Enterprise Edition :class: fact - The audit log is available in the `Enterprise Edition `_ only. + Audit log features are available in the `Enterprise Edition `_ only. +The ``audit_*`` parameters define configuration related to :ref:`audit logging `. -The ``audit_log`` section defines configuration parameters related to :ref:`audit logging `. +* :ref:`audit_extract_key ` +* :ref:`audit_filter ` +* :ref:`audit_format ` +* :ref:`audit_log ` +* :ref:`audit_nonblock ` +* :ref:`audit_spaces ` -.. NOTE:: +.. _cfg_audit_extract_key: - ``audit_log`` can be defined in any :ref:`scope `. - -* :ref:`audit_log.extract_key ` -* :ref:`audit_log.file ` -* :ref:`audit_log.filter ` -* :ref:`audit_log.format ` -* :ref:`audit_log.nonblock ` -* :ref:`audit_log.pipe ` -* :ref:`audit_log.spaces ` -* :ref:`audit_log.to ` -* :ref:`audit_log.syslog.* ` - - - :ref:`audit_log.syslog.facility ` - - :ref:`audit_log.syslog.identity ` - - :ref:`audit_log.syslog.server ` - -.. _configuration_reference_audit_extract_key: - -.. confval:: audit_log.extract_key +.. confval:: audit_extract_key **Since:** :doc:`3.0.0 `. @@ -40,24 +28,11 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi | | Type: boolean | Default: false - | Environment variable: TT_AUDIT_LOG_EXTRACT_KEY + | Environment variable: TT_AUDIT_LOG_EXTRACT_KEY ??? -.. _configuration_reference_audit_file: +.. _cfg_audit_filter: -.. confval:: audit_log.file - - Specify a file for the audit log destination. - You can set the ``file`` type using the :ref:`audit_log.to ` option. - If you write logs to a file, Tarantool reopens the audit log at `SIGHUP `_. - - | - | Type: string - | Default: 'var/log/{{ instance_name }}/audit.log' - | Environment variable: TT_AUDIT_LOG_FILE - -.. _configuration_reference_audit_filter: - -.. confval:: audit_log.filter +.. confval:: audit_filter Enable logging for a specified subset of audit events. This option accepts the following values: @@ -69,13 +44,16 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi To enable :ref:`custom audit log events `, specify the ``custom`` value in this option. + The default value is ``compatibility``, which enables logging of all events available before 2.10.0. + **Example** - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua - :language: lua - :start-at: filter: - :end-at: custom ] - :dedent: + .. code-block:: lua + + box.cfg{ + audit_log = 'audit.log', + audit_filter = 'audit,auth,priv,password_change,access_denied' + } | | Type: array @@ -84,117 +62,76 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi 'user_disable', 'user_enable', 'user_grant_rights', 'role_grant_rights', 'role_revoke_rights', 'password_change', 'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert', 'space_replace', 'space_delete', 'custom' - | Default: 'nil' - | Environment variable: TT_AUDIT_LOG_FILTER + | Default: 'compatibility' + | Environment variable: TT_AUDIT_LOG_FILTER ??? -.. _configuration_reference_audit_format: +.. _cfg_audit_format: -.. confval:: audit_log.format +.. confval:: audit_format - Specify a format that is used for the audit log. + Specify the format that is used for the audit log events -- plain text, CSV or JSON format. - **Example** + Plain text is used by default. This human-readable format can be efficiently compressed. - If you set the option to ``plain``, + .. code-block:: lua - .. code-block:: yaml - - audit_log: - to: file - format: plain + box.cfg{audit_log = 'audit.log', audit_format = 'plain'} - the output in the file might look as follows: + **Example** .. code-block:: text - 2024-01-17T00:12:27.155+0300 - 4b5a2624-28e5-4b08-83c7-035a0c5a1db9 - INFO remote:unix/:(socket) - session_type:console - module:tarantool - user:admin - type:space_create - tag: - description:Create space Bands - - | - | Type: string - | Possible values: 'json', 'csv', 'plain' - | Default: 'json' - | Environment variable: TT_AUDIT_LOG_FORMAT - -.. _configuration_reference_audit_nonblock: - -.. confval:: audit_log.nonblock - - Specify the logging behavior if the system is not ready to write. - If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. - Using this value may improve logging performance at the cost of losing some log messages. + remote: + session_type:background + module:common.admin.auth + user: type:custom_tdg_audit + tag:tdg_severity_INFO + description:[5e35b406-4274-4903-857b-c80115275940] + subj: "anonymous", + msg: "Access granted to anonymous user" - .. note:: + The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed. - The option only has an effect if the :ref:`audit_log.to ` is set to ``syslog`` - or ``pipe``. + .. code-block:: lua - | - | Type: boolean - | Default: false - | Environment variable: TT_AUDIT_LOG_NONBLOCK - -.. _configuration_reference_audit_pipe: - -.. confval:: audit_log.pipe - - Specify a pipe for the audit log destination. - You can set the ``pipe`` type using the :ref:`audit_log.to ` option. - If log is a program, its pid is stored in the ``audit.pid`` field. - You need to send it a signal to rotate logs. + box.cfg{audit_log = 'audit.log', audit_format = 'json'} **Example** - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml - :language: yaml - :start-at: audit_log: - :end-at: '| cronolog audit_tarantool.log' - :dedent: + .. code-block:: json - This starts the `cronolog `_ program when the server starts - and sends all ``audit_log`` messages to cronolog standard input (``stdin``). - If the ``audit_log`` string starts with '|', - the string is interpreted as a Unix `pipeline `_. + { + "time": "2022-11-17T21:55:49.880+0300", + "remote": "", + "session_type": "background", + "module": "common.admin.auth", + "user": "", + "type": "custom_tdg_audit", + "tag": "tdg_severity_INFO", + "description": "[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \"anonymous\", msg: \"Access granted to anonymous user\"" + } - | - | Type: string - | Default: box.NULL - | Environment variable: TT_AUDIT_LOG_PIPE - -.. _configuration_reference_audit_spaces: - -.. confval:: audit_log.spaces + Using the CSV format allows you to view audit log events in tabular form. - **Since:** :doc:`3.0.0 `. + .. code-block:: lua - The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``, - ``space_delete``) should be logged. The array accepts string values. - If set to :ref:`box.NULL `, the data operation events are logged for all spaces. + box.cfg{audit_log = 'audit.log', audit_format = 'csv'} **Example** - In the example, only the events of ``bands`` and ``singers`` spaces are logged: - - .. code-block:: yaml + .. code-block:: text - audit_log: - spaces: [bands, singers] + 2022-11-17T21:58:03.131+0300,,background,common.admin.auth,,,custom_tdg_audit,tdg_severity_INFO,"[b3dfe2a3-ec29-4e61-b747-eb2332c83b2e] subj: ""anonymous"", msg: ""Access granted to anonymous user""" | - | Type: array - | Default: box.NULL - | Environment variable: TT_AUDIT_LOG_SPACES + | Type: string + | Possible values: 'json', 'csv', 'plain' + | Default: 'json' + | Environment variable: TT_AUDIT_LOG_FORMAT ??? -.. _configuration_reference_audit_to: +.. _cfg_audit_log: -.. confval:: audit_log.to +.. confval:: audit_log Enable audit logging and define the log location. This option accepts the following values: @@ -206,99 +143,79 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi By default, audit logging is disabled. - **Example** + **Examples** - The basic audit log configuration might look as follows: + Writing to a file: - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :start-at: audit_log - :end-at: extract_key: true - :dedent: + .. code-block:: lua - | - | 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 + box.cfg{audit_log = 'audit_tarantool.log'} + -- or + box.cfg{audit_log = 'file:audit_tarantool.log'} - Specify a system logger keyword that tells `syslogd `__ where to send the message. - You can enable logging to a system logger using the :ref:`audit_log.to ` option. + This opens the ``audit_tarantool.log`` file for output in the server’s default directory. + If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path. - See also: :ref:`syslog configuration example `. + Sending to a pipe - | - | Type: string - | Possible values: 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'security', 'syslog', 'user', 'uucp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' - | Default: 'local7' - | Environment variable: TT_AUDIT_LOG_SYSLOG_FACILITY - -.. _configuration_reference_audit_syslog-identity: + .. code-block:: lua -.. confval:: audit_log.syslog.identity + box.cfg{audit_log = '| cronolog audit_tarantool.log'} + -- or + box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}' - Specify an application name to show in logs. - You can enable logging to a system logger using the :ref:`audit_log.to ` option. - - See also: :ref:`syslog configuration example `. + This starts the `cronolog `_ program when the server starts + and sends all ``audit_log`` messages to cronolog's standard input (``stdin``). + If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, + the string is interpreted as a Unix `pipeline `_. | | Type: string - | Default: 'tarantool' - | Environment variable: TT_AUDIT_LOG_SYSLOG_IDENTITY + | Possible values: 'devnull', 'file', 'pipe', 'syslog' + | Default: 'devnull' + | Environment variable: TT_AUDIT_LOG_TO ??? -.. _configuration_reference_audit_syslog-server: +.. _cfg_audit_nonblock: -.. confval:: audit_log.syslog.server +.. confval:: audit_nonblock - Set a location for the syslog server. - It can be a Unix socket path starting with 'unix:' or an ipv4 port number. - You can enable logging to a system logger using the :ref:`audit_log.to ` option. + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. -.. _configuration_reference_audit_syslog-example: + .. note:: - **Example** + The option only has an effect if the :ref:`audit_log ` is set to ``syslog`` + or ``pipe``. - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml - :language: yaml - :start-at: audit_log: - :end-at: 'tarantool_audit' - :dedent: + Setting ``audit_nonblock`` to ``true`` is not allowed if the output is to a file. + In this case, set ``audit_nonblock`` to ``false``. - - :ref:`audit_log.syslog.server ` -- a syslog server location. + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_NONBLOCK ??? - - :ref:`audit_log.syslog.facility ` -- a system logger keyword that tells syslogd where to send the message. - The default value is ``local7``. +.. _configuration_reference_audit_spaces: - - :ref:`audit_log.syslog.identity ` -- an application name to show in logs. - The default value is ``tarantool``. +.. confval:: audit_log.spaces - These options are interpreted as a message for the `syslogd `_ program, - which runs in the background of any Unix-like platform. + **Since:** :doc:`3.0.0 `. - An example of a Tarantool audit log entry in the syslog: + The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``, + ``space_delete``) should be logged. The array accepts string values. + If set to :ref:`box.NULL `, the data operation events are logged for all spaces. - .. code-block:: text + **Example** - 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"} + In the example, only the events of ``bands`` and ``singers`` spaces are logged: - .. warning:: + .. code-block:: yaml - Above is an example of writing audit logs to a directory shared with the system logs. - Tarantool allows this option, but it is not recommended to do this to avoid difficulties - when working with audit logs. System and audit logs should be written separately. - To do this, create separate paths and specify them. + audit_log: + spaces: [bands, singers] | - | Type: string + | Type: array | Default: box.NULL - | Environment variable: TT_AUDIT_LOG_SYSLOG_SERVER + | Environment variable: TT_AUDIT_LOG_SPACES ??? From 8cb680a68e9baabaf23462c0ee133f02a038c6bb Mon Sep 17 00:00:00 2001 From: lenkis Date: Mon, 19 Feb 2024 18:17:33 +0300 Subject: [PATCH 3/8] Updated env var names, fixed markup bugs --- doc/reference/configuration/cfg_audit.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index dd555dc9f1..6da42f1e50 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -28,7 +28,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | | Type: boolean | Default: false - | Environment variable: TT_AUDIT_LOG_EXTRACT_KEY ??? + | Environment variable: TT_AUDIT_EXTRACT_KEY .. _cfg_audit_filter: @@ -50,7 +50,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < .. code-block:: lua - box.cfg{ + box.cfg{ audit_log = 'audit.log', audit_filter = 'audit,auth,priv,password_change,access_denied' } @@ -63,7 +63,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < 'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert', 'space_replace', 'space_delete', 'custom' | Default: 'compatibility' - | Environment variable: TT_AUDIT_LOG_FILTER ??? + | Environment variable: TT_AUDIT_FILTER .. _cfg_audit_format: @@ -127,7 +127,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | Type: string | Possible values: 'json', 'csv', 'plain' | Default: 'json' - | Environment variable: TT_AUDIT_LOG_FORMAT ??? + | Environment variable: TT_AUDIT_FORMAT .. _cfg_audit_log: @@ -173,7 +173,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | Type: string | Possible values: 'devnull', 'file', 'pipe', 'syslog' | Default: 'devnull' - | Environment variable: TT_AUDIT_LOG_TO ??? + | Environment variable: TT_AUDIT_LOG .. _cfg_audit_nonblock: @@ -194,7 +194,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | | Type: boolean | Default: false - | Environment variable: TT_AUDIT_LOG_NONBLOCK ??? + | Environment variable: TT_AUDIT_NONBLOCK .. _configuration_reference_audit_spaces: @@ -218,4 +218,4 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | | Type: array | Default: box.NULL - | Environment variable: TT_AUDIT_LOG_SPACES ??? + | Environment variable: TT_AUDIT_SPACES From 15a40e24250c3fc864e9f1d0d292512b3ba87bae Mon Sep 17 00:00:00 2001 From: lenkis Date: Tue, 20 Feb 2024 10:49:28 +0300 Subject: [PATCH 4/8] Fixed a link --- doc/reference/configuration/cfg_audit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index 6da42f1e50..158a5d1746 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -196,7 +196,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | Default: false | Environment variable: TT_AUDIT_NONBLOCK -.. _configuration_reference_audit_spaces: +.. _cfg_audit_spaces: .. confval:: audit_log.spaces From 002dd4622550237612cbb204ac3350311b624be3 Mon Sep 17 00:00:00 2001 From: lenkis Date: Tue, 20 Feb 2024 11:45:57 +0300 Subject: [PATCH 5/8] Integrated feedback from Andrey Aksenov (peer review) --- doc/reference/configuration/cfg_audit.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index 158a5d1746..1537a278e7 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -137,9 +137,9 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < This option accepts the following values: - ``devnull``: disable audit logging. - - ``file``: write audit logs to a file (see :ref:`audit_log.file `). - - ``pipe``: start a program and write audit logs to it (see :ref:`audit_log.pipe `). - - ``syslog``: write audit logs to a system logger (see :ref:`audit_log.syslog.* `). + - ``file``: write audit logs to a file. + - ``pipe``: start a program and write audit logs to it. + - ``syslog``: write audit logs to a system logger. By default, audit logging is disabled. @@ -198,7 +198,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < .. _cfg_audit_spaces: -.. confval:: audit_log.spaces +.. confval:: audit_spaces **Since:** :doc:`3.0.0 `. @@ -210,10 +210,11 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < In the example, only the events of ``bands`` and ``singers`` spaces are logged: - .. code-block:: yaml + .. code-block:: lua - audit_log: - spaces: [bands, singers] + box.cfg{ + audit_spaces = 'bands,singers' + } | | Type: array From 85536aa63274e9e8d23363476d36846e8960d9d6 Mon Sep 17 00:00:00 2001 From: lenkis Date: Tue, 20 Feb 2024 13:04:31 +0300 Subject: [PATCH 6/8] Integrated more feedback from Andrey Aksenov (peer review 2) --- doc/reference/configuration/cfg_audit.rst | 103 +++++++++++++++++++--- 1 file changed, 92 insertions(+), 11 deletions(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index 1537a278e7..f932d4afb6 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -134,18 +134,19 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < .. confval:: audit_log 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. - - ``pipe``: start a program and write audit logs to it. - - ``syslog``: write audit logs to a system logger. + This option accepts a string value that allows you to define the log location. + The following locations are supported: - By default, audit logging is disabled. + - File: to write audit logs to a file, specify a path to a file (with an optional `file` prefix) + - Pipeline: to start a program and write audit logs to it, specify a program name (with `|` or `pipe` prefix) + - System log: to write audit logs to a system log, specify a message for `syslogd` (with `syslog` prefix) - **Examples** + See the examples below. + + By default, audit logging is disabled. - Writing to a file: + **Example: Writing to a file** .. code-block:: lua @@ -156,7 +157,9 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < This opens the ``audit_tarantool.log`` file for output in the server’s default directory. If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path. - Sending to a pipe + If you log to a file, Tarantool will reopen the audit log at `SIGHUP `_. + + **Example: Sending to a pipeline** .. code-block:: lua @@ -169,10 +172,88 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, the string is interpreted as a Unix `pipeline `_. + **Example: Writing to a system log** + + .. warning:: + + Below is an example of writing audit logs to a directory shared with the system logs. + Tarantool allows this option, but it is **not recommended** to do this to avoid difficulties + when working with audit logs. System and audit logs should be written separately. + To do this, create separate paths and specify them. + + This sample configuration sends the audit log to syslog: + + .. code-block:: lua + + box.cfg{audit_log = 'syslog:identity=tarantool'} + -- or + box.cfg{audit_log = 'syslog:facility=user'} + -- or + box.cfg{audit_log = 'syslog:identity=tarantool,facility=user'} + -- or + box.cfg{audit_log = 'syslog:server=unix:/dev/log'} + + If the ``audit_log`` string starts with "syslog:", + it is interpreted as a message for the `syslogd `_ program, + which normally runs in the background of any Unix-like platform. + The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', 'syslog:server=...' or a combination. + + The ``syslog:identity`` setting is an arbitrary string that is placed at the beginning of all messages. + The default value is ``tarantool``. + + The ``syslog:facility`` setting is currently ignored, but will be used in the future. + The value must be one of the `syslog `_ keywords + that tell ``syslogd`` where to send the message. + The possible values are ``auth``, ``authpriv``, ``cron``, ``daemon``, ``ftp``, + ``kern``, ``lpr``, ``mail``, ``news``, ``security``, ``syslog``, ``user``, ``uucp``, + ``local0``, ``local1``, ``local2``, ``local3``, ``local4``, ``local5``, ``local6``, ``local7``. + The default value is ``local7``. + + The ``syslog:server`` setting is the locator for the syslog server. + It can be a Unix socket path starting with "unix:" or an ipv4 port number. + The default socket value is ``/dev/log`` (on Linux) or ``/var/run/syslog`` (on Mac OS). + The default port value is 514, which is the UDP port. + + An example of a Tarantool audit log entry in the syslog: + + .. code-block:: json + + { + "__CURSOR" : "s=81564632436a4de590e80b89b0151148;i=11519;b=def80c1464fe49d1aac8a64895d6614d;m=8c825ebfc;t=5edb27a75f282;x=7eba320f7cc9ae4d", + "__REALTIME_TIMESTAMP" : "1668725698065026", + "__MONOTONIC_TIMESTAMP" : "37717666812", + "_BOOT_ID" : "def80c1464fe49d1aac8a64895d6614d", + "_UID" : "1003", + "_GID" : "1004", + "_COMM" : "tarantool", + "_EXE" : "/app/tarantool/dist/tdg-2.6.4.0.x86_64/tarantool", + "_CMDLINE" : "tarantool init.lua : core-03", + "_CAP_EFFECTIVE" : "0", + "_AUDIT_SESSION" : "1", + "_AUDIT_LOGINUID" : "1003", + "_SYSTEMD_CGROUP" : "/user.slice/user-1003.slice/user@1003.service/app.slice/app@core-03.service", + "_SYSTEMD_OWNER_UID" : "1003", + "_SYSTEMD_UNIT" : "user@1003.service", + "_SYSTEMD_USER_UNIT" : "app@core-03.service", + "_SYSTEMD_SLICE" : "user-1003.slice", + "_SYSTEMD_USER_SLICE" : "app.slice", + "_SYSTEMD_INVOCATION_ID" : "be368b4243d842ea8c06b010e0df62c2", + "_MACHINE_ID" : "2e2339725deb4bc198c54ff4a2e8d626", + "_HOSTNAME" : "vm-0.test.env", + "_TRANSPORT" : "syslog", + "PRIORITY" : "6", + "SYSLOG_FACILITY" : "23", + "SYSLOG_IDENTIFIER" : "tarantool", + "SYSLOG_PID" : "101562", + "_PID" : "101562", + "MESSAGE" : "remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[119eae0e-a691-42cc-9b4c-f14c499e6726] subj: \"anonymous\", msg: \"Access granted to anonymous user\"", + "_SOURCE_REALTIME_TIMESTAMP" : "1668725698064202" + } + | | Type: string - | Possible values: 'devnull', 'file', 'pipe', 'syslog' - | Default: 'devnull' + | Possible values: see the string format above + | Default: 'nill' | Environment variable: TT_AUDIT_LOG .. _cfg_audit_nonblock: From 7c60d923a7651117a00e25cd1a8d8214d0d864d6 Mon Sep 17 00:00:00 2001 From: lenkis Date: Tue, 20 Feb 2024 17:14:32 +0300 Subject: [PATCH 7/8] Integrated feedback from @locker (tech review) --- doc/reference/configuration/cfg_audit.rst | 24 +++++------------------ 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index f932d4afb6..4a97acb8a6 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -81,14 +81,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < .. code-block:: text - remote: - session_type:background - module:common.admin.auth - user: type:custom_tdg_audit - tag:tdg_severity_INFO - description:[5e35b406-4274-4903-857b-c80115275940] - subj: "anonymous", - msg: "Access granted to anonymous user" + remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[5e35b406-4274-4903-857b-c80115275940] subj: "anonymous", msg: "Access granted to anonymous user" The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed. @@ -100,16 +93,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < .. code-block:: json - { - "time": "2022-11-17T21:55:49.880+0300", - "remote": "", - "session_type": "background", - "module": "common.admin.auth", - "user": "", - "type": "custom_tdg_audit", - "tag": "tdg_severity_INFO", - "description": "[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \"anonymous\", msg: \"Access granted to anonymous user\"" - } + {"time": "2022-11-17T21:55:49.880+0300", "remote": "", "session_type": "background", "module": "common.admin.auth", "user": "", "type": "custom_tdg_audit", "tag": "tdg_severity_INFO", "description": "[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \"anonymous\", msg: \"Access granted to anonymous user\""} Using the CSV format allows you to view audit log events in tabular form. @@ -172,6 +156,8 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, the string is interpreted as a Unix `pipeline `_. + If log is a program, check out its pid and send it a signal to rotate logs. + **Example: Writing to a system log** .. warning:: @@ -274,7 +260,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < | | Type: boolean - | Default: false + | Default: true | Environment variable: TT_AUDIT_NONBLOCK .. _cfg_audit_spaces: From 85fcca07be8dc383477131050abbc710f9016b6b Mon Sep 17 00:00:00 2001 From: lenkis Date: Wed, 21 Feb 2024 16:18:43 +0300 Subject: [PATCH 8/8] Integrated feedback from @xuniq (peer review 3) --- doc/reference/configuration/cfg_audit.rst | 32 +---------------------- 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst index 4a97acb8a6..364cbedd7a 100644 --- a/doc/reference/configuration/cfg_audit.rst +++ b/doc/reference/configuration/cfg_audit.rst @@ -204,37 +204,7 @@ The ``audit_*`` parameters define configuration related to :ref:`audit logging < .. code-block:: json - { - "__CURSOR" : "s=81564632436a4de590e80b89b0151148;i=11519;b=def80c1464fe49d1aac8a64895d6614d;m=8c825ebfc;t=5edb27a75f282;x=7eba320f7cc9ae4d", - "__REALTIME_TIMESTAMP" : "1668725698065026", - "__MONOTONIC_TIMESTAMP" : "37717666812", - "_BOOT_ID" : "def80c1464fe49d1aac8a64895d6614d", - "_UID" : "1003", - "_GID" : "1004", - "_COMM" : "tarantool", - "_EXE" : "/app/tarantool/dist/tdg-2.6.4.0.x86_64/tarantool", - "_CMDLINE" : "tarantool init.lua : core-03", - "_CAP_EFFECTIVE" : "0", - "_AUDIT_SESSION" : "1", - "_AUDIT_LOGINUID" : "1003", - "_SYSTEMD_CGROUP" : "/user.slice/user-1003.slice/user@1003.service/app.slice/app@core-03.service", - "_SYSTEMD_OWNER_UID" : "1003", - "_SYSTEMD_UNIT" : "user@1003.service", - "_SYSTEMD_USER_UNIT" : "app@core-03.service", - "_SYSTEMD_SLICE" : "user-1003.slice", - "_SYSTEMD_USER_SLICE" : "app.slice", - "_SYSTEMD_INVOCATION_ID" : "be368b4243d842ea8c06b010e0df62c2", - "_MACHINE_ID" : "2e2339725deb4bc198c54ff4a2e8d626", - "_HOSTNAME" : "vm-0.test.env", - "_TRANSPORT" : "syslog", - "PRIORITY" : "6", - "SYSLOG_FACILITY" : "23", - "SYSLOG_IDENTIFIER" : "tarantool", - "SYSLOG_PID" : "101562", - "_PID" : "101562", - "MESSAGE" : "remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[119eae0e-a691-42cc-9b4c-f14c499e6726] subj: \"anonymous\", msg: \"Access granted to anonymous user\"", - "_SOURCE_REALTIME_TIMESTAMP" : "1668725698064202" - } + 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"} | | Type: string