First version of quickstart guide. Still need to wire all the docs to…

…gether

contents.rst

@@ -0,0 +1,17 @@
+Sphinx documentation contents
+=============================
+
+.. toctree::
+   :caption: LEDE pages
+   :maxdepth: 1
+
+   index
+   reasons-to-use
+   documentation
+
+.. toctree::
+   :caption: Documentation
+   :maxdepth: 2
+
+   quick-start/index
+

documentation.rst

@@ -0,0 +1,33 @@
+LEDE Documentation
+==================
+
+LEDE is a highly extensible GNU/Linux distribution for embedded devices (typically wireless routers). LEDE is based on the OpenWrt project. Unlike many other distributions for routers, LEDE is built from the ground up to be a full-featured, easily modifiable operating system for embedded devices. In practice, this means that you can have all the features you need with none of the bloat, powered by a modern Linux kernel.
+
+LEDE Guides
+-----------
+
+`Quick Start Guide <guide-quick-start>`_
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Start here if you are new to LEDE. Find out how to upgrade the firmware your home router to use LEDE and make your network at home much better. `Read more... <guide-quick-start>`_
+
+
+`User Guide <user-guide>`_
+>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Start here if you already have LEDE running on your router. LEDE has hundreds of optional packages that give you VPNs, VLANs, and other capabilities. `Read more... <user-guide>`_
+
+
+`Developer Guide <guide-developer>`_
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Start here if you want to create custom builds of LEDE or contribute to its development. There are a large number of tools that make the development easy. `Read more... <guide-developer:the-source-code>`_
+
+
+Where can I learn more?
+-----------------------
+
+The three guides above (Newcomer, User, and Developer Guides) have links to virtually all the information about LEDE.
+You can also use the Search function from any wiki page, or work you through the complete listing of documentation pages shown below.
+
+{{pagequery>@:docs: *;sort=ns,title;group;cols=2;label=Documentation pages by namespace;hidestart;hidejump;display={title};}}

quick-start/admingui-sysupgrade-keepsettings.rst

@@ -0,0 +1,12 @@
+Web GUI Sysupgrade: The "Keep settings" checkbox
+================================================
+
+The "Keep settings" checkbox is a more advanced feature.
+
+If you do not precisely understand the button's use cases, **uncheck "Keep Settings"** every time you flash a new LEDE sysupgrade to your device, to **not** preserve settings.
+
+  * Only check the "Keep settings" checkbox on minor LEDE->LEDE bug fix upgrades that are known to not change the config structure
+  * Only use it for the same firmware channel (release->release, snapshot->snapshot)
+  * Checking it will preserve several specific config files on the upgrade, but not the whole overlay partition.
+  * If you flash your device regularly, preferably consider unchecking "Keep Settings" every time you flash the router and instead create a custom installation script for your customization. Example: `config-openwrt.sh <https://github.com/richb-hanover/OpenWrtScripts/blob/master/config-openwrt.sh>`_ script.
+  * "Keep settings" can also be used to preserve own configurations files. To do, go to **System > Backup/Flash Firmware** and open the **Configuration** tab, add your config filesthere and click "Submit". This will allow you to add your custom configuration files to the ''/etc/sysupgrade.conf'' file that is read by sysupgrade when it is backing up files. Click "Submit" when done editing.\\ To view all files that would be kept when "keep settings" is checked, click the "**Open list...**" button.

quick-start/alternate-directory-search.rst

@@ -0,0 +1,10 @@
+LEDE Alternate Directory Search
+===============================
+
+The LEDE download directory structure matches the OpenWrt download directories.
+
+If the Standard Flashing Instructions don't provide the information you're looking for, ask on the `Installation Category of the forum <https://forum.lede-project.org/c/installation>`_ or search the OpenWrt site for enough information about your device to find the proper LEDE firmware image. To do this:
+      * Find the **Device Page** for your device on the **OpenWrt Table of Hardware** at https://wiki.openwrt.org/toh/start
+      * Find the name and URL of the proper OpenWrt firmware image (factory or sysupgrade).
+      * Then go to `downloads.lede-project.org <https://downloads.lede-project.org/snapshots/targets/>`_ and find the LEDE image from the corresponding directory.
+      * Follow the flashing instructions on the **OpenWrt Device Page**, if needed.

quick-start/basic-wifi.rst

