From eaf6ff31f1e3535daad77223a9d34ef2901c462c Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 18 Jan 2024 15:02:49 +0300 Subject: [PATCH] audit log: restructure the page --- .../instances.enabled/audit_log/config.yaml | 21 +- .../instances.enabled/audit_log/myapp.lua | 49 ++ .../audit_log_pipe/config.yaml | 15 +- .../audit_log_syslog/config.yaml | 18 +- doc/enterprise/audit_log.rst | 600 ++++++++++-------- .../configuration/configuration_reference.rst | 2 +- 6 files changed, 429 insertions(+), 276 deletions(-) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml index 257ef47c8a..b7ae5eeaa5 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml @@ -1,16 +1,17 @@ +audit_log: + to: file + file: 'audit_tarantool.log' + filter: [user_create,data_operations,ddl,custom] + format: json + spaces: [bands] + extract_key: true + groups: group001: - iproto: - listen: - - uri: '127.0.0.1:3301' replicasets: replicaset001: instances: instance001: - audit_log: - to: file - file: 'audit_tarantool.log' - filter: [ user_create,data_operations,ddl ] - format: json - spaces: [ bands ] - extract_key: true \ No newline at end of file + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua new file mode 100644 index 0000000000..7ed39ec1e0 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua @@ -0,0 +1,49 @@ +-- myapp.lua -- + +-- Create space +function create_space() + box.schema.space.create('Bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } }) + box.space.bands:create_index('secondary', { type = "tree", parts = { 'band_name' } }) + box.schema.user.grant('guest', 'read,write,execute', 'universe') +end +-- Insert data +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } +end + +local audit = require('audit') +-- Log message string +audit.log('Hello, Alice!') +-- Log format string and arguments +audit.log('Hello, %s!', 'Bob') +-- Log table with audit log field values +audit.log({ type = 'custom_hello', description = 'Hello, World!' }) +audit.log({ type = 'custom_farewell', user = 'eve', module = 'custom', description = 'Farewell, Eve!' }) +-- Create a new log module +local my_audit = audit.new({ type = 'custom_hello', module = 'my_module' }) +my_audit:log('Hello, Alice!') +my_audit:log({ tag = 'admin', description = 'Hello, Bob!' }) +-- Log 'Hello!' message with the VERBOSE severity level +audit.log({ severity = 'VERBOSE', description = 'Hello!' }) + +-- Log 'Hello!' message with a shortcut helper function +audit.verbose('Hello!') + +-- Like audit.log(), a shortcut helper function accepts a table of options +audit.verbose({ description = 'Hello!' }) + +-- Severity levels are available for custom loggers +local my_logger = audit.new({ module = 'my_module' }) +my_logger:log({ severity = 'ALARM', description = 'Alarm' }) +my_logger:alarm('Alarm') + +-- Overwrite session_type and remote fields +audit.log({ type = 'custom_hello', description = 'Hello!', + session_type = 'my_session', remote = 'my_remote' }) \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml index 5fbe2cdf37..1cb999804f 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml @@ -1,14 +1,13 @@ +audit_log: + to: pipe + pipe: '| cronolog audit_tarantool.log' + groups: group001: - iproto: - listen: - - uri: '127.0.0.1:3301' replicasets: replicaset001: instances: instance001: - audit_log: - to: pipe - pipe: 'cronolog audit_tarantool.log' - format: json - extract_key: false \ No newline at end of file + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file 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 index b28e40ec5c..2b2709936d 100644 --- 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,3 +1,11 @@ +audit_log: + to: syslog + syslog_server: 'unix:/dev/log' + syslog_facility: user + syslog_identity: 'tarantool' + filter: 'audit,auth,priv,password_change,access_denied' + extract_key: false + groups: group001: iproto: @@ -7,10 +15,6 @@ groups: replicaset001: instances: instance001: - audit_log: - to: syslog - syslog_server: 'unix:/dev/log' - syslog_facility: user - syslog_identity: 'tarantool' - filter: 'audit,auth,priv,password_change,access_denied' - extract_key: false \ No newline at end of file + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/enterprise/audit_log.rst b/doc/enterprise/audit_log.rst index 8ddb65d05e..bc2b719906 100644 --- a/doc/enterprise/audit_log.rst +++ b/doc/enterprise/audit_log.rst @@ -1,8 +1,10 @@ -.. _enterprise_audit_module: +.. _enterprise_audit_module: Audit module ============ +**Example on GitHub**: `audit_log `_ + The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, CSV, or JSON format. @@ -14,11 +16,235 @@ It is up to each company to decide exactly what activities to audit and what act System administrators, security engineers, and people in charge of the company may want to audit different events for different reasons. Tarantool provides such an option for each of them. -.. _audit-log-events: +.. _audit-log-configure: + +Configuring audit log +--------------------- + +The section describes how to enable and configure audit logging and write logs to a selected destination -- a file, a pipe, +or a system logger. + +Read more: :ref:`Audit log configuration reference `. + +.. _audit-log-enable: + +Enable audit logging +~~~~~~~~~~~~~~~~~~~~ + +To enable audit logging, define the log location using the +:ref:`audit_log.to ` option in the ``audit_log`` section of the configuration file. +Possible log locations: + +* a :ref:`file ` +* a :ref:`pipe ` +* a :ref:`system logger ` + +To disable audit logging, set the ``audit_log`` option to ``devnull``. + +In the configuration below, the :ref:`audit_log.to ` option is set to ``file``. +It means that the logs are written to a file. +In this case, you should also define a file path (for example, ``audit_tarantool.log``) using +the :ref:`audit_log.file ` option. +If the option is omitted, the default path is used: ``var/log/instance001/audit.log``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'audit_tarantool.log' + :dedent: + +If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. + +.. _audit-log-filters: + +Filter the events +~~~~~~~~~~~~~~~~~ + +Tarantool's extensive filtering options help you write only the events you need to the audit log. +To select the recorded events, use the :ref:`audit_log.filter ` option. +Its value can be a list of events and event groups. +You can customize the filters and use different combinations of them for your purposes. +Possible filtering options: + +- Filter by event. You can set a list of :ref:`events ` to be recorded. For example, select + ``password_change`` to monitor the users who have changed their passwords: + + .. code-block:: yaml + + audit_log: + filter: [password_change] + +- Filter by group. You can specify a list of :ref:`event groups ` to be recorded. For example, + select ``auth`` and ``priv`` to see the events related to authorization and granted privileges: + + .. code-block:: yaml + + audit_log: + filter: [auth,priv] + +- Filter by group and event. You can specify a group and a certain event depending on the purpose. + In the configuration below, ``user_create``, ``data_operations``, ``ddl``, and ``custom`` are selected to see the events related to + + * user creation + * space creation, altering, and dropping + * data modification or selection from spaces + * :ref:`custom events ` (any events added manually using the audit module API) + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: filter: + :end-at: [user_create,data_operations,ddl] + :dedent: + +.. _audit-log-format: + +Set the format of audit log events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :ref:`audit_log.format ` option to choose the format of audit log events +-- plain text, CSV, or JSON. + +JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. +The plain format can be efficiently compressed. +The CSV format allows you to view audit log events in tabular form. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: format: + :end-at: json + :dedent: + +.. _audit-log-spaces: + +Specify the spaces to be logged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since: :doc:`3.0.0 `, :ref:`audit_log.spaces ` is used to specify +a list of space names for which data operation events should be logged. + +In the configuration below, only the events from the ``bands`` space are logged: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: spaces: + :end-at: [bands] + :dedent: + +.. _audit-log-extract: + +Specify the logging mode in DML events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since: :doc:`3.0.0 `, it is possible to +force the audit subsystem to log the primary key instead of a full tuple in DML operations. +To do so, set the :ref:`audit_log.extract_key ` option to ``true``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: extract_key: + :end-at: true + :dedent: + +.. _audit-log-run-read: + +Reading audit logs +------------------ + +To read audit logs, open the file that is specified in the ``audit_log.file`` option. +In the example, this is ``audit_tarantool.log``. + +Iin the example, let's create a space ``bands`` and check the logs after the creation: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Create space + :end-before: -- Insert data + :dedent: + +The audit log entry for the ``space_create`` event might look as follows: + +.. code-block:: json + + { + "time": "2024-01-24T11:43:21.566+0300", + "uuid": "26af0a7d-1052-490a-9946-e19eacc822c9", + "severity": "INFO", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_create", + "tag": "", + "description": "Create space Bands" + } + +Then insert one tuple to space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: load_data() + :end-before: box.space.bands:insert { 2 + :dedent: + +As the ``extract_key`` option is set to ``true``, the audit system prints the primary key instead of the full tuple: + +.. code-block:: json + + { + "time": "2024-01-24T11:45:42.358+0300", + "uuid": "b437934d-62a7-419a-8d59-e3b33c688d7a", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_insert", + "tag": "", + "description": "Insert key [2] into space bands" + } + +If the ``extract_key`` option is set to ``false``, the audit system prints the full tuple like this: + +.. code-block:: json + + { + "time": "2024-01-24T11:45:42.358+0300", + "uuid": "b437934d-62a7-419a-8d59-e3b33c688d7a", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_insert", + "tag": "", + "description": "Insert tuple [1, \"Roxette\", 1986] into space bands" + } + +.. note:: + + To easily read the audit log events in the needed form, you can use these commands: + + * ``cat`` -- print one or more files + + * ``grep`` -- print a specific text + + * ``head`` -- print the first N lines of the file + + * ``tail`` -- print the last N lines of the file + + These are the basic commands to help you read the logs. If necessary, you can use other commands. + + +.. _audit-log-events: Audit log events ---------------- +.. _audit-log-events-types: + +Events types +~~~~~~~~~~~~ + The Tarantool audit log module can record various events that you can monitor and decide whether you need to take actions: @@ -33,7 +259,7 @@ decide whether you need to take actions: * System events -- events related to modification or configuration of resources. For example, such logs record the replacement of a space. -* :ref:`User-defined events `-- any events added manually using +* :ref:`Custom events `-- any events added manually using the audit module API. The full list of available audit log events is provided in the table below: @@ -48,7 +274,7 @@ The full list of available audit log events is provided in the table below: - Type of event written to the audit log - Severity level - Example of an event description - * - Audit log enabled for events + * - Audit log enabled for events - ``audit_enable`` - ``VERBOSE`` - @@ -56,15 +282,15 @@ The full list of available audit log events is provided in the table below: - ``custom`` - ``INFO`` (default) - - * - User authorized successfully + * - User authorized successfully - ``auth_ok`` - ``VERBOSE`` - ``Authenticate user `` - * - User authorization failed + * - User authorization failed - ``auth_fail`` - ``ALARM`` - ``Failed to authenticate user `` - * - User logged out or quit the session + * - User logged out or quit the session - ``disconnect`` - ``VERBOSE`` - ``Close connection`` @@ -84,11 +310,11 @@ The full list of available audit log events is provided in the table below: - ``role_drop`` - ``INFO`` - ``Drop role `` - * - User disabled + * - User disabled - ``user_disable`` - ``INFO`` - ``Disable user `` - * - User enabled + * - User enabled - ``user_enable`` - ``INFO`` - ``Enable user `` @@ -132,40 +358,40 @@ The full list of available audit log events is provided in the table below: - ``space_create`` - ``INFO`` - ``Create space `` - * - Space altered + * - Space altered - ``space_alter`` - ``INFO`` - ``Alter space `` - * - Space dropped + * - Space dropped - ``space_drop`` - ``INFO`` - ``Drop space `` - * - Tuple inserted into space + * - Tuple inserted into space - ``space_insert`` - ``VERBOSE`` - ``Insert tuple into space `` - * - Tuple replaced in space + * - Tuple replaced in space - ``space_replace`` - ``VERBOSE`` - ``Replace tuple with in space `` - * - Tuple deleted from space + * - Tuple deleted from space - ``space_delete`` - ``VERBOSE`` - ``Delete tuple from space `` .. note:: - + The ``eval`` event displays data from the ``console`` module and the ``eval`` function of the ``net.box`` module. For more on how they work, see :ref:`Module console ` - and :ref:`Module net.box -- eval `. + and :ref:`Module net.box -- eval `. To separate the data, specify ``console`` or ``binary`` in the session field. .. _audit-log-structure: Structure of audit log event ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each audit log event contains a number of fields that can be used to filter and aggregate the resulting logs. An example of a Tarantool audit log entry in JSON: @@ -199,11 +425,13 @@ Each event consists of the following fields: * - ``time`` - Time of the event - ``2024-01-15T16:33:12.368+0300`` - * - ``uuid``. Since :doc:`3.0.0 ` - - A unique identifier of audit log event + * - ``uuid`` + - Since :doc:`3.0.0 `. A unique identifier of audit log event - ``cb44fb2b-5c1f-4c4b-8f93-1dd02a76cec0`` - * - ``severity``. Since :doc:`3.0.0 ` - - A severity level + * - ``severity`` + - Since :doc:`3.0.0 `. A severity level. Each system audit event has a severity level determined by its importance. + :ref:`Custom events ` have the ``INFO`` severity level by default. + - ``VERBOSE`` * - ``remote`` - Remote host that triggered the event @@ -232,10 +460,11 @@ Each event consists of the following fields: You can set all these parameters only once. + .. _audit-log-event-groups: Event groups ------------- +~~~~~~~~~~~~ Built-in event groups are used to filter the event types that you want to audit. For example, you can set to record only authorization events, @@ -243,35 +472,35 @@ or only events related to a space. Tarantool provides the following event groups: - * ``all`` -- all :ref:`events `. +* ``all`` -- all :ref:`events `. - .. note:: + .. note:: - Events ``call`` and ``eval`` are included only in the ``all`` group. + Events ``call`` and ``eval`` are included only in the ``all`` group. - * ``audit`` -- ``audit_enable`` event. +* ``audit`` -- ``audit_enable`` event. - * ``auth`` -- authorization events: ``auth_ok``, ``auth_fail``. +* ``auth`` -- authorization events: ``auth_ok``, ``auth_fail``. - * ``priv`` -- events related to authentication, authorization, users, and roles: - ``user_create``, ``user_drop``, ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, - ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``, ``role_revoke_rights``. +* ``priv`` -- events related to authentication, authorization, users, and roles: + ``user_create``, ``user_drop``, ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, + ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``, ``role_revoke_rights``. - * ``ddl`` -- events of space creation, altering, and dropping: - ``space_create``, ``space_alter``, ``space_drop``. +* ``ddl`` -- events of space creation, altering, and dropping: + ``space_create``, ``space_alter``, ``space_drop``. - * ``dml`` -- events of data modification in spaces: - ``space_insert``, ``space_replace``, ``space_delete``. +* ``dml`` -- events of data modification in spaces: + ``space_insert``, ``space_replace``, ``space_delete``. - * ``data_operations`` -- events of data modification or selection from spaces: - ``space_select``, ``space_insert``, ``space_replace``, ``space_delete``. +* ``data_operations`` -- events of data modification or selection from spaces: + ``space_select``, ``space_insert``, ``space_replace``, ``space_delete``. - * ``compatibility`` -- events available in Tarantool before the version 2.10.0. - ``auth_ok``, ``auth_fail``, ``disconnect``, ``user_create``, ``user_drop``, - ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, - ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``. - ``role_revoke_rights``, ``password_change``, ``access_denied``. - This group enables the compatibility with earlier Tarantool versions. +* ``compatibility`` -- events available in Tarantool before the version 2.10.0. + ``auth_ok``, ``auth_fail``, ``disconnect``, ``user_create``, ``user_drop``, + ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, + ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``. + ``role_revoke_rights``, ``password_change``, ``access_denied``. + This group enables the compatibility with earlier Tarantool versions. .. warning:: @@ -280,251 +509,122 @@ Tarantool provides the following event groups: It is recommended that you select only those groups whose events your company needs to monitor and analyze. -.. _audit-log-custom: +.. _audit-log-custom: -Create user-defined events --------------------------- +Creating custom events +---------------------- Tarantool provides an API for writing user-defined audit log events. -To enable custom events, specify the ``custom`` value in the :ref:`audit_log.filter ` option. - -To add a new event, use the ``audit.log()`` function that takes one of the following values: - -* Message string. Printed to the audit log with type ``message``. - Example: ``audit.log('Hello, World!')``. - -* Format string and arguments. Passed to string format and then output to the audit log with type ``message``. - Example: ``audit.log('Hello, %s!', 'World')``. - -* Table with audit log field values. The table must contain at least one field -- ``description``. - Example: ``audit.log({type = 'custom_hello', description = 'Hello, World!'})``. - -Using the option ``audit.new()``, you can create a new log module that allows you -to avoid passing all custom audit log fields each time ``audit.log()`` is called. -It takes a table of audit log field values (same as ``audit.log()``). The ``type`` -of the log module for writing user-defined events must either be ``message`` or -have the ``custom_`` prefix. - -Example -~~~~~~~ - -.. code-block:: lua - - audit.log({type = 'custom_hello', module = 'my_module', description = 'Hello, Alice!' }) - audit.log({type = 'custom_hello', module = 'my_module', tag = 'admin', description = 'Hello, Bob!'}) - - -Some user-defined audit log fields (``time``, ``remote``, ``session_type``) -are set in the same way as for a system event. -If a field is not overwritten, it is set to the same value as for a system event. - -Some audit log fields you can overwrite with ``audit.new()`` and ``audit.log()``: - -* ``type`` -* ``user`` -* ``module`` -* ``tag`` -* ``description`` - -.. note:: - - To avoid confusion with system events, the value of the type field must either be ``message`` (default) - or begin with the ``custom_`` prefix. Otherwise, you receive the error message. - User-defined events are filtered out by default.. - - -.. _audit-log-example: - -Example: using Tarantool audit log ----------------------------------- - -The example shows how to enable and configure audit logging and write logs to a selected destination (a file, a pipe, -or a system logger). - -Before starting this example: - -#. Install the :ref:`tt ` utility. - -#. Create a tt environment in the current directory by executing the :ref:`tt init ` command. - -#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``audit_log`` directory. - -#. Inside ``instances.enabled/audit_log``, create the ``instances.yml`` and ``config.yaml`` files: - - - ``instances.yml`` specifies instances to run in the current environment and should look like this: - - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/instances.yml - :language: yaml - :end-at: instance001: - :dedent: - - - The ``config.yaml`` file stores an audit log configuration (the ``audit_log`` section). The configuration is described in detail in the next section. - -.. _audit-log-enable: - -Enable audit logging -~~~~~~~~~~~~~~~~~~~~ - -To enable audit logging, define the log location using the -:ref:`audit_log.to ` option in the ``audit_log`` section of the configuration file. -Possible logs locations: - -* a :ref:`file ` -* a :ref:`pipe ` -* a :ref:`system logger ` - -To disable audit logging, set the ``audit_log`` option to ``devnull``. - -In this tutorial, the logs are written to a file. To do this, set the -:ref:`audit_log.to ` option to ``file``. -After that, you can define a file path (for example, ``audit_tarantool.log``) using -the :ref:`audit_log.file ` option. -If the option is omitted, the default path is used: ``var/log/instance001/audit.log``. - -The configuration might look as follows: +To enable custom events, specify the ``custom`` value in the :ref:`audit_log.filter ` option: .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml :language: yaml - :start-at: audit_log: - :end-at: audit_tarantool.log + :start-at: filter: + :end-at: [user_create,data_operations,ddl,custom] :dedent: -If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. - -.. _audit-log-filters: - -Filter the events -~~~~~~~~~~~~~~~~~ - -Tarantool's extensive filtering options help you write only the events you need to the audit log. - -To select the recorded events, use the :ref:`audit_log.filter ` option. -Its value can be a list of events and event groups. -You can customize the filters and use different combinations of them for your purposes. -Possible filtering options: - -- Filter by event. You can set a list of :ref:`events ` to be recorded. For example, select - ``password_change`` to monitor the users who have changed their passwords: - - .. code-block:: yaml +.. _audit-log-custom-new: - audit_log: - filter: [ password_change ] +Add a new custom event +~~~~~~~~~~~~~~~~~~~~~~ -- Filter by group. You can specify a list of :ref:`event groups ` to be recorded. For example, - select ``auth`` and ``priv`` to see only events related to authorization and granted privileges. - - .. code-block:: yaml - - audit_log: - filter: [ auth,priv ] - -- Filter by group and event. You can specify a group and a certain event depending on the purpose. - For example, you can select ``user_create``, ``data_operations``, and ``ddl`` to see the events related to - - * user creation - * space creation, altering, and dropping - * data modification or selection from spaces +To add a new event, use the ``audit.log()`` function that takes one of the following values: - Let's add this filter to our configuration file: +* Message string. Printed to the audit log with type ``message``: - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :start-at: audit_log: - :end-at: audit_tarantool.log + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log message string + :end-before: Log format string and arguments :dedent: +* Format string and arguments. Passed to string format and then output to the audit log with type ``message``: -.. _audit-log-format: - -Set the format of audit log events -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the :ref:`audit_log.format ` option to choose the format of audit log events --- plain text, CSV, or JSON. - -JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. -The plain format can be efficiently compressed. -The CSV format allows you to view audit log events in tabular form. - -In this tutorial, set the format to JSON: - -.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :start-at: audit_log: - :end-at: format: json - :dedent: - -.. _audit-log-spaces: + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log format string and arguments + :end-before: Log table with audit log field values + :dedent: -Specify the spaces to be logged -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Table with audit log field values. The table must contain at least one field -- ``description``. -Since: :doc:`3.0.0 `, it is possible to :ref:`specify a list of space names ` -for which data operation events should be logged. + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log table with audit log field values + :end-at: description = 'Farewell, Eve!'}) + :dedent: -To log the events from the ``bands`` space only, specify the option in the configuration file: +Alternatively, you can use ``audit.new()`` to create a new log module. +This allows you to avoid passing all custom audit log fields each time ``audit.log()`` is called. +The ``audit.new()`` function takes a table of audit log field values (same as ``audit.log()``). +The ``type`` of the log module for writing custom events must either be ``message`` or have the ``custom_`` prefix. -.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml - :liines: 15 +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Create a new log module + :end-before: Log 'Hello!' message with the VERBOSE severity level :dedent: -.. _audit-log-extract: - -Specify the logging mode in DML events -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since: :doc:`3.0.0 `, it is possible to -force the audit subsystem to log the primary key instead of a full tuple in DML operations. +.. _audit-log-custom-field-overwrite: -To do so, set the :ref:`audit_log.extract_key ` option to ``true``. +Overwrite custom event fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The resulting configuration in ``config.yaml`` now looks as follows: +It is possible to overwrite most of the custom audit log :ref:`fields ` using ``audit.new()`` or ``audit.log()``. +The only audit log field that cannot be overwritten is ``time``. -.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml - :language: yaml +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Overwrite session_type and remote fields + :end-at: remote = 'my_remote'}) :dedent: -.. _audit-log-run-example: - -Check the example -~~~~~~~~~~~~~~~~~ - -After the configuration is done, execute the :ref:`tt start ` command from the :ref:`tt environment directory `: - - .. code-block:: console - - $ tt start audit_log - • Starting an instance [audit_log:instance001]... - -After that, connect to the instance with :ref:`tt connect `: +If omitted, the ``session_type`` is set to the current session type, ``remote`` is set to the remote peer address. -.. code-block:: console - - $ tt connect audit_log:instance001 +.. note:: -In the interactive console. run the following commands: + To avoid confusion with system events, the value of the type field must either be ``message`` (default) + or begin with the ``custom_`` prefix. Otherwise, you receive the error message. + User-defined events are filtered out by default. +.. _audit-log-custom-severity: -.. _audit-log-read: +Severity level +~~~~~~~~~~~~~~ -Use read commands ------------------ +By default, custom events have the ``INFO`` :ref:`severity level `. +To override the level, you can: -To easily read the audit log events in the needed form, use the different commands: +* specify the ``severity`` field +* use a shortcut function -* ``cat`` -- prints one or more files +The following shortcuts are available: -* ``grep`` -- prints a specific text +.. container:: table -* ``head`` -- prints the first N lines of the file + .. list-table:: + :widths: 40 60 + :header-rows: 1 -* ``tail`` -- prints the last N lines of the file + * - Shortcut + - Equivalent + * - ``audit.verbose(...)`` + - ``audit.log({severity = 'VERBOSE', ...})`` + * - ``audit.info(...)`` + - ``audit.log({severity = 'INFO', ...})`` + * - ``audit.warning(...)`` + - ``audit.log({severity = 'WARNING', ...})`` + * - ``audit.alarm(...)`` + - ``audit.log({severity = 'ALARM', ...})`` + +**Example** + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-at: audit.log({severity = 'VERBOSE' + :end-at: my_logger:alarm('Alarm') + :dedent: - .. note:: - - These are the basic commands to help you read the logs. If necessary, you can use other commands. .. _audit-log-tips: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index e5e55e910d..f9dcc65933 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -142,7 +142,7 @@ The ``audit_log`` section defines configuration parameters related to :ref:`audi .. note:: The option only has an effect if the :ref:`audit_log.to ` is set to ``syslog`` - ``pipe``. + or ``pipe``. | | Type: boolean