diff --git a/Makefile b/Makefile index b1281b5..90810b9 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # Change this to podman if you are on RHEL8+ DOCKER ?= docker -SINGULARITY ?= singularity +APPTAINER ?= apptainer SHARED_DIR ?= ./shared OVERLAY_DIR ?= ./overlay MAX_THREADS ?= 16 @@ -17,17 +17,26 @@ GID := $(shell id -g) p4iab.tar.gz: .docker_build "$(DOCKER)" save p4iab:latest | gzip > "$@" -p4iab.sif: p4iab.def p4iab.tar.gz - sudo "$(SINGULARITY)" build "$@" "$<" +p4iab.sif: p4iab.def .docker_build + sudo "$(APPTAINER)" build "$@" "$<" sudo chown $(UID):$(GID) "$@" -run: .docker_build - mkdir -p "$(SHARED_DIR)" - "$(DOCKER)" run --rm -it --privileged -v "$(SHARED_DIR):/home/p4/shared" -e TERM -u p4 --entrypoint p4iab_docker_entry.sh p4iab:latest +run: + @mkdir -p "$(SHARED_DIR)" + @test -n "$(shell docker image ls -q p4iab)" \ + || (echo Cannot find image p4iab:latest, has it been built yet? 1>&2 \ + && false) + @"$(DOCKER)" run --rm -it --privileged -v "$(SHARED_DIR):/home/p4/shared" \ + -e TERM -u p4 --entrypoint p4iab_docker_entry.sh p4iab:latest -sc-run: p4iab.sif - mkdir -p "$(SHARED_DIR)" "$(OVERLAY_DIR)" - sudo singularity run --allow-setuid --overlay "$(OVERLAY_DIR)" -B "$(SHARED_DIR):/home/p4/shared" "$<" +app-run: + @mkdir -p "$(SHARED_DIR)" "$(OVERLAY_DIR)" + @test -e p4iab.sif \ + || (echo Cannot find p4iab.sif, has it been built yet? 1>&2 \ + && false) + @lsmod | grep overlay > /dev/null || sudo modprobe overlay + @sudo $(APPTAINER) run --allow-setuid --overlay "$(OVERLAY_DIR)" \ + -B "$(SHARED_DIR):/home/p4/shared" p4iab.sif clean: "$(DOCKER)" container prune diff --git a/README.md b/README.md index c180b43..4d03535 100644 --- a/README.md +++ b/README.md @@ -24,46 +24,63 @@ this container also has a few other advantages: 2. It can run with a variety of setups: Docker, Podman, K8S, OpenShift, etc... 3. It can be used as a basis for other P4 runtime testing suites. 4. It's much smaller than a VM image. -5. When converted into a singularity container, it can be launched as a single - binary executable. +5. When converted into a Apptainer SIF, it can be launched as a single binary + executable. + +User Tools +---------- + +The containers are built with several additional user tools already in place, +including but not limited to: + +1. `vim`/`emacs`: text editing. +2. `git`: version control. +3. `tmux`: terminal multiplexing. +3. `tshark`/`termshark`/`tcpdump`: packets inspection. +4. `htop`: visual overview of processes. +5. `man`/`less`: documentation support. How to Use ---------- There are two ways of launching P4-in-a-Bottle: -### Singularity +### Apptainer -Singularity is a container runtime by Sylabs developed specificly for software -that require low-level access to hardware (i.e. NVIDIA drivers, network -devices). This is great for P4-in-a-Bottle, since Mininet requires access to +Apptainer is a new container runtime developed specificly for software that +require low-level access to hardware (i.e. NVIDIA drivers, network devices, +etc). This is great for P4-in-a-Bottle, since Mininet requires access to networking kernel components to work. -Unfortunately, Singularity only works natively on Linux, so if you're on Mac or +Unfortunately, Apptainer only works natively on Linux, so if you're on Mac or Windows (without WSL), you're out-of-luck here and should proceed to the docker instructions below. -To use P4-in-a-Bottle with Singularity: -1. Install singularity from [GitHub](https://github.com/sylabs/singularity/releases). -2. Download a pre-built image `p4iab.sif` and place it in the same directory - as this README. If you skip this step YOU WILL BUILD BOTH THE DOCKER - CONTAINER AND THE SINGULARITY CONTAINER FROM SOURCE. (Trust me, you do NOT - want to build this yourself). -3. Run `make sc-run`. A shared directory `shared/` will be created to allow +To use P4-in-a-Bottle with Apptainer: +1. Install Apptainer from [GitHub](https://github.com/apptainer/apptainer/releases). +2. Clone and cd into this repository. +3. Download a pre-built image + [p4iab.sif](https://git.inkweaver.net/inkweaver/P4-in-a-Bottle/releases) + and place it in the same directory alongside `README.md`. +4. Run `make app-run`. A shared directory `shared/` will be created to allow you to move files between the container and your system. ### Docker -If you are stuck with docker, don't panic! The instructions are longer but -everything should still work. +If you are stuck with docker, don't panic! The instructions are slightly more +complicated but everything should still work. 1. Install docker on your system. This should be pretty self-explanatory. -2. Download a pre-built image `p4iab.tar.gz` and place it in the same directory - as this README. Then run `docker load -i p4iab.tar.gz && touch .docker_build`. - If you skip this step YOU WILL BUILD THE DOCKER CONTAINER FROM SOURCE. Do - so only if you know what you are doing. -3. Run `make run`. A shared directory `shared/` will be created to allow +2. Clone and cd into this repository. +3. Download a pre-built image + [p4iab.tar.gz](https://git.inkweaver.net/inkweaver/P4-in-a-Bottle/releases) + and place it in the same directory alongside `README.md`. +4. Run `docker load -i p4iab.tar.gz` to import the container into docker. +5. Run `make run`. A shared directory `shared/` will be created to allow you to move files between the container and your system. +Regardless of which method you run the container, you will be dropped into a +shell with the user P4. The password for the P4 user account is simply `p4`. + Building from Source -------------------- @@ -80,10 +97,13 @@ $ make .docker_build # Building a docker image that can be imported on other machines $ make p4iab.tar.gz -# Building a singularity image (This depends on the docker image) +# Building a Apptainer image (This depends on the docker image) $ make p4iab.sif # Cleanup any cached artifacts $ make clean ``` +Once you have either `p4iab.tar.gz` or `p4iab.sif`, proceed to follow the +instructions in the "How to Use" section from step 4. + diff --git a/p4iab.def b/p4iab.def index 0c7d14b..7c66301 100644 --- a/p4iab.def +++ b/p4iab.def @@ -1,5 +1,5 @@ -BootStrap: docker-archive -From: p4iab.tar.gz +BootStrap: docker-daemon +From: p4iab:latest %files scripts/p4iab_singularity_entry.sh /usr/bin/p4iab_singularity_entry.sh