Initial implementation of containerd Checkpoint API.

Signed-off-by: boucher <rboucher@gmail.com>

experimental/README.md

@@ -2,7 +2,7 @@
 
 This page contains a list of features in the Docker engine which are
 experimental. Experimental features are **not** ready for production. They are
-provided for test and evaluation in your sandbox environments.  
+provided for test and evaluation in your sandbox environments.
 
 The information below describes each feature and the GitHub pull requests and
 issues associated with it. If necessary, links are provided to additional
@@ -74,9 +74,10 @@ to build a Docker binary with the experimental features enabled:
  * [External graphdriver plugins](plugins_graphdriver.md)
  * [Macvlan and Ipvlan Network Drivers](vlan-networks.md)
  * [Docker Stacks and Distributed Application Bundles](docker-stacks-and-bundles.md)
+ * [Checkpoint & Restore](checkpoint-restore.md)
 
 ## How to comment on an experimental feature
 
-Each feature's documentation includes a list of proposal pull requests or PRs associated with the feature. If you want to comment on or suggest a change to a feature, please add it to the existing feature PR.  
+Each feature's documentation includes a list of proposal pull requests or PRs associated with the feature. If you want to comment on or suggest a change to a feature, please add it to the existing feature PR.
 
-Issues or problems with a feature? Inquire for help on the `#docker` IRC channel or in on the [Docker Google group](https://groups.google.com/forum/#!forum/docker-user).  
+Issues or problems with a feature? Inquire for help on the `#docker` IRC channel or in on the [Docker Google group](https://groups.google.com/forum/#!forum/docker-user).

experimental/checkpoint-restore.md

@@ -0,0 +1,75 @@
+# Docker Checkpoint & Restore
+
+Checkpoint & Restore is a new feature that allows you to freeze a running
+container by checkpointing it, which turns its state into a collection of files
+on disk. Later, the container can be restored from the point it was frozen.
+
+This is accomplished using a tool called [CRIU](http://criu.org), which is an
+external dependency of this feature. A good overview of the history of
+checkpoint and restore in Docker is available in this
+[Kubernetes blog post](http://blog.kubernetes.io/2015/07/how-did-quake-demo-from-dockercon-work.html).
+
+## Installing CRIU
+
+If you use a Debian system, you can add the CRIU PPA and install with apt-get
+[from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa).
+
+Alternatively, you can [build CRIU from source](http://criu.org/Installation).
+
+You need at least version 2.0 of CRIU to run checkpoint/restore in Docker.
+
+## Use cases for checkpoint & restore
+
+This feature is currently focused on single-host use cases for checkpoint and
+restore. Here are a few:
+
+- Restarting the host machine without stopping/starting containers
+- Speeding up the start time of slow start applications
+- "Rewinding" processes to an earlier point in time
+- "Forensic debugging" of running processes
+
+Another primary use case of checkpoint & restore outside of Docker is the live
+migration of a server from one machine to another. This is possible with the
+current implementation, but not currently a priority (and so the workflow is
+not optimized for the task).
+
+## Using Checkpoint & Restore
+
+A new top level commands `docker checkpoint` is introduced, with three subcommands:
+- `create` (creates a new checkpoint)
+- `ls` (lists existing checkpoints)
+- `rm` (deletes an existing checkpoint)
+
+Additionally, a `--checkpoint` flag is added to the container start command.
+
+The options for checkpoint create:
+
+    Usage:  docker checkpoint [OPTIONS] CONTAINER CHECKPOINT_ID
+
+    Checkpoint the specified container
+
+      --leave-running=false    leave the container running after checkpoint
+
+And to restore a container:
+
+    Usage:  docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER
+
+
+A simple example of using checkpoint & restore on a container:
+
+    $ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done'
+    > abc0123
+
+    $ docker checkpoint create cr checkpoint1
+
+    # <later>
+    $ docker start --checkpoint checkpoint1 cr
+    > abc0123
+
+This process just logs an incrementing counter to stdout. If you `docker logs`
+in between running/checkpoint/restoring you should see that the counter
+increases while the process is running, stops while it's checkpointed, and
+resumes from the point it left off once you restore.
+
+Note that seccomp is only supported by CRIU in very up to date kernels.
+