4 files changed, 86 insertions, 35 deletions
diff --git a/g3doc/user_guide/containerd/BUILD b/g3doc/user_guide/containerd/BUILD
index 979d46105..0ede4819c 100644
--- a/g3doc/user_guide/containerd/BUILD
+++ b/g3doc/user_guide/containerd/BUILD
@@ -27,7 +27,7 @@ doc(
     name = "containerd_11",
     src = "containerd_11.md",
     category = "User Guide",
+    include_in_menu = False,
     permalink = "/docs/user_guide/containerd/containerd_11/",
     subcategory = "Containerd",
-    weight = "99",
 )
diff --git a/g3doc/user_guide/containerd/configuration.md b/g3doc/user_guide/containerd/configuration.md
index 5d485c24b..4f5e721be 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://cs.opensource.google/gvisor/gvisor/+/master:pkg/shim/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/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"
 ```
diff --git a/g3doc/user_guide/containerd/containerd_11.md b/g3doc/user_guide/containerd/containerd_11.md
index 50befbdf4..200d3da76 100644
--- a/g3doc/user_guide/containerd/containerd_11.md
+++ b/g3doc/user_guide/containerd/containerd_11.md
@@ -1,5 +1,9 @@
 # Older Versions (containerd 1.1)
 
+**WARNING: containerd 1.1 and shim v1 is no longer supported. The instructions
+below is kept just for reference in case you're dealing with an old version.
+It's highly recommended upgrading to the latest version.**
+
 This document describes how to install and run the `gvisor-containerd-shim`
 using the untrusted workload CRI extension. This requires `containerd` 1.1 or
 later.
diff --git a/g3doc/user_guide/install.md b/g3doc/user_guide/install.md
index c3ced9d61..ad0ab9923 100644
--- a/g3doc/user_guide/install.md
+++ b/g3doc/user_guide/install.md
@@ -12,16 +12,15 @@ To download and install the latest release manually follow these steps:
 ```bash
 (
   set -e
-  URL=https://storage.googleapis.com/gvisor/releases/release/latest
+  ARCH=$(uname -m)
+  URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
   wget ${URL}/runsc ${URL}/runsc.sha512 \
-    ${URL}/gvisor-containerd-shim ${URL}/gvisor-containerd-shim.sha512 \
     ${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512
   sha512sum -c runsc.sha512 \
-    -c gvisor-containerd-shim.sha512 \
     -c containerd-shim-runsc-v1.sha512
   rm -f *.sha512
-  chmod a+rx runsc gvisor-containerd-shim containerd-shim-runsc-v1
-  sudo mv runsc gvisor-containerd-shim containerd-shim-runsc-v1 /usr/local/bin
+  chmod a+rx runsc containerd-shim-runsc-v1
+  sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin
 )
 ```
 
@@ -29,7 +28,7 @@ To install gVisor as a Docker runtime, run the following commands:
 
 ```bash
 /usr/local/bin/runsc install
-sudo systemctl restart docker
+sudo systemctl reload docker
 docker run --rm --runtime=runsc hello-world
 ```
 
@@ -81,13 +80,15 @@ latest release is recommended.
 After selecting an appropriate release channel from the options below, proceed
 to the preferred installation mechanism: manual or from an `apt` repository.
 
+> Note: Older releases are still available but may not have an `${ARCH}`
+> component in the URL. These release were available for `x86_64` only.
+
 ### HEAD
 
 Binaries are available for every commit on the `master` branch, and are
 available at the following URL:
 
-`https://storage.googleapis.com/gvisor/releases/master/latest/runsc`
-`https://storage.googleapis.com/gvisor/releases/master/latest/runsc.sha512`
+`https://storage.googleapis.com/gvisor/releases/master/latest/${ARCH}`
 
 You can use this link with the steps described in
 [Install latest release](#install-latest).
@@ -103,15 +104,14 @@ sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases mast
 Nightly releases are built most nights from the master branch, and are available
 at the following URL:
 
-`https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc`
-`https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512`
+`https://storage.googleapis.com/gvisor/releases/nightly/latest/${ARCH}`
 
 You can use this link with the steps described in
 [Install latest release](#install-latest).
 
 Specific nightly releases can be found at:
 
-`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc`
+`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/${ARCH}`
 
 Note that a release may not be available for every day.
 
@@ -125,7 +125,7 @@ sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases nigh
 
 The latest official release is available at the following URL:
 
-`https://storage.googleapis.com/gvisor/releases/release/latest`
+`https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}`
 
 You can use this link with the steps described in
 [Install latest release](#install-latest).
@@ -140,7 +140,7 @@ sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases rele
 
 A given release release is available at the following URL:
 
-`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}`
+`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}/${ARCH}`
 
 You can use this link with the steps described in
 [Install latest release](#install-latest).
@@ -161,7 +161,7 @@ sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases yyyy
 
 A given point release is available at the following URL:
 
-`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}`
+`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}/${ARCH}`
 
 You can use this link with the steps described in
 [Install latest release](#install-latest).