Implement a VM memory dump API

[SpiffyEight77]

Description

• Implement a VM memory dump API
• close Implement a VM memory dump API #1393

Details

• OS: Ubuntu 24.04
• Arch: x86_64

Test result

CLI

root@playground:~# incus debug
Description:
  Debug commands for instances

Usage:
  incus debug [command]

Available Commands:
  get-instance-memory Export a virtual machine's memory state

Global Flags:
      --debug          Show all debug messages
      --force-local    Force using the local unix socket
  -h, --help           Print help
      --project        Override the source project
  -q, --quiet          Don't show progress information
      --sub-commands   Use with help or --help to view sub-commands
  -v, --verbose        Show all information messages
      --version        Print version number

Use "incus debug [command] --help" for more information about a command.

debug instance memory

root@playground:~# incus ls
+-----------+---------+----------------------+-------------------------------------------------+-----------------+-----------+
|   NAME    |  STATE  |         IPV4         |                      IPV6                       |      TYPE       | SNAPSHOTS |
+-----------+---------+----------------------+-------------------------------------------------+-----------------+-----------+
| ubuntu-vm | RUNNING | 10.46.82.14 (enp5s0) | fd42:a560:1040:84ee:216:3eff:fe71:18f2 (enp5s0) | VIRTUAL-MACHINE | 0         |
+-----------+---------+----------------------+-------------------------------------------------+-----------------+-----------+

root@playground:~# incus debug get-instance-memory ubuntu-vm /tmp/memory.elf
Memory dump completed successfully!

root@playground:~# ll /tmp/memory.elf
-r-------- 1 nobody nogroup 1065158131 Jan 21 15:12 /tmp/memory.elf

Analyze the memory dump file with volatility3

root@playground:~# source volatility3/venv/bin/activate
(venv) root@playground:~# vol -f /tmp/memory.elf linux.lsmod
Volatility 3 Framework 2.18.0
Progress:  100.00               Stacking attempts finished
Offset  Name    Size

0xffffc07ae8c0  kvm_amd 155648
0xffffc07896c0  ccp     110592
0xffffc072db40  kvm     1036288
0xffffc05fb240  crct10dif_pclmul        16384
0xffffc05f6240  crc32_pclmul    16384
0xffffc04e3440  ghash_clmulni_intel     16384
0xffffc05b9140  sha256_ssse3    32768
0xffffc056e8c0  sha1_ssse3      32768
0xffffc04fd480  binfmt_misc     24576
0xffffc055afc0  aesni_intel     376832
0xffffc0508100  nls_iso8859_1   16384
0xffffc0503040  crypto_simd     16384
0xffffc04f3400  virtio_gpu      73728
0xffffc04dd180  cryptd  24576
0xffffc0478000  virtio_dma_buf  16384
0xffffc04bf640  drm_kms_helper  311296
0xffffc048a6c0  joydev  32768
0xffffc0481140  input_leds      16384
0xffffc0473300  serio_raw       20480
0xffffc046b440  cec     65536
0xffffc0459ac0  rc_core 65536
0xffffc044b040  fb_sys_fops     16384
0xffffc0446000  syscopyarea     16384
0xffffc03844c0  sysfillrect     20480
0xffffc037e340  sysimgblt       16384
0xffffc0441400  vmw_vsock_virtio_transport      20480
0xffffc0439580  9p      65536
0xffffc03e0ac0  fscache 389120
0xffffc03c8580  netfs   45056
0xffffc03bbc00  vmw_vsock_virtio_transport_common       40960
0xffffc03af340  9pnet_virtio    20480
0xffffc03a5600  9pnet   90112
0xffffc038e500  vsock   49152
0xffffc03791c0  virtio_input    20480
0xffffc0304240  sch_fq_codel    20480
0xffffc02ca9c0  drm     622592
0xffffc02652c0  efi_pstore      16384
0xffffc0248780  ip_tables       32768
0xffffc023ca40  x_tables        53248
0xffffc02308c0  autofs4 49152
0xffffc0223c40  virtio_net      61440
0xffffc020f380  xhci_pci        24576
0xffffc0208080  net_failover    20480
0xffffc01fab00  ahci    49152
0xffffc01e79c0  psmouse 184320
0xffffc01b8b40  libahci 49152
0xffffc01aa100  failover        16384
0xffffc01a1580  virtio_scsi     24576
0xffffc0198340  xhci_pci_renesas        20480
0xffffc018f180  virtio_rng      16384

[SpiffyEight77]

This is my first time implementing the complete API. This feature is the minimal implementation of the dump-guest-memory command in QEMU, and there are a few issues I'm unsure about and would like to ask for help.

• File writing through QMP is blocked by AppArmor rules. My local testing was conducted in an environment with AppArmor removed, but files can only be written to the /tmp directory.
• In the API endpoint implementation, how should parameters be passed through query parameters for GET methods?
• Where should the documentation for the API and CLI be added?

I would like to receive your suggestions for modifications.🙇

[stgraber]

@SpiffyEight77 can you add the Signed-off-by line to your commits?

[SpiffyEight77]

@SpiffyEight77 can you add the Signed-off-by line to your commits?

I've now added the Signed-off-by line to all commits.
Apologies for missing this requirement earlier. 🙇🏻‍♂️

[stgraber]

Did a few tweaks:

• Added an API extension
• Renamed CLI command to incus debug dump-memory
• Changed to streaming the dump directly from the VM over the network

[SpiffyEight77]

Did a few tweaks:

• Added an API extension
• Renamed CLI command to incus debug dump-memory
• Changed to streaming the dump directly from the VM over the network

Thank you for this opportunity to learn and contribute.
I look forward to making more meaningful contributions to this project. 🙇🏻‍♂️