Connecting the CLI to a database and authentication

Most YDB CLI commands relate to operations on the YDB database and require a connection to it to run.

YDB CLI determines which database to connect to and which authentication mode to use from the following sources (in descending order of priority):

  1. Command line
  2. Profile selected by the --profile command-line option
  3. Environment variables
  4. Activated profile

For YDB CLI to attempt to connect to the database, the endpoint and database path must be determined as a result of these steps.

If all steps are completed but YDB CLI has not determined an authentication mode, requests will be sent to the YDB server without authentication data. This may allow successful work with locally deployed YDB clusters that do not require authentication. For all network-accessible databases, such requests will be rejected by the server with an authentication error.

For possible situations where YDB CLI will not attempt to connect to the database, see the Error messages section below.

Command-line parameters

Database connection options on the command line are specified before the command and its parameters:

ydb <connection_options> <command> <command_options>

Database connection parameters

  • -e, --endpoint <endpoint> — endpoint — the main connection parameter that allows you to find the YDB server on the network. If no port is specified, 2135 is used. If no protocol is specified, gRPCs (with encryption) is used in public builds of YDB CLI.
  • -d, --database <database> — database path.
  • --no-discovery — skip the discovery stage, which requests a list of addresses for connecting to the YDB cluster. If this option is set, the connection will be made directly to the endpoint specified by the user (using the -e option).

Authentication parameters

The authentication mode and parameters are selected by setting one of the following options:

  • --token-file <filepath>: Enables the Access Token authentication mode using the contents of the file specified in this option.
  • --yc-token-file <filepath>: Enables the Refresh Token authentication mode using the contents of the file specified in this option.
  • --use-metadata-credentials : The Metadata authentication mode is used.
  • --sa-key-file <filepath>: Enables the Service Account Key authentication mode, where the key and other parameters are taken from the JSON file specified in this option.

  • --user <username> : The username and password based authentication mode is used with the username set in this option value. Additionally , you can specify:

    • --password-file <filename> : The password is read from the specified file.
    • --no-password : Defines an empty password. The password will be requested interactively if none of the password identification options listed above are specified in the command line parameters.
  • --oauth2-key-file <filepath>: Enables the OAuth 2.0 token exchange authentication mode, where the key and other parameters are taken from the JSON file specified in this option. The --iam-endpoint option sets the token exchange endpoint in the <schema>://<host>:<port>/<path> format (via the YDB CLI option, profile, or environment variable).

If several of the above options are set simultaneously in the command line, the CLI returns an error asking you to specify only one:

$ ydb --use-metadata-credentials --iam-token-file ~/.ydb/token scheme ls
More than one auth method were provided via options. Choose exactly one of them
Try "--help" option for more info.

When using authentication modes that involve token rotation along with regularly re-requesting them from IAM (Refresh Token, Service Account Key, or OAuth 2.0 token exchange), a special parameter can be set to indicate where the IAM service is located:

  • --iam-endpoint <URL> : Sets the URL of the IAM service to request new tokens in authentication modes with token rotation. The default value is "iam.api.cloud.yandex.net".

TLS connection parameters

When connecting to an endpoint via gRPCs (with encryption), the client verifies the server certificate against a chain of trust. If the server uses a root CA that is not in the standard set of trusted CLI certificates, the path to it is specified in the parameter:

  • --ca-file <filename> : root PEM certificate file (CA)

If the client_certificate_authorization section in the cluster configuration has the request_client_certificate: true parameter enabled, the server requests a client certificate during device authentication. If device authentication or client certificate authentication is required, the following are specified on the client:

  • --client-cert-file <filename> : client certificate file (PEM or PKCS#12)
  • --client-cert-key-file <filename> : client certificate private key file (specified if the certificate and key are in separate files)
  • --client-cert-key-password-file <filename> : file with the private key password, if the key is encrypted; if the key is encrypted and the option is not specified, the password will be requested interactively

The options listed above are also used for client certificate authentication: request_client_certificate: true must be enabled on the server side, and no other authentication options must be set on the client. If --client-cert-file and another authentication mode are specified simultaneously, the certificate is transmitted during the TLS handshake, but an authentication token is used for request identification, not the certificate.

After successful authentication, the client is assigned a security identifier SID, which has all the rights assigned to the corresponding identifier. The method of forming the SID depends on the authentication mode. Schema and data rights are not granted automatically — see authorization.

Parameters from the profile selected by the command-line option

If any connection parameter is not specified on the command line when invoking YDB CLI, the CLI attempts to determine it from the profile selected by the --profile command-line option.

The profile can define most variables similar to the options in the command-line parameters section. Their values are processed in the same way as command-line parameters.

Parameters from environment variables

If no profile was explicitly specified on the command line or it does not contain authentication parameters, YDB CLI attempts to determine the authentication mode and parameters from the YDB CLI environment using the following algorithm:

  • If the value of the IAM_TOKEN environment variable is set, the Access Token authentication mode is used, where this variable value is passed.
  • Otherwise, if the value of the YC_TOKEN environment variable is set, the Refresh Token authentication mode is used and the token to transfer to the IAM endpoint is taken from this variable value when repeating the request.
  • Otherwise, if the value of the USE_METADATA_CREDENTIALS environment variable is set to 1, the Metadata authentication mode is used.
  • Otherwise, if the value of the SA_KEY_FILE environment variable is set, the Service Account Key authentication mode is used and the key is taken from the file whose name is specified in this variable.
  • If the value of the YDB_USER or YDB_PASSWORD environment variable is set, the username and password based authentication mode is used. The username is read from the YDB_USER variable. If it is not set, an error saying User password was provided without user name is returned. The password is read from the YDB_PASSWORD variable. If it is not set, then, depending on whether the --no-password command-line option is specified, either an empty password is used or a password is requested interactively.
  • Otherwise, if the YDB_OAUTH2_KEY_FILE environment variable value is set, the OAuth 2.0 token exchange authentication mode is used, and the token exchange parameters are taken from a JSON file specified in this variable. The --iam-endpoint option is used to set the token exchange endpoint in the <schema>://<host>:<port>/<path> format (via a YDB CLI option, profile, or environment variable).

Parameters from the activated profile

If on the previous steps it was not possible to determine any connection parameter and no profile was explicitly specified in the command line with the --profile option, then YDB CLI tries to use connection parameters from the activated profile.

Error messages

Errors before attempting to connect to the database

If all the steps described at the beginning of this article are completed, but the endpoint could not be determined, the command will be aborted with the message Missing required option 'endpoint'.

If all the steps described at the beginning of this article are completed, but the database path could not be determined, the command will be aborted with the message Missing required option 'database'.

If the authentication mode was determined, but the required additional parameters could not be determined, the command will be aborted with a message describing the problem:

  • (No such file or directory) util/system/file.cpp:857: can't open "<filepath>" with mode RdOnly|Seq (0x00000028) -- failed to open the file <filepath> for reading, specified in one of the parameters where the file name with path is passed.

Authentication check

The service command YDB CLI discovery whoami allows you to check which account you are actually authenticated as on the server.

Previous
Installation
Next
All commands in alphabetical order