From bb87d7b1f16528ba2c00294e66630c86e6ce4c59 Mon Sep 17 00:00:00 2001
From: Konstantin Osipov <kostja@tarantool.org>
Date: Wed, 15 May 2013 18:54:10 +0400
Subject: [PATCH] Remove various deficiencies of the manual.

Document bind_ipaddr (lp:bug#1032240).
Separate triggers into an own section.
Clarify that the network now is fully asynchronous.
Clarify how atomicity works in stored procedures.
Provide an overview of possible operations in the data model.
Add a stub for system-specific installation notes.
Fix all references to be stable between builds of the
manual, so that an external link to, say, memcached-protocol
stays valid over time.
---
 doc/user/CMakeLists.txt               |  2 +-
 doc/user/configuration-reference.xml  | 21 +++++---
 doc/user/connectors.xml               | 12 ++---
 doc/user/data-model.xml               | 73 +++++++++++++++++++------
 doc/user/language-reference.xml       | 48 ++++++++++-------
 doc/user/os-install-notes.xml         | 56 +++++++++++++++++++
 doc/user/persistence-architecture.xml | 45 +++++++++++-----
 doc/user/preface.xml                  | 10 ++--
 doc/user/replication.xml              |  8 +--
 doc/user/stored-procedures.xml        | 77 ++++++++++++++-------------
 doc/user/target.db                    |  4 +-
 doc/user/triggers.xml                 | 72 +++++++++++++++++++++++++
 doc/user/tutorial.xml                 | 34 +++++++++---
 doc/user/user.xml                     |  1 +
 14 files changed, 344 insertions(+), 119 deletions(-)
 create mode 100644 doc/user/os-install-notes.xml
 create mode 100644 doc/user/triggers.xml

diff --git a/doc/user/CMakeLists.txt b/doc/user/CMakeLists.txt
index 34d1a421ad..8da9b17ff1 100644
--- a/doc/user/CMakeLists.txt
+++ b/doc/user/CMakeLists.txt
@@ -64,7 +64,7 @@ add_custom_target(pdf
 
 add_custom_target(relink
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-    COMMAND ${XSLTPROC} --nonet
+    COMMAND ${XSLTPROC}
         --stringparam collect.xref.targets "only"
         --xinclude tnt-html.xsl user.xml)
 
diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml
index 7d0a9b05d5..02f1e096b0 100644
--- a/doc/user/configuration-reference.xml
+++ b/doc/user/configuration-reference.xml
@@ -25,7 +25,7 @@ the command line, or from the configuration file, but never from
 both.
 </para>
 
-<section>
+<section xml:id="command-line-options">
 <title>Command line options</title>
   <para>
     Tarantool follows the <citetitle
@@ -301,6 +301,17 @@ lsn:4 tm:1301572313.691 t:65534 127.0.0.1:52728 UPDATE_FIELDS n:0flags:00000000
           turn off the coredump off when using ulimit</entry>
         </row>
 -->
+        <row>
+          <entry xml:id="bind_ipaddr" xreflabel="bind_ipaddr">bind_ipaddr</entry>
+          <entry>string</entry>
+          <entry><emphasis role="strong">"INADDR_ANY"</emphasis></entry>
+          <entry>no</entry>
+          <entry>no</entry>
+          <entry>The network interface to bind to. By default,
+          the server binds to all available addresses.
+          Applies to all ports opened by the server.
+          </entry>
+        </row>
         <row>
           <entry xml:id="primary_port" xreflabel="primary_port">primary_port</entry>
           <entry>integer</entry>
@@ -828,12 +839,8 @@ tarantool_box: primary@sessions pri:33013 sec:33014 adm:33015</programlisting>
             xreflabel="memcached_expire"/>
             Turn on tuple time-to-live support in
             <olink targetptr="memcached_space"/>. This
-            effectively turns Tarantool into a "persistent" implementation
-            of Memcached. Since a caching server has
-            significantly different purpose than a data server, in
-            this mode Tarantool turns off replication and does not
-            bind to <olink targetptr="primary_port"/> or <olink
-            targetptr="secondary_port"/>.
+            effectively turns Tarantool into a persistent,
+            replicated and scriptable implementation of Memcached.
           </entry>
         </row>
 
diff --git a/doc/user/connectors.xml b/doc/user/connectors.xml
index 8c333b5595..646d6539a2 100644
--- a/doc/user/connectors.xml
+++ b/doc/user/connectors.xml
@@ -14,7 +14,7 @@
 
 <para>Apart from the native Tarantool client driver, you can always use a <emphasis role="strong">Memcached</emphasis> driver of your choice, after enabling Memcached protocol in the configuration file.</para>
 
-  <section>
+  <section xml:id="connector-c">
     <title>C</title>
     <para>
        Please see <link
@@ -22,21 +22,21 @@
     </para>
   </section>
 
-  <section>
+  <section xml:id="connector-node.js">
     <title>node.js</title>
     <para>
        <link xlink:href="https://github.com/devgru/node-tarantool"><filename>http://github.com/devgru/node-tarantool</filename></link>.
     </para>
   </section>
 
-  <section>
+  <section xml:id="connector-perl">
     <title>Perl</title>
     <para>
        Please refer to CPAN module <link xlink:href='http://search.cpan.org/~unera/DR-Tarantool/'>DR::Tarantool</link>.
     </para>
   </section>
 
-  <section>
+  <section xml:id="connector-php">
     <title>PHP</title>
     <para>
        Please see <link
@@ -44,7 +44,7 @@
     </para>
   </section>
 
-  <section>
+  <section xml:id="connector-python">
     <title>Python</title>
     <para>
        Please see <link
@@ -52,7 +52,7 @@
     </para>
   </section>
 
-  <section>
+  <section xml:id="connector-ruby">
     <title>Ruby</title>
     <para>
        You need <emphasis role="strong">Ruby 1.9</emphasis> or later
diff --git a/doc/user/data-model.xml b/doc/user/data-model.xml
index f6e6f590ae..aeaec44e97 100644
--- a/doc/user/data-model.xml
+++ b/doc/user/data-model.xml
@@ -3,26 +3,67 @@
 %tnt;
 ]>
 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
-         xmlns:xlink="http://www.w3.org/1999/xlink">
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="dynamic-data-model">
 <title>Dynamic data model</title>
 <para>
   Tarantool data is organized in <emphasis>tuples</emphasis>. Tuple
   length is varying: a tuple can contain any number
   of fields. A field can be either numeric &mdash;
   32- or 64- bit unsigned integer, or binary
-  string &mdash; a sequence of octets.  Fields included into the
-  first index are always assumed to be the identifying (unique)
-  key. The remaining fields make up a value, associated with the
-  key.
-  Tuple sets are called <emphasis>spaces<alt>perhaps, not the best name</alt></emphasis>, and there can be up to 255 spaces defined per
-  one Tarantool instance.
+  string &mdash; a sequence of octets.
+  Tuples are stored and retrieved by means of indexing. An index
+  can cover one or multiple fields, in any order. Fields included
+  into the first index are always assumed to be the identifying
+  (unique) key. The remaining fields make up a value, associated
+  with the key. 
 
   Apart from the primary key, it is possible to define secondary
-  <emphasis>indexes</emphasis> on other tuple fields. A secondary index does
-  not have to be unique, and can cover several fields.
-  If a space has a secondary index, the total number of fields in
-  a tuple must be at least equal to the ordinal number of the
-  field participating in the index.
+  <emphasis>indexes</emphasis> on other tuple fields.
+
+  Tuple sets together with defined indexes form
+  <emphasis>spaces<alt>the paradigm of tuples and spaces is
+  derived from distributed computing</alt></emphasis>.
+
+  A secondary index does not have to be unique, and can cover
+  multiple fields. The total number of fields in a tuple must be
+  at least equal to the ordinal number of the last field
+  participating in any index.
+</para>
+<para>
+  Supported index types are HASH, TREE and BITSET. HASH
+  index is the fastest one, with smallest memory footprint.
+  TREE index, in addition to key/value look ups, support partial
+  key lookups, key-part lookups for multipart keys and ordered
+  retrieval. BITSET indexes, while can serve as a standard unique
+  key, are best suited for bit-pattern look-ups, e.g. search for
+  objects satisfying multiple properties.
+</para>
+<para>
+  The basic server operations include insert, replace, delete,
+  update and select. All operations that modify data require
+  the primary key for look up. Select, however, may use any index.
+  A Lua stored procedure can combine multiple trivial commands,
+  as well as access data using index iterators. Indeed,
+  the iterators provide full access to the power of indexes,
+  enabling index-type specific access, such as boolean expression
+  evaluation for BITMAP indexes, or reverse range retrieval for
+  TREEs.
+</para>
+<para>
+  All operations in Tarantool are atomic and durable: they are
+  either executed and written to the write ahead log, or rolled back.
+  A stored procedure, containing a combination of basic operations,
+  holds a consistent view of the database as long as it doesn't 
+  incur writes to the write ahead log or to network. In particular,
+  a select followed by an update or delete is atomic. 
+</para>
+<para>
+  While the subject of each data changing command is a
+  single tuple, an update may modify one or more tuple fields, as
+  well as add or delete fields, all in one command. It thus
+  provides an alternative way to achieve multi-operation
+  atomicity.
 </para>
 <para>
   Currently, entire server <emphasis>schema</emphasis> must be
@@ -31,8 +72,8 @@
   file that doesn't match contents of its data directory will most
   likely crash, but may also behave in a non-defined way. 
   It is, however, possible to stop the server,
-  add new spaces to the schema or temporarily disable
-  existing spaces, and then restart the server.
+  add new spaces and indexes to the schema or temporarily disable
+  existing spaces and indexes, and then restart the server.
 </para>
 <para>
   Schema objects, such as spaces and indexes, are referred to
@@ -47,8 +88,8 @@
   only one space with id <literal>0</literal>. It has no keys
   other than the primary. The primary key numeric id is also 
   <literal>0</literal>. Tarantool command line client
-  supports a small subset of SQL, and we'll use it to demonstrate
-  supported data manipulation commands:
+  supports a small subset of SQL, and it'll be used it to
+  demonstrate supported data manipulation commands:
   <programlisting>
   localhost> insert into t0 values (1)
   Insert OK, 1 row affected
diff --git a/doc/user/language-reference.xml b/doc/user/language-reference.xml
index 2a6c903bd1..c747a0f117 100644
--- a/doc/user/language-reference.xml
+++ b/doc/user/language-reference.xml
@@ -17,12 +17,12 @@
   Unlike many other key/value servers, Tarantool uses
   different TCP ports and client/server protocols for data
   manipulation and administrative statements.
-  On start up, the server can connect to up to five TCP ports:
+  During start up, the server can connect to up to five TCP ports:
   <itemizedlist>
     <listitem><para>
       Read/write data port, to handle INSERTs, UPDATEs,
-      DELETEs, SELECTs and CALLs. This port speaks the native
-      Tarantool protocol, and provides full access to the server.
+      DELETEs, SELECTs and CALLs. This port speaks the 
+      <link xlink:href="https://github.com/mailru/tarantool/blob/master/doc/box-protocol.txt" xlink:title="A complete BNF of Tarantool client/server protocol">native Tarantool protocol</link>, and provides full access to the server.
       </para>
       <para>
       The default value of the port is <literal>33013</literal>,
@@ -60,7 +60,7 @@
   SHOW, RELOAD, SAVE and other statements are sent to the administrative port.
 </para>
 
-<section>
+<section xml:id="data-manipulation">
   <title>Data manipulation</title>
 
   <para>Tarantool protocol was designed with focus on asynchronous
@@ -72,17 +72,18 @@
     Five basic request types are supported: INSERT, UPDATE,
     DELETE, SELECT and CALL. The mandatory length, present in the
     header, allows simplifying client or proxy I/O.
-    The server response to a request always carries in its header
-    the same request type and id.
-    The id makes it possible to always match a request to a
-    response, even if the latter arrived out of order.
+    A response to a request is sent to the client as soon as it is
+    ready. It always carries in its header the same type
+    and id as in the request. The id makes it possible to
+    match a request to a response, even if the latter arrived out
+    of order.
   </para>
   <para>Request type defines the format of the payload.
     INSERTs, UPDATEs and DELETEs can only be made by the primary key, so
-    an index id and key value are always present in these requests.
-    SELECTs can use secondary keys. UPDATE only needs to
-    list the fields that are actually changed. With this one
-    exception, all commands operate on whole tuple(s).
+    an index id and a key (possibly multipart) are always present
+    in these requests. SELECTs can use secondary keys. UPDATE
+    only needs to list the fields that are actually changed. With
+    this one exception, all commands operate on whole tuple(s).
   </para>
   <para>Unless implementing a client driver, one needn't
     concern oneself with the complications of the binary
@@ -97,7 +98,7 @@
     and
     <link xlink:href="https://github.com/mailru/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link> respectively.
   </para>
-  <section>
+  <section xml:id="memcached-protocol">
     <title>Memcached protocol</title>
       <para>If full access to Tarantool functionality is not needed,
       or there is no readily available connector for the
@@ -111,15 +112,22 @@
       targetptr="memcached_space"/>) via its primary key.
       Unless tuple expiration is enabled with <olink
       targetptr="memcached_expire"/>, TTL part of the message is
