Add information about kernel requirements

This page will be helpful for people who:
- want run run a custom kernel
- want to enable memory/swap accounting on Debian/Ubuntu

docs/sources/installation/index.rst

@@ -20,3 +20,4 @@ Contents:
    rackspace
    archlinux
    upgrading
+   kernel

docs/sources/installation/kernel.rst

@@ -0,0 +1,126 @@
+.. _kernel:
+
+Kernel Requirements
+===================
+
+  The officially supported kernel is the one recommended by the
+  :ref:`ubuntu_linux` installation path. It is the one that most developers
+  will use, and the one that receives the most attention from the core
+  contributors. If you decide to go with a different kernel and hit a bug,
+  please try to reproduce it with the official kernels first.
+
+If for some reason you cannot or do not want to use the "official" kernels,
+here is some technical background about the features (both optional and
+mandatory) that docker needs to run successfully.
+
+In short, you need kernel version 3.8 (or above), compiled to include
+`AUFS support <http://aufs.sourceforge.net/>`_. Of course, you need to
+enable cgroups and namespaces.
+
+
+Namespaces and Cgroups
+----------------------
+
+You need to enable namespaces and cgroups, to the extend of what is needed
+to run LXC containers. Technically, while namespaces have been introduced
+in the early 2.6 kernels, we do not advise to try any kernel before 2.6.32
+to run LXC containers. Note that 2.6.32 has some documented issues regarding
+network namespace setup and teardown; those issues are not a risk if you
+run containers in a private environment, but can lead to denial-of-service
+attacks if you want to run untrusted code in your containers. For more details,
+see `[LP#720095 <https://bugs.launchpad.net/ubuntu/+source/linux/+bug/720095>`_.
+
+Kernels 2.6.38, and every version since 3.2, have been deployed successfully
+to run containerized production workloads. Feature-wise, there is no huge
+improvement between 2.6.38 and up to 3.6 (as far as docker is concerned!).
+
+Starting with version 3.7, the kernel has basic support for
+`Checkpoint/Restore In Userspace <http://criu.org/>`_, which is not used by
+docker at this point, but allows to suspend the state of a container to
+disk and resume it later.
+
+Version 3.8 provides improvements in stability, which are deemed necessary
+for the operation of docker. Versions 3.2 to 3.5 have been shown to
+exhibit a reproducible bug (for more details, see issue
+`#407 <https://github.com/dotcloud/docker/issues/407>`_).
+
+Version 3.8 also brings better support for the
+`setns() syscall <http://lwn.net/Articles/531381/>`_ -- but this should not
+be a concern since docker does not leverage on this feature for now.
+
+If you want a technical overview about those concepts, you might
+want to check those articles on dotCloud's blog:
+`about namespaces <http://blog.dotcloud.com/under-the-hood-linux-kernels-on-dotcloud-part>`_
+and `about cgroups <http://blog.dotcloud.com/kernel-secrets-from-the-paas-garage-part-24-c>`_.
+
+
+Extra Cgroup Controllers
+------------------------
+
+Most control groups can be enabled or disabled individually. For instance,
+you can decide that you do not want to compile support for the CPU or memory
+controller. In some cases, the feature can be enabled or disabled at boot
+time. It is worth mentioning that some distributions (like Debian) disable
+"expensive" features, like the memory controller, because they can have
+a significant performance impact.
+
+In the specific case of the memory cgroup, docker will detect if the cgroup
+is available or not. If it's not, it will print a warning, and it won't
+use the feature. If you want to enable that feature -- read on!
+
+
+Memory and Swap Accounting on Debian/Ubuntu
+-------------------------------------------
+
+If you use Debian or Ubuntu kernels, and want to enable memory and swap
+accounting, you must add the following command-line parameters to your kernel::
+
+    cgroup_enable=memory swapaccount
+
+On Debian or Ubuntu systems, if you use the default GRUB bootloader, you can
+add those parameters by editing ``/etc/default/grub`` and extending
+``GRUB_CMDLINE_LINUX``. Look for the following line::
+
+    GRUB_CMDLINE_LINUX=""
+
+And replace it by the following one::
+
+    GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount"
+
+Then run ``update-grub``, and reboot.
+
+
+AUFS
+----
+
+Docker currently relies on AUFS, an unioning filesystem.
+While AUFS is included in the kernels built by the Debian and Ubuntu
+distributions, is not part of the standard kernel. This means that if
+you decide to roll your own kernel, you will have to patch your
+kernel tree to add AUFS. The process is documented on
+`AUFS webpage <http://aufs.sourceforge.net/>`_.
+
+Note: the AUFS patch is fairly intrusive, but for the record, people have
+successfully applied GRSEC and AUFS together, to obtain hardened production
+kernels.
+
+If you want more information about that topic, there is an
+`article about AUFS on dotCloud's blog 
+<http://blog.dotcloud.com/kernel-secrets-from-the-paas-garage-part-34-a>`_.
+
+
+BTRFS, ZFS, OverlayFS...
+------------------------
+
+There is ongoing development on docker, to implement support for
+`BTRFS <http://en.wikipedia.org/wiki/Btrfs>`_
+(see github issue `#443 <https://github.com/dotcloud/docker/issues/443>`_).
+
+People have also showed interest for `ZFS <http://en.wikipedia.org/wiki/ZFS>`_
+(using e.g. `ZFS-on-Linux <http://zfsonlinux.org/>`_) and OverlayFS.
+The latter is functionally close to AUFS, and it might end up being included
+in the stock kernel; so it's a strong candidate!
+
+Would you like to `contribute
+<https://github.com/dotcloud/docker/blob/master/CONTRIBUTING.md>`_
+support for your favorite filesystem?