<!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>
<bridgehead renderas="sect4">Why tarantar?</bridgehead>
To recapitulate the idea of a snapshot and a write-ahead log:
Tarantool's database is entirely in memory; however, it has a
complete and up-to-date on-disk backup.  This consists of snapshot
files (extension .snap) which are copies of the database as of the
time the snapshot was taken, and write-ahead-log files (extension
.xlog) which contain records of insert/update/delete operations that
are written when the operations occur. If the tarantool_box server
goes down and later restarts, it will recover the database by
reading the snapshot and then re-applying the write-ahead-log records.
</para>

<para>
The approach is reliable. But if the snapshot gets old and the
number of write-ahead-log records get huge, then recovery would
take too long and .xlog files would take too much space.
So periodically one should make new snapshots -- if a .snap file
is up to date, then the .xlog files are unnecessary and can be
archived.
</para>

<para>
To take a snapshot with the tarantool client, one can say
SAVE SNAPSHOT. SAVE SNAPSHOT will copy every tuple from
the in-memory database to the .snap file. However, this
is not always the ideal method.
</para>

<para>
Taking snapshots with tarantar, instead of with SAVE SNAPSHOT,
can be better because:
<itemizedlist>
  <listitem><para>tarantar can work even if the tarantool_box server is down
  because it works from the existing .xnap and .xlog files,
   rather than from an in-memory database.</para></listitem>
   <listitem><para>tarantar saves memory when constructing its own in-memory
  index to the rows by making SHA-1 hashes for primary keys
  that contain strings or that are multi-column and longer
   than 20 bytes</para></listitem>
   <listitem><para>tarantar can be made to limit its memory usage so that
  it does not interfere with resource use by other processes
   including other Tarantool-related processes.</para></listitem>
   <listitem><para>
  tarantar can be made to run periodically as a daemon</para></listitem>
</itemizedlist>
</para>

<para>
For more 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
(signature) saving x.crc
</programlisting>
</para>

</section>

<section xml:id="tarantool_deploy">
<title>Utility <code>tarantool_deploy</code></title>
<para>
With tarantool_deploy one can set up so that, during system boot,
one or more instances of the tarantool_box server will start.
This utility is for use on Red Hat or CentOS where Tarantool
was installed using <code>rpm --install</code>.
</para>
<para>
Technically, tarantool_deploy will place instructions in <filename>/etc/init.d</filename>
which will initiate tarantool_box with appropriate options and
with settings that maximize resource usage.
The root password is necessary. These options are available,
as shown by <code>tarantool_deploy --help</code>:
<programlisting>
Tarantool deployment script: add more Tarantool instances.
usage: tarantool_deploy.sh [options] &lt;instance&gt;

  --prefix &lt;path&gt;       installation path (/usr)
  --prefix_etc &lt;path&gt;   installation etc path (/etc)
  --prefix_var &lt;path&gt;   installation var path (/var)

  --status              display deployment status
  --dry                 don't create anything, show commands

  --debug               show commands
  --yes                 don't prompt
  --help                display this usage
</programlisting>
</para>
<para>
The default prefixes (<filename>/usr</filename> and <filename>/etc</filename> and <filename>/var</filename>) are appropriate
if a Tarantool installation was done with default settings,
for example tarantool_box should be in <filename>/usr/bin</filename>.
The only necessary argument is the "instance", which is an
arbitrary numeric identification formatted as digit.digit.
The following is a sample run:
<programlisting><prompt>$ </prompt>tarantool_deploy.sh 0.1
tarantool_deploy.sh: About to deploy Tarantool instance 0.1.
tarantool_deploy.sh: Continue? [n/y]
y
tarantool_deploy.sh: &gt;&gt;&gt; deploy instance 0.1
tarantool_deploy.sh: &gt;&gt;&gt; updating deployment config
tarantool_deploy.sh: done
</programlisting>
</para>
</section>

<section xml:id="os-install-notes">
<title>System-specific administration notes</title>
<blockquote><para>
  This chapter provides a cheatsheet for most common server management
  routines on every supported operating system.
</para></blockquote>

  <section xml:id="Debian">
    <title>Debian GNU/Linux and Ubuntu</title>
    <para>
        Setting up an instance: ln -s /etc/tarantool/instances.available/instance-name.cfg /etc/tarantool/instances.enabled/
    </para>
    <para>
        Starting all instances: service tarantool start
    </para>
    <para>
        Stopping all instances: service tarantool stop
    </para>
    <para>
        Starting/stopping one instance: service tarantool-instance-name start/stop
    </para>
  </section>
  <section xml:id="rpm-based-distros">
    <title>Fedora, RHEL, CentOS</title>
    <para>
        tba
    </para>
  </section>

  <section xml:id="FreeBSD">
    <title>FreeBSD</title>
    <para>
        tba
    </para>
  </section>

  <section xml:id="mac-os-x">
    <title>Mac OS X</title>
    <para>
        tba
    </para>
  </section>

</section>

</chapter>

<!--
vim: tw=66 syntax=docbk
vim: spell spelllang=en_us
-->
