Skip to content

Getting Started

Jump to bottom
ahughes12 edited this page Jul 30, 2020 · 9 revisions

Getting started

This section will cover the software setup for working with Popcorn.

Software dependencies

This guide was created while using Ubuntu 16.04. It requires having git, docker compose and it's dependencies installed .

To install with apt: sudo apt install -y docker-compose git

You'll also need a base x86 VM, the image we use in this guide is provided here. This will be saved as base.img in the disks folder we define later in the guide.

Getting the code

You'll need the Popcorn library and Popcorn kernel. We'll use the branch from the first RFC in this example. To get these navigate to the directory you'd like to use, then run the following:

Popcorn kernel: git clone --depth=1 --branch=upstream-rfc https://github.com/ssrg-vt/popcorn-kernel.git

Popcorn library: git clone --depth=1 --branch=upstream https://github.com/ssrg-vt/popcorn-kernel-lib.git

An example docker-compose.yml file we'll be using is available here.

If you check the current directory you should have an output like below:

popcorn@popcorn:~$ ls
docker-compose.yml  popcorn-kernel  popcorn-kernel-lib

To set up folders for logs and other features you'll want to make folders for popcorn, you'll need to create and set the paths on the host for the following volumes in the docker-compose.yml (an example host path is /home/popcorn/gitlab/rfc/popcorn-kernel):

    - /home/popcorn/popcorn-kernel:/app/linux
    - /home/popcorn/share:/app/share
    - /home/popcorn/popcorn-kernel-lib:/app/popcorn-lib
    - /home/popcorn/disks:/app/disks
    - /home/popcorn/ccache:/app/ccache
    - /home/popcorn/logs:/app/logs

Make sure that the base.img is put into the disks subdirectory. Then we can coopy an example Linux config that is available here: cp example.config popcorn-kernel/.config

Running tests

Before running tests you'll need to make sure the tap/tun driver is loaded. You can do this with lsmod | grep tun. If it is loaded tun & the module size will be printed to the terminal. If it isn't loaded you'll need to find a way to load it for your Linux distribution.

To customize the number of nodes in the Popcorn network edit the line - NUMNODES=2.

Running the following should be enough to compile all code, start VMs, and run tests:

docker-compose up

By default docker will pull the image uploaded at Docker Hub indicated by docker-compose.yml. You may view the script the docker image executes here. The script then runs tests according to an Ansible playbook which can be found here. This Ansible playbook runs functional tests on node 0. You can customize tests by editing and bind mounting over it (in the docker-compose.yml) with your own playbook:

- /home/popcorn/popcorn_tests.yml:/app/popcorn_tests.yml

At the end of testing the container will pause, allowing you to interact with the container. If you would like tests to cleanly exit you can remove the - INTERACTIVE=1 line in the docker-compose.yml.

Interacting with the container & VMs

This is assuming that tests have been run, and the container is now waiting in interactive mode. To get a shell on the docker container:

docker exec -it popcorn_test_1 /bin/bash

You can then use screen -x $vm_number to get an interactive shell in the respective VM. To get a shell on the first popcorn node:

screen -x 0.

Additionally useful logs for each compilation step and VM can be found in the logs directory that is set in the docker-compose.yml.

Clone this wiki locally