1# Example Usage 2 3This section will explain how to use a prebuilt Ubuntu image as the guest OS. If you want to prepare 4a kernel and rootfs by yourself, please see [Building crosvm]. 5 6The example code for this guide is available in [tools/examples] 7 8## Run a simple Guest OS (using virt-builder) 9 10To run a VM with crosvm, we need two things: A kernel binary and a rootfs. You can 11[build those yourself](./custom_kernel_rootfs.md) or use prebuilt cloud/vm images that some linux 12distributions provide. 13 14### Preparing the guest OS image 15 16One of the more convenient ways to customize these VM images is to use [virt-builder] from the 17`libguestfs-tools` package. 18 19```bash 20{{#include ../../../../tools/examples/example_simple:build}} 21``` 22 23### Extract the Kernel (And initrd) 24 25Crosvm directly runs the kernel instead of using the bootloader. So we need to extract the kernel 26binary from the image. [virt-builder] has a tool for that: 27 28```bash 29{{#include ../../../../tools/examples/example_simple:kernel}} 30``` 31 32The kernel binary is going to be saved in the same directory. 33 34Note: Most distributions use an init ramdisk, which is extracted at the same time and needs to be 35passed to crosvm as well. 36 37### Launch the VM 38 39With all the files in place, crosvm can be run: 40 41```bash 42{{#include ../../../../tools/examples/example_simple:run}} 43``` 44 45The full source for this example can be executed directly: 46 47```bash 48./tools/examples/example_simple 49``` 50 51## Add Networking Support 52 53Networking support is easiest set up with a TAP device on the host, which can be done with: 54 55```bash 56./tools/examples/setup_network 57``` 58 59The script will create a TAP device called `crosvm_tap` and sets up routing. For details, see the 60instructions for [network devices](./advanced_usage.md#network-device). 61 62With the `crosvm_tap` in place we can use it when running crosvm: 63 64```bash 65{{#include ../../../../tools/examples/example_network:run}} 66``` 67 68To use the network device in the guest, we need to assign it a static IP address. In our example 69guest this can be done via a netplan config: 70 71```yaml 72{{#include ../../../../tools/examples/guest/01-netcfg.yaml:5:}} 73``` 74 75Which can be installed when building the VM image: 76 77```bash 78{{#include ../../../../tools/examples/example_network:build}} 79``` 80 81This also allows us to use SSH to access the VM. The script above will install your 82`~/.ssh/id_rsa.pub` into the VM, so you'll be able to SSH from the host to the guest with no 83password: 84 85```bash 86ssh 192.168.10.2 87``` 88 89The full source for this example can be executed directly: 90 91```bash 92./tools/examples/example_network 93``` 94 95## Add GUI support 96 97First you'll want to add some desktop environment to the VM image: 98 99```bash 100{{#include ../../../../tools/examples/example_desktop:build}} 101``` 102 103Then you can use the `--gpu` argument to specify how gpu output of the VM should be handled. In this 104example we are using the virglrenderer backend and output into an X11 window on the host. 105 106```bash 107{{#include ../../../../tools/examples/example_desktop:run}} 108``` 109 110 111 112The full source for this example can be executed directly (Note, you may want to run 113[setup_networking](#add-networking-support) first): 114 115```bash 116./tools/examples/example_desktop 117``` 118 119[building crosvm]: ../building_crosvm.md 120[tools/examples]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/crosvm/tools/examples 121[virt-builder]: https://libguestfs.org/virt-builder.1.html 122
