1
0
mirror of https://github.com/billz/raspap-webgui.git synced 2023-10-10 13:37:24 +02:00
raspap-webgui/README.md

172 lines
11 KiB
Markdown
Raw Normal View History

2019-06-11 12:37:29 +02:00
![](https://i.imgur.com/xeKD93p.png)
2020-02-27 19:14:33 +01:00
[![Release 2.2](https://img.shields.io/badge/Release-2.2-green.svg)](https://github.com/billz/raspap-webgui/releases) [![Awesome](https://awesome.re/badge.svg)](https://github.com/thibmaek/awesome-raspberry-pi) [![Financial Contributors on Open Collective](https://opencollective.com/raspap/all/badge.svg?label=financial+contributors)](https://opencollective.com/raspap) [![Twitter URL](https://img.shields.io/twitter/url?label=%40RaspAP&logoColor=%23d8224c&url=https%3A%2F%2Ftwitter.com%2Frasp_ap)](https://twitter.com/rasp_ap) [![Subreddit subscribers](https://img.shields.io/reddit/subreddit-subscribers/RaspAP?style=social)](https://www.reddit.com/r/RaspAP/)
2018-09-22 13:02:02 +02:00
2020-01-31 12:57:00 +01:00
RaspAP lets you quickly get a WiFi access point up and running to share the internet connectivity of a Raspberry Pi. Our famous [Quick installer](#quick-installer) creates a known-good default configuration that "just works" on all current Raspberry Pis with onboard wireless. A handsome responsive interface gives you control over the relevant services and networking options. OpenVPN client support, SSL, security audits, themes and multilingual options round out the package.
2015-02-27 16:10:52 +01:00
2020-01-29 22:08:22 +01:00
RaspAP has been featured on sites such as [Instructables](http://www.instructables.com/id/Raspberry-Pi-As-Completely-Wireless-Router/), [Adafruit](https://blog.adafruit.com/2016/06/24/raspap-wifi-configuration-portal-piday-raspberrypi-raspberry_pi/), [Raspberry Pi Weekly](https://www.raspberrypi.org/weekly/commander/) and [Awesome Raspberry Pi](https://project-awesome.org/thibmaek/awesome-raspberry-pi) and implemented in countless projects.
2015-02-27 17:18:06 +01:00
2020-01-31 12:57:00 +01:00
We hope you enjoy using RaspAP as much as we do creating it. Tell us how you use this with [your own Pi-powered projects](https://github.com/billz/raspap-awesome)!
2015-02-27 16:10:52 +01:00
2020-03-01 18:05:13 +01:00
![](https://i.imgur.com/7LsxEGP.gif)
2019-11-01 18:29:44 +01:00
![](https://i.imgur.com/EiIpdOS.gif)
![](https://i.imgur.com/eCjUS1H.gif)
![](https://i.imgur.com/5FT2BcS.gif)
![](https://i.imgur.com/RKaBFrZ.gif)
2015-02-27 16:10:52 +01:00
## Contents
2015-03-11 11:34:35 +01:00
- [Prerequisites](#prerequisites)
2016-06-16 17:02:47 +02:00
- [Quick installer](#quick-installer)
2019-04-09 21:56:19 +02:00
- [Simultaneous AP and Wifi client](#simultaneous-ap-and-wifi-client)
2019-03-11 23:38:42 +01:00
- [Support us](#support-us)
2016-06-16 17:02:47 +02:00
- [Manual installation](#manual-installation)
2020-01-07 09:21:00 +01:00
- [802.11ac 5GHz support](#80211ac-5ghz-support)
2018-06-01 20:19:07 +02:00
- [Multilingual support](#multilingual-support)
2019-07-30 02:36:54 +02:00
- [HTTPS support](#https-support)
2019-11-18 13:44:02 +01:00
- [OpenVPN support](#openvpn-support)
2015-02-27 16:10:52 +01:00
- [How to contribute](#how-to-contribute)
2019-04-13 18:08:21 +02:00
- [Reporting issues](#reporting-issues)
2015-03-11 12:17:03 +01:00
- [License](#license)
2015-02-27 16:10:52 +01:00
2015-03-11 11:34:35 +01:00
## Prerequisites
2019-06-28 10:08:32 +02:00
Start with a clean install of the [latest release of Raspbian](https://www.raspberrypi.org/downloads/raspbian/) (currently Buster). Raspbian Buster Lite is recommended.
2015-03-11 11:34:35 +01:00
2019-03-06 01:34:34 +01:00
1. Update Raspbian, including the kernel and firmware, followed by a reboot:
```
sudo apt-get update
sudo apt-get dist-upgrade
sudo reboot
```
2. Set the WiFi country in raspi-config's **Localisation Options**: `sudo raspi-config`
2015-03-11 11:34:35 +01:00
2020-01-31 12:57:00 +01:00
3. If you have a Raspberry Pi without an onboard WiFi chipset, the [**Edimax Wireless 802.11b/g/n nano USB adapter**](https://www.edimax.com/edimax/merchandise/merchandise_detail/data/edimax/global/wireless_adapters_n150/ew-7811un) is an excellent option it's small, cheap and has good driver support.
2015-03-11 11:34:35 +01:00
2019-03-06 01:34:34 +01:00
With the prerequisites done, you can proceed with either the Quick installer or Manual installation steps below.
2015-03-11 12:17:03 +01:00
2016-06-16 17:02:47 +02:00
## Quick installer
Install RaspAP from your RaspberryPi's shell prompt:
```sh
2019-11-19 22:36:46 +01:00
curl -sL https://install.raspap.com | bash
2016-06-16 17:02:47 +02:00
```
The [installer](https://github.com/billz/raspap-webgui/wiki/Quick-Installer-usage) will complete the steps in the manual installation (below) for you.
2016-06-16 17:02:47 +02:00
2016-10-23 22:39:22 +02:00
After the reboot at the end of the installation the wireless network will be
configured as an access point as follows:
* IP address: 10.3.141.1
* Username: admin
* Password: secret
2016-10-23 22:39:22 +02:00
* DHCP range: 10.3.141.50 to 10.3.141.255
* SSID: `raspi-webgui`
* Password: ChangeMe
2019-04-17 22:14:14 +02:00
**Note:** As the name suggests, the Quick Installer is a great way to quickly setup a new AP. However, it does not automagically detect the unique configuration of your RPi. Best results are obtained by connecting an RPi to ethernet (`eth0`) or as a WiFi client, also known as managed mode, with `wlan0`. For the latter, refer to [this FAQ](https://github.com/billz/raspap-webgui/wiki/FAQs#how-do-i-prepare-the-sd-card-to-connect-to-wifi-in-headless-mode). Please [read this](https://github.com/billz/raspap-webgui/wiki/Reporting-issues) before reporting an issue.
2019-04-16 15:47:42 +02:00
2019-04-09 21:56:19 +02:00
## Simultaneous AP and Wifi client
2019-04-17 22:14:14 +02:00
RaspAP lets you easily create an AP with a Wifi client configuration. With your RPi configured in managed mode, enable the AP from the **Advanced** tab of **Configure hotspot** by sliding the **Wifi client AP mode** toggle. Save settings and start the hotspot. The managed mode AP is functional without restart.
2019-04-09 21:56:19 +02:00
2019-11-01 19:12:31 +01:00
![](https://i.imgur.com/YObvd32.gif)
2019-04-09 21:56:19 +02:00
2019-12-13 16:27:53 +01:00
**Note:** This option is disabled until you configure your RPi as a wireless client. For a Raspberry Pi operating in [managed mode](https://github.com/billz/raspap-webgui/wiki/FAQs#how-do-i-prepare-the-sd-card-to-connect-to-wifi-in-headless-mode) without an `eth0` connection, this configuration must be enabled _before_ a reboot.
2019-04-15 09:18:20 +02:00
2019-03-11 23:38:42 +01:00
## Support us
2020-02-08 12:18:55 +01:00
RaspAP is free software, but powered by your support. If you find RaspAP useful for your personal or commercial projects, please [become a GitHub sponsor](https://github.com/sponsors/billz), join the project on [Open Collective](https://opencollective.com/raspap) or make a one-time donation with [PayPal](https://www.paypal.com/paypalme2/billzgithub). Any of these options makes a big difference!
2019-03-11 23:38:42 +01:00
2020-02-09 17:40:28 +01:00
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg?style=for-the-badge&logo=paypal&link=https://www.paypal.com/paypalme2/billzgithub)](https://www.paypal.com/paypalme2/billzgithub)
2016-06-16 17:02:47 +02:00
## Manual installation
2020-01-07 09:15:43 +01:00
Detailed manual setup instructions are provided [on our wiki](https://github.com/billz/raspap-webgui/wiki/Manual-installation).
2015-03-11 12:17:03 +01:00
2020-01-07 09:15:43 +01:00
## 802.11ac 5GHz support
RaspAP provides an 802.11ac wireless mode option for supported hardware (currently the RPi 3B+/4) and wireless regulatory domains. See [this FAQ](https://github.com/billz/raspap-webgui/wiki/FAQs#80211ac) for more information.
2016-05-29 17:38:43 +02:00
2018-06-01 20:19:07 +02:00
## Multilingual support
RaspAP uses [GNU Gettext](https://www.gnu.org/software/gettext/) to manage multilingual messages. In order to use RaspAP with one of our supported translations, you must configure a corresponding language package on your RPi. To list languages currently installed on your system, use `locale -a` at the shell prompt. To generate new locales, run `sudo dpkg-reconfigure locales` and select any other desired locales. Details are provided on our [wiki](https://github.com/billz/raspap-webgui/wiki/Translations#raspap-in-your-language).
The following translations are currently maintained by the project:
2018-06-16 23:48:00 +02:00
- Deutsch
2018-06-01 20:19:07 +02:00
- Français
- Italiano
- Português
- Svenska
- Nederlands
2018-10-17 17:56:21 +02:00
- 简体中文 (Chinese Simplified)
2019-10-30 08:14:08 +01:00
- Indonesian
- 한국어 (Korean)
- 日本語 (Japanese)
- Tiếng Việt (Vietnamese)
2018-11-04 18:02:04 +01:00
- Čeština
2018-11-19 18:26:44 +01:00
- Русский
2019-01-13 09:56:48 +01:00
- Español
2019-03-05 00:17:03 +01:00
- Finnish
- Sinhala
2019-06-10 11:37:39 +02:00
- Türkçe
- ελληνικό (Greek)
2018-06-01 20:19:07 +02:00
If your language is not in the list above, why not [contribute a translation](https://github.com/billz/raspap-webgui/wiki/Translations#contributing-a-translation)? Contributors will receive credit as the original translators.
2019-07-30 02:36:54 +02:00
## HTTPS support
2019-11-08 11:14:44 +01:00
The Quick Installer may be used to [generate SSL certificates](https://github.com/billz/raspap-webgui/wiki/SSL-certificates-(Quick-Installer)) with `mkcert`. The installer automates the manual steps [described in the wiki](https://github.com/billz/raspap-webgui/wiki/SSL-(Manual-steps)), including configuring lighttpd with SSL support.
Simply append the `-c` or `--cert` option to the Quick Installer, like so:
2019-11-20 00:23:52 +01:00
```sh
curl -sL https://install.raspap.com | bash -s -- --cert
2019-11-08 11:14:44 +01:00
```
**Note**: this only installs mkcert and generates an SSL certificate with the input you provide. It does *not* (re)install RaspAP.
More information on SSL certificates and HTTPS support is available [on our wiki](https://github.com/billz/raspap-webgui/wiki/SSL-certificates-(Quick-Installer)).
2019-07-30 02:36:54 +02:00
2019-11-18 13:44:02 +01:00
## OpenVPN support
OpenVPN may be optionally installed by the Quick Installer. Once this is done, you can manage client configuration and the `openvpn-client` service with RaspAP.
2015-03-11 12:17:03 +01:00
2019-11-18 13:44:02 +01:00
To configure an OpenVPN client, upload a valid .ovpn file and, optionally, specify your login credentials. RaspAP will store your client configuration and add firewall rules to forward traffic from OpenVPN's `tun0` interface to your configured wireless interface.
**Note**: this feature is currently in beta. Please [read this](https://github.com/billz/raspap-webgui/wiki/FAQs#-openvpn-fails-to-start-andor-i-have-no-internet-help) before reporting an issue.
2015-03-11 12:17:03 +01:00
2015-02-27 16:10:52 +01:00
## How to contribute
2020-01-07 09:21:00 +01:00
1. Fork the project in your account and create a new branch: `your-great-feature`.
2. Open an issue in the repository describing the feature contribution you'd like to make. This will help us get you started on the right foot.
2020-01-07 09:15:43 +01:00
3. Commit changes in your feature branch.
4. Open a pull request and reference the initial issue in the pull request message.
2019-04-10 10:57:47 +02:00
2020-02-13 08:12:50 +01:00
Find out more about our [coding style guidelines and recommended tools](CONTRIBUTING.md).
2015-02-27 16:10:52 +01:00
2019-04-13 18:08:21 +02:00
## Reporting issues
Please [read this](https://github.com/billz/raspap-webgui/wiki/Reporting-issues) before reporting a bug.
## Contributors
### Code Contributors
2020-02-13 17:08:33 +01:00
This project exists thanks to all the awesome people who [contribute](CONTRIBUTING.md) their time and expertise.
<a href="https://github.com/billz/raspap-webgui/graphs/contributors"><img src="https://opencollective.com/raspap/contributors.svg?width=890&button=false" /></a>
### Financial Contributors
2020-02-13 11:17:45 +01:00
Become a [financial contributor](https://opencollective.com/raspap/contribute) and help us sustain our community.
#### Individuals
<a href="https://opencollective.com/raspap"><img src="https://opencollective.com/raspap/individuals.svg?width=890"></a>
#### Organizations
2020-02-13 11:17:45 +01:00
[Support this project](https://opencollective.com/raspap/contribute) with your organization. Your logo will show up here with a link to your website.
<a href="https://opencollective.com/raspap/organization/0/website"><img src="https://opencollective.com/raspap/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/1/website"><img src="https://opencollective.com/raspap/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/2/website"><img src="https://opencollective.com/raspap/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/3/website"><img src="https://opencollective.com/raspap/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/4/website"><img src="https://opencollective.com/raspap/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/5/website"><img src="https://opencollective.com/raspap/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/6/website"><img src="https://opencollective.com/raspap/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/7/website"><img src="https://opencollective.com/raspap/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/8/website"><img src="https://opencollective.com/raspap/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/raspap/organization/9/website"><img src="https://opencollective.com/raspap/organization/9/avatar.svg"></a>
2015-02-27 16:10:52 +01:00
## License
2016-05-01 08:54:24 +02:00
See the [LICENSE](./LICENSE) file.