pH/README.md

89 lines
2.8 KiB
Markdown
Raw Normal View History

2019-09-20 18:51:59 -04:00
pH Hypervisor
=============
pH is a KVM hypervisor for Linux written in the Rust programming language as a tool
for isolating desktop application running environments in Subgraph OS.
Building pH
-----------
2019-09-20 19:54:15 -04:00
First you'll need to [install Rust](https://www.rust-lang.org/tools/install) of course.
Then make sure you have all the library build dependencies. The following apt command should pull in
everthing you need. If you don't already have build-essential installed, you'll need that too.
$ sudo apt install wget bc flex bison libelf-dev pkg-config libwayland-dev libxcb-composite0-dev libxkbcommon-dev libgbm-dev libpixman-1-dev libdrm-dev libdbus-1-dev
2019-09-20 18:51:59 -04:00
$ cargo build --release
2019-09-20 19:54:15 -04:00
If you like to watch text scroll when you build things you can add -vv to the build command:
$ cargo build --release -vv
The build will download and build a linux kernel, so it will may take a few minutes. When the build completes, the pH binary can be found at:
target/release/pH
2019-09-20 18:51:59 -04:00
Running pH
----------
After successfully building pH the only artifact you need is the pH binary itself. You can copy it
2019-09-20 18:53:41 -04:00
anywhere and use it.
2019-09-20 18:51:59 -04:00
If you run pH in citadel, you can simply pass it the name of a realm:
$ ./pH --realm main
This will use the correct realmfs image as a block device for the root filesystem and
mount the realm home directory as a 9p filesystem.
Without any arguments, pH will self-host on the current filesystem by mounting the
root directory as a read-only 9p filesystem. Currently it is assumed that the
home directory is /home/user and if you have a different home directory you'll
need to tell pH about it:
$ ./pH --home /home/citadel
By default a shell inside the pH instance will be launched as the user account,
but you can also add --root flag to launch a root shell instead:
$ ./pH --home /home/citadel --root
Devices
-------
The hardware emulation in pH consists of a minimal set of small legacy devices needed to
boot the system as well as several Virtio devices. Virtio is a standard interface
for efficient communication between a guest operating system and a hypervisor such that
the same guest drivers will work with any hypervisor implemention of the emulated
virtio devices.
### virtio-block
A block device driver.
#### Disk Images
Raw ext4 disk images are supported, as well as realmfs images, but currently they
are not mounted with dm-verity.
### virtio-9p
A 9P filesystem server which can be used to mount filesystem trees on the host into
the guest.
### virtio-rng
Provides entropy from /dev/urandom on the host to the guest.
### virtio-serial
A serial port device which is used to provide an interactive console on the guest.
### virtio-wl
Proxies Wayland messages from the guest to a wayland compositor running on the host. Also
allocates and shares memory and DMA-Buf allocations into the guest.