Images

The criu utility dumps the state of processes/containers into a set of image files. This article describes the format of them.

Note: Check out our image viewing tool, CRIT

Types of image files

CRIU images can be in one of the following 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 2 32-bit magic cookies. The first cookie is the type of file (see below) the second is the optional sub-type of image. 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.

Currently there are 3 types of images

Inventory file: This is the image file describing the set. It doesn't have sub-type magic.

Image file: Regular image. Most of the text below is about these files.

Auxiliary file: File that is not image, but criu generates one and it happens to be in protobuf format too. For now we have only stats and irmap cache files of that type. They also have sub-type magic.

IOW protocol-buffers image files look like

IMAGE_FILE ::= MAGIC [MAGIC_2] { ENTRY }
ENTRY      ::= SIZE PAYLOAD [ EXTRA ]
PAYLOAD    ::= "message encoded in ProtocolBuffer format"
EXTRA      ::= "arbitrary blob, depends on the PAYLOAD contents"

MAGIC      ::= "32 bit integer"
MAGIC_2    ::= "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 (merged into above)	-	eventpoll.proto
inotify	array	Inotify file information	-	intotify.proto
inotify-wd	array	Watch descriptors of inotify fds (merged into above)	-	inotify.proto
signalfd	array	signalfd info	-	signalfd.proto
core	single-entry	Core process info and (name, sigmask, itimers, etc.) 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)`) (merged into above)	-	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	-	pstree.proto
ids	single	IDs of objects (mm, files, sihand, etc.) and namespaces	-	core.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 (merged into core image)	-	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 (e.g. for invisible files)	-	remap-file-path.proto
ghost-file	single-entry	Ghost invisible files	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

Anonymous memory contents (both private and shared) 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.