Skip to content

Commit eda7efa

Browse files
lenkislenkis
authored
Add audit log params to box.cfg reference (#4050)
Close gh-4006
1 parent 402fc2f commit eda7efa

File tree

2 files changed

+264
-0
lines changed

2 files changed

+264
-0
lines changed

‎doc/reference/configuration/cfg_audit.rst

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
.. _cfg_audit:
2+
3+
.. admonition:: Enterprise Edition
4+
:class: fact
5+
6+
Audit log features are available in the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
7+
8+
The ``audit_*`` parameters define configuration related to :ref:`audit logging <enterprise_audit_module>`.
9+
10+
* :ref:`audit_extract_key <cfg_audit_extract_key>`
11+
* :ref:`audit_filter <cfg_audit_filter>`
12+
* :ref:`audit_format <cfg_audit_format>`
13+
* :ref:`audit_log <cfg_audit_log>`
14+
* :ref:`audit_nonblock <cfg_audit_nonblock>`
15+
* :ref:`audit_spaces <cfg_audit_spaces>`
16+
17+
.. _cfg_audit_extract_key:
18+
19+
.. confval:: audit_extract_key
20+
21+
**Since:** :doc:`3.0.0 </release/3.0.0>`.
22+
23+
If set to ``true``, the audit subsystem extracts and prints only the primary key instead of full
24+
tuples in DML events (``space_insert``, ``space_replace``, ``space_delete``).
25+
Otherwise, full tuples are logged.
26+
The option may be useful in case tuples are big.
27+
28+
|
29+
| Type: boolean
30+
| Default: false
31+
| Environment variable: TT_AUDIT_EXTRACT_KEY
32+
33+
.. _cfg_audit_filter:
34+
35+
.. confval:: audit_filter
36+
37+
Enable logging for a specified subset of audit events.
38+
This option accepts the following values:
39+
40+
* Event names (for example, ``password_change``). For details, see :ref:`Audit log events <audit-log-events>`.
41+
* Event groups (for example, ``audit``). For details, see :ref:`Event groups <audit-log-event-groups>`.
42+
43+
The option contains either one value from ``Possible values`` section (see below) or a combination of them.
44+
45+
To enable :ref:`custom audit log events <audit-log-custom>`, specify the ``custom`` value in this option.
46+
47+
The default value is ``compatibility``, which enables logging of all events available before 2.10.0.
48+
49+
**Example**
50+
51+
.. code-block:: lua
52+
53+
box.cfg{
54+
audit_log = 'audit.log',
55+
audit_filter = 'audit,auth,priv,password_change,access_denied'
56+
}
57+
58+
|
59+
| Type: array
60+
| Possible values: 'all', 'audit', 'auth', 'priv', 'ddl', 'dml', 'data_operations', 'compatibility',
61+
'audit_enable', 'auth_ok', 'auth_fail', 'disconnect', 'user_create', 'user_drop', 'role_create', 'role_drop',
62+
'user_disable', 'user_enable', 'user_grant_rights', 'role_grant_rights', 'role_revoke_rights', 'password_change',
63+
'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert',
64+
'space_replace', 'space_delete', 'custom'
65+
| Default: 'compatibility'
66+
| Environment variable: TT_AUDIT_FILTER
67+
68+
.. _cfg_audit_format:
69+
70+
.. confval:: audit_format
71+
72+
Specify the format that is used for the audit log events -- plain text, CSV or JSON format.
73+
74+
Plain text is used by default. This human-readable format can be efficiently compressed.
75+
76+
.. code-block:: lua
77+
78+
box.cfg{audit_log = 'audit.log', audit_format = 'plain'}
79+
80+
**Example**
81+
82+
.. code-block:: text
83+
84+
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"
85+
86+
The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed.
87+
88+
.. code-block:: lua
89+
90+
box.cfg{audit_log = 'audit.log', audit_format = 'json'}
91+
92+
**Example**
93+
94+
.. code-block:: json
95+
96+
{"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\""}
97+
98+
Using the CSV format allows you to view audit log events in tabular form.
99+
100+
.. code-block:: lua
101+
102+
box.cfg{audit_log = 'audit.log', audit_format = 'csv'}
103+
104+
**Example**
105+
106+
.. code-block:: text
107+
108+
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"""
109+
110+
|
111+
| Type: string
112+
| Possible values: 'json', 'csv', 'plain'
113+
| Default: 'json'
114+
| Environment variable: TT_AUDIT_FORMAT
115+
116+
.. _cfg_audit_log:
117+
118+
.. confval:: audit_log
119+
120+
Enable audit logging and define the log location.
121+
122+
This option accepts a string value that allows you to define the log location.
123+
The following locations are supported:
124+
125+
- File: to write audit logs to a file, specify a path to a file (with an optional `file` prefix)
126+
- Pipeline: to start a program and write audit logs to it, specify a program name (with `|` or `pipe` prefix)
127+
- System log: to write audit logs to a system log, specify a message for `syslogd` (with `syslog` prefix)
128+
129+
See the examples below.
130+
131+
By default, audit logging is disabled.
132+
133+
**Example: Writing to a file**
134+
135+
.. code-block:: lua
136+
137+
box.cfg{audit_log = 'audit_tarantool.log'}
138+
-- or
139+
box.cfg{audit_log = 'file:audit_tarantool.log'}
140+
141+
This opens the ``audit_tarantool.log`` file for output in the server’s default directory.
142+
If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path.
143+
144+
If you log to a file, Tarantool will reopen the audit log at `SIGHUP <https://en.wikipedia.org/wiki/SIGHUP>`_.
145+
146+
**Example: Sending to a pipeline**
147+
148+
.. code-block:: lua
149+
150+
box.cfg{audit_log = '| cronolog audit_tarantool.log'}
151+
-- or
152+
box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}'
153+
154+
This starts the `cronolog <https://linux.die.net/man/1/cronolog>`_ program when the server starts
155+
and sends all ``audit_log`` messages to cronolog's standard input (``stdin``).
156+
If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``,
157+
the string is interpreted as a Unix `pipeline <https://en.wikipedia.org/wiki/Pipeline_%28Unix%29>`_.
158+
159+
If log is a program, check out its pid and send it a signal to rotate logs.
160+
161+
**Example: Writing to a system log**
162+
163+
.. warning::
164+
165+
Below is an example of writing audit logs to a directory shared with the system logs.
166+
Tarantool allows this option, but it is **not recommended** to do this to avoid difficulties
167+
when working with audit logs. System and audit logs should be written separately.
168+
To do this, create separate paths and specify them.
169+
170+
This sample configuration sends the audit log to syslog:
171+
172+
.. code-block:: lua
173+
174+
box.cfg{audit_log = 'syslog:identity=tarantool'}
175+
-- or
176+
box.cfg{audit_log = 'syslog:facility=user'}
177+
-- or
178+
box.cfg{audit_log = 'syslog:identity=tarantool,facility=user'}
179+
-- or
180+
box.cfg{audit_log = 'syslog:server=unix:/dev/log'}
181+
182+
If the ``audit_log`` string starts with "syslog:",
183+
it is interpreted as a message for the `syslogd <https://datatracker.ietf.org/doc/html/rfc5424>`_ program,
184+
which normally runs in the background of any Unix-like platform.
185+
The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', 'syslog:server=...' or a combination.
186+
187+
The ``syslog:identity`` setting is an arbitrary string that is placed at the beginning of all messages.
188+
The default value is ``tarantool``.
189+
190+
The ``syslog:facility`` setting is currently ignored, but will be used in the future.
191+
The value must be one of the `syslog <https://en.wikipedia.org/wiki/Syslog>`_ keywords
192+
that tell ``syslogd`` where to send the message.
193+
The possible values are ``auth``, ``authpriv``, ``cron``, ``daemon``, ``ftp``,
194+
``kern``, ``lpr``, ``mail``, ``news``, ``security``, ``syslog``, ``user``, ``uucp``,
195+
``local0``, ``local1``, ``local2``, ``local3``, ``local4``, ``local5``, ``local6``, ``local7``.
196+
The default value is ``local7``.
197+
198+
The ``syslog:server`` setting is the locator for the syslog server.
199+
It can be a Unix socket path starting with "unix:" or an ipv4 port number.
200+
The default socket value is ``/dev/log`` (on Linux) or ``/var/run/syslog`` (on Mac OS).
201+
The default port value is 514, which is the UDP port.
202+
203+
An example of a Tarantool audit log entry in the syslog:
204+
205+
.. code-block:: json
206+
207+
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"}
208+
209+
|
210+
| Type: string
211+
| Possible values: see the string format above
212+
| Default: 'nill'
213+
| Environment variable: TT_AUDIT_LOG
214+
215+
.. _cfg_audit_nonblock:
216+
217+
.. confval:: audit_nonblock
218+
219+
Specify the logging behavior if the system is not ready to write.
220+
If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead.
221+
Using this value may improve logging performance at the cost of losing some log messages.
222+
223+
.. note::
224+
225+
The option only has an effect if the :ref:`audit_log <cfg_audit_log>` is set to ``syslog``
226+
or ``pipe``.
227+
228+
Setting ``audit_nonblock`` to ``true`` is not allowed if the output is to a file.
229+
In this case, set ``audit_nonblock`` to ``false``.
230+
231+
|
232+
| Type: boolean
233+
| Default: true
234+
| Environment variable: TT_AUDIT_NONBLOCK
235+
236+
.. _cfg_audit_spaces:
237+
238+
.. confval:: audit_spaces
239+
240+
**Since:** :doc:`3.0.0 </release/3.0.0>`.
241+
242+
The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``,
243+
``space_delete``) should be logged. The array accepts string values.
244+
If set to :ref:`box.NULL <box-null>`, the data operation events are logged for all spaces.
245+
246+
**Example**
247+
248+
In the example, only the events of ``bands`` and ``singers`` spaces are logged:
249+
250+
.. code-block:: lua
251+
252+
box.cfg{
253+
audit_spaces = 'bands,singers'
254+
}
255+
256+
|
257+
| Type: array
258+
| Default: box.NULL
259+
| Environment variable: TT_AUDIT_SPACES

‎doc/reference/configuration/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,11 @@ Logging
6060

6161
.. include:: cfg_logging.rst
6262

63+
Audit log
64+
---------
65+
66+
.. include:: cfg_audit.rst
67+
6368
Authentication
6469
--------------
6570

0 commit comments

Comments
 (0)