From abafc0c8eccedafe9d4daf9fc585e638a5c009f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Petazzoni?= <jerome.petazzoni@gmail.com>
Date: Sun, 16 Apr 2017 23:47:56 -0500
Subject: [PATCH] Add swarm-rafttool

---
 docs/index.html | 154 +++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 127 insertions(+), 27 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 258cf004..d000d38a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -4233,28 +4233,25 @@ class: swarmctl
 
 ---
 
-class: swarmctl
+class: swarmtools
 
-## Getting cluster-wide task information
+## SwarmKit debugging tools
 
-- The Docker API doesn't expose this directly (yet)
+- The SwarmKit repository comes with debugging tools
 
-- But the SwarmKit API does
+- They are *low level* tools; not for general use
 
-- Let's see how to use it
+- We are going to see two of these tools:
 
-- We will use `swarmctl`
+  - `swarmctl`, to communicate directly with the SwarmKit API
 
-- `swarmctl` is an example program showing how to
-  interact with the SwarmKit API
-
-- First, we need to install `swarmctl`
+  - `swarm-rafttool`, to inspect the content of the Raft log
 
 ---
 
-class: swarmctl
+class: swarmtools
 
-## Building `swarmctl`
+## Building the SwarmKit tools
 
 - We are going to install a Go compiler, then download SwarmKit source and build it
 
@@ -4273,33 +4270,52 @@ Shameless promo: for more Go and Docker love, check
 [this blog post](http://jpetazzo.github.io/2016/09/09/go-docker/)!
 
 Note: in the unfortunate event of SwarmKit *master* branch being broken,
-the build might fail. In that case, just skip the `swarmctl` section.
+the build might fail. In that case, just skip the Swarm tools section.
 
 ---
 
-class: swarmctl
+class: swarmtools
+
+## Getting cluster-wide task information
+
+- The Docker API doesn't expose this directly (yet)
+
+- But the SwarmKit API does
+
+- We are going to query it with `swarmctl`
+
+- `swarmctl` is an example program showing how to
+  interact with the SwarmKit API
+
+---
+
+class: swarmtools
 
 ## Using `swarmctl`
 
 - The Docker Engine places the SwarmKit control socket in a special path
 
-- And you need root privileges to access it
+- You need root privileges to access it
 
 .exercise[
 
-- Set an alias so that swarmctl can run as root and use the right control socket:
+- If you are using Play-With-Docker, set the following alias:
   ```bash
-    alias \
-      swarmctl='sudo swarmctl --socket /var/run/docker/swarm/control.sock'
+    alias swarmctl='/lib/ld-musl-x86_64.so.1 /usr/local/bin/swarmctl \
+                    --socket /var/run/docker/swarm/control.sock'
+  ```
+
+- Otherwise, set the following alias:
+  ```bash
+    alias swarmctl='sudo swarmctl \
+                    --socket /var/run/docker/swarm/control.sock'
   ```
 
 ]
 
-(Note: with Docker 1.12, that control socket was in `/var/lib/docker/swarm/control.sock`)
-
 ---
 
-class: swarmctl
+class: smarmtools
 
 ## `swarmctl` in action
 
@@ -4321,9 +4337,9 @@ class: swarmctl
 
 ---
 
-class: swarmctl
+class: swarmtools
 
-## Caveat
+## `swarmctl` notes
 
 - SwarmKit is vendored into the Docker Engine
 
@@ -4332,13 +4348,97 @@ class: swarmctl
 
 - Otherwise, you might get some errors like:
 
-```
-Error: grpc: failed to unmarshal the received message proto: wrong wireType = 0
-```
+  ```
+  Error: grpc: failed to unmarshal the received message proto: wrong wireType = 0
+  ```
+
+- With Docker 1.12, the control socket was in `/var/lib/docker/swarm/control.sock`
 
 ---
 
-class: secrets
+class: swarmtools
+
+## `swarm-rafttool`
+
+- SwarmKit stores all its important data in a distributed log using the Raft protocol
+
+  (This log is also simply called the "Raft log")
+
+- You can decode that log with `swarm-rafttool`
+
+- This is a great tool to understand how SwarmKit works
+
+- It can also be used in forensics or troubleshooting
+
+  (But consider it as a *very low level* tool!)
+
+---
+
+class: swarmtools
+
+## The powers of `swarm-rafttool`
+
+With `swarm-rafttool`, you can:
+
+- view the latest snapshot of the cluster state;
+
+- view the Raft log (i.e. changes to the cluster state);
+
+- view specific objects from the log or snapshot;
+
+- decrypt the Raft data (to analyze it with other tools).
+
+It *cannot* work on live files, so you must stop Docker or make a copy first.
+
+---
+
+class: swarmtools
+
+## Using `swarm-rafttool`
+
+- First, let's make a copy of the current Swarm data
+
+.exercise[
+
+- If you are using Play-With-Docker, the Docker data directory is `/graph`:
+  ```bash
+  cp -r /graph/swarm /swarmdata
+  ```
+
+- Otherwise, it is in the default `/var/lib/docker`:
+  ```bash
+  sudo cp -r /var/lib/docker/swarm /swarmdata
+  ```
+
+]
+
+---
+
+class: swarmtools
+
+## Dumping the Raft log
+
+- We have to indicate the path holding the Swarm data
+
+  (Otherwise `swarm-rafttool` will try to use the live data, and complain that it's locked!)
+
+.exercise[
+
+- If you are using Play-With-Docker, you must use the musl linker:
+  ```bash
+  /lib/ld-musl-x86_64.so.1 /usr/local/bin/swarm-rafttool -d /swarmdata/  dump-wal
+  ```
+
+- Otherwise, you don't need the musl linker but you need to get root:
+  ```bash
+  sudo swarm-rafttool -d /swarmdata/ dump-wal
+  ```
+
+]
+
+Reminder: this is a very low-level tool, requiring a knowledge of SwarmKit's internals!
+
+---
 
 # Secrets management and encryption at rest