Updating Standard LEDE Installation/Quick Start page

Talk about Documentation
1

As preparation for the branch of the first stable release and to respond to TP-Link Archer C7 inaccessible after installation/configurating LEDE, I looked at the Quick Start page. I fixed a few typos, but wanted to mention a couple things:

  • I added a note at the top to say that at the end of these steps, you'd have a functioning router. (Previous page didn't say explicitly what the result would be.)

  • I factored out the discussion of router vs access point to a separate page. I believe most people who read this procedure want to set up a router. Those who want an alternative can set up the router first, then change to an access point.

  • In step 2, it says "On Routers: ... connect via dhcp; On Other Devices: ..." I don't understand the second choice (even though it appears that I wrote the original draft...) Does the second choice for "other devices" even make sense?

Thanks.

2

@richb-hanover About your interrogation in "step 2", maybe you wanted to offer a more general approach for devices, like the Arduino Yún, that are not "routers" but IoT facilitator.

3

@DjiPi - Step 2 talks about connecting your computer to the newly-flashed device by Ethernet (so you can ssh in to continue configuration).

What should that step tell people to do if they're working with, say, an Arduino instead of a router? Will LEDE provide a DHCP server on the Ethernet? Will the device always have an address of 192.168.1.1? Thanks.

4

@richb-hanover - Could it just point the user back to the LEDE ToH with a mention to check for a detailed approach about first connection if the router approach doesn't work, since there might be particularities with the device ?

Something like:

On other devices: The newly-flashed device will acquire an address using DHCP. Check your existing router’s web-interface to learn which address it got. Have a look at the Device Page of the Table of Hardware for particularities about your device to get it connected before going any further.

However this could also apply to router devices in fact... There could be a simplification by removing this "other devices" step and merging with the first one:

Connect your computer to a Local Area Network (LAN) port of the device using DHCP. Have a look at the Device Page of the Table of Hardware for particularities about your device to get it connected before going any further, especially for devices that are not routers.

Even more, this "Device" not being a router, could be on DHCP client only and had to be connected to a router to get working properly. Since we don't know that for sure, asking the user to connect that device to an existing network could wreak havoc if it is configured as a DHCP server by default...

I do not personally own an Arduino, I was just pointing out something that might have triggered this particular step you wrote.

Regards

5

I'm not a developer - I was just wondering if you guys could include steps(maybe alt. steps too) about how to handle or deal with opkg returning errors. I have gotten advice to add option ipv6 0 somewhere in the /etc/init.d/network(i think). Anyway, I still had the same thing happen.
Also gave the imagebuilder a try and it returned with cannot install.. unmet dependencies.. even when adding them in to include/target.mk.
You guys are really smart - me, i just like to tinker and explore. Any way to have a really dumbed down page or something?

6

Its actually hard to troubleshoot every problem without being there to test it. I find it easier to searching a portion of the error message in google and figuring it out that way. Its likely that the question has already been solved each with different methods (thats what I saw with your wget method - one person solution might not work for you so you would have to test each one out and share your experience)
After a solution is found, possibly add it to the wiki sort of like an FAQ

EDIT: Addition to the Quick Start page:: I feel that its REALLY important to note the recommended software (ie. putty, winscp, etc)