-      stored but ignored. Note, that we do not support the binary
+      stored but ignored. Note, that Tarantool does not support the binary
       protocol of Memcached. If top performance
       is a must, Tarantool's own binary protocol should be
       used.
-  </para>
+     </para>
+     <para>
+       Notice, that <olink targetptr="memcached_space"/> is also
+       accessible using the primary port or Lua. A common use
+       of the memcached API in Tarantool is when a Memcached default
+       expiration algorithm is insufficient, and a custom expiration
+       procedure is scripted in Lua.
+     </para>
   </section>
 </section>
 
-<section>
+<section xml:id="administrative-console">
   <title>Administrative console</title>
   <para>
     The administrative console uses a simple text protocol.
@@ -157,7 +165,7 @@
         consistent snapshot of all tuples in the child process,
         which is then written to disk tuple by tuple. Since a
         snapshot is written sequentially, you can expect a very
-        high write performance (averaging to 70MB/second on modern
+        high write performance (averaging to 80MB/second on modern
         disks), which means an average database instance gets
         saved in a matter of minutes.  Note, that as long as there
         are any changes to the parent memory through concurrent
@@ -258,8 +266,9 @@ info:
         <emphasis role="tntadmin">show stat</emphasis>
       </term>
       <listitem><para>
-      Show the average number of requests per second, and the total number of requests since startup,
-      broken down by request type: INSERT or SELECT or UPDATE or DELETE."
+      Show the average number of requests per second, and the
+      total number of requests since startup, broken down by
+      request type: INSERT or SELECT or UPDATE or DELETE."
 <programlisting>
 localhost> show stat
 ---
@@ -347,6 +356,7 @@ statistics:
 </section>
 
 <xi:include href="stored-procedures.xml" />
+<xi:include href="triggers.xml" />
 
 </chapter>
 
diff --git a/doc/user/os-install-notes.xml b/doc/user/os-install-notes.xml
new file mode 100644
index 0000000000..35d62c15d7
--- /dev/null
+++ b/doc/user/os-install-notes.xml
@@ -0,0 +1,56 @@
+<!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="os-install-notes">
+
+<title>System-specific installation 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>
+
+</chapter>
+
+<!--
+vim: tw=66 syntax=docbk
+vim: spell spelllang=en_us
+-->
diff --git a/doc/user/persistence-architecture.xml b/doc/user/persistence-architecture.xml
index 70b1cfcf09..c69b7b37f9 100644
--- a/doc/user/persistence-architecture.xml
+++ b/doc/user/persistence-architecture.xml
@@ -3,7 +3,8 @@
 %tnt;
 ]>
 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
-         xmlns:xlink="http://www.w3.org/1999/xlink">
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="data-persistence">
 <title>Data persistence</title>
 <para>
 To maintain data persistence, Tarantool writes each data change
@@ -11,7 +12,8 @@ request (INSERT, UPDATE, DELETE) into a write-ahead log. WAL
 files have extension <filename>.xlog</filename> and are stored in <olink
 targetptr="wal_dir"/>. A new WAL file is created for every <olink
 targetptr="rows_per_wal"/> records.  Each INSERT, UPDATE or DELETE
-gets assigned a continuously growing 64-bit log sequence number. The name of the log file is based on the log sequence
+gets assigned a continuously growing 64-bit log sequence number.
+The name of the log file is based on the log sequence
 number of the first record this file contains.
 </para>
 
@@ -40,8 +42,8 @@ example:
     match the type of the index, the change is aborted.
     </para></listitem>
     <listitem><para>
-    The new tuple is marked 'invisible' and is added to
-    the primary and secondary indexes.
+    The new tuple replaces the old tuple in all
+    existing indexes.
     </para></listitem>
     <listitem><para>
     A message is sent to <quote>wal_writer</quote>, running in a
@@ -50,21 +52,36 @@ example:
     until an acknowledgment from the WAL writer.
     </para></listitem>
     <listitem><para>
-    Upon success, the 'invisible' flag is cleared
-    and the original tuple is deleted. A response is sent to the
-    client. Upon failure, the new tuple is removed and <olink
-    targetptr="ER_WAL_IO"/> error is sent to the client.
+    Upon success, a confirmation is sent to the client that
+    a REPLACE has succeeded.
+    Upon failure, a rollback procedure is begun.
+    During the rollback procedure, all changes to the database
+    which occurred after the failed change are rolled back in reverse
+    order. No new change is applied while rollback is in progress.
+    When the rollback procedure is finished, 
+    <olink targetptr="ER_WAL_IO"/> error is sent to the client.
     </para></listitem>
 </orderedlist>
 </para>
 
 <para>
