Skip to content

tt instance

Start, stop and inspect the instances of an application on this host.

A target is <APP>:<INSTANCE>, every instance of an application <APP>:*, a comma-separated list of them, or none, which is every instance of the project the command runs in. An application is looked for in the project the command runs in when the project has its name, and in the system scope otherwise; --scope project, user or system picks the scope outright. The instances are those of the pair of the application: the host's <root>/etc/<app>/, or the template .templates/<template>/ of the application, "default" unless --template names another.

A command that acts on several instances goes on after a failure of one of them and exits 3 when it failed for some of them only. What the exit codes mean is in tt help errors.

An instance that tt service systemd install put under a systemd unit is started and stopped with systemctl: start, stop, restart and kill refuse it, and status shows its unit.

Usage

tt instance
tt instance [flags] <command> [command flags]

Commands

tt instance check

Validate the cluster config of the instances against the schema of the Tarantool config, as tt instance start and tt cluster show --validate validate it: an unknown option or a value of a wrong type fails the check. Check the Lua file each instance runs, its script or app.file of its config, for syntax errors, with the tarantool the instance runs on, and that the binary of each external process is found. TCM, a record with kind: tcm, is checked as its start checks it: its binary is found, its config and password file are read, and the project runs on Tarantool Enterprise.

Usage

