<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 shut down gracefully 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 only be killed with SIGKILL (this signal can not be ignored).
</para>
</section>

<section xml:id="utility-tarantool">

<title>Utility <code>tarantool</code> &mdash; using the server as a client</title>

<para>
If <code>tarantool</code> is started without an initialization file, then
there will be a prompt ("<code>tarantool&gt;</code>") and it will be possible
to enter requests. When used this way, <code>tarantool</code> is a client
program as well as a server program.
</para>
<para>
This section shows all legal syntax for the tarantool program, with short notes and examples.
Other client programs may have similar options and request syntaxes.
Some of the information in this section is duplicated in the Configuration Reference chapter.
</para>

<para>
<bridgehead renderas="sect4">Conventions used in this section</bridgehead>

Tokens are character sequences which are treated as syntactic units within requests.

Square brackets <code>[</code> and <code>]</code> enclose optional syntax.
Three dots in a row <code>...</code> mean the preceding tokens may be repeated.
A vertical bar <code>|</code> means the preceding and following tokens are mutually exclusive alternatives.
</para>

<para>
<bridgehead renderas="sect4">Options when starting client from the command line</bridgehead>

General form: <code>tarantool</code> or <code>tarantool <replaceable>file-name</replaceable></code>
or <code>tarantool <replaceable>option</replaceable>... </code>.
</para>
<para>
File-name can be any script containing code for initializing.
Effect: The code in the file is executed during startup.
Example: <code>init.lua</code>.
Notes: If a script is used, there will be no prompt. The script should contain
configuration information including "admin=..." or "listen=..." so
that a separate program can connect to the server via one of the ports.
</para>
<para>
Option is one of the following (in alphabetical order by the long form of the option):
</para>

<variablelist>
  <varlistentry>
    <term xml:id="utility-tarantool-help" xreflabel="utility-tarantool-help">--help</term>
    <listitem><para>
    Syntax: short form: <code>-?</code>
    long form: <code>--h[elp]</code>.
    Effect: Client displays a help message including a list of options.
    Example: <code>--help</code>
    Notes: The program stops after displaying the help.
    </para></listitem>
  </varlistentry>

  <varlistentry>
    <term xml:id="utility-tarantool-version" xreflabel="utility-tarantool-version">--version</term>
    <listitem><para>
    Syntax: short form: <code>-V</code>
    long form: <code>--v[ersion]</code>.
    Effect: Client displays version information.
    Example: <code>--version</code>
    Notes: The program stops after displaying the version.
    </para></listitem>
  </varlistentry>
</variablelist>

<para>
<bridgehead renderas="sect4">Tokens, requests, and special key combinations</bridgehead>
</para>

<para>
Procedure identifiers are: Any sequence of letters, digits, or underscores which is
                           legal according to the rules for Lua identifiers.
                           Procedure identifiers are also called function names.
                           Notes: function names are case insensitive so <code>insert</code> and <code>Insert</code> are not the same thing.
</para>
<para>
String literals are: Any sequence of zero or more characters enclosed in single quotes.
                     Double quotes are legal but single quotes are preferred.
                     Enclosing in double square brackets is good for multi-line strings as described in
                     <link xlink:href="http://www.lua.org/pil/2.4.html">Lua documentation</link>.
                     Examples: 'Hello, world', 'A', [[A\B!]].
</para>
<para>
Numeric literals are: Character sequences containing only digits, optionally preceded by + or -.
                      Examples: 55, -.
                      Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.
</para>
<para>
Single-byte tokens are: * or , or ( or ).
                      Examples: * , ( ).
</para>
<para>
Tokens must be separated from each other by one or more spaces, except that
spaces are not necessary around single-byte tokens or string literals.
</para>

<para xml:id="utility-tarantool-delim">
<bridgehead renderas="sect4">Requests</bridgehead>
Generally requests are entered following the prompt in interactive mode while
tarantool is running. (A prompt will be the word tarantool and a greater-than
sign, for example <code>tarantool&gt;</code>). The end-of-request marker is
by default a newline (line feed).
</para>
<para>
For multi-line requests, it is possible to change the end-of-request marker.
Syntax: <code>session = require('session'); session.delimiter(<replaceable>string-literal</replaceable>)</code>.
The string-literal must be a value in single quotes.
Effect: string becomes end-of-request delimiter, so newline alone is not treated as end of request.
To go back to normal mode: <code>session.delimiter('')<replaceable>string-literal</replaceable></code>.
Example:<programlisting>session = require('session'); session.delimiter('!')
function f ()
  statement_1 = 'a'
  statement_2 = 'b'
  end!
