Line 1: |
Line 1: |
− | This page describes the CRiu Image Tool. CRIT is a feature-rich replacement for existing "criu show". | + | ''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. | | It is written completely in Python, so it is quite easy to read the code and extend its features. |
| | | |
| == Usage == | | == Usage == |
| <pre> | | <pre> |
− | usage: crit [-h] [-i IN] [-o OUT] [-f {raw,nice}] {decode,encode} | + | usage: crit [-h] {decode,encode,info,x,show} ... |
| | | |
| CRiu Image Tool | | CRiu Image Tool |
| | | |
| positional arguments: | | positional arguments: |
− | {decode,encode} decode/encode - convert criu image from/to binary type | + | {decode,encode,info,x,show} |
− | to/from json
| + | 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: | | optional arguments: |
| -h, --help show this help message and exit | | -h, --help show this help message and exit |
− | -i IN, --in IN input file (stdin by default)
| |
− | -o OUT, --out OUT output file (stdout by default)
| |
− | --pretty multi-line with indentation and some fields printed in more human-readable format
| |
| </pre> | | </pre> |
| | | |
| === Pretty output === | | === Pretty output === |
| | | |
− | By default CRIT 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. However, CRIT does a little bit more and prints some fields in even more pretty manner.
| + | <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 | | ; Addresses and registers |
Line 31: |
Line 37: |
| ; IP addresses | | ; 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. | | : 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 == | | == Functionality == |
| | | |
− | === Convert images to JSON and back === | + | === Convert images from IMG to JSON === |
| | | |
− | {{Status|ready}}
| |
| | | |
− | This is the replacement for (rather nasty) criu show code. Also this is the way to edit the images before restoring from them.
| + | <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. | | 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. |
Line 44: |
Line 55: |
| The output file is structured in the following way. | | The output file is structured in the following way. |
| | | |
− | With "--format raw":
| + | Without "--pretty": |
| <pre> | | <pre> |
| { "magic" : "FOO", "entries" : [{"foo": "bar", "bar": "foo", "extra": "abc"}, {"foo": "bar", "bar" : "foo", "extra" : "abc"} ]} | | { "magic" : "FOO", "entries" : [{"foo": "bar", "bar": "foo", "extra": "abc"}, {"foo": "bar", "bar" : "foo", "extra" : "abc"} ]} |
| </pre> | | </pre> |
| | | |
− | With "--format nice"(default for stdout): | + | With "--pretty": |
| <pre> | | <pre> |
| { | | { |
Line 69: |
Line 80: |
| | | |
| <div class="toccolours mw-collapsible mw-collapsed" style="width:800px"> | | <div class="toccolours mw-collapsible mw-collapsed" style="width:800px"> |
− | <b>Example("crit decode -i core-20700.img")</b> | + | <b>Example("crit decode -i core-5679.img --pretty")</b> |
| <div class="mw-collapsible-content"> | | <div class="mw-collapsible-content"> |
| <pre> | | <pre> |
Line 201: |
Line 212: |
| }, | | }, |
| "xmm_space": [ | | "xmm_space": [ |
− | 1953064751,
| |
− | 1769104175,
| |
− | 1702113141,
| |
− | 1664054387,
| |
| 0, | | 0, |
| + | 4278190080, |
| + | 4294967295, |
| + | 4294967295, |
| + | 1701145715, |
| + | 3219568, |
| 0, | | 0, |
| 0, | | 0, |
| 0, | | 0, |
| 0, | | 0, |
− | 4294901760, | + | 33, |
− | 255,
| |
| 0, | | 0, |
| 792358505, | | 792358505, |
Line 229: |
Line 240: |
| 65, | | 65, |
| 0, | | 0, |
− | 21771440, | + | 37049520, |
| + | 0, |
| + | 37049632, |
| + | 0, |
| + | 0, |
| + | 0, |
| + | 0, |
| + | 0, |
| 0, | | 0, |
− | 21771552,
| |
| 0, | | 0, |
| 0, | | 0, |
Line 237: |
Line 254: |
| 0, | | 0, |
| 0, | | 0, |
− | 4278190080,
| |
− | 4294967295,
| |
− | 4294967040,
| |
− | 4294967295,
| |
| 0, | | 0, |
| 0, | | 0, |
Line 246: |
Line 259: |
| 0, | | 0, |
| 0, | | 0, |
− | 4278190080,
| |
− | 4294967040,
| |
− | 4294967295,
| |
| 0, | | 0, |
| 0, | | 0, |
| 0, | | 0, |
| + | 4294901760, |
| 0, | | 0, |
| 0, | | 0, |
Line 271: |
Line 282: |
| "clear_tid_addr": 0, | | "clear_tid_addr": 0, |
| "gpregs": { | | "gpregs": { |
− | "gs": 0, | + | "gs": "0x0", |
− | "ip": 140137968588056, | + | "ip": "0x7f172cf1ea04", |
− | "cx": 18446744073709551615, | + | "cx": "0xffffffffffffffff", |
− | "cs": 51, | + | "cs": "0x33", |
− | "ax": 61, | + | "ax": "0x38", |
− | "orig_ax": 61, | + | "orig_ax": "0x38", |
− | "di": 18446744073709551615, | + | "di": "0x1200011", |
− | "es": 0, | + | "es": "0x0", |
− | "gs_base": 0, | + | "gs_base": "0x0", |
− | "r14": 0, | + | "r14": "0x0", |
− | "r15": 4294967295, | + | "r15": "0x2355e00", |
− | "r12": 21789168, | + | "r12": "0x7ffffdbf74f0", |
− | "r13": 0, | + | "r13": "0x0", |
− | "r10": 0, | + | "r10": "0x7f172d83d9d0", |
− | "r11": 582, | + | "r11": "0x246", |
− | "fs_base": 140137978173184, | + | "fs_base": "0x7f172d83d700", |
− | "bp": 2560, | + | "bp": "0x7ffffdbf7530", |
− | "dx": 0, | + | "dx": "0x0", |
− | "bx": 0, | + | "bx": "0x0", |
− | "ds": 0, | + | "ds": "0x0", |
− | "ss": 43, | + | "ss": "0x2b", |
− | "sp": 140736135950616, | + | "sp": "0x7ffffdbf74f0", |
− | "r8": 21789168, | + | "r8": "0x0", |
− | "r9": 0, | + | "r9": "0x0", |
− | "fs": 0, | + | "fs": "0x0", |
− | "si": 140736135950656, | + | "si": "0x0", |
− | "flags": 582 | + | "flags": "0x246" |
| } | | } |
| }, | | }, |
Line 323: |
Line 334: |
| "cg_set": 1, | | "cg_set": 1, |
| "signals_s": {}, | | "signals_s": {}, |
− | "blk_sigset": 65536, | + | "blk_sigset": "0x10002", |
| "exit_code": 0, | | "exit_code": 0, |
| "rlimits": { | | "rlimits": { |
Line 352: |
Line 363: |
| }, | | }, |
| { | | { |
− | "max": 62845, | + | "max": 62844, |
− | "cur": 62845 | + | "cur": 62844 |
| }, | | }, |
| { | | { |
Line 372: |
Line 383: |
| }, | | }, |
| { | | { |
− | "max": 62845, | + | "max": 62844, |
− | "cur": 62845 | + | "cur": 62844 |
| }, | | }, |
| { | | { |
Line 404: |
Line 415: |
| </div> | | </div> |
| </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 === | | === Generate core files out of task images === |
| | | |
− | {{Status|not ready}}
| + | Moved into separate project called [[criu-coredump]]. |
| + | |
| + | === Show images statistics === |
| | | |
− | All the needed information is in core-$pid.img and pagemap-$pid.img
| + | <code>crit x</code> allows you to explore image statistics. |
| + | E.g. Total number of processes, files, memory, sockets, etc. |
| | | |
− | === On-the-fly conversion ===
| + | <pre> |
| + | crit x $directory_with_images <explore type> |
| + | </pre> |
| + | |
| + | Supported explorers are |
| + | ;'ps' |
| + | :to show process tree |
| + | |
| + | ;'fds' |
| + | :to show files used by tasks |
| | | |
− | {{Status|not ready}}
| + | ;'mems' |
| + | :to show memory mappings info |
| | | |
− | There's an idea to make CRIU spawn CRIT and read images "through" it, to allow for at-the-restore-time modifications
| + | === Show images Info === |
| | | |
− | === Convert between different image versions === | + | 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> |
| | | |
− | {{Status|not ready}}
| + | == Planned functionality == |
| | | |
− | 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.
| + | === On-the-fly conversion === |
| | | |
− | === Show images statistics ===
| + | 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. |
| | | |
− | {{Status|not ready}}
| + | === Convert between different image versions === |
| | | |
− | E.g. -- total number of processes, files, memory, sockets, etc.
| + | 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/validate images === |
− |
| |
− | {{Status|not ready}}
| |
| | | |
| Check that | | Check that |
| * all images are present | | * all images are present |
| * the inter-images IDs are in consistent state | | * 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:Images]] |
| [[Category:API]] | | [[Category:API]] |