Upgrading To Unslung 6.x

This article pertains to:

• Unslung 6.x only

(It should be mentioned that a lot of people have experienced problems with the latest R63 release from Linksys. After accessing the not unslung device, the NSLU freezes completely. Of course this behavior propagate to the unslung 6.x distribution. Probably this is caused by the ntfs driver)

For users of Unslung 5.5 (and earlier), the task of upgrading to Unslung 6.x is not to be taken lightly. The addition of the significant new features in the Linksys R63 firmware has required some fundamental changes in the way disks are handled, changes that may make an upgrade more of a challenge than hoped for.

Before continuing here, please take a moment to read these Wiki articles:

• Unslung.R63DiskBehaviour
• Unslung.WhichUSBPortforUnslung6

Note that if you have a complicated installation, or encounter strange messages or errors, or if you have more than a single disk on your NSLU2, or if you just wish to understand some of the technical details of the changes in R63 and Unslung 6 most likely to cause "breakage", it is highly recommended that you read the sections on "Upgrade Challenges" at the end of this article.

Upgrade Strategies

We can identify three different approaches to the upgrade:

Starting Over a.k.a "Clean Start"

This is a perfectly legitimate upgrade strategy, and one that might be especially attractive to newer Unslung users. If the phrase "If I only knew then what I know now, I would have done it differently!" describes your feelings about your current Unslung NSLU2's installation and configuration, well, this upgrade strategy is for you.

