<commit_before><!DOCTYPE book [
<!ENTITY % tnt SYSTEM "../tnt.ent">
%tnt;
]>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="server-administration">
<title>Server administration</title>
<para>
    Typical server administration tasks include starting and stopping
    the server, reloading configuration, taking snapshots, log rotation.
</para>
<section xml:id="signal-handling">
<title>Server signal handling</title>
<para>
  The server is configured to gracefully shutdown on SIGTERM and
  SIGINT (keyboard interrupt) or SIGHUP. SIGUSR1 can be used to
  save a snapshot.
  All other signals are blocked or ignored.
  The signals are processed in the main event loop. Thus, if the
  control flow never reaches the event loop (thanks to a runaway stored
  procedure), the server stops responding to any signal, and
  can be only killed with SIGKILL (this signal can not be ignored).
</para>
</section>

<section xml:id="tarantar">
<title>Utility <code>tarantar</code></title>
<para>
The tarantar utility program will create new snapshots by reading existing
snapshots and write-ahead-log (xlog) files. Thus it differs from <olink targetptr="save-snapshot"/>,
which creates new snapshots from the database. Since tarantar uses less
memory than SAVE SNAPSHOT, it is especially appropriate for taking periodic
snapshots as a background task.
</para>
<para>
To prepare: ensure that the configuration file contains 
<olink targetptr="wal_dir"/> and <olink targetptr="snap_dir"/>
clauses. Tarantar does not assume that wal_dir and snap_dir have default values.
</para>
<para>
To run:<programlisting> <command>tarantar</command> [options] <replaceable>configuration-file</replaceable></programlisting>
where possible options are:<simplelist> <member><code>-i <replaceable>seconds-count</replaceable></code> or <code>--interval <replaceable>seconds-count</replaceable></code> &mdash; repeat every seconds-count seconds. example: <code>-i 3600</code></member>
 <member><code>-n <replaceable>lsn-number</replaceable></code> or <code>--lsn <replaceable>lsn-number</replaceable></code> &mdash; start from lsn = lsn-number. if not specified, lsn = latest. example: <code>-n 5</code></member>
 <member><code>-l <replaceable>bytes-count</replaceable></code> or <code>--limit <replaceable>bytes-count</replaceable></code> &mdash; do not use more than bytes-count bytes of memory. example: <code>-l 5000000</code></member>
 <member><code>--help </code> &mdash; display a help message and exit. example: <code>--help</code></member>
 <member><code>-v </code> or <code>--version</code> &mdash; display version and exit. example: <code>-v</code></member></simplelist></para>
<para>
Example:
<programlisting>
<prompt>$ </prompt>~/tarantool/client/tarantar/tarantar -c -i 30 ./tarantool.cfg
snap_dir: /home/user/tarantool_test/work_dir
wal_dir:  /home/user/tarantool_test/work_dir
spaces:   1
interval: 30
memory_limit: 0M

START SNAPSHOTTING Fri Oct 25 09:35:25 2013

last snapshot lsn: 7
(snapshot) 00000000000000000007.snap 0.000M processed

( &gt;&gt; ) 00000000000000000006.snap 0.000M processed

START SNAPSHOTTING Fri Oct 25 09:35:55 2013

last snapshot lsn: 7
(snapshot) 00000000000000000007.snap 0.000M processed

( &gt;&gt; ) 00000000000000000006.snap 0.000M processed

snapshot exists, skip.

...

</programlisting>
</para>

<para>
For an explanation of tarantar's design see <link xlink:href="https://github.com/tarantool/tarantool/wiki/Tarantar">the Tarantool wiki</link>.
</para>

</section>

<section xml:id="tarancheck">
<title>Utility <code>tarancheck</code></title>
<para>
The tarancheck utility program will generate and verify <quote>signature files</quote>.
A signature file contains, along with basic information that identifies the database,
checksums calculated for each index in each space of the database,
based on the latest snapshot and all subsequent entries in the write-ahead log.
Signature files are useful for ensuring that databases have been saved without error,
and for quick comparisons to see whether a database's components have been modified.
</para>
<para>
The main reason that tarancheck was created was
so that users would be able to compare the
consistency of two running servers, the master and the replica.
By creating a signature file on the master using the master
directory, and then copying the signature file to the replica,
one will be able to confirm that the replica is not corrupt.
</para>
<para>
There is one necessary warning. Since either the master or the
replica is likely to be active when tarancheck runs, the check
can only be applicable for the database as of the
last transaction that was run on both the master and the replica.
That is why tarancheck displays last_xlog_lsn, which is the log
sequence number of the write-ahead log, when it finishes.
</para>

