Configuration reference¶
This reference covers all options and parameters which can be set for Tarantool on the command line or in an initialization file.
Tarantool is started by entering the following command:
$ tarantool # OR $ tarantool options # OR $ tarantool lua-initialization-file [ arguments ]
Command options¶
-
-h
,
--help
¶
Print an annotated list of all available options and exit.
-
-V
,
--version
¶
Print product name and version, for example:
$ ./tarantool --version Tarantool 1.6.9-1-g3a3f705 Target: Linux-x86_64-Debug ...
In this example:
“Tarantool” is the name of the reusable asynchronous networking programming framework.
The 3-number version follows the standard
<major>-<minor>-<patch>
scheme, in which<major>
number is changed only rarely,<minor>
is incremented for each new milestone and indicates possible incompatible changes, and<patch>
stands for the number of bug fix releases made after the start of the milestone. For non-released versions only, there may be a commit number and commit SHA1 to indicate how much this particular build has diverged from the last release.“Target” is the platform tarantool was built on. Some platform-specific details may follow this line.
Note
Tarantool uses git describe to produce its version id, and this id can be used at any time to check out the corresponding source from our git repository.
URI¶
Some configuration parameters and some functions depend on a URI, or
“Universal Resource Identifier”. The URI string format is similar to the
generic syntax for a URI schema.
So it may contain (in order) a user name
for login, a password, a host name or host IP address, and a port number. Only
the port number is always mandatory. The password is mandatory if the user
name is specified, unless the user name is ‘guest’. So, formally, the URI
syntax is [host:]port
or [username:password@]host:port
.
If host is omitted, then ‘0.0.0.0’ or ‘[::]’ is assumed,
meaning respectively any IPv4 address or any IPv6 address,
on the local machine.
If username:password is omitted, then ‘guest’ is assumed. Some examples:
URI fragment Example port 3301 host:port 127.0.0.1:3301 username:password@host:port notguest:sesame@mail.ru:3301
In certain circumstances a Unix domain socket may be used where a URI is expected, for example “unix/:/tmp/unix_domain_socket.sock” or simply “/tmp/unix_domain_socket.sock”.
A method for parsing URIs is illustrated in Module uri.
Initialization file¶
If the command to start Tarantool includes lua-initialization-file, then
Tarantool begins by invoking the Lua program in the file, which by convention
may have the name “script.lua
”. The Lua program may get further arguments
from the command line or may use operating-system functions, such as getenv()
.
The Lua program almost always begins by invoking box.cfg()
, if the database
server will be used or if ports need to be opened. For example, suppose
script.lua
contains the lines
#!/usr/bin/env tarantool
box.cfg{
listen = os.getenv("LISTEN_URI"),
slab_alloc_arena = 0.1,
pid_file = "tarantool.pid",
rows_per_wal = 50
}
print('Starting ', arg[1])
and suppose the environment variable LISTEN_URI contains 3301,
and suppose the command line is ~/tarantool/src/tarantool script.lua ARG
.
Then the screen might look like this:
$ export LISTEN_URI=3301
$ ~/tarantool/src/tarantool script.lua ARG
... main/101/script.lua C> version 1.6.9-1216-g73f7154
... main/101/script.lua C> log level 5
... main/101/script.lua I> mapping 107374184 bytes for a shared arena...
... main/101/script.lua I> recovery start
... main/101/script.lua I> recovering from './00000000000000000000.snap'
... main/101/script.lua I> primary: bound to 0.0.0.0:3301
... main/102/leave_local_hot_standby I> ready to accept requests
Starting ARG
... main C> entering the event loop
If you wish to start an interactive session on the same terminal after initialization is complete, you can use console.start().
Configuration parameters¶
Configuration parameters have the form:
box.cfg{[key = value [, key = value …]]}
Since box.cfg
may contain many configuration parameters and since some of the
parameters (such as directory addresses) are semi-permanent, it’s best to keep
box.cfg
in a Lua file. Typically this Lua file is the initialization file
which is specified on the tarantool command line.
Most configuration parameters are for allocating resources, opening ports, and
specifying database behavior. All parameters are optional. A few parameters are
dynamic, that is, they can be changed at runtime by calling box.cfg{}
a second time.
To see all the non-null parameters, say box.cfg
(no parentheses). To see a
particular parameter, for example the listen address, say box.cfg.listen
.
The following sections describe all parameters for basic operation, for storage, for binary logging and snapshots, for replication, for networking, and for logging.
Basic parameters¶
-
background
¶ Run the server as a background task. The log and pid_file parameters must be non-null for this to work.
Type: booleanDefault: falseDynamic: no
-
coredump
¶ Deprecated. Do not use.
Type: boolean
Default: false
Dynamic: no
-
custom_proc_title
¶ Add the given string to the server’s process title (what’s shown in the COMMAND column for
ps -ef
andtop -c
commands).For example, ordinarily
ps -ef
shows the Tarantool server process thus:$ ps -ef | grep tarantool 1000 14939 14188 1 10:53 pts/2 00:00:13 tarantool <running>
But if the configuration parameters include
custom_proc_title='sessions'
then the output looks like:$ ps -ef | grep tarantool 1000 14939 14188 1 10:53 pts/2 00:00:16 tarantool <running>: sessions
Type: stringDefault: nullDynamic: yes
-
listen
¶ The read/write data port number or URI (Universal Resource Identifier) string. Has no default value, so must be specified if connections will occur from remote clients that do not use the “admin port”. Connections made with
listen = URI
are called “binary port” or “binary protocol” connections.A typical value is 3301.
Note
A replica also binds to this port, and accepts connections, but these connections can only serve reads until the replica becomes a master.
Type: integer or stringDefault: nullDynamic: yes
-
pid_file
¶ Store the process id in this file. Can be relative to work_dir. A typical value is “
tarantool.pid
”.Type: stringDefault: nullDynamic: no
-
read_only
¶ Put the server instance in read-only mode. After this, any requests that try to change data will fail with error
ER_READONLY
.Type: booleanDefault: falseDynamic: yes
-
snap_dir
¶ A directory where memtx stores snapshot (.snap) files. Can be relative to work_dir. If not specified, defaults to
work_dir
. See also wal_dir.Type: stringDefault: “.”Dynamic: no
-
username
¶ UNIX user name to switch to after start.
Type: stringDefault: nullDynamic: no
-
wal_dir
¶ A directory where write-ahead log (.xlog) files are stored. Can be relative to work_dir. Sometimes
wal_dir
and snap_dir are specified with different values, so that write-ahead log files and snapshot files can be stored on different disks. If not specified, defaults towork_dir
.Type: stringDefault: “.”Dynamic: no
-
work_dir
¶ A directory where database working files will be stored. The server instance switches to
work_dir
with chdir(2) after start. Can be relative to the current directory. If not specified, defaults to the current directory. Other directory parameters may be relative towork_dir
, for example:box.cfg{ work_dir = '/home/user/A', wal_dir = 'B', snap_dir = 'C' }
will put xlog files in
/home/user/A/B
, snapshot files in/home/user/A/C
, and all other files or subdirectories in/home/user/A
.Type: stringDefault: nullDynamic: no
Configuring the storage¶
-
slab_alloc_arena
¶ How much memory Tarantool allocates to actually store tuples, in gigabytes. When the limit is reached, INSERT or UPDATE requests begin failing with error
ER_MEMORY_ISSUE
. While the server does not go beyond the defined limit to allocate tuples, there is additional memory used to store indexes and connection information. Depending on actual configuration and workload, Tarantool can consume up to 20% more than the limit set here.Type: float
Default: 1.0
Dynamic: no
-
slab_alloc_factor
¶ Use slab_alloc_factor as the multiplier for computing the sizes of memory chunks that tuples are stored in. A lower value may result in less wasted memory depending on the total amount of memory available and the distribution of item sizes.
Type: float
Default: 1.1
Dynamic: no
-
slab_alloc_maximal
¶ Size of the largest allocation unit, in bytes. It can be increased if it is necessary to store large tuples.
Type: integerDefault: 1024 * 1024 = 1048576Dynamic: no
-
slab_alloc_minimal
¶ Size of the smallest allocation unit, in bytes. It can be decreased if most of the tuples are very small. The value must be between 8 and 1048280 inclusive.
Type: integerDefault: 16Dynamic: no
Snapshot daemon¶
The snapshot daemon is a fiber which is constantly running. At intervals, it may make new snapshot (.snap) files and then may remove old snapshot files. If the snapshot daemon removes an old snapshot file, it will also remove any write-ahead log (.xlog) files that are older than the snapshot file and contain information that is present in the snapshot file.
The snapshot_period and snapshot_count configuration settings determine how long the intervals are, and how many snapshots should exist before removals occur.
-
snapshot_period
¶ The interval between actions by the snapshot daemon, in seconds. If
snapshot_period
is set to a value greater than zero, and there is activity which causes change to a database, then the snapshot daemon will call box.snapshot everysnapshot_period
seconds, creating a new snapshot file each time.For example:
box.cfg{snapshot_period=3600}
will cause the snapshot daemon to create a new database snapshot once per hour.
Type: integerDefault: 0 (disabled)Dynamic: yes
-
snapshot_count
¶ The maximum number of snapshots that may exist on the
snap_dir
directory before the snapshot daemon will remove old snapshots. Ifsnapshot_count
equals zero, then the snapshot daemon does not remove old snapshots. For example:box.cfg{ snapshot_period = 3600, snapshot_count = 10 }
will cause the snapshot daemon to create a new snapshot each hour until it has created ten snapshots. After that, it will remove the oldest snapshot (and any associated write-ahead-log files) after creating a new one.
Type: integerDefault: 6Dynamic: yes
Binary logging and snapshots¶
- panic_on_snap_error,
- panic_on_wal_error,
- rows_per_wal,
- snap_io_rate_limit,
- wal_mode,
- wal_dir_rescan_delay
-
panic_on_snap_error
¶ If there is an error while reading the snapshot file (at server start), abort.
Type: boolean
Default: true
Dynamic: no
-
panic_on_wal_error
¶ If there is an error while reading a snapshot file (at server instance start) or a write-ahead log file (at server instance start or to relay to a replica), abort.
Type: booleanDefault: trueDynamic: no
-
rows_per_wal
¶ How many log records to store in a single write-ahead log file. When this limit is reached, Tarantool creates another WAL file named
<first-lsn-in-wal>.xlog
. This can be useful for simple rsync-based backups.Type: integerDefault: 500000Dynamic: no
-
snap_io_rate_limit
¶ Reduce the throttling effect of box.snapshot on INSERT/UPDATE/DELETE performance by setting a limit on how many megabytes per second it can write to disk. The same can be achieved by splitting wal_dir and snap_dir locations and moving snapshots to a separate disk.
Type: floatDefault: nullDynamic: yes
-
wal_mode
¶ Specify fiber-WAL-disk synchronization mode as:
none
: write-ahead log is not maintained;write
: fibers wait for their data to be written to the write-ahead log (no fsync(2));fsync
: fibers wait for their data, fsync(2) follows each write(2);
Type: stringDefault: “write”Dynamic: yes
-
wal_dir_rescan_delay
¶ Number of seconds between periodic scans of the write-ahead-log file directory, when checking for changes to write-ahead-log files for the sake of replication or local hot standby.
Type: floatDefault: 2Dynamic: no
Replication¶
-
replication_source
¶ If
replication_source
is not an empty string, the instance is considered to be a Tarantool replica. The replica will try to connect to the master specified inreplication_source
with a URI (Universal Resource Identifier), for example:konstantin:secret_password@tarantool.org:3301
If there is more than one replication source in a replica set, specify an array of URIs, for example: (replace ‘uri’ and ‘uri2’ in this example with valid URIs):
box.cfg{ replication_source = { ‘uri1’, ‘uri2’ } }
If one of the URIs is “self” – that is, if one of the URIs is for the instance where
box.cfg{}
is being executed on – then it is ignored. Thus it is possible to use the samereplication
specification on multiple servers.The default user name is ‘guest’. A replica does not accept data-change requests on the listen port. The
replication_source
parameter is dynamic, that is, to enter master mode, simply setreplication_source
to an empty string and issue:box.cfg{ replication_source = new-value }
Type: stringDefault: nullDynamic: yes
Networking¶
-
io_collect_interval
¶ The instance will sleep for io_collect_interval seconds between iterations of the event loop. Can be used to reduce CPU load in deployments in which the number of client connections is large, but requests are not so frequent (for example, each connection issues just a handful of requests per second).
Type: floatDefault: nullDynamic: yes
-
readahead
¶ The size of the read-ahead buffer associated with a client connection. The larger the buffer, the more memory an active connection consumes and the more requests can be read from the operating system buffer in a single system call. The rule of thumb is to make sure the buffer can contain at least a few dozen requests. Therefore, if a typical tuple in a request is large, e.g. a few kilobytes or even megabytes, the read-ahead buffer size should be increased. If batched request processing is not used, it’s prudent to leave this setting at its default.
Type: integerDefault: 16320Dynamic: yes
Logging¶
-
log_level
¶ How verbose the logging is. There are six log verbosity classes:
- 1 –
SYSERROR
- 2 –
ERROR
- 3 –
CRITICAL
- 4 –
WARNING
- 5 –
INFO
- 6 –
DEBUG
By setting log_level, one can enable logging of all classes below or equal to the given level. Tarantool prints its logs to the standard error stream by default, but this can be changed with the log configuration parameter.
Type: integerDefault: 5Dynamic: yes- 1 –
-
logger
¶ By default, Tarantool sends the log to the standard error stream (
stderr
). Iflogger
is specified, Tarantool sends the log to a file, or to a pipe, or to the system logger.Example setting:
box.cfg{logger = 'tarantool.log'} -- or box.cfg{logger = 'file: tarantool.log'}
This will open the file
tarantool.log
for output on the server’s default directory. If thelogger
string has no prefix or has the prefix “file:”, then the string is interpreted as a file path.Example setting:
box.cfg{logger = '| cronolog tarantool.log'} -- or box.cfg{logger = 'pipe: cronolog tarantool.log'}'
This will start the program
cronolog
when the server starts, and will send all log messages to the standard input (stdin
) of cronolog. If thelog
string begins with ‘|’ or has the prefix “pipe:”, then the string is interpreted as a Unix pipeline.Example setting:
box.cfg{logger = 'syslog:identity=tarantool'} -- or box.cfg{logger = 'syslog:facility=user'} -- or box.cfg{logger = 'syslog:identity=tarantool,facility=user'}
If the
logger
string has the prefix “syslog:”, then the string is interpreted as a message for the syslogd program which normally is running in the background of any Unix-like platform. One can optionally specify anidentity
, afacility
, or both. Theidentity
is an arbitrary string, default value =tarantool
, which will be placed at the beginning of all messages. The facility is an abbreviation for the name of one of the syslog facilities, default value =user
, which tell syslogd where the message should go.Possible values for
facility
are: auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2, local3, local4, local5, local6, local7.The
facility
setting is currently ignored but will be used in the future.When logging to a file, Tarantool reopens the log on SIGHUP. When log is a program, its pid is saved in the log.logger_pid variable. You need to send it a signal to rotate logs.
Type: stringDefault: nullDynamic: no
-
logger_nonblock
¶ If
logger_nonblock
equals true, Tarantool does not block on the log file descriptor when it’s not ready for write, and drops the message instead. If log_level is high, and a lot of messages go to the log file, settinglogger_nonblock
to true may improve logging performance at the cost of some log messages getting lost.Type: booleanDefault: trueDynamic: no
-
too_long_threshold
¶ If processing a request takes longer than the given value (in seconds), warn about it in the log. Has effect only if log_level is more than or equal to 4 (WARNING).
Type: floatDefault: 0.5Dynamic: yes
Logging example¶
This will illustrate how “rotation” works, that is, what happens when the server instance is writing to a log and signals are used when archiving it.
Start with two terminal shells, Terminal #1 and Terminal #2.
On Terminal #1: start an interactive Tarantool session, then say the logging will go to Log_file, then put a message “Log Line #1” in the log file:
box.cfg{logger='Log_file'}
log = require('log')
log.info('Log Line #1')
On Terminal #2: use mv
so the log file is now named Log_file.bak.
The result of this is: the next log message will go to Log_file.bak.
mv Log_file Log_file.bak
On Terminal #1: put a message “Log Line #2” in the log file.
log.info('Log Line #2')
On Terminal #2: use ps
to find the process ID of the Tarantool instance.
ps -A | grep tarantool
On Terminal #2: use kill -HUP
to send a SIGHUP signal to the Tarantool instance.
The result of this is: Tarantool will open Log_file again, and
the next log message will go to Log_file.
(The same effect could be accomplished by executing log.rotate() on the instance.)
kill -HUP process_id
On Terminal #1: put a message “Log Line #3” in the log file.
log.info('Log Line #3')
On Terminal #2: use less
to examine files. Log_file.bak will have these lines,
except that the date and time will depend on when the example is done:
2015-11-30 15:13:06.373 [27469] main/101/interactive I> Log Line #1`
2015-11-30 15:14:25.973 [27469] main/101/interactive I> Log Line #2`
and Log_file will have
log file has been reopened
2015-11-30 15:15:32.629 [27469] main/101/interactive I> Log Line #3
Local hot standby¶
Local hot standby is a feature which provides a simple form of failover without replication.
The expectation is that there will be two instances of the server using the same configuration. The first one to start will be the “primary” instance. The second one to start will be the “standby” instance.
To initiate the standby instance, start a second instance of the Tarantool server on the same computer with the same box.cfg configuration settings – including the same directories and same non-null URIs. The standby instance will initialize and will try to connect on listen address, but will fail because the primary instance has already taken it. Expect to see a warning with the words
W> binary: [URI] is already in use, will retry binding after [n] seconds
.This is fine. It means that the second instance is ready to take over if the first instance goes down.
So the standby instance goes into a loop, reading the write ahead log which the primary instance is writing (so the two instances are always in synch), and trying to connect on the port. If the primary instance goes down for any reason, the port will become free so the standby instance will succeed in connecting, and will become the primary instance.
Expect to see a notification ending with the words
I> ready to accept requests
.Thus there is no noticeable downtime if the primary instance goes down.
Hot standby feature has no effect:
- if wal_dir_rescan_delay = a large number (on Mac OS and FreeBSD); on these platforms, it is designed so that the loop repeats every
wal_dir_rescan_delay
seconds.- if wal_mode = ‘none’; it is designed to work with
wal_mode = 'write'
orwal_mode = 'fsync'
.