Starting and stopping instances | Tarantool
Документация на русском языке
поддерживается сообществом
Администрирование Starting and stopping instances

Starting and stopping instances

To start a Tarantool instance from an instance file using the tt utility:

  1. Place the instance file (for example, my_app.lua) into /etc/tarantool/instances.enabled/. This is the default location where tt searches for instance files.

  2. Run tt start:

    $ tt start
       • Starting an instance [my_app]...

In this case, tt starts an instance from any *.lua file it finds in /etc/tarantool/instances.enabled/.

All the instance files or directories placed in the instances_enabled directory specified in tt configuration are called enabled instances. If there are several enabled instances, tt start starts a separate Tarantool instance for each of them.

Learn more about working with multiple Tarantool instances in Multi-instance applications.

To start a specific enabled instance, specify its name in the tt start argument:

$ tt start my_app
   • Starting an instance [my_app]...

When starting an instance, tt uses its configuration file tt.yaml to set up a tt environment in which the instance runs. The default tt configuration file is created automatically in /etc/tarantool/. Learn how to set up a tt environment in a directory of your choice in Running Tarantool locally.

After the instance has started and worked for some time, you can find its artifacts in the directories specified in the tt configuration. These are the default locations:

  • /var/log/tarantool/<instance_name>.log – instance logs.
  • /var/lib/tarantool/<instance_name>/ – snapshots and write-ahead logs.
  • /var/run/tarantool/<instance_name>.control – a control socket. This is a Unix socket with the Lua console attached to it. This file is used to connect to the instance console.
  • /var/run/tarantool/<instance_name>.pid – a PID file that tt uses to check the instance status and send control commands.


These commands can be called without an instance name. In this case, they are executed for all enabled instances.

tt provides a set of commands for performing basic operations over instances:

  • tt check – check the instance file for syntax errors:

    $ tt check my_app
       • Result of check: syntax of file '/etc/tarantool/instances.enabled/my_app.lua' is OK
  • tt status – check the instance status:

    $ tt status my_app
    INSTANCE     STATUS          PID
    my_app       NOT RUNNING
  • tt restart – restart the instance:

    $ tt restart my_app -y
       • The Instance my_app (PID = 729) has been terminated.
       • Starting an instance [my_app]...

    The -y option responds «yes» to the confirmation prompt automatically.

  • tt stop – stop the instance:

    $ tt stop my_app
       • The Instance my_app (PID = 639) has been terminated.
  • tt clean – remove instance artifacts: logs, snapshots, and other files.

    $ tt clean my_app -f
       • List of files to delete:
       • /var/log/tarantool/my_app.log
       • /var/lib/tarantool/my_app/00000000000000000000.snap
       • /var/lib/tarantool/my_app/00000000000000000000.xlog

    The -f option removes the files without confirmation.

Tarantool applications can include multiple instances that run different code. A typical example is a cluster application that includes router and storage instances. The tt utility enables managing such applications. With a single tt call, you can:

  • start an application on multiple instances
  • check the status of application instances
  • connect to a specific instance of an application
  • stop a specific instance of an application or all its instances

To create a multi-instance application, prepare its layout in a directory inside instances_enabled. The directory name is used as the application identifier.

This directory should contain the following files:

  • The default instance file named init.lua. This file is used for all instances of the application unless there are specific instance files (see below).

  • The instances configuration file instances.yml with instance names followed by colons:



    Do not use the dot (.) and dash (-) characters in the instance names. They are reserved for system use.

  • (Optional) Specific instances files. These files should have names <instance_name>.init.lua, where <instance_name> is the name specified in instances.yml. For example, if your application has separate source files for the router and storage instances, place the router code in the router.init.lua file.

For example, take a demo application that has three instances:storage1, storage2, and router. Storage instances share the same code, and router has its own. The application directory demo inside instances_enabled must contain the following files:

  • instances.yml – the instances configuration:

  • init.lua – the code of storage1 and storage2

  • router.init.lua – the code of router

When the application is working, each instance has associated environment variables TARANTOOL_INSTANCE_NAME and TARANTOOL_APP_NAME. You can use them in the application code to identify the instance on which the code runs.

To obtain the instance and application names, use the following code:

local inst_name = os.getenv('TARANTOOL_INSTANCE_NAME')
local app_name = os.getenv('TARANTOOL_APP_NAME')

Start all three instances of the demo application:

$ tt start demo
   • Starting an instance [demo:router]...
   • Starting an instance [demo:storage1]...
   • Starting an instance [demo:storage2]...

Check the status of demo instances:

$ tt status demo
demo:router      RUNNING     55
demo:storage1    RUNNING     56
demo:storage2    RUNNING     57

Check the status of a specific instance:

$ tt status demo:router
demo:router      RUNNING     55

Connect to an instance:

$ tt connect demo:router
   • Connecting to the instance...
   • Connected to /var/run/tarantool/demo/router/router.control


Stop a specific instance:

$ tt stop demo:storage1
   • The Instance demo:storage1 (PID = 56) has been terminated.

Stop all running instances of the demo application:

$ tt stop demo
   • The Instance demo:router (PID = 55) has been terminated.
   • can't "stat" the PID file. Error: "stat /var/run/tarantool/demo/storage1/ no such file or directory"
   • The Instance demo:storage2 (PID = 57) has been terminated.


The error message indicates that storage1 is already not running.

Sometimes you may need to run a Tarantool instance locally, for example, for test purposes. tt runs in a local environment if it finds a tt.yaml configuration file in the current directory or any of its enclosing directories.

To set up a local environment for tt:

  1. Create a home directory for the environment.
  2. Run tt init in this directory:
$ tt init
   • Environment config is written to 'tt.yaml'

This command creates a default tt configuration file tt.yaml for a local environment and the directories for instance files, control sockets, logs, and other artifacts:

$ ls
bin  distfiles  include  instances.enabled  modules  templates  tt.yaml

To run a Tarantool instance in the local environment:

  1. Place the instance file into the instances.enabled/ directory inside the current directory.

  2. Run tt start:

    $ tt start

After the instance is started, you can find its artifacts in their locations inside the current directory:

  • logs in var/log/<instance_name>
  • snapshots and write-ahead logs in var/lib/<instance_name>
  • control sockets and PID files in var/run/<instance_name>

To work with a local environment from a directory outside it, issue tt calls with the -L or --local argument with the path to this environment as its value:

$ tt --local=/usr/tt/env/ start

При запуске экземпляра с помощью инструментария systemd указанным ниже способом (имя экземпляра – my_app):

$ systemctl start tarantool@my_app
$ ps axuf|grep my_app
taranto+  5350  1.3  0.3 1448872 7736 ?        Ssl  20:05   0:28 tarantool my_app.lua <running>

This actually calls tarantoolctl like in case of tarantoolctl start my_app.

Для включения автоматической загрузки экземпляра my_app при запуске всей системы используйте команду:

$ systemctl enable tarantool@my_app

To stop a running my_app instance with systemctl, run:

$ systemctl stop tarantool@my_app

To restart a running my_app instance with systemctl, run:

$ systemctl restart tarantool@my_app
Нашли ответ на свой вопрос?
Обратная связь