Repository files navigation

This repository is no longer maintained.Please visit theapplication catalog.

This application starts an Nginx web server with Unikraft.Follow the instructions below to set up, configure, build and run Nginx.

To get started immediately, you can use Unikraft's command-line companion tool,kraft.Start by running the interactive installer:

curl --proto '=https' --tlsv1.2 -sSf https://get.kraftkit.sh | sudo sh

Once installed, clonethis repository and runkraft build:

git clone https://github.com/unikraft/app-nginx nginxcd nginx/kraft build

This will guide you through an interactive build process where you can select one of the available targets (architecture/platform combinations).Otherwise, we recommend building forqemu/x86_64 like so:

kraft build --target nginx-qemu-x86_64-initrd

Once built, you can instantiate the unikernel via:

kraft run --target nginx-qemu-x86_64-initrd --initrd ./rootfs -p 8080:80

If you don't have KVM support (such as when running inside a virtual machine), pass the-W option tokraft run to disable virtualization support:

kraft run -W --target nginx-qemu-x86_64-initrd --initrd ./rootfs -p 8080:80

When left without the--target argument, you'll be queried for the desired target from the list.

To use the Unikraft instance of Nginx, open another console and use thewget command below to query the server:

wget localhost:8080

You can set up, configure, build and run the application from grounds up, without using the companion toolkraft.

For a quick setup, run the commands below.Note that you still need to install therequirements.

For building and running everything forx86_64, follow the steps below:

git clone https://github.com/unikraft/app-nginx nginxcd nginx/./scripts/setup.shwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.pychmod a+x scripts/generate.py./scripts/generate.py./scripts/build/make-qemu-x86_64-9pfs.sh./scripts/run/qemu-x86_64-9pfs.sh

This will configure, build and run thenginx server.You can see how to test it in therunning section.

To close the QEMU Nginx server, use theCtrl+a x keyboard shortcut;that is press theCtrl anda keys at the same time and then, separately, press thex key.

The same can be done forAArch64, by running the commands below:

git clone https://github.com/unikraft/app-nginx nginxcd nginx/./scripts/setup.shwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.pychmod a+x scripts/generate.py./scripts/generate.py./scripts/build/make-qemu-arm64-9pfs.sh./scripts/run/qemu-arm64-9pfs.sh

Similar to thex86_64 build, this will start thenginx server.Information about every step is detailed below.

In order to set up, configure, build and run Nginx on Unikraft, the following packages are required:

• build-essential /base-devel /@development-tools (the meta-package that includesmake,gcc and other development-related packages)
• sudo
• flex
• bison
• git
• wget
• uuid-runtime
• qemu-system-x86
• qemu-system-arm
• qemu-kvm
• sgabios
• gcc-aarch64-linux-gnu

GCC >= 8 is required to build Nginx on Unikraft.

On Ubuntu/Debian or otherapt-based distributions, run the following command to install the requirements:

sudo apt install -y --no-install-recommends \  build-essential \  sudo \  gcc-aarch64-linux-gnu \  libncurses-dev \  libyaml-dev \  flex \  bison \  git \  wget \  uuid-runtime \  qemu-kvm \  qemu-system-x86 \  qemu-system-arm \  sgabios

Running Nginx Unikraft with QEMU requires networking support.For this to work properly a specific configuration must be enabled for QEMU.Run the commands below to enable that configuration (for the network bridge to work):

sudo mkdir /etc/qemu/echo "allow all" | sudo tee /etc/qemu/bridge.conf

The following repositories are required for Nginx:

• The application repository (this repository):app-nginx
• The Unikraft core repository:unikraft
• Library repositories:
  • The Nginx "library" repository:lib-nginx
  • The standard C library:lib-musl
  • The networking stack library:lib-lwip

Follow the steps below for the setup:

1. First clone theapp-nginx repository in thenginx/ directory:

   git clone https://github.com/unikraft/app-nginx nginx

   Enter thenginx/ directory:

   cd nginx/ls -aF

   This will print the contents of the repository:

   Makefile  Makefile.uk  README.md  defconfigs/  kraft.cloud.yaml  kraft.yaml  rootfs/  scripts/

2. While inside thenginx/ directory, clone all required repositories by using thesetup.sh script:

   ./scripts/setup.sh