-The master and the WAL writer threads communicate using asynchronous (yet reliable)
-messaging; the master thread, not being blocked on
-WAL tasks, continues to handle requests quickly
-even at hight volumes of disk I/O. For instance, SELECT performance,
-provided SELECTs are run in their own connections, remains
-unaffected by disk load.
+One advantage of the described algorithm is that complete request
+pipelining is achieved, even for requests on the same primary key.
+In Tarantool, unlike in most database systems, database performance
+doesn't degrade even if all requests touch upon the same key in the
+same space.
+</para>
+
+<para>
+The master and the WAL writer threads communicate using
+asynchronous (yet reliable) messaging; the master thread, not
+being blocked on WAL tasks, continues to handle requests quickly
+even at high volumes of disk I/O. A response to a request
+is sent as soon as it is ready, even if there were earlier
+requests on the same connection which have not completed yet.
+For instance, SELECT performance, even for SELECTs running 
+on the same connection as UPDATEs and DELETEs, remains unaffected
+by disk load.
 </para>
 
 <para>
diff --git a/doc/user/preface.xml b/doc/user/preface.xml
index c20edb99bc..2877672380 100644
--- a/doc/user/preface.xml
+++ b/doc/user/preface.xml
@@ -3,9 +3,9 @@
 %tnt;
 ]>
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
-         xmlns:xlink="http://www.w3.org/1999/xlink">
+         xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="preface">
 <title>Preface</title>
-<section xml:id="preface">
+<section xml:id="tarantool-overview">
   <title>Tarantool: an overview</title>
   <para>
     <productname>Tarantool</productname> is an in-memory NoSQL
@@ -119,7 +119,7 @@
   </para>
 
 </section>
-<section>
+<section xml:id="manual-conventions">
   <title>Conventions</title>
   <para>
     This manual is written in <citetitle
@@ -154,14 +154,14 @@
 
   </para>
 </section>
-<section>
+<section xml:id="reporting-bugs">
   <title>Reporting bugs</title>
   <para>
     Please report bugs in Tarantool at <link
     xlink:href="http://bugs.launchpad.net/tarantool"/>. You can
     contact developers directly on
     <link xlink:href="irc://irc.freenode.net#tarantool">#tarantool</link>
-    IRC channel or via mailing list,
+    IRC channel or via a mailing list,
     <link xlink:href="https://launchpad.net/~tarantool-developers">tarantool-developers@lists.launchpad.net</link>.
   </para>
   <para>
diff --git a/doc/user/replication.xml b/doc/user/replication.xml
index 8d68f0aba8..632fe9df9e 100644
--- a/doc/user/replication.xml
+++ b/doc/user/replication.xml
@@ -13,7 +13,7 @@
   a degraded state.
 </para></blockquote>
 
-<section>
+<section xml:id="replication-architecture">
     <title>Replication architecture</title>
   <para>
     A replica gets all updates from the master by continuously
@@ -55,7 +55,7 @@
   </para>
 </section>
 
-<section>
+<section xml:id="setting-up-the-master">
   <title>Setting up the master</title>
   <para>
     To prepare the master for connections from replica, it's only
@@ -67,7 +67,7 @@
     has its own replication state.
   </para>
 </section>
-<section>
+<section xml:id="settin-up-a-replica">
   <title>Setting up a replica</title>
   <para>
     The server, master or replica, always requires a valid
@@ -102,7 +102,7 @@
   </simpara></note>
 
 </section>
-<section>
+<section xml:id="recovering-from-a-degraded-state">
   <title>Recovering from a degraded state</title>
   <para>
     "Degraded state" is a situation when the master becomes
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index 280b64a544..dc7718e64b 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -16,7 +16,9 @@
         server-side procedure written in Lua can select and modify
         data, access configuration and perform administrative
         tasks. It is possible to dynamically define, invoke,
-        alter and drop Lua procedures.
+        alter and drop Lua procedures. Lua procedures can run
+        in the background and perform administrative tasks,
+        such as data expiration and re-sharding.
 
     </para>
     <para>
@@ -105,7 +107,22 @@ expirationd.run_task("exprd space 0", 0, is_expired, purge,
                     { field_no = 1, ttl = 30 * 60 })
 ]]>
     </programlisting>
+ </para>
+ <para>
+    The initialization script can select and modify data. However,
+    if the server is a running replica, data change requests from
+    the start script fail just the same way they would fail if
+    were sent from a remote client.
   </para>
+ <para>
+   Another common task to perform in the initialization script
+   is to start background fibers for data expiration, re-sharding,
+   or communication with networked peers.
+ </para>
+ <para>
+   Finally, the script can be used to define Lua triggers run
+   on various events within the system.
+ </para>
 
   <para>
     There is a single global instance of the Lua interpreter, which is
