Difference between revisions of "CRIT"

From CRIU
Jump to navigation Jump to search
 
(30 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This page describes the CRiu Image Tool.
+
''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 ==
 
== Usage ==
<pre>Usage: crit [-h] [-i IN] [-o OUT] [-f {raw,nice}] [-t {json}] {convert}
+
<pre>
 +
usage: crit [-h] {decode,encode,info,x,show} ...
  
 
CRiu Image Tool
 
CRiu Image Tool
  
 
positional arguments:
 
positional arguments:
   {convert}            use "covert" to convert CRIU image to/from human-
+
   {decode,encode,info,x,show}
                        readable format
+
                        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
 
  -f {raw,nice}, --format {raw,nice}
 
                        well-formated output (by default: raw for files and
 
                        nice for stdout)
 
  -t {json}, --type {json}
 
                        Type of output file (by default img is converted to
 
                        txt and vice versa)
 
 
</pre>
 
</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 ==
 
== Functionality ==
  
=== Convert images to human-readable and back ===
+
=== Convert images from IMG to JSON ===
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.
  
'''Status: Ready'''<br>
 
 
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.
Output file is structured like:
+
 
With "--format raw":
+
The output file is structured in the following way.
<pre>
+
 
#<magic value>
+
Without "--pretty":
#0
 
<pb entry in text_format>
 
....
 
#N
 
<pb entry in text_format>
 
</pre>
 
With "--format nice":
 
 
<pre>
 
<pre>
#<magic name>
+
{ "magic" : "FOO", "entries" : [{"foo": "bar", "bar": "foo", "extra": "abc"}, {"foo": "bar", "bar" : "foo", "extra" : "abc"} ]}
#0 <pb entry name>
 
<pb entry in text_format with tabs>
 
....
 
#N <pb entry name>
 
<pb entry in text_format with tabs>
 
 
</pre>
 
</pre>
  
So, here is how core file will look like with --format nice:
+
With "--pretty":
 
<pre>
 
<pre>
#CORE
+
{
#0 core_entry
+
     "magic" : "FOO",
     mtype: X86_64
+
     "entries" : [
     thread_info {
+
        {
      clear_tid_addr: 0
+
            "foo" : "bar",
      gpregs {
+
            "bar" : "foo",
        r15: 0
+
            "extra" : "abc"
        r14: 19884608
+
         },
        r13: 1
+
         {
        r12: 0
+
            "foo" : "bar",
        bp: 19879232
+
            "bar" : "foo",
        bx: 0
+
            "extra" : "abc"
        r11: 582
 
        r10: 0
 
        r9: 0
 
        r8: 19879232
 
        ax: 61
 
        cx: 18446744073709551615
 
        dx: 0
 
        si: 140733241187376
 
        di: 18446744073709551615
 
        orig_ax: 61
 
        ip: 213251769082
 
        cs: 51
 
        flags: 582
 
        sp: 140733241187336
 
        ss: 43
 
        fs_base: 140140334651200
 
        gs_base: 0
 
        ds: 0
 
        es: 0
 
        fs: 0
 
         gs: 0
 
      }
 
      fpregs {
 
        cwd: 895
 
        swd: 0
 
        twd: 0
 
         fop: 0
 
        rip: 0
 
        rdp: 0
 
        mxcsr: 8064
 
        mxcsr_mask: 65535
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        st_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 4294967295
 
        xmm_space: 4294967295
 
        xmm_space: 16777215
 
        xmm_space: 16843009
 
        xmm_space: 16843009
 
        xmm_space: 16843009
 
        xmm_space: 4478800
 
        xmm_space: 661857632
 
        xmm_space: 1869488186
 
        xmm_space: 543236212
 
        xmm_space: 1970037624
 
        xmm_space: 1680696676
 
        xmm_space: 775778921
 
        xmm_space: 544500071
 
        xmm_space: 2019896621
 
        xmm_space: 1685417059
 
        xmm_space: 1768172901
 
        xmm_space: 1747860850
 
        xmm_space: 809328999
 
        xmm_space: 909327153
 
        xmm_space: 1932405306
 
        xmm_space: 809334896
 
        xmm_space: 909327153
 
        xmm_space: 2016291386
 
        xmm_space: 1030123635
 
        xmm_space: 859517232
 
        xmm_space: 14902
 
        xmm_space: 0
 
        xmm_space: 65
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 4294967295
 
        xmm_space: 4294967295
 
        xmm_space: 4294967295
 
        xmm_space: 4294967295
 
        xmm_space: 4294967040
 
        xmm_space: 4294967295
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
        xmm_space: 0
 
      }
 
    }
 
    tc {
 
      task_state: 1
 
      exit_code: 0
 
      personality: 0
 
      flags: 1077960704
 
      blk_sigset: 65536
 
      comm: "loop.sh"
 
      timers {
 
        real {
 
          isec: 0
 
          iusec: 0
 
          vsec: 0
 
          vusec: 0
 
 
         }
 
         }
        virt {
+
     ]
          isec: 0
+
}
          iusec: 0
 
          vsec: 0
 
          vusec: 0
 
        }
 
        prof {
 
          isec: 0
 
          iusec: 0
 
          vsec: 0
 
          vusec: 0
 
        }
 
      }
 
      rlimits {
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 8388608
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 0
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 3898
 
          max: 3898
 
        }
 
        rlimits {
 
          cur: 1024
 
          max: 4096
 
        }
 
        rlimits {
 
          cur: 65536
 
          max: 65536
 
        }
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
        rlimits {
 
          cur: 3898
 
          max: 3898
 
        }
 
        rlimits {
 
          cur: 819200
 
          max: 819200
 
        }
 
        rlimits {
 
          cur: 0
 
          max: 0
 
        }
 
        rlimits {
 
          cur: 0
 
          max: 0
 
        }
 
        rlimits {
 
          cur: 18446744073709551615
 
          max: 18446744073709551615
 
        }
 
      }
 
      cg_set: 1
 
      signals_s {
 
      }
 
    }
 
     thread_core {
 
      futex_rla: 0
 
      futex_rla_len: 24
 
      sched_nice: 0
 
      sched_policy: 0
 
      sas {
 
        ss_sp: 0
 
        ss_size: 0
 
        ss_flags: 2
 
      }
 
      signals_p {
 
      }
 
    }
 
 