tt instance check [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")

tt instance clean

Remove the data and the logs of the instances: the files of <root>/var/lib/<app>/<instance>/ and <root>/var/log/<app>/<instance>/, and of the data directories their config moves elsewhere. A running instance is left alone, which counts as a failure for it: it is told of first, and what is listed and asked about is the files of the others.

Usage

tt instance clean [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")
  • -V, --verbose - list all files to remove before confirmation
  • -y, --yes - confirm without a prompt, as is needed when the standard input is not a terminal

tt instance connect

Connect to the tarantool instance.

An instance of an application is reached at its console socket, and with --binary at iproto.advertise.client of its config, else at the first TCP address of its iproto.listen, 0.0.0.0 and [::] dialed as 127.0.0.1 and [::1], else at its binary port, with TLS and the TLS files of the iproto.listen entry there unless the flags give them. Over iproto it is logged in to with the credentials of --username and --password only.

The command supports the following Tarantool environment variables:

  • TT_CLI_USERNAME - specifies the Tarantool username
  • TT_CLI_PASSWORD - specifies the Tarantool password

They apply to a URI without credentials.

You could pass command line arguments to the interpreted SCRIPT or COMMAND passed via -f flag:

echo "print(...)" | tt instance connect user:pass@localhost:3013 -f- 1, 2, 3

Usage

tt instance connect (<APP>:<INSTANCE> | <URI>) [flags] [-f <FILE>] [-- ARGS]
  COMMAND | tt instance connect (<APP>:<INSTANCE> | <URI>) [flags]
  COMMAND | tt instance connect (<APP>:<INSTANCE> | <URI>) [flags] [-f-] [-- ARGS]

  The URI can be specified in the following formats:
  * [tcp://][username:password@][host:port]
  * [unix://][username:password@]socketpath
  To specify relative path without `unix://` use `./`.
  The query of a URI, `?transport=ssl&auth_type=pap-sha256`, takes
  transport (ssl or plain), auth_type (auto, chap-sha1 or pap-sha256)
  and the TLS settings ssl_key_file, ssl_cert_file, ssl_ca_file,
  ssl_ciphers, ssl_password and ssl_password_file.

  Available commands:
  * \shortcuts - get the full list of available shortcuts
  * \set language <language> - set language (lua or sql)
  * \set output <format> - output format: yaml (default), lua, table or ttable
  * \set delimiter <delimiter> - set expression delimiter
  * \help - show available backslash commands
  * \quit - quit interactive console

Flags

  • --auth-type string - authentication method: auto, chap-sha1 or pap-sha256; pap-sha256 needs TLS and Tarantool EE or CE 3.9+ (default auto)
  • --binary - connect to instance using binary port
  • --connect-timeout duration - timeout for establishing a binary connection (default 1s)
  • -f, --file string - file to read the script for evaluation. "-" - read the script from stdin
  • -i, --interactive - enter interactive mode after executing 'FILE'
  • -l, --language string - language: lua or sql
  • -x, --outputformat string - output format: yaml, lua, table or ttable (default yaml)
  • -p, --password string - password
  • --scope string - scope the application is looked for in: project, user or system
  • --sslcafile string - path to a trusted certificate authorities (CA) file
  • --sslcertfile string - path to an SSL certificate file
  • --sslciphers string - colon-separated (:) list of SSL cipher suites the connection can use
  • --sslkeyfile string - path to a private SSL key file
  • --sslpassword string - password for decrypting the private SSL key file
  • --sslpasswordfile string - path to a file containing the password for decrypting the private SSL key file
  • --template string - template of the application the instances are described in (default "default")
  • -u, --username string - username

tt instance kill

Kill the instances the targets select with SIGKILL: the process group of the watchdog of each instance, the instance included, and the process group of an external process. Nothing stops gracefully, nothing is restarted, and the pid file and the console socket are removed after them. tt instance stop is the graceful stop; kill is for an instance that does not stop.

With --dump tt sends SIGQUIT instead, which has Tarantool quit with a core dump for a post-mortem, and waits for it to end. An external process and an instance that is not running are refused.

kill asks for a confirmation, and off a terminal needs --yes. An instance a systemd unit manages is refused: the error names the systemctl kill command for its unit.

Usage

tt instance kill [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • -d, --dump - quit with a core dump (SIGQUIT) instead of SIGKILL
  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")
  • -y, --yes - confirm without a prompt, as is needed when the standard input is not a terminal

tt instance logrotate

Rotate the logs of running instances

Usage

tt instance logrotate [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")

tt instance logs

Print the last lines of tt.log of the instances, the log their output goes to, whether they run in the background or in the foreground.

Usage

tt instance logs [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --follow - Output appended data as the log file grows, until Ctrl-C
  • -n, --lines int - Count of last lines to output (default 10)
  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")

tt instance restart

Stop the instances the targets select and start them again in the background, resolved anew: an installed application restarts on its active version, with its pair as it is now. Every target is checked as tt instance start checks it before any instance stops, its cluster config validated among the rest.

The cluster config of the instances is validated against the schema of the Tarantool config first, as tt cluster show --validate and tt instance check validate it: a config Tarantool would refuse, such as one with an unknown option, starts nothing, and the error names every problem. --no-validate starts the instances all the same.

In the background tt waits until every instance it starts is up, all of them at once, for --timeout at most: a Tarantool instance once its box runs and its config is applied, as tt instance status shows them in BOX and CONFIG, an external process once it has run for a second, TCM once its HTTP address answers. An instance that exits before that has failed, also when its restart policy has its watchdog start it again, and so has one that is not up in time, which is left to its watchdog: tt says what happened, quotes the end of its tt.log and exits with an error. --no-wait starts the watchdogs and returns at once.

Usage

tt instance restart [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --no-validate - start without validating the cluster config against the schema of Tarantool
  • --no-wait - do not wait for the instances started in the background to come up
  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")
  • --timeout duration - how long to wait for the instances started in the background to come up (default 1m0s)
  • -y, --yes - confirm without a prompt, as is needed when the standard input is not a terminal

tt instance start

Start the instances the targets select. By default every instance runs in the background under a watchdog of tt, which restarts it as the restart field of its record says.

The cluster config of the instances is validated against the schema of the Tarantool config first, as tt cluster show --validate and tt instance check validate it: a config Tarantool would refuse, such as one with an unknown option, starts nothing, and the error names every problem. --no-validate starts the instances all the same.

In the background tt waits until every instance it starts is up, all of them at once, for --timeout at most: a Tarantool instance once its box runs and its config is applied, as tt instance status shows them in BOX and CONFIG, an external process once it has run for a second, TCM once its HTTP address answers. An instance that exits before that has failed, also when its restart policy has its watchdog start it again, and so has one that is not up in time, which is left to its watchdog: tt says what happened, quotes the end of its tt.log and exits with an error. --no-wait starts the watchdogs and returns at once.

What an instance runs - its binary or tarantool, its script or cluster config, its arguments, environment, restart policy and paths - is resolved here, before its watchdog starts, and the watchdog runs that for its whole life, restarts included: an edit of instances.yaml takes effect at the next tt instance start or restart. tarantool reads config.yaml itself at every start.

With --foreground tt stays in the foreground, for systemd, a container or a terminal, while every instance runs under a watchdog of its own that does not restart it. The output of the instances goes to their tt.log and to the standard output, prefixed with the instance when there are several. SIGINT, SIGTERM and SIGQUIT stop every instance, as a stop of its watchdog does; tt instance stop stops one of them from another terminal. An instance that ends does not stop the others. tt exits once all of them have ended: with 0 when they were stopped in time, with the exit code of the first instance that failed otherwise, 137 for one killed as it did not stop in time.

Usage

tt instance start [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --foreground - stay in the foreground while the instances run, without restarting them
  • --no-validate - start without validating the cluster config against the schema of Tarantool
  • --no-wait - do not wait for the instances started in the background to come up
  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")
  • --timeout duration - how long to wait for the instances started in the background to come up (default 1m0s)

tt instance status

The 'status' command provides information about the status of the instances.

With no target it shows the instances of the project the command runs in; with --scope user or --scope system, every instance of every application installed in that scope, warning of one that cannot be read.

Columns:

  • INSTANCE: The name of the instance, <APP>:<INSTANCE>.
  • STATUS: The current status of the instance: - RUNNING: The instance is up and running. - NOT RUNNING: The instance is not running. - ERROR: The process has terminated unexpectedly.
  • UNIT: The systemd unit that manages the instance, for an instance that tt service systemd install put under a unit. The column is shown only when a unit manages some of the instances.
  • PID: The watchdog process PID.
  • MODE: The mode of the instance, indicating its read/write status: - RO: The instance is in read-only mode. - RW: The instance is in read-write mode.
  • CONFIG: The config info status (for Tarantool 3+); -- for an instance that runs its script, which does not use the cluster config.
  • BOX: The box info status.
  • UPSTREAM: The replication upstream status.

MODE, CONFIG, BOX and UPSTREAM are what a running Tarantool instance tells over its console socket; an external process shows the state of its process alone. --details prints the alerts of the instances, and the tarantool each Tarantool instance starts on and where it comes from. For an instance that does not run it prints how its last process ended and when, as its watchdog recorded it, and the last lines of its tt.log unless it was stopped cleanly; -o json and -o yaml give that record as last_exit.

The status reads the cluster config as far as it can. When "*" stands for a topology in a config storage that is out of reach, it stands for the instances known on this host instead - named in instances.yaml, declared by config.yaml itself, or with state under var/run or var/lib of the application - and a warning names the storage and says that the list may be incomplete.

Usage

tt instance status [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • -d, --details - print detailed alerts and the tarantool the instances start on
  • -o, --format string - output format: json, yaml, table, pretty-table (default table)
  • --instance-timeout duration - timeout for collecting a single instance's status; 0 disables the timeout (default 5s)
  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")

tt instance stop

Stop instances

Usage

tt instance stop [<APP>:<INSTANCE> | <APP>:*][,...] [flags]

Flags

  • --scope string - scope the application is looked for in: project, user or system
  • --template string - template of the application the instances are described in (default "default")
  • -y, --yes - confirm without a prompt, as is needed when the standard input is not a terminal