new repository

1 files changed, 30 insertions, 0 deletions

diff --git a/devdocs/docker/engine%2Freference%2Fcommandline%2Fcheckpoint%2Findex.html b/devdocs/docker/engine%2Freference%2Fcommandline%2Fcheckpoint%2Findex.html
new file mode 100644
index 00000000..fc824e94
--- /dev/null
+++ b/devdocs/docker/engine%2Freference%2Fcommandline%2Fcheckpoint%2Findex.html
@@ -0,0 +1,30 @@
+<h1>docker checkpoint</h1>  <p><br></p> <p>Manage checkpoints</p> <blockquote> <p>This command is experimental.</p> <p>This command is experimental on the Docker daemon. It should not be used in production environments. To enable experimental features on the Docker daemon, edit the <a href="../dockerd/index#daemon-configuration-file">daemon.json</a> and set <code class="language-plaintext highlighter-rouge">experimental</code> to <code class="language-plaintext highlighter-rouge">true</code>.</p>  <p>Experimental features provide early access to future product functionality. These features are intended for testing and feedback only as they may change between releases without warning or can be removed entirely from a future release. Experimental features must not be used in production environments. Docker does not offer support for experimental features.</p> </blockquote> <p>For a list of current experimental features in the Docker CLI, see <a href="https://github.com/docker/cli/blob/master/experimental/README/">Docker CLI Experimental features</a>.</p> <h2 id="usage">Usage</h2> <div class="highlight"><pre class="highlight" data-language="">$ docker checkpoint COMMAND
+</pre></div> <h2 id="description">Description</h2> <p name="extended-description">Checkpoint and Restore is an experimental 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.</p> <p>This is accomplished using a tool called <a href="https://criu.org">CRIU</a>, which is an external dependency of this feature. A good overview of the history of checkpoint and restore in Docker is available in this <a href="https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/">Kubernetes blog post</a>.</p> <h3 id="installing-criu">Installing CRIU</h3> <p>If you use a Debian system, you can add the CRIU PPA and install with <code class="language-plaintext highlighter-rouge">apt-get</code> <a href="https://launchpad.net/~criu/+archive/ubuntu/ppa">from the criu launchpad</a>.</p> <p>Alternatively, you can <a href="https://criu.org/Installation">build CRIU from source</a>.</p> <p>You need at least version 2.0 of CRIU to run checkpoint and restore in Docker.</p> <h3 id="use-cases-for-checkpoint-and-restore">Use cases for checkpoint and restore</h3> <p>This feature is currently focused on single-host use cases for checkpoint and restore. Here are a few:</p> <ul> <li>Restarting the host machine without stopping/starting containers</li> <li>Speeding up the start time of slow start applications</li> <li>“Rewinding” processes to an earlier point in time</li> <li>“Forensic debugging” of running processes</li> </ul> <p>Another primary use case of checkpoint and 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).</p> <h3 id="using-checkpoint-and-restore">Using checkpoint and restore</h3> <p>A new top level command <code class="language-plaintext highlighter-rouge">docker checkpoint</code> is introduced, with three subcommands:</p> <ul> <li>
+<code class="language-plaintext highlighter-rouge">docker checkpoint create</code> (creates a new checkpoint)</li> <li>
+<code class="language-plaintext highlighter-rouge">docker checkpoint ls</code> (lists existing checkpoints)</li> <li>
+<code class="language-plaintext highlighter-rouge">docker checkpoint rm</code> (deletes an existing checkpoint)</li> </ul> <p>Additionally, a <code class="language-plaintext highlighter-rouge">--checkpoint</code> flag is added to the <code class="language-plaintext highlighter-rouge">docker container start</code> command.</p> <p>The options for <code class="language-plaintext highlighter-rouge">docker checkpoint create</code>:</p> <div class="highlight"><pre class="highlight" data-language="">Usage:  docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT
+
+Create a checkpoint from a running container
+
+  --leave-running=false    Leave the container running after checkpoint
+  --checkpoint-dir         Use a custom checkpoint storage directory
+</pre></div> <p>And to restore a container:</p> <div class="highlight"><pre class="highlight" data-language="">Usage:  docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER
+</pre></div> <p>Example of using checkpoint and restore on a container:</p> <div class="highlight"><pre class="highlight" data-language="">$ 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
+
+# &lt;later&gt;
+$ docker start --checkpoint checkpoint1 cr
+abc0123
+</pre></div> <p>This process just logs an incrementing counter to stdout. If you run <code class="language-plaintext highlighter-rouge">docker logs</code> 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.</p> <h3 id="known-limitations">Known limitations</h3> <p>seccomp is only supported by CRIU in very up to date kernels.</p> <p>External terminal (i.e. <code class="language-plaintext highlighter-rouge">docker run -t ..</code>) is not supported at the moment. If you try to create a checkpoint for a container with an external terminal, it would fail:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker checkpoint create cr checkpoint1
+Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n"
+
+$ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log
+Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount
+</pre></div>  <h2 id="child-commands">Child commands</h2> <table> <thead> <tr> <td>Command</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td><a href="../checkpoint_create/index">docker checkpoint create</a></td> <td>Create a checkpoint from a running container</td> </tr> <tr> <td><a href="../checkpoint_ls/index">docker checkpoint ls</a></td> <td>List checkpoints for a container</td> </tr> <tr> <td><a href="../checkpoint_rm/index">docker checkpoint rm</a></td> <td>Remove a checkpoint</td> </tr> </tbody> </table> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
+    <a href="https://docs.docker.com/engine/reference/commandline/checkpoint/" class="_attribution-link">https://docs.docker.com/engine/reference/commandline/checkpoint/</a>
+  </p>
+</div>