These steps apply to the latest release of RaspAP, Raspberry Pi OS Lite, Debian and Armbian. Notes for previous versions, Ubuntu Server 18.04 TLS and 19.10 are provided, where applicable. Please refer to this regarding operating systems support.
Start off by updating your system's package list, then upgrade the kernel, firmware and installed packages to their latest versions:
sudo apt-get update
sudo apt-get full-upgrade
Note that full-upgrade is used rather than a simple upgrade, as this also picks up any dependency changes that may have been made. The kernel and firmware are installed as a Debian package, and so will also get updates when using the procedure above. These packages are updated infrequently and after extensive testing.
Telecommunications radio bands are subject to regulatory restrictions to ensure interference-free operation. The Linux OS complies with these rules by requiring users to configure a two-letter "WiFi country code". In RPi OS, 5 GHz wireless networking is disabled until this country code has been set, usually as part of the initial installation process. If you have not set your country code or are unsure, check the "WLAN Country" setting in raspi-config's Localisation Options:
sudo raspi-config
To ensure the WiFi radio is not blocked on the Raspberry Pi, execute the following command:
sudo rfkill unblock wlan
Non-RPi OS dependencies Operating systems other than RPi OS have some additional dependencies. If you are using RPi OS Lite, skip this section. On Ubuntu Server, add a dependency and the ppa:ondrej/php apt package:
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:ondrej/php
On Debian, Armbian and Ubuntu, install dhcpcd5 with the following:
sudo apt-get install dhcpcd5
Install packages Install git, lighttpd, php7, hostapd, dnsmasq and some extra packages with the following:
sudo apt-get install lighttpd git hostapd dnsmasq iptables-persistent vnstat qrencode php7.3-cgi
ℹ Note: for Ubuntu, you may replace php7.3-cgi with php7.4-cgi. php5 is no longer supported.
Enable PHP Next, enable PHP for lighttpd and restart the service for the settings to take effect:
sudo lighttpd-enable-mod fastcgi-php
sudo service lighttpd force-reload
sudo systemctl restart lighttpd.service
Create the web application In these steps we will prepare the web destination and git clone the files to /var/www/html.
ℹ Caution: If this is not a clean installation, be sure you do not have existing files or directories in the web root before executing the rm -rf command.
sudo rm -rf /var/www/html
sudo git clone https://github.com/RaspAP/raspap-webgui /var/www/html
Copy an extra lighttpd config file to support application routing. This step requires some text substitutions to support user changes to lighttpd's server.document-root setting:
WEBROOT="/var/www/html"
CONFSRC="$WEBROOT/config/50-raspap-router.conf"
LTROOT=$(grep "server.document-root" /etc/lighttpd/lighttpd.conf | awk -F '=' '{print $2}' | tr -d " \"")
HTROOT=${WEBROOT/$LTROOT}
HTROOT=$(echo "$HTROOT" | sed -e 's/\/$//')
awk "{gsub(\"/REPLACE_ME\",\"$HTROOT\")}1" $CONFSRC > /tmp/50-raspap-router.conf
sudo cp /tmp/50-raspap-router.conf /etc/lighttpd/conf-available/
Link it into conf-enabled and restart the web service:
sudo ln -s /etc/lighttpd/conf-available/50-raspap-router.conf /etc/lighttpd/conf-enabled/50-raspap-router.conf
sudo systemctl restart lighttpd.service
Now comes the fun part. For security reasons, the www-data user which lighttpd runs under is not allowed to start or stop daemons, or run commands like ip link, all of which we want our app to do. So we will add the www-data user to sudoers, but with restrictions on what commands the user can run. Copy the sudoers rules to their destination:
cd /var/www/html
sudo cp installers/raspap.sudoers /etc/sudoers.d/090_raspap
Configuration directories RaspAP uses several directories to manage its own configuration. Create these with the following commands:
sudo mkdir /etc/raspap/
sudo mkdir /etc/raspap/backups
sudo mkdir /etc/raspap/networking
sudo mkdir /etc/raspap/hostapd
sudo mkdir /etc/raspap/lighttpd
Move RaspAP's auth control file to the configuration directory you created above:
sudo cp raspap.php /etc/raspap
Set permissions
Next, set the files ownership to the www-data user for the web files and RaspAP config:
sudo chown -R www-data:www-data /var/www/html
sudo chown -R www-data:www-data /etc/raspap
Control scripts
RaspAP uses several shell scripts to manage various aspects of the application, including hostapd logging and raspapd, the RaspAP control service. Move these scripts to their destinations with the following:
sudo mv installers/*log.sh /etc/raspap/hostapd
sudo mv installers/service*.sh /etc/raspap/hostapd
Set ownership and permissions for the logging and service control scripts:
sudo chown -c root:www-data /etc/raspap/hostapd/*.sh
sudo chmod 750 /etc/raspap/hostapd/*.sh
Copy and set ownership of the lighttpd control scripts:
sudo cp installers/configport.sh /etc/raspap/lighttpd
sudo chown -c root:www-data /etc/raspap/lighttpd/*.sh
Next, move the raspapd service file to the correct location and enable it:
sudo mv installers/raspapd.service /lib/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable raspapd.service
Default configuration
To facilitate a faster setup, RaspAP uses a "known-good" default configuration as a starting point. Copy the configuration files for dhcpcd, dnsmasq, hostapd and defaults.json. Optionally, backup your existing hostapd.conf:
sudo mv /etc/default/hostapd ~/default_hostapd.old
sudo cp /etc/hostapd/hostapd.conf ~/hostapd.conf.old
sudo cp config/default_hostapd /etc/default/hostapd
sudo cp config/hostapd.conf /etc/hostapd/hostapd.conf
sudo cp config/090_raspap.conf /etc/dnsmasq.d/090_raspap.conf
sudo cp config/090_wlan0.conf /etc/dnsmasq.d/090_wlan0.conf
sudo cp config/dhcpcd.conf /etc/dhcpcd.conf
sudo cp config/config.php /var/www/html/includes/
sudo cp config/defaults.json /etc/raspap/networking/
ℹ Note: If you wish to modify RaspAP's default configuration for dnsmasq and dhcp, you may do so by changing these files and editing config/defaults.json.
Next, disable systemd-networkd and copy the bridge configuration with the following:
sudo systemctl stop systemd-networkd
sudo systemctl disable systemd-networkd
sudo cp config/raspap-bridge-br0.netdev /etc/systemd/network/raspap-bridge-br0.netdev
sudo cp config/raspap-br0-member-eth0.network /etc/systemd/network/raspap-br0-member-eth0.network
Optimize PHP
Optionally, you may optimize PHP with the following, replacing php7.3-cgi with your installed version:
sudo sed -i -E 's/^session\.cookie_httponly\s*=\s*(0|([O|o]ff)|([F|f]alse)|([N|n]o))\s*$/session.cookie_httponly = 1/' /etc/php/7.3/cgi/php.ini
sudo sed -i -E 's/^;?opcache\.enable\s*=\s*(0|([O|o]ff)|([F|f]alse)|([N|n]o))\s*$/opcache.enable = 1/' /etc/php/7.3/cgi/php.ini
sudo phpenmod opcache
Routing and IP masquerading
These steps allow WLAN clients to access computers on the main wired eth0 network, and from there the internet. Begin by enabling IP forwarding with the following commands:
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/90_raspap.conf > /dev/null
sudo sysctl -p /etc/sysctl.d/90_raspap.conf
sudo /etc/init.d/procps restart
To enable traffic between clients on the WLAN and the internet, we add two iptables network address translation (NAT) "masquerade" firewall rules. Create these rules and persist them with the following:
sudo iptables -t nat -A POSTROUTING -j MASQUERADE
sudo iptables -t nat -A POSTROUTING -s 192.168.50.0/24 ! -d 192.168.50.0/24 -j MASQUERADE
sudo iptables-save | sudo tee /etc/iptables/rules.v4
Enable hostapd
The hostapd service is disabled by default, as there is no configuration for it after its initial installation. Unmask and enable it with the following:
sudo systemctl unmask hostapd.service
sudo systemctl enable hostapd.service
Optional components
The following components are not required to operate RaspAP, but extend its usefulness in several ways. Each is independent of the others, so you may choose to add whichever one you need.
OpenVPN
Install OpenVPN, enabling the option in RaspAP's config and the openvpn-client service, like so:
sudo apt-get install openvpn
sudo sed -i "s/\('RASPI_OPENVPN_ENABLED', \)false/\1true/g" /var/www/html/includes/config.php
sudo systemctl enable openvpn-client@client
Copy the OpenVPN auth control script to its destination, setting ownership and permissions with the following:
sudo mkdir /etc/raspap/openvpn/
sudo cp installers/configauth.sh /etc/raspap/openvpn/
sudo chown -c root:www-data /etc/raspap/openvpn/*.sh
sudo chmod 750 /etc/raspap/openvpn/*.sh
WireGuard
Adding support for WireGuard is straightforward. The application files are already present in RaspAP, so you may simply install and enable the service, then activate the management option:
sudo apt-get install wireguard
sudo sed -i "s/\('RASPI_WIREGUARD_ENABLED', \)false/\1true/g" /var/www/html/includes/config.php
sudo systemctl enable wg-quick@wg
Ad blocking
There are several steps to enable Ad blocking, including downloading the blocklists, setting permissions and adding a dnsmasq configuration:
sudo mkdir /etc/raspap/adblock
wget https://raw.githubusercontent.com/notracking/hosts-blocklists/master/hostnames.txt -O /tmp/hostnames.txt
wget https://raw.githubusercontent.com/notracking/hosts-blocklists/master/domains.txt -O /tmp/domains.txt
sudo cp /tmp/hostnames.txt /etc/raspap/adblock
sudo cp /tmp/domains.txt /etc/raspap/adblock
sudo cp installers/update_blocklist.sh /etc/raspap/adblock/
sudo chown -c root:www-data /etc/raspap/adblock/*.*
sudo chmod 750 /etc/raspap/adblock/*.sh
sudo touch /etc/dnsmasq.d/090_adblock.conf
echo "conf-file=/etc/raspap/adblock/domains.txt" | sudo tee -a /etc/dnsmasq.d/090_adblock.conf > /dev/null
echo "addn-hosts=/etc/raspap/adblock/hostnames.txt" | sudo tee -a /etc/dnsmasq.d/090_adblock.conf > /dev/null
sudo sed -i '/dhcp-option=6/d' /etc/dnsmasq.d/090_raspap.conf
sudo sed -i "s/\('RASPI_ADBLOCK_ENABLED', \)false/\1true/g" includes/config.php
Restart
Finally, restart your device and verify that the wireless access point is available:
sudo systemctl reboot
After your device has restarted, search for wireless networks with your wireless client. The default SSID is raspi-webgui. The default username is "admin" and the default password is "secret".
ℹ Note: It is strongly recommended that you change these default login credentials in RaspAP's Authentication panel. APs managed by RaspAP in the wild have been administered by third parties with the default login.
If you have any difficulties with the manual install steps, start a discussion and refer to this page.