Skip to content

Commit 089122e

Browse files
p7novoleg-jukovecxuniq
authored
Add tt integrity check options (#4341)
Resolves: https://github.com/tarantool/enterprise_doc/issues/261, https://github.com/tarantool/enterprise_doc/issues/262, https://github.com/tarantool/enterprise_doc/issues/263 Co-authored-by: Oleg Jukovec <oleg.jukovec@gmail.com> Co-authored-by: Kseniia Antonova <73473519+xuniq@users.noreply.github.com>
1 parent 6400e9d commit 089122e

File tree

4 files changed

+178
-12
lines changed

4 files changed

+178
-12
lines changed

‎doc/reference/tooling/tt_cli/cluster.rst

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,48 @@ and aborts in case of an error. To skip the validation, add the ``--force`` opti
131131
132132
$ tt cluster publish myapp source.yaml --force
133133
134+
.. _tt-cluster-publish-integrity:
135+
136+
Publishing configurations with integrity check
137+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138+
139+
.. admonition:: Enterprise Edition
140+
:class: fact
141+
142+
The integrity check functionality is supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
143+
144+
When called with the ``--with-integrity-check`` option, ``tt cluster publish``
145+
generates a checksum of the configurations it publishes. It signs the checksum using
146+
the private key passed as the option argument, and writes it into the configuration store.
147+
148+
.. code-block:: console
149+
150+
$ tt cluster publish "http://localhost:2379/myapp" source.yaml --with-integrity-check private.pem
151+
152+
If an application configuration is published this way, it can be checked for integrity
153+
using the ``--integrity-check`` :ref:`global option <tt-global-options>`.
154+
155+
.. code-block:: console
156+
157+
$ tt --integrity-check public.pem cluster show myapp
158+
$ tt --integrity-check public.pem start myapp
159+
160+
Learn more about integrity checks upon application startup and in runtime in the :ref:`tt start <tt-start-integrity-check>` reference.
161+
162+
To ensure the configuration integrity when updating it, call ``tt cluster publish``
163+
with two options:
164+
165+
- ``--integrity-check PUBLIC_KEY`` global option checks that the configuration wasn't changed
166+
since it was published
167+
- ``--with-integrity-check PRIVATE_KEY`` generates new hash and signature
168+
for future integrity checks of the updated configuration.
169+
170+
.. code-block:: console
171+
172+
$ tt --integrity-check public.pem cluster publish \
173+
--with-integrity-check private.pem \
174+
"http://localhost:2379/myapp" source.yaml
175+
134176
.. _tt-cluster-show:
135177

136178
show
@@ -509,3 +551,5 @@ Options
509551
**Applicable to:** ``publish``
510552

511553
Generate hashes and signatures for integrity checks.
554+
555+
See also: :ref:`tt-cluster-publish-integrity`

‎doc/reference/tooling/tt_cli/global_options.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,16 @@ Global options
2424

2525
Display help.
2626

27+
.. option:: --integrity-check PUBLIC_KEY
28+
29+
.. admonition:: Enterprise Edition
30+
:class: fact
31+
32+
This option is supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
33+
34+
Perform an integrity check using the specified public key before executing the operation.
35+
Learn more in :ref:`tt-start-integrity-check`.
36+
2737
.. option:: -I, --internal
2838

2939
Force the use of an internal module even if there is an

‎doc/reference/tooling/tt_cli/pack.rst

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ option to the ``tt pack`` call:
5858
5959
.. important::
6060

61-
The ``systemd-unit-params.yml`` file has a higher priority than the ``--unit-params-file`` option.
61+
The ``systemd-unit-params.yml`` file has a higher priority than the ``--unit-params-file`` option.
6262
If this file exists, it overrides parameters from the file passed in the option.
6363

6464
``tt pack`` supports the following systemd unit parameters:
@@ -76,6 +76,49 @@ An example of the ``systemd-unit-params.yml`` file:
7676
INSTANCE: "inst:%i"
7777
TARANTOOL_WORKDIR: "/tmp"
7878
79+
.. _tt-pack-integrity-check:
80+
81+
Generating files for integrity checks
82+
-------------------------------------
83+
84+
.. admonition:: Enterprise Edition
85+
:class: fact
86+
87+
The integrity check functionality is supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
88+
89+
``tt pack`` can generate checksums and signatures to use for integrity checks
90+
when running the application. These files are:
91+
92+
- ``hashes.json`` and ``hashes.json.sig`` in each application directory.
93+
``hashes.json`` contains SHA256 checksums of executable files that the application uses
94+
and its configuration file. ``hashes.json.sig`` contains a digital signature
95+
for ``hashes.json``.
96+
97+
- ``env_hashes.json`` and ``env_hashes.json.sig`` in the environment root are
98+
similar files for the ``tt`` environment. They contain checksums for
99+
Tarantool and ``tt`` executables, and for the ``tt.yaml`` configuration file.
100+
101+
To generate checksums and signatures for integrity check, use the ``--with-integrity-check``
102+
option. Its argument must be an RSA private key.
103+
104+
.. note::
105+
106+
You can generate a key pair using `OpenSSL 3 <https://www.openssl.org/>`__ as follows:
107+
108+
.. code-block:: console
109+
110+
$ openssl genrsa -traditional -out private.pem 2048
111+
$ openssl rsa -in private.pem -pubout > public.pem
112+
113+
To create a ``tar.gz`` archive with integrity check artifacts:
114+
115+
.. code-block:: console
116+
117+
$ tt pack tgz --with-integrity-check private.pem
118+
119+
Learn how to perform integrity checks at the application startup and in runtime
120+
in the :ref:`tt start <tt-start-integrity-check>` reference.
121+
79122

80123
.. _tt-pack-options:
81124

@@ -210,6 +253,12 @@ Options
210253

211254
Include Tarantool and ``tt`` binaries in a bundle.
212255

256+
.. option:: --with-integrity-check PRIVATE_KEY
257+
258+
Generate checksums and signatures for integrity checks at the application startup.
259+
260+
See also: :ref:`tt-pack-integrity-check`
261+
213262
.. option:: --with-tarantool-deps
214263

215264
Add Tarantool and ``tt`` as package dependencies.

‎doc/reference/tooling/tt_cli/start.rst

Lines changed: 74 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,29 @@ inside the ``instances_enabled`` directory specified in the :ref:`tt configurati
1212
For detailed instructions on preparing and running Tarantool applications, see
1313
:ref:`admin-instance-environment-overview` and :ref:`admin-start_stop_instance`.
1414

15-
When called without arguments, starts all enabled applications in the current environment.
16-
1715
See also: :ref:`tt-stop`, :ref:`tt-restart`, :ref:`tt-status`.
1816

17+
To start all instances of the application stored in the ``app`` directory inside
18+
``instances_enabled`` in accordance with its ``instances.yml``:
19+
20+
.. code-block:: console
21+
22+
$ tt start app
23+
24+
To start the ``router`` instance of the ``app`` application:
25+
26+
.. code-block:: console
27+
28+
$ tt start app:router
29+
30+
When called without arguments, starts all enabled applications in the current environment:
31+
32+
.. code-block:: console
33+
34+
$ tt start
35+
36+
.. _tt-start-app-layout:
37+
1938
Application layout
2039
------------------
2140

@@ -38,6 +57,8 @@ For more information about Tarantool application layout, see :ref:`admin-instanc
3857
which is considered a legacy approach since Tarantool 3.0. For information
3958
about using ``tt`` with such applications, refer to the Tarantool 2.11 documentation.
4059

60+
.. _tt-start-background:
61+
4162
Running in the background
4263
-------------------------
4364

@@ -52,19 +73,61 @@ process for status checks (:ref:`tt status <tt-status>`) and application stoppin
5273
If you start such an application with ``tt start``, ``tt`` won't be able to check
5374
the application status or stop it using the corresponding commands.
5475

55-
Examples
56-
--------
76+
.. _tt-start-integrity-check:
77+
78+
Integrity check
79+
---------------
80+
81+
.. admonition:: Enterprise Edition
82+
:class: fact
83+
84+
The integrity check functionality is supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
85+
86+
``tt start`` can perform initial and periodical integrity checks of the environment,
87+
application, and centralized configuration.
88+
89+
To enable integrity checks of environment and application files, you need to pack
90+
the application using ``tt pack`` with the ``--with-integrity-check`` option.
91+
This option generates and signs checksums of executables and configuration files in the current ``tt``
92+
environment. Learn more in :ref:`tt-pack-integrity-check`.
93+
94+
To enable integrity check of the configuration at the centralized storage,
95+
publish the configuration to this storage using ``tt cluster publish`` with the ``--with-integrity-check`` option.
96+
This option generates and signs configuration checksums and saves them to the storage.
97+
Learn more in :ref:`tt-cluster-publish-integrity`.
98+
99+
To perform the integrity checks when running the application, start it with the
100+
``--integrity-check`` :ref:`global option <tt-global-options>`.
101+
Its argument must be a public key matching the private key that was used for
102+
generating checksums.
103+
104+
.. code-block:: console
105+
106+
$ tt --integrity-check public.pem start myapp
107+
108+
After such a call, ``tt`` checks the environment, application, and configuration integrity
109+
using the checksums and starts the application in case of the success. Then, integrity
110+
checks are performed periodically while the application is running. By default,
111+
they are performed once every 24 hours. You can adjust the integrity check period
112+
by adding the ``--integrity-check-period`` option:
113+
114+
.. code-block:: console
115+
116+
$ tt --integrity-check public.pem start myapp --integrity-check-period 60
57117
58-
* Start instances of the application stored in the ``app`` directory inside
59-
``instances_enabled`` in accordance with its ``instances.yml``:
118+
Additionally, Tarantool checks the integrity of the modules that the application uses
119+
at the load time, that is, when ``require('module')`` is called.
60120

61-
.. code-block:: console
121+
If an integrity check fails, ``tt`` stops the application.
62122

63-
$ tt start app
123+
.. _tt-start-options:
64124

65-
* Start the ``router`` instance of the ``app`` application:
125+
Options
126+
-------
66127

67-
.. code-block:: console
128+
.. option:: --integrity-check-interval NUMBER
68129

69-
$ tt start app:router
130+
Integrity check interval in seconds. Default: 86400 (24 hours).
131+
Set this option to ``0`` to disable periodic checks.
70132

133+
See also: :ref:`tt-start-integrity-check`

0 commit comments

Comments
 (0)