diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore
index 7705395c26abd9044835278630dc14086fe4aee3..37d0c8b719d2d8cfc75ca6b3dc4df5f78981d622 100644
--- a/doc/sphinx/.gitignore
+++ b/doc/sphinx/.gitignore
@@ -1,2 +1,4 @@
!.gitignore
*.pyc
+_html_build
+_single_build
diff --git a/doc/sphinx/CMakeLists.txt b/doc/sphinx/CMakeLists.txt
index 9b1373a70ec74ab1ba6c731c69f0620f9eb30b9e..e0b651417f5fb7afa8959d578ae832bbec106d70 100644
--- a/doc/sphinx/CMakeLists.txt
+++ b/doc/sphinx/CMakeLists.txt
@@ -2,7 +2,8 @@ find_package(Sphinx REQUIRED)
#find_program(MKDIR mkdir)
-set(SPHINX_BUILD_DIR "${PROJECT_BINARY_DIR}/doc/sphinx/_build/")
+set(SPHINX_BUILD_SINGLE_DIR "${PROJECT_BINARY_DIR}/doc/sphinx/_single_build/")
+set(SPHINX_BUILD_HTML_DIR "${PROJECT_BINARY_DIR}/doc/sphinx/_html_build/")
set(SPHINX_HTML_DIR "${PROJECT_BINARY_DIR}/doc/www/output/doc/")
#add_custom_command(OUTPUT
@@ -14,7 +15,7 @@ add_custom_target(sphinx-html ALL
# DEPENDS ${SPHINX_BUILD_DIR} ${SPHINX_HTML_DIR}
COMMAND "${SPHINX_EXECUTABLE}"
-b html
- -d "${SPHINX_BUILD_DIR}"
+ -d "${SPHINX_BUILD_SINGLE_DIR}"
-c html/
"${PROJECT_SOURCE_DIR}/doc/sphinx"
"${SPHINX_HTML_DIR}"
@@ -24,9 +25,10 @@ add_custom_target(sphinx-html ALL
add_custom_target(sphinx-singlehtml ALL
COMMAND "${SPHINX_EXECUTABLE}"
-b singlehtml
- -d "${SPHINX_BUILD_DIR}"
+ -d "${SPHINX_BUILD_HTML_DIR}"
-c singlehtml/
"${PROJECT_SOURCE_DIR}/doc/sphinx"
"${SPHINX_HTML_DIR}"
+ singlehtml.rst
COMMENT "Building HTML documentation with Sphinx"
)
diff --git a/doc/sphinx/_static/headers.js b/doc/sphinx/_static/headers.js
index ac5cd6a0f63ebe0cacb6724ae3605c2ca12be20d..6e5f577cfc7cc2796e9a1612b2dc4a849c3e5b57 100644
--- a/doc/sphinx/_static/headers.js
+++ b/doc/sphinx/_static/headers.js
@@ -23,7 +23,7 @@ $(document).ready(function () {
$(el).html(icon + $(el).html());
}
);
-
+ $(".b-cols_content_left").pin({containerSelector: ".b-cols_content"});
});
// vim: syntax=javascript ts=2 sts=2 sw=2 expandtab
diff --git a/doc/sphinx/_static/jquery.pin.min.js b/doc/sphinx/_static/jquery.pin.min.js
new file mode 100644
index 0000000000000000000000000000000000000000..04cc68d23659c62c3b92c129f5e6bd856ca98097
--- /dev/null
+++ b/doc/sphinx/_static/jquery.pin.min.js
@@ -0,0 +1 @@
+(function(e){"use strict";e.fn.pin=function(t){var n=0,r=[],i=false,s=e(window);t=t||{};var o=function(){for(var n=0,o=r.length;n<o;n++){var u=r[n];if(t.minWidth&&s.width()<=t.minWidth){if(u.parent().is(".pin-wrapper")){u.unwrap()}u.css({width:"",left:"",top:"",position:""});if(t.activeClass){u.removeClass(t.activeClass)}i=true;continue}else{i=false}var a=t.containerSelector?u.closest(t.containerSelector):e(document.body);var f=u.offset();var l=a.offset();var c=u.offsetParent().offset();if(!u.parent().is(".pin-wrapper")){u.wrap("<div class='pin-wrapper'>")}var h=e.extend({top:0,bottom:0},t.padding||{});u.data("pin",{pad:h,from:(t.containerSelector?l.top:f.top)-h.top,to:l.top+a.height()-u.outerHeight()-h.bottom,end:l.top+a.height(),parentTop:c.top});u.css({width:u.outerWidth()});u.parent().css("height",u.outerHeight())}};var u=function(){if(i){return}n=s.scrollTop();var o=[];for(var u=0,a=r.length;u<a;u++){var f=e(r[u]),l=f.data("pin");if(!l){continue}o.push(f);var c=l.from-l.pad.bottom,h=l.to-l.pad.top;if(c+f.outerHeight()>l.end){f.css("position","");continue}if(c<n&&h>n){!(f.css("position")=="fixed")&&f.css({left:f.offset().left,top:l.pad.top}).css("position","fixed");if(t.activeClass){f.addClass(t.activeClass)}}else if(n>=h){f.css({left:"",top:h-l.parentTop+l.pad.top}).css("position","absolute");if(t.activeClass){f.addClass(t.activeClass)}}else{f.css({position:"",top:"",left:""});if(t.activeClass){f.removeClass(t.activeClass)}}}r=o};var a=function(){o();u()};this.each(function(){var t=e(this),n=e(this).data("pin")||{};if(n&&n.update){return}r.push(t);e("img",this).one("load",o);n.update=a;e(this).data("pin",n)});s.scroll(u);s.resize(function(){o()});o();s.load(a);return this}})(jQuery)
\ No newline at end of file
diff --git a/doc/sphinx/_static/sphinx_design.css b/doc/sphinx/_static/sphinx_design.css
index 2ee104651a6984d2d125a2ad11b4b4e8a4bfcfe6..760feb48d4d87e9f3d201709a9abc0039231f607 100644
--- a/doc/sphinx/_static/sphinx_design.css
+++ b/doc/sphinx/_static/sphinx_design.css
@@ -121,10 +121,10 @@ a.headerlink {
margin: 5px;
font-size: 16px;
}
-.b-documentation_top.p-documentation_in .b-section-title {
+.p-documentation_in .b-section-title {
margin:0 0 17px 0;
}
-.b-documentation_top.p-documentation_in .b-block-wrapper {
+.p-documentation_in .b-block-wrapper {
padding: 20px 0 21px 0;
}
@@ -198,6 +198,7 @@ a.headerlink {
.b-page_header {
margin-bottom: 10px;
+ padding-top: 4px;
}
.headerlink {
@@ -235,7 +236,7 @@ tr.field td p {
position:relative;
float:left;
width:295px;
- padding:30px 0 0 0;
+ padding:15px 0 0 0;
}
.b-cols_content_right {
float:right;
@@ -346,3 +347,24 @@ ul.search {
ul.search li div.context {
margin-top: 5px;
}
+
+div.b-cols_content_left #searchbox {
+ width: 267px;
+}
+
+div.b-cols_content_left .b-search-text {
+ width: 240px;
+}
+
+.b-documentation_top .b-section-title {
+ float: left;
+}
+
+.b-documentation_top .b-search {
+ float: right;
+}
+
+.b-cols_content>.pin-wrapper {
+ float: left;
+ position: relative;
+}
diff --git a/doc/sphinx/_templates/base b/doc/sphinx/_templates/base
index 478c571a35820ce3c77e03dca1d31ed654294ec8..6cde8a4190481300eae31612573f2b0e470b6b4e 100644
--- a/doc/sphinx/_templates/base
+++ b/doc/sphinx/_templates/base
@@ -1,6 +1,6 @@
-{% import "menu" as menu %}
+{% import "menu" as menu with context %}
-{% set script_files = ['https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js'] + script_files %}
+{% set script_files = script_files %}
{% set css_files = ['/theme/design.css', '/theme/pygmentize.css'] + css_files %}
<!doctype html>
@@ -42,7 +42,7 @@
<header class="b-header">
<div class="b-header-wrapper">
<nav class="b-header_menu">
- {{ menu.i_menu({slug:'documentation'}) }}
+ {{ menu.i_menu(page) }}
</nav>
</div>
</header>
@@ -57,7 +57,7 @@
<footer class="b-footer">
<div class="b-footer-wrapper">
<nav class="b-footer_menu">
- {{ menu.i_menu({slug:'documentation'}) }}
+ {{ menu.i_menu(page) }}
<div class="b-footer-other">
<a href="http://stable.tarantool.org">1.5 web site and downloads</a>
</div>
diff --git a/doc/sphinx/_templates/layout.html b/doc/sphinx/_templates/layout.html
index eb05865327248cb62e14aec3176e52a961de4101..dbd4b25ffc0193920750c46cbe0240cb09db9e41 100644
--- a/doc/sphinx/_templates/layout.html
+++ b/doc/sphinx/_templates/layout.html
@@ -2,7 +2,8 @@
{% import "breadcrumbs" as breadcrumbs with context %}
{% import "navbar" as navbar with context %}
-{% set script_files = ['_static/headers.js'] + script_files %}
+{% set page = {"slug": "documentation"} %}
+{% set script_files = script_files + ['_static/jquery.pin.min.js', '_static/headers.js'] %}
{% set css_files = ['_static/sphinx_design.css', '//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css'] + css_files %}
{% set render_sidebar = true %}
@@ -18,21 +19,18 @@
{% endif %}
<div class="b-block-wrapper">
<h2 class="b-section-title">{{ title }}</h2>
- {%- if builder != "singlehtml" %}
- <form id="searchbox" role="search" class="search b-search" action="{{ pathto('search') }}" method="get">
- <input class="b-search-text" name="q" type="text"/>
- <input class="b-search-but" type="submit" />
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
- </div>
- {%- endif %}
+ {% if title == 'Documentation' %}
+ {% include "searchbox.html" %}
+ {% endif %}
</div>
</section>
{%- if render_sidebar %}
<div class="b-cols_content b-clearbox">
<div class="b-cols_content_left">
+ {% if title != 'Documentation' %}
+ {% include "searchbox.html" %}
+ {% endif %}
{{ toctree(maxdepth=2) }}
- {% block sidebar %} {% endblock %}
</div>
<div class="b-cols_content_right">
<div class="b-cols_content_right-slot">
diff --git a/doc/sphinx/_templates/menu b/doc/sphinx/_templates/menu
index a475b471f6367b29d06dea4f1a13e875108ff588..7556b6cc52ead1d44f32a8b370b2c3031717a5db 100644
--- a/doc/sphinx/_templates/menu
+++ b/doc/sphinx/_templates/menu
@@ -1,4 +1,3 @@
-
{# Modify i_links to add records to site #}
{% set i_links = [
("Overview", "http://tarantool.org"),
diff --git a/doc/sphinx/_templates/searchbox.html b/doc/sphinx/_templates/searchbox.html
new file mode 100644
index 0000000000000000000000000000000000000000..508b4b30257d4d207f3b38c565122adc9a9aec70
--- /dev/null
+++ b/doc/sphinx/_templates/searchbox.html
@@ -0,0 +1,10 @@
+{%- if builder != "singlehtml" %}
+<form id="searchbox" role="search" class="search b-search" action="{{ pathto('search') }}" method="get">
+ <input class="b-search-text" name="q" type="text"/ placeholder="Search">
+ <input class="b-search-but" type="submit" />
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+</form>
+{%- endif %}
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/book/administration.rst b/doc/sphinx/book/administration.rst
index e95163ca6bece5fc9c8975ef4a3e3f34d3950bc9..6d059251a2a5db4b333aa69d7581be5ba3f6fbde 100644
--- a/doc/sphinx/book/administration.rst
+++ b/doc/sphinx/book/administration.rst
@@ -30,7 +30,7 @@ a client for a remote server.
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
-:doc:`/book/configuration` chapter.
+:ref:`book-cfg` chapter.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Conventions used in this section
diff --git a/doc/sphinx/book/app_a_errcodes.rst b/doc/sphinx/book/app_a_errcodes.rst
index 60f25a917d74c45edc2d385139a9a64b5d40756f..6034e2acf69d5ec56aaa41230ea965c24d429034 100644
--- a/doc/sphinx/book/app_a_errcodes.rst
+++ b/doc/sphinx/book/app_a_errcodes.rst
@@ -24,7 +24,7 @@ ER_ILLEGAL_PARAMS
Illegal parameters. Malformed protocol message.
ER_MEMORY_ISSUE
- Out of memory: :ref:`slab_alloc_arena <slab_alloc_arena>` limit is reached.
+ Out of memory: :confval:`slab_alloc_arena` limit is reached.
ER_WAL_IO
Failed to write to disk. May mean: failed to record a change in the
diff --git a/doc/sphinx/book/app_b_proctitle.rst b/doc/sphinx/book/app_b_proctitle.rst
index c4f540f0121768379cf1741c75c54d7585653a32..1c70b3626ce8b5215d276b8c690744ab0da7d976 100644
--- a/doc/sphinx/book/app_b_proctitle.rst
+++ b/doc/sphinx/book/app_b_proctitle.rst
@@ -1,3 +1,5 @@
+.. _book-proctitle:
+
-------------------------------------------------------------------------------
Appendix B. Process title
-------------------------------------------------------------------------------
@@ -8,14 +10,14 @@ meet the needs of system administration, such as figuring out what services are
running on a host, their status, and so on.
A Tarantool server process title follows the following naming scheme:
-**program_name: role[@`custom_proc_title`_]**
+**program_name: role[@** :confval:`custom_proc_title` **]**
**program_name** is typically **tarantool**. The role can be one of the following:
* **running** -- ordinary node "ready to accept requests",
* **loading** -- ordinary node recovering from old snap and wal files,
* **orphan** -- not in a cluster,
-* **hot_standby** -- see section :ref:`local_hot_standby`,
+* **hot_standby** -- see section :confval:`local_hot_standby`,
* **dumper + process-id** -- saving a snapshot,
For example:
diff --git a/doc/sphinx/book/box/admin.rst b/doc/sphinx/book/box/admin.rst
index f0c35b632f31969dd89a391300766670fa34b1b7..739b3ff1642b6cbbb84fe63509c9ece939e08be3 100644
--- a/doc/sphinx/book/box/admin.rst
+++ b/doc/sphinx/book/box/admin.rst
@@ -7,7 +7,7 @@ A reference description also follows below:
.. function:: box.snapshot()
- Take a snapshot of all data and store it in :ref:`snap_dir <snap_dir>`/<latest-lsn>.snap.
+ Take a snapshot of all data and store it in :confval:`snap_dir`:samp:`/{<latest-lsn>}.snap`.
To take a snapshot, Tarantool first enters the delayed garbage collection
mode for all data. In this mode, tuples which were allocated before the
snapshot has started are not freed until the snapshot has finished. To
@@ -20,7 +20,7 @@ A reference description also follows below:
saved in a matter of minutes. Note, that as long as there are any changes to
the parent index memory through concurrent updates, there are going to be
page splits, and therefore one needs to have some extra free memory to run
- this command. 10% of :ref:`slab_alloc_arena <slab_alloc_arena>` is, on average,
+ this command. 10% of :confval:`slab_alloc_arena` is, on average,
sufficient. This statement waits until a snapshot is taken and returns operation result.
.. code-block:: lua
@@ -58,6 +58,3 @@ A reference description also follows below:
.. function:: require('fiber').info()
Show all running fibers, with their stack. Mainly useful for debugging.
-
-.. _snap_dir: :ref:`snap_dir`
-.. _slab_alloc_arena: :ref:`slab_alloc_arena`
diff --git a/doc/sphinx/book/box/box_introspection.rst b/doc/sphinx/book/box/box_introspection.rst
index cb4887f174d50170d5048ccd207f44b558502a62..efb22418dfd5025a83de3544664f40fd571f1011 100644
--- a/doc/sphinx/book/box/box_introspection.rst
+++ b/doc/sphinx/book/box/box_introspection.rst
@@ -10,7 +10,7 @@
The ``box.cfg`` package is for administrators to specify all the server
configuration parameters; the full description of the parameters is in
-section :ref:`box-configuration`. Use ``box.cfg`` without braces to get read-only
+section :ref:`book-cfg`. Use ``box.cfg`` without braces to get read-only
access to those parameters.
.. data:: box.cfg
@@ -134,8 +134,8 @@ so bytes_used = 1024); there is 1 item stored in the 136-byte slab
(and 136*1=136 so bytes_used = 136); the arena_used value is the total of all
the bytes_used values (1024+136 = 1160); the arena_size value is the arena_used
value plus the total of all the bytes_free values (1160+4193200+4194088 = 8388448).
-The arena_size and arena_used values are the amount of the % of slab_alloc_arena
-that is already distributed to the slab allocator.
+The arena_size and arena_used values are the amount of the % of
+:confval:`slab_alloc_arena` that is already distributed to the slab allocator.
.. data:: slab
diff --git a/doc/sphinx/book/box/limitations.rst b/doc/sphinx/book/box/limitations.rst
index 532c76dbd852fe275017cc801e69dbd23c5787fd..109cdbf43412950fdc1a36fe8c0daaa34217bb6a 100644
--- a/doc/sphinx/book/box/limitations.rst
+++ b/doc/sphinx/book/box/limitations.rst
@@ -24,7 +24,7 @@ Number of connections
Space size
The total maximum size for all spaces is in effect set by
- :ref:`slab_alloc_arena <slab_alloc_arena>`, which in turn
+ :confval:`slab_alloc_arena`, which in turn
is limited by the total available memory.
Update operations count
diff --git a/doc/sphinx/book/configuration.rst b/doc/sphinx/book/configuration.rst
deleted file mode 100644
index 35416a9de78afe03240c4350086b83865123bd3a..0000000000000000000000000000000000000000
--- a/doc/sphinx/book/configuration.rst
+++ /dev/null
@@ -1,482 +0,0 @@
-.. _box-configuration:
-
--------------------------------------------------------------------------------
- Configuration reference
--------------------------------------------------------------------------------
-
-This chapter provides a reference of options which can be set on the command
-line or in an initialization file.
-
-Tarantool is started by entering the command:
-
-.. program:: tarantool
-
-.. code-block:: bash
-
- $ tarantool
- OR
- $ tarantool <options>
- OR
- $ tarantool <lua-initialization-file> [arguments]
-
-=====================================================================
- Command options
-=====================================================================
-
-.. option:: -h, --help
-
- Print an annotated list of all available options and exit.
-
-.. option:: -V, --version
-
- Print product name and version, for example:
-
- .. code-block:: bash
-
- $ ./tarantool --version
- Tarantool 1.6.3-439-g7e1011b
- 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`_.
-
-.. _git describe: http://www.kernel.org/pub/software/scm/git/docs/git-describe.html
-.. _git repository: http://github.com/tarantool/tarantool.git
-
-
-.. _URI:
-
-=====================================================================
- 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 'localhost' is assumed.
-If username:password is omitted, then 'guest' is assumed. Some examples:
-
-.. _generic syntax for a URI schema: http://en.wikipedia.org/wiki/URI_scheme#Generic_syntax
-
-.. container:: table
-
- +-----------------------------+------------------------------+
- | 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 socket may be used where a URI is required.
-
-=====================================================================
- 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
-
-.. code-block:: lua
-
- #!/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:
-
-.. code-block:: lua
-
- $ export LISTEN_URI=3301
- $ ~/tarantool/src/tarantool script.lua ARG
- ... main/101/script.lua C> version 1.6.3-439-g7e1011b
- ... 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
-
-.. _local_hot_standby:
-.. _replication_port:
-.. _slab_alloc_arena:
-.. _replication_source:
-.. _admin_port:
-.. _snap_dir:
-.. _wal_dir:
-.. _wal_mode:
-.. _snapshot daemon:
-.. _logger:
-
-=====================================================================
- 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 tables describe all parameters for basic operation, for storage,
-for binary logging and snapshots, for replication, for networking, and for logging.
-
-.. container:: table
-
- **Basic parameters**
-
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +===================+===========+==========+==========+=================================================+
- | username | string | null | no | UNIX user name to switch to after start. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | work_dir | string | null | no | A directory where database working files will |
- | | | | | be stored. The server switches to work_dir with |
- | | | | | chdir(2) after start. Can be relative to the |
- | | | | | current directory. If not specified, defaults |
- | | | | | to the current directory. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | wal_dir | string | "." | no | A directory where write-ahead log (.xlog) files |
- | | | | | are stored. Can be relative to work_dir. Most |
- | | | | | commonly used so that snapshot files and |
- | | | | | write-ahead log files can be stored on separate |
- | | | | | disks. If not specified, defaults to work_dir. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | snap_dir | string | "." | no | A directory where snapshot (.snap) files will |
- | | | | | be stored. Can be relative to work_dir. If not |
- | | | | | specified, defaults to work_dir. See also |
- | | | | | :ref:`wal_dir`. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | sophia_dir | string | "sophia" | no | A directory where sophia files will be stored. |
- | | | | | Can be relative to work_dir. If not specified, |
- | | | | | defaults to ``work_dir/sophia``. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | coredump | boolean | "false" | no | Deprecated. Do not use. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | listen | integer | "null" | yes | The read/write data port number or `URI`_ |
- | | or string | | | (Universal Resource Identifier) string. Has no |
- | | | | | default value, so must be specified if |
- | | | | | connections will occur from remote clients that |
- | | | | | do not use "admin address" (the administrative |
- | | | | | host and port). Note: a replica also binds to |
- | | | | | this port, and accepts connections, but these |
- | | | | | connections can only serve reads until the |
- | | | | | replica becomes a master. A typical value is |
- | | | | | 3301. The listen parameter may also be set |
- | | | | | for `local hot standby`_. |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | pid_file | string | "null" | no | Store the process id in this file. Can be |
- | | | | | relative to work_dir. A typical value is |
- | | | | | "tarantool.pid". |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | custom_proc_title | string | "null" | no | Inject the given string into |
- | | | | | :doc:`app_b_proctitle` (what's shown in the |
- | | | | | COMMAND column for ps and top commands). |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
- | background | boolean | false | no | Run the server as a background task. The logger |
- | | | | | and pid_file parameters must be non-null for |
- | | | | | this to work. |
- | | | | | |
- +-------------------+-----------+----------+----------+-------------------------------------------------+
-
- .. NOTE::
-
- **custom_proc_title**
-
- For example, ordinarily ps shows the Tarantool server process thus:
-
- .. code-block:: lua
-
- $ ps -ef | grep tarantool
- 1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running
- 1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner
- tarantool: primary pri: 3301 adm: 3313
-
- But if the configuration parameters include
- ``custom_proc_title='sessions'`` then the output looks like:
-
- .. code-block:: lua
-
- $ ps -ef | grep tarantool
- 1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running@sessions
- 1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner@sessions
- tarantool: primary pri: 3301 adm: 3313
-
- **Configuring the storage**
-
- +--------------------------+-----------+----------+----------+-------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +==========================+===========+==========+==========+=================================================+
- | slab_alloc_arena | float | null | no | How much memory Tarantool allocates to actually |
- | | | | | store tuples, in gigabytes. When the limit is |
- | | | | | reached, INSERT or UPDATE requests begin |
- | | | | | failing with error :ref:`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. |
- +--------------------------+-----------+----------+----------+-------------------------------------------------+
- | slab_alloc_minimal | integer | 64 | no | Size of the smallest allocation unit. It can be |
- | | | | | tuned down if most of the tuples are very small |
- +--------------------------+-----------+----------+----------+-------------------------------------------------+
- | slab_alloc_maximal | integer | 1048576 | no | Size of the largest allocation unit. It can be |
- | | | | | tuned down up if it is necessary to store large |
- | | | | | tuples. |
- +--------------------------+-----------+----------+----------+-------------------------------------------------+
- | slab_alloc_factor | float | 2.0 | no | 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. |
- +--------------------------+-----------+----------+----------+-------------------------------------------------+
- | sophia | table | (see the | no | The default sophia configuration can be changed |
- | | | note) | | with |
- | | | | | |
- | | | | | .. code-block:: lua |
- | | | | | |
- | | | | | sophia = { |
- | | | | | page_size = number, |
- | | | | | threads = number, |
- | | | | | node_size = number, |
- | | | | | memory_limit = number |
- | | | | | } |
- | | | | | |
- | | | | | This method may change in the future. |
- +--------------------------+-----------+----------+----------+-------------------------------------------------+
-
- **Snapshot daemon**
-
- +--------------------+-----------+----------+----------+-----------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +====================+===========+==========+==========+=====================================================+
- | snapshot_period | integer | 0 | yes | The interval between actions by the snapshot |
- | | | | | daemon, in seconds. The snapshot daemon is a |
- | | | | | fiber which is constantly running. If |
- | | | | | ``snapshot_period`` is set to a value greater |
- | | | | | than zero, then the snapshot daemon will call |
- | | | | | :func:`box.snapshot` every ``snapshot_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. |
- +--------------------+-----------+----------+----------+-----------------------------------------------------+
- | snapshot_count | integer | 6 | yes | The maximum number of snapshots that the |
- | | | | | snapshot daemon maintains. 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. If ``snapshot_count`` equals zero, then the |
- | | | | | snapshot daemon does not remove old snapshots. |
- +--------------------+-----------+----------+----------+-----------------------------------------------------+
-
- **Snapshot daemon**
-
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +======================+===========+==========+==========+=====================================================+
- | panic_on_snap_error | boolean | true | no | If there is an error while reading the snapshot |
- | | | | | file (at server start), abort. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | panic_on_wal_error | boolean | true | no | If there is an error while reading a write-ahead |
- | | | | | log file (at server start or to relay to a replica),|
- | | | | | abort. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | rows_per_val | integer | 500000 | no | 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. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | snap_io_rate_limit | float | null | **yes** | Reduce the throttling effect of |
- | | | | | :func:`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 |
- | | | | | :ref:`snap_dir` locations and moving snapshots to a |
- | | | | | separate disk. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | wal_mode | string | "write" | **yes** | 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); |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | wal_dir_rescan_delay | float | 0.1 | no | 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. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
-
- **Replication**
-
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +======================+===========+==========+==========+=====================================================+
- | replication_source | string | null | **yes** | If replication_source is not an empty string, the |
- | | | | | server is considered to be a Tarantool replica. The |
- | | | | | replica server will try to connect to the master |
- | | | | | which replication_source specifies with a `URI`_ |
- | | | | | (Universal Resource Identifier), for example |
- | | | | | '``konstantin:secret_password@tarantool.org:3301``' |
- | | | | | The default user name is 'guest'. |
- | | | | | The replication_source parameter is dynamic, |
- | | | | | that is, to enter master mode, simply set |
- | | | | | replication_source to an empty string and issue |
- | | | | | "``box.cfg{replication_source=new-value}``" |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
-
- **Networking**
-
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +======================+===========+==========+==========+=====================================================+
- | io_collect_interval | float | null | **yes** | The server 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). |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | readahead | integer | 16320 | **yes** | 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. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
-
- **Logging**
-
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | Name | Type | Default | Dynamic? | Description |
- +======================+===========+==========+==========+=====================================================+
- | log_level | integer | true | **yes** | 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 "logger" configuration parameter. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | logger | string | "null" | no | By default, the log is sent to the standard error |
- | | | | | stream (``stderr``). If logger is specified, the |
- | | | | | log is sent to the file named in the string. |
- | | | | | Example setting: ``logger = 'tarantool.log'`` (this |
- | | | | | will open tarantool.log for output on the server's |
- | | | | | default directory). |
- | | | | | If logger string begins with a pipe, for example |
- | | | | | '| cronolog tarantool.log', the program specified in|
- | | | | | the option is executed at server start and all log |
- | | | | | When logging to a file, tarantool reopens the log |
- | | | | | on SIGHUP. When log is a program, it's pid is saved |
- | | | | | in logger_pid variable of package log. You need to |
- | | | | | send it a signal to rotate logs. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | logger_nonblock | boolean | true | no | 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, setting logger_nonblock to true may |
- | | | | | improve logging performance at the cost of some log |
- | | | | | messages getting lost. |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
- | too_long_threshold | float | 0.5 | **yes** | 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 less than or equal to |
- | | | | | 4 (WARNING). |
- +----------------------+-----------+----------+----------+-----------------------------------------------------+
-
-=====================================================================
- Local hot standby
-=====================================================================
-
-Local hot standby is a feature which provides a simple form of failover without
-replication. To initiate it, start a second instance of the Tarantool server on
-the same computer with the same :func:`box.cfg` configuration settings -
-including the same directories and same non-null URIs. A warning should appear with a
-message like
-
-.. code-block:: lua
-
- W> primary: [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.
-
-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. The standby instance
-will initialize and will try to connect on listen address,
-but will fail because the primary instance has already taken it. 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. Thus there is no noticeable
-downtime if the primary instance goes down.
-
-If this ``local_hot_standby`` feature is being used, then ``wal_mode`` should
-not be equal to "none".
diff --git a/doc/sphinx/book/configuration/cfg-basic.rst b/doc/sphinx/book/configuration/cfg-basic.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9e29c413dfad55ad2f90c7774257e2222c559765
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-basic.rst
@@ -0,0 +1,122 @@
+.. confval:: username
+
+ UNIX user name to switch to after start.
+
+ Type: string |br|
+ Default: null |br|
+ Dynamic: no |br|
+
+.. confval:: work_dir
+
+ A directory where database working files will be stored. The server
+ switches to work_dir with :manpage:`chdir(2)` after start. Can be
+ relative to the current directory. If not specified, defaults to
+ the current directory.
+
+ Type: string |br|
+ Default: null |br|
+ Dynamic: no |br|
+
+.. confval:: wal_dir
+
+ A directory where write-ahead log (.xlog) files are stored. Can be
+ relative to work_dir. Most commonly used so that snapshot files and
+ write-ahead log files can be stored on separate disks. If not
+ specified, defaults to work_dir.
+
+ Type: string |br|
+ Default: "." |br|
+ Dynamic: no |br|
+
+.. confval:: snap_dir
+
+ A directory where snapshot (.snap) files will be stored. Can be relative to
+ work_dir. If not specified, defaults to work_dir. See also :confval:`snap_dir`.
+
+ Type: string |br|
+ Default: "." |br|
+ Dynamic: no |br|
+
+.. confval:: sophia_dir
+
+ A directory where sophia files will be stored. Can be relative to
+ :confval:`work_dir`. If not specified, defaults to :file:`work_dir/sophia`.
+
+ Type: string |br|
+ Default: "sophia" |br|
+ Dynamic: no |br|
+
+.. confval:: coredump
+
+ Deprecated. Do not use.
+
+ Type: boolean |br|
+ Default: "false" |br|
+ Dynamic: no |br|
+
+.. confval:: listen
+
+ The read/write data port number or :ref:`URI` (Universal Resource Identifier)
+ string. Has no default value, so must be specified if connections will
+ occur from remote clients that do not use “admin address†(the
+ administrative host and port).
+
+ A typical value is 3301. The listen parameter may also be set for
+ :ref:`book-cfg-local_hot_standy`.
+
+ .. 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 string |br|
+ Default: "null" |br|
+ Dynamic: yes |br|
+
+.. confval:: pid_file
+
+ Store the process id in this file. Can be relative to :confval:`work_dir`.
+ A typical value is “:file:`tarantool.pid`â€.
+
+ Type: string |br|
+ Default: "null" |br|
+ Dynamic: no |br|
+
+.. confval:: custom_proc_title
+
+ Inject the given string into :ref:`process title <book-proctitle>`
+ (what’s shown in the COMMAND column for :samp:`ps` and :samp:`top` commands).
+
+ .. NOTE::
+
+ For example, ordinarily ps shows the Tarantool server process thus:
+
+ .. code-block:: lua
+
+ $ ps -ef | grep tarantool
+ 1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running
+ 1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner
+ tarantool: primary pri: 3301 adm: 3313
+
+ But if the configuration parameters include
+ ``custom_proc_title='sessions'`` then the output looks like:
+
+ .. code-block:: lua
+
+ $ ps -ef | grep tarantool
+ 1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running@sessions
+ 1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner@sessions
+ tarantool: primary pri: 3301 adm: 3313
+
+ Type: string |br|
+ Default: "null" |br|
+ Dynamic: no |br|
+
+.. confval:: background
+
+ Run the server as a background task. The :confval:`logger` and
+ :confval:`pid_file` parameters must be non-null for this to work.
+
+ Type: boolean |br|
+ Default: false |br|
+ Dynamic: no |br|
diff --git a/doc/sphinx/book/configuration/cfg-binary_logging_snapshots.rst b/doc/sphinx/book/configuration/cfg-binary_logging_snapshots.rst
new file mode 100644
index 0000000000000000000000000000000000000000..31d84f4dd9e2d623224a5bff83bd57d39811fc40
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-binary_logging_snapshots.rst
@@ -0,0 +1,64 @@
+.. confval:: panic_on_snap_error
+
+ If there is an error while reading the snapshot file
+ (at server start), abort.
+
+ Type: boolean |br|
+ Default: true |br|
+ Dynamic: no |br|
+
+.. confval:: panic_on_wal_error
+
+ If there is an error while reading a write-ahead log
+ file (at server start or to relay to a replica), abort.
+
+ Type: boolean |br|
+ Default: true |br|
+ Dynamic: no |br|
+
+.. confval:: rows_per_val
+
+ How many log records to store in a single write-ahead log file.
+ When this limit is reached, Tarantool creates another WAL file
+ named :samp:`{<first-lsn-in-wal>}.xlog` This can be useful for
+ simple rsync-based backups.
+
+ Type: integer |br|
+ Default: 500000 |br|
+ Dynamic: no |br|
+
+.. confval:: snap_io_rate_limit
+
+ Reduce the throttling effect of :func:`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 :confval:`wal_dir` and :confval:`snap_dir`
+ locations and moving snapshots to a separate disk.
+
+ Type: float |br|
+ Default: null |br|
+ Dynamic: **yes** |br|
+
+.. confval:: 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 :manpage:`fsync(2)`);
+ * fsync: fibers wait for their data, :manpage:`fsync(2)`
+ follows each :manpage:`write(2)`;
+
+ Type: string |br|
+ Default: "write" |br|
+ Dynamic: **yes** |br|
+
+.. confval:: 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: float |br|
+ Default: 0.1 |br|
+ Dynamic: no |br|
diff --git a/doc/sphinx/book/configuration/cfg-logging.rst b/doc/sphinx/book/configuration/cfg-logging.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b3caf57251c1062d4d240fb3c36acc15da052525
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-logging.rst
@@ -0,0 +1,73 @@
+.. confval:: 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 :confval:`logger`
+ configuration parameter.
+
+ Type: integer |br|
+ Default: 5 |br|
+ Dynamic: **yes** |br|
+
+.. confval:: logger
+
+ By default, the log is sent to the standard error stream (``stderr``). If
+ ``logger`` is specified, the log is sent to the file named in the string.
+ Example setting:
+
+ .. code-block:: lua
+
+ box.cfg{
+ logger = 'tarantool.log'
+ }
+
+ This will open :file:`tarantool.log` for output on the server’s default
+ directory. If ``logger`` string begins with a pipe, for example
+
+ .. code-block:: lua
+
+ box.cfg{
+ logger = '| cronolog tarantool.log'
+ }
+
+ the program specified in the option is executed at server start and all
+ log messages are send to the standart input.
+
+ When logging to a file, tarantool reopens the log on SIGHUP. When log is
+ a program, it’s pid is saved in :func:`log.logger_pid` variable. You need
+ to send it a signal to rotate logs.
+
+ Type: string |br|
+ Default: "null" |br|
+ Dynamic: no |br|
+
+.. confval:: 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 :confval:`log_level` is high, and a lot of messages go to the
+ log file, setting ``logger_nonblock`` to true may improve logging
+ performance at the cost of some log messages getting lost.
+
+ Type: boolean |br|
+ Default: true |br|
+ Dynamic: no |br|
+
+.. confval:: 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 :confval:`log_level` is
+ more than or equal to 4 (WARNING).
+
+ Type: float |br|
+ Default: 0.5 |br|
+ Dynamic: **yes** |br|
diff --git a/doc/sphinx/book/configuration/cfg-networking.rst b/doc/sphinx/book/configuration/cfg-networking.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a32971b2d5005f4e54f138e73d8b4b094a986b09
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-networking.rst
@@ -0,0 +1,25 @@
+.. confval:: io_collect_interval
+
+ The server 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: float |br|
+ Default: null |br|
+ Dynamic: **yes** |br|
+
+.. confval:: 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: integer |br|
+ Default: 16320 |br|
+ Dynamic: **yes** |br|
diff --git a/doc/sphinx/book/configuration/cfg-replication.rst b/doc/sphinx/book/configuration/cfg-replication.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3e9665e7520c26fc7ebdddbf2719910ada3170bd
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-replication.rst
@@ -0,0 +1,18 @@
+.. confval:: replication_source
+
+ If ``replication_source`` is not an empty string, the server is considered
+ to be a Tarantool replica. The replica server will try to connect to the
+ master which replication_source specifies with a :ref:`URI` (Universal
+ Resource Identifier), for example :samp:`{konstantin}:{secret_password}@{tarantool.org}:{3301}`.
+
+ The default user name is ‘guest’. The ``replication_source`` parameter is
+ dynamic, that is, to enter master mode, simply set ``replication_source``
+ to an empty string and issue
+
+ .. code-block:: lua
+
+ box.cfg{replication_source=new-value}
+
+ Type: string |br|
+ Default: null |br|
+ Dynamic: **yes** |br|
diff --git a/doc/sphinx/book/configuration/cfg-snapshot_daemon.rst b/doc/sphinx/book/configuration/cfg-snapshot_daemon.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f3dd10cf40f0b2bc7d7622ca84d841e91ef1690c
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-snapshot_daemon.rst
@@ -0,0 +1,42 @@
+.. confval:: snapshot_period
+
+ The interval between actions by the snapshot daemon, in seconds.
+ The snapshot daemon is a fiber which is constantly running.
+ If ``snapshot_period`` is set to a value greater than zero,
+ then the snapshot daemon will call :func:`box.snapshot` every
+ ``snapshot_period`` seconds, creating a new snapshot file each time.
+
+ For example:
+
+ .. code-block:: lua
+
+ box.cfg{snapshot_period=3600}
+
+ will cause the snapshot daemon to create a new database snapshot
+ once per hour.
+
+ Type: integer |br|
+ Default: 0 |br|
+ Dynamic: yes |br|
+
+.. confval:: snapshot_count
+
+ The maximum number of snapshots that the snapshot daemon maintains.
+ For example:
+
+ .. code-block:: lua
+
+ 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.
+ If ``snapshot_count`` equals zero, then the snapshot daemon does not remove
+ old snapshots.
+
+ Type: integer |br|
+ Default: 6 |br|
+ Dynamic: yes |br|
diff --git a/doc/sphinx/book/configuration/cfg-storage.rst b/doc/sphinx/book/configuration/cfg-storage.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9f17a879e47d9732e653835b086dfa27e541c6e3
--- /dev/null
+++ b/doc/sphinx/book/configuration/cfg-storage.rst
@@ -0,0 +1,60 @@
+.. confval:: 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 :ref:`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 |br|
+ Default: null |br|
+ Dynamic: no |br|
+
+.. confval:: slab_alloc_minimal
+
+ Size of the smallest allocation unit. It can be tuned down if most
+ of the tuples are very small
+
+ Type: integer |br|
+ Default: 64 |br|
+ Dynamic: no |br|
+
+.. confval:: slab_alloc_maximal
+
+ Size of the largest allocation unit. It can be tuned down up if it
+ is necessary to store large tuples.
+
+ Type: integer |br|
+ Default: 1048576 |br|
+ Dynamic: no |br|
+
+.. confval:: 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 |br|
+ Default: 2.0 |br|
+ Dynamic: no |br|
+
+.. confval:: sophia
+
+ The default sophia configuration can be changed with
+
+ .. code-block:: lua
+
+ sophia = {
+ page_size = number,
+ threads = number,
+ node_size = number,
+ memory_limit = number
+ }
+
+ This method may change in the future.
+
+ Type: table |br|
+ Default: (see the note) |br|
+ Dynamic: no |br|
diff --git a/doc/sphinx/book/configuration/index.rst b/doc/sphinx/book/configuration/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9f6840180620b7c7d8a8040bb778721052ebb3d6
--- /dev/null
+++ b/doc/sphinx/book/configuration/index.rst
@@ -0,0 +1,247 @@
+.. _book-cfg:
+
+-------------------------------------------------------------------------------
+ Configuration reference
+-------------------------------------------------------------------------------
+
+This chapter provides a reference of options which can be set on the command
+line or in an initialization file.
+
+Tarantool is started by entering the command:
+
+.. program:: tarantool
+
+.. code-block:: bash
+
+ $ tarantool
+ OR
+ $ tarantool <options>
+ OR
+ $ tarantool <lua-initialization-file> [arguments]
+
+=====================================================================
+ Command options
+=====================================================================
+
+.. option:: -h, --help
+
+ Print an annotated list of all available options and exit.
+
+.. option:: -V, --version
+
+ Print product name and version, for example:
+
+ .. code-block:: bash
+
+ $ ./tarantool --version
+ Tarantool 1.6.3-439-g7e1011b
+ 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`_.
+
+.. _git describe: http://www.kernel.org/pub/software/scm/git/docs/git-describe.html
+.. _git repository: http://github.com/tarantool/tarantool.git
+
+
+.. _URI:
+
+=====================================================================
+ 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 'localhost' is assumed.
+If username:password is omitted, then 'guest' is assumed. Some examples:
+
+.. _generic syntax for a URI schema: http://en.wikipedia.org/wiki/URI_scheme#Generic_syntax
+
+.. container:: table
+
+ +-----------------------------+------------------------------+
+ | 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 socket may be used where a URI is required.
+
+=====================================================================
+ 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
+
+.. code-block:: lua
+
+ #!/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:
+
+.. code-block:: lua
+
+ $ export LISTEN_URI=3301
+ $ ~/tarantool/src/tarantool script.lua ARG
+ ... main/101/script.lua C> version 1.6.3-439-g7e1011b
+ ... 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
+
+.. _local_hot_standby:
+.. _replication_port:
+.. _slab_alloc_arena:
+.. _replication_source:
+.. _admin_port:
+.. _snap_dir:
+.. _wal_dir:
+.. _wal_mode:
+.. _snapshot daemon:
+.. _logger:
+
+=====================================================================
+ 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 tables describe all parameters for basic operation, for storage,
+for binary logging and snapshots, for replication, for networking, and for logging.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Basic parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-basic.rst
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Configuring the storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-storage.rst
+
+.. _book-cfg-snapshot_daemon:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Snapshot daemon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-snapshot_daemon.rst
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Binary logging and snapshots
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-binary_logging_snapshots.rst
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Replication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-replication.rst
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Networking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-networking.rst
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Logging
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: cfg-logging.rst
+
+.. _book-cfg-local_hot_standy:
+
+=====================================================================
+ Local hot standby
+=====================================================================
+
+Local hot standby is a feature which provides a simple form of failover without
+replication. To initiate it, start a second instance of the Tarantool server on
+the same computer with the same :func:`box.cfg` configuration settings -
+including the same directories and same non-null URIs. A warning should appear with a
+message like
+
+.. code-block:: lua
+
+ W> primary: [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.
+
+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. The standby instance
+will initialize and will try to connect on listen address,
+but will fail because the primary instance has already taken it. 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. Thus there is no noticeable
+downtime if the primary instance goes down.
+
+If this ``local_hot_standby`` feature is being used, then ``wal_mode`` should
+not be equal to "none".
diff --git a/doc/sphinx/book/index.rst b/doc/sphinx/book/index.rst
index 486206078922fccafb8824c449a57181f5d3735a..c28333014256270782dc387f4dab056fbdba2873 100644
--- a/doc/sphinx/book/index.rst
+++ b/doc/sphinx/book/index.rst
@@ -10,7 +10,7 @@
intro
box/index
replication/index
- configuration
+ configuration/index
administration
connectors/index
app_a_errcodes
diff --git a/doc/sphinx/book/replication/index.rst b/doc/sphinx/book/replication/index.rst
index 687223576a7e8042b0fc66a9fd62c5328c61ecc0..05ed77f15668937d408dceea4cda7cf2b079c8bd 100644
--- a/doc/sphinx/book/replication/index.rst
+++ b/doc/sphinx/book/replication/index.rst
@@ -47,12 +47,12 @@ has its own replication state.
A server requires a valid snapshot (.snap) file. A snapshot file is created
for a server the first time that ``box.cfg`` occurs for it. If this first
-``box.cfg`` request occurs without a "replication_source" clause, then the
+``box.cfg`` request occurs without a ":confval:`replication_source`" clause, then the
server is a master and starts its own new cluster with a new unique UUID.
-If this first ``box.cfg`` request occurs with a "replication_source" clause,
+If this first ``box.cfg`` request occurs with a ":confval:`replication_source`" clause,
then the server is a replica and its snapshot file, along with the cluster
information, is constructed from the write-ahead logs of the master.
-Therefore, to start replication, specify :ref:`replication_source <replication_source>`
+Therefore, to start replication, specify :confval:`replication_source`
in a ``box.cfg`` request. When a replica contacts a master for the first time,
it becomes part of a cluster. On subsequent occasions, it should always contact
a master in the same cluster.
@@ -73,8 +73,8 @@ Again, this procedure works only if the master's WAL files are present.
.. NOTE::
The replica does not inherit the master's configuration parameters, such
- as the ones that cause the :ref:`snapshot daemon` to run on the master. To get
- the same behavior, one would have to set the relevant parameters explicitly
+ as the ones that cause the :ref:`book-cfg-snapshot_daemon` to run on the master.
+ To get the same behavior, one would have to set the relevant parameters explicitly
so that they are the same on both master and replica.
=====================================================================
@@ -110,8 +110,7 @@ Step 1. Start the first server thus:
... Now a new cluster exists.
Step 2. Check where the second server's files will go by looking at its
-directories (:ref:`snap_dir <snap_dir>` for snapshot files,
-:ref:`wal_dir <wal_dir>` for .xlog files).
+directories (:confval:`snap_dir` for snapshot files, :confval:`wal_dir` for .xlog files).
They must be empty - when the second server joins for the first time, it
has to be working with a clean slate so that the initial copy of the first
server's databases can happen without conflicts.
@@ -161,7 +160,7 @@ servers will end up with different contents.
=====================================================================
:Q: What if there are more than two servers with master-master?
-:A: On each server, specify the replication_source for all the others. For
+:A: On each server, specify the :confval:`replication_source` for all the others. For
example, server #3 would have a request:
``box.cfg{replication_source=uri#1, replication_source=uri#2}``.
@@ -199,7 +198,7 @@ servers will end up with different contents.
:Q: What if replication causes security concerns?
:A: Prevent unauthorized replication sources by associating a password with
every user that has access privileges for the relevant spaces. That way,
- the :ref:`URI` for the replication_source parameter will always have to have
+ the :ref:`URI` for the :confval:`replication_source` parameter will always have to have
the long form ``replication_source='username:password@host:port'``.
.. _vector clock: https://en.wikipedia.org/wiki/Vector_clock
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index cfa19f5aa927f203c552e022e4cdd8f10e85af25..329dbeab5fc8d78a13694b73e5538f96ab388e91 100644
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -30,6 +30,7 @@ exclude_patterns = [
'book/connectors/__*',
'book/replication/*-1.rst',
'book/replication/*-2.rst',
+ 'book/configuration/cfg-*'
]
pygments_style = 'sphinx'
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 6b2496e82b4a8d5fc21c22c3b681581a8ed97bf2..ee4916409d2642e2300d361248bf98fcdfc1355c 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -1,18 +1,4 @@
-:orphan:
-
--------------------------------------------------------------------------------
- Documentation
--------------------------------------------------------------------------------
-
-.. toctree::
- :maxdepth: 2
-
- intro.rst
- faq.rst
- getting_started
- book/index.rst
- reference/index.rst
- dev_guide/index.rst
+.. include:: singlehtml.rst
.. NOTE::
diff --git a/doc/sphinx/reference/log.rst b/doc/sphinx/reference/log.rst
index 1a6ae2a419b425c951af574b96a0e3ea3568f303..6ce6e77b95ee57ec80d9f87f2a4c6b924871c047 100644
--- a/doc/sphinx/reference/log.rst
+++ b/doc/sphinx/reference/log.rst
@@ -5,7 +5,7 @@
.. module:: log
The Tarantool server puts all diagnostic messages in a log file specified by
-the :ref:`logger <logger>` configuration parameter. Diagnostic messages may be either
+the :confval:`logger` configuration parameter. Diagnostic messages may be either
system-generated by the server's internal code, or user-generated with the
``log.log_level_function_name`` function.
diff --git a/doc/sphinx/singlehtml.rst b/doc/sphinx/singlehtml.rst
index 47022972925880e4754cc5db5a9a5cc2bb329075..29f3bb7070a8d3a9caa2b270a08d79ecaf9638e4 100644
--- a/doc/sphinx/singlehtml.rst
+++ b/doc/sphinx/singlehtml.rst
@@ -5,7 +5,7 @@
-------------------------------------------------------------------------------
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
intro.rst
faq.rst
diff --git a/doc/www/theme/static/design.css b/doc/www/theme/static/design.css
index 2365517ffad4cf7463166e605d2735b342978fd3..bd3dd1d5b280433b60cd614825425105814fcd13 100644
--- a/doc/www/theme/static/design.css
+++ b/doc/www/theme/static/design.css
@@ -882,7 +882,10 @@ input.b-button.p-smaller {
transform:rotate(360deg);
}
}
-.b-documentation_top .b-block-wrapper,
+.b-documentation_top .b-block-wrapper {
+ padding:20px 0 21px 0;
+}
+
.b-benchmark_top .b-block-wrapper {
/* padding:20px 0 21px 0;*/
padding:35px 0 35px 0;
@@ -915,8 +918,7 @@ input.b-button.p-smaller {
padding-left:19px;
}
.b-documentation_top .b-section-title {
-/* margin:0 0 17px 0;*/
- margin:0;
+ margin:0 0 17px 0;
}
.b-tcontents-list,
.b-tcontents-sublist {