<para>
To prepare: ensure that the configuration file contains 
<olink targetptr="wal_dir"/> and <olink targetptr="snap_dir"/>
clauses. Tarancheck does not assume that wal_dir and snap_dir have default values.
</para>
<para>
To run:<programlisting> <command>tarancheck</command> [options] <replaceable>configuration-file</replaceable></programlisting>
where possible options are:<simplelist>
 <member><code>-G <replaceable>signature file</replaceable></code> or <code>--generate <replaceable>signature-file</replaceable></code> &mdash; generate signature file. example: <code>-G x.crc</code></member>
 <member><code>-V <replaceable>signature file</replaceable></code> or <code>--verify <replaceable>signature-file</replaceable></code> &mdash; verify signature file. example: <code>--verify x.crc</code></member>
 <member><code>--help </code> &mdash; display a help message and exit. example: <code>--help</code></member>
 <member><code>-v </code> or <code>--version</code> &mdash; display version and exit. example: <code>-v</code></member></simplelist></para>
<para>
Example:
<programlisting>
<prompt>$ </prompt>~/tarantool/client/tarantar/tarancheck --generate=x.crc tarantool.cfg
&gt;&gt;&gt; Signature file generation
configured spaces: 1
snap_dir: ./work_dir
wal_dir: ./work_dir
last snapshot lsn: 1
last xlog lsn: 0
(snapshot) 00000000000000000001.snap<commit_msg>server-administration.xml tarantar+tarancheck changes due to issue fixes<commit_after><!DOCTYPE book [
<!ENTITY % tnt SYSTEM "../tnt.ent">
%tnt;
]>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="server-administration">
<title>Server administration</title>
<para>
    Typical server administration tasks include starting and stopping
    the server, reloading configuration, taking snapshots, log rotation.
</para>
<section xml:id="signal-handling">
<title>Server signal handling</title>
<para>
  The server is configured to gracefully shutdown on SIGTERM and
  SIGINT (keyboard interrupt) or SIGHUP. SIGUSR1 can be used to
  save a snapshot.
  All other signals are blocked or ignored.
  The signals are processed in the main event loop. Thus, if the
  control flow never reaches the event loop (thanks to a runaway stored
  procedure), the server stops responding to any signal, and
  can be only killed with SIGKILL (this signal can not be ignored).
</para>
</section>

<section xml:id="tarantar">
<title>Utility <code>tarantar</code></title>
<para>
The tarantar utility program will create new snapshots by reading existing
snapshots and write-ahead-log (xlog) files. Thus it differs from <olink targetptr="save-snapshot"/>,
which creates new snapshots from the database. Since tarantar uses less
memory than SAVE SNAPSHOT, it is especially appropriate for taking periodic
snapshots as a background task.
</para>
<para>
To prepare: ensure that the configuration file is available.
</para>
<para>
To run:<programlisting> <command>tarantar</command> [options] <replaceable>configuration-file</replaceable></programlisting>
where possible options are:<simplelist>
 <member><code>-c </code> or <code>--create </code> &mdash; create snapshot file. example: <code>--create</code></member>
 <member><code>-i <replaceable>seconds-count</replaceable></code> or <code>--interval <replaceable>seconds-count</replaceable></code> &mdash; repeat every seconds-count seconds. example: <code>-i 3600</code></member>
 <member><code>-n <replaceable>lsn-number</replaceable></code> or <code>--lsn <replaceable>lsn-number</replaceable></code> &mdash; start from lsn = lsn-number. if not specified, lsn = latest. example: <code>-n 5</code></member>
 <member><code>-l <replaceable>bytes-count</replaceable></code> or <code>--limit <replaceable>bytes-count</replaceable></code> &mdash; do not use more than bytes-count bytes of memory. example: <code>-l 5000000</code></member>
 <member><code>-? </code> or <code>--help </code> &mdash; display a help message and exit. example: <code>--help</code></member>
 <member><code>-V </code> or <code>--version</code> &mdash; display version and exit. example: <code>-V</code></member></simplelist></para>