@@ -0,0 +1,36 @@
+Enabling a Wi-Fi access point on your LEDE device
+=================================================
+
+Devices that have ethernet ports have Wi-Fi turned off by default.
+This is a basic description, how to enable a first WiFi network and most important, how to properly configure your country code such that your WiFi network complies with the legal regulation of your country.
+
+On web admin GUI
+----------------
+
+  - Open the admin GUI on http://192.168.1.1
+  - Login with your "root" password
+  - Go to the menu Network → Wireless. This page list a separate WiFi configuration section for each of your pysical radios, (many devices you will have a first radio for 2.4 GHz and a second one for 5 GHz).
+  - For each of your radios, you can create a WiFi network by clicking ''Add'':
+    - On the first WiFi network that you configure, go to the **Device Configuration** and open the tab **Advanced Settings**: in the ''Country Code'' field, select the correct county code, where your LEDE device is installed. This is important to ensure your LEDE device meets legal regulations in your country. (all other configured radios will use the same device settings)
+    - For each WiFi network, in the "Interface Configuration" section, configure your WiFi settings, at least customizing the following settings:
+      * In the tab **General Setup**, define a custom ''ESSID'' (the name of your WiFi network)
+      * In the tab **Wireless Security**, activate some ''Encryption'' (e,g, "WPA2-PSK")
+      * In the tab **Wireless Security**, activate a ''Cipher'' (e.g. "Force CCMP AES")
+      * In the tab **Wireless Security**, in ''Key'', define a personal secret phrase, which clients need to use, to successfully connect to your WiFi network.
+      * If needed, configure further settings according to your needs. often the default settings like **auto** are sufficient for general usage.
+  - Click ''Save & Apply'' when done.
+
+Troubleshooting:
+  * If you have configured 5GHz WiFi and have just enabled it, but the 5 GHz WiFi does not seem to start up, consider the following: If your device supports WiFi channels > 100, your LEDE device first must scan for weather radar on these channels, before you can actually use such channels for WiFi. This may take 1-10 minutes onetime after first reboot depending on your WiFi situation and depending on the number of device-supported channels > 100. You may also experience 1 minute delay on each automatic channel change, as the same scan delay is required for regulation compliance.
+
+On SSH command line
+-------------------
+
+This is not a complete howto, to create a WiFi network on the command line.\\
+It just shows you the important step, to initially set your country code for proper WiFi on the command line, to meet legal regulations of your country:
+
+  * Connect with SSH to your LEDE device.
+  * Execute ''uci show wireless'' to see all the wireless configuration and how many Wi-Fi chips (called “radio” in the config) there are on the device
+  * Find out your country in a list of ISO/IEC 3166 alpha2 country codes. There is a list on the wikipedia article about ISO 3166-1 alpha-2
+  * Execute ''uci set wireless.radio0.country='XX' '' to set the country code XX for radio0 device, and adjust this command to set the same country code for all wireless radios in the device.
+

quick-start/developmentinstallation.rst

