UpSlug2 is a tool to flash your NSLU2 from a computer on the same network. It is available for Linux and MacOS X. Windows users see below.

Basic use

See below for how to obtain and install the program.

To use it, first you have to put your NSLU2 into 'upgrade mode'. This is described here: UseTheResetButtonToEnterUpgradeMode.

Then, to find a list of NSLU2 machines in upgrade mode, just run the upslug2 program with no options. (Note that UpSlug2 must always run as root):

If this doesn't find your Slug it means that either you have not put it in upgrade mode successfully, or the network connection between the PC and the Slug is not working (see the notes below about the network requirements). Or, if your PC has more than one network interface, you may need to specify one using --device.

If more than one Slug is detected you need to give the full ethernet MAC address (six pairs of hex digits separated by ':' characters) as the argument to the --target option to identify one of them. This is not necessary if there is only one Slug in upgrade mode.

You specify the flash image using the --image option. The flash image should be an 8 MByte file. Here is an example:

As it runs the program will display progress information as it erases, programs and verifies the flash. When it completes it will reboot the Slug.

Network Requirements

UpSlug2 requires a direct connection to the NSLU2 in the same Ethernet segment. This means it will not work if you have routers or NAT devices between your computer and the NSLU2. A WiFi connection via a wireless access point can be used, however a wireless connection is not as reliable as a wired one and some users do not recommended it for re-flashing the NSLU2.

Obtaining UpSlug2

If you use one of the following distributions you can install it from the usual package repositories, as follows:

• Gentoo: emerge upslug2
• Debian etch: apt-get install upslug2
• Unslung slug, or any optware device: ipkg install upslug2 (Yes, you can use a slug running Unslung, or any device that supports optware, to upgrade a slug.)
• Ubuntu (Edgy and above): sudo aptitude install upslug2
• Fedora 7/8: yum install upslug2
• rhel 5 i386: rpm -ihv http://pion.xs4all.nl/rpm/rhel5-i386/upslug-20070916-1.i386.rpm
• rhel 5 x86_64: rpm -ihv http://pion.xs4all.nl/rpm/rhel5-x86_64/upslug-20070916-1.x86_64.rpm
• openSUSE: http://software.opensuse.org/search?baseproject=ALL&p=1&q=upslug2

If you have a Mac, you will need to build UpSlug2 from source, as described in the UpSlug2 on OSX page.

Otherwise you can install from source as follows.

The source code for UpSlug2 resides in the Subversion repository of the nslu2-linux project and has a standard GNU autotools configuration environment. You can fetch it from the repository at http://svn.nslu2-linux.org/svnroot/upslug2/trunk/ or you can browse it with trac.

After you have downloaded the source code, use GNU autotools (i.e. autoconf and automake) and GCC to build upslug2:

Note: On Fedora Core 1, I had to modify the configure.ac file, changing the expected versions for autoconf and automake to the following.

To build for MacOS X or other BSD-derived operating systems, see Main.UpSlug2onOSX.

For other operating systems consult PortingUpslug2.

Permissions

upslug2 must either be run as root or, more secure, install the program into a system directory with root setuid; as root:

When made setuid the program only uses the root privilege to open the ethernet device (eth0 or the one specified to --device). The device name is only used in socket calls.

Windows Users

If you only have a Windows computer available you can make it run Linux temporarily just for UpSlug2, without affecting anything on its hard disk, by booting from a "Live" Linux CD such as Knoppix. Alternatively you could use the Sercomm Update Utility for Windows.

Upslug2 does work with VMware Workstation. Note that the user must configure the VM to have access on the ethernet in Bridge mode. (Upslug2 requires layer 2 access on the network). You must be using version 6 or above of VMWare workstation.

For a proof of Debian Etch running Upslug2 in a VMWare 6 pc, bridged network to a 64bit Vista Ultimate host, see here.

Upslug2 also works from a virtual Fedora 7 on Microsoft Virtual PC / Vista.

