diff --git a/doc/reference/tooling/tt_cli/cluster.rst b/doc/reference/tooling/tt_cli/cluster.rst index 19bee01cd..9177bb9c3 100644 --- a/doc/reference/tooling/tt_cli/cluster.rst +++ b/doc/reference/tooling/tt_cli/cluster.rst @@ -112,6 +112,48 @@ and aborts in case of an error. To skip the validation, add the ``--force`` opti $ tt cluster publish myapp source.yaml --force +.. _tt-cluster-publish-integrity: + +Publishing configurations with integrity check +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. admonition:: Enterprise Edition + :class: fact + + The integrity check functionality is supported by the `Enterprise Edition `_ only. + +When called with the ``--with-integrity-check`` option, ``tt cluster publish`` +generates a checksum of the configurations it publishes. It signs the checksum using +the private key passed as the option argument, and writes it into the configuration store. + +.. code-block:: console + + $ tt cluster publish "http://localhost:2379/myapp" source.yaml --with-integrity-check private.pem + +If an application configuration is published this way, it can be checked for integrity +using the ``--integrity-check`` :ref:`global option `. + +.. code-block:: console + + $ tt --integrity-check public.pem cluster show myapp + $ tt --integrity-check public.pem start myapp + +Learn more about integrity checks upon application startup and in runtime in the :ref:`tt start ` reference. + +To ensure the configuration integrity when updating it, call ``tt cluster publish`` +with two options: + +- ``--integrity-check PUBLIC_KEY`` global option checks that the configuration wasn't changed + since it was published +- ``--with-integrity-check PRIVATE_KEY`` generates new hash and signature + for future integrity checks of the updated configuration. + +.. code-block:: console + + $ tt --integrity-check public.pem cluster publish \ + --with-integrity-check private.pem \ + "http://localhost:2379/myapp" source.yaml + .. _tt-cluster-show: show @@ -478,3 +520,5 @@ Options **Applicable to:** ``publish`` Generate hashes and signatures for integrity checks. + + See also: :ref:`tt-cluster-publish-integrity` diff --git a/doc/reference/tooling/tt_cli/global_options.rst b/doc/reference/tooling/tt_cli/global_options.rst index 69c673d62..9c21ac960 100644 --- a/doc/reference/tooling/tt_cli/global_options.rst +++ b/doc/reference/tooling/tt_cli/global_options.rst @@ -24,6 +24,16 @@ Global options Display help. +.. option:: --integrity-check PUBLIC_KEY + + .. admonition:: Enterprise Edition + :class: fact + + This option is supported by the `Enterprise Edition `_ only. + + Perform an integrity check using the specified public key before executing the operation. + Learn more in :ref:`tt-start-integrity-check`. + .. option:: -I, --internal Force the use of an internal module even if there is an diff --git a/doc/reference/tooling/tt_cli/pack.rst b/doc/reference/tooling/tt_cli/pack.rst index 748ed4899..828627ec9 100644 --- a/doc/reference/tooling/tt_cli/pack.rst +++ b/doc/reference/tooling/tt_cli/pack.rst @@ -58,7 +58,7 @@ option to the ``tt pack`` call: .. important:: - The ``systemd-unit-params.yml`` file has a higher priority than the ``--unit-params-file`` option. + The ``systemd-unit-params.yml`` file has a higher priority than the ``--unit-params-file`` option. If this file exists, it overrides parameters from the file passed in the option. ``tt pack`` supports the following systemd unit parameters: @@ -76,6 +76,49 @@ An example of the ``systemd-unit-params.yml`` file: INSTANCE: "inst:%i" TARANTOOL_WORKDIR: "/tmp" +.. _tt-pack-integrity-check: + +Generating files for integrity checks +------------------------------------- + +.. admonition:: Enterprise Edition + :class: fact + + The integrity check functionality is supported by the `Enterprise Edition `_ only. + +``tt pack`` can generate checksums and signatures to use for integrity checks +when running the application. These files are: + +- ``hashes.json`` and ``hashes.json.sig`` in each application directory. + ``hashes.json`` contains SHA256 checksums of executable files that the application uses + and its configuration file. ``hashes.json.sig`` contains a digital signature + for ``hashes.json``. + +- ``env_hashes.json`` and ``env_hashes.json.sig`` in the environment root are + similar files for the ``tt`` environment. They contain checksums for + Tarantool and ``tt`` executables, and for the ``tt.yaml`` configuration file. + +To generate checksums and signatures for integrity check, use the ``--with-integrity-check`` +option. Its argument must be an RSA private key. + +.. note:: + + You can generate a key pair using `OpenSSL 3 `__ as follows: + + .. code-block:: console + + $ openssl genrsa -traditional -out private.pem 2048 + $ openssl rsa -in private.pem -pubout > public.pem + +To create a ``tar.gz`` archive with integrity check artifacts: + +.. code-block:: console + + $ tt pack tgz --with-integrity-check private.pem + +Learn how to perform integrity checks at the application startup and in runtime +in the :ref:`tt start ` reference. + .. _tt-pack-options: @@ -210,6 +253,12 @@ Options Include Tarantool and ``tt`` binaries in a bundle. +.. option:: --with-integrity-check PRIVATE_KEY + + Generate checksums and signatures for integrity checks at the application startup. + + See also: :ref:`tt-pack-integrity-check` + .. option:: --with-tarantool-deps Add Tarantool and ``tt`` as package dependencies. diff --git a/doc/reference/tooling/tt_cli/start.rst b/doc/reference/tooling/tt_cli/start.rst index 43d0c5c84..63e78358d 100644 --- a/doc/reference/tooling/tt_cli/start.rst +++ b/doc/reference/tooling/tt_cli/start.rst @@ -12,10 +12,29 @@ inside the ``instances_enabled`` directory specified in the :ref:`tt configurati For detailed instructions on preparing and running Tarantool applications, see :ref:`admin-instance-environment-overview` and :ref:`admin-start_stop_instance`. -When called without arguments, starts all enabled applications in the current environment. - See also: :ref:`tt-stop`, :ref:`tt-restart`, :ref:`tt-status`. +To start all instances of the application stored in the ``app`` directory inside +``instances_enabled`` in accordance with its ``instances.yml``: + +.. code-block:: console + + $ tt start app + +To start the ``router`` instance of the ``app`` application: + +.. code-block:: console + + $ tt start app:router + +When called without arguments, starts all enabled applications in the current environment: + +.. code-block:: console + + $ tt start + +.. _tt-start-app-layout: + Application layout ------------------ @@ -38,6 +57,8 @@ For more information about Tarantool application layout, see :ref:`admin-instanc which is considered a legacy approach since Tarantool 3.0. For information about using ``tt`` with such applications, refer to the Tarantool 2.11 documentation. +.. _tt-start-background: + Running in the background ------------------------- @@ -52,19 +73,61 @@ process for status checks (:ref:`tt status `) and application stoppin If you start such an application with ``tt start``, ``tt`` won't be able to check the application status or stop it using the corresponding commands. -Examples --------- +.. _tt-start-integrity-check: + +Integrity check +--------------- + +.. admonition:: Enterprise Edition + :class: fact + + The integrity check functionality is supported by the `Enterprise Edition `_ only. + +``tt start`` can perform initial and periodical integrity checks of the environment, +application, and centralized configuration. + +To enable integrity checks of environment and application files, you need to pack +the application using ``tt pack`` with the ``--with-integrity-check`` option. +This option generates and signs checksums of executables and configuration files in the current ``tt`` +environment. Learn more in :ref:`tt-pack-integrity-check`. + +To enable integrity check of the configuration at the centralized storage, +publish the configuration to this storage using ``tt cluster publish`` with the ``--with-integrity-check`` option. +This option generates and signs configuration checksums and saves them to the storage. +Learn more in :ref:`tt-cluster-publish-integrity`. + +To perform the integrity checks when running the application, start it with the +``--integrity-check`` :ref:`global option `. +Its argument must be a public key matching the private key that was used for +generating checksums. + +.. code-block:: console + + $ tt --integrity-check public.pem start myapp + +After such a call, ``tt`` checks the environment, application, and configuration integrity +using the checksums and starts the application in case of the success. Then, integrity +checks are performed periodically while the application is running. By default, +they are performed once every 24 hours. You can adjust the integrity check period +by adding the ``--integrity-check-period`` option: + +.. code-block:: console + + $ tt --integrity-check public.pem start myapp --integrity-check-period 60 -* Start instances of the application stored in the ``app`` directory inside - ``instances_enabled`` in accordance with its ``instances.yml``: +Additionally, Tarantool checks the integrity of the modules that the application uses +at the load time, that is, when ``require('module')`` is called. - .. code-block:: console +If an integrity check fails, ``tt`` stops the application. - $ tt start app +.. _tt-start-options: -* Start the ``router`` instance of the ``app`` application: +Options +------- - .. code-block:: console +.. option:: --integrity-check-interval NUMBER - $ tt start app:router + Integrity check interval in seconds. Default: 86400 (24 hours). + Set this option to ``0`` to disable periodic checks. + See also: :ref:`tt-start-integrity-check` \ No newline at end of file