From af2ff08940084173ba9435b92eccbd39a6d1ebb2 Mon Sep 17 00:00:00 2001
From: Christian Schwarz <me@cschwarz.com>
Date: Mon, 18 Sep 2017 00:59:59 +0200
Subject: [PATCH] docs: document UNIX sockets & job debugging

---
 docs/content/configuration/misc.md       | 52 ++++++++++++++++++++++++
 docs/content/configuration/prune.md      |  2 +-
 docs/content/configuration/transports.md |  1 +
 docs/content/install/_index.md           | 23 ++++-------
 4 files changed, 63 insertions(+), 15 deletions(-)
 create mode 100644 docs/content/configuration/misc.md

diff --git a/docs/content/configuration/misc.md b/docs/content/configuration/misc.md
new file mode 100644
index 0000000..3c30b54
--- /dev/null
+++ b/docs/content/configuration/misc.md
@@ -0,0 +1,52 @@
++++
+title = "Miscellaneous"
+weight = 100
++++
+
+## Runtime Directories & UNIX Sockets
+
+zrepl daemon creates various UNIX sockets to allow communicating with it:
+
+* the `stdinserver` transport connects to a socket named after `client_identity` parameter
+* the `control` subcommand connects to a defined control socket
+
+There is no further authentication on these sockets.
+Therefore we have to make sure they can only be created and accessed by `zrepl daemon`.
+
+In fact, `zrepl daemon` will not bind a socket to a path in a directory that is world-accessible.
+
+The directories can be configured in the main configuration file:
+
+```yaml
+global:
+  control:
+    sockpath: /var/run/zrepl/control
+  serve:
+    stdinserver:
+      sockdir: /var/run/zrepl/stdinserver
+```
+
+
+## Super-Verbose Job Debugging
+
+You have probably landed here because you opened an issue on GitHub and some developer told you to do this...
+So just read the annotated comments ;)
+
+```yaml
+
+job:
+- name: ...
+  ...
+ # JOB DEBUGGING OPTIONS
+  # should be equal for all job types, but each job implements the debugging itself
+  debug:
+    conn: # debug the io.ReadWriteCloser connection
+      read_dump: /tmp/connlog_read   # dump results of Read() invocations to this file
+      write_dump: /tmp/connlog_write # dump results of Write() invocations to this file
+    rpc: # debug the RPC protocol implementation
+      log: true # log output from rpc layer to the job log
+```
+
+{{% notice info %}}
+Connection dumps will almost certainly contain your or other's private data. Do not share it in a bug report.
+{{% /notice %}}
diff --git a/docs/content/configuration/prune.md b/docs/content/configuration/prune.md
index 7a04098..97ebc57 100644
--- a/docs/content/configuration/prune.md
+++ b/docs/content/configuration/prune.md
@@ -1,7 +1,7 @@
 +++
 title = "Pruning"
 description = "Automated pruning of snapshots"
-weight = 200
+weight = 40
 +++
 
 {{% alert theme="warning" %}}Under Construction{{% /alert %}}
diff --git a/docs/content/configuration/transports.md b/docs/content/configuration/transports.md
index bb52e44..c2e5739 100644
--- a/docs/content/configuration/transports.md
+++ b/docs/content/configuration/transports.md
@@ -1,5 +1,6 @@
 +++
 title = "Transports"
+weight = 30
 +++
 
 {{% alert theme="warning" %}}Under Construction{{% /alert %}}
diff --git a/docs/content/install/_index.md b/docs/content/install/_index.md
index 0356d41..f80eeff 100644
--- a/docs/content/install/_index.md
+++ b/docs/content/install/_index.md
@@ -35,31 +35,26 @@ rehash
 zrepl help
 ```
 
+## Configuration Files
 
-
-## Configuration & Runtime Directories
-
-### Main Configuration File
-
-The main configuration file lives in either
+zrepl searches for its main configuration file in the following locations (in that order):
 
 * `/etc/zrepl/zrepl.yml`
 * `/usr/local/etc/zrepl/zrepl.yml`
 
-The file locations are check in that order. Alternative locations must be specified using a command line flag.
+Copy a config from the [tutorial](/tutorial) or the `cmd/sampleconf` directory to one of these locations and customize it to your setup.
 
-### Runtime Directories
+## Runtime Directories
 
-**Source jobs** with `serve.type = stdinserver` require a private runtime directory. ([Why?]({{< relref "configuration/transports.md#stdinserver" >}}))
-
-The default is `/var/run/zrepl/stdinserver` and it must only be accessible by the user
-that runs `zrepl daemon` and `zrepl stdinserver`:
+For default settings, the following should to the trick.
+Check out the [configuration documentation]({{< relref "configuration/misc.md#runtime-directories-unix-sockets" >}}) for more information.
 
 ```bash
 mkdir -p /var/run/zrepl/stdinserver
 chmod -R 0700 /var/run/zrepl
 ```
 
+
 ## Running the Daemon
 
 All work zrepl done is performed by a daemon process.
@@ -69,7 +64,7 @@ There are no *rc(8)* or *systemd.service(5)* service definitions yet.
 The daemon does not fork and writes all log output to stderr.
 
 ```bash
-zrepl --config /etc/zrepl/zrepl.yml daemon
+zrepl daemon
 ```
 
 FreeBSD ships with the *daemon(8)* utility which is also a good start for writing an *rc(8)* file:
@@ -82,7 +77,7 @@ daemon -o /var/log/zrepl.log \
 
 {{% notice info %}}
 Make sure to read the first lines of log output after the daemon starts: if the daemon cannot create the [stdinserver]({{< relref "configuration/transports.md#stdinserver" >}}) sockets
-in the runtime directory, it will complain but not terminate as other tasks such as taking periodic snapshots might still work.
+in the runtime directory, it will complain but not terminate as other tasks such as taking periodic snapshots might still work and are equally important.
 {{% / notice %}}
 
 ### Restarting