github.com/endophage/docker@v1.4.2-0.20161027011718-242853499895/experimental/checkpoint-restore.md (about)

     1  # Docker Checkpoint & Restore
     2  
     3  Checkpoint & Restore is a new feature that allows you to freeze a running
     4  container by checkpointing it, which turns its state into a collection of files
     5  on disk. Later, the container can be restored from the point it was frozen.
     6  
     7  This is accomplished using a tool called [CRIU](http://criu.org), which is an
     8  external dependency of this feature. A good overview of the history of
     9  checkpoint and restore in Docker is available in this
    10  [Kubernetes blog post](http://blog.kubernetes.io/2015/07/how-did-quake-demo-from-dockercon-work.html).
    11  
    12  ## Installing CRIU
    13  
    14  If you use a Debian system, you can add the CRIU PPA and install with apt-get
    15  [from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa).
    16  
    17  Alternatively, you can [build CRIU from source](http://criu.org/Installation).
    18  
    19  You need at least version 2.0 of CRIU to run checkpoint/restore in Docker.
    20  
    21  ## Use cases for checkpoint & restore
    22  
    23  This feature is currently focused on single-host use cases for checkpoint and
    24  restore. Here are a few:
    25  
    26  - Restarting the host machine without stopping/starting containers
    27  - Speeding up the start time of slow start applications
    28  - "Rewinding" processes to an earlier point in time
    29  - "Forensic debugging" of running processes
    30  
    31  Another primary use case of checkpoint & restore outside of Docker is the live
    32  migration of a server from one machine to another. This is possible with the
    33  current implementation, but not currently a priority (and so the workflow is
    34  not optimized for the task).
    35  
    36  ## Using Checkpoint & Restore
    37  
    38  A new top level command `docker checkpoint` is introduced, with three subcommands:
    39  - `create` (creates a new checkpoint)
    40  - `ls` (lists existing checkpoints)
    41  - `rm` (deletes an existing checkpoint)
    42  
    43  Additionally, a `--checkpoint` flag is added to the container start command.
    44  
    45  The options for checkpoint create:
    46  
    47      Usage:  docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT
    48  
    49      Create a checkpoint from a running container
    50  
    51        --leave-running=false    leave the container running after checkpoint
    52  
    53  And to restore a container:
    54  
    55      Usage:  docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER
    56  
    57  
    58  A simple example of using checkpoint & restore on a container:
    59  
    60      $ 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'
    61      > abc0123
    62  
    63      $ docker checkpoint create cr checkpoint1
    64  
    65      # <later>
    66      $ docker start --checkpoint checkpoint1 cr
    67      > abc0123
    68  
    69  This process just logs an incrementing counter to stdout. If you `docker logs`
    70  in between running/checkpoint/restoring you should see that the counter
    71  increases while the process is running, stops while it's checkpointed, and
    72  resumes from the point it left off once you restore.
    73  
    74  ## Current Limitation
    75  
    76  seccomp is only supported by CRIU in very up to date kernels.
    77  
    78  External terminal (i.e. `docker run -t ..`) is not supported at the moment.
    79  If you try to create a checkpoint for a container with an external terminal, 
    80  it would fail:
    81  
    82      $ docker checkpoint create cr checkpoint1
    83      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"
    84      
    85      $ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log
    86      Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount
    87