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