</pre>
 
</pre>
  
=== Convert to json (and back) ===
+
<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
 
+
<b>Example("crit decode -i core-5679.img --pretty")</b>
Same as before, but the human-readable format is JSON
+
<div class="mw-collapsible-content">
 
 
'''Status: Ready'''<br>
 
For now, it does it in a dumb way, by just wrapping text_format in brackets and adding commas where needed.
 
Example:
 
 
<pre>
 
<pre>
 
{
 
{
     "magic": "CORE",
+
     &quot;magic&quot;: &quot;CORE&quot;,  
     "0": {
+
     &quot;entries&quot;: [
        "mtype": "X86_64",  
+
        {
        "thread_core": {
+
            &quot;mtype&quot;: &quot;X86_64&quot;,  
            "futex_rla_len": "24",  
+
            &quot;thread_core&quot;: {
            "sched_policy": "0",  
+
                &quot;futex_rla_len&quot;: 24,  
            "sched_nice": "0",  
+
                &quot;sched_policy&quot;: 0,  
            "futex_rla": "0",  
+
                &quot;sched_nice&quot;: 0,  
            "signals_p": {},  
+
                &quot;futex_rla&quot;: 0,  
            "sas": {
+
                &quot;signals_p&quot;: {},  
                "ss_size": "0",  
+
                &quot;sas&quot;: {
                "ss_sp": "0",  
+
                    &quot;ss_size&quot;: 0,  
                "ss_flags": "2"
+
                    &quot;ss_sp&quot;: 0,  
            }
+
                    &quot;ss_flags&quot;: 2
        },
+
                }
        "pbtype": "core_entry",
 
        "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",
 
                "xmm_space": [
 
                    "0",
 
                    "0",
 
                    "4294967295",
 
                    "4294967295",
 
                    "16777215",
 
                    "16843009",
 
                    "16843009",
 
                    "16843009",
 
                    "4478800",
 
                    "661857632",
 
                    "1869488186",
 
                    "543236212",
 
                    "1970037624",
 
                    "1680696676",
 
                    "775778921",
 
                    "544500071",
 
                    "2019896621",
 
                    "1685417059",
 
                    "1768172901",
 
                    "1747860850",
 
                    "809328999",
 
                    "909327153",
 
                    "1932405306",
 
                    "809334896",
 
                    "909327153",
 
                    "2016291386",
 
                    "1030123635",
 
                    "859517232",
 
                    "14902",
 
                    "0",
 
                    "65",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "4294967295",
 
                    "4294967295",
 
                    "4294967295",
 
                    "4294967295",
 
                    "4294967040",
 
                    "4294967295",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0",
 
                    "0"
 
                ],
 
                "cwd": "895",
 
                "mxcsr_mask": "65535"
 
 
             },  
 
             },  
             "clear_tid_addr": "0",
+
             &quot;thread_info&quot;: {
            "gpregs": {
+
                &quot;fpregs&quot;: {
                "gs": "0",  
+
                    &quot;st_space&quot;: [
                "ip": "213251769082",  
+
                        0,
                "cx": "18446744073709551615",  
+
                        0,
                "cs": "51",  
+
                        0,
                "ax": "61",  
+
                        0,  
                "orig_ax": "61",  
+
                        0,
                "di": "18446744073709551615",  
+
                        0,
                "es": "0",  
+
                        0,
                "gs_base": "0",  
+
                        0,
                "r14": "19884608",  
+
                        0,
                "r15": "0",  
+
                        0,
                "r12": "0",  
+
                        0,
                "r13": "1",  
+
                        0,
                "r10": "0",  
+
                        0,
                "r11": "582",  
+
                        0,
                "fs_base": "140140334651200",  
+
                        0,
                "bp": "19879232",  
+
                        0,
                "dx": "0",  
+
                        0,
                "bx": "0",  
+
                        0,
                "ds": "0",  
+
                        0,
                "ss": "43",  
+
                        0,
                "sp": "140733241187336",  
+
                        0,
                "r8": "19879232",  
+
                        0,
                "r9": "0",  
+
                        0,
                "fs": "0",  
+
                        0,
                "si": "140733241187376",  
+
                        0,
                "flags": "582"
+
                        0,
            }
+
                        0,
        },  
+
                        0,
        "tc": {
+
                        0,
            "timers": {
+
                        0,
                "real": {
+
                        0,
                     "isec": "0",  
+
                        0
                     "vusec": "0",  
+
                    ],
                     "iusec": "0",  
+
                    &quot;fop&quot;: 0,  
                     "vsec": "0"
+
                    &quot;rdp&quot;: 0,  
 +
                    &quot;twd&quot;: 0,  
 +
                    &quot;mxcsr&quot;: 8064,  
 +
                    &quot;swd&quot;: 0,  
 +
                    &quot;rip&quot;: 0,  
 +
                    &quot;xsave&quot;: {
 +
                        &quot;ymmh_space&quot;: [
 +
                            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
 +
                        ],
 +
                        &quot;xstate_bv&quot;: 2
 +
                    },
 +
                     &quot;xmm_space&quot;: [
 +
                        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
 +
                     ],  
 +
                     &quot;cwd&quot;: 0,  
 +
                     &quot;mxcsr_mask&quot;: 65535
 
                 },  
 
                 },  
                 "virt": {
+
                 &quot;clear_tid_addr&quot;: 0,
                     "isec": "0",  
+
                &quot;gpregs&quot;: {
                     "vusec": "0",  
+
                     &quot;gs&quot;: &quot;0x0&quot;,
                     "iusec": "0",  
+
                    &quot;ip&quot;: &quot;0x7f172cf1ea04&quot;,
                     "vsec": "0"
+
                    &quot;cx&quot;: &quot;0xffffffffffffffff&quot;,
                },  
+
                    &quot;cs&quot;: &quot;0x33&quot;,
                "prof": {
+
                    &quot;ax&quot;: &quot;0x38&quot;,
                     "isec": "0",  
+
                    &quot;orig_ax&quot;: &quot;0x38&quot;,
                     "vusec": "0",  
+
                    &quot;di&quot;: &quot;0x1200011&quot;,
                     "iusec": "0",  
+
                    &quot;es&quot;: &quot;0x0&quot;,
                     "vsec": "0"
+
                    &quot;gs_base&quot;: &quot;0x0&quot;,
 +
                    &quot;r14&quot;: &quot;0x0&quot;,
 +
                    &quot;r15&quot;: &quot;0x2355e00&quot;,
 +
                    &quot;r12&quot;: &quot;0x7ffffdbf74f0&quot;,
 +
                    &quot;r13&quot;: &quot;0x0&quot;,
 +
                    &quot;r10&quot;: &quot;0x7f172d83d9d0&quot;,
 +
                    &quot;r11&quot;: &quot;0x246&quot;,
 +
                    &quot;fs_base&quot;: &quot;0x7f172d83d700&quot;,
 +
                    &quot;bp&quot;: &quot;0x7ffffdbf7530&quot;,
 +
                    &quot;dx&quot;: &quot;0x0&quot;,  
 +
                     &quot;bx&quot;: &quot;0x0&quot;,  
 +
                     &quot;ds&quot;: &quot;0x0&quot;,  
 +
                     &quot;ss&quot;: &quot;0x2b&quot;,
 +
                    &quot;sp&quot;: &quot;0x7ffffdbf74f0&quot;,  
 +
                    &quot;r8&quot;: &quot;0x0&quot;,
 +
                     &quot;r9&quot;: &quot;0x0&quot;,  
 +
                     &quot;fs&quot;: &quot;0x0&quot;,  
 +
                     &quot;si&quot;: &quot;0x0&quot;,  
 +
                     &quot;flags&quot;: &quot;0x246&quot;
 
                 }
 
                 }
 
             },  
 
             },  
             "cg_set": "1",
+
             &quot;tc&quot;: {
            "signals_s": {},
+
                 &quot;timers&quot;: {
            "blk_sigset": "65536",
+
                     &quot;real&quot;: {
            "exit_code": "0",
+
                         &quot;isec&quot;: 0,  
            "rlimits": {
+
                         &quot;vusec&quot;: 0,  
                 "rlimits": [
+
                         &quot;iusec&quot;: 0,  
                    {
+
                         &quot;vsec&quot;: 0
                        "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": "3898",
 
                        "cur": "3898"
 
                    },
 
                    {
 
                        "max": "4096",
 
                        "cur": "1024"
 
                    },
 
                    {
 
                        "max": "65536",
 
                        "cur": "65536"
 
                    },
 
                    {
 
                        "max": "18446744073709551615",  
 
                         "cur": "18446744073709551615"
 
                    },
 
                    {
 
                        "max": "18446744073709551615",
 
                        "cur": "18446744073709551615"
 
                    },
 
                    {
 
                        "max": "3898",
 
                        "cur": "3898"
 
                    },
 
                    {
 
                        "max": "819200",
 
                        "cur": "819200"
 
                    },
 
                    {
 
                        "max": "0",  
 
                         "cur": "0"
 
 
                     },  
 
                     },  
                     {
+
                     &quot;virt&quot;: {
                         "max": "0",  
+
                         &quot;isec&quot;: 0,
                         "cur": "0"
+
                        &quot;vusec&quot;: 0,
 +
                        &quot;iusec&quot;: 0,  
 +
                         &quot;vsec&quot;: 0
 
                     },  
 
                     },  
                     {
+
                     &quot;prof&quot;: {
                         "max": "18446744073709551615",  
+
                         &quot;isec&quot;: 0,
                         "cur": "18446744073709551615"
+
                        &quot;vusec&quot;: 0,
 +
                        &quot;iusec&quot;: 0,  
 +
                         &quot;vsec&quot;: 0
 
                     }
 
                     }
                 ]
+
                 },
            },  
+
                &quot;cg_set&quot;: 1,
            "comm": "\"loop.sh\"",  
+
                &quot;signals_s&quot;: {},
            "flags": "1077960704",  
+
                &quot;blk_sigset&quot;: &quot;0x10002&quot;,
            "task_state": "1",  
+
                &quot;exit_code&quot;: 0,
            "personality": "0"
+
                &quot;rlimits&quot;: {
 +
                    &quot;rlimits&quot;: [
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 8388608
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 0
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 62844,
 +
                            &quot;cur&quot;: 62844
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 4096,
 +
                            &quot;cur&quot;: 1024
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 65536,
 +
                            &quot;cur&quot;: 65536
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 62844,
 +
                            &quot;cur&quot;: 62844
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 819200,
 +
                            &quot;cur&quot;: 819200
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 0,
 +
                            &quot;cur&quot;: 0
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 0,
 +
                            &quot;cur&quot;: 0
 +
                        },
 +
                        {
 +
                            &quot;max&quot;: 18446744073709551615,
 +
                            &quot;cur&quot;: 18446744073709551615
 +
                        }
 +
                    ]
 +
                },  
 +
                &quot;comm&quot;: &quot;loop.sh&quot;,  
 +
                &quot;flags&quot;: 1077960704,  
 +
                &quot;task_state&quot;: 1,  
 +
                &quot;personality&quot;: 0
 +
            }
 
         }
 
         }
     }
