forked from immortalwrt/packages
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- added a major readme update based on the work of @richb-hanover Signed-off-by: Dirk Brenken <[email protected]>
- Loading branch information
Showing
1 changed file
with
91 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,60 +1,99 @@ | ||
| <!-- markdownlint-disable --> | ||
|
|
||
| # travelmate, a wlan connection manager for travel router | ||
| # Travelmate, a wlan connection manager for travel routers | ||
|
|
||
| ## Description | ||
| If you’re planning an upcoming vacation or a business trip, taking your laptop, tablet or smartphone give you the ability to connect with friends or complete work on the go. But many hotels don’t have a secure wireless network setup or you’re limited on using a single device at once. Investing in a portable, mini travel router is a great way to connect all of your devices at once while having total control over your own personalized wireless network. | ||
| A logical combination of AP+STA mode on one physical radio allows most of OpenWrt supported router devices to connect to a wireless hotspot/station (STA) and provide a wireless access point (AP) from that hotspot at the same time. Downside of this solution: whenever the STA interface looses the connection it will go into an active scan cycle which renders the radio unusable for AP mode operation, therefore the AP is taken down if the STA looses its association. | ||
| To avoid these kind of deadlocks, travelmate will set all station interfaces to an "always off" mode and connects automatically to available/configured hotspots. | ||
|
|
||
| ## Main Features | ||
| * STA interfaces operating in an "always off" mode, to make sure that the AP is always accessible | ||
| * easy setup within normal OpenWrt environment | ||
| * strong LuCI-Support with builtin interface wizard and a wireless station manager | ||
| * render the QR-Code of the selected Access Point in LuCI to comfortably transfer the WLAN credentials to your mobile devices | ||
| * fast uplink connections | ||
| * support all kinds of uplinks, incl. hidden and enterprise uplinks (WEP-based uplinks are no longer supported!) | ||
| * continuously checks the existing uplink connection (quality), e.g. for conditional uplink (dis-) connections | ||
| * automatically add open uplinks to your wireless config, e.g. hotel captive portals | ||
| * captive portal detection with internet online check and a 'heartbeat' function to keep the uplink connection up & running | ||
| * captive portal auto-login hook (configured via uci/LuCI), you are able to reference an external script for captive portal auto-logins (see example below) | ||
| * includes a vpn hook with support for 'wireguard' or 'openvpn' client setups to handle VPN (re-) connections automatically | ||
| * includes an email hook to 'msmtp' to send notification e-mails after every succesful uplink connect | ||
| * proactively scan and switch to a higher prioritized uplink, despite of an already existing connection | ||
| * connection tracking which keeps start and end date of an uplink connection | ||
| * automatically disable the uplink after n minutes, e.g. for timed connections | ||
| * automatically (re-)enable the uplink after n minutes, e.g. after failed login attempts | ||
| * option to generate a random unicast MAC address for each uplink connection | ||
| * ntp time sync before sending emails | ||
| * support devices with multiple radios in any order | ||
| If you’re taking your laptop, tablet, or phone on | ||
| an upcoming vacation or business trip, you'll want | ||
| to connect with friends or complete work on the go. | ||
| But many hotels don’t have a secure wireless network setup or | ||
| limit you to using a single device at a time. | ||
|
|
||
| Travelmate lets you use a small "travel router" to connect | ||
| all of your devices at once while having total control over your own | ||
| personal wireless network. | ||
|
|
||
| Travelmate runs on OpenWrt, and provides an "uplink" to the hotel's wireless access point/hotspot. | ||
| Travelmate then becomes the Access Point (AP) for you and your companions, | ||
| providing secure access to the internet. | ||
| See the [Installation and Usage](#installation-and-usage) section below. | ||
|
|
||
| Travelmate manages all the network settings, firewall settings, | ||
| connections to a hotel network, etc. and | ||
| automatically (re)connnects to configured APs/hotspots as they become available. | ||
|
|
||
| ## Main Benefits and Features | ||
|
|
||
| * Easy setup from LuCI web interface | ||
| with **Interface Wizard** and **Wireless Station manager** | ||
| * Display a QR code to | ||
| transfer the wireless credentials to your mobile devices | ||
| * Fast uplink connections | ||
| * Supports routers with multiple radios in any order | ||
| * Supports all kinds of uplinks, including hidden and enterprise uplinks. | ||
| (WEP-based uplinks are no longer supported) | ||
| * Continuously checks the existing uplink quality, | ||
| e.g. for conditional uplink (dis)connections | ||
| * Automatically add open uplinks to your wireless config, e.g. hotel captive portals | ||
| * Captive portal detection with a | ||
| 'heartbeat' function to keep the uplink connection up and running | ||
| * Captive portal hook for auto-login configured via uci/LuCI. | ||
| Use an external script for | ||
| captive portal auto-logins (see example below) | ||
| * VPN hook supports 'wireguard' or 'openvpn' client | ||
| setups to handle VPN (re)connections automatically | ||
| * Email hook via 'msmtp' sends notification e-mails | ||
| after every successful uplink connect | ||
| * Proactively scan and switch to a higher priority uplink, | ||
| replacing an existing connection | ||
| * Connection tracking logs start and end date of an uplink connection | ||
| * Automatically disable the uplink after n minutes, e.g. for timed connections | ||
| * Automatically (re)enable the uplink after n minutes, e.g. after failed login attempts | ||
| * (Optional) Generate a random unicast MAC address for each uplink connection | ||
| * NTP time sync before sending emails | ||
| * procd init and ntp-hotplug support | ||
| * runtime information available via LuCI & via 'status' init command | ||
| * status & debug logging to syslog | ||
| * Runtime information available via LuCI & via 'status' init command | ||
| * Log status and debug information to syslog | ||
| * STA interfaces operate in an "always off" mode, | ||
| to make sure that the AP is always accessible | ||
|
|
||
| ## Prerequisites | ||
| * [OpenWrt](https://openwrt.org), tested/compatible with current stable 23.x and latest OpenWrt snapshot | ||
| * 'dnsmasq' as dns backend | ||
| * 'iwinfo' for wlan scanning | ||
| * 'curl' for connection checking and all kinds of captive portal magic, e.g. cp detection and auto-logins | ||
| * a 'wpad' variant to support various WPA encrypted networks (WEP-based uplinks are no longer supported!) | ||
| * optional: 'qrencode' for AP QR code support | ||
| * The `luci-app-travelmate` ensures these packages are present: | ||
| * 'dnsmasq' as dns backend | ||
| * 'iwinfo' for wlan scanning | ||
| * 'curl' for connection checking and all kinds of captive portal magic, | ||
| e.g. cp detection and auto-logins | ||
| * a 'wpad' variant to support various WPA encrypted networks | ||
| (WEP-based uplinks are no longer supported!)* optional: 'qrencode' for AP QR code support | ||
| * optional: 'wireguard' or 'openvpn' for vpn client connections | ||
| * optional: 'msmtp' to send out travelmate related status messages via email | ||
|
|
||
| ## Installation & Usage | ||
| * **Please note:** before you start with travelmate ... | ||
| * setup at least one AP, ideally on a separate radio | ||
| * if you're using a single radio unit set the AP channel to 'auto' | ||
| * download [travelmate](https://downloads.openwrt.org/snapshots/packages/x86_64/packages) | ||
| * download [luci-app-travelmate](https://downloads.openwrt.org/snapshots/packages/x86_64/luci) | ||
| * install both packages (_opkg install travelmate_, _opkg install luci-app-travelmate_) | ||
| * the LuCI application is located under the 'Services' menu | ||
| * start the travelmate 'Interface Wizard' once | ||
| * add multiple uplink stations as you like via the 'Wireless Stations' tab | ||
| * happy traveling ... | ||
| * optional: 'msmtp' to send out Travelmate related status messages via email | ||
|
|
||
| ## Installation and Usage | ||
| * Install OpenWrt on your router, and set it up to allow wireless connections. | ||
| Be sure to set a strong password on the wireless channel(s) so that only | ||
| you and your companions can use it. | ||
| * Decide which radio you'll use for the Travelmate uplink (radio0, radio1, etc): | ||
| * 2.4GHz allows a longer (more distant) link; 5GHz provides a faster link | ||
| * Travelmate works on all radios. | ||
| But for better performance, configure the AP on a separate radio from | ||
| the one you're planning to use as the uplink. | ||
| * Use LuCI web interface to install both **travelmate** and **luci-app-travelmate** | ||
| * Open the Travelmate LuCI application - **Services -> Travelmate** | ||
| * You must use the Travelmate **Interface Wizard** one time to | ||
| configure the uplink, firewall and other network settings | ||
| * Use the **Wireless Stations** tab to add an uplink station | ||
| * **Scan** the radio you chose for the uplink | ||
| * Click **Add Uplink...** for the desired SSID. | ||
| If there are multiples, choose the one with the largest _Strength_ | ||
| * You'll need to enter the credentials (password, etc) | ||
| * You should be "on the air" - test by browsing the internet | ||
| * You may add additional uplinks (for different locations) | ||
| by repeating the previous step | ||
| * Happy traveling ... | ||
|
|
||
| ## Travelmate config options | ||
| * usually the pre-configured travelmate setup works quite well and no manual config overrides are needed, all listed options apply to the 'global' section: | ||
| * usually the pre-configured Travelmate setup works quite well and no manual config overrides are needed, all listed options apply to the 'global' section: | ||
|
|
||
| | Option | Default | Description/Valid Values | | ||
| | :----------------- | :--------------------------------- | :---------------------------------------------------------------------------------------------------- | | ||
|
|
@@ -140,7 +179,7 @@ user yyy | |
| password zzz | ||
| </code></pre> | ||
|
|
||
| Finally enable E-Mail support in travelmate and add a valid E-Mail receiver address. | ||
| Finally enable E-Mail support in Travelmate and add a valid E-Mail receiver address. | ||
|
|
||
| ## Captive Portal auto-logins | ||
| For automated captive portal logins you can reference an external shell script per uplink. All login scripts should be executable and located in '/etc/travelmate' with the extension '.login'. The package ships multiple ready to run auto-login scripts: | ||
|
|
@@ -166,7 +205,7 @@ Hopefully more scripts for different captive portals will be provided by the com | |
|
|
||
| ## Runtime information | ||
|
|
||
| **receive travelmate runtime information:** | ||
| **Receive Travelmate runtime information:** | ||
| <pre><code> | ||
| root@2go:~# /etc/init.d/travelmate status | ||
| ::: travelmate runtime information | ||
|
|
@@ -182,14 +221,14 @@ root@2go:~# /etc/init.d/travelmate status | |
| + system : GL.iNet GL-A1300, OpenWrt SNAPSHOT r24187-bb8fd41f9a | ||
| </code></pre> | ||
|
|
||
| To debug travelmate runtime problems, please always enable the 'trm\_debug' flag, restart travelmate and check the system log afterwards (_logread -e "trm-"_) | ||
| To debug travelmate runtime problems, please always enable the 'trm\_debug' flag, restart Travelmate and check the system log afterwards (_logread -e "trm-"_) | ||
|
|
||
| ## Support | ||
| Please join the travelmate discussion in this [forum thread](https://forum.lede-project.org/t/travelmate-support-thread/5155) or contact me by [mail](mailto:[email protected]) | ||
| Please join the Travelmate discussion in this [forum thread](https://forum.openwrt.org/t/travelmate-support-thread/5155) or contact me by [mail](mailto:[email protected]) | ||
|
|
||
| ## Removal | ||
| * stop the travelmate daemon with _/etc/init.d/travelmate stop_ | ||
| * remove the travelmate package (_opkg remove luci-app-travelmate_, _opkg remove travelmate_) | ||
| * stop the Travelmate daemon with _/etc/init.d/travelmate stop_ | ||
| * remove the Travelmate package (_opkg remove luci-app-travelmate_, _opkg remove travelmate_) | ||
|
|
||
| Have fun! | ||
| Dirk | ||