CRIU - User contributions [en]

CLI/opt/--tcp-close

2023-10-19T15:19:34Z

Ymanton:

''Main article: [[TCP connection]]''

tldr; This option is only used with CRIU restore command.
It allows your listening (server) TCP sockets to exist after process tree c/r. It drops all the other TCP connections in the process tree.
All your server clients will be able reconnect to its listening sockets created during process tree restore.
--tcp-close option allows you to migrate your servers to environments with different ip addresses if your sockets listen on addresses such as 0.0.0.0.
Moreover you'll be able to restore many copies of your server on different machines in this case.
--tcp-close option works well with another one that allows to change ip addresses of sockets in CRIU image files. It is not implemented yet (https://github.com/checkpoint-restore/criu/issues/211).

Some details:

All the original process tree sockets data is preserved in process tree image files.
--tcp-close option affects all the process tree TCP sockets that have any TCP state except CLOSED and LISTEN.
Those affected sockets are restored in CLOSED TCP state (TCP_CLOSE Linux macro).
Userspace code that uses those affected sockets will just get errors from its syscalls. Then it would assume that there was a networking/peer problem
and it would execute usual error handling code path.

[[Category: CLI]]
[[Category:Sockets]]
[[Category:Editor_help_needed]]

Validate files on restore

2023-10-19T14:27:59Z

Ymanton:

This article describes what CRIU does to make sure it restores the correct set of files and how this file validation is implemented in CRIU. This project was completed under the [https://summerofcode.withgoogle.com/projects/#5773537320632320 GSoC 2020 program].

Note: This is NOT merged to CRIU, see https://github.com/checkpoint-restore/criu/pull/1148

== The previous implementation ==
Since CRIU doesn’t carry the contents of files into images while dumping (Except for ghost files), files that are being restored must be validated to make sure they are the “same” as they were during the dumping process (Especially true for ELF files since there is a risk of restoring executables or libraries of a different version). This was being done by only storing and comparing the size of the file. By itself, this isn’t a very strong check.

== The current implementation ==
The file size method is used as a preliminary method, if it fails there’s no need to do any of the more intensive checks, instead it will immediately give out an error and stop restoring. Stronger checks are used only if it passes.

The simplest and strongest check is to calculate the checksum for the entire file but this would be very intensive for large files and therefore not always feasible. A reasonable compromise would be to calculate the checksum only for certain parts of the file. This is the checksum method and it is one of the two methods that have been implemented in CRIU.

The other method is the build-ID method. The build-ID is a "strongly unique embedded identifier" that (If present) is stored in a particular note section of ELF files.

== Build-ID ==
The build-ID (If present) is stored in a note of type <code>NT_GNU_BUILD_ID</code> in the ELF file. All notes are in the note section which is a program header of type <code>PT_NOTE</code> in the ELF file. After the file has been mmap-ed, the first thing that needs to be done is to check whether the file is an ELF file or not. This is done by checking for the magic number. The next thing to do is to identify whether the file is a 32-bit ELF file or a 64-bit ELF file since the data types of the variables used to parse the ELF file will change depending on the bitness of the file (There are specific 32-bit and 64-bit variants of the data structures in <code>elf.h</code>) but the procedure will remain the same.

The position of the program headers is stored as an offset in <code>phoff</code>. Since all the program headers are stored in an arbitrary order, each program header needs to be checked. If a program header of type <code>PT_NOTE</code> is found, the position of this note section is stored as an offset in <code>p_offset</code>. The notes are stored in an arbitrary order as well, so each note needs to be checked. If a note of type <code>NT_GNU_BUILD_ID</code> is found, the build-ID is present in its description.

== Checksum ==
CRC32C is used to calculate the checksum. The only difference between CRC32C and CRC32 is the polynomial being used. CRC32C uses the Castagnoli polynomial (0x82F63B78 in little-endian notation) and CRC32 uses 0xEDB88320 (In little-endian notation).

The file is mapped 10 MB at a time and the checksum is calculated on the required bytes (Depending on the configuration set - Entire file, First N bytes of the file, or Every Nth byte of the file). N is the checksum parameter.

Adding a new configuration is quite simple and only requires the iterator to be moved to the necessary bytes (0 refers to the first byte of the file and 1 refers to the second byte and so on):
# Input handling for the new configuration
# The <code>checksum_iterator_init</code> function in ''"criu/files-reg.c”'' sets the initial iterator position (The first byte to calculate the checksum)
# The <code>checksum_iterator_next</code> function in ''“criu/files-reg.c”'' moves the iterator to the next position (The next byte to calculate the checksum)
# The <code>checksum_iterator_stop</code> function in ''“criu/files-reg.c”'' returns true when the iterator has reached its final position
There is a separate check in the <code>calculate_checksum</code> function to make sure the iterator refers to a valid byte (Not negative and smaller than the total number of bytes in the file). If the iterator is outside the mapped region but still valid, the required region of the file will be mapped.

== Using different validation methods and parameters ==
The build-ID method is much less intensive compared to the checksum method while still being a much stronger check than simply comparing the file size and is therefore the default. In other words, <code>--file-validation buildid</code> will not make a difference as this is the default method.

CRIU can also be configured to use the checksum method by default by using the <code>--file-validation option</code>:
* <code>--file-validation checksum-full</code> to calculate and use the checksum on the entire file.
* <code>--file-validation checksum</code> to calculate and use the checksum on the first N bytes of the file. The parameter N is set by using the <code>--checksum-parameter</code> option.
* <code>--file-validation checksum-period</code> to calculate and use the checksum on every Nth byte of the file (Including the first byte of the file). The parameter N is set by using the <code>--checksum-parameter option</code>.
By default, the checksum parameter N is set to 1024. If a method that doesn’t require the checksum parameter is being used, then the checksum parameter is simply ignored.
For example, to use the checksum method on the first 2048 bytes of the file: <code>--file-validation checksum --checksum-parameter 2048</code>

If the build-ID method is being used and is inconclusive (Maybe because the ELF file doesn’t contain a build-ID), then the checksum method on the first 1024 bytes of the file is used as a fallback. If the checksum method is being used and is inconclusive, then the build-ID method is used as a fallback. If both are inconclusive, only the file size check is used (And a warning is put out to inform the user that only a weak check has been used for that particular file).

To explicitly use only the file size check all the time, the following command-line option can be used: <code>--file-validation filesize</code> (This is the fastest and least intensive check).

== Performance impact ==
The values shown below are the average times it took to finish the ZDTM tests over multiple runs, and are only to indicate the impact each method has in general.

Each test has 3 files (Of sizes: 0.09 MB, 2 MB and 0.17 MB approximately) and each test is run 3 times (In Host, Namespace and User Namespace). For each file the checksum/build-ID is obtained twice (During dump and restore) therefore the function to find checksum/build-ID is called 18 times overall per test.

For reference, these tests were run on tmpfs (To remove any disk latency) and on an undervolted i5 4800H.

{| class="wikitable" style="text-align: center;
|+zdtm/transition/shmem:
|-
|File Size
|3.782s
|-
|Build-ID
|4.153s (~9% increase)
|-
|Checksum (First 1024 bytes)
|4.465s (~18% increase)
|-
|Checksum (Entire File)
|4.722s (~24% increase)
|-
|Checksum (Every 1024th byte)
|4.498s (~19% increase)
|}

{| class="wikitable" style="text-align: center;
|+zdtm/static/maps04:
|-
|File Size
|35.317s
|-
|Build-ID
|35.720s (~1% increase)
|-
|Checksum (First 1024 bytes)
|35.919s (~2% increase)
|-
|Checksum (Entire File)
|36.679s (~4% increase)
|-
|Checksum (Every 1024th byte)
|36.476s (~3% increase)
|}

== Scope for improvement and future work ==
* Calculating the checksum can be made faster by using a lookup table.

[[Category:Files]]
[[Category:Under the hood]]

CRIT

2022-11-04T16:31:05Z

Ymanton: /* Check/validate images */

''This page describes the CRIT Python tool. For the Go library, see [[CRIT (Go library)]]''.

CRiu Image Tool is a feature-rich replacement for existing "criu show".
It is written completely in Python, so it is quite easy to read the code and extend its features.

== Usage ==
<pre>
usage: crit [-h] {decode,encode,info,x,show} ...

CRiu Image Tool

positional arguments:
{decode,encode,info,x,show}
Use crit CMD --help for command-specific help
decode convert criu image from binary type to json
encode convert criu image from json type to binary
info show info about image
x explore image dir
show convert criu image from binary to human-readable json

optional arguments:
-h, --help show this help message and exit
</pre>

=== Pretty output ===

<code>crit decode</code> prints JSON text in one line. This can be read by any further JSON-aware tool for parsing. For human eyes it's more convenient to read JSON multi-line with indentation. CRIT can do this when using the <code>show</code> action or the <code>--pretty</code> option.

Wend doing pretty optput CRIT does a little bit more, than just multiline indented JSON.

; Addresses and registers
: VM addresses and core.img register values are all printed in hex. Since JSON doesn't support this form of numbers, such fields are encoded as strings.

; Bit-fields
: Such things as flags and masks (e.g. sig-block mask) are also better understood when written in hex, so CRIT does this.

; IP addresses
: By default those a printed in decimal, but the "1.2.3.4" for v4 or "::1" for v6 can be seen in the --pretty mode.

; Symbolic names for flags
: Some known bit sets (e.g. MAP_PRIVATE, MAP_ANONYMOUS, etc. for vma->flags) are shown with names.

; Device numbers
: If the field is known to be of <code>dev_t</code> type, it's printed in the <code>major:minor</code> manner

== Functionality ==

=== Convert images from IMG to JSON ===

<code>crit decode</code> is the replacement for the (rather nasty) <code>criu show</code> code. This is also the way to edit the images before restoring from them.

It uses [https://developers.google.com/protocol-buffers/docs/reference/python/google.protobuf.text_format-module text_format] as a human-readable format for protobuf messages.

The output file is structured in the following way.

Without "--pretty":
<pre>
{ "magic" : "FOO", "entries" : [{"foo": "bar", "bar": "foo", "extra": "abc"}, {"foo": "bar", "bar" : "foo", "extra" : "abc"} ]}
</pre>

With "--pretty":
<pre>
{
"magic" : "FOO",
"entries" : [
{
"foo" : "bar",
"bar" : "foo",
"extra" : "abc"
},
{
"foo" : "bar",
"bar" : "foo",
"extra" : "abc"
}
]
}
</pre>

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
<b>Example("crit decode -i core-5679.img --pretty")</b>
<div class="mw-collapsible-content">
<pre>
{
"magic": "CORE",
"entries": [
{
"mtype": "X86_64",
"thread_core": {
"futex_rla_len": 24,
"sched_policy": 0,
"sched_nice": 0,
"futex_rla": 0,
"signals_p": {},
"sas": {
"ss_size": 0,
"ss_sp": 0,
"ss_flags": 2
}
},
"thread_info": {
"fpregs": {
"st_space": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"fop": 0,
"rdp": 0,
"twd": 0,
"mxcsr": 8064,
"swd": 0,
"rip": 0,
"xsave": {
"ymmh_space": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"xstate_bv": 2
},
"xmm_space": [
0,
4278190080,
4294967295,
4294967295,
1701145715,
3219568,
0,
0,
0,
0,
33,
0,
792358505,
1953460082,
1852400175,
0,
942882145,
876295483,
774519349,
1031303283,
893073459,
976565307,
1937255978,
859661936,
993344312,
3814708,
65,
0,
37049520,
0,
37049632,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
4294901760,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"cwd": 0,
"mxcsr_mask": 65535
},
"clear_tid_addr": 0,
"gpregs": {
"gs": "0x0",
"ip": "0x7f172cf1ea04",
"cx": "0xffffffffffffffff",
"cs": "0x33",
"ax": "0x38",
"orig_ax": "0x38",
"di": "0x1200011",
"es": "0x0",
"gs_base": "0x0",
"r14": "0x0",
"r15": "0x2355e00",
"r12": "0x7ffffdbf74f0",
"r13": "0x0",
"r10": "0x7f172d83d9d0",
"r11": "0x246",
"fs_base": "0x7f172d83d700",
"bp": "0x7ffffdbf7530",
"dx": "0x0",
"bx": "0x0",
"ds": "0x0",
"ss": "0x2b",
"sp": "0x7ffffdbf74f0",
"r8": "0x0",
"r9": "0x0",
"fs": "0x0",
"si": "0x0",
"flags": "0x246"
}
},
"tc": {
"timers": {
"real": {
"isec": 0,
"vusec": 0,
"iusec": 0,
"vsec": 0
},
"virt": {
"isec": 0,
"vusec": 0,
"iusec": 0,
"vsec": 0
},
"prof": {
"isec": 0,
"vusec": 0,
"iusec": 0,
"vsec": 0
}
},
"cg_set": 1,
"signals_s": {},
"blk_sigset": "0x10002",
"exit_code": 0,
"rlimits": {
"rlimits": [
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 8388608
},
{
"max": 18446744073709551615,
"cur": 0
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 62844,
"cur": 62844
},
{
"max": 4096,
"cur": 1024
},
{
"max": 65536,
"cur": 65536
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 62844,
"cur": 62844
},
{
"max": 819200,
"cur": 819200
},
{
"max": 0,
"cur": 0
},
{
"max": 0,
"cur": 0
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
}
]
},
"comm": "loop.sh",
"flags": 1077960704,
"task_state": 1,
"personality": 0
}
}
]
}
</pre>
</div>
</div>

Decode also supports input via STDIN instead of the "-i" flag.

<pre>
cat "core-5679.img" | crit decode
</pre>

=== Convert images from JSON to IMG ===

<code>crit encode</code> converts the image from JSON to IMG. Standard usage would look like:

<pre>
crit encode -i core-5679.json -o core-5679.img
</pre>

Encode also supports input via STDIN instead of the "-i" flag.

<pre>
cat "core-5679.json" | crit encode
</pre>

Incase a "-o" flag is not specified the input is piped out to STDOUT.

=== Generate core files out of task images ===

Moved into separate project called [[criu-coredump]].

=== Show images statistics ===

<code>crit x</code> allows you to explore image statistics.
E.g. Total number of processes, files, memory, sockets, etc.

<pre>
crit x $directory_with_images <explore type>
</pre>

Supported explorers are
;'ps'
:to show process tree

;'fds'
:to show files used by tasks

;'mems'
:to show memory mappings info

=== Show images Info ===

Image of a info such as its "COUNT" and "MAGIC" can be displayed using the INFO command.
<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
<b>Example("crit info core-5679.img")</b>
<div class="mw-collapsible-content">
<pre>
{
"count": 1,
"magic": "CORE"
}
</pre>
</div>
</div>

== Planned functionality ==

=== On-the-fly conversion ===

There's an idea to make CRIU spawn CRIT and read images "through" it, to allow for at-the-restore-time modifications. For details, see https://github.com/checkpoint-restore/criu/issues/59.

=== Convert between different image versions ===

Right now we store the images version in inventory.img and collect info about [[what's bad with V1 images]]. If some day we have v2, CRIT will convert from v1. And for backward compatibility we'll use on-the-fly conversion when restoring from old images.

=== Check/validate images ===

Check that
* all images are present
* the inter-images IDs are in consistent state

For details, see https://github.com/checkpoint-restore/criu/issues/44.

=== [[Anonymize image files]] ===

Since images contain raw memory dumps people may refuse to send us images for debugging. Need to anonymize them, i.e. -- remove this sensitive information.

[[Category:Images]]
[[Category:API]]

CRIT

2022-11-04T15:22:47Z

Ymanton: /* On-the-fly conversion */

''This page describes the CRIT Python tool. For the Go library, see [[CRIT (Go library)]]''.

CRiu Image Tool is a feature-rich replacement for existing "criu show".
It is written completely in Python, so it is quite easy to read the code and extend its features.

== Usage ==
<pre>
usage: crit [-h] {decode,encode,info,x,show} ...

CRiu Image Tool

positional arguments:
{decode,encode,info,x,show}
Use crit CMD --help for command-specific help
decode convert criu image from binary type to json
encode convert criu image from json type to binary
info show info about image
x explore image dir
show convert criu image from binary to human-readable json

optional arguments:
-h, --help show this help message and exit
</pre>

=== Pretty output ===

<code>crit decode</code> prints JSON text in one line. This can be read by any further JSON-aware tool for parsing. For human eyes it's more convenient to read JSON multi-line with indentation. CRIT can do this when using the <code>show</code> action or the <code>--pretty</code> option.

Wend doing pretty optput CRIT does a little bit more, than just multiline indented JSON.

; Addresses and registers
: VM addresses and core.img register values are all printed in hex. Since JSON doesn't support this form of numbers, such fields are encoded as strings.

; Bit-fields
: Such things as flags and masks (e.g. sig-block mask) are also better understood when written in hex, so CRIT does this.

; IP addresses
: By default those a printed in decimal, but the "1.2.3.4" for v4 or "::1" for v6 can be seen in the --pretty mode.

; Symbolic names for flags
: Some known bit sets (e.g. MAP_PRIVATE, MAP_ANONYMOUS, etc. for vma->flags) are shown with names.

; Device numbers
: If the field is known to be of <code>dev_t</code> type, it's printed in the <code>major:minor</code> manner

== Functionality ==

=== Convert images from IMG to JSON ===

<code>crit decode</code> is the replacement for the (rather nasty) <code>criu show</code> code. This is also the way to edit the images before restoring from them.

It uses [https://developers.google.com/protocol-buffers/docs/reference/python/google.protobuf.text_format-module text_format] as a human-readable format for protobuf messages.

The output file is structured in the following way.

Without "--pretty":
<pre>
{ "magic" : "FOO", "entries" : [{"foo": "bar", "bar": "foo", "extra": "abc"}, {"foo": "bar", "bar" : "foo", "extra" : "abc"} ]}
</pre>

With "--pretty":
<pre>
{
"magic" : "FOO",
"entries" : [
{
"foo" : "bar",
"bar" : "foo",
"extra" : "abc"
},
{
"foo" : "bar",
"bar" : "foo",
"extra" : "abc"
}
]
}
</pre>

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
<b>Example("crit decode -i core-5679.img --pretty")</b>
<div class="mw-collapsible-content">
<pre>
{
"magic": "CORE",
"entries": [
{
"mtype": "X86_64",
"thread_core": {
"futex_rla_len": 24,
"sched_policy": 0,
"sched_nice": 0,
"futex_rla": 0,
"signals_p": {},
"sas": {
"ss_size": 0,
"ss_sp": 0,
"ss_flags": 2
}
},
"thread_info": {
"fpregs": {
"st_space": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"fop": 0,
"rdp": 0,
"twd": 0,
"mxcsr": 8064,
"swd": 0,
"rip": 0,
"xsave": {
"ymmh_space": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"xstate_bv": 2
},
"xmm_space": [
0,
4278190080,
4294967295,
4294967295,
1701145715,
3219568,
0,
0,
0,
0,
33,
0,
792358505,
1953460082,
1852400175,
0,
942882145,
876295483,
774519349,
1031303283,
893073459,
976565307,
1937255978,
859661936,
993344312,
3814708,
65,
0,
37049520,
0,
37049632,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
4294901760,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"cwd": 0,
"mxcsr_mask": 65535
},
"clear_tid_addr": 0,
"gpregs": {
"gs": "0x0",
"ip": "0x7f172cf1ea04",
"cx": "0xffffffffffffffff",
"cs": "0x33",
"ax": "0x38",
"orig_ax": "0x38",
"di": "0x1200011",
"es": "0x0",
"gs_base": "0x0",
"r14": "0x0",
"r15": "0x2355e00",
"r12": "0x7ffffdbf74f0",
"r13": "0x0",
"r10": "0x7f172d83d9d0",
"r11": "0x246",
"fs_base": "0x7f172d83d700",
"bp": "0x7ffffdbf7530",
"dx": "0x0",
"bx": "0x0",
"ds": "0x0",
"ss": "0x2b",
"sp": "0x7ffffdbf74f0",
"r8": "0x0",
"r9": "0x0",
"fs": "0x0",
"si": "0x0",
"flags": "0x246"
}
},
"tc": {
"timers": {
"real": {
"isec": 0,
"vusec": 0,
"iusec": 0,
"vsec": 0
},
"virt": {
"isec": 0,
"vusec": 0,
"iusec": 0,
"vsec": 0
},
"prof": {
"isec": 0,
"vusec": 0,
"iusec": 0,
"vsec": 0
}
},
"cg_set": 1,
"signals_s": {},
"blk_sigset": "0x10002",
"exit_code": 0,
"rlimits": {
"rlimits": [
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 8388608
},
{
"max": 18446744073709551615,
"cur": 0
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 62844,
"cur": 62844
},
{
"max": 4096,
"cur": 1024
},
{
"max": 65536,
"cur": 65536
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
},
{
"max": 62844,
"cur": 62844
},
{
"max": 819200,
"cur": 819200
},
{
"max": 0,
"cur": 0
},
{
"max": 0,
"cur": 0
},
{
"max": 18446744073709551615,
"cur": 18446744073709551615
}
]
},
"comm": "loop.sh",
"flags": 1077960704,
"task_state": 1,
"personality": 0
}
}
]
}
</pre>
</div>
</div>

Decode also supports input via STDIN instead of the "-i" flag.

<pre>
cat "core-5679.img" | crit decode
</pre>

=== Convert images from JSON to IMG ===

<code>crit encode</code> converts the image from JSON to IMG. Standard usage would look like:

<pre>
crit encode -i core-5679.json -o core-5679.img
</pre>

Encode also supports input via STDIN instead of the "-i" flag.

<pre>
cat "core-5679.json" | crit encode
</pre>

Incase a "-o" flag is not specified the input is piped out to STDOUT.

=== Generate core files out of task images ===

Moved into separate project called [[criu-coredump]].

=== Show images statistics ===

<code>crit x</code> allows you to explore image statistics.
E.g. Total number of processes, files, memory, sockets, etc.

<pre>
crit x $directory_with_images <explore type>
</pre>

Supported explorers are
;'ps'
:to show process tree

;'fds'
:to show files used by tasks

;'mems'
:to show memory mappings info

=== Show images Info ===

Image of a info such as its "COUNT" and "MAGIC" can be displayed using the INFO command.
<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
<b>Example("crit info core-5679.img")</b>
<div class="mw-collapsible-content">
<pre>
{
"count": 1,
"magic": "CORE"
}
</pre>
</div>
</div>

== Planned functionality ==

=== On-the-fly conversion ===

There's an idea to make CRIU spawn CRIT and read images "through" it, to allow for at-the-restore-time modifications. For details, see https://github.com/checkpoint-restore/criu/issues/59.

=== Convert between different image versions ===

Right now we store the images version in inventory.img and collect info about [[what's bad with V1 images]]. If some day we have v2, CRIT will convert from v1. And for backward compatibility we'll use on-the-fly conversion when restoring from old images.

=== Check/validate images ===

Check that
* all images are present
* the inter-images IDs are in consistent state

For details, see https://github.com/xemul/criu/issues/44.

=== [[Anonymize image files]] ===

Since images contain raw memory dumps people may refuse to send us images for debugging. Need to anonymize them, i.e. -- remove this sensitive information.

[[Category:Images]]
[[Category:API]]

Statistics

2022-07-25T16:55:30Z

Ymanton: Update show command to use crit

CRIU generates a set of <code>stats-<type></code> files that contain statistics about how dump/restore went. These files are in google-protocol-buffers format, just like the [[images]] are, and can be viewed using the <code>crit show [FILE]</code> command (<code>criu show -f [FILE]</code> in previous versions).

== Dump/Pre-dump stats ==

These are in <code>stats-dump</code> file. Fields are:

;<code>freezing_time</code>
:Time it took criu to freeze the process tree

;<code>frozen_time</code>
:Time tasks were in frozen state

;<code>memdump_time</code>
:Time criu spent grabbing required pages out of processes. This time does ''not'' include the next time

;<code>memwrite_time</code>
:Time criu spend transferring memory pages into image files (locally or on page-server)

All the above times are in microseconds.

;<code>pages_scanned</code>
:The number of pages criu looked at to decide whether or not to dump them

;<code>pages_skipped_parent</code>
:The number of pages criu skipped due to they were found in parent images (read about [[memory changes tracking]])

;<code>pages_written</code>
:The total number of pages criu put into image files

== Restore stats ==

;<code>forking_time</code>
:Time took to fork the tree of processes (with groups and sessions)

;<code>restore_time</code>
:Total time of restore

;<code>pages_compared</code>
:Number of pages compared for being COW-ed

;<code>pages_skipped_cow</code>
:Number of pages, restoration of which was skipped due to COW setup

[[Category:API]]