+
     ]
 
}
 
}
 
</pre>
 
</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 ===
 
=== Generate core files out of task images ===
  
All the needed information is in core-$pid.img and pagemap-$pid.img
+
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>
  
'''Status: Not ready'''
+
Supported explorers are
 +
;'ps'
 +
:to show process tree
  
=== On-the-fly conversion ===
+
;'fds'
 +
:to show files used by tasks
  
There's an idea to make CRIU spawn CRIT and read images "through" it, to allow for at-the-restore-time modifications
+
;'mems'
 +
:to show memory mappings info
  
'''Status: Not ready'''
+
=== 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>
  
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.
+
== Planned functionality ==
  
'''Status: Not ready'''
+
=== 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.
  
E.g. -- total number of processes, files, memory, sockets, etc.
+
=== Convert between different image versions ===
  
Status: Not ready
+
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 ===
Line 602: Line 492:
 
* the inter-images IDs are in consistent state
 
* the inter-images IDs are in consistent state
  
'''Status: Not ready'''
+
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]]
[[Category:Plans]]
 

Latest revision as of 16:31, 4 November 2022

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

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

Pretty output[edit]

crit decode 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 show action or the --pretty 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 dev_t type, it's printed in the major:minor manner

Functionality[edit]

Convert images from IMG to JSON[edit]

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

