<!-- markdownlint-disable MD033 --> <!-- markdownlint-disable MD041 --> <p1 align="center"> <img src="docs/checkpointctl.svg" height="250" alt="checkpointctl logo"> </p> <!-- markdownlint-disable MD013 -->

checkpointctl - a tool for in-depth analysis of container checkpoints

Container engines like Podman and CRI-O have the ability to checkpoint a container. All data related to a checkpoint is collected in a checkpoint archive. With the help of this tool, checkpointctl, it is possible to display information about these checkpoint archives.

Details on how to create checkpoints with the help of [CRIU][criu] can be found at:

• [Forensic container checkpointing in Kubernetes][forensic]
• [Podman checkpoint][podman]

Usage

show sub-command

To display an overview of a checkpoint archive you can just use checkpointctl show:

$ checkpointctl show /tmp/dump.tar

Displaying container checkpoint data from /tmp/dump.tar

CONTAINER   IMAGE                              ID             RUNTIME   CREATED                ENGINE   CHKPT SIZE   ROOT FS DIFF SIZE
---------   -----                              --             -------   -------                ------   ----------   -----------------
looper      docker.io/library/busybox:latest   8b5c2ca15082   crun      2021-09-28T10:03:56Z   Podman   130.8 KiB    204 B

For a checkpoint archive created by Kubernetes with CRI-O the output would look like this:

$ checkpointctl show /var/lib/kubelet/checkpoints/checkpoint-checkpoint-test_default-checkpoint-test-2026-03-13T21:43:06Z.tar

Displaying container checkpoint data from /var/lib/kubelet/checkpoints/checkpoint-checkpoint-test_default-checkpoint-test-2026-03-13T21:43:06Z.tar

CONTAINER         IMAGE                              ID             RUNTIME   CREATED                         ENGINE   CHKPT SIZE   ROOT FS DIFF SIZE
---------         -----                              --             -------   -------                         ------   ----------   -----------------
checkpoint-test   docker.io/library/busybox:latest   68bb2fa6a176   crun      2026-03-13T21:42:59.05135916Z   CRI-O    314.6 KiB    3.5 KiB

inspect sub-command

To retrieve low-level information about a container checkpoint, use the checkpointctl inspect command:

Displaying container checkpoint tree view from /tmp/ubuntu_looper.tar.gz

awesome_booth
├── Image: docker.io/library/ubuntu:latest
├── ID: 2076a99c49c959375c6ae406818a2c841744a019d30221f134db657232f133f5
├── Runtime: crun
├── Created: 2026-03-16T08:00:17Z
├── Engine: Podman
├── Network Interfaces
│   └── podman (eth0)
│       ├── IP: 10.88.0.4/16
│       ├── MAC: 2e:e1:db:6b:68:93
│       └── Gateway: 10.88.0.1
├── Checkpoint size: 1018.3 KiB
│   └── Memory pages size: 952.0 KiB
├── Root FS diff size: 2.0 KiB
└── Process tree
    └── [1]  bash
        └── [4]  su
            └── [5]  bash
                └── [6]  sleep

For a complete list of flags supported, use checkpointctl inspect --help.

diff sub-command

To compare two container checkpoints and analyze changes between them, use the checkpointctl diff command.

$ checkpointctl diff checkpoint1.tar checkpoint2.tar

╔════════════════════════════════════════════════════════════════╗
║ Checkpoint Diff                                                ║
╠════════════════════════════════════════════════════════════════╣
║ Container: web-server                                          ║
║ Image:     docker.io/library/nginx:latest                      ║
╚════════════════════════════════════════════════════════════════╝

Checkpoint A:
  Created: 2026-02-15T10:00:00Z
  Size:    2.1 MiB

Checkpoint B:
  Created: 2026-02-15T10:05:00Z
  Size:    2.3 MiB

┌─ Memory Changes ─────────────────────────────────────────────┐
│ ↑ Increased by 0.15 MB
└──────────────────────────────────────────────────────────────┘

┌─ Process Changes ────────────────────────────────────────────┐
│ Added:
│   + PID 42    xmrig
│ Unchanged: 3
└──────────────────────────────────────────────────────────────┘

Summary:
Checkpoint comparison for container web-server
Processes: +1 -0 ~0
Memory: +0.15 MB

memparse sub-command

To perform memory analysis of container checkpoints, you can use the checkpointctl memparse command.

$ checkpointctl memparse /tmp/jira.tar.gz  --pid=1 | less

Displaying memory pages content for Process ID 1 from checkpoint: /tmp/jira.tar.gz

