Difference between revisions of "Images"

From CRIU
Jump to navigation Jump to search
(+ raw images)
m (→‎Images with PB data: add ns-files)
 
(42 intermediate revisions by 7 users not shown)
Line 3: Line 3:
 
== Types of image files ==
 
== Types of image files ==
  
−
CRIU images can be in one of formats
+
CRIU images can be in one of the following formats
  
−
* crtools specific images in google protocol buffer format (PB format)
+
* criu specific images in google protocol buffer format (PB format)
−
* crtools specific images with binary data in it
+
* criu specific images with binary data in it
 
* image files in 3rd party format (a.k.a. raw images)
 
* image files in 3rd party format (a.k.a. raw images)
  
−
== crtools-specific format description ==
+
== Images in criu-specific format ==
  
−
All crtools-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.
+
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
 
IOW protocol-buffers image files look like
  
 
<pre>
 
<pre>
−
IMAGE_FILE ::= MAGIC { ENTRY }
+
IMAGE_FILE ::= MAGIC [MAGIC_2] { ENTRY }
 
ENTRY      ::= SIZE PAYLOAD [ EXTRA ]
 
ENTRY      ::= SIZE PAYLOAD [ EXTRA ]
 
PAYLOAD    ::= "message encoded in ProtocolBuffer format"
 
PAYLOAD    ::= "message encoded in ProtocolBuffer format"
Line 22: Line 33:
  
 
MAGIC      ::= "32 bit integer"
 
MAGIC      ::= "32 bit integer"
 +
MAGIC_2    ::= "32 bit integer"
 
SIZE      ::= "32 bit integer, equals the PAYLOAD length"
 
SIZE      ::= "32 bit integer, equals the PAYLOAD length"
 
</pre>
 
</pre>
 +
 +
