Added static credentials for deploy ydb on premises

document the deployment of cluster with authentication enabled

5 files changed, 325 insertions, 85 deletions

diff --git a/ydb/docs/en/core/deploy/manual/_includes/prepare-configs.md b/ydb/docs/en/core/deploy/manual/_includes/prepare-configs.md
index e6b2b0adf1..7b91b7792b 100644
--- a/ydb/docs/en/core/deploy/manual/_includes/prepare-configs.md
+++ b/ydb/docs/en/core/deploy/manual/_includes/prepare-configs.md
@@ -4,11 +4,13 @@ Prepare a configuration file for {{ ydb-short-name }}:
 
    * [block-4-2](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/block-4-2.yaml): For a single-data center cluster.
    * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-9-nodes.yaml): For a cross-data center cluster consisting of 9 nodes.
-   * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml): For a cross-data center cluster consisting of 3 nodes.
+   * [mirror-3dc-3nodes](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml): For a cross-data center cluster consisting of 3 nodes.
 
-1. In the host_configs section, specify all disks and their types on each cluster node. Possible disk types:
+1. In the `host_configs` section, specify all disks and their types on each cluster node. Possible disk types are:
+   * ROT: rotational, HDD devices.
+   * SSD: SSD or NVMe devices.
 
-   ```text
+   ```json
    host_configs:
    - drive:
      - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
@@ -16,12 +18,9 @@ Prepare a configuration file for {{ ydb-short-name }}:
      host_config_id: 1
    ```
 
-   * ROT (rotational): HDD.
-   * SSD: SSD or NVMe.
-
 1. In the `hosts` section, specify the FQDN of each node, their configuration and location in a `data_center` or `rack`:
 
-   ```text
+   ```json
    hosts:
    - host: node1.ydb.tech
      host_config_id: 1
@@ -43,4 +42,24 @@ Prepare a configuration file for {{ ydb-short-name }}:
        rack: '1'
    ```
 
-   For more detailed information about creating configurations, see [Cluster configurations](../../configuration/config.md).
\ No newline at end of file
+1. Enable user authentication (optional). 
+
+    If you plan to use the authentication and authorization capabilities in the {{ ydb-short-name }} cluster being created, add the following additional parameters to the `domains_config` section:
+
+    ```json
+    domains_config:
+      security_config:
+        enforce_user_token_requirement: true
+        monitoring_allowed_sids:
+        - "root"
+        - "ADMINS"
+        - "DATABASE-ADMINS"
+        administration_allowed_sids:
+        - "root"
+        - "ADMINS"
+        - "DATABASE-ADMINS"
+        viewer_allowed_sids:
+        - "root"
+        - "ADMINS"
+        - "DATABASE-ADMINS"
+    ```
diff --git a/ydb/docs/en/core/deploy/manual/deploy-ydb-on-premises.md b/ydb/docs/en/core/deploy/manual/deploy-ydb-on-premises.md
index a0d985dc63..f6d3fed94d 100644
--- a/ydb/docs/en/core/deploy/manual/deploy-ydb-on-premises.md
+++ b/ydb/docs/en/core/deploy/manual/deploy-ydb-on-premises.md
@@ -1,6 +1,6 @@
 # Deploying a {{ ydb-short-name }} cluster on virtual or bare metal servers
 
-This document describes the procedure to deploy a multi-tenant {{ ydb-short-name }} cluster on several servers.
+This document describes the procedure to deploy a multi-tenant {{ ydb-short-name }} cluster on several virtual or bare metal servers.
 
 ## Before you begin {#before-start}
 
