How to install OpenWrt on OXNAS boxes
This thread is based on my tutorial HowTo: OpenWrt on Kirkwood boxes (Attention: if it is one of the Kirkwood Pogoplugs you have, it is that tutorial you want to follow!). The basic approach is
the same for the OXNAS', but some modifications are required (and, as we will see, not everything is perfect as of the original writeup of this tutorial on August 1st, 2022)
The procedure described in this thread is confirmed to work for both the Pogoplug Pro as well as the classic v3.
Credits
As always, credits are due to bodhi as well as to shv for his post on the subject and similarly to echowarrior108 for his efforts and also to David Golle over at OpenWrt.
Assumptions
I assume that the box in question has the latest uBoot and is able to boot a USB device with the latest kernel and rootfs according to the first two links in section Oxnas plugs of the wiki.
However, it will be absolutely necessary to be able to reach the box via netconsole or serial console.
The plan
We now want to install OpenWrt on our box. The steps we will need to take are
Implementation
So, let us look at these steps in more detail.
1. Modify uBoot variables
First, we need to boot the box to debian, log in and then do the following:
All the other variables can stay the way they were before, but we have to add the OpenWrt boot option to the bootcmd. If we still have bodhi's environment variables as they came, this would be:
The important part is to add 'run bootcmd_owrt' to the bootcmd you are currently using. So, if you changed something, e.g. to be able to boot with a separate boot partition or from SATA or anything like that, just append the OpenWrt boot option to the one you are using.
2. Download an OpenWrt image
Next, we need the appropriate image. Start on the release page of OpenWrt and choose the one you like best and then navigate to
Remark: When this tutorial was written, it meant that I used version 21.02.3, so concretely
Hint: It makes sense to keep the browser tab open for the final step 6.
3. Reboot to NAND with (net)console
Then, we need to reboot the box without the debian USB device, but with a way of interacting with it, preferably via netconsole. The latter needs to be started on the server beforehand with
4. Reboot with OpenWrt image
Insert the drive you created in step 2 into the box and boot it by issuing the following command at the (net)console prompt:
5. Log in to OpenWrt
Find the IP address of your box and ssh into it (user root without password). The following step is absolutely crucial but does not yet quite work the way it should.
Verify your mtd layout. Ideally, (see bodhi's u-Boot post) it should be:
Instead, what it will probably be (at least it was for me) is:
This means that for OpenWrt, the boot-section is further subdivided, while the ubi-/data-section is the same - and this also seems to be the source of the remaining issues with this setup (see below).
Temporarily generate or modify /etc/fw_env.config
Check whether the file /etc/fw_env.config has the following contents (which is easily calculated from the above MTD layout in comparison to bodhi's):
Afterwards, check that the uBoot environment is found by printing the variables to screen using
Remarks:
6. Install to NAND
Finally, we can perform a sysupgrade of OpenWrt/LEDE either using the WIF (Web Interface) or the command line. Since we are already logged in via ssh, I only describe the latter option, while the former may be found, e.g., in step 4.b of Jörg's original post for the Kirkwoods. We must do:
Remark: Coresponding to the above uImages, the concrete files for the sysupgrade were
The upgrade process will result in an automatic reboot (during which I removed the USB stick, but that may not be necessary).
7. Boot from NAND and log in to OpenWrt
There is, unfortunately, a very good chance that OpenWrt in NAND also cannot find the uBoot environment (as before in the case of the image loaded into RAM). Therefore, you have to repeat step 5. above in order to be able to modify the uBoot environment. This time, it will be a permanent modification of /etc/fw_env.config allowing you to make changes to the uBoot environment using your new rescue system. At least, this is the whole idea. But, unfortunatly, while we can READ the environment now, trying to write something to it will yield the following result:
8. Further configuration
Install nano (and more, if desired)
This step is completely optional, especially if you are happy to use vim. If not, do
MAC-Address
Other than the Kirkwood boxes, the OXNAS' seem not to pick up the ethaddr from the uBoot-environment. This results in a randomly assigned MAC-address at each boot and therefore (usually) ia a different IP on the local LAN for the box after each boot - definitely undesirable. Therefore, we must make use of OpenWrt's config options (as explained fully in the documentation). There are two ways of achieving this:
Option 1: within the ssh-console
You just open https://<IP-of-your-box> in your webbrowser and press "Login". Then, navigate to "Network -> Interfaces" and choose the "Devices"-tab. Then press the "Configure ..."-button for both "br-lan" and "eth0" and input the MAC-address there.
Edit ubootenv
This is just for sanity, since OpenWrt also specifies the location of the uBoot-environment in the file /etc/config/ubootenv. This should for reasons of sanity reflect the values we also specified in /etc/fw_env.config and should therefore be modified to look like this:
9. Enjoy
This thread is based on my tutorial HowTo: OpenWrt on Kirkwood boxes (Attention: if it is one of the Kirkwood Pogoplugs you have, it is that tutorial you want to follow!). The basic approach is
the same for the OXNAS', but some modifications are required (and, as we will see, not everything is perfect as of the original writeup of this tutorial on August 1st, 2022)
The procedure described in this thread is confirmed to work for both the Pogoplug Pro as well as the classic v3.
Credits
As always, credits are due to bodhi as well as to shv for his post on the subject and similarly to echowarrior108 for his efforts and also to David Golle over at OpenWrt.
Assumptions
I assume that the box in question has the latest uBoot and is able to boot a USB device with the latest kernel and rootfs according to the first two links in section Oxnas plugs of the wiki.
However, it will be absolutely necessary to be able to reach the box via netconsole or serial console.
The plan
We now want to install OpenWrt on our box. The steps we will need to take are
- Boot into debian and do some modifications to the uBoot environment variables
- Download, rename and copy to a FAT32 USB drive an OpenWrt Image
- Reboot the box without a USB device but with netconsole to interact with it <- this is crucial
- Use netconsole to boot OpenWrt image from the USB drive created before
- SSH into OpenWrt and make sure the uBoot environment is found <- this is crucial (and not quite working for the OXNAS yet)
- Install to NAND via sysupgrade OpenWrt
- Boot from NAND and SSH into OpenWrt and make sure the uBoot environment is always found (which is possible, but does not yet have quite the desired effect)
- Do some additional configuration
- Enjoy!
Implementation
So, let us look at these steps in more detail.
1. Modify uBoot variables
First, we need to boot the box to debian, log in and then do the following:
fw_setenv bootcmd_owrt 'nboot 60500000 0 440000; bootm'
All the other variables can stay the way they were before, but we have to add the OpenWrt boot option to the bootcmd. If we still have bodhi's environment variables as they came, this would be:
fw_setenv bootcmd 'run bootcmd_uenv; run scan_disk; run set_bootargs; run bootcmd_exec; run bootcmd_owrt'
The important part is to add 'run bootcmd_owrt' to the bootcmd you are currently using. So, if you changed something, e.g. to be able to boot with a separate boot partition or from SATA or anything like that, just append the OpenWrt boot option to the one you are using.
2. Download an OpenWrt image
Next, we need the appropriate image. Start on the release page of OpenWrt and choose the one you like best and then navigate to
/targets/oxnas/ox820/Then, download the uImage appropriate for your box. Rename it to uImage and place it in the root of a FAT32 formatted USD device.
Remark: When this tutorial was written, it meant that I used version 21.02.3, so concretely
- this image for the classic Pogoplug v3
- this image for the Pogoplug Pro
Hint: It makes sense to keep the browser tab open for the final step 6.
3. Reboot to NAND with (net)console
Then, we need to reboot the box without the debian USB device, but with a way of interacting with it, preferably via netconsole. The latter needs to be started on the server beforehand with
nc -l -u -p 6666Wait until after a few error messages you see the prompt, e.g.
OX820>in the console window (alternatively, you can force this via a keystroke during the bootdelay, if you configured one).
4. Reboot with OpenWrt image
Insert the drive you created in step 2 into the box and boot it by issuing the following command at the (net)console prompt:
usb reset; fatload usb 0 0x60500000 uImage; bootm 0x60500000This should end with
Starting kernel ...in the console output, meaning that OpenWrt is now running in RAM.
5. Log in to OpenWrt
Find the IP address of your box and ssh into it (user root without password). The following step is absolutely crucial but does not yet quite work the way it should.
Verify your mtd layout. Ideally, (see bodhi's u-Boot post) it should be:
root@OpenWrt:# cat /proc/mtd dev: size erasesize name mtd0: 00e00000 00020000 "boot" mtd1: 07200000 00020000 "data"
Instead, what it will probably be (at least it was for me) is:
root@OpenWrt:~# cat /proc/mtd dev: size erasesize name mtd0: 00040000 00020000 "stage1" mtd1: 00380000 00020000 "u-boot" mtd2: 00080000 00020000 "u-boot-env" mtd3: 009c0000 00020000 "kernel" mtd4: 07200000 00020000 "ubi"
This means that for OpenWrt, the boot-section is further subdivided, while the ubi-/data-section is the same - and this also seems to be the source of the remaining issues with this setup (see below).
Temporarily generate or modify /etc/fw_env.config
Check whether the file /etc/fw_env.config has the following contents (which is easily calculated from the above MTD layout in comparison to bodhi's):
/dev/mtd1 0xc0000 0x20000 0x20000If not or if the file does not exist at all, the easiest way to modify/generate it is
echo '/dev/mtd1 0xc0000 0x20000 0x20000' > /etc/fw_env.config
Afterwards, check that the uBoot environment is found by printing the variables to screen using
fw_printenv
Remarks:
- Since OpenWrt only runs in RAM at the moment, this is a temporary change. If you want to be able to access the uBoot environment from the OpenWrt rescue system later on, this step will most likely have to be repeated (see step 7 below).
- If you would rather modify an existing file, you can do so using vim (which is pre-installed in OpenWrt). If, like me, you do not want to learn vim and prefer nano, you can instead do
opkg update && opkg install nano
6. Install to NAND
Finally, we can perform a sysupgrade of OpenWrt/LEDE either using the WIF (Web Interface) or the command line. Since we are already logged in via ssh, I only describe the latter option, while the former may be found, e.g., in step 4.b of Jörg's original post for the Kirkwoods. We must do:
opkg update opkg install ca-certificates cd /tmp wget <URL of our desired sysupgrade file> sysupgrade <name of our desired sysupgrade file>The desired upgrade file may be found the same way as we found the image in step 2 above starting from the release page (but, ideally, you kept the browser tab open in step 2). There you can just copy the link address to the sysupgrade file (tar or bin depending on the release) and paste it into the ssh window.
Remark: Coresponding to the above uImages, the concrete files for the sysupgrade were
- this upgrade file for the classic Pogoplug v3
- this upgrade file for the Pogoplug Pro
The upgrade process will result in an automatic reboot (during which I removed the USB stick, but that may not be necessary).
7. Boot from NAND and log in to OpenWrt
There is, unfortunately, a very good chance that OpenWrt in NAND also cannot find the uBoot environment (as before in the case of the image loaded into RAM). Therefore, you have to repeat step 5. above in order to be able to modify the uBoot environment. This time, it will be a permanent modification of /etc/fw_env.config allowing you to make changes to the uBoot environment using your new rescue system. At least, this is the whole idea. But, unfortunatly, while we can READ the environment now, trying to write something to it will yield the following result:
root@OpenWrt:~# fw_setenv testvar 'something' Can't open /dev/mtd1: Permission denied Error: can't write fw_env to flash
8. Further configuration
Install nano (and more, if desired)
This step is completely optional, especially if you are happy to use vim. If not, do
opkg update opkg install nanoThen you can use nano for the upcoming modifications (and opkg to install a bunch of additional packages, if you so desire).
MAC-Address
Other than the Kirkwood boxes, the OXNAS' seem not to pick up the ethaddr from the uBoot-environment. This results in a randomly assigned MAC-address at each boot and therefore (usually) ia a different IP on the local LAN for the box after each boot - definitely undesirable. Therefore, we must make use of OpenWrt's config options (as explained fully in the documentation). There are two ways of achieving this:
Option 1: within the ssh-console
nano /etc/config/networkModify this by specifying the MAC-address (option macaddr) of your box at the appropriate locations. This should look like:
config interface 'loopback'
option device 'lo'
option proto 'static'
option ipaddr '127.0.0.1'
option netmask '255.0.0.0'
config globals 'globals'
option ula_prefix 'xxxx:yyyy:zzzz::/48'
config device
option name 'br-lan'
option type 'bridge'
list ports 'eth0'
# add option here
option macaddr '00:25:31:xx:yy:zz'
config interface 'lan'
option device 'br-lan'
option proto 'dhcp'
config interface 'lan6'
option device 'br-lan'
option proto 'dhcpv6'
config device
option name 'eth0'
# add option here
option macaddr '00:25:31:xx:yy:zz'
Option2: using Luci (the Web-IF)
You just open https://<IP-of-your-box> in your webbrowser and press "Login". Then, navigate to "Network -> Interfaces" and choose the "Devices"-tab. Then press the "Configure ..."-button for both "br-lan" and "eth0" and input the MAC-address there.
Edit ubootenv
This is just for sanity, since OpenWrt also specifies the location of the uBoot-environment in the file /etc/config/ubootenv. This should for reasons of sanity reflect the values we also specified in /etc/fw_env.config and should therefore be modified to look like this:
config ubootenv
option dev '/dev/mtd1'
option offset '0xc0000'
option envsize '0x2000'
option secsize '0x2000'
option numsec '1'
Unfortunately, this also does not yield a writeable uBoot-environment ...
9. Enjoy