It uses text_format as a human-readable format for protobuf messages.

The output file is structured in the following way.

Without "--pretty":

{ "magic" : "FOO", "entries" : [{"foo": "bar", "bar": "foo", "extra": "abc"}, {"foo": "bar", "bar" : "foo", "extra" : "abc"} ]}

With "--pretty":

{
    "magic" : "FOO",
    "entries" : [
        {
            "foo" : "bar",
            "bar" : "foo",
            "extra" : "abc"
        },
        {
            "foo" : "bar",
            "bar" : "foo",
            "extra" : "abc"
        }
    ]
}

Example("crit decode -i core-5679.img --pretty")

{
    "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
            }
        }
    ]
}

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

cat "core-5679.img" | crit decode 

Convert images from JSON to IMG[edit]

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

crit encode -i core-5679.json -o core-5679.img

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

cat "core-5679.json" | crit encode 

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

Generate core files out of task images[edit]

Moved into separate project called criu-coredump.

Show images statistics[edit]

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

crit x $directory_with_images <explore type>

Supported explorers are

'ps'
to show process tree
'fds'
to show files used by tasks
'mems'
to show memory mappings info

Show images Info[edit]

Image of a info such as its "COUNT" and "MAGIC" can be displayed using the INFO command.

Example("crit info core-5679.img")

{
    "count": 1, 
    "magic": "CORE"
}

Planned functionality[edit]

On-the-fly conversion[edit]

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

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

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

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.