From e5ce4f202b22c321dcdd013a8081d38957bfe7f0 Mon Sep 17 00:00:00 2001 From: Bill Zimmerman Date: Sat, 4 Apr 2020 00:00:56 +0200 Subject: [PATCH] Updated FAQs (markdown) --- FAQs.md | 65 +++++++++++++++++++++++++-------------------------------- 1 file changed, 28 insertions(+), 37 deletions(-) diff --git a/FAQs.md b/FAQs.md index 3fe47f2..03b27f2 100644 --- a/FAQs.md +++ b/FAQs.md @@ -23,7 +23,7 @@ This has been written to address some frequently asked questions among users of * [Why is the maximum throughput of my 802.11n AP reduced by half?](#wirelessn) * [How do I remove RaspAP?](#uninstall) -### What do all these settings in the UI do? Changing them seems to have no effect. +## What do all these settings in the UI do? Changing them seems to have no effect. RaspAP manipulates several daemons, services and helper programs behind the scenes for you. In the footer of each management panel is a helpful "Information provided by..." label. These indicate which Linux daemon and/or program is being modified by the UI. Learning what these services are and how they work will go a long way toward demystifying things. ![](https://i.imgur.com/q1RflMy.png) @@ -32,15 +32,15 @@ For example, two of the best starting points for understanding `hostapd` (the se **Important:** After you choose **Save settings** for `hostapd` or `dhcpcd`, these services _must_ be stopped and restarted for your changes to take effect. If you're not sure if your AP is behaving as expected, enable logging in the **Advanced** options of **Configure hotspot** and check the output. -### My custom rc.local/networking configuration/wpa configuration is gone! +## My custom rc.local/networking configuration/wpa configuration is gone! Currently, RaspAP generates a few of its own files so that it starts with a known configuration. Your custom configurations haven't been lost however, they've been moved to the backups directory in `/etc/raspap/backups`. Feel free to SSH in to restore those files to their rightful position, however, you may need to ensure that the RaspAP modifications are applied to your own custom configurations. -### I changed the admin password and forgot what it was. Help! +## I changed the admin password and forgot what it was. Help! Login credentials are stored in `/etc/raspap/raspap.auth`. The password is encrypted and cannot be edited manually. However, deleting this file with `sudo rm /etc/raspap/raspap.auth` will restore the default admin password. -### What are the steps to upgrade RaspAP? +## What are the steps to upgrade RaspAP? Upgrading your current install to a **specific release** is very straightforward. For example, to upgrade to the current release [version 2.3](https://github.com/billz/raspap-webgui/releases/tag/2.3), enter the following in the RaspAP install folder (default location is `/var/www/html`): ``` @@ -57,43 +57,34 @@ sudo git pull origin master ``` Whichever method you choose (specific release or latest updates), your RaspAP configuration won't be changed. -### RaspAP control panel works but there is no WiFi after reboot. +## RaspAP control panel works but there is no WiFi after reboot. This problem often occurs when another program tries to reconfigure hostapd at startup. It can also happen when your RPi is configured as both a WiFi client and access point, known as a 'managed mode' AP. To address this, RaspAP has added a `systemd` init service to bring up networking services in a predictable order and timing after the Linux kernel is booted. You can check the status of this service with: ``` -sudo systemctl status raspap.service +sudo systemctl status raspapd.service ``` -The `raspap.service` is optionally installed and enabled by the Quick Installer. It is also included in the manual setup steps. +The `raspapd.service` is optionally installed and enabled by the Quick Installer. It is also included in the manual setup steps. -### Do I need the RaspAP service to run at boot? -If you are using your RPi as a client on a WiFi network (also known as managed mode) and hosting an access point simultaneously, the `raspap.service` will ensure that your hotspot is active after a reboot. It does this by detecting WiFi client AP mode, adding the `uap0` interface and starting up networking services in a specific order. +## Do I need the RaspAP service to run at boot? +If you are using your RPi as a client on a WiFi network (also known as managed mode) and hosting an access point simultaneously, the `raspapd.service` will ensure that your hotspot is active after a reboot. It does this by detecting WiFi client AP mode, adding the `uap0` interface and starting up networking services in a specific order. If your RPi is configured with wired ethernet (`eth0`) or you haven't experienced problems with the AP starting on boot, you can disable the RaspAP daemon like so: ``` -sudo systemctl disable raspap.service +sudo systemctl disable raspapd.service ``` -### How do I integrate RaspAP with Pi-hole? -[Pi-hole®](https://github.com/pi-hole/pi-hole) is a popular RPi-based project that blocks ads network-wide by creating a DNS sinkhole. There have been several discussions around integrating RaspAP with Pi-hole, with the end goal of hosting a complete AP and ad-blocker on a single device. This is possible with a few modifications, essentially giving Pi-hole permission to manage `dnsmasq` leases. +## How do I integrate RaspAP with Pi-hole? +There have been several discussions around integrating RaspAP with Pi-hole, with the end goal of hosting a complete AP and ad-blocker on a single device. Both projects rely on `dnsmasq`, so integration between them is tricky. One workaround is [proposed here](https://discourse.pi-hole.net/t/raspap-pihole/14739/12). -Follow these steps in the order below: +**Update:** By popular demand, RaspAP has released its own [ad blocking facility](https://github.com/billz/raspap-webgui/wiki/Ad-blocking-(Beta)). Feedback is welcome. -1. Install RaspAP -2. Install Pi-Hole -3. `sudo touch /var/lib/misc/dnsmasq.leases` -4. `sudo chown pihole:pihole /var/lib/misc/dnsmasq.leases` -4. Reboot manually or `sudo reboot` -([source](https://discourse.pi-hole.net/t/raspap-pihole/14739/7)) - -Please note: Pi-hole integration is not officially supported by this project. Therefore, bug reports will not be addressed. - -### Can I configure RaspAP to work with a captive portal? +## Can I configure RaspAP to work with a captive portal? Yes, the [nodogsplash project](https://github.com/nodogsplash/nodogsplash) works just fine with RaspAP and is recommended over other methods. A detailed setup guide is [available here](https://github.com/billz/raspap-webgui/wiki/Captive-portal-setup). -### Why can't I access wireless mode 'N' (802.11n)? +## Why can't I access wireless mode 'N' (802.11n)? On the **Configure hotspot** > **Security** tab, be sure to select CCMP for the Encryption Type. Save the settings and restart the hotspot. The wireless mode should be reported on clients as 802.11b/g/n. ``` @@ -108,7 +99,7 @@ RaspAP: If using TKIP for encryption with WPA, you will be restricted to 54 Mb/s. This is because the IEEE 802.11n draft prohibits using high throughput with WEP or TKIP ciphers. -### How do I prepare the SD card to connect to WiFi in headless mode? +## How do I prepare the SD card to connect to WiFi in headless mode? Since [May 2016](https://www.raspberrypi.org/blog/another-update-raspbian/), Raspbian has been able to copy wifi details from `/boot/wpa_supplicant.conf` into `/etc/wpa_supplicant/wpa_supplicant.conf` to automatically configure wireless network access. An example `wpa_supplicant.conf` file is shown below. Replace the fields with your settings: @@ -125,7 +116,7 @@ network={ } ``` -### Can I use wlan0 and wlan1 rather than eth0 for my AP? +## Can I use wlan0 and wlan1 rather than eth0 for my AP? The short answer is yes. In this scenario, you may wish to use the built-in `wlan0` interface as the AP with a USB `wlan1` connection as the client, rather than wired ethernet (`eth0`). This is partly supported by RaspAP, although you will need to make two small updates. Change the following setting in `includes/config.php` to `wlan1`: @@ -147,10 +138,10 @@ sudo systemctl restart hostapd.service **Important:** Be aware that external WiFi adapters (ie, USB "dongles") vary greatly in terms of hardware capabilities and driver support. Many do not work out of the box on the RPi, require a powered USB hub, manual driver and/or firmware installation or are otherwise [not well suited for the RPi](https://elinux.org/RPi_USB_Wi-Fi_Adapters). For these reasons, issues related to wlan0 and wlan1 configurations with external adapters will not be considered. -### Can I use RaspAP as a monitor only, without changing my configuration? +## Can I use RaspAP as a monitor only, without changing my configuration? Yes, RaspAP has support for a so-called "monitor mode". In `config.php` change the setting `RASPI_MONITOR_ENABLED` to `true`. This disables the ability to modify settings, start/stop daemons, shutdown or reboot the RPi. RaspAP will continue to report interface statistics, service settings and data usage as normal. -### WiFi scanning doesn't work or I get the error `cannot execute "wpa_cli reconfigure"`. Help! +## WiFi scanning doesn't work or I get the error `cannot execute "wpa_cli reconfigure"`. Help! On some configurations, the **Configure WiFi client** panel may appear empty. This project uses the `wpa_supplicant` command line client `wpa_cli` to populate a list of available wireless networks. If you can't execute this from the shell, neither can the web UI. For example, the results of this command: ``` @@ -174,7 +165,7 @@ sudo wpa_supplicant -B -Dnl80211,wext -c/etc/wpa_supplicant/wpa_supplicant.conf substituting `wlan0` with your wireless interface, if necessary. You should then be able to perform scans as expected. -### Can the Quick Installer accept the default options without prompting me? +## Can the Quick Installer accept the default options without prompting me? Yes, the [Quick Installer](https://github.com/billz/raspap-webgui/wiki/Quick-Installer-usage) has a non-interactive mode that lets you perform unattended setups. This mode assumes "yes" as an answer to all prompts. You can do an unattended install of RaspAP by appending the `--yes` command-line option, like so: ``` @@ -183,7 +174,7 @@ curl -sL https://install.raspap.com | bash -s -- --yes The options `-y` or `--assume-yes` are also accepted and have the same result. -### Can I configure an alternate port for RaspAP's web service? +## Can I configure an alternate port for RaspAP's web service? Yes, you can now do this from the **Advanced** tab in System. Manual steps for changing lighttpd's default port are included below. Edit `/etc/lighttpd/lighttpd.conf` and change the following line: @@ -197,7 +188,7 @@ sudo systemctl restart lighttpd.service ``` You can then access RaspAP as before with the new port number in the URI, for example, http://raspberrypi.local:8080. This will allow you run another web server alongside lighttpd, if that is your goal. -### Can I use RaspAP with my custom dnsmasq configuration? +## Can I use RaspAP with my custom dnsmasq configuration? Yes, RaspAP supports this through the use of `dnsmasq.d`. The primary `dnsmasq.conf` managed by the UI includes the following directive to enable your custom .conf files: ``` @@ -207,7 +198,7 @@ conf-dir=/etc/dnsmasq.d Configuration files placed in this directory will be used by the dnsmasq service and are untouched by the UI. -### OpenVPN fails to start and/or I have no internet. Help! +## OpenVPN fails to start and/or I have no internet. Help! RaspAP supports OpenVPN clients by uploading a valid .ovpn file to `/etc/openvpn/client` and, optionally, creating a `login.conf` file with your client auth credentials. Additionally, in line with the project's [default configuration](https://github.com/billz/raspap-webgui/wiki/Reporting-issues#default-settings), the following iptables rules are added to forward traffic from OpenVPN's `tun0` interface to your configured wireless interface (`wlan0` is the default): ``` @@ -217,7 +208,7 @@ RaspAP supports OpenVPN clients by uploading a valid .ovpn file to `/etc/openvpn It is your responsibility to provide a valid .ovpn file; RaspAP does not attempt to validate the settings or RSA keys contained in this file. If OpenVPN fails to start, check for errors with `sudo systemctl status openvpn-client@client` and `journalctl --identifier openvpn`. -### How do I exclude NAT rules from IP traffic on localhost? +## How do I exclude NAT rules from IP traffic on localhost? RaspAP's [Quick Installer](https://github.com/billz/raspap-webgui/wiki/Quick-Installer-usage) configures network-address-translation (NAT) with iptables rules, so that the RPi can act as an internet gateway to multiple hosts on a local network with a single public IP address. This is done by rewriting the addresses of IP packets as they pass through the NAT system. Many access points, including RaspAP, use a combination of IP forwarding and masquerading to achieve this. In some cases, NAT rules applied to `localhost` can interfere with other services running on an RPi. An example is the Plex Media Server, which has an API that listens on localhost. As of this writing, the Plex API has been built to not authenticate communication between service processes of the server. This can cause a failure to communicate with the Plex API or similar add-on services on your RPi. @@ -247,7 +238,7 @@ Chain POSTROUTING (policy ACCEPT 0 packets, 0 bytes) ``` Refer to [this issue](https://github.com/billz/raspap-webgui/issues/333#issue-454352554). -### Why is the 802.11ac 5GHz wireless mode option disabled in Configure hotspot? +## Why is the 802.11ac 5GHz wireless mode option disabled in Configure hotspot? **Short answer:** because of wireless regulatory restrictions for your country. If the AC option is disabled on your RPi, there are two small configuration changes you can make to enable it. First, configure your RPi's wireless regulatory domain with `sudo iw reg set US`. Next, on the **Advanced** tab of **Configure hotspot**, choose "United States" as the country code and save settings. You can now choose 802.11ac from the wireless mode select on the **Basic** tab. Choosing the AC wireless mode will populate the supported 5 GHz channels for you. @@ -265,7 +256,7 @@ hostapd: Could not set channel for kernel driver In testing, stable AP's on the RPi's supported AC channels were only reliably obtained with 'US' as the regulatory domain. To get a list of the supported channels on your RPi for the 2.4 and 5 GHz bands, use `iw phy phy0 channels`. Refer to [this issue](https://github.com/billz/raspap-webgui/issues/450#issuecomment-569343686). -### I think my country allows 5 GHz AP channels. Can I test this? +## I think my country allows 5 GHz AP channels. Can I test this? Yes, you can. In the spirit of experimentation and discovery, this project makes it easy to override RaspAP's [default configuration](https://github.com/billz/raspap-webgui/wiki/Reporting-issues#default-settings). The file [wireless.json](https://github.com/billz/raspap-webgui/blob/master/config/wireless.json) contains the regulatory domains and channels for the 2.4 and 5 GHz bands. Add a valid ISO Alpha-2 country code to the list of `5Ghz_max48ch` countries and save the file. Next, edit `includes/config.php` and add the same country to this constant: ``` @@ -277,7 +268,7 @@ The **Configure hotspot** page will now let you select AC as a wireless mode opt **Note:** it is recommended to monitor logs such as `dmesg` and the hostapd error log (available in the **Logfile output** tab of RaspAP) while doing this. Bug reports like "AC doesn't work" and/or troubleshooting requests will not be considered. No hard feelings. -### Why is the maximum throughput of my 802.11n AP reduced by half? +## Why is the maximum throughput of my 802.11n AP reduced by half? In order to achieve optimal throughput with 802.11n, the wireless stream must operate at a 40 MHz wide channel on the 2.4 GHz band. A 20 MHz channel will restrict you to 72 Mbps. Your `hostapd.conf` might have the required settings, but this is no guarantee of a 40 MHz channel. In practice, this can be quite difficult due to interference on the 2.4 GHz band. There are many things that will cause an AP to fallback to 20 MHz. The most common reason is if an AP detects another wireless network within 40 MHz, i.e. two channels, of its own channel. For example, if an AP is set to channel 6, another network operating anywhere from channel 4 to 8 will trigger a fallback. hostapd will usually report a fallback like so: @@ -290,7 +281,7 @@ For more information on optimizing 802.11n, refer to this [resource](https://www Generally speaking, the 5 GHz band has substantially greater capacity due to more non-overlapping radio channels and less radio interference as compared to the 2.4 GHz band. -### How do I remove RaspAP? +## How do I remove RaspAP? We have provided an uninstall script to remove RaspAP cleanly, and also restore any backups of your configuration that were created before RaspAP was installed. The uninstall script is located in `installers/uninstall.sh`. To start the uninstaller, simply run the following from the project root folder (default location is `/var/www/html`): ```