1podman-container-checkpoint(1G)eneral Commands Manupaoldman-container-checkpoint(1)
2
3
4

NAME

6       podman-container-checkpoint - Checkpoint one or more running containers
7
8

SYNOPSIS

10       podman container checkpoint [options] container [container ...]
11
12

DESCRIPTION

14       podman  container  checkpoint  checkpoints  all the processes in one or
15       more containers. A container can be restored  from  a  checkpoint  with
16       podman-container-restore. The container IDs or names are used as input.
17
18
19       IMPORTANT:  If the container is using systemd as entrypoint checkpoint‐
20       ing the container might not be possible.
21
22

OPTIONS

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

EXAMPLES

233       Make a checkpoint for the container "mywebserver".
234
235       # podman container checkpoint mywebserver
236
237
238
239       Create a checkpoint image for the container "mywebserver".
240
241       # podman container checkpoint --create-image mywebserver-checkpoint-1 mywebserver
242
243
244
245       Dumps the container's memory information of the latest  container  into
246       an archive.
247
248       # podman container checkpoint -P -e pre-checkpoint.tar.gz -l
249
250
251
252       Keep  the container's memory information from an older dump and add the
253       new container's memory information.
254
255       # podman container checkpoint --with-previous -e checkpoint.tar.gz -l
256
257
258
259       Dump the container's memory information of the latest container into an
260       archive with the specified compress method.
261
262       # podman container checkpoint -l --compress=none --export=dump.tar
263       # podman container checkpoint -l --compress=gzip --export=dump.tar.gz
264
265
266

SEE ALSO

268       podman(1), podman-container-restore(1), criu(8)
269
270

HISTORY

272       September  2018,  Originally compiled by Adrian Reber areber@redhat.com
273       ⟨mailto:areber@redhat.com⟩
274
275
276
277                                                podman-container-checkpoint(1)
Impressum