TARANTOOLCTL(1)

📦
version 2.6.0 · 6 versions
, in ubuntu questing

💖 TARANTOOLCTL — a utility to control Tarantool instances 💖

okay bestie, this is tarantoolctl(1) from the Tarantool instances control fam, and honestly? she's the group chat moderator for all your Tarantool instances. let's get into it 🎀

✨ SYNOPSIS ✨

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

like, you give her a command, maybe an instance, maybe a file, maybe a URI, maybe some options, and she handles it. 💅

🦋 DESCRIPTION 🦋

so tarantoolctl is the girl who can introspect and control the state of your Tarantool instances. she sees all, she knows all, she starts and stops things. main character energy fr fr.

and when we say INSTANCE? that's just the name of an instance file. that's it. that's the whole thing. no cap. 💜

👑 COMMANDS 👑

these are the commands she understands, bestie. memorize them, they're iconic:

  • start INSTANCE — starts the Tarantool instance you named on the command line, but only if it's not already running. if it's running? she does nothing. she's not gonna double-start, that's not the vibe. 🫶
  • stop INSTANCE — stops the Tarantool instance you named, but only if it's actually running. if it's not running, she does nothing. respectful queen.
  • status INSTANCE — shows you the status of the instance (started/stopped, obvi). here's the tea: if the pid file exists and an alive control socket exists, the return code is 0. otherwise the return code is not 0. she also reports typical problems to stderr (like, say, pid file exists but control socket does not 👀). she will tell you what's wrong.
  • restart INSTANCE — stop and start the instance you named, but only if it's running. if it's not running? nothing happens. she's not gonna invent an instance for you.
  • logrotate INSTANCE — rotates logs of the instance you named, if the instance is running. BUT — this only works if logging-into-file is enabled in the instance file (that's the box.cfg{log=...} parameter). pipe/syslog make no effect. so if you're piping logs somewhere, this command is giving nothing, sorry babe 😭
  • check INSTANCE — checks if there are syntax errors in the instance script of the instance you named. like a lil spell-check but for lua. ✨
  • enter INSTANCE — drops you into the interactive console of the instance you named. go talk to her directly. 💬
  • eval INSTANCE FILE — or, if you're feeling pipe-y: COMMAND | tarantoolctl eval INSTANCE. evaluates a local file on the instance you named, if the instance is running. if it's not running, nothing happens. 🤷‍♀️
  • connect URI — or COMMAND | tarantoolctl connect URI. connects on an admin-console port to the Tarantool instance at the URI you gave. supports both TCP and Unix sockets. versatile queen. 🔥
  • cat FILE... [--space=space_no...] [--show-system] [--from=from_lsn] [--to=to_lsn] [--replica=replica_id] — prints the contents of the .snap/.xlog files you specified into stdout. yes she will just dump them at you. 📖
  • play URI FILE... [--space=space_no...] [--show-system] [--from=from_lsn] [--to=to_lsn] [--replica=replica_id] — plays the contents of those .snap/.xlog files to another Tarantool instance, the one at the URI you gave. replaying history, literally. ⏪

💅 OPTIONS 💅

the options she understands. one bullet per option because we're organized:

  • --space=space_no — filters the output by space number. you can pass this more than once if you're fancy. 🎀
  • --show-system — shows/plays the contents of system spaces. peek behind the curtain bestie. 🙈
  • --from=from_lsn — shows/plays operations starting from the given lsn.
  • --to=to_lsn — shows/plays operations ending with the given lsn.
  • --replica=replica_id — filters the output by replica ID. and yes, you can pass this more than once too. go off. 🌈

🌸 CONFIGURATION 🌸

okay this part is important, listen up. 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 it's 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? she falls back to built-in defaults. no drama:

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{}. here's the rundown:

  • 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. heads up: this is the operating-system user name, not the Tarantool-client user name. Tarantool will change its effective user to this user after becoming a daemon. so like, it's the OS-level identity, iykyk. 🔑
  • instance_dir — the directory where all instance files for this host are stored. put instance files in this directory, or create symbolic links. your call bestie. 🦋

as a full-featured example, you can take the example.lua script that ships with Tarantool and defines all configuration options. she's the blueprint. ✨

💀 EXIT STATUS 💀

on success, 0 is returned. a non-zero failure code otherwise. simple as that. no in-between. periodt.

🔥 SEE ALSO 🔥

go read those too, bestie, they're literally so good. 📚

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

and that's the whole page!! this was --name=tarantoolctl, dated 2025-01-05, from the TARANTOOLCTL(1) era — mwah, iconic, ate, no crumbs left. go start some instances and slay 💖✨🦋

📦 where this page comes from