session.delimiter('')!</programlisting>
</para>

<para>
For a condensed Backus-Naur Form [BNF] description of the suggested form of client requests, see
    <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/box-protocol.txt"><filename>doc/box-protocol.txt</filename></link>
    and
    <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
</para>


<para>
In <emphasis>interactive</emphasis> mode, one types requests and gets results.
Typically the requests
are typed in by the user following prompts.
Here is an example of an interactive-mode tarantool client session:

<programlisting>
<prompt>$ </prompt>tarantool
                [ tarantool will display an introductory message including version number here ]
tarantool> box.cfg{admin=3301, listen=3313}
                [ tarantool will display configuration information here ]
tarantool> s = box.schema.create_space('tester')
                [ tarantool may display an in-progress message here ]
---
...
tarantool> s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
---
...
tarantool> box.space.tester:insert{1,'My first tuple'}
---
- [1, 'My first tuple']
...
tarantool> box.space.tester:select(1)
---
- - [1, 'My first tuple']
...
tarantool> box.space.tester:drop()
---
...
tarantool> os.exit()
2014-04-30 10:28:00.886 [20436] main/101/spawner I> Exiting: master shutdown
<prompt>$ </prompt>
</programlisting>
Explanatory notes about what tarantool displayed in the above example:
</para>
<para>
* Many requests return typed objects.
    In the case of "box.cfg{admin=3301, listen=3313}",
    this result is displayed on the screen.
    If the request had assigned the result to a variable, for example
    "c = box.cfg{admin=3301, listen=3313}", then
    the result would not have been displayed on the screen.
</para>
<para>
* A display of an object always begins with "---" and ends with "...".
</para>
<para>
* The insert request returns an object of type = tuple, so the object display line
    begins with a single dash ('- '). However, the select request returns
    an object of type = <emphasis>table of tuples</emphasis>, so the object display line
    begins with two dashes ('- - ').
</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,<commit_msg>Correct ports (admin = 3313, listen = 3301)<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 shut down gracefully 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 only be killed with SIGKILL (this signal can not be ignored).
</para>
</section>

<section xml:id="utility-tarantool">

<title>Utility <code>tarantool</code> &mdash; using the server as a client</title>

<para>
If <code>tarantool</code> is started without an initialization file, then
there will be a prompt ("<code>tarantool&gt;</code>") and it will be possible
to enter requests. When used this way, <code>tarantool</code> is a client
program as well as a server program.
</para>
<para>
This section shows all legal syntax for the tarantool program, with short notes and examples.
Other client programs may have similar options and request syntaxes.
Some of the information in this section is duplicated in the Configuration Reference chapter.
</para>

<para>
<bridgehead renderas="sect4">Conventions used in this section</bridgehead>

Tokens are character sequences which are treated as syntactic units within requests.

Square brackets <code>[</code> and <code>]</code> enclose optional syntax.
Three dots in a row <code>...</code> mean the preceding tokens may be repeated.
A vertical bar <code>|</code> means the preceding and following tokens are mutually exclusive alternatives.
</para>

<para>
<bridgehead renderas="sect4">Options when starting client from the command line</bridgehead>

General form: <code>tarantool</code> or <code>tarantool <replaceable>file-name</replaceable></code>
or <code>tarantool <replaceable>option</replaceable>... </code>.
</para>
<para>
File-name can be any script containing code for initializing.
Effect: The code in the file is executed during startup.
Example: <code>init.lua</code>.
Notes: If a script is used, there will be no prompt. The script should contain
configuration information including "admin=..." or "listen=..." so
that a separate program can connect to the server via one of the ports.
</para>
<para>
Option is one of the following (in alphabetical order by the long form of the option):
</para>

<variablelist>
  <varlistentry>
    <term xml:id="utility-tarantool-help" xreflabel="utility-tarantool-help">--help</term>
    <listitem><para>
    Syntax: short form: <code>-?</code>
    long form: <code>--h[elp]</code>.
    Effect: Client displays a help message including a list of options.
    Example: <code>--help</code>
    Notes: The program stops after displaying the help.
    </para></listitem>
  </varlistentry>

  <varlistentry>
    <term xml:id="utility-tarantool-version" xreflabel="utility-tarantool-version">--version</term>
    <listitem><para>
    Syntax: short form: <code>-V</code>
    long form: <code>--v[ersion]</code>.
    Effect: Client displays version information.
    Example: <code>--version</code>
    Notes: The program stops after displaying the version.
    </para></listitem>
  </varlistentry>