(Check Unslung.CleanStartUpgradeExperiences for other upgraders' experiences, learnings, and shortcuts about this strategy.)

Procedure:

1. Copy data off to another place in the network or to another drive.
2. Record all settings that you wish to preserve.
   • Network Shares that you may have added.
   • User accounts and passwords you may have created.
   • Software packages you wish to install on the new system, and any custom settings and configuration files for same.
3. Unplug the drive(s), attach to another Linux or Windows system.
4. Format the drive(s) as a single partition, FAT or NTFS filesystem [Note: this step is required because if you instruct the NSLU2 to "format" a disk that appears to already be formatted, the NSLU2 will not do anything at all to the disk -- re-partitioning the disk on another system as described here will force the NSLU2 to actually create fresh, empty partitions].
5. Follow the README to reflash the NSLU2 with the Unslung 6.x firmware, format the drives to the native ext3 format, and unsling the system (run "/sbin/unsling")
6. Reboot the NSLU2.
7. Restore your settings, reinstall the applications, and copy the data back to the NSLU2.

Part of the value of a wiki such as this is the collective knowledge we all bring. Please add your experiences with this upgrade approach to Unslung.CleanStartUpgradeExperiences.

"Dirty Start"

The big drawback of the "Clean Start" approach is that you need to be able to back up all data currently on the NSLU2 - which might be a problem for some. If the "starting over" idea is appealing to you, but you just cannot move all the data off of the NSLU2, there is another approach. However, be warned - we cannot guarantee the safety of your data! You alone are responsible for your data, nobody but yourself can be held liable or accountable if your data is lost or damaged during this procedure!

If you do not understand the risk to your data, or do not agree that you alone are responsible for the data on your NSLU2, then please close this document immediately, and DO NOT attempt this procedure.

Ok, with that out of the way, here's the strategy: a natively-formatted ext3 disk contains a directory named /public which maps to the "DISK 1" network share. This directory is preserved across all Linksys firmware upgrades, and will also be untouched by the unsling process. The approach is to find everything that is not in the /public directory, and move it into a "holding" area in the /public directory. This will result in a system that (theoretically) can be recovered by moving all the stuff back, but will appear to be a clean disk for a fresh install (just remember to not do a format on the drive during the installation process!).

(Check Unslung.DirtyStartUpgradeExperiences for other upgraders' experiences and learnings about this strategy.)

Procedure [NOTE: assumes a single disk in USB Port 1, Unslung 5.5]:

1. Record all settings that you wish to preserve.
   • Network Shares that you may have added.
   • User accounts and passwords you may have created.
   • Software packages you with to install on the new system, and any custom settings and configuration files for same.
2. Shut down the NSLU2
3. Detach the disk, and restart
4. Login to the NSLU2, and re-attach the disk.
5. Verify that the disk is recognized and mounted on /share/hdd/data
6. Create the directory for the "holding area": mkdir /share/hdd/data/public/unslung55
7. Change directory to the drive: cd /share/hdd/data
8. Now use the ls command and mv command to move everything in /share/hdd/data into /share/hdd/data/public/unslung55, except:
   • the quota files (/share/hdd/data/public/quota.user and /share/hdd/data/public/quota.user~)
   • /share/hdd/data/public itself -- don't copy that; it's very much like a snake trying to swallow its own tail.
   • /share/hdd/data/lost+found
9. Don't forget to move the hidden files that mark the disk as an unslung disk:
   • mv /share/hdd/data/.unslung /share/hdd/data/public/unslung55/.unslung
   • mv /share/hdd/data/.sda1root /share/hdd/data/public/unslung55/.sda1root
10. Verify that the new contents of /share/hdd/data look like this:
    • ls -la /share/hdd/data
      • drwxrwxr-x 21 admin everyone 4096 Feb 18 18:04 .
      • drwxrwxr-x 4 admin everyone 4096 Sep 10 00:15 ..
      • drwxr-xr-x 2 root root 4096 Dec 31 1969 lost+found
      • drwxrwxrwx 11 admin everyone 4096 Mar 2 13:58 public
      • -rw------- 1 root root 64032 Feb 28 15:40 quota.user
      • -rw------- 1 root root 64032 Feb 18 18:02 quota.user~
11. Follow the README to reflash the NSLU2 with the Unslung 6.x firmware -- but do not format the drive to the native ext3 format; it already is, and holds all your data(!) -- and unsling the system (run "/sbin/unsling")
12. Reboot the NSLU2.
13. Reinstall the applications.

As with the Clean Start approach, your experiences and learning will be very helpful for others in the community. Please add your experiences to Unslung.DirtyStartUpgradeExperiences.

In-place Upgrade

You don't want to move a thing. You desire to just flash the NSLU2 with the firmware, and unsling to the existing Unslung 5.5 installation, overwriting where necessary.

Well, this should work. The author of this article doesn't know how well it might work, however -- it certainly didn't work very well when he was upgrading between the various Unslung 6.x alpha releases. It's probably just a matter of figuring out what to fix where after the unsling in order to get it all running again.

The huge advantage of this approach is incredible simplicity. The clear downside is that it might render you with a disk that won't boot Unslung 6.x, but neither can be restored to its original Unslung 5.5 state. That could be unfortunate, indeed. Until this approach is better explored and understood (a challenge for the brave and risk-takers in the Unslung community!), the unsling utility itself will refuse to do it. It will explain what file to remove from the target disk to enable it to perform the unsling operation, and warn you once again that you enter uncharted territory.

As with the other upgrades, please use this article to outline your experiences and experiments with this potentially-promising upgrade approach: Unslung.InPlaceUpgradeExperiences

Upgrade Challenge #1

For unknown reasons, Linksys changed the mapping of disk devices to USB ports, and the mapping of disk devices to mount points. Specifically, here's what it used to look like:

That all made sense. Now, introducing the new order of things with R63 (and Unslung 6.x):

As the bolded changes indicate, there's just no way even if you move drives around on ports, that something isn't going to change. Either you end up with your drives mounted on /share/hdd/... as before -- but your drive device switches to /dev/sdbn (and you lose the flexibility of USB Port 1), or you move the first disk to USB Port 2, in which case your drive device remains /dev/sdan, but the drives end up mounted on /share/flash/.... The good news, such that it is, would be that there are few software packages that should be aware of either the device name or the disk mount point -- so if you do experience a failure, it's very likely to be a bug.

Now that you might think that at this point you understand the changes, but take a look at what happens if you add a second natively-formatted (ext3) drive to an NSLU with R63 (or Unslung 6.x):

The /dev/sda2 partition which used to be mounted on /share/flash/conf 2 is not mounted at all, and instead the /dev/sdb2 partition is mounted on both /share/hdd/conf and /share/flash/conf. The good news, if there is any to be found in this strange behavior, is that the conf partition is only used for a small number of files.

Unfortunately these files include the passwd, group, smbpasswd, and other critical system files. The message is clear: either avoid dual natively-formatted ext3 drives, or if you must use such a configuration, either use /dev/sdb (the disk in USB Port 1) as the root disk or accept that the resulting Unslung system will be dependent upon both drives.

From an upgrading point-of-view, this odd behavior shouldn't be a big problem, as long as you consider the possible loss of all user ids and password to not be a big problem.

Upgrade Challenge #2

A little-known feature of Unslung is that it actually searches for the root drive when it boots up. So if you've plugged your drive into the wrong USB port, it's quite possible that your NSLU2 will boot and run just fine! (This can be viewed as a "bug", too -- if you feel strongly that this behavior is "misbehavior", please mention your concerns on the nslu2-linux mail list. It's only code, and can be changed if the concensus wishes so.)

This is "A Very Good Thing" for experimenters, but it can be a nasty trap that is especially likely to trip up the unsuspecting upgrader.

Consider the scenario of the upgrader who has opted to perform a "Clean Start" upgrade to a new disk, and intends to plug in the original Unslung 5.5 disk as a second drive for Unslung 6.x. Our upgrader has chosen to plug the new drive or memory stick into USB Port 1, and has unslung to "disk 1" (which, courtesy of Linksys is now /dev/sdb). All goes well, and the system checks out perfectly.

Now the upgrader makes a huge mistake: he has set aside his original disk (the one which was previously unslung to with Unslung 5.5) and now plugs it into the "USB Port 2" port and boots his NSLU2.

Here's what happens:

• The kernel boots from the internal flash
• The linuxrc script on the internal flash runs
  • it determines that this system is unslung, and begins the search for a bootable drive (starting with /dev/sda)
  • it mounts the drive on USB Port 2 (/dev/sda, the preferred root drive), and sees if it appears to be bootable.
  • the drive on USB Port 2 appears to be bootable, so that drive becomes the new root filesystem.....

and at this point, things have gone very wrong indeed, as the drive on Port 2 was the old Unslung 5.5 drive -- it passed the tests because it was indeed perfectly bootable as an Unslung drive, the only problem is that it was for a previous version of Unslung.

The solution is fairly simple. Any of the following will avoid this problem:

• Leave the desired root drive for Unslung always plugged into USB Port 2 (/dev/sda).

or

• Remove the /.sda1root or /.sdb1root files on the old disk. In other words, ensure that the only filesystem that has the /.sda1root or /.sdb1root files present is the one true root filesystem from which the NSLU2 should be booting.

Upgrade Challenge #3

And of course, make sure you always check Unslung.KnownProblems for a list of any particular issues, problems, or other "bumps" in general that might also affect users who are upgrading.