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.
|
|
|
|
|
|
2019-09-20 23:06:51 -04:00
|
|
|
$ 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.
|
|
|
|
|
|
|
|
|
|
|
