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 [Custom Kernel / Rootfs](./custom_kernel_rootfs.md). 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### Add the user to the kvm group 38 39To run crosvm without `sudo`, the user should be added to the `kvm` group in order to obtain the 40access to the `/dev/kvm` file. If the user is already in the kvm group, skip this part. Otherwise, 41execute the command below. 42 43```bash 44{{#include ../../../../tools/examples/example_simple:kvm}} 45``` 46 47You can check if the user is in the kvm group or not with the following command: 48 49```bash 50groups | grep kvm 51``` 52 53After executing the `adduser` command above, please logout and log back in to reflect the kvm group. 54 55### Launch the VM 56 57With all the files in place, crosvm can be run: 58 59```bash 60{{#include ../../../../tools/examples/example_simple:run}} 61``` 62 63The full source for this example can be executed directly: 64 65```bash 66./tools/examples/example_simple 67``` 68 69The login username will be the username on the host, and it will prompt to decide the password on 70the first login in the VM. 71 72## Add Networking Support 73 74Networking support is easiest set up with a TAP device on the host, which can be done with: 75 76```bash 77./tools/examples/setup_network 78``` 79 80The script will create a TAP device called `crosvm_tap` and sets up routing. For details, see the 81instructions for [network devices](../devices/net.md). 82 83With the `crosvm_tap` in place we can use it when running crosvm: 84 85```bash 86{{#include ../../../../tools/examples/example_network:run}} 87``` 88 89To use the network device in the guest, we need to assign it a static IP address. In our example 90guest this can be done via a netplan config: 91 92First, create a guest directory and the netplan config: 93 94```bash 95mkdir guest/ 96touch guest/01-netcfg.yaml 97``` 98 99Then edit guest/01-netcfg.yaml and add the following contents: 100 101```yaml 102{{#include ../../../../tools/examples/guest/01-netcfg.yaml:5:}} 103``` 104 105The netplan config can be installed when building the VM image: 106 107```bash 108{{#include ../../../../tools/examples/example_network:build}} 109``` 110 111This also allows us to use SSH to access the VM. The script above will install your 112`~/.ssh/id_rsa.pub` into the VM, so you'll be able to SSH from the host to the guest with no 113password: 114 115```bash 116ssh 192.168.10.2 117``` 118 119WARNING: If you are on a gLinux machine, then you will need to disable Corp SSH Helper: 120 121```bash 122ssh -oProxyCommand=none 192.168.10.2 123``` 124 125The full source for this example can be executed directly: 126 127```bash 128./tools/examples/example_network 129``` 130 131## Add GUI support 132 133First you'll want to add some desktop environment to the VM image: 134 135```bash 136{{#include ../../../../tools/examples/example_desktop:build}} 137``` 138 139Then you can use the `--gpu` argument to specify how gpu output of the VM should be handled. In this 140example we are using the virglrenderer backend and output into an X11 window on the host. 141 142```bash 143{{#include ../../../../tools/examples/example_desktop:run}} 144``` 145 146 147 148The full source for this example can be executed directly (Note, you may want to run 149[setup_networking](#add-networking-support) first): 150 151```bash 152./tools/examples/example_desktop 153``` 154 155[tools/examples]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/crosvm/tools/examples 156[virt-builder]: https://libguestfs.org/virt-builder.1.html 157