More specialized options for developers:

With just the kernel image ("zImage-openslug") and the image of the JFFS2 root file system ("openslug-nslu2-date.rootfs.jffs2"):

To get more information about the options:

If you need to use an ethernet device other than eth0 (the default built in to the program) simply specify it with the --device option. Test that the device works correctly by using upslug2 with no options other than --device.

Remember you will need to run upslug2 as root in order for it to correctly access the ethernet interface on your host machine.

Overwriting the boot loader

UpSlug2 has some of the functionality of slugimage (also in the NSLU cvs repository). When used with the --image option it copies the given image without change, however it does not overwrite the RedBoot or SysConf partitions. To overwrite these partitions use --image with --Complete-reprogram after editing the program (in upslug2.cc) to allow this option.

The --Complete-reprogram option is deliberately disabled because it overwrites the boot loader - if you get it wrong (because the image is incorrect) or if the power fails during the writing of the RedBoot partition you will have to use JTAG to reflash the boot loader.

Changing the partitions

With the options documented above a fairly standard flash layout is produced, matching that used in the OpenSlug image. It is also possible to write an old Unslung or LinkSys style image which has a Ramdisk partition and no jffs2 (Flashdisk) partition.

The partition layout is as follows (assuming 0x50000000 base offset):

The image is terminated by a 16 byte signature which identifies the image as valid to RedBoot and includes the product ID, protocol ID and firmware version fields (each two bytes) plus an extra 2 byte version field. The defaults for these fields are taken from the LinkSys R29 image but may be changed by the corresponding upslug2 options.

Full information (from "upslug2 --help" output):

Usage: upslug2 {options}

 options:
  -h --help:                     output this help message
  -d --device[eth0]:             local ethernet device to use
  -t --target:                   NSLU2 to upgrade (MAC address)
  -f --from:                     MAC of host (this machine)
  -v --verify:                   verify only (do not write flash)
  -U --no-verify:                upgrade only (do not verify)
  -n --no-reboot:                do not reboot after upgrade
  -i --image:                    complete flash image to use
  -C --Complete-reprogram:       overwrite RedBoot
  -k --kernel:                   compressed kernel image (zImage)
  -r --ramdisk:                  compressed ramdisk image (rootfs)
  -R --ram-payload:              payload (replaces ramdisk)
  -j --rootfs:                   jffs2 (flash) rootfs
  -p --payload:                  FIS directory payload
  -e --endian[,b,b]:             kernel and data endianness;
                          [<kernel>],<data>[,<directory>]
                          l: little endian
                          p: pdp endian
                          b: big endian

  -P --product-id[1]:            2 byte product id
  -T --protocol-id[0]:           2 byte protocol id
  -F --firmware-version[0x2329]: 2 byte firmware version
  -E --extra-version[0x90f7]:    2 byte extra version info

 Specify --target to upgrade an NSLU2 (or to verify a previous upgrade)
 without no arguments upslug2 will list the NSLU2 machines which are currently
 in upgrade mode (and do nothing else).  Without --target upslug2 will only
 perform an upgrade if there is just one NSLU2 in upgrade mode.

 Specify --image=<file> if a complete NSLU2 flash image is available, if
 --Complete-reprogram is specified the whole flash image will be overwritten
 (the NSLU2 may become permanently unuseable if this is done), otherwise the
 RedBoot boot loader and the current 'SysConf' configuration is not changed.

 Alternatively specify --kernel and --rootfs to build the image which will be
 used to upgrade the NSLU2.  In this case --product-id, --protocol-id and
 --firmware-version should be specified to set these fields in the flash image.

 Image endianness is detected automatically from the kernel.  By default no byte
 swapping is performed (none is normally necessary).  The --endian flag can be
 used to force byte swapping to occur.  It takes three arguments separated by ','
 characters to specify the endianness of the kernel, the data and the values in
 the RedBoot FIS directory

(The above partition information is not accurate for Debian installations that use APEX - would someone like to update it?)