</variablelist>

<para>
<bridgehead renderas="sect4">Tokens, requests, and special key combinations</bridgehead>
</para>

<para>
Procedure identifiers are: Any sequence of letters, digits, or underscores which is
                           legal according to the rules for Lua identifiers.
                           Procedure identifiers are also called function names.
                           Notes: function names are case insensitive so <code>insert</code> and <code>Insert</code> are not the same thing.
</para>
<para>
String literals are: Any sequence of zero or more characters enclosed in single quotes.
                     Double quotes are legal but single quotes are preferred.
                     Enclosing in double square brackets is good for multi-line strings as described in
                     <link xlink:href="http://www.lua.org/pil/2.4.html">Lua documentation</link>.
                     Examples: 'Hello, world', 'A', [[A\B!]].
</para>
<para>
Numeric literals are: Character sequences containing only digits, optionally preceded by + or -.
                      Examples: 55, -.
                      Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.
</para>
<para>
Single-byte tokens are: * or , or ( or ).
                      Examples: * , ( ).
</para>
<para>
Tokens must be separated from each other by one or more spaces, except that
spaces are not necessary around single-byte tokens or string literals.
</para>

<para xml:id="utility-tarantool-delim">
<bridgehead renderas="sect4">Requests</bridgehead>
Generally requests are entered following the prompt in interactive mode while
tarantool is running. (A prompt will be the word tarantool and a greater-than
sign, for example <code>tarantool&gt;</code>). The end-of-request marker is
by default a newline (line feed).
</para>
<para>
For multi-line requests, it is possible to change the end-of-request marker.
Syntax: <code>session = require('session'); session.delimiter(<replaceable>string-literal</replaceable>)</code>.
The string-literal must be a value in single quotes.
Effect: string becomes end-of-request delimiter, so newline alone is not treated as end of request.
To go back to normal mode: <code>session.delimiter('')<replaceable>string-literal</replaceable></code>.
Example:<programlisting>session = require('session'); session.delimiter('!')
function f ()
  statement_1 = 'a'
  statement_2 = 'b'
  end!
session.delimiter('')!</programlisting>
</para>

<para>
For a condensed Backus-Naur Form [BNF] description of the suggested form of client requests, see
    <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/box-protocol.txt"><filename>doc/box-protocol.txt</filename></link>
    and
    <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
</para>


<para>
In <emphasis>interactive</emphasis> mode, one types requests and gets results.
Typically the requests
are typed in by the user following prompts.
Here is an example of an interactive-mode tarantool client session:

<programlisting>
<prompt>$ </prompt>tarantool
                [ tarantool will display an introductory message including version number here ]
tarantool> box.cfg{admin=3313, listen=3301}
                [ tarantool will display configuration information here ]
tarantool> s = box.schema.create_space('tester')
                [ tarantool may display an in-progress message here ]
---
...
tarantool> s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
---
...
tarantool> box.space.tester:insert{1,'My first tuple'}
---
- [1, 'My first tuple']
...
tarantool> box.space.tester:select(1)
---
- - [1, 'My first tuple']
...
tarantool> box.space.tester:drop()
---
...
tarantool> os.exit()
2014-04-30 10:28:00.886 [20436] main/101/spawner I> Exiting: master shutdown
<prompt>$ </prompt>
</programlisting>
Explanatory notes about what tarantool displayed in the above example:
</para>
<para>
* Many requests return typed objects.
    In the case of "box.cfg{admin=3313, listen=3301}",
    this result is displayed on the screen.
    If the request had assigned the result to a variable, for example
    "c = box.cfg{admin=3313, listen=3301}", then
    the result would not have been displayed on the screen.
</para>
<para>
* A display of an object always begins with "---" and ends with "...".
</para>
<para>
* The insert request returns an object of type = tuple, so the object display line
    begins with a single dash ('- '). However, the select request returns
    an object of type = <emphasis>table of tuples</emphasis>, so the object display line
    begins with two dashes ('- - ').
</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,
{'fraction_non_alphanumeric': 0.1150046490004649, 'fraction_numerical': 0.00894932589493259, 'mean_word_length': 3.844876126126126, 'pattern_counts': {'":': 0, '<': 329, '<?xml version=': 0, '>': 345, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, 'xml': 18}, 'pii_count': 0, 'substrings_counts': 0, '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': '2867790', 'n_tokens_mistral': 5100, 'n_tokens_neox': 4879, 'n_words': 1894}