No description
Find a file
Daniel Verkamp 35bac991e6 presubmit: add cargo fmt check
This will automatically check rustfmt during 'repo upload'.

BUG=chromium:908640
TEST=repo upload
CQ-DEPEND=CL:1352648

Change-Id: I97911e00de2f25f0827c37b9715f7f77a504d2fa
Signed-off-by: Daniel Verkamp <dverkamp@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1351693
Reviewed-by: Zach Reizner <zachr@chromium.org>
2018-12-04 00:11:31 -08:00
9s uprev crosvm and 9s libc to 0.2.44 2018-11-27 19:13:44 -08:00
aarch64 aarch64: report PCI interrupts as level triggered 2018-11-16 05:02:22 -08:00
arch lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
bit_field macros: Format code inside of quote! invocations 2018-11-21 05:52:46 -08:00
crosvm_plugin crosvm_plugin: Remove underscores in variable name 2018-11-20 18:27:40 -08:00
data_model data_model: prevent unaligned DataInit::from_slice 2018-12-03 20:32:05 -08:00
devices lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
fuzz Add kernel_loader fuzzing 2018-01-12 22:37:48 -08:00
gpu_buffer lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
gpu_display gpu_display: use syslog for display_wl 2018-10-22 17:38:06 -07:00
gpu_renderer gpu_renderer: cargo fmt epoxy_egl.rs, which is huge 2018-10-09 21:14:06 -07:00
io_jail lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
kernel_cmdline cargo fmt all source code 2018-10-09 21:14:05 -07:00
kernel_loader lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
kokoro crosvm: update kokoro docker file to install libusb-1.0 2018-12-01 01:08:50 -08:00
kvm crosvm: use msg_socket in vm_control 2018-11-19 16:28:35 -08:00
kvm_sys lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
msg_socket lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
net_sys lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
net_util lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
p9 macros: Update syn to 0.15 2018-11-21 05:52:45 -08:00
plugin_proto cargo fmt all source code 2018-10-09 21:14:05 -07:00
qcow lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
qcow_utils qcow_utils: do not close given fds in convert_to_* functions 2018-11-16 05:01:42 -08:00
resources wl: silence unused code warnings 2018-11-21 05:52:54 -08:00
seccomp devices: block: fix seccomp failures from free() 2018-10-31 12:42:43 -07:00
src linux: Clean up a misleading loop 2018-12-03 20:32:14 -08:00
sys_util lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
syscall_defines cargo fmt all source code 2018-10-09 21:14:05 -07:00
tests crosvm: add getpid and prlimit to seccomp 2018-10-23 02:55:29 -07:00
usb_util lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
vhost cargo fmt all source code 2018-10-09 21:14:05 -07:00
virtio_sys cargo fmt all source code 2018-10-09 21:14:05 -07:00
vm_control lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
x86_64 lint: Resolve the easier clippy lints 2018-12-03 20:32:03 -08:00
.gitignore gitignore: Remove Cargo.lock 2017-06-17 01:12:44 -07:00
.rustfmt.toml Add basic rustfmt config 2018-09-15 20:58:19 -07:00
build_test add build_test script to automate crosvm test running 2017-09-01 12:39:19 -07:00
build_test.py crosvm: set ARM_TRIPLE to armv7a-cros-linux-gnueabihf 2018-09-26 10:33:18 -07:00
Cargo.lock usb_util: Create libusb wrapper 2018-12-01 01:08:35 -08:00
Cargo.toml usb_util: Create libusb wrapper 2018-12-01 01:08:35 -08:00
LICENSE add LICENSE and README 2017-04-17 14:06:21 -07:00
PRESUBMIT.cfg presubmit: add cargo fmt check 2018-12-04 00:11:31 -08:00
README.md toolchain: The latest stable version is required 2018-11-20 05:52:41 -08:00
rust-toolchain toolchain: Add rust-toolchain file 2018-11-20 05:52:35 -08:00

crosvm - The Chrome OS Virtual Machine Monitor

This component, known as crosvm, runs untrusted operating systems along with virtualized devices. No actual hardware is emulated. This only runs VMs through the Linux's KVM interface. What makes crosvm unique is a focus on safety within the programming language and a sandbox around the virtual devices to protect the kernel from attack in case of an exploit in the devices.

Usage

To see the usage information for your version of crosvm, run crosvm or crosvm run --help.

Boot a Kernel

To run a very basic VM with just a kernel and default devices:

$ crosvm run "${KERNEL_PATH}"

The uncompressed kernel image, also known as vmlinux, can be found in your kernel build directory in the case of x86 at arch/x86/boot/compressed/vmlinux.

Rootfs

In most cases, you will want to give the VM a virtual block device to use as a root file system:

$ crosvm run -r "${ROOT_IMAGE}" "${KERNEL_PATH}"

The root image must be a path to a disk image formatted in a way that the kernel can read. Typically this is a squashfs image made with mksquashfs or an ext4 image made with mkfs.ext4. By using the -r argument, the kernel is automatically told to use that image as the root, and therefore can only be given once. More disks can be given with -d or --rwdisk if a writable disk is desired.

To run crosvm with a writable rootfs:

WARNING: Writable disks are at risk of corruption by a malicious or malfunctioning guest OS.

crosvm run --rwdisk "${ROOT_IMAGE}" -p "root=/dev/vda" vmlinux

NOTE: If more disks arguments are added prior to the desired rootfs image, the root=/dev/vda must be adjusted to the appropriate letter.

Control Socket

If the control socket was enabled with -s, the main process can be controlled while crosvm is running. To tell crosvm to stop and exit, for example:

NOTE: If the socket path given is for a directory, a socket name underneath that path will be generated based on crosvm's PID.

$ crosvm run -s /run/crosvm.sock ${USUAL_CROSVM_ARGS}
    <in another shell>
$ crosvm stop /run/crosvm.sock

WARNING: The guest OS will not be notified or gracefully shutdown.

This will cause the original crosvm process to exit in an orderly fashion, allowing it to clean up any OS resources that might have stuck around if crosvm were terminated early.

Multiprocess Mode

By default crosvm runs in multiprocess mode. Each device that supports running inside of a sandbox will run in a jailed child process of crosvm. The appropriate minijail seccomp policy files must be present either in /usr/share/policy/crosvm or in the path specified by the --seccomp-policy-dir argument. The sandbox can be disabled for testing with the --disable-sandbox option.

Virtio Wayland

Virtio Wayland support requires special support on the part of the guest and as such is unlikely to work out of the box unless you are using a Chrome OS kernel along with a termina rootfs.

To use it, ensure that the XDG_RUNTIME_DIR enviroment variable is set and that the path $XDG_RUNTIME_DIR/wayland-0 points to the socket of the Wayland compositor you would like the guest to use.

Defaults

The following are crosvm's default arguments and how to override them.

  • 256MB of memory (set with -m)
  • 1 virtual CPU (set with -c)
  • no block devices (set with -r, -d, or --rwdisk)
  • no network (set with --host_ip, --netmask, and --mac)
  • virtio wayland support if XDG_RUNTIME_DIR enviroment variable is set (disable with --no-wl)
  • only the kernel arguments necessary to run with the supported devices (add more with -p)
  • run in single process mode (run in multiprocess mode with -u)
  • no control socket (set with -s)

System Requirements

A Linux kernel with KVM support (check for /dev/kvm) is required to run crosvm. In order to run certain devices, there are additional system requirements:

  • virtio-wayland - The memfd_create syscall, introduced in Linux 3.17, and a Wayland compositor.
  • vsock - Host Linux kernel with vhost-vsock support, introduced in Linux 4.8.
  • multiprocess - Host Linux kernel with seccomp-bpf and Linux namespaceing support.
  • virtio-net - Host Linux kernel with TUN/TAP support (check for /dev/net/tun) and running with CAP_NET_ADMIN privileges.

Emulated Devices

Device Description
CMOS/RTC Used to get the current calendar time.
i8042 Used by the guest kernel to exit crosvm.
serial x86 I/O port driven serial devices that print to stdout and take input from stdin.
virtio-block Basic read/write block device.
virtio-net Device to interface the host and guest networks.
virtio-rng Entropy source used to seed guest OS's entropy pool.
virtio-vsock Enabled VSOCKs for the guests.
virtio-wayland Allowed guest to use host Wayland socket.

Contributing

Code Health

build_test

There are no automated tests run before code is committed to crosvm. In order to maintain sanity, please execute build_test before submitting code for review. All tests should be passing or ignored and there should be no compiler warnings or errors. All supported architectures are built, but only tests for x86_64 are run. In order to build everything without failures, sysroots must be supplied for each architecture. See build_test -h for more information.

rustfmt

All code should be formatted with rustfmt. Run cargo fmt --all to autoformat your code before checking in a change.

Dependencies

With a few exceptions, external dependencies inside of the Cargo.toml files are not allowed. The reason being that community made crates tend to explode the binary size by including dozens of transitive dependencies. All these dependencies also must be reviewed to ensure their suitability to the crosvm project. Currently allowed crates are:

  • byteorder - A very small library used for endian swaps.
  • gcc - Build time dependency needed to build C source code used in crosvm.
  • libc - Required to use the standard library, this crate is a simple wrapper around libc's symbols.

Code Overview

The crosvm source code is written in Rust and C. To build, crosvm generally requires the most recent stable version of rustc.

Source code is organized into crates, each with their own unit tests. These crates are:

  • crosvm - The top-level binary front-end for using crosvm.
  • devices - Virtual devices exposed to the guest OS.
  • io_jail - Creates jailed process using libminijail.
  • kernel_loader - Loads elf64 kernel files to a slice of memory.
  • kvm_sys - Low-level (mostly) auto-generated structures and constants for using KVM.
  • kvm - Unsafe, low-level wrapper code for using kvm_sys.
  • net_sys - Low-level (mostly) auto-generated structures and constants for creating TUN/TAP devices.
  • net_util - Wrapper for creating TUN/TAP devices.
  • sys_util - Mostly safe wrappers for small system facilities such as eventfd or syslog.
  • syscall_defines - Lists of syscall numbers in each architecture used to make syscalls not supported in libc.
  • vhost - Wrappers for creating vhost based devices.
  • virtio_sys - Low-level (mostly) auto-generated structures and constants for interfacing with kernel vhost support.
  • vm_control - IPC for the VM.
  • x86_64 - Support code specific to 64 bit intel machines.

The seccomp folder contains minijail seccomp policy files for each sandboxed device. Because some syscalls vary by architecturs, the seccomp policies are split by architecture.