This repository has been archived by the owner on Mar 4, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Makefile, configuration files and scripts
Update the README with instructions on setting up, configuring, building and running the Nginx app with Unikraft. As part of it, add Makefile files, configuration files and scripts; they are referenced in the `README.md` file. Current instructions cover the use of QEMU/KVM platform (both on x86_64 and on AArch64) and GCC. Firecraker/KVM, Xen, Linux platforms and Clang are not yet documented. Signed-off-by: Razvan Deaconescu <razvand@unikraft.io>
- Loading branch information
Showing
7 changed files
with
1,140 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
UK_ROOT ?= $(PWD)/.unikraft/unikraft | ||
UK_LIBS ?= $(PWD)/.unikraft/libs | ||
LIBS := $(UK_LIBS)/musl:$(UK_LIBS)/lwip:$(UK_LIBS)/nginx | ||
|
||
all: | ||
@$(MAKE) -C $(UK_ROOT) A=$(PWD) L=$(LIBS) | ||
|
||
$(MAKECMDGOALS): | ||
@$(MAKE) -C $(UK_ROOT) A=$(PWD) L=$(LIBS) $(MAKECMDGOALS) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
$(eval $(call addlib,appnginx)) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,93 +1,202 @@ | ||
# Nginx on Unikraft | ||
|
||
This application starts an NginX web server. | ||
This application starts an Nginx web server with Unikraft. | ||
Follow the instructions below to set up, configure, build and run Nginx. | ||
|
||
To configure, build and run the application you need to have [kraft](https://github.com/unikraft/kraft) installed. | ||
## Set Up | ||
|
||
To be able to interact with the web server, configure the application to run on the KVM platform: | ||
``` | ||
$ kraft configure -p kvm -m x86_64 | ||
``` | ||
The following repositories are required for Nginx: | ||
|
||
Build the application: | ||
``` | ||
$ kraft build | ||
``` | ||
* The application repository (this repository): [`app-nginx`](https://github.com/unikraft/app-nginx) | ||
* The Unikraft core repository: [`unikraft`](https://github.com/unikraft/unikraft) | ||
* Library repositories: | ||
* The Nginx "library" repository: [`lib-nginx`](https://github.com/unikraft/lib-nginx) | ||
* The standard C library: [`lib-musl`](https://github.com/unikraft/lib-musl) | ||
* The networking stack library: [`lib-lwip`](https://github.com/unikraft/lib-lwip) | ||
|
||
We use a virtual bridge to create a connection between the VM and the host system. | ||
We assign address `172.44.0.1/24` to the bridge interface (pointing to the host) and we assign address `172.44.0.2/24` to the virtual machine, by passing boot arguments. | ||
The IP addresses are of our choosing, they can be changed to other values. | ||
Follow the steps below for the setup: | ||
|
||
We run the commands below to create and assign the IP address to the bridge `virbr0` (once again, our choice of name; any name works): | ||
``` | ||
$ sudo brctl addbr virbr0 | ||
$ sudo ip a a 172.44.0.1/24 dev virbr0 | ||
$ sudo ip l set dev virbr0 up | ||
``` | ||
1. First clone the [`app-nginx` repository](https://github.com/unikraft/app-nginx) repository in the `nginx/` directory: | ||
|
||
We can check the proper configuration: | ||
``` | ||
$ ip a s virbr0 | ||
420: virbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 | ||
link/ether 3a:3e:88:e6:a1:e4 brd ff:ff:ff:ff:ff:ff | ||
inet 172.44.0.1/24 scope global virbr0 | ||
valid_lft forever preferred_lft forever | ||
inet6 fe80::383e:88ff:fee6:a1e4/64 scope link | ||
valid_lft forever preferred_lft forever | ||
```console | ||
$ git clone https://github.com/unikraft/app-nginx nginx | ||
``` | ||
|
||
Enter the `nginx/` directory: | ||
|
||
```console | ||
$ cd nginx/ | ||
|
||
$ ls | ||
fs0/ kraft.yaml Makefile Makefile.uk.default README.md run-aarch64* run-x86_64* | ||
``` | ||
|
||
1. While inside the `nginx/` directory, create the `.unikraft/` directory: | ||
|
||
```console | ||
$ mkdir .unikraft | ||
``` | ||
|
||
Enter the `.unikraft/` directory: | ||
|
||
```console | ||
$ cd .unikraft/ | ||
``` | ||
|
||
1. While inside the `.unikraft` directory, clone the [`unikraft` repository](): | ||
|
||
```console | ||
$ git clone https://github.com/unikraft/unikraft unikraft | ||
``` | ||
|
||
1. While inside the `.unikraft/` directory, create the `libs/` directory: | ||
|
||
```console | ||
$ mkdir libs | ||
``` | ||
|
||
1. While inside the `.unikraft/` directory, clone the library repositories in the `libs/` directory: | ||
|
||
```console | ||
$ git clone https://github.com/unikraft/lib-nginx nginx | ||
|
||
$ git clone https://github.com/unikraft/lib-musl musl | ||
|
||
$ git clone https://github.com/unikraft/lib-lwip lwip | ||
``` | ||
|
||
1. Get back to the application directory: | ||
|
||
```console | ||
$ cd ../ | ||
``` | ||
|
||
Use the `tree` command to inspect the contents of the `.unikraft/` directory. | ||
It should print something like this: | ||
|
||
```console | ||
$ tree --charset=ascii -F -L 2 .unikraft/ | ||
.unikraft/ | ||
|-- libs/ | ||
| |-- lwip/ | ||
| |-- musl/ | ||
| `-- nginx/ | ||
`-- unikraft/ | ||
|-- arch/ | ||
|-- Config.uk | ||
|-- CONTRIBUTING.md | ||
|-- COPYING.md | ||
|-- include/ | ||
|-- lib/ | ||
|-- Makefile | ||
|-- Makefile.uk | ||
|-- plat/ | ||
|-- README.md | ||
|-- support/ | ||
`-- version.mk | ||
|
||
10 directories, 7 files | ||
``` | ||
|
||
## Configure | ||
|
||
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 (`config-...`), according to your choice of platform and architecture. | ||
|
||
### QEMU x86_64 | ||
|
||
Use the `config-qemu-x86_64` configuration file together with `make defconfig` to create the configuration file: | ||
|
||
```console | ||
$ UK_DEFCONFIG=$(pwd)/config-qemu-x84_64 make defconfig | ||
``` | ||
|
||
Now we start the virtual machine and pass it the proper arguments to assing the IP address `172.44.0.2/24`: | ||
This results in the creation of the `.config` file: | ||
|
||
```console | ||
$ ls .config | ||
.config | ||
``` | ||
$ kraft run -b virbr0 "netdev.ipv4_addr=172.44.0.2 netdev.ipv4_gw_addr=172.44.0.1 netdev.ipv4_subnet_mask=255.255.255.0 --" | ||
[...] | ||
0: Set IPv4 address 172.44.0.2 mask 255.255.255.0 gw 172.44.0.1 | ||
en0: Added | ||
en0: Interface is up | ||
[...] | ||
|
||
This file will be used in the build step. | ||
|
||
### QEMU AArch64 | ||
|
||
Use the `config-qemu-aarch64` configuration file together with `make defconfig` to create the configuration file: | ||
|
||
```console | ||
$ UK_DEFCONFIG=$(pwd)/config-qemu-aarch64 make defconfig | ||
``` | ||
|
||
The boot message confirms the assigning of the `172.44.0.2/24` IP address to the virtual machine. | ||
We use `wget` to validate it's working properly and we are able to get the `index.html` file: | ||
Similar to the x86_64 configuration, this results in the creation of the `.config` file that will be used in the build step. | ||
|
||
## Build | ||
|
||
### QEMU x86_64 | ||
|
||
TODO | ||
|
||
### QEMU AArch64 | ||
|
||
TODO | ||
|
||
## Run | ||
|
||
Run the resulting image with the `run-...` scripts. | ||
|
||
### QEMU x86_64 | ||
|
||
To run the QEMU x86_64 build, use `run-qemu-x86_64.sh`: | ||
|
||
```console | ||
$ ./run-qemu-x86_64.sh | ||
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.1 | ||
en1: Added | ||
en1: Interface is up | ||
Powered by | ||
o. .o _ _ __ _ | ||
Oo Oo ___ (_) | __ __ __ _ ' _) :_ | ||
oO oO ' _ `| | |/ / _)' _` | |_| _) | ||
oOo oOO| | | | | (| | | (_) | _) :_ | ||
OoOoO ._, ._:_:_,\_._, .__,_:_, \___) | ||
Atlas 0.13.1~5eb820bd | ||
``` | ||
|
||
The server listens for connections on the `172.44.0.2` address advertised. | ||
A web client (such as wget) is required to query the server. | ||
|
||
Open another console and use the `wget` command below to query the server: | ||
|
||
```console | ||
$ wget 172.44.0.2 | ||
--2021-08-18 16:47:38-- http://172.44.0.2/ | ||
--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 OK | ||
[...] | ||
2021-08-18 16:47:38 (41.5 MB/s) - ‘index.html’ saved [160] | ||
``` | ||
Length: 180 [text/html] | ||
Saving to: ‘index.html’ | ||
|
||
Cleaning up means closing the virtual machine (and the HTTP server) and disabling and deleting the bridge interface: | ||
``` | ||
$ sudo ip l set dev virbr0 down | ||
$ sudo brctl delbr virbr0 | ||
index.html 100%[================================================================================================>] 180 --.-KB/s in 0s | ||
|
||
2023-07-01 13:53:25 (12.6 MB/s) - ‘index.html’ saved [180/180] | ||
``` | ||
|
||
If you want to have more control you can also configure, build and run the application manually. | ||
To close the QEMU Nginx server, use the `Ctrl+a x` keyboard shortcut; | ||
that is press the `Ctrl` and `a` keys at the same time and then, separately, press the `x` key. | ||
|
||
To configure it for the KVM platform: | ||
``` | ||
$ make menuconfig | ||
``` | ||
### QEMU AArch64 | ||
|
||
Build the application: | ||
``` | ||
$ make | ||
``` | ||
To run the AArch64 build, use `run-qemu-aarch64.sh`: | ||
|
||
Run the application: | ||
``` | ||
sudo qemu-system-x86_64 -fsdev local,id=myid,path=$(pwd)/fs0,security_model=none \ | ||
-device virtio-9p-pci,fsdev=myid,mount_tag=fs0,disable-modern=on,disable-legacy=off \ | ||
-netdev bridge,id=en0,br=virbr0 \ | ||
-device virtio-net-pci,netdev=en0 \ | ||
-kernel "build/app-nginx_kvm-x86_64" \ | ||
-append "netdev.ipv4_addr=172.44.0.2 netdev.ipv4_gw_addr=172.44.0.1 netdev.ipv4_subnet_mask=255.255.255.0 --" \ | ||
-cpu host \ | ||
-enable-kvm \ | ||
-nographic | ||
```console | ||
$ ./run-qemu-aarch64.sh | ||
TODO | ||
``` | ||
|
||
|
||
For more information about `kraft` type ```kraft -h``` or read the | ||
[documentation](http://docs.unikraft.org). | ||
Open another console and use the `wget` command below to query the server, same as above. | ||
Similarly, to close the QEMU Nginx server, use the `Ctrl+a x` keyboard shortcut. |
Oops, something went wrong.