Edits to user guide + added filesystem section

6 files changed, 105 insertions, 21 deletions

diff --git a/content/docs/user_guide/FAQ.md b/content/docs/user_guide/FAQ.md
index 167933f9f..5e166ace3 100644
--- a/content/docs/user_guide/FAQ.md
+++ b/content/docs/user_guide/FAQ.md
@@ -20,12 +20,13 @@ not realize a new file was copied to a given directory. To invalidate the cache
 and force a refresh, create a file under the directory in question and list the
 contents again.
 
+As a workaround, shared root filesystem can be enabled. See [Filesystem](../filesystem/).
+
 This bug is tracked in [bug #4](https://github.com/google/gvisor/issues/4).
 
 Note that `kubectl cp` works because it does the copy by exec'ing inside the
-sandbox, and thus gVisor cache is aware of the new files and dirs.
-
-There are also different filesystem modes that can be used to avoid this issue.
+sandbox, and thus gVisor's internal cache is made aware of the new files and
+directories.
 
 ### What's the security model?
 
diff --git a/content/docs/user_guide/debugging.md b/content/docs/user_guide/debugging.md
index f8a5999fd..c6f5cc772 100644
--- a/content/docs/user_guide/debugging.md
+++ b/content/docs/user_guide/debugging.md
@@ -21,6 +21,10 @@ To enable debug and system call logging, add the `runtimeArgs` below to your
 }
 ```
 
+> Note: the last `/` in `--debug-log` is needed to interpret it as a directory.
+> Then each `runsc` command executed will create a separate log file.
+> Otherwise, log messages from all commands will be appended to the same file.
+
 You may also want to pass `--log-packets` to troubleshoot network problems. Then
 restart the Docker daemon:
 
@@ -29,8 +33,10 @@ sudo systemctl restart docker
 ```
 
 Run your container again, and inspect the files under `/tmp/runsc`. The log file
-with name `boot` will contain the strace logs from your application, which can
-be useful for identifying missing or broken system calls in gVisor.
+ending with `.boot` will contain the strace logs from your application, which can
+be useful for identifying missing or broken system calls in gVisor. If you are
+having problems starting the container, the log file ending with `.create` may
+have the reason for the failure.
 
 ## Stack traces
 
@@ -46,7 +52,7 @@ docker run --runtime=runsc --rm -d alpine sh -c "while true; do echo running; sl
 sudo runsc --root /var/run/docker/runtime-runsc/moby debug --stacks 63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b
 ```
 
-> Note: `--root` variable is provided by docker and is normally set to 
+> Note: `--root` variable is provided by docker and is normally set to
 > `/var/run/docker/runtime-[runtime-name]/moby`. If in doubt, `--root` is logged to
 > `runsc` logs.
 
diff --git a/content/docs/user_guide/docker.md b/content/docs/user_guide/docker.md
index c42a320e3..78c1271b1 100644
--- a/content/docs/user_guide/docker.md
+++ b/content/docs/user_guide/docker.md
@@ -3,7 +3,7 @@ title = "Docker Quick Start"
 weight = 10
 +++
 This guide will help you quickly get started running Docker containers using
-gVisor with the default platform.
+gVisor.
 
 ## Install gVisor
 
@@ -43,13 +43,19 @@ sudo systemctl restart docker
 Now run your container using the `runsc` runtime:
 
 ```bash
-docker run --runtime=runsc hello-world
+docker run --runtime=runsc --rm hello-world
 ```
 
 You can also run a terminal to explore the container.
 
 ```bash