@@ -0,0 +1,44 @@
+Installing LEDE Development Snapshots
+=====================================
+
+**For experienced users only!**
+
+The steps below install LEDE development snapshot firmware on your device.
+
+What is a development snapshot firmware?
+----------------------------------------
+
+Development snapshots are also known as simply "snapshots" or the outdated term "trunk builds". Snapshots are versions of LEDE that are "in development". They are rebuilt frequently, often multiple times a day.
+
+I am a standard consumer, do I want a development snapshot firmware?
+--------------------------------------------------------------------
+
+**No!** Although they are the latest version, there is no guarantee that any particular snapshot build will be bug-free, or even work at all.\\
+Snapshots are not likely to be stable enough to be used on your home router, where you or members of your family rely on the network.\\
+As a standard consumer stick to the official release versions of LEDE.
+
+Snapshots do not have LuCi web admin GUI installed by default
+-------------------------------------------------------------
+
+On snapshots, LuCi has to be installed manually (if needed).
+
+Manual LuCi installation by package may require more free flash storage than a 4MB-flash-device can handle, `see 4/32 device warning <meta:infobox:432_warning>`_
+
+To manually install LuCi: `LuCI installation <user-guide/luci:Essentials>`_
+
+Installing a LEDE Snapshot
+--------------------------
+
+To install (or "flash") a LEDE snapshot firmware image, just follow the standard flashing instructions: `Factory install <quick-start:factory_installation>`_ and `Sysupgrade <quick-start/sysupgrade:luci>`_, with the only difference to use it for a firmware file from the snapshot download section.
+
+Optional Next Steps
+-------------------
+
+Once the snapshot is installed on your device
+  * `Install LuCI <user-guide:luci:Essentials>`_, if required
+  * Consult the `User Guide <user-guide>`_
+  * Install other packages with `opkg install ...`
+    * You should definitely install the **SQM-QoS package** to minimize lag/latency. Use `opkg install luci-app-sqm`, then read how to configure it in the `SQM Howto <https://lede-project.org/docs/howto/sqm>`_.
+    * Other useful packages are snmpd, netperf, and any of your favorites.
+  * If you have an unbranded / low-end / low-cost router that came shipped with OpenWrt / LEDE, you can find out the architecture it is using by connecting to it over ssh and opening `/proc/cpuinfo`. A combination of the `system type` and `machine` is what you are looking for.
+  * If you will be flashing LEDE snapshot firmware frequently, you can create a script that makes configuration changes in a reliable and repeatable fashion. See, for example, the `config-openwrt.sh <https://github.com/richb-hanover/OpenWrtScripts/blob/master/config-openwrt.sh>`_ script that updates most settings.

quick-start/factory-installation.rst