@@ -122,12 +139,11 @@ expirationd.run_task("exprd space 0", 0, is_expired, purge,
     &mdash; set of local variables and definitions.
   </para>
   <para>
-    The interpreter environment is not restricted when
+     The interpreter environment is not restricted when
      <olink targetptr="init.lua"/> is loaded. But before the
      server starts accepting requests, the standard Lua APIs, such
      as for file I/O, process control and module management are
-     unset, to avoid possible trivial security attacks, and
-     Tarantool-specific libraries are loaded.
+     unset, to avoid possible trivial security attacks.
   </para>
   <para>
     In the binary protocol, it's only possible to <emphasis
@@ -187,6 +203,10 @@ Call OK, 2 rows affected
 localhost> call box.space[0]:truncate()
 error: 1:15 expected '('
 </computeroutput></programlisting>
+    Since it's impossible to invoke object methods from the binary
+    protocol, the object-oriented syntax is often used on purpose,
+    to restrict certain operations to be used by a system
+    administrator only.
   </para>
   <para>
     Every value, returned from a stored function by means of
@@ -340,6 +360,16 @@ localhost> lua type(i), type(i*2),  type(i/2), i, i*2, i/2
                 Any server error produced by the executed
                 command.
             </para>
+            <para>
+                Please note, that since all requests from Lua
+                enter the core through <emphasis
+                role="lua">box.process()</emphasis>, all checks
+                and triggers run by the core automatically apply.
+                For example, if the server is in read-only mode,
+                an update or delete fails. Analogously, if a
+                system-wide "instead of" trigger is defined, it
+                is run.
+            </para>
         </listitem>
     </varlistentry>
 
@@ -1091,7 +1121,7 @@ localhost> lua t:find(1, 'abc')
     <varlistentry>
         <term><emphasis role="lua">box.tuple.new(...)</emphasis></term>
         <listitem><para>
-        Construct a new tuple from a Lua table or a scalar. 
+        Construct a new tuple from a Lua table or a scalar.
         </para>
             <bridgehead renderas="sect4">Example</bridgehead>
             <programlisting>localhost> lua box.tuple.new({tonumber64('18446744073709551615'), 'string', 1})
@@ -1669,39 +1699,12 @@ event.
         <listitem><simpara>Return true if a session is alive,
         false otherwise.</simpara></listitem>
     </varlistentry>
-
-    <varlistentry>
-        <term>
-            <emphasis role="lua">box.session.on_connect(chunk) </emphasis>
-        </term>
-        <listitem><para>
-		Set a callback (trigger) invoked on each connected session.
-        The callback doesn't get any arguments, but is the first
-        thing invoked in the scope of the newly created session.
-        If the trigger fails by raising an error, the error
-        is sent to the client and the connection is shut down.
-        Returns the old value of the trigger.
-        </para>
-        <warning>
-        <para>
-        If a trigger always results in an error, it may become
-        impossible to connect to the server to reset it.
-        </para>
-        </warning>
-        </listitem>
-    </varlistentry>
-
-    <varlistentry>
-        <term>
-            <emphasis role="lua">box.session.on_disconnect(chunk)</emphasis>
-        </term>
-        <listitem><simpara>Set a trigger invoked after a client has
-        disconnected. Returns the old value of the trigger. If
-        the trigger raises an error, the error is logged but otherwise
-        is ignored.
-        </simpara></listitem>
-    </varlistentry>
 </variablelist>
+    <para>
+This module also makes it possible to define triggers on connect
+and disconnect events. Please see <olink targetptr="sp-box-session-triggers">
+the triggers chapter</olink> for details.
+    </para>
 </section>
 
 <!--   end of lib -->
diff --git a/doc/user/target.db b/doc/user/target.db
index f7dd73319c..8f0bfdff9f 100644
--- a/doc/user/target.db
+++ b/doc/user/target.db
@@ -1,5 +1,5 @@
-<div element="book" href="#tarantool-user-guide" number="" targetptr="tarantool-user-guide"><ttl>Tarantool/Box User Guide, version 1.4.8-182-g92e107a</ttl><xreftext>Tarantool/Box User Guide, version 1.4.8-182-g92e107a</xreftext><div element="chapter" href="#idp90592" number="1"><ttl>Preface</ttl><xreftext>Chapter 1, <i>Preface</i></xreftext><div element="section" href="#preface" number="" targetptr="preface"><ttl>Tarantool/Box: an overview</ttl><xreftext>the section called “Tarantool/Box: an overview”</xreftext></div><div element="section" href="#idp199984" number=""><ttl>Conventions</ttl><xreftext>the section called “Conventions”</xreftext></div><div element="section" href="#idp208880" number=""><ttl>Reporting bugs</ttl><xreftext>the section called “Reporting bugs”</xreftext></div></div><div element="chapter" href="#idp229824" number="2"><ttl>Getting started</ttl><xreftext>Chapter 2, <i>Getting started</i></xreftext></div><div element="chapter" href="#data-and-persistence" number="3" targetptr="data-and-persistence"><ttl>Data model and data persistence</ttl><xreftext>Chapter 3, <i>Data model and data persistence</i></xreftext><div element="section" href="#idp294864" number=""><ttl>Dynamic data model</ttl><xreftext>the section called “Dynamic data model”</xreftext></div><div element="section" href="#idp407472" number=""><ttl>Data persistence</ttl><xreftext>the section called “Data persistence”</xreftext></div></div><div element="chapter" href="#language-reference" number="4" targetptr="language-reference"><ttl>Language reference</ttl><xreftext>Chapter 4, <i>Language reference</i></xreftext><div element="section" href="#idp888400" number=""><ttl>Data manipulation</ttl><xreftext>the section called “Data manipulation”</xreftext><div element="section" href="#idp882416" number=""><ttl>Memcached protocol</ttl><xreftext>the section called “Memcached protocol”</xreftext></div></div><div element="section" href="#idp867984" number=""><ttl>Administrative console</ttl><xreftext>the section called “Administrative console”</xreftext><obj element="term" href="#save-snapshot" number="" targetptr="save-snapshot"><ttl>???TITLE???</ttl><xreftext>SAVE SNAPSHOT</xreftext></obj><obj element="term" href="#reload-configuration" number="" targetptr="reload-configuration"><ttl>???TITLE???</ttl><xreftext>RELOAD CONFIGURATION</xreftext></obj><obj element="term" href="#show-configuration" number="" targetptr="show-configuration"><ttl>???TITLE???</ttl><xreftext>SHOW CONFIGURATION</xreftext></obj><obj element="term" href="#show-info" number="" targetptr="show-info"><ttl>???TITLE???</ttl><xreftext>SHOW INFO</xreftext></obj><obj element="term" href="#show-stat" number="" targetptr="show-stat"><ttl>???TITLE???</ttl><xreftext>SHOW STAT</xreftext></obj><obj element="term" href="#show-slab" number="" targetptr="show-slab"><ttl>???TITLE???</ttl><xreftext>SHOW SLAB</xreftext></obj><obj element="term" href="#show-palloc" number="" targetptr="show-palloc"><ttl>???TITLE???</ttl><xreftext>SHOW PALLOC</xreftext></obj><obj element="term" href="#save-coredump" number="" targetptr="save-coredump"><ttl>???TITLE???</ttl><xreftext>SAVE COREDUMP</xreftext></obj><obj element="term" href="#show-fiber" number="" targetptr="show-fiber"><ttl>???TITLE???</ttl><xreftext>SHOW FIBER</xreftext></obj><obj element="term" href="#lua-command" number="" targetptr="lua-command"><ttl>???TITLE???</ttl><xreftext>LUA ...</xreftext></obj></div><div element="section" href="#stored-procedures" number="" targetptr="stored-procedures"><ttl>Writing stored procedures in Lua</ttl><xreftext>the section called “Writing stored procedures in Lua”</xreftext><obj element="emphasis" href="#init.lua" number="" targetptr="init.lua"><ttl>???TITLE???</ttl><xreftext>init.lua</xreftext></obj><obj element="term" href="#tonumber64" number="" targetptr="tonumber64"><ttl>???TITLE???</ttl><xreftext>tonumber64</xreftext></obj><div element="section" href="#sp-box" number="" targetptr="sp-box"><ttl>Package <code class="code">box</code></ttl><xreftext>the section called “Package <code class="code">box</code>”</xreftext><obj element="variablelist" href="#box" number="" targetptr="box"><ttl>???TITLE???</ttl><xreftext>box</xreftext></obj><obj element="emphasis" href="#box.select" number="" targetptr="box.select"><ttl>???TITLE???</ttl><xreftext>box.select</xreftext></obj><obj element="emphasis" href="#box.select_range" number="" targetptr="box.select_range"><ttl>???TITLE???</ttl><xreftext>box.select_range</xreftext></obj><obj element="emphasis" href="#box.select_reverse_range" number="" targetptr="box.select_reverse_range"><ttl>???TITLE???</ttl><xreftext>box.select_reverse_range</xreftext></obj></div><div element="section" href="#sp-box-tuple" number="" targetptr="sp-box-tuple"><ttl>Package <code class="code">box.tuple</code></ttl><xreftext>the section called “Package <code class="code">box.tuple</code>”</xreftext><obj element="variablelist" href="#box.tuple" number="" targetptr="box.tuple"><ttl>???TITLE???</ttl><xreftext>box.tuple</xreftext></obj></div><div element="section" href="#sp-box-space" number="" targetptr="sp-box-space"><ttl>Package <code class="code">box.space</code></ttl><xreftext>the section called “Package <code class="code">box.space</code>”</xreftext><obj element="variablelist" href="#box.space" number="" targetptr="box.space"><ttl>???TITLE???</ttl><xreftext>box.space</xreftext></obj><obj element="emphasis" href="#box.space.select_range" number="" targetptr="box.space.select_range"><ttl>???TITLE???</ttl><xreftext>box.space[i].select_range()</xreftext></obj><obj element="emphasis" href="#box.space.select_reverse_range" number="" targetptr="box.space.select_reverse_range"><ttl>???TITLE???</ttl><xreftext>box.space.select_reverse_range</xreftext></obj></div><div element="section" href="#sp-box-index" number="" targetptr="sp-box-index"><ttl>Package <code class="code">box.index</code></ttl><xreftext>the section called “Package <code class="code">box.index</code>”</xreftext><obj element="variablelist" href="#box.index" number="" targetptr="box.index"><ttl>???TITLE???</ttl><xreftext>box.index</xreftext></obj><obj element="emphasis" href="#box.index.iterator" number="" targetptr="box.index.iterator"><ttl>???TITLE???</ttl><xreftext>box.index.iterator</xreftext></obj><obj element="table" href="#iterator-types" number="4.1" targetptr="iterator-types"><ttl>Iterator types</ttl><xreftext>Table 4.1, “Iterator types”</xreftext></obj></div><div element="section" href="#sp-box-fiber" number="" targetptr="sp-box-fiber"><ttl>Package <code class="code">box.fiber</code></ttl><xreftext>the section called “Package <code class="code">box.fiber</code>”</xreftext><obj element="variablelist" href="#box.fiber" number="" targetptr="box.fiber"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj></div><div element="section" href="#sp-box-session" number="" targetptr="sp-box-session"><ttl>Package <code class="code">box.session</code></ttl><xreftext>the section called “Package <code class="code">box.session</code>”</xreftext></div><div element="section" href="#sp-box-ipc" number="" targetptr="sp-box-ipc"><ttl>Package <code class="code">box.ipc</code> — inter procedure communication</ttl><xreftext>the section called “Package <code class="code">box.ipc</code> — inter procedure communication”</xreftext><obj element="variablelist" href="#box.ipc" number="" targetptr="box.ipc"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj></div><div element="section" href="#sp-box-socket" number="" targetptr="sp-box-socket"><ttl>Package <code class="code">box.socket</code> — TCP and UDP sockets</ttl><xreftext>the section called “Package <code class="code">box.socket</code> — TCP and UDP sockets”</xreftext><obj element="variablelist" href="#box.socket" number="" targetptr="box.socket"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj><obj element="table" href="#idp425584" number="4.2"><ttl><code class="code">readline()</code> returns</ttl><xreftext>Table 4.2, “<code class="code">readline()</code> returns”</xreftext></obj></div><div element="section" href="#sp-box-cfg" number="" targetptr="sp-box-cfg"><ttl>Packages <code class="code">box.cfg</code>,
+<div element="book" href="#tarantool-user-guide" number="" targetptr="tarantool-user-guide"><ttl>Tarantool User Guide, version 1.4.9-40-g67f3d3c</ttl><xreftext>Tarantool User Guide, version 1.4.9-40-g67f3d3c</xreftext><div element="chapter" href="#preface" number="1" targetptr="preface"><ttl>Preface</ttl><xreftext>Chapter 1, <i>Preface</i></xreftext><div element="section" href="#tarantool-overview" number="" targetptr="tarantool-overview"><ttl>Tarantool: an overview</ttl><xreftext>the section called “Tarantool: an overview”</xreftext></div><div element="section" href="#manual-conventions" number="" targetptr="manual-conventions"><ttl>Conventions</ttl><xreftext>the section called “Conventions”</xreftext></div><div element="section" href="#reporting-bugs" number="" targetptr="reporting-bugs"><ttl>Reporting bugs</ttl><xreftext>the section called “Reporting bugs”</xreftext></div></div><div element="chapter" href="#getting-started" number="2" targetptr="getting-started"><ttl>Getting started</ttl><xreftext>Chapter 2, <i>Getting started</i></xreftext></div><div element="chapter" href="#data-and-persistence" number="3" targetptr="data-and-persistence"><ttl>Data model and data persistence</ttl><xreftext>Chapter 3, <i>Data model and data persistence</i></xreftext><div element="section" href="#dynamic-data-model" number="" targetptr="dynamic-data-model"><ttl>Dynamic data model</ttl><xreftext>the section called “Dynamic data model”</xreftext></div><div element="section" href="#data-persistence" number="" targetptr="data-persistence"><ttl>Data persistence</ttl><xreftext>the section called “Data persistence”</xreftext></div></div><div element="chapter" href="#language-reference" number="4" targetptr="language-reference"><ttl>Language reference</ttl><xreftext>Chapter 4, <i>Language reference</i></xreftext><div element="section" href="#data-manipulation" number="" targetptr="data-manipulation"><ttl>Data manipulation</ttl><xreftext>the section called “Data manipulation”</xreftext><div element="section" href="#memcached-protocol" number="" targetptr="memcached-protocol"><ttl>Memcached protocol</ttl><xreftext>the section called “Memcached protocol”</xreftext></div></div><div element="section" href="#administrative-console" number="" targetptr="administrative-console"><ttl>Administrative console</ttl><xreftext>the section called “Administrative console”</xreftext><obj element="term" href="#save-snapshot" number="" targetptr="save-snapshot"><ttl>???TITLE???</ttl><xreftext>SAVE SNAPSHOT</xreftext></obj><obj element="term" href="#reload-configuration" number="" targetptr="reload-configuration"><ttl>???TITLE???</ttl><xreftext>RELOAD CONFIGURATION</xreftext></obj><obj element="term" href="#show-configuration" number="" targetptr="show-configuration"><ttl>???TITLE???</ttl><xreftext>SHOW CONFIGURATION</xreftext></obj><obj element="term" href="#show-info" number="" targetptr="show-info"><ttl>???TITLE???</ttl><xreftext>SHOW INFO</xreftext></obj><obj element="term" href="#show-stat" number="" targetptr="show-stat"><ttl>???TITLE???</ttl><xreftext>SHOW STAT</xreftext></obj><obj element="term" href="#show-slab" number="" targetptr="show-slab"><ttl>???TITLE???</ttl><xreftext>SHOW SLAB</xreftext></obj><obj element="term" href="#show-palloc" number="" targetptr="show-palloc"><ttl>???TITLE???</ttl><xreftext>SHOW PALLOC</xreftext></obj><obj element="term" href="#save-coredump" number="" targetptr="save-coredump"><ttl>???TITLE???</ttl><xreftext>SAVE COREDUMP</xreftext></obj><obj element="term" href="#show-fiber" number="" targetptr="show-fiber"><ttl>???TITLE???</ttl><xreftext>SHOW FIBER</xreftext></obj><obj element="term" href="#lua-command" number="" targetptr="lua-command"><ttl>???TITLE???</ttl><xreftext>LUA ...</xreftext></obj></div><div element="section" href="#stored-procedures" number="" targetptr="stored-procedures"><ttl>Writing stored procedures in Lua</ttl><xreftext>the section called “Writing stored procedures in Lua”</xreftext><obj element="emphasis" href="#init.lua" number="" targetptr="init.lua"><ttl>???TITLE???</ttl><xreftext>init.lua</xreftext></obj><obj element="term" href="#tonumber64" number="" targetptr="tonumber64"><ttl>???TITLE???</ttl><xreftext>tonumber64</xreftext></obj><div element="section" href="#sp-box" number="" targetptr="sp-box"><ttl>Package <code class="code">box</code></ttl><xreftext>the section called “Package <code class="code">box</code>”</xreftext><obj element="variablelist" href="#box" number="" targetptr="box"><ttl>???TITLE???</ttl><xreftext>box</xreftext></obj><obj element="emphasis" href="#box.select" number="" targetptr="box.select"><ttl>???TITLE???</ttl><xreftext>box.select</xreftext></obj><obj element="emphasis" href="#box.select_range" number="" targetptr="box.select_range"><ttl>???TITLE???</ttl><xreftext>box.select_range</xreftext></obj><obj element="emphasis" href="#box.select_reverse_range" number="" targetptr="box.select_reverse_range"><ttl>???TITLE???</ttl><xreftext>box.select_reverse_range</xreftext></obj></div><div element="section" href="#sp-box-tuple" number="" targetptr="sp-box-tuple"><ttl>Package <code class="code">box.tuple</code></ttl><xreftext>the section called “Package <code class="code">box.tuple</code>”</xreftext><obj element="variablelist" href="#box.tuple" number="" targetptr="box.tuple"><ttl>???TITLE???</ttl><xreftext>box.tuple</xreftext></obj></div><div element="section" href="#sp-box-space" number="" targetptr="sp-box-space"><ttl>Package <code class="code">box.space</code></ttl><xreftext>the section called “Package <code class="code">box.space</code>”</xreftext><obj element="variablelist" href="#box.space" number="" targetptr="box.space"><ttl>???TITLE???</ttl><xreftext>box.space</xreftext></obj><obj element="emphasis" href="#box.space.select_range" number="" targetptr="box.space.select_range"><ttl>???TITLE???</ttl><xreftext>box.space[i].select_range()</xreftext></obj><obj element="emphasis" href="#box.space.select_reverse_range" number="" targetptr="box.space.select_reverse_range"><ttl>???TITLE???</ttl><xreftext>box.space.select_reverse_range</xreftext></obj></div><div element="section" href="#sp-box-index" number="" targetptr="sp-box-index"><ttl>Package <code class="code">box.index</code></ttl><xreftext>the section called “Package <code class="code">box.index</code>”</xreftext><obj element="variablelist" href="#box.index" number="" targetptr="box.index"><ttl>???TITLE???</ttl><xreftext>box.index</xreftext></obj><obj element="emphasis" href="#box.index.iterator" number="" targetptr="box.index.iterator"><ttl>???TITLE???</ttl><xreftext>box.index.iterator</xreftext></obj><obj element="table" href="#iterator-types" number="4.1" targetptr="iterator-types"><ttl>Iterator types</ttl><xreftext>Table 4.1, “Iterator types”</xreftext></obj></div><div element="section" href="#sp-box-fiber" number="" targetptr="sp-box-fiber"><ttl>Package <code class="code">box.fiber</code></ttl><xreftext>the section called “Package <code class="code">box.fiber</code>”</xreftext><obj element="variablelist" href="#box.fiber" number="" targetptr="box.fiber"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj></div><div element="section" href="#sp-box-session" number="" targetptr="sp-box-session"><ttl>Package <code class="code">box.session</code></ttl><xreftext>the section called “Package <code class="code">box.session</code>”</xreftext></div><div element="section" href="#sp-box-ipc" number="" targetptr="sp-box-ipc"><ttl>Package <code class="code">box.ipc</code> — inter procedure communication</ttl><xreftext>the section called “Package <code class="code">box.ipc</code> — inter procedure communication”</xreftext><obj element="variablelist" href="#box.ipc" number="" targetptr="box.ipc"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj></div><div element="section" href="#sp-box-socket" number="" targetptr="sp-box-socket"><ttl>Package <code class="code">box.socket</code> — TCP and UDP sockets</ttl><xreftext>the section called “Package <code class="code">box.socket</code> — TCP and UDP sockets”</xreftext><obj element="variablelist" href="#box.socket" number="" targetptr="box.socket"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj><obj element="table" href="#idp398336" number="4.2"><ttl><code class="code">readline()</code> returns</ttl><xreftext>Table 4.2, “<code class="code">readline()</code> returns”</xreftext></obj></div><div element="section" href="#sp-box-cfg" number="" targetptr="sp-box-cfg"><ttl>Packages <code class="code">box.cfg</code>,
     <code class="code">box.info</code>, <code class="code">box.slab</code> and
     <code class="code">box.stat</code>: server introspection</ttl><xreftext>the section called “Packages <code class="code">box.cfg</code>,
     <code class="code">box.info</code>, <code class="code">box.slab</code> and
-    <code class="code">box.stat</code>: server introspection”</xreftext><obj element="code" href="#box.cfg" number="" targetptr="box.cfg"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="code" href="#box.stat" number="" targetptr="box.stat"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj></div><div element="section" href="#sp-limitations" number="" targetptr="sp-limitations"><ttl>Limitation of stored procedures</ttl><xreftext>the section called “Limitation of stored procedures”</xreftext></div></div></div><div element="chapter" href="#replication" number="5" targetptr="replication"><ttl>Replication</ttl><xreftext>Chapter 5, <i>Replication</i></xreftext><div element="section" href="#idm6192" number=""><ttl>Replication architecture</ttl><xreftext>the section called “Replication architecture”</xreftext></div><div element="section" href="#idp226192" number=""><ttl>Setting up the master</ttl><xreftext>the section called “Setting up the master”</xreftext></div><div element="section" href="#idm1984" number=""><ttl>Setting up a replica</ttl><xreftext>the section called “Setting up a replica”</xreftext></div><div element="section" href="#idp364672" number=""><ttl>Recovering from a degraded state</ttl><xreftext>the section called “Recovering from a degraded state”</xreftext></div></div><div element="chapter" href="#configuration-reference" number="6" targetptr="configuration-reference"><ttl>Configuration reference</ttl><xreftext>Chapter 6, <i>Configuration reference</i></xreftext><div element="section" href="#idp1154336" number=""><ttl>Command line options</ttl><xreftext>the section called “Command line options”</xreftext><obj element="listitem" href="#help-option" number="" targetptr="help-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#version-option" number="" targetptr="version-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#config-option" number="" targetptr="config-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="option" href="#init-storage-option" number="" targetptr="init-storage-option"><ttl>???TITLE???</ttl><xreftext>--init-storage</xreftext></obj><obj element="option" href="#cat-option" number="" targetptr="cat-option"><ttl>???TITLE???</ttl><xreftext>--cat</xreftext></obj></div><div element="section" href="#option-file" number="" targetptr="option-file"><ttl>The option file</ttl><xreftext>option file</xreftext><obj element="table" href="#idp1167024" number="6.1"><ttl>Basic parameters</ttl><xreftext>Table 6.1, “Basic parameters”</xreftext></obj><obj element="entry" href="#work_dir" number="" targetptr="work_dir"><ttl>???TITLE???</ttl><xreftext>work_dir</xreftext></obj><obj element="entry" href="#wal_dir" number="" targetptr="wal_dir"><ttl>???TITLE???</ttl><xreftext>wal_dir</xreftext></obj><obj element="entry" href="#snap_dir" number="" targetptr="snap_dir"><ttl>???TITLE???</ttl><xreftext>snap_dir</xreftext></obj><obj element="entry" href="#primary_port" number="" targetptr="primary_port"><ttl>???TITLE???</ttl><xreftext>primary_port</xreftext></obj><obj element="entry" href="#secondary_port" number="" targetptr="secondary_port"><ttl>???TITLE???</ttl><xreftext>secondary_port</xreftext></obj><obj element="entry" href="#admin_port" number="" targetptr="admin_port"><ttl>???TITLE???</ttl><xreftext>admin_port</xreftext></obj><obj element="entry" href="#custom_proc_title" number="" targetptr="custom_proc_title"><ttl>???TITLE???</ttl><xreftext>custom_proc_title</xreftext></obj><obj element="table" href="#idp1216240" number="6.2"><ttl>Configuring the storage</ttl><xreftext>Table 6.2, “Configuring the storage”</xreftext></obj><obj element="anchor" href="#slab_alloc_arena" number="" targetptr="slab_alloc_arena"><ttl>???TITLE???</ttl><xreftext>slab_alloc_arena</xreftext></obj><obj element="para" href="#space" number="" targetptr="space"><ttl>???TITLE???</ttl><xreftext>the section called “The option file”</xreftext></obj><obj element="table" href="#idp1252304" number="6.3"><ttl>Binary logging and snapshots</ttl><xreftext>Table 6.3, “Binary logging and snapshots”</xreftext></obj><obj element="entry" href="#rows_per_wal" number="" targetptr="rows_per_wal"><ttl>???TITLE???</ttl><xreftext>rows_per_wal</xreftext></obj><obj element="entry" href="#wal_mode" number="" targetptr="wal_mode"><ttl>???TITLE???</ttl><xreftext>wal_mode</xreftext></obj><obj element="table" href="#idp1287632" number="6.4"><ttl>Replication</ttl><xreftext>Table 6.4, “Replication”</xreftext></obj><obj element="entry" href="#replication_port" number="" targetptr="replication_port"><ttl>???TITLE???</ttl><xreftext>replication_port</xreftext></obj><obj element="entry" href="#replication_source" number="" targetptr="replication_source"><ttl>???TITLE???</ttl><xreftext>replication_source</xreftext></obj><obj element="table" href="#idp1306608" number="6.5"><ttl>Networking</ttl><xreftext>Table 6.5, “Networking”</xreftext></obj><obj element="table" href="#idp1325376" number="6.6"><ttl>Logging</ttl><xreftext>Table 6.6, “Logging”</xreftext></obj><obj element="table" href="#idp1350272" number="6.7"><ttl>Memcached protocol support</ttl><xreftext>Table 6.7, “Memcached protocol support”</xreftext></obj><obj element="anchor" href="#memcached_port" number="" targetptr="memcached_port"><ttl>???TITLE???</ttl><xreftext>memcached_port</xreftext></obj><obj element="anchor" href="#memcached_space" number="" targetptr="memcached_space"><ttl>???TITLE???</ttl><xreftext>memcached_space</xreftext></obj><obj element="anchor" href="#memcached_expire" number="" targetptr="memcached_expire"><ttl>???TITLE???</ttl><xreftext>memcached_expire</xreftext></obj></div></div><div element="chapter" href="#connectors" number="7" targetptr="connectors"><ttl>Connectors</ttl><xreftext>Chapter 7, <i>Connectors</i></xreftext><div element="section" href="#idp388128" number=""><ttl>C</ttl><xreftext>the section called “C”</xreftext></div><div element="section" href="#idp387024" number=""><ttl>Perl</ttl><xreftext>the section called “Perl”</xreftext></div><div element="section" href="#idp1024896" number=""><ttl>PHP</ttl><xreftext>the section called “PHP”</xreftext></div><div element="section" href="#idp236416" number=""><ttl>Python</ttl><xreftext>the section called “Python”</xreftext></div><div element="section" href="#idp372240" number=""><ttl>Ruby</ttl><xreftext>the section called “Ruby”</xreftext></div></div><div element="appendix" href="#proctitle" number="A" targetptr="proctitle"><ttl>Server process titles</ttl><xreftext>Appendix A, <i>Server process titles</i></xreftext></div><div element="appendix" href="#errcode" number="B" targetptr="errcode"><ttl>List of error codes</ttl><xreftext>Appendix B, <i>List of error codes</i></xreftext><obj element="term" href="#ER_NONMASTER" number="" targetptr="ER_NONMASTER"><ttl>???TITLE???</ttl><xreftext>ER_NONMASTER</xreftext></obj><obj element="term" href="#ER_ILLEGAL_PARAMS" number="" targetptr="ER_ILLEGAL_PARAMS"><ttl>???TITLE???</ttl><xreftext>ER_ILLEGAL_PARAMS</xreftext></obj><obj element="term" href="#ER_TUPLE_IS_RO" number="" targetptr="ER_TUPLE_IS_RO"><ttl>???TITLE???</ttl><xreftext>ER_TUPLE_IS_RO</xreftext></obj><obj element="term" href="#ER_MEMORY_ISSUE" number="" targetptr="ER_MEMORY_ISSUE"><ttl>???TITLE???</ttl><xreftext>ER_MEMORY_ISSUE</xreftext></obj><obj element="term" href="#ER_WAL_IO" number="" targetptr="ER_WAL_IO"><ttl>???TITLE???</ttl><xreftext>ER_WAL_IO</xreftext></obj><obj element="term" href="#ER_INDEX_VIOLATION" number="" targetptr="ER_INDEX_VIOLATION"><ttl>???TITLE???</ttl><xreftext>ER_INDEX_VIOLATION</xreftext></obj><obj element="term" href="#ER_KEY_PART_COUNT" number="" targetptr="ER_KEY_PART_COUNT"><ttl>???TITLE???</ttl><xreftext>ER_KEY_PART_COUNT</xreftext></obj><obj element="term" href="#ER_NO_SUCH_SPACE" number="" targetptr="ER_NO_SUCH_SPACE"><ttl>???TITLE???</ttl><xreftext>ER_NO_SUCH_SPACE</xreftext></obj><obj element="term" href="#ER_NO_SUCH_INDEX" number="" targetptr="ER_NO_SUCH_INDEX"><ttl>???TITLE???</ttl><xreftext>ER_NO_SUCH_INDEX</xreftext></obj><obj element="term" href="#ER_PROC_LUA" number="" targetptr="ER_PROC_LUA"><ttl>???TITLE???</ttl><xreftext>ER_PROC_LUA</xreftext></obj></div></div>
+    <code class="code">box.stat</code>: server introspection”</xreftext><obj element="code" href="#box.cfg" number="" targetptr="box.cfg"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="code" href="#box.stat" number="" targetptr="box.stat"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj></div><div element="section" href="#sp-limitations" number="" targetptr="sp-limitations"><ttl>Limitation of stored procedures</ttl><xreftext>the section called “Limitation of stored procedures”</xreftext></div></div><div element="section" href="#triggers" number="" targetptr="triggers"><ttl>Defining triggers in Lua</ttl><xreftext>the section called “Defining triggers in Lua”</xreftext><div element="section" href="#sp-box-session-triggers" number="" targetptr="sp-box-session-triggers"><ttl>Triggers on connect and disconnect</ttl><xreftext>session triggers</xreftext></div></div></div><div element="chapter" href="#replication" number="5" targetptr="replication"><ttl>Replication</ttl><xreftext>Chapter 5, <i>Replication</i></xreftext><div element="section" href="#replication-architecture" number="" targetptr="replication-architecture"><ttl>Replication architecture</ttl><xreftext>the section called “Replication architecture”</xreftext></div><div element="section" href="#setting-up-the-master" number="" targetptr="setting-up-the-master"><ttl>Setting up the master</ttl><xreftext>the section called “Setting up the master”</xreftext></div><div element="section" href="#settin-up-a-replica" number="" targetptr="settin-up-a-replica"><ttl>Setting up a replica</ttl><xreftext>the section called “Setting up a replica”</xreftext></div><div element="section" href="#recovering-from-a-degraded-state" number="" targetptr="recovering-from-a-degraded-state"><ttl>Recovering from a degraded state</ttl><xreftext>the section called “Recovering from a degraded state”</xreftext></div></div><div element="chapter" href="#configuration-reference" number="6" targetptr="configuration-reference"><ttl>Configuration reference</ttl><xreftext>Chapter 6, <i>Configuration reference</i></xreftext><div element="section" href="#command-line-options" number="" targetptr="command-line-options"><ttl>Command line options</ttl><xreftext>the section called “Command line options”</xreftext><obj element="listitem" href="#help-option" number="" targetptr="help-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#version-option" number="" targetptr="version-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#config-option" number="" targetptr="config-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="option" href="#init-storage-option" number="" targetptr="init-storage-option"><ttl>???TITLE???</ttl><xreftext>--init-storage</xreftext></obj><obj element="option" href="#cat-option" number="" targetptr="cat-option"><ttl>???TITLE???</ttl><xreftext>--cat</xreftext></obj></div><div element="section" href="#option-file" number="" targetptr="option-file"><ttl>The option file</ttl><xreftext>option file</xreftext><obj element="table" href="#idp1180064" number="6.1"><ttl>Basic parameters</ttl><xreftext>Table 6.1, “Basic parameters”</xreftext></obj><obj element="entry" href="#work_dir" number="" targetptr="work_dir"><ttl>???TITLE???</ttl><xreftext>work_dir</xreftext></obj><obj element="entry" href="#wal_dir" number="" targetptr="wal_dir"><ttl>???TITLE???</ttl><xreftext>wal_dir</xreftext></obj><obj element="entry" href="#snap_dir" number="" targetptr="snap_dir"><ttl>???TITLE???</ttl><xreftext>snap_dir</xreftext></obj><obj element="entry" href="#bind_ipaddr" number="" targetptr="bind_ipaddr"><ttl>???TITLE???</ttl><xreftext>bind_ipaddr</xreftext></obj><obj element="entry" href="#primary_port" number="" targetptr="primary_port"><ttl>???TITLE???</ttl><xreftext>primary_port</xreftext></obj><obj element="entry" href="#secondary_port" number="" targetptr="secondary_port"><ttl>???TITLE???</ttl><xreftext>secondary_port</xreftext></obj><obj element="entry" href="#admin_port" number="" targetptr="admin_port"><ttl>???TITLE???</ttl><xreftext>admin_port</xreftext></obj><obj element="entry" href="#custom_proc_title" number="" targetptr="custom_proc_title"><ttl>???TITLE???</ttl><xreftext>custom_proc_title</xreftext></obj><obj element="table" href="#idp1233728" number="6.2"><ttl>Configuring the storage</ttl><xreftext>Table 6.2, “Configuring the storage”</xreftext></obj><obj element="anchor" href="#slab_alloc_arena" number="" targetptr="slab_alloc_arena"><ttl>???TITLE???</ttl><xreftext>slab_alloc_arena</xreftext></obj><obj element="para" href="#space" number="" targetptr="space"><ttl>???TITLE???</ttl><xreftext>the section called “The option file”</xreftext></obj><obj element="table" href="#idp1269856" number="6.3"><ttl>Binary logging and snapshots</ttl><xreftext>Table 6.3, “Binary logging and snapshots”</xreftext></obj><obj element="entry" href="#rows_per_wal" number="" targetptr="rows_per_wal"><ttl>???TITLE???</ttl><xreftext>rows_per_wal</xreftext></obj><obj element="entry" href="#wal_mode" number="" targetptr="wal_mode"><ttl>???TITLE???</ttl><xreftext>wal_mode</xreftext></obj><obj element="table" href="#idp1305184" number="6.4"><ttl>Replication</ttl><xreftext>Table 6.4, “Replication”</xreftext></obj><obj element="entry" href="#replication_port" number="" targetptr="replication_port"><ttl>???TITLE???</ttl><xreftext>replication_port</xreftext></obj><obj element="entry" href="#replication_source" number="" targetptr="replication_source"><ttl>???TITLE???</ttl><xreftext>replication_source</xreftext></obj><obj element="table" href="#idp1324288" number="6.5"><ttl>Networking</ttl><xreftext>Table 6.5, “Networking”</xreftext></obj><obj element="table" href="#idp1343056" number="6.6"><ttl>Logging</ttl><xreftext>Table 6.6, “Logging”</xreftext></obj><obj element="table" href="#idp1367952" number="6.7"><ttl>Memcached protocol support</ttl><xreftext>Table 6.7, “Memcached protocol support”</xreftext></obj><obj element="anchor" href="#memcached_port" number="" targetptr="memcached_port"><ttl>???TITLE???</ttl><xreftext>memcached_port</xreftext></obj><obj element="anchor" href="#memcached_space" number="" targetptr="memcached_space"><ttl>???TITLE???</ttl><xreftext>memcached_space</xreftext></obj><obj element="anchor" href="#memcached_expire" number="" targetptr="memcached_expire"><ttl>???TITLE???</ttl><xreftext>memcached_expire</xreftext></obj></div></div><div element="chapter" href="#connectors" number="7" targetptr="connectors"><ttl>Connectors</ttl><xreftext>Chapter 7, <i>Connectors</i></xreftext><div element="section" href="#connector-c" number="" targetptr="connector-c"><ttl>C</ttl><xreftext>the section called “C”</xreftext></div><div element="section" href="#connector-node.js" number="" targetptr="connector-node.js"><ttl>node.js</ttl><xreftext>the section called “node.js”</xreftext></div><div element="section" href="#connector-perl" number="" targetptr="connector-perl"><ttl>Perl</ttl><xreftext>the section called “Perl”</xreftext></div><div element="section" href="#connector-php" number="" targetptr="connector-php"><ttl>PHP</ttl><xreftext>the section called “PHP”</xreftext></div><div element="section" href="#connector-python" number="" targetptr="connector-python"><ttl>Python</ttl><xreftext>the section called “Python”</xreftext></div><div element="section" href="#connector-ruby" number="" targetptr="connector-ruby"><ttl>Ruby</ttl><xreftext>the section called “Ruby”</xreftext></div></div><div element="chapter" href="#os-install-notes" number="8" targetptr="os-install-notes"><ttl>System-specific installation notes</ttl><xreftext>Chapter 8, <i>System-specific installation notes</i></xreftext><div element="section" href="#Debian" number="" targetptr="Debian"><ttl>Debian GNU/Linux and Ubuntu</ttl><xreftext>the section called “Debian GNU/Linux and Ubuntu”</xreftext></div><div element="section" href="#rpm-based-distros" number="" targetptr="rpm-based-distros"><ttl>Fedora, RHEL, CentOS</ttl><xreftext>the section called “Fedora, RHEL, CentOS”</xreftext></div><div element="section" href="#FreeBSD" number="" targetptr="FreeBSD"><ttl>FreeBSD</ttl><xreftext>the section called “FreeBSD”</xreftext></div><div element="section" href="#mac-os-x" number="" targetptr="mac-os-x"><ttl>Mac OS X</ttl><xreftext>the section called “Mac OS X”</xreftext></div></div><div element="appendix" href="#proctitle" number="A" targetptr="proctitle"><ttl>Server process titles</ttl><xreftext>Appendix A, <i>Server process titles</i></xreftext></div><div element="appendix" href="#errcode" number="B" targetptr="errcode"><ttl>List of error codes</ttl><xreftext>Appendix B, <i>List of error codes</i></xreftext><obj element="term" href="#ER_NONMASTER" number="" targetptr="ER_NONMASTER"><ttl>???TITLE???</ttl><xreftext>ER_NONMASTER</xreftext></obj><obj element="term" href="#ER_ILLEGAL_PARAMS" number="" targetptr="ER_ILLEGAL_PARAMS"><ttl>???TITLE???</ttl><xreftext>ER_ILLEGAL_PARAMS</xreftext></obj><obj element="term" href="#ER_TUPLE_IS_RO" number="" targetptr="ER_TUPLE_IS_RO"><ttl>???TITLE???</ttl><xreftext>ER_TUPLE_IS_RO</xreftext></obj><obj element="term" href="#ER_MEMORY_ISSUE" number="" targetptr="ER_MEMORY_ISSUE"><ttl>???TITLE???</ttl><xreftext>ER_MEMORY_ISSUE</xreftext></obj><obj element="term" href="#ER_WAL_IO" number="" targetptr="ER_WAL_IO"><ttl>???TITLE???</ttl><xreftext>ER_WAL_IO</xreftext></obj><obj element="term" href="#ER_INDEX_VIOLATION" number="" targetptr="ER_INDEX_VIOLATION"><ttl>???TITLE???</ttl><xreftext>ER_INDEX_VIOLATION</xreftext></obj><obj element="term" href="#ER_KEY_PART_COUNT" number="" targetptr="ER_KEY_PART_COUNT"><ttl>???TITLE???</ttl><xreftext>ER_KEY_PART_COUNT</xreftext></obj><obj element="term" href="#ER_NO_SUCH_SPACE" number="" targetptr="ER_NO_SUCH_SPACE"><ttl>???TITLE???</ttl><xreftext>ER_NO_SUCH_SPACE</xreftext></obj><obj element="term" href="#ER_NO_SUCH_INDEX" number="" targetptr="ER_NO_SUCH_INDEX"><ttl>???TITLE???</ttl><xreftext>ER_NO_SUCH_INDEX</xreftext></obj><obj element="term" href="#ER_PROC_LUA" number="" targetptr="ER_PROC_LUA"><ttl>???TITLE???</ttl><xreftext>ER_PROC_LUA</xreftext></obj></div></div>
diff --git a/doc/user/triggers.xml b/doc/user/triggers.xml
new file mode 100644
index 0000000000..051994f1eb
--- /dev/null
+++ b/doc/user/triggers.xml
@@ -0,0 +1,72 @@
+<!DOCTYPE section [
+<!ENTITY % tnt SYSTEM "../tnt.ent">
+%tnt;
+]>
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xml:id="triggers">
+  <title>Defining triggers in Lua</title>
+<blockquote>
+    <para>
+        Triggers are Lua scripts invoked by the system upon
+        a certain event. Tarantool currently only supports
+        system-wide triggers, run when a new connection
+        is established or dropped. Since trigger body is
+        a Lua script, it is external to the server, and
+        a trigger must be set up on each server start.
+        This is most commonly done in <olink
+        targetptr="init.lua">the initialization script</olink>.
+        Once a trigger for an event exists, it is automatically
+        invoked whenever an event occurs.  The performance
+        overhead of triggers, as long as they are not defined, is
+        minimal: merely a pointer dereference and check. If a
+        trigger is defined, its overhead is equivalent to the
+        overhead of calling a stored procedure.
+    </para>
+</blockquote>
+<section xml:id="sp-box-session-triggers" xreflabel="session triggers">
+    <title>Triggers on connect and disconnect</title>
+<variablelist>
+    <varlistentry>
+        <term>
+            <emphasis role="lua">box.session.on_connect(chunk) </emphasis>
+        </term>
+        <listitem><para>
+		Set a callback (trigger) invoked on each connected session.
+        The callback doesn't get any arguments, but is the first
+        thing invoked in the scope of the newly created session.
+        If the trigger fails by raising an error, the error
+        is sent to the client and the connection is shut down.
+        Returns the old value of the trigger.
+        </para>
+        <warning>
+        <para>
+        If a trigger always results in an error, it may become
+        impossible to connect to the server to reset it.
+        </para>
+        </warning>
+        </listitem>
+    </varlistentry>
+
+    <varlistentry>
+        <term>
+            <emphasis role="lua">box.session.on_disconnect(chunk)</emphasis>
+        </term>
+        <listitem><simpara>Set a trigger invoked after a client has
+        disconnected. Returns the old value of the trigger. If
+        the trigger raises an error, the error is logged but otherwise
+        is ignored. The trigger is invoked while the session associated
+        with the client still exists and can access session properties,
+        such as id.
+        </simpara></listitem>
+    </varlistentry>
+</variablelist>
+</section>
+
+</section>
+
+<!--
+vim: tw=66 syntax=docbk
+vim: spell spelllang=en_us
+-->
diff --git a/doc/user/tutorial.xml b/doc/user/tutorial.xml
index ec69f7c711..a826ebb652 100644
--- a/doc/user/tutorial.xml
+++ b/doc/user/tutorial.xml
@@ -1,20 +1,36 @@
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
-         xmlns:xlink="http://www.w3.org/1999/xlink">
+         xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="getting-started">
 <title>Getting started</title>
 <blockquote><para>
-  This chapter describes the contents
-  of binary and source package download, explains how to
-  start or stop the server, and explains how to connect to it with
-  a command line client.
+  This chapter describes installation procedures, the contents of
+  binary and source package download, explains how to start,
+  stop the server or connect to it with a command line client.
 </para></blockquote>
 
 <para>
-  Tarantool is distributed in binary and source code form.
+  To install Tarantool, check out instructions on the project
+  <citetitle xlink:href="http://tarantool.org/download.html"
+  xlink:title="Download Tarantool">download page</citetitle>. For
+  many distributions the server and the command line client are
+  available from the distribution's upstream. Local repositories
+  for popular Linux distributions, as well as a FreeBSD port
+  and a Mac OS X "homebrew" recipe are also available online.
+  The online archive is automatically refreshed on each push
+  into the stable branch of the server. Please follow
+  <olink targetptr="os-install-notes">distribution-specific
+  instructions</olink> to find out how to manage
+  Tarantool instances on your operating system.
+</para>
+<para>
+  The easiest way to try Tarantool without installing it is by
+  downloading a binary or source package tarball.
   Binary packages use <filename>tarantool-<replaceable>&lt;version&gt;</replaceable>-<replaceable>&lt;OS&gt;</replaceable>-<replaceable>&lt;machine&gt;</replaceable>.tar.gz</filename> naming scheme. Source packages are
   named simply <filename>tarantool-<replaceable>&lt;version&gt;</replaceable>-src.tar.gz</filename>.
   You can find out the canonical name of your operating system
   and machine type with <command>uname -o</command> and <command>uname
--m</command> respectively.
+-m</command> respectively. The programs included into the binary
+  tarball are linked statically to not have any external dependencies.
+
   Besides the downloaded package, you will need the following
   software:
 
@@ -45,6 +61,8 @@
   After download, unpack the binary package, a new directory will be created:
   <programlisting>
   <prompt>$ </prompt><command>tar</command> <option>zxvf</option> <filename><replaceable><replaceable>package-name</replaceable></replaceable>.tar.gz</filename></programlisting>
+  To remove a binary tarball package, simply drop the directory
+  containing the unpacked files.
   The binary download contains just two subdirectories:
   <filename>bin</filename> and <filename>doc</filename>.
   The server, by default, looks for its configuration file in
@@ -93,7 +111,7 @@
   of optional features:
   <programlisting>
   -- *** The following options are on in this configuration: ***
-  -- ENABLE_CLIENT: true 
+  -- ENABLE_CLIENT: true
   -- ENABLE_GCOV: ON
   -- ENABLE_TRACE: ON
   -- ENABLE_BACKTRACE: ON
diff --git a/doc/user/user.xml b/doc/user/user.xml
index c86efb427f..e70be657a2 100644
--- a/doc/user/user.xml
+++ b/doc/user/user.xml
@@ -15,6 +15,7 @@
 <xi:include href="replication.xml"/>
 <xi:include href="configuration-reference.xml"/>
 <xi:include href="connectors.xml"/>
+<xi:include href="os-install-notes.xml"/>
 <xi:include href="proctitle.xml"/>
 <xi:include href="errcode.xml"/>
 <!--
-- 
GitLab