From 2b97c87acc213a58aca7e56c6994bdaf36170b02 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 01:51:06 -0700 Subject: [PATCH 1/9] Clarified container setup instructions --- README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c180b43..fcf7468 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,13 @@ 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: +0. Clone this repository if you haven't done so already. 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). +2. 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`. 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 you to move files between the container and your system. @@ -56,9 +58,12 @@ To use P4-in-a-Bottle with Singularity: If you are stuck with docker, don't panic! The instructions are longer but everything should still work. +0. Clone this repository if you haven't done so already. 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`. +2. 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`. 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 From 7c00f217b92ec53a1a5caa2defc1c2b3543526c4 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 01:52:46 -0700 Subject: [PATCH 2/9] Relabel step 0 as step 1 in README.md since gitea hides step 0. --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index fcf7468..a4ea3f8 100644 --- a/README.md +++ b/README.md @@ -44,29 +44,29 @@ 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: -0. Clone this repository if you haven't done so already. -1. Install singularity from [GitHub](https://github.com/sylabs/singularity/releases). -2. Download a pre-built image +1. Clone this repository if you haven't done so already. +2. Install singularity from [GitHub](https://github.com/sylabs/singularity/releases). +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`. 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 +4. Run `make sc-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. -0. Clone this repository if you haven't done so already. -1. Install docker on your system. This should be pretty self-explanatory. -2. Download a pre-built image +1. Clone this repository if you haven't done so already. +2. Install docker on your system. This should be pretty self-explanatory. +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`. 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 +4. Run `make run`. A shared directory `shared/` will be created to allow you to move files between the container and your system. From a8ca4ba9eb922608de97b95ae18744a925e496c7 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 02:07:15 -0700 Subject: [PATCH 3/9] Added steps in README.md to prevent make image rebuild --- README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a4ea3f8..f0fbdc4 100644 --- a/README.md +++ b/README.md @@ -44,29 +44,32 @@ 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. Clone this repository if you haven't done so already. -2. Install singularity from [GitHub](https://github.com/sylabs/singularity/releases). +1. Install singularity from [GitHub](https://github.com/sylabs/singularity/releases). +2. Clone and enter 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`. 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). -4. Run `make sc-run`. A shared directory `shared/` will be created to allow + and place it in the same directory alongside `README.md`. +4. Run `touch .docker_build p4iab.tar.gz p4iab.sif`. This prevents make from + building the container from source. 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). +5. Run `make sc-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. -1. Clone this repository if you haven't done so already. -2. Install docker on your system. This should be pretty self-explanatory. +1. Install docker on your system. This should be pretty self-explanatory. +2. Clone and enter 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`. 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. -4. Run `make run`. A shared directory `shared/` will be created to allow + `docker load -i p4iab.tar.gz` to import the container into docker. +4. Run `touch .docker_build`. This tricks make into skipping the docker build + commands. If you skip this step YOU WILL BUILD THE DOCKER CONTAINER FROM + SOURCE. Do so only if you know what you are doing. +5. Run `make run`. A shared directory `shared/` will be created to allow you to move files between the container and your system. From 102b065fabae1e467bb6764dfd633d8079b92450 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 03:45:12 -0700 Subject: [PATCH 4/9] Enhanced Makefile runscript and simplified using pre-built images --- Makefile | 20 ++++++++++++++------ README.md | 20 ++++++++------------ 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/Makefile b/Makefile index b1281b5..3700235 100644 --- a/Makefile +++ b/Makefile @@ -21,13 +21,21 @@ p4iab.sif: p4iab.def p4iab.tar.gz sudo "$(SINGULARITY)" 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? \ + && 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" "$<" +sc-run: + @mkdir -p "$(SHARED_DIR)" "$(OVERLAY_DIR)" + @test -e p4iab.sif \ + || (echo Cannot find p4iab.sif, has it been built yet? \ + && false) + @sudo singularity 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 f0fbdc4..650d1f4 100644 --- a/README.md +++ b/README.md @@ -45,15 +45,11 @@ instructions below. To use P4-in-a-Bottle with Singularity: 1. Install singularity from [GitHub](https://github.com/sylabs/singularity/releases). -2. Clone and enter this repository. +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 `touch .docker_build p4iab.tar.gz p4iab.sif`. This prevents make from - building the container from source. 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). -5. Run `make sc-run`. A shared directory `shared/` will be created to allow +4. Run `make sc-run`. A shared directory `shared/` will be created to allow you to move files between the container and your system. ### Docker @@ -61,14 +57,11 @@ To use P4-in-a-Bottle with Singularity: If you are stuck with docker, don't panic! The instructions are longer but everything should still work. 1. Install docker on your system. This should be pretty self-explanatory. -2. Clone and enter this repository. +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`. Then run - `docker load -i p4iab.tar.gz` to import the container into docker. -4. Run `touch .docker_build`. This tricks make into skipping the docker build - commands. If you skip this step YOU WILL BUILD THE DOCKER CONTAINER FROM - SOURCE. Do so only if you know what you are doing. + 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. @@ -95,3 +88,6 @@ $ make p4iab.sif $ 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. + From 39a5f2ed32804616be2a40d51961e39ec63f8d62 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 03:47:13 -0700 Subject: [PATCH 5/9] Print Makefile error messages to stderr --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 3700235..05718c8 100644 --- a/Makefile +++ b/Makefile @@ -24,7 +24,7 @@ p4iab.sif: p4iab.def p4iab.tar.gz run: @mkdir -p "$(SHARED_DIR)" @test -n "$(shell docker image ls -q p4iab)" \ - || (echo Cannot find image p4iab:latest, has it been built yet? \ + || (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 @@ -32,7 +32,7 @@ run: sc-run: @mkdir -p "$(SHARED_DIR)" "$(OVERLAY_DIR)" @test -e p4iab.sif \ - || (echo Cannot find p4iab.sif, has it been built yet? \ + || (echo Cannot find p4iab.sif, has it been built yet? 1>&2 \ && false) @sudo singularity run --allow-setuid --overlay "$(OVERLAY_DIR)" \ -B "$(SHARED_DIR):/home/p4/shared" p4iab.sif From d8adf910a9603047d703e91c7c238cb4349de488 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 11:04:56 -0700 Subject: [PATCH 6/9] Updated references to singulartiy in README with apptainer --- Makefile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 05718c8..c073005 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 @@ -18,7 +18,7 @@ p4iab.tar.gz: .docker_build "$(DOCKER)" save p4iab:latest | gzip > "$@" p4iab.sif: p4iab.def p4iab.tar.gz - sudo "$(SINGULARITY)" build "$@" "$<" + sudo "$(APPTAINER)" build "$@" "$<" sudo chown $(UID):$(GID) "$@" run: @@ -29,12 +29,12 @@ run: @"$(DOCKER)" run --rm -it --privileged -v "$(SHARED_DIR):/home/p4/shared" \ -e TERM -u p4 --entrypoint p4iab_docker_entry.sh p4iab:latest -sc-run: +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) - @sudo singularity run --allow-setuid --overlay "$(OVERLAY_DIR)" \ + @sudo $(APPTAINER) run --allow-setuid --overlay "$(OVERLAY_DIR)" \ -B "$(SHARED_DIR):/home/p4/shared" p4iab.sif clean: From a07e8e94ed5662126dd0eb6d1b2802bfe595df4d Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 11:07:14 -0700 Subject: [PATCH 7/9] README.md: Update sc-run to app-run --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 650d1f4..8fa248f 100644 --- a/README.md +++ b/README.md @@ -24,32 +24,32 @@ 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. 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 +Apptainer 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 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). +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 sc-run`. A shared directory `shared/` will be created to allow +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 @@ -81,7 +81,7 @@ $ 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 From 4584f35f7b1c1224dbf08e5db8b1032e94d0f02d Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Thu, 18 May 2023 15:55:05 -0700 Subject: [PATCH 8/9] Backport changes from apptainer image rework --- Makefile | 2 +- README.md | 26 +++++++++++++++++++++----- p4iab.def | 4 ++-- 3 files changed, 24 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index c073005..7af33c4 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ GID := $(shell id -g) p4iab.tar.gz: .docker_build "$(DOCKER)" save p4iab:latest | gzip > "$@" -p4iab.sif: p4iab.def p4iab.tar.gz +p4iab.sif: p4iab.def .docker_build sudo "$(APPTAINER)" build "$@" "$<" sudo chown $(UID):$(GID) "$@" diff --git a/README.md b/README.md index 8fa248f..4d03535 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,19 @@ this container also has a few other advantages: 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 ---------- @@ -34,9 +47,9 @@ There are two ways of launching P4-in-a-Bottle: ### Apptainer -Apptainer 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, Apptainer only works natively on Linux, so if you're on Mac or @@ -54,8 +67,8 @@ To use P4-in-a-Bottle with Apptainer: ### 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. Clone and cd into this repository. 3. Download a pre-built image @@ -65,6 +78,9 @@ everything should still work. 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 -------------------- 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 From 06a688a3f91815ebdad363df7a66121f3d37df24 Mon Sep 17 00:00:00 2001 From: Yiyao Yu Date: Mon, 22 May 2023 18:31:09 -0700 Subject: [PATCH 9/9] Auto load overlay kernel module for apptainer --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 7af33c4..90810b9 100644 --- a/Makefile +++ b/Makefile @@ -34,6 +34,7 @@ app-run: @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