@@ -23,16 +23,16 @@ Run each static node on a separate server.
 
 For more information about hardware requirements, see [{#T}](../../cluster/system-requirements.md).
 
-## Create a system user and a group to run {{ ydb-short-name }} under {#create-user}
+## Create a system user and a group to run {{ ydb-short-name }} {#create-user}
 
-On each server that will be running {{ ydb-short-name }}, execute the command below:
+On each server that will be running {{ ydb-short-name }}, execute the commands below:
 
 ```bash
 sudo groupadd ydb
 sudo useradd ydb -g ydb
 ```
 
-To make sure the {{ ydb-short-name }} server has access to block disks to run, you need to add the process owner to the disk group:
+To make sure the {{ ydb-short-name }} server has access to block disk devices, you need to add the process owner to the `disk` user group:
 
 ```bash
 sudo usermod -aG disk ydb
@@ -93,7 +93,7 @@ We don't recommend storing data on disks used by other processes (including the
 1. Format the disk with the builtin command below:
 
    ```bash
-   sudo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin bs disk obliterate /dev/disk/by-partlabel/ydb_disk_ssd_01
+   sudo LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd admin bs disk obliterate /dev/disk/by-partlabel/ydb_disk_ssd_01
    ```
 
    Perform this operation for each disk that will be used for data storage.
@@ -104,15 +104,13 @@ We don't recommend storing data on disks used by other processes (including the
 
 - Unprotected mode
 
-   In this mode, traffic between cluster nodes and between client and cluster uses an unencrypted connection. Use this mode for testing purposes.
+   In the unprotected mode, traffic between cluster nodes and between client and cluster uses  unencrypted connections. Use this mode for testing purposes only.
 
    {% include [prepare-configs.md](_includes/prepare-configs.md) %}
 
-   Save the {{ ydb-short-name }} configuration file as `/opt/ydb/cfg/config.yaml`.
-
 - Protected mode
 
-   In this mode, traffic between cluster nodes and between the client and cluster is encrypted using the TLS protocol.
+   In the protected mode, traffic between cluster nodes and between the client and cluster is encrypted using the TLS protocol.
 
    {% note info %}
 
@@ -120,7 +118,7 @@ We don't recommend storing data on disks used by other processes (including the
 
    {% endnote %}
 
-   1. Create a CA key:
+   1. Create a key and a certificate for the Certification Authority (CA):
 
       1. Create a directory named `secure` to store the CA key and one named `certs` for certificates and node keys:
 
@@ -231,7 +229,7 @@ We don't recommend storing data on disks used by other processes (including the
          sudo chmod 0750 /opt/ydb/certs
          ```
 
-      1. Copy the node certificates and keys
+      1. Copy the node certificates and keys to the installation directory:
 
          ```bash
          sudo -u ydb cp certs/ca.crt certs/node.crt certs/node.key /opt/ydb/certs/
@@ -239,9 +237,11 @@ We don't recommend storing data on disks used by other processes (including the
 
    1. {% include [prepare-configs.md](_includes/prepare-configs.md) %}
 
-      1. In the `interconnect_config` and `grpc_config` sections, specify the path to the certificate, key, and CA certificates:
+   1. Enable traffic encryption in the {{ ydb-short-name }} configuration file.
+
+        In the `interconnect_config` and `grpc_config` sections, specify the paths to the certificate, key, and CA certificate files:
 
-      ```text
+        ```json
         interconnect_config:
             start_tcp: true
             encryption_mode: OPTIONAL
@@ -253,13 +253,15 @@ We don't recommend storing data on disks used by other processes (including the
             cert: "/opt/ydb/certs/node.crt"
             key: "/opt/ydb/certs/node.key"
             ca: "/opt/ydb/certs/ca.crt"
-      ```
-
-   Save the {{ ydb-short-name }} configuration file as `/opt/ydb/cfg/config.yaml`.
+        ```
 
 {% endlist %}
 
-## Start static nodes {# start-storage}
+Save the {{ ydb-short-name }} configuration file as `/opt/ydb/cfg/config.yaml` on each cluster node.
+
+For more detailed information about creating configurations, see [Cluster configurations](../configuration/config.md).
+
+## Start static nodes {#start-storage}
 
 {% list tabs %}
 
@@ -270,7 +272,7 @@ We don't recommend storing data on disks used by other processes (including the
    ```bash
    sudo su - ydb
    cd /opt/ydb
-   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+   export LD_LIBRARY_PATH=/opt/ydb/lib
    /opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config /opt/ydb/cfg/config.yaml  \
    --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
    ```
@@ -297,7 +299,7 @@ We don't recommend storing data on disks used by other processes (including the
    SyslogIdentifier=ydbd
    SyslogFacility=daemon
    SyslogLevel=err
-   Environment=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+   Environment=LD_LIBRARY_PATH=/opt/ydb/lib
    ExecStart=/opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config  /opt/ydb/cfg/config.yaml --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
    LimitNOFILE=65536
    LimitCORE=0
@@ -315,24 +317,77 @@ We don't recommend storing data on disks used by other processes (including the
 
 {% endlist %}
 
-## Initialize a cluster {#initialize-cluster}
+## Initialize the cluster {#initialize-cluster}
 
-On one of the cluster nodes, run the command:
+The procedure of cluster initialization depends on whether user authentication mode is enabled in the {{ ydb-short-name }} configuration file.
 
-```bash
-LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml ; echo $?
-```
+{% list tabs %}
+
+- Authentication Disabled
+
+  On one of the cluster nodes, run the command:
+
+  ```bash
+  export LD_LIBRARY_PATH=/opt/ydb/lib
+  /opt/ydb/bin/ydbd admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
+  echo $?
+  ```
+
+  The command status code should be zero.
 
-The command execution code should be null.
+- Authentication Enabled
 
-## Creating the first database {#create-fist-db}
+  To perform the administrative commands (including cluster initialization, database creation, disk management, and others) in a cluster with user authentication enabled, you must first obtain an authentication token using the {{ ydb-short-name }} CLI client version 2.0.0 or higher. {{ ydb-short-name }} CLI can be installed on any host having network access to the cluster nodes (for example, on one of the cluster nodes themselves), according to the [installation instructions](../../reference/ydb-cli/install.md).
+  
+  While the cluster is being initially set up, it only has a single user account named `root` with an empty password. Therefore, the command to obtain the authentication token looks like the following:
+
+  ```bash
+  ydb -e grpc://<node1.ydb.tech>:2135 -d /Root \
+      --user root --no-password auth get-token --force >token-file
+  ```
+
+  A name of any server in the cluster can be specified as the connection endpoint (parameter `-e` or `--endpoint`).
+
+  If TLS traffic protection has been enabled, then instead of the `grpc` protocol in the command above, its secure flavor `grpcs` must be used. In addition, the path to the file with the CA certificate needs to be specified in the `--ca-file` parameter. For example:
+
+  ```bash
+  ydb -e grpcs://<node1.ydb.tech>:2135 -d /Root --ca-file /opt/ydb/certs/ca.crt \
+       --user root --no-password auth get-token --force >token-file
+  ```
+
+  Upon successful execution of the command shown above, the authentication token will be written to the `token-file`. This file will need to be copied to the cluster node on which you plan to run the cluster initialization and database creation commands. To initialize the cluster, run the following commands on that cluster node:
+
+  ```bash
+  export LD_LIBRARY_PATH=/opt/ydb/lib
+  /opt/ydb/bin/ydbd -f token-file admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
+  echo $?
+  ```
+
+  The command status code should be zero.
+
+{% endlist %}
+
+## Create the database {#create-db}
 
 To work with tables, you need to create at least one database and run a process to service this database (a dynamic node):
 
 ```bash
-LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /Root/testdb create ssd:1
+LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd admin database /Root/testdb create ssd:1
+```
+
+If the user authentication is enabled in the cluster, an authentication token must be passed to the database creation command. The procedure to obtain the token is described above in the [cluster initialization section](#initialize-cluster).
+
+The authenticated version of the database creation command:
+
+```bash
+LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd -f token-file admin database /Root/testdb create ssd:1
 ```
 
+The following parameters are used in the command examples shown above:
+* `/Root` - name of the cluster root domain, must match the value of the `domains_config`.`domain`.`name` setting in the configuration file;
+* `testdb` - name of the database being created;
+* `ssd:1` - name of the storage pool and the "box" number within the pool. Name of the pool typically means the device type used, and should match the value of `storage_pool_types`.`kind` setting within the `domains_config`.`domain` element of the configuration file.
+
 ## Start the DB dynamic node {#start-dynnode}
 
 {% list tabs %}
@@ -344,7 +399,7 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
    ```bash
    sudo su - ydb
    cd /opt/ydb
-   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+   export LD_LIBRARY_PATH=/opt/ydb/lib
    /opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml \
    --tenant /Root/testdb --node-broker <node1.ydb.tech>:2135 --node-broker <node2.ydb.tech>:2135 --node-broker <node3.ydb.tech>:2135
    ```
@@ -375,7 +430,7 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
    SyslogIdentifier=ydbd
    SyslogFacility=daemon
    SyslogLevel=err
-   Environment=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+   Environment=LD_LIBRARY_PATH=/opt/ydb/lib
    ExecStart=/opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb --node-broker <node1.ydb.tech>:2135 --node-broker <node2.ydb.tech>:2135 --node-broker <node3.ydb.tech>:2135
    LimitNOFILE=65536
    LimitCORE=0
@@ -397,11 +452,50 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
 
 {% endlist %}
 
+## Initial setup of user accounts {#security-setup}
+
+If authentication mode is enabled in the cluster settings file, then you must perform the initial setup of user accounts before starting to work with the {{ ydb-short-name }} cluster.
+
+A single user account `root` with an empty password, and a standard set of pre-defined user groups, as specified in the [Access management](../../cluster/access.md) chapter, are created automatically during {{ ydb-short-name }} cluster initialization.
+
+In order to perform the initial setup of user accounts in the newly created {{ ydb-short-name }} cluster use the following steps:
+
+1. Install the {{ ydb-short-name }} CLI as described in [documentation](../../reference/ydb-cli/install.md).
+
+1. Change the password of the `root` user account:
+
+    ```bash
+    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root --no-password \
+        yql -s 'ALTER USER root PASSWORD "passw0rd"'
+    ```
+
+    Replace the `passw0rd` value in the command above with the password to be used.
+
+1. Create the additional user accounts:
+
+    ```bash
+    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root \
+        yql -s 'CREATE USER user1 PASSWORD "passw0rd"'
+    ```
+
+1. Configure the permissions by putting the user accounts into the builtin groups:
+
+    ```bash
+    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root \
+        yql -s 'ALTER GROUP `ADMINS` ADD USER user1'
+    ```
+
+In the command examples listed above `<node.ydb.tech>` is the FQDN of the server running the dynamic node for the database `/Root/testdb`.
+
+By default {{ ydb-short-name }} CLI application will query the password of the `root` user on each command. Password value can optionally be stored in the connection profile, as described in the [{{ ydb-short-name }} CLI documentation](../../reference/ydb-cli/profile/index.md), to avoid the need to repeatably enter it.
+
+If TLS traffic protection has been enabled, then instead of the `grpc` protocol in the commands above, its secure flavor `grpcs` must be used, and CA certificate filename has to be specified in the `--ca-file` parameter (or stored in the connection profile).
+
 ## Test the created database {#try-first-db}
 
-1. Install the {{ ydb-short-name }} CLI as described in [Installing the {{ ydb-short-name }} CLI](../../reference/ydb-cli/install.md):
+1. Install the {{ ydb-short-name }} CLI as described in [documentation](../../reference/ydb-cli/install.md).
 
-1. Create a `test_table`:
+1. Create a test table named `test_table`:
 
    ```bash
    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb scripting yql \
@@ -409,3 +503,10 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
    ```
 
    Where `<node.ydb.tech>` is the FQDN of the server running the dynamic node that supports the `/Root/testdb` database.
+
+   The command shown above has to be modified if user authentication or TLS traffic protection modes are enabled in the cluster. For example:
+
+   ```bash
+   ydb -e grpcs://<node.ydb.tech>:2136 -d /Root/testdb --ca-file ydb-ca.crt --user root scripting yql \
+   --script 'CREATE TABLE `testdir/test_table` (id Uint64, title Utf8, PRIMARY KEY (id));'
+   ```
diff --git a/ydb/docs/ru/core/_includes/storage-device-requirements.md b/ydb/docs/ru/core/_includes/storage-device-requirements.md
index 1e496d0b40..b9dde90f2d 100644
--- a/ydb/docs/ru/core/_includes/storage-device-requirements.md
+++ b/ydb/docs/ru/core/_includes/storage-device-requirements.md
@@ -1,9 +1,9 @@
-Для эффективной работы YDB рекомендуется использовать физические (не виртуальные) диски объемом более 800 ГБ как блочные устройства.
+Для эффективной работы {{ ydb-short-name }} рекомендуется использовать физические (не виртуальные) диски объемом более 800 ГБ как блочные устройства.
 
-Минимальный объем диска должен быть не менее 80 ГБ, при меньшем объеме узел не сможет использовать устройство. Корректная и бесперебойная работа с дисками минимального объема не гарантируется. Использовать такие диски рекомендуется исключительно в ознакомительных целях.
+Минимальный объем диска должен быть не менее 80 ГБ, при меньшем объеме узел {{ ydb-short-name }} не сможет использовать устройство. Корректная и бесперебойная работа с дисками минимального объема не гарантируется. Использовать такие диски рекомендуется исключительно в ознакомительных целях.
 
 {% note warning %}
 
-Конфигурации с дисками меньше 800 ГБ или с любыми видами виртуализации системы хранения нельзя использовать для продакшн-сервисов, а также для тестирования производительности системы.
+Конфигурации с дисками объемом меньше 800 ГБ или с любыми видами виртуализации системы хранения нельзя использовать для сервисов, находящихся в промышленной эксплуатации, а также для тестирования производительности системы.
 
 {% endnote %}
diff --git a/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md b/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md
index 287f33e8d0..3021eeb304 100644
--- a/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md
+++ b/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md
@@ -3,12 +3,14 @@
 1. Скачайте пример конфига для соответствующей модели отказа вашего кластера:
 
     * [block-4-2](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/block-4-2.yaml) - для однодатацентрового кластера.
-    * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-9-nodes.yaml) - для crossDC кластера из 9 нод.
-    * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml) - для crossDC кластера из 3 нод.
+    * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-9-nodes.yaml) - для cross-DC кластера из 9 нод.
+    * [mirror-3dc-3nodes](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml) - для cross-DC кластера из 3 нод.
 
-1. В секции host_configs укажите все диски и их тип на каждой из нод кластера. Возможные варианты типов дисков:
+1. В секции `host_configs` укажите все диски и их тип на каждой из нод кластера. Возможные варианты типов дисков:
+    * ROT: rotational, HDD диски.
+    * SSD: SSD или NVMe диски.
 
-    ```text
+    ```json
     host_configs:
     - drive:
       - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
@@ -16,12 +18,9 @@
       host_config_id: 1
     ```
 
-    * ROT (rotational) - HDD диски.
-    * SSD - SSD или NVMe диски.
-
 1. В секции `hosts` укажите FQDN всех нод, их конфигурацию и расположение по датацентрам (`data_center`) и стойкам (`rack`):
 
-    ```text
+    ```json
     hosts:
     - host: node1.ydb.tech
       host_config_id: 1
@@ -43,4 +42,24 @@
         rack: '1'
     ```
 
-    Более подробная информация по созданию конфигурации приведена в статье [Конфигурация кластера](../../configuration/config.md).
\ No newline at end of file
+1. Включите аутентификацию пользователей (опционально).
+
+    Если вы планируете использовать в кластере {{ ydb-short-name }} возможности аутентификации и разграничения доступа пользователей, добавьте в секцию `domains_config` следующие дополнительные параметры:
+
+    ```json
+    domains_config:
+      security_config:
+        enforce_user_token_requirement: true
+        monitoring_allowed_sids:
+        - "root"
+        - "ADMINS"
+        - "DATABASE-ADMINS"
+        administration_allowed_sids:
+        - "root"
+        - "ADMINS"
+        - "DATABASE-ADMINS"
+        viewer_allowed_sids:
+        - "root"
+        - "ADMINS"
+        - "DATABASE-ADMINS"
+    ```
diff --git a/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md b/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md
index 7ed27d78b5..dc8158f707 100644
--- a/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md
+++ b/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md
@@ -1,12 +1,12 @@
-# Развертывание кластера {{ ydb-short-name }} на виртуальных или железных серверах
+# Развертывание кластера {{ ydb-short-name }} на виртуальных или физических серверах
 
-Данный документ описывает способ развернуть мультитенантный кластер {{ ydb-short-name }} на нескольких серверах.
+Этот документ описывает способ развернуть мультитенантный кластер {{ ydb-short-name }} на нескольких физических или виртуальных серверах.
 
 ## Перед началом работы {#before-start}
 
 ### Требования {#requirements}
 
-У вас должен быть ssh доступ на все сервера. Это необходимо для установки артефактов и запуска бинарника {{ ydb-short-name }}. Ваша сетевая конфигурация должна разрешать TCP соединения по следующим портам (по умолчанию):
+У вас должен быть ssh доступ на все сервера. Это необходимо для установки артефактов и запуска исполняемого файла {{ ydb-short-name }}. Сетевая конфигурация должна разрешать TCP соединения по следующим портам (по умолчанию):
 
 * 2135, 2136 - grpc для клиент-кластерного взаимодействия;
 * 19001, 19002 - Interconnect для внутрикластерного взаимодействия нод;
@@ -16,8 +16,8 @@
 
 Выберите серверы и диски, которые будут использоваться для хранения данных:
 
-* Используйте схему отказоустойчивости `block-4-2` для деплоя кластера в одной зоне доступности (AZ). Чтобы переживать отказ 2 нод используйте не менее 8 нод.
-* Используйте схему отказоустойчивости `mirror-3-dc` для деплоя кластера в трех зонах доступности (AZ). Чтобы переживать отказ 1 AZ и 1 ноды в другом AZ используйте не менее 9 нод. Количество нод в каждой AZ должно быть одинаковым.
+* Используйте схему отказоустойчивости `block-4-2` для развертывания кластера в одной зоне доступности (AZ). Чтобы переживать отказ 2 нод используйте не менее 8 нод.
+* Используйте схему отказоустойчивости `mirror-3-dc` для развертывания кластера в трех зонах доступности (AZ). Чтобы переживать отказ 1 AZ и 1 ноды в другом AZ используйте не менее 9 нод. Количество нод в каждой AZ должно быть одинаковым.
 
 Запускайте каждую статическую ноду на отдельном сервере.
 
@@ -32,7 +32,7 @@ sudo groupadd ydb
 sudo useradd ydb -g ydb
 ```
 
-Для того, чтобы {{ ydb-short-name }} server имел доступ к блочным дискам для работы, необходимо добавить пользователя, под которым будет запущен процесс, в группу disk:
+Для того, чтобы сервис {{ ydb-short-name }} имел доступ к блочным дискам для работы, необходимо добавить пользователя, под которым будет запущен процесс, в группу `disk`:
 
 ```bash
 sudo usermod -aG disk ydb
@@ -42,7 +42,7 @@ sudo usermod -aG disk ydb
 
 {% note warning %}
 
-Мы не рекомендуем использовать для хранения данных диски, которые используются другими процессами (в т.ч. операционной системой).
+Мы не рекомендуем использовать для хранения данных диски, которые используются другими процессами (в том числе операционной системой).
 
 {% endnote %}
 
@@ -81,7 +81,7 @@ sudo usermod -aG disk ydb
     sudo chown -R ydb:ydb /opt/ydb
     ```
 
-1. Скопируйте бинарник, библиотеки и конфигурационный файл в соответствующие директории:
+1. Скопируйте исполняемый файл, библиотеки и конфигурационный файл в соответствующие директории:
 
     ```bash
     sudo cp -i ydbd-stable-linux-amd64/bin/ydbd /opt/ydb/bin/
@@ -93,7 +93,7 @@ sudo usermod -aG disk ydb
 1. Отформатируйте диск встроенной командой:
 
     ```bash
-    sudo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin bs disk obliterate /dev/disk/by-partlabel/ydb_disk_ssd_01
+    sudo LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd admin bs disk obliterate /dev/disk/by-partlabel/ydb_disk_ssd_01
     ```
 
     Проделайте данную операцию для каждого диска, который будет использоваться для хранения данных.
@@ -104,15 +104,13 @@ sudo usermod -aG disk ydb
 
 - Незащищенный режим
 
-  В данном режиме трафик между нодами кластера, а также между клиентом и кластером использует нешифрованное соединение. Используйте данный режим для тестовых задач.
+  В незащищенном режиме трафик между нодами кластера, а также между клиентом и кластером использует нешифрованное соединение. Используйте данный режим для тестовых задач.
 
   {% include [prepare-configs.md](_includes/prepare-configs.md) %}
 
-  Сохраните конфигурационный файл {{ ydb-short-name }} под именем `/opt/ydb/cfg/config.yaml`.
-
 - Защищенный режим
 
-  В данном режиме трафик между нодами кластера, а также между клиентом и кластером шифруется протоколом TLS.
+  В защищенном режиме трафик между нодами кластера, а также между клиентом и кластером шифруется протоколом TLS.
 
   {% note info %}
 
@@ -120,7 +118,7 @@ sudo usermod -aG disk ydb
 
   {% endnote %}
 
-  1. Создайте CA ключ:
+  1. Создайте ключ и сертификат для центра сертификации (CA):
 
       1. Создайте директории `secure`, в которой будет храниться ключ CA, и `certs` для сертификатов и ключей нод:
 
@@ -231,7 +229,7 @@ sudo usermod -aG disk ydb
           sudo chmod 0750 /opt/ydb/certs
           ```
 
-      1. Скопируйте сертификаты и ключи ноды
+      1. Скопируйте сертификаты и ключи ноды в каталог инсталляции:
 
           ```bash
           sudo -u ydb cp certs/ca.crt certs/node.crt certs/node.key /opt/ydb/certs/
@@ -239,9 +237,11 @@ sudo usermod -aG disk ydb
 
   1. {% include [prepare-configs.md](_includes/prepare-configs.md) %}
 
-      1. В секциях `interconnect_config` и `grpc_config` укажите путь до сертификата, ключа и CA сертификаты:
+  1. Включите режим шифрования трафика в конфигурационном файле {{ ydb-short-name }}.
+
+       В секциях `interconnect_config` и `grpc_config` укажите путь до файлов сертификата, ключа и CA сертификата:
 
-      ```text
+        ```json
         interconnect_config:
             start_tcp: true
             encryption_mode: OPTIONAL
@@ -253,13 +253,15 @@ sudo usermod -aG disk ydb
             cert: "/opt/ydb/certs/node.crt"
             key: "/opt/ydb/certs/node.key"
             ca: "/opt/ydb/certs/ca.crt"
-      ```
-
-  Сохраните конфигурационный файл {{ ydb-short-name }} под именем `/opt/ydb/cfg/config.yaml`.
+        ```
 
 {% endlist %}
 
-## Запустите статические ноды {# start-storage}
+Сохраните конфигурационный файл {{ ydb-short-name }} под именем `/opt/ydb/cfg/config.yaml` на каждом узле кластера.
+
+Более подробная информация по созданию конфигурации приведена в статье [Конфигурация кластера](../configuration/config.md).
+
+## Запустите статические ноды {#start-storage}
 
 {% list tabs %}
 
@@ -270,7 +272,7 @@ sudo usermod -aG disk ydb
   ```bash
   sudo su - ydb
   cd /opt/ydb
-  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  export LD_LIBRARY_PATH=/opt/ydb/lib
   /opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config /opt/ydb/cfg/config.yaml  \
   --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
   ```
@@ -297,7 +299,7 @@ sudo usermod -aG disk ydb
   SyslogIdentifier=ydbd
   SyslogFacility=daemon
   SyslogLevel=err
-  Environment=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  Environment=LD_LIBRARY_PATH=/opt/ydb/lib
   ExecStart=/opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config  /opt/ydb/cfg/config.yaml --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
   LimitNOFILE=65536
   LimitCORE=0
@@ -317,23 +319,76 @@ sudo usermod -aG disk ydb
 
 ## Инициализируйте кластер {#initialize-cluster}
 
-На одной из нод кластера выполните команду:
+Действия по инициализации кластера зависят от того, включен ли в конфигурационном файле {{ ydb-short-name }} режим аутентификации пользователей.
 
-```bash
-LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml ; echo $?
-```
+{% list tabs %}
 
-Код завершения команды должен быть нулевым.
+- Аутентификация выключена
 
-## Создание первой базы данных {#create-fist-db}
+  На одной из нод кластера выполните команды:
+
+  ```bash
+  export LD_LIBRARY_PATH=/opt/ydb/lib
+  /opt/ydb/bin/ydbd admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
+  echo $?
+  ```
+
+  Код завершения команды должен быть нулевым.
+
+- Аутентификация включена
+
+  Для выполнения административных команд (включая инициализацию кластера, создание баз данных, управление дисками и другие) в кластере со включённым режимом аутентификации пользователей необходимо предварительно получить аутентификационный токен с использованием клиента {{ ydb-short-name }} CLI версии 2.0.0 или выше. Клиент {{ ydb-short-name }} CLI следует установить на любом компьютере, имеющем сетевой доступ к узлам кластера (например, на одном из узлов кластера), в соответствии с [инструкцией по установке](../../reference/ydb-cli/install.md).
+  
+  При первоначальной установке кластера в нём существует единственная учётная запись `root` с пустым паролем, поэтому команда получения токена выглядит следующим образом:
+
+  ```bash
+  ydb -e grpc://<node1.ydb.tech>:2135 -d /Root \
+      --user root --no-password auth get-token --force >token-file
+  ```
+
+  В качестве сервера для подключения (параметр `-e` или `--endpoint`) может быть указан любой из серверов кластера.
+
+  Если была включена защита трафика с использованием TLS, то вместо протокола `grpc` в команде выше следует использовать его защищенный вариант `grpcs`, и дополнительно указать путь к файлу с сертификатом CA в параметре `--ca-file`. Например:
+
+  ```bash
+  ydb -e grpcs://<node1.ydb.tech>:2135 -d /Root --ca-file /opt/ydb/certs/ca.crt \
+       --user root --no-password auth get-token --force >token-file
+  ```
+
+  При успешном выполнении указанной выше команды аутентификационный токен будет записан в файл `token-file`. Этот файл необходимо будет скопировать на ноду кластера, на которой в дальнейшем вы собираетесь выполнять команды инициализации кластера и создания базы данных. Далее на этой ноде кластера выполните команды:
+
+  ```bash
+  export LD_LIBRARY_PATH=/opt/ydb/lib
+  /opt/ydb/bin/ydbd -f token-file admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
+  echo $?
+  ```
+
+  Код завершения команды должен быть нулевым.
+
+{% endlist %}
+
+## Создайте базу данных {#create-db}
 
 Для работы с таблицами необходимо создать как минимум одну базу данных и поднять процесс, обслуживающий эту базу данных (динамическую ноду):
 
 ```bash
-LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /Root/testdb create ssd:1
+LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd admin database /Root/testdb create ssd:1
+```
+
+Если в кластере включен режим аутентификации пользователей, то в команду создания базы данных необходимо передать аутентификационный токен. Процедура получения токена описана в разделе по [инициализации кластера](#initialize-cluster).
+
+Вариант команды создания базы данных с указанием файла токена:
+
+```bash
+LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd -f token-file admin database /Root/testdb create ssd:1
 ```
 
-## Запустите динамическую ноду базы {#start-dynnode}
+В приведенных выше примерах команд используются следующие параметры:
+* `/Root` - имя корневого домена, должно соответствовать настройке `domains_config`.`domain`.`name` в файле конфигурации кластера;
+* `testdb` - имя создаваемой базы данных;
+* `ssd:1` - имя пула хранения и номер блока в пуле. Имя пула обычно означает тип устройств хранения данных и должно соответствовать настройке `storage_pool_types`.`kind` внутри элемента `domains_config`.`domain` файла конфигурации.
+
+## Запустите динамическую ноду базы данных {#start-dynnode}
 
 {% list tabs %}
 
@@ -344,7 +399,7 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
   ```bash
   sudo su - ydb
   cd /opt/ydb
-  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  export LD_LIBRARY_PATH=/opt/ydb/lib
   /opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml \
   --tenant /Root/testdb --node-broker <node1.ydb.tech>:2135 --node-broker <node2.ydb.tech>:2135 --node-broker <node3.ydb.tech>:2135
   ```
@@ -375,7 +430,7 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
   SyslogIdentifier=ydbd
   SyslogFacility=daemon
   SyslogLevel=err
-  Environment=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  Environment=LD_LIBRARY_PATH=/opt/ydb/lib
   ExecStart=/opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb --node-broker <node1.ydb.tech>:2135 --node-broker <node2.ydb.tech>:2135 --node-broker <node3.ydb.tech>:2135
   LimitNOFILE=65536
   LimitCORE=0
@@ -397,9 +452,48 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
 
 {% endlist %}
 
+## Первоначальная настройка учетных записей {#security-setup}
+
+Если в файле настроек кластера включен режим аутентификации, то перед началом работы с кластером {{ ydb-short-name }} необходимо выполнить первоначальную настройку учетных записей.
+
+При первоначальной установке кластера {{ ydb-short-name }} автоматически создается учетная запись `root` с пустым паролем, а также стандартный набор групп пользователей, описанный в разделе [Управление доступом](../../cluster/access.md).
+
+Для выполнения первоначальной настройки учетных записей в созданном кластере {{ ydb-short-name }} выполните следующие операции: 
+
+1. Установите {{ ydb-short-name }} CLI, как описано в [документации](../../reference/ydb-cli/install.md).
+
+1. Выполните установку пароля учетной записи `root`:
+
+    ```bash
+    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root --no-password \
+        yql -s 'ALTER USER root PASSWORD "passw0rd"'
+    ```
+
+    Вместо значения `passw0rd` подставьте необходимый пароль.
+
+1. Создайте дополнительные учетные записи:
+
+    ```bash
+    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root \
+        yql -s 'CREATE USER user1 PASSWORD "passw0rd"'
+    ```
+
+1. Установите права учетных записей, включив их во встроенные группы:
+
+    ```bash
+    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root \
+        yql -s 'ALTER GROUP `ADMINS` ADD USER user1'
+    ```
+
+В перечисленных выше примерах команд `<node.ydb.tech>` - FQDN сервера, на котором запущена динамическая нода, обслуживающая базу `/Root/testdb`.
+
+При выполнении команд создания учетных записей и присвоения групп клиент {{ ydb-short-name }} CLI будет запрашивать ввод пароля пользователя `root`. Избежать многократного ввода пароля можно, создав профиль подключения, как описано в [документации {{ ydb-short-name }} CLI](../../reference/ydb-cli/profile/index.md).
+
+Если в кластере была включена защита трафика с использованием TLS, то вместо протокола `grpc` в команде выше следует использовать его защищенный вариант `grpcs`, и дополнительно указать путь к файлу с сертификатом CA в параметре `--ca-file` (либо сохранить в профиле подключения).
+
 ## Протестируйте работу с созданной базой {#try-first-db}
 
-1. Установите {{ ydb-short-name }} CLI, как описано в статье [Установка {{ ydb-short-name }} CLI](../../reference/ydb-cli/install.md):
+1. Установите {{ ydb-short-name }} CLI, как описано в [документации](../../reference/ydb-cli/install.md).
 
 1. Создайте тестовую таблицу `test_table`:
 
@@ -409,3 +503,10 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin database /
    ```
 
    Где `<node.ydb.tech>` - FQDN сервера, на котором запущена динамическая нода, обслуживающая базу `/Root/testdb`.
+
+   Указанную выше команду необходимо будет скорректировать, если в кластере включена защита трафика с использованием TLS или активирован режим аутентификации пользователей. Пример:
+
+   ```bash
+   ydb -e grpcs://<node.ydb.tech>:2136 -d /Root/testdb --ca-file ydb-ca.crt --user root scripting yql \
+   --script 'CREATE TABLE `testdir/test_table` (id Uint64, title Utf8, PRIMARY KEY (id));'
+   ```