github.com/khulnasoft/cli@v0.0.0-20240402070845-01bcad7beefa/docs/reference/commandline/checkpoint.md (about)

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