@@ -0,0 +1,81 @@
+Factory install: First-time installation of LEDE on a device
+============================================================
+
+Your device must still have the vendor firmware to be eligible for this so-called "factory installation" procedure.
+  * If your device already has an older LEDE or OpenWrt firmware on it, refer to the `sysupgrade <quick-start/sysupgrade>`_ howto instead .
+  * If you have any questions about this description, ask for help on the `Installing and Using LEDE forum section <https://forum.lede-project.org/c/installation>`_ before beginning.
+
+Device selection
+----------------
+
+  * Devices with >=8 MBytes Flash memory and >=64 MBytes RAM allow a full-featured LEDE installation with GUI.
+  * Devices with 4 MByte or less Flash memory can install LEDE as well, but with a limited feature set. They cannot use optional packages and in some cases may also not have a web GUI, due to limited flash space and may therefore have to stick to command line administration only. The creation of individual custom packages may help to avoid some of these limitations on such 'small' devices, but such a custom-package-creation is not part of this howto.
+  * If you want to purchase a new router for LEDE, stick to devices with >=8 MBytes Flash memory and >=64 MBytes RAM.
+
+Locate and download the LEDE firmware
+-------------------------------------
+
+  - On the `Table of Hardware: Firmware downloads <toh_fwdownload>`_ page, locate your specific device. The table of hardware only references stable release versions of LEDE. If you are a newbee, only use these stable release version for first-time device installations; do not initially use a (clearly marked) develop/snapshot version downloaded from other subfolders. This ensures that you get the easiest possible first-time LEDE installation experience.
+  - When you have located your device in this list, click on the "View/edit data" link of the device record. This will open a new page with several details for your specific device. We recommend to bookmark that page, as it has lots of helpful information about your router.
+  - On this device-specific **Techdata** page, at the bottom locate the line called **"Firmware LEDE Install URL"** that links to a downloadable file called **"...factory.bin"** file.
+  - Download this file.
+
+Troubleshooting:
+  * Some devices lack a factory image and require a special (and usually a bit more complex) installation procedure that is device-specific. This tutorial won't apply for such devices. If you have such a device, locate the corresponding device page in the older OpenWrt wiki and follow the custom installation description (Eventually older OpenWrt info will be migrated to the LEDE tech data pages).
+  * If you can't find your device in the Table of Hardware, or if there is no "...factory.bin" file, you can consult the `"Installing and Using LEDE" Forum <https://forum.lede-project.org/c/installation>`_ for help. You can also try `alternative ways to locate LEDE firmware images <quick-start:alternate-directory-search>`_
+  * If you have accidentally browsed the generic LEDE download folders to locate your device, you might see some more download files matching your device. Ignore those other files for your device: you only want the "...factory.bin" file.
+
+Verify the downloaded firmware file
+-----------------------------------
+
+You will now use a checksum tool, to calculate a checksum from your downloaded file and then compare this calculated checksum  with the file-specific checksum listed on the firmware download site.
+This ensures that you have a 100% correct download and that you will not brick your device by applying a faulty download.
+
+  - Check your downloaded "...factory.bin" file according to `checksum verification of downloaded LEDE firmware files <quick-start/verify_firmware_checksum>`_.
+  - Only continue with flashing, if the firmware checksum of your download matches the checksum stated on the download site!
+
+Troubleshooting:
+  * if the checksum process has reported a checksum mismatch, do NOT start flashing, as the download could be corrupt. A corrupt firmware file can brick your device! Instead retry with another download attempt and retry the checksum step.
+  * if the checksum step fails repeatedly, you can consult the `"Installing and Using LEDE" Forum <https://forum.lede-project.org/c/installation>`_ for help. Be sure to include the exact brand, model, and version of your device.
+
+Flash the firmware
+------------------
+
+  - Connect to the device via Ethernet cable (Only fallback to wireless, if the device has no Ethernet connection options)
+  - Ensure that the LEDE firmware file that you are about to flash, matches your router model and is called **"....factory.bin"**, as you will use it to modify a vendor's **factory** firmware towards LEDE.
+  -  Log into the device's admin web interface and locate the device-specific firmware installation function. Follow the device-specific instructions of your manufacturer's user guide for installing firmware and use this to install the  "...factory.bin" firmware file of LEDE.
+  - Wait while the device writes the firmware image to its flash memory. This can take several minutes (the Device Page may state an expected time for this process). At the end, the device will reboot automatically.
+  - The new firmware has been installed. Continue with the next section to check the result.
+
+Check flash result
+------------------
+
+  - After your device has finished flashing and rebooting, check if you can access the LEDE web admin GUI of LEDE on LEDE's default IP address: http://192.168.1.1
+  - Login to the LEDE web GUI as "root" admin user with the password field empty
+  - Go to the System->Administration page and define a new password in both fields, then click Save and Apply (at the bottom of the page).
+  - This has verified that you can successfully use the LAN ports of your LEDE device. You now have a working LEDE device in its initial default configuration.
+
+Troubleshooting:
+  * For this check only use an Ethernet cable, as WiFi is by default only enabled for devices that do not have Ethernet ports
+  * If you have flashed a development/snapshot firmware of LEDE, you first need to manually enable the admin web GUI: `development installation guide <quick-start:developmentinstallation>`_. Or verify the result on snapshot builds by SSH-connecting to your LEDE device IP 192.168.1.1
+  * You can consult the troubleshooting section of the `User Guide <user-guide/start>`_, if you think that resetting LEDE's settings might help.
+  * You can consult the `Installing and Using LEDE forum section <https://forum.lede-project.org/c/installation>`_, if something went wrong. Please provide specific details of your device and what you did so far and what you have attempted to fix it.
+
+Next steps
+----------
+
+  * For a first quick Internet access test: If you have an existing router, connect the WAN port of your LEDE device to a LAN port of that router and confirm internet connectivity of your LEDE device with the following steps:
+     * In the LEDE admin web GUI, go to Network -> Diagnostics and Click on "ping" button
+     * or, if using LEDE SSH command line, you can use the command ''ping lede-project.org''
+     * This should return "0% packet loss" if everything is allright with your Internet connection.
+  * Decide, whether you want to use LEDE `as switch,  router or gateway <user-guide/switch_router_gateway_and_nat>`_
+  * **When using your LEDE device as a WiFi access point, remember to initially set your country code in the LEDE WiFi configuration, to properly comply with your country's WiFi legal regulation!**, e.g. see here for a first `basic WiFi setup <quick-start/basic_wifi>`_.
+  * Consult the `User Guide <user-guide>`_ for more advanced configuration.
+  * Install custom software packages that you might be interested in.
+
+Troubleshooting your first steps with the new LEDE device
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+  * Do not worry, if the 5 GHz WiFi does not seem to start immediately after having enabled it. It might be busy for 1-10 min scanning for weather radar, see `basic WiFi setup <quick-start:basic_wifi>`_ for more background info.
+  * Note that you can always run ''logread'' on the SSH command line, to gain more insight into what the device is currently doing or to diagnose any kind of problems.
+  * If needed, you can also take a look at `Troubleshooting Internet Connectivity <quick-start:ts-internetconnectivity>`_].