Instituto Superior de Engenharia do Porto (ISEP)
Mestrado em Engenharia Eletrotécnica e de Computadores (MEEC)
Arquitectura de Computadores (ARCOM)
Building an Embedded Web Server with Buildroot
Introduction
This tutorial builds upon the results of the previous tutorial. The main objective is to use the
generated toolchain to create a minimal Linux distribution with a HTTP server for the
Raspberry Pi board. The HTTP server used in this experiment is the Apache HTTP server.
This also illustrates how to develop new Buildroot projects without the need of building a
toolchain for each project.
Setting up a new project
Buildroot does not offer a backtrack or undo option. This means that a package conflict may
sometimes render the configuration unusable, requiring a full rebuild of the project.
In order to avoid the need of such rebuild, it is advisable to make a backup of the initial build
before adding additional software packages. Additionally, to save disk space, it is possible to
use the toolchain from a previous project on new projects. We will illustrate the latter route
here.
1.1) Create a new directory for this lesson:
mkdir -p ~/student_number/Lab3
1.2) Install the toolchain generated in the previous PL lesson under your student directory:
cd ~/student_number/Lab2/buildroot-rpi/output/images
tar xvf aarch64-buildroot-linux-gnu_sdk-buildroot.tar.gz \
-C ~/student_number/
cd ~/student_number/aarch64-buildroot-linux-gnu_sdk-buildroot
./relocate-sdk.sh
If you do not have the files from the previous lesson, you may use the toolchain provided in
the lesson web page.
1.3) Check the gcc version of the toolchain, for later use:
bin/aarch64-linux-gcc --version
Building an Embedded Web Server with Buildroot 1/6
ARCOM – MEEC – ISEP – 2023/2024
1.4) Create a new Buildroot project for the Raspberry Pi:
• Go back to the Lab3 directory: cd ~/student_number/Lab3
• Decompress the Buildroot tarball (the file you downloaded at the beginning of the last
lesson).
• Rename the extracted directory (the buildroot directory) to buildroot-rpi-apache
• Copy the configuration parameters from the last lesson’s project to the new project:
o cp ../Lab2/buildroot-rpi/.config buildroot-rpi-apache
• Buildroot stores the source code packages in a directory named dl. In order to avoid
downloading the same packages from the previous lesson, turn dl into a link (ln
command) to the dl directory from the previous project:
o cd buildroot-rpi-apache
o ln -s ../../Lab2/buildroot-rpi/dl dl
2.1) Launch the Buildroot configuration screen (make xconfig)
2.2) Change the following fields from the “Toolchain” option, with the necessary adaptions for
the directory structure of your machine:
• Toolchain Type => External toolchain
• Toolchain => Custom toolchain
• Toolchain origin => Pre-installed toolchain
• Toolchain path => /home/arcom1x/student_number/aarch64-buildroot-
linux-gnu_sdk-buildroot
• Toolchain prefix => $(ARCH)-linux
• External toolchain gcc version => Check the output from aarch64-linux-gcc -v
• External toolchain kernel header series => 5.15.x
• External toolchain C library => glibc
• Toolchain has RPC support => no
• Toolchain has C++ support => yes
Adding the Apache package to the Linux distribution
3) Under “Target packages => Networking applications”:
• Select the “apache” package.
4) Although system initialization based on systemV and systemd are supported, by default
Buildroot uses an initialization system based on a set of scripts stored on /etc/init.d, as
also a custom /etc/inittab. The initialization process executes the SnnXXXX scripts in
/etc/init.d, starting with the ones with a lower “nn” value in the filename.
In the case of the apache package, no control script is created. In order to add such script, we’ll
use the mechanism of file system overlays. By using this mechanism, it is possible to define a
set of directories and files that will be added to the final distribution.
Thus, under “System configuration”, find “Root filesystem overlay directories” and introduce
the following value: ../buildroot-rpi-apache-overlay
5) Save the configuration and exit the configuration screen.
6) Create the overlay directory structure in the parent directory and make it the current
Building an Embedded Web Server with Buildroot 2/6
ARCOM – MEEC – ISEP – 2023/2024
directory:
cd ..
mkdir -p buildroot-rpi-apache-overlay/etc/init.d
cd buildroot-rpi-apache-overlay/etc/init.d
7.1) Using a text editor, create the service control script S50apache with the following
contents (in buildroot-rpi-apache-overlay/etc/init.d/):
#!/bin/sh
#
# Start the Apache HTTP server...
#
case "$1" in
start|stop|restart|reload)
apachectl "$1"
;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
esac
exit $?
7.2) Grant everyone read and execution permissions to S50apache:
chmod a+rx S50apache
8) Build the new distribution:
make
9.1) Generate graphs of the duration of each build step:
make graph-build
The generated graphs are stored in output/graphs.
9.2) Generate a graph of the file system size contribution of each package:
make graph-size
Adding a personalized web page
10) Mount rootfs.ext2 and check the apache configuration file:
mkdir m
su
mount output/images/rootfs.ext2 m
less m/etc/apache2/httpd.conf
(press q to quit, do not change this file)
Which directory is used to store the HTTP hosted documents? (hint: look for DocumentRoot)
11) Using a text editor, add a welcome message containing your student number to the default
web page (index.html).
Building an Embedded Web Server with Buildroot 3/6
ARCOM – MEEC – ISEP – 2023/2024
Test on QEMU
12.1) Test the generated root file system image on an aarch64 virtual machine with two Cortex-
a72 cores and 256 MiB of RAM:
#download the kernel file
wget -P ../.. https://www.ave.dee.isep.ipp.pt/~jes/arcom/Lab3-Buildroot/linux-
aarch64-qemu
#launch qemu, using rootfs.ext2 as a virtual disk partition
qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256 -smp 2 \
-kernel ../../linux-aarch64-qemu \
-append "rootwait root=/dev/vda console=ttyAMA0 " \
-device virtio-blk-device,drive=hd0 \
-drive file=output/images/rootfs.ext2,format=raw,if=none,format=raw,id=hd0 \
-serial stdio -nic hostfwd=tcp::8000-:80
QEMU creates a private network for the emulated machine using the Network Address
Translation (NAT) mechanism. The last parameter,
"-nic hostfwd=tcp::8000-:80"
tells QEMU to forward port 8000 of the host machine to port 80 of the emulated machine.
12.2) In the host machine, open a web browser and type http://localhost:8000 in the
address bar. The browser should present the page you edited on step 11 (index.html).
12.3) Shutdown the emulated machine by typing poweroff in its command line (of the QEMU
window).
Deployment of the distribution in the USB storage device
As in the previous tutorial, it is necessary to copy the contents of the root file system image
(rootfs.ext2) to the file system in the second partition of your USB storage device.
In what follows, it is assumed that the USB storage device is associated to /dev/sdb, but you
should check that for your own system, using the lsblk utility.
13) Use mkfs.ext4 to create an empty filesystem on the second partition of your USB storage
device and transfer the files in rootfs.ext2 to it.
su
mount output/images/rootfs.ext2 m
mkfs.ext4 /dev/sdb2 -d m
umount m
14) Make sure that all the USB device file systems are unmounted, by running umount
/dev/sdb* until you reveive the following message:
umount: /dev/sdb: not mounted.
umount: /dev/sdb1: not mounted.
umount: /dev/sdb2: not mounted.
Building an Embedded Web Server with Buildroot 4/6
ARCOM – MEEC – ISEP – 2023/2024
15) Test the system, from the USB device, on QEMU:
qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256 -smp 2 \
-kernel ../../linux-aarch64-qemu \
-append "rootwait root=/dev/vda console=ttyAMA0" \
-device virtio-blk-device,drive=hd0 \
-drive file=/dev/sdb2,format=raw,if=none,format=raw,id=hd0 \
-serial stdio -nic hostfwd=tcp::8000-:80
Test on the Raspberry Pi
16) Introduce the USB disk in one of the Raspberry Pi USB ports and connect the power supply.
17) Log in as root and check the assigned address to eth0 by typing ifconfig. If no IPv4
address is assigned, check the cable connection and LED indicators. As a last resort, perform
the static configuration of the Ethernet interface using the ifconfig command:
ifconfig eth0 10.0.16.128 netmask 255.255.255.0
18) On your classroom computer, open a web browser and introduce the address assigned to
the Raspberry Pi board Ethernet interface. You should get the previously defined welcome
page.
19) Mandatory for grading: Upload the rootfs.ext2 file to your web area in
ave.dee.isep.ipp.pt. The file should be available under the following location:
https://ave.dee.isep.ipp.pt/~your_student_number/arcom/lab3/
Building an Embedded Web Server with Buildroot 5/6
ARCOM – MEEC – ISEP – 2023/2024
Document history
• 2024-10-22 – change from uclibc to glibc (jes@isep.ipp.pt)
• 2023-10-17 – changed from Arm (32 bit) target to Aarch64 target (jes@isep.ipp.pt)
• 2022-10-20 – minor updates by Jorge Estrela da Silva (jes@isep.ipp.pt)
• 2020-11-19 – minor updates by Jorge Estrela da Silva (jes@isep.ipp.pt)
o Removed the kernel parameter “console=tty1”
o “-redir” changed to “hostfwd”
• 2018-10-08 – minor updates by Jorge Estrela da Silva (jes@isep.ipp.pt)
o Update to kernel-qemu-4.14.50-stretch
o Hack to avoid error message due to absence of kernel files in the buildroot
output directory.
• 2017-10-01 – created by Jorge Estrela da Silva (jes@isep.ipp.pt)
Building an Embedded Web Server with Buildroot 6/6
ARCOM – MEEC – ISEP – 2023/2024
