RaspAP has introduced a new DNS based filter to stop ads, trackers, malware and other undesirable hosts in their tracks.
+In the best of times, ads are usually just annoying. When access to online services served by our AP is hampered by ads, malware and trackers, the best tool in our arsenal is DNS blacklisting.
+RaspAP already uses dnsmasq to manage both DHCP and DNS, so we have the foundation for a highly effective ad blocking facility.
To install ad blocking with DNS blacklists, simply respond with Y or press Enter when prompted by the installer:
+ +The installer will download the blocklists, configure RaspAP to use them and enable the Ad blocking management page.
+
Ad blocking is enabled and active for clients connected to your AP. You may update the blocklists or disable ad blocking with the management page. These actions are described below.
+Ad blocking may also be installed manually. Refer to the detailed installation steps.
+Blocklists are sourced from multiple, continuously updated open source projects. These are divided into two groups: hosts and domain blocklists. By default, RaspAP's ad block facility uses StevenBlack's hosts as the primary hosts blocklist. This repository is a hosts file aggregator that consolidates several reputable hosts files and merges them into a unified, optimized hosts file with duplicates removed.
+
Alternatively, users may choose from a number of host blocklist sources maintained by the badmojr/1Hosts GitHub project. These lists are compiled daily into Mini, Lite, Pro and Xtra versions depending on specific user needs. Refer to the GitHub project for an explanation of these different blocklists.
+In addition to blocking hosts, domain blocking gives us the ability to use wildcards with dnsmasq to block an entire domain (for example, baddomain.org) with a single rule. This includes all known and unknown subdomains, such as *.baddomain.org. Domain blocklists are provided by the OISD project. Similar to hosts lists, these are continuously updated and curated into several lists: Small, Big and NSFW. Refer to the OISD project for an explanation of these lists.
Each of the hosts and domains blocklists are updated daily, so it's a good practice to refresh them periodically. You can do this from the Ad Blocking management page in RaspAP. Simply select the list from the dropdown and choose Update now.
+
Next to the update button, a gear icon will appear to indicate that the selected list is being downloaded. Thereafter, a timestamp after each list will indicate when it was last updated.
+Note
+To apply the latest blocklists, be sure to Restart Ad Blocking.
+Alternatively, you may wish to automate the process of keeping the ad block source lists up-to-date. A method to achieve this is described in this FAQ.
+In addition to the notracking blocklists, you may create your own host blocklist by adding entries on the Custom blocklist tab.
+Define custom hosts to be blocked by entering an IPv4 or IPv6 address followed by any whitespace (spaces or tabs) and the host name. An IPv4 example would take the form 0.0.0.0 badhost.com.
+Choose Save settings and Restart Ad Blocking.
Note
+As the name suggests, this is effective at blocking individual hosts, but not entire domains (or subdomains).
+By default, DNS logging is disabled. If you'd like to see which hosts are being blocked, enable it on the DHCP Server > Logging tab by selecting the Log DNS queries toggle. Save settings and Restart Ad Blocking. The Logging tab on the Ad Blocking page will display blacklisted DNS queries with host addresses of 0.0.0.0. A sample of blocked ad/tracker requests is below.
dnsmasq[9633]: config static.ads-twitter.com is 0.0.0.0
+dnsmasq[9633]: config tag.bounceexchange.com is 0.0.0.0
+dnsmasq[9633]: config cdn.boomtrain.com is 0.0.0.0
+dnsmasq[9633]: config securepubads.g.doubleclick.net is 0.0.0.0
+dnsmasq[9633]: config c.amazon-adsystem.com is 0.0.0.0
+dnsmasq[9633]: config pixel.adsafeprotected.com is 0.0.0.0
+dnsmasq[9633]: config ad.doubleclick.net is 0.0.0.0
+dnsmasq[9633]: config www.summerhamster.com is 0.0.0.0
+dnsmasq[9633]: config c2.taboola.com is 0.0.0.0
+dnsmasq[9633]: config ads.servebom.com is 0.0.0.0
+dnsmasq[9633]: config s.cpx.to is 0.0.0.0
+dnsmasq[9633]: config pixel.quantserve.com is 0.0.0.0
+dnsmasq[9633]: config cdn.taboola.com is 0.0.0.0
+dnsmasq[9633]: config sdk.iad-01.braze.com is 0.0.0.0
+To disable the ad blocking service, slide the Enable blocklists toggle to its off position, then choose Save settings. You may then restart your hotspot for the changes to take effect.
+The blocklist sources chosen for RaspAP adhere to these policies:
+Users may tailor RaspAP's ad blocking to suit their needs by selecting from multiple blocklist sources. Furthermore, domain blocklists enable full use of domain name based wildcard filtering (for example, *.baddomain.org). This reduces the chance of missing any new subdomains and significantly reduces the size of the blocklists.
After running the Quick installer, Docker setup or following the manual installation steps, RaspAP will start up a routed wireless access point (AP) with a default configuration.
+As part of this initial setup, the hostapd service broadcasts an AP with the following settings:
Interface: wlan0
+SSID: raspi-webgui
+Wireless Mode: 802.11n - 2.4GHz
+Channel: 1
+Security Type: WPA2
+Encryption Type: CCMP
+Passphrase: ChangeMe
Each of these settings may be changed on the Hotspot > Basic and Security tabs to any values you wish. Your changes will be applied and made visible on the broadcasted AP by choosing +Save settings followed by Restart hotspot.
+
At this point, a dialog will appear to indicate the progress of the RaspAP service. This is a Linux systemd process that is responsible for starting up several network services in a specific order and timing.
When the AP is operational, you may connect clients to it by using one of two methods:
+By default, clients are assigned IP addresses from the DHCP range 10.3.141.50 โ 10.3.141.254. These values may be changed in the DHCP options section of the DHCP server settings UI. If for some reason a client is unable to obtain an IP address from your AP, consult this FAQ.
For devices with compatible wireless hardware, RaspAP version 3.0 largely removes the guesswork in creating a 5 GHz access point. It achieves this by being tightly integrated with the wireless regulatory database used by the Linux kernel. Behind the scenes, RaspAP queries iw and intelligently matches its output with the 5 GHz channels allowed by hostapd, the user space daemon access point software.
From the Hotspot > Advanced tab, select your country from the dropdown then choose Save settings. This sets the wireless regulatory domain for your device. Now, on the Hotspot > Basic tab choose an interface and select the 802.11ac - 5 GHz wireless mode option. RaspAP will automatically populate the available 5 GHz channels for your country. Select a channel followed by Save settings, then Start or Restart hotspot.
Tip
+Not all AC channels may be compatible with your hardware. If your hotspot fails to start, enable hostapd service logging by sliding the Logfile output toggle on the Hotspot > Logging tab, followed by Save settings, then Restart hotspot. See this FAQ for more assistance.
If the Channel dropdown and Save settings button are disabled, refer to this FAQ.
+WPA2 is currently the most secure standard utilizing AES (Advanced Encryption Standard) and a pre-shared key for authentication. WPA2 is also backwards compatible with TKIP to allow interoperability with legacy devices. AES uses the CCMP encryption protocol which is a stronger algorithm for message integrity and confidentiality.
+By default, RaspAP's access point is configured with WPA2 and CCMP encryption. You may of course change this to allow legacy clients (older mobile devices, for example) by selecting TKIP+CCMP as the encryption type. Choose Save settings and Restart hotspot for your changes to take effect.
Experimental ยท Insiders only
+WPA3 is an improved encryption standard, thanks to Simultaneous Authentication of Equals (SAE) which replaces the Pre-Shared Key (PSK) authentication method used in prior WPA +versions. WPA3-Personal allows for better password-based authentication even when using simple passphrases. In general, WPA3-Personal networks with simple passphrases are more difficult to crack +by using brute-force, dictionary-based methods, as with WPA/WPA2.
+
WPA3 also requires the use of Protected Management Frames (PMFs) to increase network security. If you wish to connect AP clients that may not have support for WPA3-Personal or PMFs, a transitional +security mode is also available.
+Note
+The Raspberry Pi's onboard wireless chipsets do not currently support the WPA3 standard. For this reason, in order to use this setting you will need to configure your AP with an external wireless adapter that supports WPA3.
+Experimental ยท Insiders only
+The 802.11w amendment was introduced as a way to secure Wi-Fi management frames against attacks by ensuring that these frames are legitimately exchanged between an AP and its clients, rather than +a malicious third-party. These 802.11w Protected Management Frames (PMFs) can mitigate common types of "deauthentication" and "disassociation" attacks.
+Similar to WPA3-Personal, 802.11w may be configured in one of two modes: enabled and required. Enabled allows for mixed operation by allowing legacy devices that do not support 802.11w to associate +while also allowing devices that support 802.11w to use the PMF features. Required will prevent clients that do not support 802.11w from associating with the SSID.
+Experimental ยท Insiders only
+The default dashboard layout may be customized to suit your needs. Enable this option from the System > Theme menu by selecting the Dynamic widgets toggle. Next, from the Dashboard click or tap the icon to modify the widgets. Each widget may be resized, dragged and repositioned. Release the widget to drop it into a new location.
+Tip
+This option works best for large displays. The default dashboard widgets are optimized for mobile devices and smaller displays.
+Click or tap the icon a second time when you're done making changes. The new responsive dashboard layout will be saved to your browser's local storage.
+Experimental ยท Insiders only
+Beneath the QR code on the Hotspot > Security tab, you will find a link to open a "Wi-Fi connect" sign suitable for printing. Click or tap the link after the printer icon to open a new window with your hotspot's QR code, SSID and password neatly formatted.
+
To print, select File > Print from your browser's toolbar and adjust print preferences as needed. This feature can be especially useful if you operate a public wireless access point. You may also +opt to integrate a captive portal for your visitors.
+The above sections cover everything you will need for a basic routed AP. The Hotspot > Advanced tab has several options that allow you to control advanced settings for the Linux hostapd service. These are discussed in the following sections.
If you wish to configure RaspAP as a bridged AP, this may be done by sliding the Bridged AP mode toggle, saving settings and restarting the hotspot. Be aware that when the hotspot restarts
+you will no longer be able to access the web interface from the default 10.1.141.1 address. Refer to this explanation and tips for administering your bridged AP.
RaspAP has support for this special mode, also known as a micro-AP or simply AP-STA. Typically this can be difficult to configure manually, but RaspAP performs most of the config work behind the scenes for you.
+Note
+This option is disabled or "greyed out" until a wireless client is configured. This can be done via the WiFi client UI, or by manually configuring a valid wpa_supplicant.conf.
Before using this mode, it is recommended that users familiarize themselves with how AP-STA works. Users of AP-STA mode should also be aware of its limitations, and understand that performance and stability of this AP mode will not be equal to using a second wireless adapter bound to a separate interface. +For the latter, refer to this FAQ.
+Wireless APs continuously send beacon frames to indicate their presence, traffic load, and capabilities. The default hostapd beacon interval is 100ms. If desired, you may change this to any value between 15 and 65535.
An AP may disassociate a client due to inactivity, transmission failures or other indications of connection loss. This phenomenon can usually be observed in the hostapd logs like so:
wlan0: AP-STA-DISCONNECTED 24:62:ab:fd:24:34
+wlan0: STA 24:62:ab:fd:24:34 IEEE 802.11: disassociated
+wlan0: STA 24:62:ab:fd:24:34 IEEE 802.11: deauthenticated due to inactivity (timer DEAUTH/REMOVE)
+This option sets the disassoc_low_ack boolean value for hostapd. Be aware that this value is dependent on driver capabilities. Moreover, hostapd may disassociate a client (or station) for a variety of reasons, so this is not a silver bullet.
RaspAP allows you to control the transmit power of the configured AP interface. The default "auto" setting will suffice for the vast majority of APs. A lower txpower value
+can be useful to mitigate WiFi radio interference, for example if you are hosting multiple APs in a given area. It can also be advantageous to set txpower to a lower value in IoT or similar applications where reduced power consumption is needed.
Set the transmit power by selecting a value from the dropdown and choosing Save settings. The transmit power setting is expressed as dBm, or decibels (dB) with reference to one milliwatt (mW). +It is not necessary to restart the AP for this to take effect.
+This option sets the max_num_sta value for hostapd, and is effective for placing a limit on the number of clients (stations) that can connect to your AP. When the limit is reached, new client connections will be rejected.
Note
+The default setting is 2007, but this is merely the value set by hostapd from the IEEE 802.11 specification. It should not be interpreted as a guarantee that RaspAP can support this many simultaneous clients. In practice, this number depends on several factors and is a much lower value, as discussed in this FAQ.
RaspAP gives you advanced control over several Linux networking-related services. As a result, your AP may fail to start for a variety of reasons. You may also encounter errors connecting clients to +the AP, have no internet on AP clients, or observe clients being disconnected from the AP for no apparent reason.
+If any of the above happens, one of the best diagnostic tools at your disposal is RaspAP's built-in service logging facility. You may enable the hostapd service log by sliding the Logfile output toggle on the Hotspot > Logging tab and choosing Save settings. Finally, choose
+Restart hotspot and check the log output.
Similarly, you may also enable DHCP server activity by sliding either of the two logging options on the DHCP server > Logging tab.
+In some situations, you may need more comprehensive information to self-diagnose a problem. RaspAP lets you generate a debug log with a detailed summary of your system including the installed OS, Linux kernel version, attached USB devices, RaspAP settings, network configuration and current state of several AP-related services.
+To create this log, simply click or tap on the Generate debug log button from the System > Tools tab. You will be prompted to choose a location to store the generated raspap_debug.log file on your local computer or mobile device. An example portion of RaspAP's debug log is shown below:
System Info
+===========
+Hardware: Raspberry Pi 3 Model B Rev 1.2
+Detected OS: Debian GNU/Linux 12 (bookworm) 64-bit
+Kernel: Linux raspberrypi 6.1.0-rpi4-rpi-v8 (2023-10-05) aarch64 GNU/Linux
+System Uptime: 4 days, 20 hours, 45 minutes
+Memory Usage: 29.0749%
+
+Installed Packages
+==================
+PHP Version: 8.2.7 (cli) (built: Jun 9 2023 19:37:27) (NTS)
+Dnsmasq Version: 2.89
+dhcpcd Version: 9.4.1
+lighttpd Version: 1.4.69
+vnStat Version: 2.10
+
+RaspAP Install
+==============
+RaspAP Version: 2.9.9
+RaspAP Installation Directory: /var/www/html
+RaspAP hostapd.ini contents:
+WifiInterface = wlan0
+Tip
+If you are unable to perform a self-diagnosis and would like to share your debug log (or a portion of it) with another party, upload it to Pastebin or Ubuntu Pastebin. Please don't paste the log in its entirety to RaspAP's discussions, issues or other support channels.
+RaspAP's debug log contains information about your system and local network configuration. However, no passwords or other senstive data are included.
+Look for any reported errors logged by the hostapd, dhcpcd or dnsmasq services. In most cases, errors thrown by one or more of these services have been discussed in various online forums.
+Start by searching the official Raspberry Pi forums or Raspberry Pi on Stack Exchange. Chances are the problems with your AP have been discussed and answered before.
For additional help and advice, the FAQ is a rich source of troubleshooting info that is continuously updated with answers to the most commonly asked questions. For issues not covered in +the FAQ, you may find many topics in RaspAP discussions and the RaspAP subreddit.
+Tip
+Capture output from the Linux kernel's message buffer with dmesg to help diagnose failure events. Read the last 100 lines with dmesg | tail -100 and look for any anomalies.
The performance of WiFi radios may be impacted by many factors, including, but not limited to:
+Bear these things in mind if your AP exhibits unexpected behavior and do your best to mitigate them.
+It is generally advisable to begin with RaspAP's default configuration, which has been rigorously tested and validated with the project's supported operating systems. If, after modifying RaspAP's default settings, your AP no longer functions as expected, you may perform a system reset to restore these defaults.
+Each time you revert to RaspAP's base settings, your existing service configuration files are automatically backed up to /etc/raspap/backups. In this way, you can compare differences between your files and the default configuration, if needed.
+There are many ways to do this in Linux, such as using the built-in GNU diff tool. Another option is to install colordiff, a wrapper for diff that produces the same output but with colored syntax highligting.
+Install colordiff with sudo apt-get install colordiff.
Similarly, the web files located in the default /var/www/html root are backed up to /var/www in a directory named with a timestamp. Therefore, any changes you've made to RaspAP's internals are preserved.
Experimental (Unsupported)
+This walkthrough describes an installation of RaspAP on the Raspberry Pi Zero W or Zero 2 W models. However, the same steps apply to any device with a chipset capable of supporting this mode.
+A managed mode AP, variously known as WiFi client AP mode, a micro-AP or simply AP-STA, usually works with the Quick Installer if the steps below are followed carefully. This feature was added to RaspAP specifically to support Internet of Things (IoT) and embedded applications for the Pi Zero W, however it is equally useful for a broad range of projects.
+Disclaimer
+This mode is completely unsupported and should be used for educational purposes only. If you need a reliable solution with an access point (AP) and wireless client (STA) on the same device, buy a second Wi-Fi adapter and follow this FAQ instead.
+Before proceeding with the installation, it's important to have a basic understanding of how AP-STA works.
+Many wireless devices support simultaneous operation as both an access point (AP) and as a wireless client/station (STA). This is sometimes called Wi-Fi AP/STA concurrency. In this configuration, it is possible to create a software AP acting as a wireless repeater for an existing network, using a single wireless device. This capability is listed in the following section in the output of iw list:
$ iw list | grep -A 4 'valid interface'
+ valid interface combinations:
+ * #{ managed } <= 1, #{ P2P-device } <= 1, #{ P2P-client, P2P-GO } <= 1,
+ total <= 3, #channels <= 2
+ * #{ managed } <= 1, #{ AP } <= 1, #{ P2P-client } <= 1, #{ P2P-device } <= 1,
+ total <= 4, #channels <= 1
+The second valid interface combination indicates that both a managed and AP configuration is possible. The constraint #channels <= 1 means that your software AP must operate on the same channel as your Wi-Fi client connection.
Note
+If you have a second wireless adapter bound to wlan1 on a Pi Zero W (or other device), refer to this FAQ.
There are many scenarios in which AP-STA mode might be useful. These are some of the more popular ones:
+Security is an important consideration with IoT and it can be beneficial to keep your devices on a separate network, for safetyโs sake. No one wants a random internet user turning your lights on and off.
+In this configuration, we create a virtual network interface (here uap0) and add it as the AP to the physical wlan0 device. This virtual interface is used by several of the services needed to operate a software access point. RaspAP manages these configurations in the background for you. Relevant sections are displayed below as examples.
dhcpcd.conf:
+
# RaspAP uap0 configuration
+interface uap0
+static ip_address=192.168.50.1/24
+nohook wpa_supplicant
+hostapd.conf:
+
dnsmasq.conf:
+
# RaspAP uap0 configuration
+interface=lo,uap0 # Use interfaces lo and uap0
+bind-interfaces # Bind to the interfaces
+domain-needed # Don't forward short names
+bogus-priv # Never forward addresses in the non-routed address spaces
+On AP-STA startup and system reboots, RaspAP's service control script adds the virtual uap0 interface and brings it up, like so:
After the virtual uap0 interface is added to the wlan0 physical device, we can then start up hostapd. It is important that the virtual interface is brought up first, otherwise it will fail with the message "could not configure driver mode". We also need to be sure that the interface is not managed by systemd-networkd, so this service should be disabled. These steps are handled by the RaspAP daemon.
With a basic understanding of AP-STA mode, we can proceed with the installation.
+ssh access by creating an empty file called "ssh" (no extension) in the SD card's root. ssh pi@raspberrypi.local is typical.curl -sL https://install.raspap.com | bash.eth0 interface. In this case, you will not be prompted to reboot your Pi.http://raspberrypi.local.
Note
+The WiFi client AP mode option will be disabled, or "greyed out", until a wireless client is configured.
+Rebooting before configuring AP-STA mode is likely the main cause of problems for users with the Pi Zero W. The reason is the default configuration is designed for a wired (ethernet) AP.
+Once the Pi Zero W is configured in AP-STA mode, RaspAP will store several values in /etc/raspap/hostapd.ini:
+
raspapd to determine that a managed mode AP is enabled for the Pi and restore the connection after subsequent reboots.
+Changes to the hotspot configuration should be applied to the wlan0 physical device, not uap0 (a virtual interface). In other words, if you wish to change hostapd settings, stop the hotspot,
+disable AP-STA, make your config changes on wlan0, re-enable AP-STA and finally restart hostapd. An explanation is available here.