Revise admin chapter (iteration #2)

Author: lenkis

doc/1.7/book/admin/daemon_supervision.rst

@@ -47,8 +47,9 @@ long-running procedure which prevents return to the main thread event loop.
 Automatic instance restart
 --------------------------------------------------------------------------------
 
-``systemd`` automatically restarts all Tarantool instances in case of failure.
-To demonstrate it, let’s try to destroy an instance:
+On ``systemd``-enabled platforms, ``systemd`` automatically restarts all
+Tarantool instances in case of failure. To demonstrate it, let’s try to destroy
+an instance:
 
 .. code-block:: bash
 
@@ -89,25 +90,25 @@ Finally, let’s check the boot logs:
 Core dumps
 --------------------------------------------------------------------------------
 
-Tarantool makes a core dump if it receives any of these signals: SIGSEGV, SIGFPE,
-SIGABRT or SIGQUIT. This is automatic if Tarantool crashes. On systems with
-``systemd``, ``coredumpctl`` automatically saves core dumps and stack traces in
-case of a crash.
+Tarantool makes a core dump if it receives any of the following signals: SIGSEGV,
+SIGFPE, SIGABRT or SIGQUIT. This is automatic if Tarantool crashes.
 
-For this to work, make sure in advance that:
+On ``systemd``-enabled platforms, ``coredumpctl`` automatically saves core dumps
+and stack traces in case of a crash. Here is a general "how to" for how to
+enable core dumps on a Unix system:
 
-* Core dumps are enabled on the system. In Linux, you might need to say
-  ``ulimit -c unlimited``, but there are many other reasons why a core dump will
-  not be produced, as explained by "man 5 core". Often core dumps are not allowed
-  by default because core dumps can be large.
+1. Ensure session limits are configured to enable core dumps, i.e. say
+   ``ulimit -c unlimited``. Check  "man 5 core" for other reasons why a core
+   dump may not be produced. 
 
-* You know what directory core dumps would be written to, and be sure that that
-  directory is writable.
+2. Set a directory for writing core dumps to, and make sure that the directory
+   is writable. On Linux, the directory path is set in a kernel parameter
+   configurable via ``/proc/sys/kernel/core_pattern``.
 
-* A core dump will include stack trace information. If you use a binary
-  distribution, this is automatic. If you build Tarantool from source, you will
-  not get detailed information if you pass ``-DCMAKE_BUILD_TYPE=Release``
-  to CMake.
+3. Make sure that core dumps include stack trace information. If you use a
+   binary Tarantool distribution, this is automatic. If you build Tarantool
+   from source, you will not get detailed information if you pass
+   ``-DCMAKE_BUILD_TYPE=Release`` to CMake.
 
 To simulate a crash, you can execute an illegal command against a Tarantool
 instance:
@@ -116,13 +117,10 @@ instance:
 
    $ # !!! please never do this on a production system !!!
    $ tarantoolctl enter my_app
-   /bin/tarantoolctl: Found my_app.lua in /etc/tarantool/instances.available
-   /bin/tarantoolctl: Connecting to /var/run/tarantool/my_app.control
-   /bin/tarantoolctl: connected to unix/:/var/run/tarantool/my_app.control
    unix/:/var/run/tarantool/my_app.control> require('ffi').cast('char *', 0)[0] = 48
    /bin/tarantoolctl: unix/:/var/run/tarantool/my_app.control: Remote host closed connection
 
-Alternatively, if you know the process id of the instance (here we refer to it
+Alternatively, if you know the process ID of the instance (here we refer to it
 as $PID), you can abort a Tarantool instance by running ``gdb`` debugger:
 
 .. code-block:: bash
@@ -145,7 +143,8 @@ or manually sending a SIGABRT signal:
 
    * say ``systemctl status tarantool@my_app|grep PID``.
 
-To see the latest crashes of the Tarantool daemon, say:
+On a ``systemd-enabled`` system, to see the latest crashes of the Tarantool
+daemon, say:
 
 .. code-block:: bash
 

doc/1.7/book/admin/disaster_recovery.rst

@@ -44,28 +44,40 @@ transferred to the replica before crash. If you were able to salvage the master
 
 1. Find out the position of the crashed master, as reflected on the new master.
 
-2. Find out instance UUID from the crashed master xlog:
+   a. Find out instance UUID from the crashed master xlog:
 
-   .. code-block:: bash
-   
-      $ head -5 *.xlog | grep Instance   
-      Instance: ed607cad-8b6d-48d8-ba0b-dae371b79155
+      .. code-block:: bash
+      
+         $ head -5 *.xlog | grep Instance   
+         Instance: ed607cad-8b6d-48d8-ba0b-dae371b79155
 
-3. On the new master, use the UUID to find the position:
+   b. On the new master, use the UUID to find the position:
 
-   .. code-block:: tarantoolsession
-   
-      tarantool>box.info.vclock[box.space._cluster.index.uuid:select{'ed607cad-8b6d-48d8-ba0b-dae371b79155'}[1][1]]
-      ---
-      - 23425
-      <...>
+      .. code-block:: tarantoolsession
       
-4. Play the records from the crashed .xlog to the new master, starting from the
+         tarantool>box.info.vclock[box.space._cluster.index.uuid:select{'ed607cad-8b6d-48d8-ba0b-dae371b79155'}[1][1]]
+         ---
+         - 23425
+         <...>
+      
+2. Play the records from the crashed .xlog to the new master, starting from the
    new master position:
-
-   .. code-block:: tarantoolsession
 
-      $ tarantoolctl <new_master_uri> <xlog_file> play --from-lsn 23425
+   a. Issue this request locally at the new master's machine to find out
+      instance ID of the new master:
+   
+      .. code-block:: tarantoolsession
+      
+         tarantool> box.space._cluster:select{}
+         ---
+         - - [1, '88580b5c-4474-43ab-bd2b-2409a9af80d2']
+         ...
+   
+   b. Play the records to the new master:
+
+      .. code-block:: tarantoolsession
+      
+         $ tarantoolctl <new_master_uri> <xlog_file> play --from-lsn 23425 -- replica_id 1
 
 .. _admin-disaster_recovery-master_master:
 
@@ -108,3 +120,5 @@ Your actions:
 
 3. Start a new instance (instance#1) and use ``tarantoolctl play`` command to
    play to it the contents of .snap/.xlog files up to the calculated lsn.
+
+4. Bootstrap a new replica from the recovered master (instance#1).

doc/1.7/book/admin/logs.rst

@@ -38,7 +38,7 @@ Then check the logs:
    2017-04-04 15:54:04.989 [29255] main C> entering the event loop
    2017-04-04 15:54:47.147 [29255] main/107/console/unix/: I> Hello for the manual readers
 
-When logging to a log file, the system administrator must ensure logs are
+When logging to a file, the system administrator must ensure logs are
 rotated timely and do not take up all the available disk space. With 
 ``tarantoolctl``, log rotation is pre-configured to use ``logrotate`` program,
 which you must have installed.

doc/1.7/book/admin/security.rst

@@ -55,8 +55,8 @@ For example:
    Tarantool 1.7.3 (Lua console)
    type 'help' for interactive help
 
-In this example, the response does not include the word “binary” and does
-include the words “Lua console”. Therefore it is clear that this is a successful
+In this example, the response does not include the word "binary" and does
+include the words "Lua console". Therefore it is clear that this is a successful
 connection to a port for admin console, and you can now enter admin requests on
 this terminal.
 
@@ -74,5 +74,5 @@ privilege.
 
 Therefore, when ``ssh`` access to the machine is not available, creating a
 Tarantool user with global "EXECUTE" privilege and non-empty password can be
-used to provide a system administrator remote access to an instance.
+used to provide a system administrator **remote** access to an instance.
 

doc/1.7/book/admin/server_introspection.rst

@@ -35,7 +35,7 @@ You can attach to an instance's admin console and execute some Lua code using
 
 .. code-block:: bash
 
-   # for local instances:
+   $ # for local instances:
    $ tarantoolctl enter my_app
    /bin/tarantoolctl: Found my_app.lua in /etc/tarantool/instances.available
    /bin/tarantoolctl: Connecting to /var/run/tarantool/my_app.control
@@ -46,7 +46,7 @@ You can attach to an instance's admin console and execute some Lua code using
    ...
    unix/:/var/run/tarantool/my_app.control>
    
-   # for local and remote instances:
+   $ # for local and remote instances:
    $ tarantoolctl connect username:[email protected]:3306
 
 You can also use ``tarantoolctl`` to execute Lua code on an instance without

doc/1.7/book/admin/upgrades.rst

@@ -42,10 +42,10 @@ when migrating from Tarantool 1.6. to 1.8 directly.
 
 This procedure is for upgrading a standalone Tarantool instance in production
 from 1.6.x to 1.7.x. Notice that this will **always imply a downtime**.
-To upgrade without downtime, you need several Tarantool servers running in a
+To upgrade **without downtime**, you need several Tarantool servers running in a
 replication cluster (see :ref:`below <admin-upgrades_replication_cluster>`).
 
-Tarantool 1.7 has an incompatible snapshot and .xlog file format: 1.6 files are
+Tarantool 1.7 has an incompatible .snap and .xlog file format: 1.6 files are
 supported during upgrade, but you won’t be able to return to 1.6 after running
 under 1.7 for a while. It also renames a few configuration parameters, but old
 parameters are supported. The full list of breaking changes is available in
@@ -73,7 +73,7 @@ To upgrade from Tarantool 1.6 to 1.7:
 
 6. Update application files, if needed.
 
-7. Launch the updated Tarantool server.
+7. Launch the updated Tarantool server using ``tarantoolctl`` or ``systemctl``.
 
 .. _admin-upgrades_replication_cluster:
 

doc/1.7/reference/tarantoolctl.rst

@@ -1,7 +1,7 @@
 .. _tarantoolctl:
 
 --------------------------------------------------------------------------------
-tarantoolctl
+Utility `tarantoolctl`
 --------------------------------------------------------------------------------
 
 ``tarantoolctl`` is a utility for administering Tarantool instances. It is