diff --git a/README.md b/README.md index 579870a..8fa7839 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -OpenWrtScripts -============== +# OpenWrtScripts -This is a set of scripts (sometimes also called "Openscripts") that report, configure and measure (and improve) latency in home routers (and everywhere else!) -These scripts work equally well for both [LEDE](https://lede-project.org) and [OpenWrt](https://openwrt.org) and include: +This is a set of scripts (sometimes also called "Openscripts") that report, +configure and measure (and improve) latency in home routers. +These scripts work for [OpenWrt](https://openwrt.org) and include: * [getstats.sh](#getstatssh) - a script to collect troubleshooting information that helps to diagnose problems in the OpenWrt distribution. @@ -15,7 +15,11 @@ These scripts work equally well for both [LEDE](https://lede-project.org) and [O OpenWrt router consistently after flashing factory firmware. * [config-spare-router.sh](#config-spare-routersh) - Configure a - "spare router" to known settings so it's easy to use in a new setting. + "spare router" to known configuration so it's easy to re-use in a new setting. + +* [print-router-label.sh](#print-router-labelsh) - + Create a printable label showing LAN address and login credentials + that can be taped on the side of the router. * [betterspeedtest.sh](#betterspeedtestsh) & [netperfrunner.sh](#netperfrunnersh) & @@ -26,12 +30,12 @@ These scripts work equally well for both [LEDE](https://lede-project.org) and [O an "idle line" without any additional traffic generation from the script. * [tunnelbroker.sh](#tunnelbrokersh) - a script to set up a - IPv6 6-in-4 tunnel to TunnelBroker.net. + IPv6 6-in-4 tunnel to TunnelBroker.net. -These scripts can be saved in the `/usr/lib/OpenWrtScripts` directory. -The easiest way to do this is to use ssh into the router and enter these commands: +These scripts can be saved in the `/usr/lib/OpenWrtScripts` directory. +The easiest way to do this is to ssh into the router and enter these commands: -``` +```bash opkg update opkg install netperf git git-http cd /usr/lib @@ -40,36 +44,43 @@ git clone https://github.com/richb-hanover/OpenWrtScripts.git ## [getstats.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/getstats.sh) -The `getstats.sh` script helps diagnose problems with OpenWrt. -If you report a problem, it is always helpful to include the output of this script. +The `getstats.sh` script helps diagnose problems with OpenWrt. +If you report a problem, it is always helpful to include the output of this script. -`getstats.sh` executes a built-in set of commands and writes the collected output to `/tmp/openwrtstats.txt`. +`getstats.sh` executes a built-in set of commands and writes the +collected output to `/tmp/openwrtstats.txt`. The script also executes commands passed as arguments on the command line. -It also displays a list of user-installed opkg packages - that is those not installed by default. -In the example below, the output would contain results from the standard set of commands plus the two additional arguments: +It also displays a list of user-installed opkg packages - +that is those not installed by default. +In the example below, the output would contain results from the +standard set of commands plus the two additional arguments: **Usage:** `sh getstats.sh "ls /usr/lib" "ls -al /etc/config"` -**To install and run this script:** The script is self-contained, and can be placed in any directory. -Read the top of the [getstats.sh](./getstats.sh) file for a simple procedure for using the script. +**To install and run this script:** The script is self-contained, +and can be placed in any directory. Read the top of the +[getstats.sh](./getstats.sh) file for a simple procedure for using the script. -**Sample output file:** See a sample output file - [openwrtstats.txt](./sample_output/openwrtstats.txt) +**Sample output file:** See a sample output file - +[openwrtstats.txt](./sample_output/openwrtstats.txt) ## [opkgscript.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/opkgscript.sh) _**NOTE:** This script is deprecated. -It still works, but when upgrading to a new OpenWrt release, a far easier option is to use the +It still works, but when upgrading to a new OpenWrt release, +a far easier option is to use the [Attended Sysupgrade](https://openwrt.org/docs/guide-user/installation/attended.sysupgrade) in recent versions of OpenWrt._ -The `opkgscript.sh` script helps to restore the current set of packages after a sysupgrade -or even a clean install of either LEDE or OpenWrt. -By default, the `write` command saves the list of installed packages in -`/etc/config/opkg.installed` (where it will be preserved across sysupgrades), and the -`install` command reads the file, to restore that set of packages. -Cloned from Malte Forkel's [original script.](https://forum.openwrt.org/viewtopic.php?pid=194478#p194478) +The `opkgscript.sh` script helps to restore the current set of packages +after a sysupgrade or even a clean install of either LEDE or OpenWrt. +By default, the `write` command saves the list of installed packages in +`/etc/config/opkg.installed` (where it will be preserved across sysupgrades), +and the `install` command reads the file, to restore that set of packages. +Cloned from Malte Forkel's +[original script.](https://forum.openwrt.org/viewtopic.php?pid=194478#p194478) -**Usage:** +**Usage:** `sh opkgscript.sh write` _use before sysupgrade to save the current set of packages_ @@ -91,88 +102,126 @@ It also prints a label that can be taped to the outside of the router so the next person "to touch it" can log in easily. When you're taking a router out of service, -reset it, then run this script. -Print the label below and tape it to the router. +install the latest OpenWrt firmware, then run this script. +Print the label (below) and tape it to the router. It'll be easy to start using it again. For more details, read [Why a "spare router"?](./Why%20a%20Spare%20Router%3F.md) -``` -================================================= - Device: D-Link DIR-878 A1 - OpenWrt: 'OpenWrt 23.05.5 r24106-10cc5fcd00' - Connect to: http://SpareRouter.local - or: ssh root@SpareRouter.local - LAN: 172.30.42.1 - User: root - Login PW: SpareRouter - WiFi SSID: SpareRouter - WiFi PW: - Configured: 2024-Sep-26 -================================================= +## [print-router-label.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/print-router-label.sh) -Power Brick Label: D-Link DIR-878 A1 +This script retrieves values from an OpenWrt router to create a +label that contains the LAN address and important credentials. +Tape this label to the side of the router so the next person +to encounter the router (which may be you) can access it. + +This process is reasonably secure - if the bad guy +can read the label, they can also factory-reset the router +(or steal TV or your silverware). Here's a sample label: + +```text +======= Printed with: print-router-label.sh ======= + Device: Linksys E8450 (UBI) + OpenWrt: OpenWrt 23.05.5 r24106-10cc5fcd00 + Connect to: http://Belkin-RT3200.local + or: ssh root@Belkin-RT3200.local + LAN: 192.168.253.1 + User: root + Login PW: abcd9876 + Wifi SSID: My Wifi SSID + Wifi PW: + Configured: 2024-Nov-28 +=== See github.com/richb-hanover/OpenWrtScripts === + +Label for Power Brick: Linksys E8450 (UBI) ``` - + ## [config-openwrt.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/config-openwrt.sh) -The `config-openwrt.sh` script updates the factory settings of OpenWrt to a known-good configuration. +The `config-openwrt.sh` script updates the factory settings of OpenWrt +to a known-good configuration. If you frequently update your firmware, you can use this script to reconfigure the router to a consistent state. You should make a copy of this script, customize it to your needs, then use the "To run this script" procedure (below). -This script is designed to configure the settings after an initial "factory" firmware flash. +This script is designed to configure the settings after an initial +"factory" firmware flash. There are sections below to configure many aspects of your router. All the sections are commented out. There are sections for: -- Set up the WAN interface to connect to your provider -- Update the software packages -- Update the root password -- Set the time zone -- Enable SNMP for traffic monitoring and measurements -- Enable mDNS/ZeroConf on the WAN interface -- Set the SQM (Smart Queue Management) parameters +* Set up the WAN interface to connect to your provider +* Update the software packages +* Update the root password +* Set the time zone +* Enable SNMP for traffic monitoring and measurements +* Enable mDNS/ZeroConf on the WAN interface +* Set the SQM (Smart Queue Management) parameters _[ Note: the remaining items have not been converted to work on OpenWrt yet ]_ -- Enable NetFlow export for traffic analysis -- Change default IP addresses and subnets for interfaces -- Change default DNS names -- Set the radio channels -- Set wireless SSID names -- Set the wireless security credentials]_ +* Enable NetFlow export for traffic analysis +* Change default IP addresses and subnets for interfaces +* Change default DNS names +* Set the radio channels +* Set wireless SSID names +* Set the wireless security credentials]_ -**To run this script** +### To run this script -Flash the router with factory firmware. Then telnet/ssh in and execute these statements. +Flash the router with factory firmware. +Then telnet/ssh in and execute these statements. You should do this over a wired connection because some of these changes may reset the wireless network. - ssh root@192.168.1.1 - cd /tmp - cat > config.sh - [paste in the contents of this file, then hit ^D] - sh config.sh - Presto! (You should reboot the router when this completes.) +```bash +ssh root@192.168.1.1 +cd /tmp +cat > config.sh +[paste in the contents of this file, then hit ^D] +sh config.sh +Presto! (You should reboot the router when this completes.) +``` -**Note:** If you use a secondary OpenWrt router, you can create another copy of this script, and use it to set different configuration parameters (perhaps different subnets, radio channels, SSIDs, enable mDNS, etc). +**Note:** If you use a secondary OpenWrt router, you can create another copy +of this script, and use it to set different configuration parameters +(perhaps different subnets, radio channels, SSIDs, enable mDNS, etc). ## [betterspeedtest.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/betterspeedtest.sh) -The `betterspeedtest.sh` script emulates the web-based test performed by speedtest.net, but does it one better. While script performs a download and an upload to a server on the Internet, it simultaneously measures latency of pings to see whether the file transfers affect the responsiveness of your network. +The `betterspeedtest.sh` script emulates the web-based test performed +by speedtest.net, but does it one better. [^1] +While script performs a download and an upload to a server on the Internet, +it simultaneously measures latency of pings to see whether the file transfers +affect the responsiveness of your network. -Here's why that's important: If the data transfers do increase the latency/lag much, then other network activity, such as voice or video chat, gaming, and general network activity will also work poorly. Gamers will see this as lagging out when someone else uses the network. Skype and FaceTime will see dropouts or freezes. Latency is bad, and good routers will not allow it to happen. +Here's why that's important: +If the data transfers do increase the latency/lag much, +then other network activity, such as voice or video chat, gaming, and +general network activity will also work poorly. +Gamers will see this as lagging out when someone else uses the network. +Skype and FaceTime will see dropouts or freezes. +Latency is bad, and good routers will not allow it to happen. + +[^1]: Since the script was created all three of the major speed test sites now +include a latency setting. +But `betterspeedtest.sh` still provides good numerical results. See: + +* [Speedtest.net](https://www.speedtest.net/) +* [Cloudflare Speed Test](https://speed.cloudflare.com/) +* [Waveform Speed Test](https://www.waveform.com/tools/bufferbloat) The betterspeedtest.sh script measures latency during file transfers. To invoke it: - sh betterspeedtest.sh -Z passphrase [ -4 | -6 ] [ -H netperf-server ] [ -t duration ] [ -p host-to-ping ] [ -i ] [ -n simultaneous-streams ] +```bash +sh betterspeedtest.sh -Z passphrase [ -4 | -6 ] [ -H netperf-server ] [ -t duration ] [ -p host-to-ping ] [ -i ] [ -n simultaneous-streams ] +``` Options, if present, are: -* -H | --host: DNS or Address of a netperf server (default - netperf.bufferbloat.net) -Alternate servers are netperf-east (east coast US), netperf-west (California), -and netperf-eu (Denmark) +* -H | --host: DNS or Address of a netperf server (default - netperf.bufferbloat.net) + Alternate servers are netperf-east (east coast US), netperf-west (California), + and netperf-eu (Denmark) * -4 | -6: Enable ipv4 or ipv6 testing (default - ipv4) * -t | --time: Duration for how long each direction's test should run - (default - 60 seconds) * -p | --ping: Host to ping to measure latency (default - gstatic.com) @@ -181,70 +230,89 @@ and netperf-eu (Denmark) * -Z passphrase: Required to use the default netperf.bufferbloat.net server. Visit the site to get today's value. -The output shows separate (one-way) download and upload speed, along with a summary of latencies, including min, max, average, median, and 10th and 90th percentiles so you can get a sense of the distribution. The tool also displays the percent packet loss. The example below shows two measurements, bad and good. +The output shows separate (one-way) download and upload speed, +along with a summary of latencies, including min, max, average, median, +and 10th and 90th percentiles so you can get a sense of the distribution. +The tool also displays the percent packet loss. +The example below shows two measurements, bad and good. -The Idle test uses the same process to measure latency of the line, but without any additional traffic from this script. It runs for the specified --time. +The Idle test uses the same process to measure latency of the line, +but without any additional traffic from this script. +It runs for the specified --time. -_Note:_ If the script displays the latency values as all-zeros on OpenWrt, -then it's likely that the device has received (and is trying to use) -an IPv6 address for the ping host. -This will fail if you don't have IPv6 service from your ISP. -To solve this, add `-p 1.1.1.1` or `-p 8.8.8.8` to the command to force an IPv4 host. +_Note:_ If the script displays all-zeros for the latency, +check these possibilities: + +* The named server may be down +* The script may have chosen an IPv6 address when it's not available. + Use the `-4` or `-6` option to force the proper address type. ### Sample Results -On the left is a test run without SQM. Note that the latency gets huge (greater than 5 seconds), meaning that network performance would be terrible for anyone else using the network. -On the right is a test using SQM: the latency goes up a little (less than 23 msec under load), and network performance remains good. +On the left is a test run without SQM. +Note that the latency gets huge (greater than 5 seconds), meaning that +network performance would be terrible for anyone else using the network. - Example with NO SQM - BAD Example using SQM - GOOD - - root@openwrt:/usr/lib/OpenWrtScripts# sh betterspeedtest.sh root@openwrt:/usr/lib/OpenWrtScripts# sh betterspeedtest.sh - [date/time] Testing against netperf.bufferbloat.net (ipv4) [date/time] Testing against netperf.bufferbloat.net (ipv4) - with 5 simultaneous sessions while pinging gstatic.com with 5 simultaneous sessions while pinging gstatic.com - (60 seconds in each direction) (60 seconds in each direction) - - Download: 6.65 Mbps Download: 6.62 Mbps - Latency: (in msec, 58 pings, 0.00% packet loss) Latency: (in msec, 61 pings, 0.00% packet loss) - Min: 43.399 Min: 43.092 - 10pct: 156.092 10pct: 43.916 - Median: 230.921 Median: 46.400 - Avg: 248.849 Avg: 46.575 - 90pct: 354.738 90pct: 48.514 - Max: 385.507 Max: 56.150 - - Upload: 0.72 Mbps Upload: 0.70 Mbps - Latency: (in msec, 59 pings, 0.00% packet loss) Latency: (in msec, 53 pings, 0.00% packet loss) - Min: 43.699 Min: 43.394 - 10pct: 352.521 10pct: 44.202 - Median: 4208.574 Median: 50.061 - Avg: 3587.534 Avg: 50.486 - 90pct: 5163.901 90pct: 56.061 - Max: 5334.262 Max: 69.333 +On the right is a test using SQM: the latency goes up a little +(less than 23 msec under load), and network performance remains good. + +```text +Example with NO SQM - BAD Example using SQM - GOOD + +root@openwrt# sh betterspeedtest.sh root@openwrt# sh betterspeedtest.sh +[date] Testing against netperf.bufferbloat.net (ipv4) [date] Testing against netperf.bufferbloat.net (ipv4) + with 5 simultaneous sessions while pinging gstatic.com with 5 simultaneous sessions while pinging gstatic.com + (60 seconds in each direction) (60 seconds in each direction) + + Download: 6.65 Mbps Download: 6.62 Mbps + Latency: (in msec, 58 pings, 0.00% packet loss) Latency: (in msec, 61 pings, 0.00% packet loss) + Min: 43.399 Min: 43.092 + 10pct: 156.092 10pct: 43.916 + Median: 230.921 Median: 46.400 + Avg: 248.849 Avg: 46.575 + 90pct: 354.738 90pct: 48.514 + Max: 385.507 Max: 56.150 + + Upload: 0.72 Mbps Upload: 0.70 Mbps + Latency: (in msec, 59 pings, 0.00% packet loss) Latency: (in msec, 53 pings, 0.00% packet loss) + Min: 43.699 Min: 43.394 + 10pct: 352.521 10pct: 44.202 + Median: 4208.574 Median: 50.061 + Avg: 3587.534 Avg: 50.486 + 90pct: 5163.901 90pct: 56.061 + Max: 5334.262 Max: 69.333 +``` ## [netperfrunner.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/netperfrunner.sh) The `netperfrunner.sh` script runs several netperf commands simultaneously. -This mimics the stress test of [netperf-wrapper](https://github.com/tohojo/netperf-wrapper) [Github] but without the nice GUI result. +This mimics the stress test of +[netperf-wrapper](https://github.com/tohojo/netperf-wrapper) +[Github] but without the nice GUI result. When you start this script, it concurrently uploads and downloads several -streams (files) to a server on the Internet. This places a heavy load -on the bottleneck link of your network (probably your connection to the Internet), -and lets you measure both the total bandwidth and the latency of the link during the transfers. +streams (files) to a server on the Internet. This places a heavy load +on the bottleneck link of your network +(probably your connection to the Internet), +and lets you measure both the total bandwidth +and the latency of the link during the transfers. To invoke the script: - sh netperfrunner.sh -Z passphrase [ -4 | -6 ] [ -H netperf-server ] [ -t duration ] [ -p host-to-ping ] [-n simultaneous-streams ] +```bash +sh netperfrunner.sh -Z passphrase [ -4 | -6 ] [ -H netperf-server ] [ -t duration ] [ -p host-to-ping ] [-n simultaneous-streams ] +``` Options, if present, are: -* -H | --host: DNS or Address of a netperf server (default - netperf.bufferbloat.net) -Alternate servers are netperf-east (East Coast US), -netperf-west (California), -netperf-eu (Denmark), or -flent-fremont (also California) - +* -H | --host: DNS or Address of a netperf server (default - netperf.bufferbloat.net) + Alternate servers are netperf-east (East Coast US), + netperf-west (California), + netperf-eu (Denmark), or + flent-fremont (also California) * -4 | -6: Enable ipv4 or ipv6 testing (default - ipv4) -* -t | --time: Duration for how long each direction's test should run - (default - 60 seconds) +* -t | --time: Duration for how long each direction's test should run - + (default - 60 seconds) * -p | --ping: Host to ping to measure latency (default - gstatic.com) * -n | --number: Number of simultaneous sessions (default - 4 sessions) * -Z passphrase: Required for netperf.bufferbloat.net @@ -252,26 +320,33 @@ flent-fremont (also California) The output of the script looks like this: - root@openwrt:/usr/lib/OpenWrtScripts# sh netperfrunner.sh - [date/time] Testing netperf.bufferbloat.net (ipv4) with 4 streams down and up - while pinging gstatic.com. Takes about 60 seconds. - Download: 5.02 Mbps - Upload: 0.41 Mbps - Latency: (in msec, 61 pings, 15.00% packet loss) - Min: 44.494 - 10pct: 44.494 - Median: 66.438 - Avg: 68.559 - 90pct: 79.049 - Max: 140.421 +```bash +root@openwrt:/usr/lib/OpenWrtScripts# sh netperfrunner.sh +[date/time] Testing netperf.bufferbloat.net (ipv4) with 4 streams down and up + while pinging gstatic.com. Takes about 60 seconds. +Download: 5.02 Mbps + Upload: 0.41 Mbps + Latency: (in msec, 61 pings, 15.00% packet loss) + Min: 44.494 + 10pct: 44.494 + Median: 66.438 + Avg: 68.559 + 90pct: 79.049 + Max: 140.421 +``` -**Note:** The download and upload speeds reported may be considerably lower than your line's rated speed. This is not a bug, nor is it a problem with your internet connection. That's because the acknowledge messages sent back to the sender consume a significant fraction of the link's capacity (as much as 25%). +**Note:** The download and upload speeds reported may be considerably lower +than your line's rated speed. +This is not a bug, nor is it a problem with your internet connection. +That's because the acknowledge messages sent back to the sender consume +a significant fraction of the link's capacity (as much as 25%). ## [networkhammer.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/networkhammer.sh) +The `networkhammer.sh` script continually invokes the netperfrunner script to +provide a heavy load. +It runs forever - Ctl-C will interrupt it. -The `networkhammer.sh` script continually invokes the netperfrunner script to provide a heavy load. It runs forever - Ctl-C will interrupt it. - ## [idlelatency.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/idlelatency.sh) _This script is no longer maintained. @@ -279,34 +354,44 @@ Use the `--idle` option of the `betterspeedtest.sh` script._ ## [tunnelbroker.sh](https://github.com/richb-hanover/OpenWrtScripts/blob/master/tunnelbroker.sh) -The `tunnelbroker.sh` script configures OpenWrt to create an IPv6 tunnel via Hurricane Electric. -It's an easy way to become familiar with IPv6 if your ISP doesn't offer native IPv6 capabilities. +The `tunnelbroker.sh` script configures OpenWrt to create +an IPv6 tunnel via Hurricane Electric. +It's an easy way to become familiar with IPv6 if your ISP +doesn't offer native IPv6 capabilities. There are several steps: -1. Go to the Hurricane Electric [TunnelBroker.net](http://www.tunnelbroker.net/) site to set up your free account. -There are detailed instructions for setting up an account and an IPv6 tunnel in the script itself, or at the -[IPv6 Tunnel page](http://www.bufferbloat.net/projects/cerowrt/wiki/IPv6_Tunnel) of [bufferbloat.net](bufferbloat.net) +1. Go to the Hurricane Electric + [TunnelBroker.net](http://www.tunnelbroker.net/) site to set up your free account. + There are detailed instructions for setting up an account and an IPv6 tunnel + in the script itself, or at the + [IPv6 Tunnel page](http://www.bufferbloat.net/projects/cerowrt/wiki/IPv6_Tunnel) + of [bufferbloat.net](bufferbloat.net) 2. From the tunnelbroker main page, click "Create Regular Tunnel" - * Enter your IP address in "IPv4 Endpoint" (paste in the address you're "viewing from") - * Select a nearby Tunnel Server - * Click "Create Tunnel" - -3. On the resulting Tunnel Details page, click **Assign /48** to get a /48 prefix -4. From the Tunnel Details page, copy and paste the matching values into the `tunnel.sh` file. -The *User\_Name* is the name you used to create the account. -Find the *Update\_Key* on the Advanced Tab of the Tunnel Details page. + * Enter your IP address in "IPv4 Endpoint" + (paste in the address you're "viewing from") + * Select a nearby Tunnel Server + * Click "Create Tunnel" + +3. On the resulting Tunnel Details page, click **Assign /48** to get + a /48 prefix +4. From the Tunnel Details page, copy and paste the matching values + into the `tunnel.sh` file. + The _User\_Name_ is the name you used to create the account. + Find the _Update\_Key_ on the Advanced Tab of the Tunnel Details page. 5. ssh into the router and execute this script with these steps. - - ssh root@192.168.1.1 # use the address of your router - cd /tmp - cat > tunnel.sh - [paste in the contents of this file, then hit ^D] - [edit the script to match your tunnelbroker values] - sh tunnel.sh - [Restart your router. This seems to make a difference.] - -Presto! Your tunnel is up! -Your computer should get a global IPv6 address, and should be able to communicate directly with IPv6 devices on the Internet. -To test it, try: `ping6 ivp6.google.com` +```bash +ssh root@192.168.1.1 # use the address of your router +cd /tmp +cat > tunnel.sh +[paste in the contents of this file, then hit ^D] +[edit the script to match your tunnelbroker values] +sh tunnel.sh +[Restart your router. This seems to make a difference.] +``` + +Presto! Your tunnel is up! +Your computer should get a global IPv6 address, and should be able to +communicate directly with IPv6 devices on the Internet. +To test it, try: `ping6 ivp6.google.com` diff --git a/Why a Spare Router?.md b/Why a Spare Router?.md index d20668f..2c77c12 100644 --- a/Why a Spare Router?.md +++ b/Why a Spare Router?.md @@ -2,7 +2,8 @@ Many people who use OpenWrt wind up with unused routers when they retire one for a newer device. -These are perfectly functioning devices that are perhaps older or missing a certain function. +These are perfectly functioning devices that are perhaps older +or missing a certain function. They could be easily re-used and passed along to friends, family or neighbors. BUT... you have to solve a couple problems: @@ -11,7 +12,7 @@ BUT... you have to solve a couple problems: passwords, certificates, idiosyncratic packages. etc. 2. You can't remember how it was configured, so you can't even connect to it. - + **The remedy:** A "spare router" configuration script that you can use when you take a router out of service. It leaves the router with current OpenWrt firmware @@ -36,32 +37,31 @@ To use it: * SSH into the router using the Ethernet connection * Run the attached script (see the instructions within it) * The script prints a label: cut it out and tape it to the router -* _Pro tip:_ Snip the model number from the paper +* _Pro tip:_ Snip the model number from the paper and tape it directly to the power brick. (Use the text from the "Power Brick Label" section.) -* _Pro tip:_ Place the router and its power brick in a ziploc bag +* _Pro tip:_ Place the router and its power brick in a Ziploc bag to keep them together. The `config-spare-router.sh` script may be run multiple times without bad effect. -When the script completes, it displays configuration like this, +When the script completes, it displays configuration similar to this, suitable for printing and taping to the router. -``` -================================================= - Device: D-Link DIR-878 A1 - OpenWrt: 'OpenWrt 23.05.5 r24106-10cc5fcd00' - Connect to: http://SpareRouter.local - or: ssh root@SpareRouter.local - LAN: 172.30.42.1 - User: root - Login PW: SpareRouter - WiFi SSID: SpareRouter - WiFi PW: - Configured: 2024-Sep-26 -================================================= - -Power Brick Label: D-Link DIR-878 A1 - +```text +# ======= Printed with: print-router-label.sh ======= +# Device: Linksys E8450 (UBI) +# OpenWrt: OpenWrt 23.05.5 r24106-10cc5fcd00 +# Connect to: http://SpareRouter.local +# or: ssh root@SpareRouter.local +# LAN: 172.30.42.1 +# User: root +# Login PW: SpareRouter +# Wifi SSID: SpareRouter +# Wifi PW: +# Configured: 2024-Nov-28 +# === See github.com/richb-hanover/OpenWrtScripts === +# +# Label for Power Brick: Linksys E8450 (UBI) ``` ## When you (re)deploy the router @@ -70,15 +70,18 @@ The default settings are (intentionally) insecure. Remember to change the following: * Root password (**System -> Administration**) -* Wifi credentials (**Network -> Wireless**) -* Enable other Wifi radios (**Network -> Wireless**) -* Change the LAN interace IP address and other settings as needed (**Network -> Interfaces**) +* Wifi credentials (**Network -> Wireless**) +* Enable other Wifi radios (**Network -> Wireless**) +* Change the LAN interface IP address and other settings as needed (**Network -> Interfaces**) * (Optional) Configure SQM (**Network -> SQM QoS**) * (Optional) Change the hostname (**System -> System**) * (Optional) Install other packages as needed * (Optional) Travelmate (**Services -> Travelmate**) Click the **Interface Wizard** button one time - +* (Optional) Re-run the `print-router-label.sh` to create + a new label and tape it to the router, so you don't + have to fuss the next time you work on it. + ## Rationale for the configuration choices This script was designed for ease of use. @@ -90,7 +93,7 @@ was not a consideration. the `root` password is set to `SpareRouter`. There is no need for strong security here, as you will be changing the password when you set it up in its new location. -* **LAN Address:** The LAN IP address is set to `172.30.42.1`. +* **LAN Address:** The LAN IP address is set to `172.30.42.1`. This is a [valid private IP address range](https://en.wikipedia.org/wiki/Private_network) (like `10...` and `192.168...` subnets) but it is less commonly used. @@ -108,22 +111,22 @@ was not a consideration. because you will be changing it immediately. * **Time Zone:** As a convenience, the time zone is set to `Americas/New York`. You can use the LuCI GUI to re-configure as needed. -* **Software packages:** The script installs a minimal set of useful +* **Software packages:** The script installs a minimal set of useful packages that are required to bootstrap a new router. - * **luci** Released versions of OpenWrt already install `luci`, - re-installing does no harm. - * **umdns** To allow the router to advertise its name as "SpareRouter" - (e.g., connect using `ssh root@sparerouter`) - * **luci-app-sqm** All OpenWrt routers should have the SQM package installed - to minimize bufferbloat - * **travelmate** _and_ - * **luci-app-travelmate** This package allows a router to + * **luci** Released versions of OpenWrt already install `luci`. + Re-installing does no harm. + * **umdns** Allows the router to advertise its name as "SpareRouter" + (e.g., connect using `ssh root@sparerouter.local`) + * **luci-app-sqm** All OpenWrt routers ought to have the SQM package + installed to minimize bufferbloat. Just do it. + * **travelmate** _and_ + * **luci-app-travelmate** This packages allow a router to act as a Wifi repeater by making a wireless "uplink" to an existing network Even if there's no Ethernet connection for the spare routers's WAN port, - the wireless uplink lets you download additional packages. - + you can use the wireless uplink to download additional packages. + ## Modifications This script provides a stable platform for re-deploying old routers. diff --git a/config-spare-router.sh b/config-spare-router.sh index 8e72cf6..fd9144e 100644 --- a/config-spare-router.sh +++ b/config-spare-router.sh @@ -1,47 +1,126 @@ #!/bin/sh -# Conigure a "spare router" in a known-good state. +# Configure a "spare router" to a known-good state. # This script configures the factory default settings of OpenWrt # to make it easy to swap it in when a new router is needed. -# It also displays important configuration information when complete. -# You can print out those lines and tape them to the router so -# the next person will know how to access the router in the future. -# The format is: +# It also creates a label showing the configuration and credentials. +# You can print the label and tape it to the router so +# the next person will know how to access the router. +# The label format is: # -# Configured: YYYY-MMM-DD -# Device: Belkin RT3200 -# OpenWrt: 22.03.5 r20134-5f15225c1e -# LAN: 192.168.253.1 -# User: root -# Login PW: SpareRouter -# WiFi SSID: SpareRouter -# WiFi PW: none +# ======= Printed with: print-router-label.sh ======= +# Device: Linksys E8450 (UBI) +# OpenWrt: OpenWrt 23.05.5 r24106-10cc5fcd00 +# Connect to: http://Belkin-RT3200.local +# or: ssh root@Belkin-RT3200.local +# LAN: 192.168.253.1 +# User: root +# Login PW: root-password +# Wifi SSID: My Wifi SSID +# Wifi PW: abcd9876 +# Configured: 2024-Nov-28 +# === See github.com/richb-hanover/OpenWrtScripts === +# +# Label for Power Brick: Linksys E8450 (UBI) -# The default settings of the script are generic, but the router will work. +# ***** To run this script ***** +# +# 1. Connect your laptop on a wired LAN port (Ethernet): +# some of these changes can reset the wireless network. +# 2. Connect the router's WAN port to the internet: this +# script needs to install certain packages. (Perhaps +# plug its WAN port into your new router's LAN port +# while running this script.) +# 3. Flash the router with factory firmware. +# Do NOT keep the settings. +# 4. SSH in and execute the statements below. +# +# ssh root@192.168.1.1 # the default OpenWrt LAN address +# cd /tmp +# cat > config.sh +# [paste in the entire contents of this file, then hit ^D] +# sh config.sh +# Presto! (The router reboots when the script completes.) +# +# The script sets generic settings and credentials. # You could make a copy of this script, customize it to your needs, # then use the "To run this script" procedure (below). # -# ***** To run this script ***** -# -# Flash the router with factory firmware. Then SSH in and execute these statements. -# You should do this over a wired connection because some of these changes -# can reset the wireless network. -# -# ssh root@192.168.1.1 -# cd /tmp -# cat > config.sh -# [paste in the contents of this file, then hit ^D] -# sh config.sh -# Presto! (You should reboot the router when this completes.) + +# === print_router_label() === +# This function is copy/pasted from "print-router-label.sh" +# to keep the "config-spare-router.sh" script a single file. +# Maintenance hassle: Changes to the printing must be updated +# in both places +print_router_label() { + local ROOTPASSWD="${1:-"?"}" + TODAY=$(date +"%Y-%b-%d") + DEVICE=$(cat /tmp/sysinfo/model) + OPENWRTVERSION=$(grep "DISTRIB_DESCRIPTION" /etc/openwrt_release | cut -d"=" -f2 | tr -d '"' | tr -d "'") + HOSTNAME=$(uci get system.@system[0].hostname) + LANIPADDRESS=$(uci get network.lan.ipaddr) + + # Create temporary file for both SSID and password + TMPFILE=$(mktemp /tmp/wifi_creds.XXXXXX) + + # Get wifi credentials + uci show wireless |\ + egrep =wifi-iface$ |\ + cut -d= -f1 |\ + while read s; + do uci -q get $s.disabled |\ + grep -q 1 && continue; + id=$(uci -q get $s.ssid); + key=$(uci -q get $s.key); + # Write both SSID and password to temporary file + echo "$id:$key" > "$TMPFILE" + break + done + + # Read both values from temporary file + if [ -f "$TMPFILE" ]; then + WIFISSID=$(cut -d: -f1 "$TMPFILE") + WIFIPASSWD=$(cut -d: -f2 "$TMPFILE") + # Check if password is empty and replace with "" + if [ -z "$WIFIPASSWD" ]; then + WIFIPASSWD="" + fi + else + WIFISSID="unknown" + WIFIPASSWD="unknown" + fi + + # Clean up temporary file + rm -f "$TMPFILE" + + echo "" + echo "Print the following label and tape it to the router..." + echo "" + echo "======= Printed with: print-router-label.sh =======" + echo " Device: $DEVICE" + echo " OpenWrt: $OPENWRTVERSION" + echo " Connect to: http://$HOSTNAME.local" + echo " or: ssh root@$HOSTNAME.local" + echo " LAN: $LANIPADDRESS" + echo " User: root" + echo " Login PW: $ROOTPASSWD" + echo " Wifi SSID: $WIFISSID" + echo " Wifi PW: $WIFIPASSWD" + echo " Configured: $TODAY" + echo "=== See github.com/richb-hanover/OpenWrtScripts ===" + echo "" + echo "Label for Power Brick: $DEVICE" + echo "" +} # === CONFIGURATION PARAMETERS === -# Set the variables in this section to be used for configuration +# Set the variables to be used for configuration HOSTNAME="SpareRouter" -NEWPASSWD="SpareRouter" -TIMEZONE='EST5EDT,M3.2.0,M11.1.0' # see link to other time zones below +ROOTPASSWD="SpareRouter" +TIMEZONE='EST5EDT,M3.2.0,M11.1.0' # see link below for other time zones ZONENAME='America/New York' -LANIPADDRESS="172.30.42.1" +LANIPADDRESS="172.30.42.1" # 172.30.42.1 minimizes chance of conflict LANSUBNET="255.255.255.0" SNMP_COMMUNITYSTRING=public WIFISSID="SpareRouter" @@ -53,15 +132,15 @@ ENCRMODE='none' # echo '*** Updating root password' passwd <" +# +# Here's a sample label created from the Usage above: -# === Printed with: print-router-label.sh ============ +# ======= Printed with: print-router-label.sh ======= # Device: Linksys E8450 (UBI) -# OpenWrt: 'OpenWrt 23.05.5 r24106-10cc5fcd00' +# OpenWrt: OpenWrt 23.05.5 r24106-10cc5fcd00 # Connect to: http://Belkin-RT3200.local # or: ssh root@Belkin-RT3200.local # LAN: 192.168.253.1 # User: root -# Login PW: abcdef -# Wifi SSID: OpenWrt -# Wifi PW: -open- -# Configured: 2024-Nov-27 -# === See: github.com/richb-hanover/OpenWrtScripts === +# Login PW: root-password +# Wifi SSID: My Wifi SSID +# Wifi PW: +# Configured: 2024-Nov-28 +# === See github.com/richb-hanover/OpenWrtScripts === # # Label for Power Brick: Linksys E8450 (UBI) - -# Usage: sh print-router-label.sh root-password WifiSSID WifiPassword +# print_router_label() { + local ROOTPASSWD="${1:-"?"}" + TODAY=$(date +"%Y-%b-%d") + DEVICE=$(cat /tmp/sysinfo/model) + OPENWRTVERSION=$(grep "DISTRIB_DESCRIPTION" /etc/openwrt_release | cut -d"=" -f2 | tr -d '"' | tr -d "'") + HOSTNAME=$(uci get system.@system[0].hostname) + LANIPADDRESS=$(uci get network.lan.ipaddr) -local ROOTPASSWD="${1:-"?"}" -local WIFISSID="${2:-"?"}" -local WIFIPASSWD="${3:-"?"}" + # Create temporary file for both SSID and password + TMPFILE=$(mktemp /tmp/wifi_creds.XXXXXX) -TODAY=$(date +"%Y-%b-%d") -DEVICE=$(cat /tmp/sysinfo/model) -OPENWRTVERSION=$(grep "DISTRIB_DESCRIPTION" /etc/openwrt_release | cut -d"=" -f2 | tr -d '"') -HOSTNAME=$(uci get system.@system[0].hostname) -LANIPADDRESS=$(uci get network.lan.ipaddr) + # Get wifi credentials + uci show wireless |\ + egrep =wifi-iface$ |\ + cut -d= -f1 |\ + while read s; + do uci -q get $s.disabled |\ + grep -q 1 && continue; + id=$(uci -q get $s.ssid); + key=$(uci -q get $s.key); + # Write both SSID and password to temporary file + echo "$id:$key" > "$TMPFILE" + break + done -echo "" -echo "Print the following label and tape it to the router..." -echo "" -echo "=== Printed with: print-router-label.sh ============" -echo " Device: $DEVICE" -echo " OpenWrt: $OPENWRTVERSION" -echo " Connect to: http://$HOSTNAME.local" -echo " or: ssh root@$HOSTNAME.local" -echo " LAN: $LANIPADDRESS" -echo " User: root" -echo " Login PW: $ROOTPASSWD" -echo " Wifi SSID: $WIFISSID" -echo " Wifi PW: $WIFIPASSWD" -echo " Configured: $TODAY" -echo "=== See: github.com/richb-hanover/OpenWrtScripts ===" -echo "" -echo "Label for Power Brick: $DEVICE" -echo "" + # Read both values from temporary file + if [ -f "$TMPFILE" ]; then + WIFISSID=$(cut -d: -f1 "$TMPFILE") + WIFIPASSWD=$(cut -d: -f2 "$TMPFILE") + # Check if password is empty and replace with "" + if [ -z "$WIFIPASSWD" ]; then + WIFIPASSWD="" + fi + else + WIFISSID="unknown" + WIFIPASSWD="unknown" + fi + + # Clean up temporary file + rm -f "$TMPFILE" + + echo "" + echo "Print the following label and tape it to the router..." + echo "" + echo "======= Printed with: print-router-label.sh =======" + echo " Device: $DEVICE" + echo " OpenWrt: $OPENWRTVERSION" + echo " Connect to: http://$HOSTNAME.local" + echo " or: ssh root@$HOSTNAME.local" + echo " LAN: $LANIPADDRESS" + echo " User: root" + echo " Login PW: $ROOTPASSWD" + echo " Wifi SSID: $WIFISSID" + echo " Wifi PW: $WIFIPASSWD" + echo " Configured: $TODAY" + echo "=== See github.com/richb-hanover/OpenWrtScripts ===" + echo "" + echo "Label for Power Brick: $DEVICE" + echo "" } -print_router_label "$1" "$2" "$3" +print_router_label "$1"