readme modified by Alejandro Liu

Alejandro Liu — Fri, 18 Oct 2013 13:17:15 -0000

NAS-CC Boot Firmware

This is the NAS-CC boot firmware. This firmware is
meant to replace the LinkSys stock firmware.

NAS-CC boot's firmware main functionality is to:

Allow users to run a standard Desktop class distribution.

Actual end user functionality is provided by the installed distro.

The NAS-CC boot firmware makes use of an old Buildroot snapshot
(2008-08-27). This is included with the source distribution.

Allthough, this firmware is quite old, it provides all the
functionality needed for a basic boot environment.

Package Contents

This is the list of the top-level files

binaries/ - Where the images are created
br-XXXXX/ - Created from buildroot-YYYYMMDD.tar.bz2.
buildroot-YYYYMMDD.tar.bz2 - Snapshot of buildroot.
dl/ - Contains downloaded source files. Empty until you do your own
firmware builds.
docs/ - Misc documentation.
extras/ - Extra packages added by NAS-CC to what is already
available from buildroot.
kernel-patches/ - Patches to the stock Linux kernel. They provide
the NAS200 platform specifics.
local/ - buildroot build profiles.
nas200-misc.mk - Some additional customisations to the root image.
patches/ - Patches made to buildroot.
README.txt - this file.
mk - Utility scripts.
skel/ - skeleton directories. Used to pre-initialise root images.
tools/ - Support utilities.
version.txt - Versioning information

Building from source

Unpack the source tarball. Then enter:

$ ./mk

From the root directory of the unpacked source tarball.

Testing the build

For this you need a working qemu program. Enter:

./mk run boot

This will attempt to run your boot image from qemu.

By default it will qemu user level networking. This means that it
will configure the network using DHCP and assign IP address
10.0.2.15. The host acts as the router and is given IP address
10.0.2.2. A virtual DNS servers is visible on 10.0.2.3.

Installing the BOOT Firmware

BEWARE doing this may brick your NAS200.

Essentially there are two ways of getting NAS-CC on your device.
One is using the redboot upgrade utility and the other one is using
the upgrade firmware option from the webpage.

The preferred method for upgrading under NAS-CC is by the redboot
upgrade utility since NAS-CC does not provide its own method for
doing firmware upgrades. That is, if after downgrading to NAS-CC
you want to go back to a different firmware you will have to use
redboot upgrade to do so.

To upgrade using NAS-CC this software distribution includes a script
to put your NAS200 in upgrade mode and the upslug program that is
used to flash the firmware.

upslug is a Linux tool. For Windows users, you may want to visit
this
web site.

Before beginning, you must compile the upslug executable. This can
be found in the tools/upslug subdirectory. It is up to you to
decide if you want to place upslug in your executable PATH.

These steps must be run as root user:

Make sure your NAS200 is off.
run the script swupgrade which can be found in the
tools/upslug sub-directory.
Turn-on your NAS200.
The NAS200 should start blinking its power LED orange. Also at
this point swupgrade should have printed the word Redboot> and
return you to the shell prompt.
Run upslug with upslug -f -u firmware.bin. Replace
firmware.bin with the name of your firmware file.
Follow the prompts.

You can use this procedure to install not only NAS-CC but any
firmware that is compatible with the NAS200.

Using NAS-CC boot firmware

Installing the boot NAS-CC firmware image does not touch any of the
attached discs. By default it will scan any attached storage devices,
either internal SATA or external by USB, for boot scripts. If it
finds any, it will try to boot from them.

You can break the boot process by pressing the two USB buttons in the
back of your NAS200.

If it did not find any boot scripts or if you aborted the boot process
(by pressing the USB buttons) it will drop into fail-safe mode. In
fail-safe mode, you can only log-in to the system by using an attached
serial console. However, pressing the two USB buttons will enable
a telnetd daemon.

By default this provides a password-less telnet console on an IP
address provided by DHCP or the default redboot IP address:
192.168.21.249 if DHCP is not available.

You can then to start using your NAS-CC by telnet'ing to it (either
by the IP address provided by the DHCP server or 192.168.21.249 if
DHCP is not functioning). This will give you a prompt where you can
enter Linux commands. You can use this prompt to check if things are
working. A basic set of disc management and network commands are
available for you to set-up your NAS200.

Booting a distro

After your NAS200 has been flashed you need to create a distro USB key
to boot from.

Refer to the distro specific instructions:

CentOS

NAS-CC Boot modes