<para>
Example:
<programlisting>
<prompt>$ </prompt>~/tarantool/client/tarantar/tarantar -c -i 30 ./tarantool.cfg
snap_dir: /home/user/tarantool_test/work_dir
wal_dir:  /home/user/tarantool_test/work_dir
spaces:   1
interval: 30
memory_limit: 0M

START SNAPSHOTTING Fri Oct 25 09:35:25 2013

last snapshot lsn: 7
(snapshot) 00000000000000000007.snap 0.000M processed

( &gt;&gt; ) 00000000000000000006.snap 0.000M processed

START SNAPSHOTTING Fri Oct 25 09:35:55 2013

last snapshot lsn: 7
(snapshot) 00000000000000000007.snap 0.000M processed

( &gt;&gt; ) 00000000000000000006.snap 0.000M processed

snapshot exists, skip.

...

</programlisting>
</para>

<para>
For an explanation of tarantar's design see <link xlink:href="https://github.com/tarantool/tarantool/wiki/Tarantar">the Tarantool wiki</link>.
</para>

</section>

<section xml:id="tarancheck">
<title>Utility <code>tarancheck</code></title>
<para>
The tarancheck utility program will generate and verify <quote>signature files</quote>.
A signature file contains, along with basic information that identifies the database,
checksums calculated for each index in each space of the database,
based on the latest snapshot and all subsequent entries in the write-ahead log.
Signature files are useful for ensuring that databases have been saved without error,
and for quick comparisons to see whether a database's components have been modified.
</para>
<para>
The main reason that tarancheck was created was
so that users would be able to compare the
consistency of two running servers, the master and the replica.
By creating a signature file on the master using the master
directory, and then copying the signature file to the replica,
one will be able to confirm that the replica is not corrupt.
</para>
<para>
There is one necessary warning. Since either the master or the
replica is likely to be active when tarancheck runs, the check
can only be applicable for the database as of the
last transaction that was run on both the master and the replica.
That is why tarancheck displays last_xlog_lsn, which is the log
sequence number of the write-ahead log, when it finishes.
</para>

<para>
To prepare: ensure that the configuration file contains 
<olink targetptr="wal_dir"/> and <olink targetptr="snap_dir"/>
clauses. Tarancheck does not assume that wal_dir and snap_dir have default values.
</para>
<para>
To run:<programlisting> <command>tarancheck</command> [options] <replaceable>configuration-file</replaceable></programlisting>
where possible options are:<simplelist>
 <member><code>-G <replaceable>signature file</replaceable></code> or <code>--generate <replaceable>signature-file</replaceable></code> &mdash; generate signature file. example: <code>-G x.crc</code></member>
 <member><code>-W <replaceable>signature file</replaceable></code> or <code>--verify <replaceable>signature-file</replaceable></code> &mdash; verify signature file. example: <code>--verify x.crc</code></member>
 <member><code>-? </code> or <code>--help </code> &mdash; display a help message and exit. example: <code>--help</code></member>
 <member><code>-V </code> or <code>--version</code> &mdash; display version and exit. example: <code>-V</code></member></simplelist></para>
<para>
Example:
<programlisting>
<prompt>$ </prompt>~/tarantool/client/tarantar/tarancheck --generate=x.crc tarantool.cfg
&gt;&gt;&gt; Signature file generation
configured spaces: 1
snap_dir: ./work_dir
wal_dir: ./work_dir
last snapshot lsn: 1
last xlog lsn: 0
(snapshot) 00000000000000000001.snap
{'fraction_non_alphanumeric': 0.12081016679904687, 'fraction_numerical': 0.02716441620333598, 'mean_word_length': 5.301801801801802, 'pattern_counts': {'":': 0, '<': 343, '<?xml version=': 0, '>': 343, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 13}, 'pii_count': 0, 'substrings_counts': 10, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2250864', 'n_tokens_mistral': 4091, 'n_tokens_neox': 3693, 'n_words': 1350}