Or, you can visualize it like
 +
 +
{| class="wikitable"
 +
|-
 +
! 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.
 
The amount of entries in a image file depends on the type of file.
  
−
== Types of image files with PB data  ==
+
=== Images with PB data  ===
  
 
Such images can be one of
 
Such images can be one of
Line 33: Line 64:
 
; Array image files
 
; 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.
 
: 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
 
; Single-entry image files
 
: In these files exactly one entry is stored.
 
: 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 <type>.proto files.
+
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 <code>images/</code> directory in the source tree.
  
 
{|class="wikitable sortable"
 
{|class="wikitable sortable"
Line 44: Line 76:
 
  ! description
 
  ! description
 
  ! extra payload
 
  ! extra payload
 +
! describing proto file
 
  |-
 
  |-
−
  | inventory || single-entry || Top level description of images || -
+
  | inventory || single-entry || Top level description of images || - || inventory.proto
 
  |-
 
  |-
−
  | fdinfo || array || Open file descriptors || -
+
  | fdinfo || array || [[Fdinfo-engine|Open file descriptors]] || - || fdinfo.proto
 
  |-
 
  |-
−
  | regfile || array || Paths to files opened with <code>open(2)</code> syscall || -
+
  | reg-files || array || Paths to [[:Category:Files|files]] opened with <code>open(2)</code> syscall || - || regfile.proto
 
  |-
 
  |-
−
  | eventfd || array || Eventfd file information || -
+
  | ext-files || array || Files that are dumped/restored with plugins || - || ext-file.proto
 
  |-
 
  |-
−
  | eventpoll || array || Eventpoll file information || -
+
  | ns-files || array || Linux procfs namespace entries || - || ns.proto
 
  |-
 
  |-
−
  | eventpoll-tfd || array || Target file descriptors of eventpoll fds || -
+
  | eventfd || array || Eventfd file information || - || eventfd.proto
 
  |-
 
  |-
−
  | inotify-file || array || Inotify file information || -
+
  | eventpoll || array || Eventpoll file information || - || eventpoll.proto
 
  |-
 
  |-
−
  | inotify-wd || array || Watch descriptors of inotify fds || -
+
  | eventpoll-tfd || array || Target file descriptors of eventpoll fds (merged into above) || - || eventpoll.proto
 
  |-
 
  |-
−
  | signalfd || array || signalfd info
+
  | inotify || array || Inotify file information || - || fsnotify.proto
 
  |-
 
  |-
−
  | core || single-entry || Arch-dependent information (registers, etc.) || -
+
  | inotify-wd || array || Watch descriptors of inotify fds (merged into above) || - || fsnotify.proto
 
  |-
 
  |-
−
  | mm || single-entry || Address space generic information (segments, exe file, etc.) || -
+
  | signalfd || array || signalfd info || - || signalfd.proto
 
  |-
 
  |-
−
  | vmas || array || Virtual mappings (<code>mmap(2)</code>) || -
+
  | core || single-entry || Core process info and (name, sigmask, itimers, etc.) arch-dependent information (registers, etc.) || - || core.proto
 
  |-
 
  |-
−
  | pipes || array || Pipes information || -
+
  | mm || single-entry || [[Memory dumping and restoring|Address space]] information (VMAs, segments, exe file, etc.) || - || mm.proto
 
  |-
 
  |-
−
  | pipes-data || array || Contents of pipes || <code>entry.bytes</code> bytes of data sitting in a pipe
+
  | pipes || array || Pipes information || - || pipe.proto
 
  |-
 
  |-
−
  | fifo || array || FIFO information || -
+
  | pipes-data || array || Contents of pipes || <code>entry.bytes</code> bytes of data sitting in a pipe || pipe-data.proto
 
  |-
 
  |-
−
  | fifo-data || array || Contents of FIFOs || same as in pipes-data
+
  | fifo || array || FIFO information || - || fifo.proto
 
  |-
 
  |-
−
  | pstree || array || Process tree linkage and IDs || -
+
  | fifo-data || array || Contents of FIFOs || same as in pipes-data || pipe-data.proto
 
  |-
 
  |-
−
  | sigacts || array || Signal handling map || -
+
  | pstree || array || Process [[tree after restore|tree linkage]] || - || pstree.proto
 
  |-
 
  |-
−
  | unixsk || array || Unix domain sockets || -
+
  | ids || single || IDs of objects (mm, files, sihand, etc.) and namespaces || - || core.proto
 
  |-
 
  |-
−
  | inetsk || array || PF_INET sockets, both IPv4 and IPv6 || -
+
  | sigacts || array || Signal handling map || - || sa.proto
 
  |-
 
  |-
−
  | sk-queues || array || Contents of socket queues || <code>entry.length</code> bytes of data, one entry per packet
+
  | unixsk || array || [[Unix sockets]] || - || sk-unix.proto
 
  |-
 
  |-
−
  | itimers || array || Interval timers state || -
+
  | inetsk || array || PF_INET sockets, both IPv4 and IPv6 || - || sk-inet.proto
 
  |-
 
  |-
−
  | creds || single-entry || Task credentials: uids, gids, caps, etc. || -
+
  | sk-queues || array || Contents of socket queues || <code>entry.length</code> bytes of data, one entry per packet || sk-packet.proto
 
  |-
 
  |-
−
  | fs || single-entry || Chroot and chdir information || -
+
  | itimers || array || Interval timers state (merged into core image) || - || timer.proto
 
  |-
 
  |-
−
  | path-remap || array || File paths remaps || -
+
  | creds || single-entry || Task credentials: uids, gids, caps, etc. || - || creds.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
+
  | fs || single-entry || Chroot and chdir information || - || fs.proto
 
  |-
 
  |-
−
  | tcp-stream || single-entry || TCP connection state (including data in queues) || -
+
  | remap-fpath || array || File paths remaps (e.g. for [[invisible files]]) || - || remap-file-path.proto
 
  |-
 
  |-
−
  | mountpoints || array || Mountpoints information || -
+
  | ghost-file || single-entry || Ghost [[invisible files]] || Right after the entry up to the EOF goes the contents of the file || ghost-file.proto
 
  |-
 
  |-
−
  | utsns || single-entry || Uname nodename and domainname of a UTS namespace || -
+
  | tcp-stream || single-entry || [[TCP connection]] state (including data in queues) || <code>entry.inq_len</code> bytes of in-queue data followed by <code>entry.outq_len</code> bytes of out-queue data || tcp-stream.proto
 
  |-
 
  |-
−
  | tty || array || Information about opened tty-s
+
  | mountpoints || array || [[Mountpoints]] information || - || mnt.proto
 
  |-
 
  |-
−
  | tty-info || array || Termios and similar stuff about tty-s
+
  | utsns || single-entry || Uname nodename and domainname of a UTS namespace || - || utsns.proto
 
  |-
 
  |-
−
  | packetsk || array || Info about PF_PACKET sockets
+
  | tty || array || Information about opened [[TTYs]] || - || tty.proto
 
  |-
 
  |-
−
  | netdev || array || Info about network devices
+
| tty-info || array || Termios and similar stuff about [[TTYs]] || - || tty.proto
 +
|-
 +
| packetsk || array || Info about PF_PACKET sockets || - || packet-sock.proto
 +
|-
 +
  | netdev || array || Info about [[:Category:Network|network]] devices || - || netdev.proto
 
  |}
 
  |}
  
−
== Images with binary crtools data ==
+
=== Images with memory dumps ===
  
−
These are
+
''Main article: [[memory dumps]]''.
  
−
; Memory dumps
+
Anonymous memory contents (both private and shared) is stored in two types of images:
−
: These files contain memory dumps. The format is
+
 
−
<pre>
+
; Pagemap files
−
IMAGE ::= MAGIC [ ADDRESS DATA ]
+
: These files contain info about which virtual regions are populated with data. The file is a set of protobuf messages.
−
ADDRESS ::= "64-bit virtual address"
+
{{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.}}
−
DATA ::= "4K bytes blob (i.e. -- memory page)"
+
 
−
</pre>
+
; Pages files
 +
: These contain 4k pages that are to be put into the memory according to the pagemap.
  
 
== Raw images ==
 
== Raw images ==
  
−
These images contain data that were collected by crtools with the help of some external tools. These are
+
These images contain data collected by CRIU with the help of some external tools.
  
 
{|class="wikitable sortable"
 
{|class="wikitable sortable"
 
  |-
 
  |-
−
  ! name
+
  ! Name
−
  ! tool that understand this format
+
  ! Tool supporting the format
−
  ! description
+
  ! Description
 +
! Decode command
 
  |-
 
  |-
−
  | ifaddr || iproute2's ip || Contains info about IP addresses on network devices
+
  | ifaddr || ip from iproute2 || IP addresses on network devices || <nowiki>cat ifaddr-8.img | ip addr showdump</nowiki>
 
  |-
 
  |-
−
  | route || iproute2's ip || Contains routing tables
+
  | route || ip from iproute2 || Routing tables || <nowiki>cat route-8.img | ip route showdump</nowiki>
 
  |-
 
  |-
−
  | tmpfs || tar + gzip || Contains contents of tmpfs filesystem
+
  | tmpfs || tar + gzip || Contents of a tmpfs filesystem || tar -tzf tmpfs-dev-49.tar.gz.img
 
  |}
 
  |}
 +
 +
== Notes about protobuf ==
 +
We have a registered field number (1018) for [https://developers.google.com/protocol-buffers/docs/proto#options custom options] of all kinds. See protobuf/opts.proto for more info.
 +
 +
== See also ==
 +
 +
* [[CRIT]]: a tool to decode images to a human readable format
 +
* [[What's bad with V1 images]]
 +
* [[Image field merging]]
 +
* [[Memory dumps]]
 +
 +
[[Category:Development]]
 +
[[Category:Images]]
 +
[[Category:Outdated]]

Latest revision as of 12:56, 15 September 2023

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

Types of image files[edit]

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[edit]

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[edit]

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 images/ 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
ext-files array Files that are dumped/restored with plugins - ext-file.proto
ns-files array Linux procfs namespace entries - ns.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 - fsnotify.proto
inotify-wd array Watch descriptors of inotify fds (merged into above) - fsnotify.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 information (VMAs, segments, exe file, etc.) - mm.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 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) - timer.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 TTYs - tty.proto
tty-info array Termios and similar stuff about TTYs - tty.proto
packetsk array Info about PF_PACKET sockets - packet-sock.proto
netdev array Info about network devices - netdev.proto

Images with memory dumps[edit]

Main article: 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.svg 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[edit]

These images contain data collected by CRIU with the help of some external tools.

Name Tool supporting the format Description Decode command
ifaddr ip from iproute2 IP addresses on network devices cat ifaddr-8.img | ip addr showdump
route ip from iproute2 Routing tables cat route-8.img | ip route showdump
tmpfs tar + gzip Contents of a tmpfs filesystem tar -tzf tmpfs-dev-49.tar.gz.img

Notes about protobuf[edit]

We have a registered field number (1018) for custom options of all kinds. See protobuf/opts.proto for more info.

See also[edit]

Retrieved from "https://criu.org/index.php?title=Images&oldid=5421"