1 files changed, 67 insertions, 20 deletions
diff --git a/g3doc/user_guide/containerd/configuration.md b/g3doc/user_guide/containerd/configuration.md
index 558050bbc..bb65aa514 100644
--- a/g3doc/user_guide/containerd/configuration.md
+++ b/g3doc/user_guide/containerd/configuration.md
@@ -4,41 +4,56 @@ This document describes how to configure runtime options for
 `containerd-shim-runsc-v1`. This follows the
 [Containerd Quick Start](./quick_start.md) and requires containerd 1.2 or later.
 
-### Update `/etc/containerd/config.toml` to point to a configuration file for `containerd-shim-runsc-v1`.
+## Shim Configuration
 
-`containerd-shim-runsc-v1` supports a few different configuration options based
-on the version of containerd that is used. For versions >= 1.3, it supports a
-configurable `ConfigPath` in the containerd runtime configuration.
+The shim can be provided with a configuration file containing options to the
+shim itself as well as a set of flags to runsc. Here is a quick example:
+
+```shell
+cat <<EOF | sudo tee /etc/containerd/runsc.toml
+option = "value"
+[runsc_config]
+  flag = "value"
+```
+
+The set of options that can be configured can be found in
+[options.go](https://github.com/google/gvisor/blob/master/pkg/shim/v2/options.go).
+Values under `[runsc_config]` can be used to set arbitrary flags to runsc.
+`flag = "value"` is converted to `--flag="value"` when runsc is invoked. Run
+`runsc flags` so see which flags are available
+
+Next, containerd needs to be configured to send the configuration file to the
+shim.
+
+### Containerd 1.3+
+
+Starting in 1.3, containerd supports a configurable `ConfigPath` in the runtime
+configuration. Here is an example:
 
 ```shell
 cat <<EOF | sudo tee /etc/containerd/config.toml
 disabled_plugins = ["restart"]
-[plugins.linux]
-  shim_debug = true
 [plugins.cri.containerd.runtimes.runsc]
   runtime_type = "io.containerd.runsc.v1"
 [plugins.cri.containerd.runtimes.runsc.options]
   TypeUrl = "io.containerd.runsc.v1.options"
-  # containerd 1.3 only!
   ConfigPath = "/etc/containerd/runsc.toml"
 EOF
 ```
 
-When you are done restart containerd to pick up the new configuration files.
+When you are done, restart containerd to pick up the changes.
 
 ```shell
 sudo systemctl restart containerd
 ```
 
-### Configure `/etc/containerd/runsc.toml`
+### Containerd 1.2
 
-> Note: For containerd 1.2, the config file should named `config.toml` and
-> located in the runtime root. By default, this is `/run/containerd/runsc`.
+For containerd 1.2, the config file is not configurable. It should be named
+`config.toml` and located in the runtime root. By default, this is
+`/run/containerd/runsc`.
 
-The set of options that can be configured can be found in
-[options.go](https://github.com/google/gvisor/blob/master/pkg/shim/v2/options.go).
-
-#### Example: Enable the KVM platform
+### Example: Enable the KVM platform
 
 gVisor enables the use of a number of platforms. This example shows how to
 configure `containerd-shim-runsc-v1` to use gvisor with the KVM platform.
@@ -49,11 +64,42 @@ Find out more about platform in the
 ```shell
 cat <<EOF | sudo tee /etc/containerd/runsc.toml
 [runsc_config]
-platform = "kvm"
+  platform = "kvm"
+EOF
+```
+
+## Debug
+
+When `shim_debug` is enabled in `/etc/containerd/config.toml`, containerd will
+forward shim logs to its own log. You can additionally set `level = "debug"` to
+enable debug logs. To see the logs run `sudo journalctl -u containerd`. Here is
+a containerd configuration file that enables both options:
+
+```shell
+cat <<EOF | sudo tee /etc/containerd/config.toml
+disabled_plugins = ["restart"]
+[debug]
+  level = "debug"
+[plugins.linux]
+  shim_debug = true
+[plugins.cri.containerd.runtimes.runsc]
+  runtime_type = "io.containerd.runsc.v1"
+[plugins.cri.containerd.runtimes.runsc.options]
+  TypeUrl = "io.containerd.runsc.v1.options"
+  ConfigPath = "/etc/containerd/runsc.toml"
 EOF
 ```
 
-### Example: Enable gVisor debug logging
+It can be hard to separate containerd messages from the shim's though. To create
+a log file dedicated to the shim, you can set the `log_path` and `log_level`
+values in the shim configuration file:
+
+-   `log_path` is the directory where the shim logs will be created. `%ID%` is
+    the path is replaced with the container ID.
+-   `log_level` sets the logs level. It is normally set to "debug" as there is
+    not much interesting happening with other log levels.
+
+### Example: Enable shim and gVisor debug logging
 
 gVisor debug logging can be enabled by setting the `debug` and `debug-log` flag.
 The shim will replace "%ID%" with the container ID, and "%COMMAND%" with the
@@ -63,8 +109,9 @@ Find out more about debugging in the [debugging guide](../debugging.md).
 
 ```shell
 cat <<EOF | sudo tee /etc/containerd/runsc.toml
+log_path = "/var/log/runsc/%ID%/shim.log"
+log_level = "debug"
 [runsc_config]
-  debug=true
-  debug-log=/var/log/%ID%/gvisor.%COMMAND%.log
-EOF
+  debug = "true"
+  debug-log = "/var/log/runsc/%ID%/gvisor.%COMMAND%.log"
 ```