Skip to content

Latest commit

 

History

History
118 lines (84 loc) · 3.13 KB

README.md

File metadata and controls

118 lines (84 loc) · 3.13 KB

Overview

Ward is a Spectre and Meltdown resistant research operating system based on sv6 which was in turn based on xv6.

This page is a general README for getting started with Ward. If you are looking for the directions for the OSDI '20 artifact evaluation, refer to ARTIFACT-README.md.

Compiling Ward

On Linux

You'll need a recent version of clang, GNU make, and QEMU. Generating disk images also requires mtools. On Ubuntu, this should just be a matter of:

sudo apt-get install git build-essential clang mtools qemu-system-x86

Now you should be set to run:

git clone https://github.com/mit-pdos/ward && cd ward
make -j

At this point, the output directory should now contain ward.efi which is a UEFI binary that is also multiboot compatible, meaning that can be loaded by a variety of bootloaders.

The makefile also supports generating IMG, VHDX, VMDK, and VDI disk images. These images support both MBR and UEFI booting using bundled copies of GRUB, and the resulting ward.img, ward.vhdx, ward.vmdk, and ward.vdi should be compatible with a range of hypervisors:

make -j disks

Running Ward in a VM

To launch inside QEMU just run...

make -j qemu

(To exit, press Ctrl-a x.)

Alternatively, if you want to test the generated ward.img disk image, you can run:

make -j qemu-grub

The simplest command would actually just be qemu-system-x86_64 output/ward.img, however QEMU's default settings are rather suboptimal (no hardware acceleration, 128MB of RAM, etc.)

Running Ward on real hardware

Make sure you can build and run Ward in QEMU first. For each of the following options you'll need either ward.efi or ward.img. These files should be in the output directory after running make -j or make -j disks respectively. They are also automatically generated by each GitHub CI run.

GRUB

First copy ward.efi to your /boot directory and then add the following entry to /etc/grub.d/40_custom:

menuentry "ward" {
    load_video
    echo 'GRUB: Loading ward...'
    multiboot2 /boot/ward.efi
    echo 'GRUB: Booting ward...'
}

Don't forget to run sudo update-grub or the appropriate grub-mkconfig command afterwards!

PXELINUX

Add the following entry to your pxelinux.cfg:

label ward
        say Booting ward...
        menu label ward
        kernel mboot.c32
        append -aout /path/to/ward.efi

Bootable USB Stick

Use dd to copy the contents of ward.img to a flash drive (replace sdX with the device number of your flash drive), and then select the drive as a temporary boot device from the pre-boot menu:

$ sudo dd conv=nocreat if=output/ward.img of=/dev/sdX bs=4M && sync

And if you want to make sure the drive works:

$ qemu-system-x86_64 /dev/sdX

NOTE: For reasons that we don't fully understand, this boot method is less reliable than the previous options but it still may work for you.