1# Advanced Usage 2 3To see the usage information for your version of crosvm, run `crosvm` or `crosvm run --help`. 4 5## Boot a Kernel 6 7To run a very basic VM with just a kernel and default devices: 8 9```sh 10crosvm run "${KERNEL_PATH}" 11``` 12 13The compressed kernel image, also known as bzImage, can be found in your kernel build directory in 14the case of x86 at `arch/x86/boot/bzImage`. 15 16## Rootfs 17 18### With a disk image 19 20In most cases, you will want to give the VM a virtual block device to use as a root file system: 21 22```sh 23crosvm run -b "${ROOT_IMAGE},root,ro" "${KERNEL_PATH}" 24``` 25 26The root image must be a path to a disk image formatted in a way that the kernel can read. Typically 27this is a squashfs image made with `mksquashfs` or an ext4 image made with `mkfs.ext4`. By 28specifying the `root` flag, the kernel is automatically told to use that image as the root, and 29therefore it can only be given once. The `ro` flag also makes the disk image read-only for the 30guest. More disks images can be given with `-b` or `--block` if needed. 31 32To run crosvm with a writable rootfs, just remove the `ro` flag from the command-line above. 33 34> **WARNING:** Writable disks are at risk of corruption by a malicious or malfunctioning guest OS. 35 36Without the `root` flag, mounting a disk image as the root filesystem requires to pass the 37corresponding kernel argument manually using the `-p` option: 38 39```sh 40crosvm run --block "${ROOT_IMAGE}" -p "root=/dev/vda" bzImage 41``` 42 43> **NOTE:** If more disks arguments are added prior to the desired rootfs image, the `root=/dev/vda` 44> must be adjusted to the appropriate letter. 45 46### With virtiofs 47 48Linux kernel 5.4+ is required for using virtiofs. This is convenient for testing. The file system 49must be named "mtd\*" or "ubi\*". 50 51```sh 52crosvm run --shared-dir "/:mtdfake:type=fs:cache=always" \ 53 -p "rootfstype=virtiofs root=mtdfake" bzImage 54``` 55 56## Device emulation 57 58Crosvm supports several emulated devices and 15+ types of virtio devices. See 59["Device" chapter](../devices/index.md) for the details. 60 61## Control Socket 62 63If the control socket was enabled with `-s`, the main process can be controlled while crosvm is 64running. To tell crosvm to stop and exit, for example: 65 66> **NOTE:** If the socket path given is for a directory, a socket name underneath that path will be 67> generated based on crosvm's PID. 68 69```sh 70crosvm run -s /run/crosvm.sock ${USUAL_CROSVM_ARGS} 71 <in another shell> 72crosvm stop /run/crosvm.sock 73``` 74 75> **WARNING:** The guest OS will not be notified or gracefully shutdown. 76 77This will cause the original crosvm process to exit in an orderly fashion, allowing it to clean up 78any OS resources that might have stuck around if crosvm were terminated early. 79 80## Multiprocess Mode 81 82By default crosvm runs in multiprocess mode. Each device that supports running inside of a sandbox 83will run in a jailed child process of crosvm. The sandbox can be disabled for testing with the 84`--disable-sandbox` option. 85 86## GDB Support 87 88crosvm supports [GDB Remote Serial Protocol] to allow developers to debug guest kernel via GDB 89(**x86_64 or AArch64 only**). 90 91You can enable the feature by `--gdb` flag: 92 93```sh 94# Use uncompressed vmlinux 95crosvm run --gdb <port> ${USUAL_CROSVM_ARGS} vmlinux 96``` 97 98Then, you can start GDB in another shell. 99 100```sh 101gdb vmlinux 102(gdb) target remote :<port> 103(gdb) hbreak start_kernel 104(gdb) c 105<start booting in the other shell> 106``` 107 108For general techniques for debugging the Linux kernel via GDB, see this [kernel documentation]. 109 110## Defaults 111 112The following are crosvm's default arguments and how to override them. 113 114- 256MB of memory (set with `-m`) 115- 1 virtual CPU (set with `-c`) 116- no block devices (set with `-b`, `--block`) 117- no network device (set with `--net`) 118- only the kernel arguments necessary to run with the supported devices (add more with `-p`) 119- run in multiprocess mode (run in single process mode with `--disable-sandbox`) 120- no control socket (set with `-s`) 121 122## Exit code 123 124Crosvm will exit with a non-zero exit code on failure. 125 126See [CommandStatus](https://crosvm.dev/doc/crosvm/enum.CommandStatus.html) for meaning of the major 127exit codes. 128 129## Hypervisor 130 131The default hypervisor back can be overriden using `--hypervisor=<backend>`. 132 133The available backends are: 134 135- On Linux: "kvm" 136- On Windows: "whpx", "haxm", "ghaxm", "gvm" 137 138See the ["Hypervisors" chapter](../hypervisors.md) for more information. 139 140[gdb remote serial protocol]: https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html 141[kernel documentation]: https://www.kernel.org/doc/html/latest/dev-tools/gdb-kernel-debugging.html 142