NSLU2-Linux
view · edit · print · history

Suggested Changes to the README

This article pertains to:

  • Unslung 6.8

The README file (/opt/doc/README on an Unslung system) is incorporated into the Monotone repository, and should be used as a starting point for suggested changes. A copy can also be found at http://www.slug-firmware.net/

The NOTES file (/opt/doc/NOTES on an Unslung system) is considered to be initial "usage" notes for the Unslung firmware - "doco on the go." Please suggest changes for that documentation here as well.

Note: Thanks to those who have suggested changes to date -- your feedback is appreciated. The latest README has been updated with the suggestions that were previously added here.

All documents can be improved, and this page is a great place to help us make sure that the first experience new users have with Unslung is as positive as it can be. Your suggestions are needed - please add your suggested changes and corrections to this page. Thanks!

Please add new suggestions below this line, prefixed by a > so we can easily spot new suggestions and answer them, but before the next separation (----) so that what is being worked on will not be confused with new issues. Also state whether the suggested change is to NOTES or to README as shown below. Thank you for your suggestions.

>README - suggested change

Suggestion:

If someone can find the time to remove all obsolete information that no longer applies, then the documents will make some sense again. At the moment things are quite unusable. INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

<suggestion here> INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

<suggestion here> INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

It would be good if there were a list of available commands and switches, with explainations and examples, etc. INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

Readme Preinstall-4), Line 114 says the flash drive has to be at least 256MB in size if used to install packages, /wiki/WhichUSBPortforUnslung6 says "2# The root device must be 512MB or larger in size." None of them say how big it has to be without installing packages or whether unslung can be installed without installing packages (for the people not understanding the need for packages) INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

In step 4 it says "If the disk has not been previously formatted on the NSLU2, then now is 

          the time to do that."

It would be worthwhile being explicit about how to do that rather than assuming the user will know to use the web interface rather than that inviting telnet session...

INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

> First-time unslingers should NOT use -nopw

In the UNSLINGING DETAILS section of the README, it says "NOTE: There are two root passwords." and "Later in the process you can change both of them."

I decided to run /sbin/unsling with -nopw. I was happy with the default in /usr/local/passwd AND I KNEW that the external disk's password would be different. But the README line above led me to think it could be changed easily, and that the process would not let me reboot without knowing the appropriate password(s).

Of course, after rebooting with the external unslung disk attached, I couldn't telnet. http://www.nslu2-linux.org/wiki/FAQ/CantTelnetToMyNewlyUnslungNSLU2 is useless at this point. Eventually, I solved the problem by unslinging again WITHOUT -nopw.

I accept that using -nopw as a first-timer was a bit silly, but I thought the README would indicate AT THE APPROPRIATE TIME how to change the external disk's password. It doesn't. The 5.5 README had text at just the right point, but that text isn't present anymore. (5.5's UNSLINGING DETAILS section basically says "after unslinging, don't logout until you're sure you have got YOUR root password on the external disk", and references the CantTelnetToMyNewlyUnslungNSLU2 page.)

I think the README should 1) say first-timers have no reason AT ALL to use -nopw, and 2) reuse the dropped text from the 5.5 README.

INSERT YOUR SUGGESTION HERE!

>README - suggested change

Suggestion:

> In the README, /unslung and /opt warning unclear

For seasoned Unslung users the following warning (preinstallation step 3) might be meaningful 

  The unsling script will not touch anything in /unslung or /opt on your
  disk, so make sure all your file modifications are in those directories,
  as you were warned in the README file in all previous Unslung versions :-)

I believe it's rather cryptic. I would suggest it be a longer phrase like 

  Before unsling, the root of the harddisk contains a directory per user (and the "public" one).
  After unslinging, it also contains a copy of all the files/directories of the root file system
  (like bin, proc, sbin). Thirdly, it will contain the /opt and /unslung directory. Those will
  be used to install packages respectively diversion scripts (the two reasons why you would want
  Unslung). The unsling script will not touch the 1st and 3rd category files (user directories and
  /opt plus /unslung) but it will touch the 2nd (root file system files). So make sure your file
  modifications are in category 1 or 3, but not in 2 if you ever plan to re-unsling.

Suggestion:

>In the README, when checking if you are unslung

It may sound obvious, but when checking whether you are unslung, you may have to manually refresh the web GUI - just returning to the homepage won't necessarily work. Using IE, a simple F5 should suffice. The most reliable test is logging in via the telnet session. Enable telnet as before, and then use the password entered during the unsling process to login.

>NOTES - Suggested change

NSLU2 Users: Please do not modify information below this line, as it contains information for review by NSLU2 developers.

We have tried to make the README cover the most prevalent issues - emphasizing certain things so that newbies can follow the directions and have a usable Unslung NSLU2. We still expect you to be able to read documentation AND be familiar enough with the Linksys basic functionality to be running an Unslung NSLU2 without problems. Thank you for your suggestions to help make NSLU2-Linux documentation better.