---
name: "tarantoolctl"
section: "1"
platform: "linux"
package: "tarantool-common"
version: "2.6.0-1.4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/tarantoolctl"
---

# tarantoolctl(1)

a utility to control Tarantool instances

## NAME

tarantoolctl - a utility to control Tarantool instances

## SYNOPSIS

tarantoolctl COMMAND \[INSTANCE\] \[FILE\] \[URI\] \[OPTIONS...\]

## DESCRIPTION

tarantoolctl may be used to introspect and control the state of Tarantool instances.

The `"INSTANCE"` represents the name of an instance file.

## COMMANDS

The following commands are understood:

- start INSTANCE

  Start the Tarantool instance specified on the command line if the instance is not running. This does nothing if an instance is running.

- stop INSTANCE

  Stop the Tarantool instance specified on the command line if the instance is running. This does nothing if an instance is not running.

- status INSTANCE

  Show status of the Tarantool instance specified on the command line (started/stopped). If pid file exists and an alive control socket exists, the return code is `0`. Otherwise, the return code is not `0`. Reports typical problems to stderr (e.g. pid file exists and control socket does not).

- restart INSTANCE

  Stop and start the Tarantool instance specified on the command line if the instance is running. This does nothing if an instance is not running.

- logrotate INSTANCE

  Rotate logs of the Tarantool instance specified on the command line if the instance is running. This works only if logging-into-file is enabled in the instance file (`"box.cfg{log=...}"` parameter). Pipe/syslog make no effect.

- check INSTANCE

  Check if there are syntax errors in the instance script of the Tarantool instance specified on the command line.

- enter INSTANCE

  Enter the interactive console of the Tarantool instance specified on the command line.

- eval INSTANCE FILE

  - COMMAND \| tarantoolctl eval INSTANCE

  Evaluate a local file on the Tarantool instance specified on the command line if the instance is running. This does nothing if an instance is not running.

- connect URI

  - COMMAND \| tarantoolctl connect URI

  Connect on an admin-console port to the Tarantool instance with the URI specified on the command line. This supports both TCP/Unix sockets.

- cat FILE... \[--space=space\_no...\] \[--show-system\] \[--from=from\_lsn\] \[--to=to\_lsn\] \[--replica=replica\_id\]

  Print into stdout the contents of .snap/.xlog files specified on the command line.

- play URI FILE... \[--space=space\_no...\] \[--show-system\] \[--from=from\_lsn\] \[--to=to\_lsn\] \[--replica=replica\_id\]

  Play the contents of .snap/.xlog files to another Tarantool instance with URI specified on the command line.

## OPTIONS

The following options are understood:

- \--space=space\_no

  Filter the output by space number. May be passed more than once.

- \--show-system

  Show/play the contents of system spaces.

- \--from=from\_lsn

  Show/play operations starting from the given lsn.

- \--to=to\_lsn

  Show/play operations ending with the given lsn.

- \--replica=replica\_id

  Filter the output by replica ID. May be passed more than once.

## CONFIGURATION

The file with system-wide defaults for tarantoolctl is installed in `"/etc/default/tarantool"`. This file is used when tarantoolctl is invoked by root. When invoked by a local user, tarantoolctl first looks for its defaults file in the current directory (`"$PWD/.tarantoolctl"`), and then in the current user's home directory (`"$HOME/.config/tarantool/tarantool"`). If not found, tarantoolctl falls back to built-in defaults:

```
    default_cfg = {
    pid_file  = "/var/run/tarantool",
    wal_dir   = "/var/lib/tarantool",
    memtx_dir = "/var/lib/tarantool",
    vinyl_dir = "/var/lib/tarantool",
    log       = "/var/log/tarantool",
    username  = "tarantool",
    }
    instance_dir = "/etc/tarantool/instances.enabled"
```

Most of these parameters are similar to those in `"box.cfg{}"`:

- pid\_file

  Directory for the pid file and control-socket file; tarantoolctl will add "/instance\_name" to the directory name.

- wal\_dir

  Directory for write-ahead \*.xlog files; tarantoolctl will add "/instance\_name" to the directory name.

- memtx\_dir

  Directory for snapshot \*.snap files; tarantoolctl will add "/instance\_name" to the directory name.

- vinyl\_dir

  Directory for vinyl files; tarantoolctl will add "/instance\_name" to the directory name.

- log

  The place where the application log will go; tarantoolctl will add "/instance\_name.log" to the name.

- username

  The user that runs the Tarantool instance. This is the operating-system user name rather than the Tarantool-client user name. Tarantool will change its effective user to this user after becoming a daemon.

- instance\_dir

  The directory where all instance files for this host are stored. Put instance files in this directory, or create symbolic links.

  As a full-featured example, you can take `"example.lua"` script that ships with Tarantool and defines all configuration options.

## EXIT STATUS

On success, `0` is returned, a non-zero failure code otherwise.

## SEE ALSO

[**tarantool**(1)](/tarantool/1.md), Tarantool manual at http://tarantool.org/doc/

## COPYRIGHT

Copyright (C) 2010-2017 Tarantool AUTHORS: please see AUTHORS file.