3. Use thetree command to inspect the contents of theworkdir/ directory:

   tree -F -L 2 workdir/

   The layout of theworkdir/ directory should look something like this:

   workdir/|-- libs/|   |-- lwip/|   |-- musl/|   `-- nginx/`-- unikraft/    |-- arch/    |-- Config.uk    |-- CONTRIBUTING.md    |-- COPYING.md    |-- include/    |-- lib/    |-- Makefile    |-- Makefile.uk    |-- plat/    |-- README.md    |-- support/    `-- version.mk10 directories, 7 files

To make it easier to build, run and test different configurations, the repository provides a set of scripts that do everything required.These are scripts used for building different configurations of the Nginx server and for running these with all the requirements behind the scenes: creating network configurations, setting up archives etc.

First of all, grab thegenerate.py script and place it in thescripts/ directory by running:

wget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.pychmod a+x scripts/generate.py

Now, run thegenerate.py script.You must run it in the root directory of this repository:

./scripts/generate.py

The scripts (as shell scripts) are now generated inscripts/build/ andscripts/run/:

scripts/|-- build/|   |-- kraft-fc-aarch64-initrd.sh*|   |-- kraft-fc-arm64-initrd.sh*|   |-- kraft-fc-x86_64-initrd.sh*|   |-- kraft-qemu-aarch64-9pfs.sh*|   |-- kraft-qemu-aarch64-initrd.sh*|   |-- kraft-qemu-arm64-9pfs.sh*|   |-- kraft-qemu-arm64-initrd.sh*|   |-- kraft-qemu-x86_64-9pfs.sh*|   |-- kraft-qemu-x86_64-initrd.sh*|   |-- make-fc-x86_64-initrd.sh*|   |-- make-qemu-arm64-9pfs.sh*|   |-- make-qemu-arm64-initrd.sh*|   |-- make-qemu-x86_64-9pfs.sh*|   `-- make-qemu-x86_64-initrd.sh*|-- generate.py*|-- run/|   |-- fc-x86_64-initrd.json|   |-- fc-x86_64-initrd.sh*|   |-- kraft-fc-aarch64-initrd.sh*|   |-- kraft-fc-arm64-initrd.sh*|   |-- kraft-fc-x86_64-initrd.sh*|   |-- kraft-qemu-aarch64-9pfs.sh*|   |-- kraft-qemu-aarch64-initrd.sh*|   |-- kraft-qemu-arm64-9pfs.sh*|   |-- kraft-qemu-arm64-initrd.sh*|   |-- kraft-qemu-x86_64-9pfs.sh*|   |-- kraft-qemu-x86_64-initrd.sh*|   |-- qemu-arm64-9pfs.sh*|   |-- qemu-arm64-initrd.sh*|   |-- qemu-x86_64-9pfs.sh*|   `-- qemu-x86_64-initrd.sh*|-- run.yaml`-- setup.sh*

They are shell scripts, so you can use an editor or a text viewer to check their contents:

cat scripts/run/fc-x86_64-initrd.sh

Now, invoke each script to build and run the application.A sample build and run set of commands is:

./scripts/build/make-qemu-x86_64-9pfs.sh./scripts/run/qemu-x86_64-9pfs.sh

Note that Firecracker only works with initrd (not 9pfs).And Firecracker networking is not yet upstream.

Configuring, building and running a Unikraft application depends on our choice of platform and architecture.Currently, supported platforms are QEMU (KVM), Xen and linuxu.QEMU (KVM) is known to be working, so we focus on that.

Supported architectures are x86_64 and AArch64.