Just from personally experience when starting out, the first question I asked myself was, "How do I SSH" "What program do I use?" (I'm sure a great portion are windows users - well we can take a survey)

EDIT: jk, no need for a survey, the percentage of Windows Users is found on the stats page

EDIT2: I see part where it says "Configure your computer to get a the DHCP address" If I remembered correctly I had to do quite a bit of research (reading/youtube) just to learn how to set a static address on windows (still dont know how on linux) but to note, I haven't been setting the address as of late since the router does a good job of assigning the address to my PC, just for some thought though

1 Like
7

I think we need to separate the Web GUI steps from the Command Line steps in the Standard Flashing Instructions page. Those procedures appeal to different readers, and have very different levels of difficulty.

The Standard Flashing Instructions page now sends readers who don't have a web interface to the Installing LEDE from the Command Line page.

@bobafetthotmail Would you check the Installing LEDE from the Command Line page, and:

  1. Remove all the "LuCI method" steps
  2. Be sure that all those "web steps" are accounted for in the Standard Flashing Instructions

Thanks.

1 Like
8

Rich, I think these pages are looking real good. I do have some comments.

Regarding the prerequisites, on the QSG page, the link from the second bullet "Your router has a LAN and WAN Ethernet port" does not really tell one how to configure a single port device, but more how one can reconfigure it after flashing. I also do not think that for "Release" product that there is an installation problem on these devices. Under Snapshot one needs to configure the WWAN via UCI to get to the internet. With Release product one can connect to a WISP\Hotspot with a Scan in Luci. These instructions should work up to step 5 below, which can not be performed as there is no WAN Ethernet. Steps 6 & 7 also need some tweaking, mostly to connect to the WISP\Hotspot, but the router vs access point page does not cover it.

It might be easiest to add a bullet to step 5 such as: "For single port devices continue here" and open a new page (single port device configuration). I can word smith this when I install RC1 on my HooToo TM-02, hopefully this weekend.

I would also like to suggest these minor text changes to the "Flashing Instructions" page:

Preliminary steps for Everyone, item 2, bullet #2:
If your device is running LEDE (or OpenWrt) with Luci, use ...

Preliminary steps for Everyone, item 3:
If your device does not have a web interface, follow the instructions...

I think this reads better.

9

Maybe it's intuitive, but at some point in the instructions should we be telling the user to remove their old router and connect directly to their Modem?

10

Thanks!

Yes, I used that link more as a placeholder for the option when a router doesn't have a WAN and LAN port. I would welcome a more detailed article to link to.

[quote] I also do not think that for "Release" product that there is an installation problem on these devices. Under Snapshot one needs to configure the WWAN via UCI to get to the internet. With Release product one can connect to a WISP\Hotspot with a Scan in Luci. These instructions should work up to step 5 below, which can not be performed as there is no WAN Ethernet. Steps 6 & 7 also need some tweaking, mostly to connect to the WISP\Hotspot, but the router vs access point page does not cover it.

It might be easiest to add a bullet to step 5 such as: "For single port devices continue here" and open a new page (single port device configuration). I can word smith this when I install RC1 on my HooToo TM-02, hopefully this weekend.
[/quote]
I don't quite understand how these things work, so cannot comment on how they might be included.

I chose to exclude single-port devices because it creates a special case in the description that could be confusing to people who "just want to flash their router." Rather than spend time tweaking this wording, perhaps your word-smithed page could be the proper destination for the link for point 2 (device that doesn't have WAN and LAN port).

Done.

Good point. I added it as an Optional Step - see how it reads... Thanks again.

11

I only skimmed the quick start guide and attempted to follow through the steps mentally. I am assuming that that the guide directs the user to a stable release with LuCI package included? I noticed some instructions noted to use the web interface.

Given a scenario where the user follow the guide and is unable to access the web interface, are there links from the QSG to guide them to install LuCI?

Theoretical path I'm taking:

  1. Start here: QSG > directed to flashed LEDE
  2. Now I'm here: https://lede-project.org/docs/guide-quick-start/standardflashinginstructions
  3. "Oh no, no web GUI" (If the LuCI web interface is not installed, use the Installing LEDE from Command Line)> Directed to https://lede-project.org/docs/user-guide/ssh-firmware-upgrade
  4. Stuck here: No info on installing LuCI GUI

Well that was my experience, maybe I missed something, Just walking through it was if I was new to the website attempting to find missing pieces. Maybe I missed something :open_mouth:

12

Yes. The QSG and Standard Flashing Instructions are both geared to help (what I believe to be) the majority of LEDE users - people who "just want to install a LEDE Release build" on an adequate (8/64 MByte) router.

I leave for other pages the task of describing development installs; command-line "no web GUI" installs; low-memory package selection; peculiar hardware (no WAN port, etc). Note: those peculiar devices should have the installation process described on the Device Page: although those pages don't exist at this time, a team of us is working to create them soon.

If you follow the constraint of installing a Release build, I don't think people will get to your step #3 above. (The person would be caught by step #3 on the Flashing Instructions, sending them to the "installing via command-line" page.) There's also a separate page for installing a Development build, that does recommend installing LuCI.

The Installing LEDE from Command Line page does need further editing.

My focus in the near term is to have a bullet-proof process for this most common use case. Please continue to read these pages closely. Thanks.

13

It's probably worth understanding exactly what device and firmware file you were trying to install.

If you follow the QSG you are directed to the ToH to find your routers device page, and then link to the file for install. Lets make sure you got the right file.

If you have a small flash device we should also understand this as maybe Luci did not fit into the image.

Did you SSH to the device and check for Luci?

14

@richb-hanover Ok, merged articles as requested.

https://lede-project.org/docs/guide-quick-start/standardflashinginstructions It was mostly an affair of adding the instructions for checking SHA256sums of the downloaded files.

In quickstart here https://lede-project.org/docs/guide-quick-start/start I also restored and added Luci instructions for basic networking configuration, because what you wrote is either not applicable on many devices (those without WAN port) or inefficient (double NAT is bad) and also usually wrong (in most cases both LAN and WAN will be on same subnet -> internet not working) for those that have WAN port.

I'm sorry if it makes the guide longer and is of course more complex but networking setup can't be hand-waved like you did. Decent networking setup information MUST be in a quick-start guide about devices that will live on a network most of their time, as it's not something most newbie users will know already.

I also removed references to QoS setup from quickstart as that's not required for basic networking functionality, and is usually more involved to set it up properly (it requires making tests to actually tune it on your actual uplink/downlink speed which varies depending on user). You can add links to other wiki articles in Optional Next Steps, but setting up QoS isn't as easy as in the steps I removed.

EDIT: btw, I tested the settings in my LEDE virtualbox VM. https://lede-project.org/docs/user-guide/virtualbox-vm

15

Hmm, it seems we send people to this page to find their firmwares, and this page does not list the appropriate sha256sums file for the device so they cannot check if the file was downloaded correctly (and uploaded correctly in the device before flashing) https://lede-project.org/toh/views/toh_fwdownload

It is usually in the same page of the firmware download, so for this file https://downloads.lede-project.org/releases/17.01.0-rc1/targets/au1000/au1500/lede-17.01.0-rc1-r3042-ec095b5-au1000-au1500-squashfs-sysupgrade.bin
the sha256sums file is here
https://downloads.lede-project.org/releases/17.01.0-rc1/targets/au1000/au1500/sha256sums

Might be cool to have the sha256 in the table directly, but it has to be kept updated.

16

[quote="bobafetthotmail, post:15, topic:966"]
Might be cool to have the sha256 in the table directly, but it has to be kept updated.
[/quote]Will be rather impossible to keep it updated. as phase1 builds can be done several times per day by the buildbot. rc1 or release builds should naturally be more stable and need less updating, but it would still be a huge task to parse the correct checksums for each file to the table.Better to have a just link to the sha256sums file, if something is needed.

17

@bobafetthotmail It see your changes to the Quick Start Guide/Standard Flashing Instructions. My initial impression is that the new pages attempt to address too many possibilities, leaving them unsuitable for most everyone.

It seems that we have different opinions about what those pages should show. In your mind, who is the audience for the Quick Start Guide? Thanks.

Rich

18

Imho the most common usecase for true newbies (i.e. the reason for which we have the Quick Start in the first place) is what I call "Client" device in there. That is, you take a device, flash lede and then connect it to an existing network generated with by other devices (99% a modem-router given by ISP), that seems more or less what you had in mind too with your instructions.

That is the reason I did put much effort in getting that right.

The Router and Gateway device setups are for a bit more advanced users and will require reading some LEDE documentation anyway as in most cases they will be user-specific setups, these can be safely linked to outside page/tutorials as they are not the main meal for true newbies.
So I was more vague and linked what little we have atm for documentation about them.
We currently have no pages to document either properly but I think we can't assume all people want a "Client" device (same as we can't assume everyone reading that guide will have a device with a WAN port). So I think we still need to have at least a line for each of them in Quick Start linking to a page detailing some basic procedure (currently not really there).

About the Standard flashing... I just added parts to check SHA256sums and clarified something else minor.

It might be worth it to split the download-and-check-sha256sums in its own article though.

19

I absolutely agree. If the QSG provides this info, and no more, the outcome will be a functioning LEDE router, connected to the world. It has these benefits:

  • You prove to yourself that you can get LEDE installed on your router (it's not too scary)
  • You can browse the LEDE/LuCI interface, to see how it works, what it offers
  • You can read stuff "on the internet" via the LEDE router, so you can tell it's working
  • You're in a good position to make the LEDE router your primary router simply by swapping it with your current router.

The most important outcome is that you have had success. This inspires further confidence that "LEDE will work for me", and is worth investigating further.

That's why I have been so focussed on cutting the procedure down to its basics for people who want to:

  • Install a Release build
  • ... on a router (with LAN and WAN Ethernet port)
  • ... with 8/64 MBytes
  • ... and a web GUI

If someone has a device that doesn't meet those requirement, we definitely need to supply a link to a page that provides a thorough description for that alternative (Got a 4/32MByte device? Here's how to use it...; want to use the CLI? Here's how you use it...; etc.) This also applies to the "router" and "gateway" setups you mention - we may have more pages to write.

But I think the QSG must assume a straightforward "router" (or "client", in your terminology) device, so that we provide a simple procedure for this extremely common use-case.

That's why I think it would be better to start with the revision from ~3 Feb 2017 (say, https://lede-project.org/docs/guide-quick-start/start?rev=1486145562) as a basis for the QSG. Thanks for listening.

20

I really do not think you two are in alignment on terminology (client and router).

I think there is a problem in the original version cited by Rich. The user is left with a router behind a router, and the instructions to move the physical device are located in the "Optional Next Steps". This is a potentially bad configuration as it is very probable that the LEDE device is in the same subnet as the primary router (see more below). Alberto is interpreting this to be a "client", and the config instructions he offers are basically a wired "Dumb AP'.

I do not believe that most new users are looking to set up a Dumb AP (or bridge) out of the box, but as we collect no data on devices or usage from the community, it's a guess. In the absence of the same i think the QSG should focus on the absolute minimum needed to get a user on the current Release version of firmware and guarantee it works. The device is delivered as a Router, so that seems to be the most basic approach.

The DD-WRT approach has the user:
1 - Download firmware to a "Client PC"
2 - Go "Offline" - Connect the PC directly to the device to be flashed, flash the device, gain access and set basic info like password, LAN IP, and time zone and basic wireless.
3 - Shut down PC and router, reconfigure the user hardware environment (remove and replace old router) and connect to the internet.

Between the shut down and reconfigure we should avoid the router behind the router and IP issue. While not ideal, double nat will work and connect in most cases if there is no IP subnet conflict between devices. Unfortunately there are about 1/2 dozen major brands at 192.168.1.1. I have advocated elsewhere we change the default LEDE address, however the 3rd item above should avoid the issue, and not require the user to set fixed IPs (As DD-WRT has suggested in the past).

The prerequisites can indicate that the "Router" is the expected outcome, however we can also link there and as a note after item 2 above to instructions (some other item number in our instructions) for device configuration behind the primary router (Wired AP and bridge variations).

Related, I would like to clarify that single port devices are, by default in LEDE, configured as a "router". All the LAN side stuff is the same. The only real difference is there is no WAN physical or logical connection delivered by default. What ever flashing instructions for these devices should work up until the point we connect the device to the internet (3 above). At that point there can be a "Single port" bullet item with a link directing the user to another page for configuring the WISP\STation\Hotspot connection. (I have test Rich's instructions twice for this now).

It may be less confusing to combine the QSG and standard flashing instructions into a single page. I realize the benefits of the modular approach, but not seeing that the module is accessed elsewhere. That said, the "Standard Flashing Instructions" should be the same for a user moving from factory or LEDE to a version of Trunk, but require different subsequent handing (SSH, install Luci, etc). While we do strongly discourage this use, it may be the only approach for a user to get their NEW device operating on LEDE, at least until the next Release version. (warrants more discussion)

I agree that Rich's link is a better starting point. I also agree that SQM, while a great tool, is not a minimum requirement and can be moved to "Optional Next Steps". I do not think we need any UCI instructions and agree that checksum is important, but can be linked to a separate page (and be made modular for other instruction sets) to make the QSG more "Quick", at least visually.

Regarding terminology, I would like to suggest that we consider adding a new WIKI section for "Terminology" (Definitions). With the large international audience, there are many terms that do not translate well. Examples:

  • bridge, wireless bridge, repeater bridge
  • WISP, STAtion, AP, hotspot

Clarity in these definitions would better help us align terminology across wiki documents or even to direct forum posters for clarification of their configuration. I am amazed at how challenging it is to understand what some users are trying to accomplish.