-docker run --runtime=runsc -it ubuntu /bin/bash
+docker run --runtime=runsc --rm -it ubuntu /bin/bash
+```
+
+Many docker options are compatible with gVisor, try them out. Here is an example:
+
+```bash
+docker run --runtime=runsc --rm --link backend:database -v ~/bin:/tools:ro -p 8080:80 --cpus=0.5 -it busybox telnet towel.blinkenlights.nl
 ```
 
 ## Verify the runtime
@@ -75,7 +81,8 @@ $ docker run --runtime=runsc -it ubuntu dmesg
 Note that this is easily replicated by an attacker so applications should never
 use `dmesg` to verify the runtime in a security sensitive context.
 
-Next, try running gVisor using the [KVM platform](../platforms/).
+Next, look at the different options available for gVisor: [platform](../platforms/),
+[network](../networking/), [filesystem](../filesystem/).
 
 [docker]: https://docs.docker.com/install/
 [storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver
diff --git a/content/docs/user_guide/filesystem.md b/content/docs/user_guide/filesystem.md
new file mode 100644
index 000000000..e0a038007
--- /dev/null
+++ b/content/docs/user_guide/filesystem.md
@@ -0,0 +1,59 @@
++++
+title = "Filesystem"
+weight = 45
++++
+gVisor accesses the filesystem through a file proxy, called the Gofer. The gofer
+runs as a separate process, that is isolated from the sandbox. Gofer instances
+communicate with their respective sentry using the 9P protocol. For a more detailed
+explanation see [Overview > Gofer](../../architecture_guide/overview/#gofer).
+
+## Sandbox overlay
+
+To isolate the host filesystem from the sandbox, you can set a writable tmpfs overlay
+on top of the entire filesystem. All modifications are made to the overlay, keeping
+the host filesystem unmodified.
+
+> Note: All created and modified files are stored in memory inside the sandbox.
+
+To use the tmpfs overlay, add the following `runtimeArgs` to your Docker configuration
+(`/etc/docker/daemon.json`) and restart the Docker daemon:
+
+```json
+{
+    "runtimes": {
+        "runsc": {
+            "path": "/usr/local/bin/runsc",
+            "runtimeArgs": [
+                "--overlay"
+            ]
+       }
+    }
+}
+```
+
+## Shared root filesystem
+
+The root filesystem is where the image is extracted and is not generally modified
+from outside the sandbox. This allows for some optimizations, like skipping checks
+to determine if a directory has changed since the last time it was cached, thus
+missing updates that may have happened. If you need to `docker cp` files inside the
+root filesystem, you may want to enable shared mode. Just be aware that file system
+access will be slower due to the extra checks that are required.
+
+> Note: External mounts are always shared.
+
+To use set the root filesystem shared, add the following `runtimeArgs` to your Docker
+configuration (`/etc/docker/daemon.json`) and restart the Docker daemon:
+
+```json
+{
+    "runtimes": {
+        "runsc": {
+            "path": "/usr/local/bin/runsc",
+            "runtimeArgs": [
+                "--file-access=shared"
+            ]
+       }
+    }
+}
+```
diff --git a/content/docs/user_guide/networking.md b/content/docs/user_guide/networking.md
index 83e75aaf2..f1aa77625 100644
--- a/content/docs/user_guide/networking.md
+++ b/content/docs/user_guide/networking.md
@@ -8,14 +8,19 @@ state, control messages, and packet assembly — keeping it isolated from the ho
 network stack. Data link layer packets are written directly to the virtual
 device inside the network namespace setup by Docker or Kubernetes.
 
-A network passthrough mode is also supported, but comes at the cost of reduced
-isolation.
+The IP address and routes configured for the device are transferred inside the
+sandbox. The loopback device runs exclusively inside the sandbox and does not
+use the host. You can inspect them by running:
 
-## Enabling network passthrough
+```bash
+docker run --rm --runtime=runsc alpine ip addr
+```
+
+## Network passthrough
 
 For high-performance networking applications, you may choose to disable the user
-space network stack and instead use the host network stack. Note that this mode
-decreases the isolation to the host.
+space network stack and instead use the host network stack, including the loopback.
+Note that this mode decreases the isolation to the host.
 
 Add the following `runtimeArgs` to your Docker configuration
 (`/etc/docker/daemon.json`) and restart the Docker daemon:
diff --git a/content/docs/user_guide/platforms.md b/content/docs/user_guide/platforms.md
index 5a43ad897..e15072068 100644
--- a/content/docs/user_guide/platforms.md
+++ b/content/docs/user_guide/platforms.md
@@ -14,9 +14,10 @@ more depth in the [Architecture Guide](../../architecture_guide/).
 
 ## Selecting a Platform
 
-The platform is selected by a `--platform` command line flag passed to `runsc`.
-To select a different platform, modify your Docker configuration
-(`/etc/docker/daemon.json`) to pass this argument:
+The platform is selected by the `--platform` command line flag passed to
+`runsc`. By default, the ptrace platform is selected. To select a different
+platform, modify your Docker configuration (`/etc/docker/daemon.json`) to
+pass this argument:
 
 ```json
 {
@@ -31,7 +32,12 @@ To select a different platform, modify your Docker configuration
 }
 ```
 
-Then restart the Docker daemon.
+You must restart the Docker daemon after making changes to this file, typically
+this is done via `systemd`:
+
+```bash
+sudo systemctl restart docker
+```
 
 ## Example: Using the KVM Platform
 
@@ -50,7 +56,7 @@ sudo apt-get install qemu-kvm
 
 If you are using a virtual machine you will need to make sure that nested
 virtualization is configured. Here are links to documents on how to set up
-nested virtualization in several popular environments.
+nested virtualization in several popular environments:
 
  * Google Cloud: [Enabling Nested Virtualization for VM Instances][nested-gcp]
  * Microsoft Azure: [How to enable nested virtualization in an Azure VM][nested-azure]
@@ -99,7 +105,7 @@ Now run your container using the `runsc-kvm` runtime. This will run the
 container using the KVM platform:
 
 ```bash
-docker run --runtime=runsc-kvm hello-world
+docker run --runtime=runsc-kvm --rm hello-world
 ```
 
 [nested-azure]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization