<commit_before># crosvm - The Chrome OS Virtual Machine Monitor

This component, known as crosvm, runs untrusted operating systems along with
virtualized devices. 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.

## IRC

The channel #crosvm on [freenode](https://webchat.freenode.net/#crosvm) is used
for technical discussion related to crosvm development and integration.

## Getting started

### Building for CrOS

crosvm on Chromium OS is built with Portage, so it follows the same general
workflow as any `cros_workon` package. The full package name is
`chromeos-base/crosvm`.

See the [Chromium OS developer guide] for more on how to build and deploy with
Portage.

[Chromium OS developer guide]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md

### Building with Docker

See the [README](docker/README.md) from the `docker` subdirectory to learn how
to build crosvm in enviroments outside of the Chrome OS chroot.

### Building for Linux

>**NOTE:** Building for Linux natively is new and not fully supported.

First, [set up depot_tools] and use `repo` to sync down the crosvm source
tree. This is a subset of the entire Chromium OS manifest with just enough repos
to build crosvm.

```sh
mkdir crosvm
cd crosvm
repo init -g crosvm -u https://chromium.googlesource.com/chromiumos/manifest.git --repo-url=https://chromium.googlesource.com/external/repo.git
repo sync
```

A basic crosvm build links against `libcap` and `libfdt`. On a Debian-based system,
you can install `libcap-dev` and `libfdt-dev`.

Handy Debian one-liner for all build and runtime deps, particularly if you're
running Crostini:
```sh
sudo apt install build-essential libcap-dev libfdt-dev pkg-config python
```

Known issues:
*   Seccomp policy files have hardcoded absolute paths. You can either fix up
    the paths locally, or set up an awesome hacky symlink: `sudo mkdir
    /usr/share/policy && sudo ln -s /path/to/crosvm/seccomp/x86_64
    /usr/share/policy/crosvm`. We'll eventually build the precompiled
    policies [into the crosvm binary](http://crbug.com/1052126).
*   Devices can't be jailed if `/var/empty` doesn't exist. `sudo mkdir -p
    /var/empty` to work around this for now.

And that's it! You should be able to `cargo build/run/test`.

[set up depot_tools]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up

## 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:

```bash
$ 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:

```bash
$ 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<commit_msg>README: Document permissions needed for running.<commit_after># crosvm - The Chrome OS Virtual Machine Monitor

This component, known as crosvm, runs untrusted operating systems along with
virtualized devices. 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.

## IRC

The channel #crosvm on [freenode](https://webchat.freenode.net/#crosvm) is used
for technical discussion related to crosvm development and integration.

## Getting started

### Building for CrOS

crosvm on Chromium OS is built with Portage, so it follows the same general
workflow as any `cros_workon` package. The full package name is
`chromeos-base/crosvm`.

See the [Chromium OS developer guide] for more on how to build and deploy with
Portage.

[Chromium OS developer guide]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md

### Building with Docker

See the [README](docker/README.md) from the `docker` subdirectory to learn how
to build crosvm in enviroments outside of the Chrome OS chroot.

### Building for Linux

>**NOTE:** Building for Linux natively is new and not fully supported.

First, [set up depot_tools] and use `repo` to sync down the crosvm source
tree. This is a subset of the entire Chromium OS manifest with just enough repos
to build crosvm.

```sh
mkdir crosvm
cd crosvm
repo init -g crosvm -u https://chromium.googlesource.com/chromiumos/manifest.git --repo-url=https://chromium.googlesource.com/external/repo.git
repo sync
```

A basic crosvm build links against `libcap` and `libfdt`. On a Debian-based system,
you can install `libcap-dev` and `libfdt-dev`.

Handy Debian one-liner for all build and runtime deps, particularly if you're
running Crostini:
```sh
sudo apt install build-essential libcap-dev libfdt-dev pkg-config python
```

Known issues:
*   Seccomp policy files have hardcoded absolute paths. You can either fix up
    the paths locally, or set up an awesome hacky symlink: `sudo mkdir
    /usr/share/policy && sudo ln -s /path/to/crosvm/seccomp/x86_64
    /usr/share/policy/crosvm`. We'll eventually build the precompiled
    policies [into the crosvm binary](http://crbug.com/1052126).
*   Devices can't be jailed if `/var/empty` doesn't exist. `sudo mkdir -p
    /var/empty` to work around this for now.
*   You need read/write permissions for `/dev/kvm` to run tests or other crosvm
    instances. Usually it's owned by the `kvm` group, so `sudo usermod -a -G kvm
    $USER` and then log out and back in again to fix this.
*   Some other features (networking) require `CAP_NET_ADMIN` so those usually
    need to be run as root.

And that's it! You should be able to `cargo build/run/test`.

[set up depot_tools]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up

## 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:

```bash
$ 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:

```bash
$ 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
{'fraction_non_alphanumeric': 0.0832244008714597, 'fraction_numerical': 0.004357298474945534, 'mean_word_length': 4.2009063444108765, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '431317', 'n_tokens_mistral': 2214, 'n_tokens_neox': 2050, 'n_words': 931}