github.com/hanks177/podman/v4@v4.1.3-0.20220613032544-16d90015bc83/docs/source/markdown/podman-container-checkpoint.1.md (about)

     1  % podman-container-checkpoint(1)
     2  
     3  ## NAME
     4  podman\-container\-checkpoint - Checkpoints one or more running containers
     5  
     6  ## SYNOPSIS
     7  **podman container checkpoint** [*options*] *container* [*container* ...]
     8  
     9  ## DESCRIPTION
    10  **podman container checkpoint** checkpoints all the processes in one or more *containers*. A *container* can be restored from a checkpoint with **[podman-container-restore](podman-container-restore.1.md)**. The *container IDs* or *names* are used as input.
    11  
    12  *IMPORTANT: If the container is using __systemd__ as __entrypoint__ checkpointing the container might not be possible.*
    13  
    14  ## OPTIONS
    15  #### **--all**, **-a**
    16  
    17  Checkpoint all running *containers*.\
    18  The default is **false**.\
    19  *IMPORTANT: This OPTION does not need a container name or ID as input argument.*
    20  
    21  #### **--compress**, **-c**=**zstd** | *none* | *gzip*
    22  
    23  Specify the compression algorithm used for the checkpoint archive created
    24  with the **--export, -e** OPTION. Possible algorithms are **zstd**, *none*
    25  and *gzip*.\
    26  One possible reason to use *none* is to enable faster creation of checkpoint
    27  archives. Not compressing the checkpoint archive can result in faster checkpoint
    28  archive creation.\
    29  The default is **zstd**.
    30  
    31  #### **--create-image**=*image*
    32  
    33  Create a checkpoint image from a running container. This is a standard OCI image
    34  created in the local image store. It consists of a single layer that contains
    35  all of the checkpoint files. The content of this image layer is in the same format as a
    36  checkpoint created with **--export**. A checkpoint image can be pushed to a
    37  standard container registry and pulled on a different system to enable container
    38  migration. In addition, the image can be exported with **podman image save** and
    39  inspected with **podman inspect**. Inspecting a checkpoint image would display
    40  additional information, stored as annotations, about the host environment used
    41  to do the checkpoint:
    42  
    43  - **io.podman.annotations.checkpoint.name**: Human-readable name of the original
    44    container.
    45  
    46  - **io.podman.annotations.checkpoint.rawImageName**: Unprocessed name of the
    47    image used to create the original container (as specified by the user).
    48  
    49  - **io.podman.annotations.checkpoint.rootfsImageID**: ID of the image used to
    50    create the original container.
    51  
    52  - **io.podman.annotations.checkpoint.rootfsImageName**: Image name used to
    53    create the original container.
    54  
    55  - **io.podman.annotations.checkpoint.podman.version**: Version of Podman used to
    56    create the checkpoint.
    57  
    58  - **io.podman.annotations.checkpoint.criu.version**: Version of CRIU used to
    59    create the checkpoint.
    60  
    61  - **io.podman.annotations.checkpoint.runtime.name**: Container runtime (e.g.,
    62    runc, crun) used to create the checkpoint.
    63  
    64  - **io.podman.annotations.checkpoint.runtime.version**: Version of the container
    65    runtime used to create the checkpoint.
    66  
    67  - **io.podman.annotations.checkpoint.conmon.version**: Version of conmon used
    68    with the original container.
    69  
    70  - **io.podman.annotations.checkpoint.host.arch**: CPU architecture of the host
    71    on which the checkpoint was created.
    72  
    73  - **io.podman.annotations.checkpoint.host.kernel**: Version of Linux kernel
    74    of the host where the checkpoint was created.
    75  
    76  - **io.podman.annotations.checkpoint.cgroups.version**: cgroup version used by
    77    the host where the checkpoint was created.
    78  
    79  - **io.podman.annotations.checkpoint.distribution.version**: Version of host
    80    distribution on which the checkpoint was created.
    81  
    82  - **io.podman.annotations.checkpoint.distribution.name**: Name of host
    83    distribution on which the checkpoint was created.
    84  
    85  #### **--export**, **-e**=*archive*
    86  
    87  Export the checkpoint to a tar.gz file. The exported checkpoint can be used
    88  to import the *container* on another system and thus enabling container live
    89  migration. This checkpoint archive also includes all changes to the *container's*
    90  root file-system, if not explicitly disabled using **--ignore-rootfs**.
    91  
    92  #### **--file-locks**
    93  
    94  Checkpoint a *container* with file locks. If an application running in the container
    95  is using file locks, this OPTION is required during checkpoint and restore. Otherwise
    96  checkpointing *containers* with file locks is expected to fail. If file locks are not
    97  used, this option is ignored.\
    98  The default is **false**.
    99  
   100  #### **--ignore-rootfs**
   101  
   102  If a checkpoint is exported to a tar.gz file it is possible with the help of **--ignore-rootfs** to explicitly disable including changes to the root file-system into the checkpoint archive file.\
   103  The default is **false**.\
   104  *IMPORTANT: This OPTION only works in combination with __--export, -e__.*
   105  
   106  #### **--ignore-volumes**
   107  
   108  This OPTION must be used in combination with the **--export, -e** OPTION.
   109  When this OPTION is specified, the content of volumes associated with
   110  the *container* will not be included into the checkpoint tar.gz file.\
   111  The default is **false**.
   112  
   113  #### **--keep**, **-k**
   114  
   115  Keep all temporary log and statistics files created by CRIU during checkpointing. These files are not deleted if checkpointing fails for further debugging. If checkpointing succeeds these files are theoretically not needed, but if these files are needed Podman can keep the files for further analysis.\
   116  The default is **false**.
   117  
   118  #### **--latest**, **-l**
   119  
   120  Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\
   121  The default is **false**.\
   122  *IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.*
   123  
   124  #### **--leave-running**, **-R**
   125  
   126  Leave the *container* running after checkpointing instead of stopping it.\
   127  The default is **false**.
   128  
   129  #### **--pre-checkpoint**, **-P**
   130  
   131  Dump the *container's* memory information only, leaving the *container* running. Later
   132  operations will supersede prior dumps. It only works on `runc 1.0-rc3` or `higher`.\
   133  The default is **false**.
   134  
   135  The functionality to only checkpoint the memory of the container and in a second
   136  checkpoint only write out the memory pages which have changed since the first
   137  checkpoint relies on the Linux kernel's soft-dirty bit, which is not available
   138  on all systems as it depends on the system architecture and the configuration
   139  of the Linux kernel. Podman will verify if the current system supports this
   140  functionality and return an error if the current system does not support it.
   141  
   142  #### **--print-stats**
   143  
   144  Print out statistics about checkpointing the container(s). The output is
   145  rendered in a JSON array and contains information about how much time different
   146  checkpoint operations required. Many of the checkpoint statistics are created
   147  by CRIU and just passed through to Podman. The following information is provided
   148  in the JSON array:
   149  
   150  - **podman_checkpoint_duration**: Overall time (in microseconds) needed to create
   151    all checkpoints.
   152  
   153  - **runtime_checkpoint_duration**: Time (in microseconds) the container runtime
   154    needed to create the checkpoint.
   155  
   156  - **freezing_time**: Time (in microseconds) CRIU needed to pause (freeze) all
   157    processes in the container (measured by CRIU).
   158  
   159  - **frozen_time**: Time (in microseconds) all processes in the container were
   160    paused (measured by CRIU).
   161  
   162  - **memdump_time**: Time (in microseconds) needed to extract all required memory
   163    pages from all container processes (measured by CRIU).
   164  
   165  - **memwrite_time**: Time (in microseconds) needed to write all required memory
   166    pages to the corresponding checkpoint image files (measured by CRIU).
   167  
   168  - **pages_scanned**: Number of memory pages scanned to determine if they need
   169    to be checkpointed (measured by CRIU).
   170  
   171  - **pages_written**: Number of memory pages actually written to the checkpoint
   172    image files (measured by CRIU).
   173  
   174  The default is **false**.
   175  
   176  #### **--tcp-established**
   177  
   178  Checkpoint a *container* with established TCP connections. If the checkpoint
   179  image contains established TCP connections, this OPTION is required during
   180  restore. Defaults to not checkpointing *containers* with established TCP
   181  connections.\
   182  The default is **false**.
   183  
   184  #### **--with-previous**
   185  
   186  Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\
   187  The default is **false**.\
   188  *IMPORTANT: This OPTION is not available with __--pre-checkpoint__*.
   189  
   190  This option requires that the option __--pre-checkpoint__ has been used before on the
   191  same container. Without an existing pre-checkpoint, this option will fail.
   192  
   193  Also see __--pre-checkpoint__ for additional information about __--pre-checkpoint__
   194  availability on different systems.
   195  
   196  ## EXAMPLES
   197  Make a checkpoint for the container "mywebserver".
   198  ```
   199  # podman container checkpoint mywebserver
   200  ```
   201  
   202  Create a checkpoint image for the container "mywebserver".
   203  ```
   204  # podman container checkpoint --create-image mywebserver-checkpoint-1 mywebserver
   205  ```
   206  
   207  Dumps the container's memory information of the latest container into an archive.
   208  ```
   209  # podman container checkpoint -P -e pre-checkpoint.tar.gz -l
   210  ```
   211  
   212  Keep the container's memory information from an older dump and add the new container's memory information.
   213  ```
   214  # podman container checkpoint --with-previous -e checkpoint.tar.gz -l
   215  ```
   216  
   217  Dump the container's memory information of the latest container into an archive with the specified compress method.
   218  ```
   219  # podman container checkpoint -l --compress=none --export=dump.tar
   220  # podman container checkpoint -l --compress=gzip --export=dump.tar.gz
   221  ```
   222  
   223  ## SEE ALSO
   224  **[podman(1)](podman.1.md)**, **[podman-container-restore(1)](podman-container-restore.1.md)**, **criu(8)**
   225  
   226  ## HISTORY
   227  September 2018, Originally compiled by Adrian Reber <areber@redhat.com>