openwrt-auto-extroot/README.md

# What

It's a script to build a customized
[OpenWRT](https://openwrt.org/docs/guide-user/start)
firmware image using
[ImageBuilder](https://openwrt.org/docs/guide-user/additional-software/imagebuilder).

If the generated image is flashed on a device it will try to
automatically set up
[extroot](https://openwrt.org/docs/guide-user/additional-software/extroot_configuration)
on **any (!)** storage device plugged into the USB port (`/dev/sda`),
including your working extroot pendrive if you plug it in only later
in the boot process. Keep in mind that **this will erase any inserted
storage device while the router is in the initial setup phase**!
Unfortunately there's little that can be done at that point to ask the
user for confirmation.

# Why

So that e.g. customers can buy a router on their own, flash our custom
firmware, plug in a pendrive, and manage their SIP (telephony) node
from our webapp.

I've extracted the generic parts from the above mentioned auto-provision
project because I thought it's useful enough for making it public.

# How

You can read more about the underlying technology on the OpenWRT wiki: see e.g. the
[ImageBuilder](https://openwrt.org/docs/guide-user/additional-software/imagebuilder)
page, or the page that lists some other
[ImageBuilder frontends](https://openwrt.org/docs/guide-developer/imagebuilder_frontends).

As for the actual mechanism: custom scripts are baked into the boot
process of the flashed firmware. If the extroot overlay is properly
set up, then these scripts get hidden by it; i.e. they will only run
when the extroot has failed to mount early in the boot process.

### Building

OpenWRT's ImageBuilder only works on Linux x86_64. To build a firmware, issue the following command:
`./build.sh architecture variant device-profile`, e.g.:

* `./build.sh ath79 generic tplink_tl-wr1043nd-v1`
* `./build.sh ath79 generic tplink_archer-c6-v2`
* `./build.sh ath79 generic tplink_tl-wdr4300-v1`

Results will be under `build/openwrt-imagebuilder-${release}-${architecture}-${variant}.Linux-x86_64/bin/`.

To see a list of available targets, run `make info` in the ImageBuilder dir.

If you want to change which OpenWRT version is used, then edit the relevant variable(s)
in `build.sh`.

### Setup stages

Blinking leds show which phase the extroot setup scripts are in. Consult the
sources for details: [autoprovision-functions.sh](image-extras/common/root/autoprovision-functions.sh#L49).

#### Stage 1: setup extroot

When the custom firmware first boots, the autoprovision script will
wait for anything (!) in `/dev/sda` to show up (that is >= 512M), then erase
it and set up a `swap`, an `extroot`, and a `data`filesystem (for the remaining
space), and then reboot.

#### Stage 2: download and install some packages from the internet

Once it rebooted into the new extroot, it will continuously keep trying to install
some OpenWRT packages until an internet connection is set up on the router. You
need to do that manually either by using ssh or the web UI (LuCI).

#### Stage 3, optional

We also have a 3rd stage, written in Python, but it's commented out here.
Search for `autoprovision-stage3.py` to see how it's done.

### Login

After flashing the firmware the router will have the standard
`192.168.1.1` IP address.

By default the root passwd is not set, so the router will start telnet with
no password. If you want to set up a password, then edit the stage 2 script:
[autoprovision-stage2.sh](image-extras/common/root/autoprovision-stage2.sh#L53).

If a password is set, then telnet is disabled by OpenWRT and SSH will listen
using the keys specified in [authorized_keys](image-extras/common/etc/dropbear/authorized_keys).

Once connected, you can read the log with `logread -f`.

# Status

This is more of a template than something standalone, but I use it for
my home routers as is. You most
probably want to customize this script here and there; search for
`CUSTOMIZE` for places of interest.

Most importantly, **set up a password and maybe an ssh key**.

At the time of writing it only supports a few `ath79` routers out of
the box, but it's easy to extend it. Support for a new router entails
looking up some led names for `setLedAttribute` so that there's
feedback to the user through the blinking of the leds. It should work
fine without that, but it will be less convenient to interact with
your router in the initial setup phase.

# Troubleshooting

## Which file should I flash?

You should consult the [OpenWRT documentation](https://openwrt.org/docs/guide-user/start).
The produced firmware files should be somewhere around
```./build/openwrt-imagebuilder-21.02.0-ath79-generic.Linux-x86_64/bin/targets/ath79/generic/```.

In short:

* You need a file with the name ```-factory.bin``` or ```-sysupgrade.bin```. The former is to
  be used when you first install OpenWRT, the latter is when you upgrade an already installed
  OpenWRT.

* You must carefully pick the proper firmware file for your **hardware version**! I advise you
  to look up the wiki page for your hardware on the [OpenWRT wiki](https://openwrt.org),
  because most of them have a table of the released hardware versions with comments on their
  status (sometimes new hardware revisions are only supported by the latest OpenWRT, which is
  not released yet).

## Help! The build has finished but there's no firmware file!

If the build doesn't yield a firmware file (```*-factory.bin``` and/or ```*-sysupgrade.bin```):
when there's not enough space in the flash memory of the target device to install everything
then the OpenWRT ImageBuilder prints a hardly visible error into its flow of output and
silently continues. Look into [build.sh](build.sh#L31) and try to remove some packages
that you can live without.