The NAS-CC will boot the /rc script when first starting as the
init process. This script scans all attached storage devices
(including USB ports) for bootable partitions. If it finds one or
more bootable partitions it will proceed to boot them. If this fails
(because the partitions were misconfigured or there were none) then it
will drop to its fail-safe mode.

Determining if a partition is bootable is done by mounting it and
checking if any of thes files are present:

kexec scripts

nascc*.sh
lnxboot*.sh

chroot scripts

chroot*.sh

firmware scripts

fwboot*.sh

misc scripts

script*.sh

NAS-CC will look for these files in all these directories of a partition:

/boot
/etc
/ (root)
/share
/share/boot
/share/etc
/public
/public/boot
/public/etc

The directories beginning with /share should map to the Linksys
DISK_1 shares. While the ones begining with /public to the
PUBLIC DISK shares.

The * should be replaced with a number which is used to determine
the priority. i.e. higher priority scripts will override lower
priority scripts. The default (if no number is specified) is 50.

So you can set up a bootable partition on the internal SATA discs with
priority 50 and if you want to boot a differrent configuration you can
store it on a USB drive with a higher priority. NAS-CC will boot
from the USB drive if it has the highest priority. This is a way to
quickly test new kernel/root configurations without having to reflash
your device.

oneshot scripts

If the filename started with the characters one, the scripts is
taken to be a oneshot script. That means, that it will only be used
once and afterwards, the script will be renamed to
no(original-name).

This is used so that you can safely test new boot configurations. If
the boot configuration failed, it will be ignored the next reboot.
You just need to rename the boot script to something without the no
and/or one in front to make the change permanent. After you are
happy that things work correctly.

kexec scripts

kexec scripts allows you to replace the currently running Linux kernel
to a new kernel. kexec scripts can contain the following
specifications:

kernel=vmlinuz
cmdline="console=ttyS0"
initrd=""

Shown are the default values. You can (should) override this as
necessary. The kernel and initrd can be specified as absolute paths
if starting with / or are considered relative to the kexec script
location.

kexec - THis is the name of the linux kernel we are trying to boot.
cmdline - additional command line parameters that should be passed
to the linux kernel command line (usually the append line in
lilo).
initrd - initrd file to use. If blank, no initrd will be used.

The kexec script file is actually a shell script so any shell
commands are valid here.

Useful variables that are available for use are:

bootpart - /dev/xxxyy device file path for the boot partition.
bootdisc - /dev/xxx device file path for the boot disc (without
partition).

chroot scripts

These scripts simply transfer control to the boot partition without
loading a new linux kernel. This means that you will be using the
Linux kernel loaded from flash. The boot partition will become the
new root parition. chroot scripts can contain the following:

new_root=/mnt
old_root=/pivot
init=/sbin/init

These are the defaults and do not need to be specified.

The old root parititon will be available in the directory specified by
old_root (/pivot by default) and must already exist on the root of
the boot partition. The old root partition can then be unmounted.

Control will be transferred to the init program (usually
/sbin/init) for the actual start-up sequence.

The boot parition is always mounted read-only.

firmware scripts

These scripts allow you to replace the currently running Linux kernel
with a new kernel and initrd image loaded from a firmware image
file, in the same format as the ones used to flash the system.

Firmware scripts can contain the following specifications:

cmdline="console=ttyS0 root=/dev/ram0"
fwname=linux.bin

Like kexec scripts, this file is actually a shell script so any shell
commands are valid here.

Useful variables that are available for use are:

bootpart - /dev/xxxyy device file path for the boot partition.
bootdisc - /dev/xxx device file path for the boot disc (without
partition).

This actually loads the squashfs into memory so you loose about 6MB
of RAM with this set-up. Because the Linksys firmware will activate
swap areas, this should not be much of a problem.

You can use this to boot the NAS200 original Linksys firmware. Just
make sure that the boot script and firmware file are located either in
a root share called /etc or /boot.

misc scripts

misc scripts are just shell scripts that will be called during the
boot process.

These can be used to do special configuration actions on your device.
Combined with the oneshot facility, this can be used for making
unattended/scripted upgrades of devices.

Copyright

NAS-CC is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.

NAS-CC is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public
icense along with this program. If not, see
http://www.gnu.org/licenses/

Recent changes to readme

readme modified by Alejandro Liu

NAS-CC Boot Firmware

Package Contents

Building from source

Testing the build

Installing the BOOT Firmware

Using NAS-CC boot firmware

Booting a distro

NAS-CC Boot modes

kexec scripts

chroot scripts

firmware scripts

misc scripts

oneshot scripts

kexec scripts

chroot scripts

firmware scripts

misc scripts

See Also

Copyright