github.com/containers/podman/v5@v5.1.0-rc1/docs/source/markdown/podman-container-checkpoint.1.md (about)

     1  % podman-container-checkpoint 1
     2  
     3  ## NAME
     4  podman\-container\-checkpoint - Checkpoint 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 displays
    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* is not 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*. The default is **false**.
   121  *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.*
   122  
   123  #### **--leave-running**, **-R**
   124  
   125  Leave the *container* running after checkpointing instead of stopping it.\
   126  The default is **false**.
   127  
   128  #### **--pre-checkpoint**, **-P**
   129  
   130  Dump the *container's* memory information only, leaving the *container* running. Later
   131  operations supersedes prior dumps. It only works on `runc 1.0-rc3` or `higher`.\
   132  The default is **false**.
   133  
   134  The functionality to only checkpoint the memory of the container and in a second
   135  checkpoint only write out the memory pages which have changed since the first
   136  checkpoint relies on the Linux kernel's soft-dirty bit, which is not available
   137  on all systems as it depends on the system architecture and the configuration
   138  of the Linux kernel. Podman verifies if the current system supports this
   139  functionality and return an error if the current system does not support it.
   140  
   141  #### **--print-stats**
   142  
   143  Print out statistics about checkpointing the container(s). The output is
   144  rendered in a JSON array and contains information about how much time different
   145  checkpoint operations required. Many of the checkpoint statistics are created
   146  by CRIU and just passed through to Podman. The following information is provided
   147  in the JSON array:
   148  
   149  - **podman_checkpoint_duration**: Overall time (in microseconds) needed to create
   150    all checkpoints.
   151  
   152  - **runtime_checkpoint_duration**: Time (in microseconds) the container runtime
   153    needed to create the checkpoint.
   154  
   155  - **freezing_time**: Time (in microseconds) CRIU needed to pause (freeze) all
   156    processes in the container (measured by CRIU).
   157  
   158  - **frozen_time**: Time (in microseconds) all processes in the container were
   159    paused (measured by CRIU).
   160  
   161  - **memdump_time**: Time (in microseconds) needed to extract all required memory
   162    pages from all container processes (measured by CRIU).
   163  
   164  - **memwrite_time**: Time (in microseconds) needed to write all required memory
   165    pages to the corresponding checkpoint image files (measured by CRIU).
   166  
   167  - **pages_scanned**: Number of memory pages scanned to determine if they need
   168    to be checkpointed (measured by CRIU).
   169  
   170  - **pages_written**: Number of memory pages actually written to the checkpoint
   171    image files (measured by CRIU).
   172  
   173  The default is **false**.
   174  
   175  #### **--tcp-established**
   176  
   177  Checkpoint a *container* with established TCP connections. If the checkpoint
   178  image contains established TCP connections, this OPTION is required during
   179  restore. Defaults to not checkpointing *containers* with established TCP
   180  connections.\
   181  The default is **false**.
   182  
   183  #### **--with-previous**
   184  
   185  Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\
   186  The default is **false**.\
   187  *IMPORTANT: This OPTION is not available with __--pre-checkpoint__*.
   188  
   189  This option requires that the option __--pre-checkpoint__ has been used before on the
   190  same container. Without an existing pre-checkpoint, this option fails.
   191  
   192  Also see __--pre-checkpoint__ for additional information about __--pre-checkpoint__
   193  availability on different systems.
   194  
   195  ## EXAMPLES
   196  Make a checkpoint for the container "mywebserver".
   197  ```
   198  # podman container checkpoint mywebserver
   199  ```
   200  
   201  Create a checkpoint image for the container "mywebserver".
   202  ```
   203  # podman container checkpoint --create-image mywebserver-checkpoint-1 mywebserver
   204  ```
   205  
   206  Dumps the container's memory information of the latest container into an archive.
   207  ```
   208  # podman container checkpoint -P -e pre-checkpoint.tar.gz -l
   209  ```
   210  
   211  Keep the container's memory information from an older dump and add the new container's memory information.
   212  ```
   213  # podman container checkpoint --with-previous -e checkpoint.tar.gz -l
   214  ```
   215  
   216  Dump the container's memory information of the latest container into an archive with the specified compress method.
   217  ```
   218  # podman container checkpoint -l --compress=none --export=dump.tar
   219  # podman container checkpoint -l --compress=gzip --export=dump.tar.gz
   220  ```
   221  
   222  ## SEE ALSO
   223  **[podman(1)](podman.1.md)**, **[podman-container-restore(1)](podman-container-restore.1.md)**, **criu(8)**
   224  
   225  ## HISTORY
   226  September 2018, Originally compiled by Adrian Reber <areber@redhat.com>