Images
The criu utility dumps the state of processes/containers into a set of image files. This article describes the format of them.
|
Note: You might also want to checkout our image tool called CRIT |
Types of image files
CRIU images can be in one of formats
- criu specific images in google protocol buffer format (PB format)
- criu specific images with binary data in it
- image files in 3rd party format (a.k.a. raw images)
Images in criu-specific format
All criu-specific image files begin with 32-bit magic cookie. Images in PB format are followed by zero or more entries of the same type (not size!), each entry is preceded with 32-bit entry size value (not including this 32-bit value itself). Optionally each entry may be followed by extra payload which depends on the entry type.
IOW protocol-buffers image files look like
IMAGE_FILE ::= MAGIC { ENTRY }
ENTRY ::= SIZE PAYLOAD [ EXTRA ]
PAYLOAD ::= "message encoded in ProtocolBuffer format"
EXTRA ::= "arbitrary blob, depends on the PAYLOAD contents"
MAGIC ::= "32 bit integer"
SIZE ::= "32 bit integer, equals the PAYLOAD length"
Or, you can visualize it like
| Type | Size(bytes) |
|---|---|
| Magic | 4 |
| Size0 | 4 |
| Message0 | Size0 |
| ... | ... |
| SizeN | 4 |
| MessageN | SizeN |
The amount of entries in a image file depends on the type of file.
Images with PB data
Such images can be one of
- Array image files
- In these files the amount of entries can be any. You should read the image file up to the EOF to find out the exact number.
- Single-entry image files
- In these files exactly one entry is stored.
A file type can be guessed by the magic. The description of the entries in ProtocolBuffers language are in respective .proto files which reside in protobuf/ directory in the source tree.
| name | type | description | extra payload | describing proto file |
|---|---|---|---|---|
| inventory | single-entry | Top level description of images | - | inventory.proto |
| fdinfo | array | Open file descriptors | - | fdinfo.proto |
| reg-files | array | Paths to files opened with open(2) syscall |
- | regfile.proto |
| eventfd | array | Eventfd file information | - | eventfd.proto |
| eventpoll | array | Eventpoll file information | - | eventpoll.proto |
| eventpoll-tfd | array | Target file descriptors of eventpoll fds | - | eventpoll.proto |
| inotify | array | Inotify file information | - | intotify.proto |
| inotify-wd | array | Watch descriptors of inotify fds | - | inotify.proto |
| signalfd | array | signalfd info | - | signalfd.proto |
| core | single-entry | Arch-dependent information (registers, etc.) | - | core.proto |
| mm | single-entry | Address space generic information (segments, exe file, etc.) | - | mm.proto |
| vmas | array | Virtual mappings (mmap(2)) |
- | vma.proto |
| pipes | array | Pipes information | - | pipe.proto |
| pipes-data | array | Contents of pipes | entry.bytes bytes of data sitting in a pipe |
pipe-data.proto |
| fifo | array | FIFO information | - | fifo.proto |
| fifo-data | array | Contents of FIFOs | same as in pipes-data | pipe-data.proto |
| pstree | array | Process tree linkage and IDs | - | pstree.proto |
| sigacts | array | Signal handling map | - | sa.proto |
| unixsk | array | Unix domain sockets | - | sk-unix.proto |
| inetsk | array | PF_INET sockets, both IPv4 and IPv6 | - | sk-inet.proto |
| sk-queues | array | Contents of socket queues | entry.length bytes of data, one entry per packet |
sk-packet.proto |
| itimers | array | Interval timers state | - | itimer.proto |
| creds | single-entry | Task credentials: uids, gids, caps, etc. | - | creds.proto |
| fs | single-entry | Chroot and chdir information | - | fs.proto |
| remap-fpath | array | File paths remaps | - | remap-file-path.proto |
| ghost-file | single-entry | Ghost files (those, not visible from FS, but still used by tasks) | Right after the entry up to the EOF goes the contents of the file | ghost-file.proto |
| tcp-stream | single-entry | TCP connection state (including data in queues) | entry.inq_len bytes of in-queue data followed by entry.outq_len bytes of out-queue data |
tcp-stream.proto |
| mountpoints | array | Mountpoints information | - | mnt.proto |
| utsns | single-entry | Uname nodename and domainname of a UTS namespace | - | utsns.proto |
| tty | array | Information about opened tty-s | - | tty.proto |
| tty-info | array | Termios and similar stuff about tty-s | - | tty.proto |
| packetsk | array | Info about PF_PACKET sockets | - | packet-sock.proto |
| netdev | array | Info about network devices | - | netdev.proto |
Images with memory dumps
Memory info is stored in two types of images
- Pagemap files
- These files contain info about which virtual regions are populated with data. The file is a set of protobuf messages.
|
|
Note: Even though, pagemap is an array kind of image(and can be included to the previous type), first pb message is of type pagemap_head and all the following ones are of type pagemap_entry. |
- Pages files
- These contain 4k pages that are to be put into the memory according to the pagemap.
Raw images
These images contain data that were collected by criu with the help of some external tools. These are
| name | tool that understand this format | description |
|---|---|---|
| ifaddr | iproute2's ip | Contains info about IP addresses on network devices |
| route | iproute2's ip | Contains routing tables |
| tmpfs | tar + gzip | Contains contents of tmpfs filesystem |
Notes about protobuf
We have a registered field number(1018) for custom options of all kinds. See protobuf/opts.proto for more info.