github.com/kaisenlinux/docker.io@v0.0.0-20230510090727-ea55db55fac7/cli/docs/reference/commandline/checkpoint.md (about)

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