ADDRESS           HEXADECIMAL                                       ASCII
-------------------------------------------------------------------------------------
00005633bb080000  f3 0f 1e fa 48 83 ec 08 48 8b 05 d1 4f 00 00 48  |....H...H...O..H|
00005633bb080010  85 c0 74 02 ff d0 48 83 c4 08 c3 00 00 00 00 00  |..t...H.........|
00005633bb080020  ff 35 b2 4e 00 00 f2 ff 25 b3 4e 00 00 0f 1f 00  |.5.N....%.N.....|
00005633bb080030  f3 0f 1e fa 68 00 00 00 00 f2 e9 e1 ff ff ff 90  |....h...........|
*
00005633bb0800a0  f3 0f 1e fa 68 07 00 00 00 f2 e9 71 ff ff ff 90  |....h......q....|
00005633bb0800b0  f3 0f 1e fa 68 08 00 00 00 f2 e9 61 ff ff ff 90  |....h......a....|
00005633bb0800c0  f3 0f 1e fa 68 09 00 00 00 f2 e9 51 ff ff ff 90  |....h......Q....|
00005633bb0800d0  f3 0f 1e fa 68 0a 00 00 00 f2 e9 41 ff ff ff 90  |....h......A....|
00005633bb0800e0  f3 0f 1e fa 68 0b 00 00 00 f2 e9 31 ff ff ff 90  |....h......1....|

Here's an example of memory analysis of a PostgreSQL container. In this case, we start a PostgreSQL container with a password set to 'mysecret'. Then, we create a checkpoint of the container and use the memparse to find the stored password.

$ sudo podman run --name postgres -e POSTGRES_PASSWORD=mysecret -d postgres
$ sudo podman container checkpoint -l --export=/tmp/postgres.tar.gz
$ sudo checkpointctl memparse --pid 1 /tmp/postgres.tar.gz | grep -B 1 -A 1 mysecret
000055dd725c1e60  50 4f 53 54 47 52 45 53 5f 50 41 53 53 57 4f 52  |POSTGRES_PASSWOR|
000055dd725c1e70  44 3d 6d 79 73 65 63 72 65 74 00 00 00 00 00 00  |D=mysecret......|
000055dd725c1e80  00 00 00 00 00 00 00 00 31 00 00 00 00 00 00 00  |........1.......|

Here's another scenario, of memory analysis for a web application container. We start a vulnerable web application container, perform an arbitrary code execution attack, create a checkpoint for forensic analysis while leaving the container running, and finally analyze the checkpoint memory to identify the injected code.

# Start vulnerable web application
$ sudo podman run --name dsvw -p 1234:8000 -d quay.io/rst0git/dsvw

# Perform arbitrary code execution attack: $(echo secret)
$ curl "http://localhost:1234/?domain=www.google.com%3B%20echo%20secret"
nslookup: can't resolve '(null)': Name does not resolve

Name:      www.google.com
Address 1: 142.250.187.228 lhr25s34-in-f4.1e100.net
Address 2: 2a00:1450:4009:820::2004 lhr25s34-in-x04.1e100.net
secret

# Create a checkpoint for forensic analysis and leave the container running
$ sudo podman container checkpoint --leave-running -l -e /tmp/dsvw.tar

# Analyse checkpoint memory to identify the attacker's injected code
$ sudo checkpointctl memparse --pid 1 /tmp/dsvw.tar | grep 'echo secret'
00007faac5711f60  6f 6d 3b 20 65 63 68 6f 20 73 65 63 72 65 74 00  |om; echo secret.|

For larger processes, it's recommended to write the contents of process memory pages to a file rather than standard output.

To get an overview of process memory sizes within the checkpoint, run checkpointctl memparse without arguments.

$ sudo checkpointctl memparse /tmp/jira.tar.gz

Displaying processes memory sizes from /tmp/jira.tar.gz

PID  PROCESS NAME  MEMORY SIZE  SHARED MEMORY SIZE
---  ------------  -----------  ------------------
1    tini          100.0 KiB    0 B
2    java          553.5 MiB    0 B

In this example, given the large size of the java process, it is better to write its output to a file.

$ sudo checkpointctl memparse --pid=2 /tmp/jira.tar.gz --output=/tmp/java-memory-pages.txt
Writing memory pages content for process ID 2 from checkpoint: /tmp/jira.tar.gz to file: /tmp/java-memory-pages.txt...

Please note that writing large memory pages to a file can take several minutes.

build sub-command

Restoring a container from a checkpoint in Kubernetes requires converting the checkpoint archive into an OCI image. The build command simplifies this process by extracting the necessary metadata from the checkpoint and creating an OCI-compatible image with appropriate annotations.

Example:

checkpointctl build ./checkpoint.tar quay.io/foo/bar:latest
buildah push quay.io/foo/bar:latest

In this example, the checkpointctl build command converts the checkpoint.tar archive into an OCI-compatible image and tags it as quay.io/foo/bar:latest. The following buildah push command then uploads the newly created OCI image to the container registry, making it available for deployment.

plugin sub-command

The plugin sub-command manages external plugins that extend checkpointctl with additional subcommands. Plugins are standalone executables in PATH with names matching the pattern checkpointctl-<name>.

$ checkpointctl plugin list
Available plugins:
  hello                My custom plugin description
                       /usr/local/bin/checkpointctl-hello

This plugin architecture allows extending checkpointctl functionality without increasing the binary size of the core tool. Plugins with larger dependencies can be distributed separately, and can be implemented in any programming language.