Use the corresponding the configuration files (defconfigs/*), according to your choice of platform and architecture.

Use thedefconfigs/qemu-x86_64-9pfs configuration file together withmake defconfig to create the configuration file:

UK_DEFCONFIG=$(pwd)/defconfigs/qemu-x86_64-9pfs make defconfig

This results in the creation of the.config file:

ls .config.config

The.config file will be used in the build step.

Use thedefconfigs/qemu-arm64-9pfs configuration file together withmake defconfig to create the configuration file:

UK_DEFCONFIG=$(pwd)/defconfigs/qemu-arm64-9pfs make defconfig

Similar to the x86_64 configuration, this results in the creation of the.config file that will be used in the build step.

Building uses as input the.config file from above, and results in a unikernel image as output.The unikernel output image, together with intermediary build files, are stored in thebuild/ directory.

Before starting a build on a different platform or architecture, you must clean up the build output.This may also be required in case of a new configuration.

Cleaning up is done with 3 possible commands:

• make clean: cleans all actual build output files (binary files, including the unikernel image)
• make properclean: removes the entirebuild/ directory
• make distclean: removes the entirebuild/ directoryand the.config file

Typically, you would usemake properclean to remove all build artifacts, but keep the configuration file.

Building for QEMU x86_64 assumes you did the QEMU x86_64 configuration step above.Build the Unikraft Nginx image for QEMU x86_64 by using the command below:

make -j $(nproc)

You will see a list of all the files generated by the build system:

[...]  LD      nginx_qemu-x86_64.dbg  UKBI    nginx_qemu-x86_64.dbg.bootinfo  SCSTRIP nginx_qemu-x86_64  GZ      nginx_qemu-x86_64.gzmake[1]: Leaving directory 'nginx/workdir/unikraft'

At the end of the build command, thenginx_qemu-x86_64 unikernel image is generated.This image is to be used in the run step.

If you had configured and build a unikernel image for another platform or architecture (such as x86_64) before, then:

1. Do a cleanup step withmake properclean.

2. Configure for QEMU AAarch64, as shown above.

3. Follow the instructions below to build for QEMU AArch64.

Building for QEMU AArch64 assumes you did the QEMU AArch64 configuration step above.Build the Unikraft Nginx image for QEMU AArch64 by using the same command as for x86_64:

make -j $(nproc)

Similar to building for x86_64, you will see a list of the files generated by the build system.

[...]  LD      nginx_qemu-arm64.dbg  UKBI    nginx_qemu-arm64.dbg.bootinfo  SCSTRIP nginx_qemu-arm64  GZ      nginx_qemu-arm64.gzmake[1]: Leaving directory 'nginx/workdir/unikraft

Similarly to x86_64, at the end of the build command, thenginx_qemu-arm64 unikernel image is generated.This image is to be used in the run step.

To run the QEMU x86_64 build, useqemu-x86_64-9pfs.sh:

./scripts/generate.py./scripts/run/qemu-x86_64-9pfs.sh

This will start the Nginx server:

qemu-system-x86_64: warning: TCG doesn't support requested feature: CPUID.01H:ECX.vmx [bit 5]1: Set IPv4 address 172.44.0.2 mask 255.255.255.0 gw 172.44.0.1en1: Addeden1: Interface is upPowered byo.   .o       _ _               __ _Oo   Oo  ___ (_) | __ __  __ _ ' _) :_oO   oO ' _ `| | |/ /  _)' _` | |_|  _)oOo oOO| | | | |   (| | | (_) |  _) :_ OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)                  Atlas 0.13.1~5eb820bd

The server listens for connections on the172.44.0.2 address advertised.A web client (such aswget) is required to query the server.

To test if the Unikraft instance of Nginx works, open another console and use thewget command below to query the server:

wget 172.44.0.2

This will download theindex.html file provided in therootfs/ directory.

--2023-07-01 13:53:24--  http://172.44.0.2/Connecting to 172.44.0.2:80... connected.HTTP request sent, awaiting response... 200 OKLength: 180 [text/html]Saving to: ‘index.html’index.html                                    100%[================================================================================================>]     180  --.-KB/s    in 0s2023-07-01 13:53:25 (12.6 MB/s) - ‘index.html’ saved [180/180]

To close the QEMU Nginx server, use theCtrl+a x keyboard shortcut;that is press theCtrl anda keys at the same time and then, separately, press thex key.

To run the AArch64 build, useqemu-aarch64-9pfs.sh:

./scripts/generate.py./scripts/run/qemu-arm64-9pfs.sh

This will start the Nginx server, same as above.Follow the same steps as above to qeury / test / close the running instance of Nginx with Unikraft.

The examples above use 9pfs as the filesystem interface.Clean up the previous configuration, use the initrd configuration and build the unikernel by using the commands:

./scripts/generate.py./scripts/build/make-qemu-x86_64-initrd.sh

To run the QEMU x86_64 initrd build, useqemu-x86_64-initrd.sh:

./scripts/run/qemu-x86_64-initrd.sh

The commands for AArch64 are similar:

./scripts/build/make-qemu-arm64-initrd.sh

Firecracker is a lightweight VMM (virtual machine manager) that can be used as more efficient alternative to QEMU.

Configure and build commands are similar to a QEMU-based build with an initrd-based filesystem:

./scripts/build/make-fc-x86_64-initrd.sh

To use Firecraker, you need to download aFirecracker release.You can use the commands below to make thefirecracker-x86_64 executable from release v1.4.0 available globally in the command line:

cd /tmpwget https://github.com/firecracker-microvm/firecracker/releases/download/v1.4.0/firecracker-v1.4.0-x86_64.tgztar xzf firecracker-v1.4.0-x86_64.tgzsudo cp release-v1.4.0-x86_64/firecracker-v1.4.0-x86_64 /usr/local/bin/firecracker-x86_64

To run a unikernel image, you need to configure a JSON file.This is thescripts/run/fc-x86_64-initrd.json file.This configuration file is uses as part of the run command:

./scripts/run/fc-x86_64-initrd.sh

Same as running with QEMU, the application will start:

1: Set IPv4 address 172.44.0.2 mask 255.255.255.0 gw 172.44.0.1en1: Addeden1: Interface is upPowered byo.   .o       _ _               __ _Oo   Oo  ___ (_) | __ __  __ _ ' _) :_oO   oO ' _ `| | |/ /  _)' _` | |_|  _)oOo oOO| | | | |   (| | | (_) |  _) :_ OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)                  Atlas 0.13.1~5eb820bd

This will start the Nginx server, same as above.Follow the same steps as above to qeury / test / close the running instance of Nginx with Unikraft.