+UNSLUNG-3.x family release README
+
+Unslung is a replacement firmware image for the Linksys NSLU2 which is
+designed to allow you to make changes to the root filesystem
+(including the installation of downloadable packages) while still
+providing (almost) all the standard product functionality.
+
+This is intended to be a way of distributing and loading new packages
+for the NSLU2, with minimal changes to the standard user interface and
+firmware.
+
+The changes in the UNSLUNG 3.x firmware from the standard Linksys
+2.3R25 can be found at:
+
+ http://www.nslu2-linux.org/wiki/Unslung/UnslungStandard
+
+For more information about the Unslung firmware, including details on
+how to build it from source code yourself, look at:
+
+ http://www.nslu2-linux.org/wiki/Unslung
+
+PRE-INSTALLATION CONSIDERATIONS
+
+1) It is strongly recommended that you test telnet Redboot access
+ first. See http://www.nslu2-linux.org/wiki/HowTo/TelnetIntoRedBoot
+
+2) Because you can now make changes to the root filesystem in the
+ internal flash storage, you no longer need to have an external
+ disk to use the Unslung firmware (except if you want to install
+ more than what can fit in the meagre spare space in the internal
+ flash storage).
+
+3) If you do want to use an external disk as the target for package
+ installation, then it is absolutely required that the disk is (or has
+ previously been) formatted by the NSLU2. It is possible to upgrade
+ from Unslung 1.x or Unslung 2.x to Unslung 3.x without reformatting
+ your disk. 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
+ Unslung 1.x and Unslung 2.x :-)
+
+INSTALLATION DETAILS
+
+1) Make sure your NSLU2 is working properly, and remove any disks that
+ you may have plugged into the NSLU2 (upgrades must always be
+ performed with *no* hard disks or flash disks attached).
+
+2) If you are installing Unslung 3.x onto an NSLU2 unit which has the
+ standard Linksys firmware or Unslung versions 1.x or 2.x installed,
+ then just flash unslung-standard-3.x.img as you normally would
+ flash new firmware (using the web interface Upgrade Firmware page).
+
+3) If you are installing Unslung 3.x onto an NSLU2 unit which already
+ has Unslung version 3.x installed, then you must put the NSLU2 into
+ maintenance mode before you can use the web interface to flash a new
+ version. Just click the "Enter Maintenance Mode" link on the web
+ interface Upgrade Firmware page, wait for the NSLU2 to reboot, and
+ then you can flash the new firmware in the normal manner.
+
+4) Verify your NSLU2 is working normally at this point.
+
+5) Make sure that you do *not* have a disk plugged in when you reboot to
+ perform the next part of the installation.
+
+'UNSLINGING' DETAILS
+
+0) Note that this only has to be done when you update the firmware,
+ and because Unslung 3.x now runs completely from the internal flash
+ memory, it is no longer necessary to "unsling" to an external disk
+ unless you wish to store downloadable packages on that disk - which
+ you will probably want to do, because the internal flash memory
+ only has enough spare room to one or two very small packages.
+
+ Also note that you should not have a disk plugged in at this stage.
+
+1) Enable telnet by going to http://192.168.1.77/Management/telnet.cgi,
+ and press the enable button. Note that if you had previously changed
+ the IP address of your NSLU2 from 192.168.1.77 to something else, then
+ you should use that new IP address to enable telnet. Also note that
+ you should use the username "admin" and password "admin" for the web
+ interface at this point (as no disks are attached, the default
+ username and password is the only way to access the Management web
+ pages).
+
+2) Make sure you have **** NO DISKS ATTACHED AT THIS TIME ****
+
+ If you plug a disk in before you complete the telnet connection,
+ then the NSLU2 will pick up the Linksys password from the disk,
+ and you will not be able to telnet into it. So don't have any
+ disks attached at this point.
+
+ Make sure you have **** NO DISKS ATTACHED AT THIS TIME ****
+ (Sorry for the capitals, this step seems to trip up some people.)
+
+ OK, now that you don't have any disks attached, you can proceed and
+ telnet into the NSLU2 using the username root and password uNSLUng.
+
+3) Identify which drive you wish you "unsling", and plug it in.
+ Wait a minute or two while the disk is mounted. If the disk has not
+ been previously formatted on the NSLU2, then now is the time to do
+ that. Make sure that the drive is recognised in the web interface.
+
+4) In the telnet session, run "/sbin/unsling". Note that starting with
+ Unslung 3.x, the external disk is no longer used for the root
+ filesystem, so only a few documentation files will be copied to
+ the "conf" partition (not the "data" partition). Once you
+ "unsling" to an external disk on a particular port (Disk 1 or
+ Disk 2), it is important that you keep that disk continually
+ plugged into that same port whenever the NSLU2 is turned on.
+
+5) Note that unsling will not change the password on your disk, so if
+ you had previously changed the password on a disk, then your password
+ will not be changed.
+
+6) Reboot.
+
+Congratulations, you're now Unslung!
+
+Make sure you add an entry to the "The Unslung 3.x" table in the Yahoo
+group. Just use the next free integer for your Unslung number.
+
+If you make no further changes, your NSLU2 will continue to operate
+normally. But to customize things, you'll be downloading packages and
+adding stuff to the /unslung directory on the external disk (or even
+in the internal flash memory) using diversion scripts.
+
+If you "unsling" an external disk, then downloaded packages will be
+installed onto that external disk. The number of packages that you
+can install is only limited by the size of the "conf" partition on the
+external disk.
+
+If you are experienced with the Linux operating system, then you can
+also make changes directly to the root filesystem, and these changes
+are persistent across reboots.
+
+You are advised to use diversion scripts (see below) on an external
+disk to modify the behaviour of the NSLU2 rather than editing system
+files directly (as this will allow you to upgrade the Unslung firmware
+in the future without having to make all your changes again).
+
+If you do need to edit system files directly, then you can use the
+"resling" script to save and load your modified system files.
+
+POST-INSTALLATION DETAILS
+
+Diversion scripts go into /unslung (which is normally a symbolic link
+to the unslung directory on the conf partition of an external disk).
+You can divert as many or as few scripts as you like. Simply add the
+name of the standard rc script into /unslung and it will be run.
+
+For example, I have a script /unslung/rc.local:
+
+#! /bin/sh
+/opt/bin/do_foo
+return 1
+
+That will run at the beginning of the normal /etc/rc.d/rc.local, and then
+the rest of the factory rc.local will be executed. If I do NOT want to run
+the factory rc.local, my script would be
+
+#!/bin/sh
+/opt/bin/do_foo
+return 0
+
+That is, if the diversion script returns with something other than 0, it will
+run the rest of the factory script.
+
+Note that any variable definitions or function declarations are allowed to
+happen before the diversion script is called. This allows you to use the
+variables and functions defined by the factory script.
+
+PACKAGE INSTALLATION
+
+0) Note that you must have network connectivity to the package
+ repository at http://ipkg.nslu2-linux.org before proceeding.
+ You must also confirm that your DNS server address is set in the
+ web interface, or the NSLU2 will not be able to find the site.
+1) Run "ipkg update" on the NSLU2.
+2) Run "ipkg list" to see the available packages.
+3) Run "ipkg install <package-name>" to install them.
+
+ADDITIONAL INFORMATION:
+
+1) The unsling firmware and associated scripts will never touch any
+ files under /unslung or /opt, so please store all your additional
+ files there.
+
+2) The diversion of startup scripts is done at the lowest granularity,
+ so you can, for instance, just divert the rc.xinetd script if you
+ want, and leave all the others unchanged.
+
+3) The diversion mechanism allows you to add to, or replace, the Linksys
+ script functionality.
+
+4) Note that telnet is not enabled by default - there is an openssh
+ package available to replace telnet access with secure shell
+ access. The rationale behind not enabling it by default is to
+ ensure that an NSLU2 with Unslung firmware has the same network
+ footprint as the standard firmware.
+
+5) This simple diversion script will enable telnet on boot
+
+ [ Store the following in /unslung/rc.xinetd ]
+
+ #!/bin/sh
+ echo "telnet stream tcp nowait root /usr/sbin/telnetd" > /etc/inetd.conf
+ # Additional lines must append (using >>), ie:
+ # echo "ftp stream tcp nowait root /usr/sbin/ftpd -a=passwd" >> /etc/inetd.conf
+ return 1
+
+6) The Unslung firmware will automatically execute any scripts
+ which are in /opt/etc/init.d - and this is where any packages
+ put their startup scripts so that they execute on each boot.
+
+CHANGELOG:
+
+1.11:
+
+First public release
+
+1.12:
+
+Added a symlink to slingbox for gzip. Added flashfs (as simple utility for preserving
+user files across hard disk formats during beta testing).
+
+1.13:
+
+Added LD_LIBRARY_PATH to /etc/profile (only works for telnet and ssh
+access, not for serial or diversion scripts).
+
+1.14:
+
+Added Unslung Doc link to the User Guide page.
+
+2.3:
+
+Moved development to OpenEmbedded.
+
+2.4:
+
+Updated to the latest ipk binary instead of the simple script.
+
+2.5:
+
+Added the real wget (instead of using the busybox version). This is
+so we can support .netrc files for commercial packages.
+
+2.6:
+
+Fixed the unsling script so it removes conflicting files on an upgrade.
+
+2.7:
+
+Began development of the -able variant.
+
+2.8:
+
+Added the patch for genesys enclosures.
+
+2.9:
+
+Reorganised the various variants into a more consistent scheme.
+
+2.10:
+
+Added the ext3flash-on-disk1 functionality.
+
+2.11:
+
+Added the README to /opt/doc.
+
+2.12:
+
+First public release of 2.x firmware.
+
+3.1:
+
+Added jffs2 functionality.
+
+3.2:
+
+Incorporated switchbox functionality.
+
+3.3:
+
+Added ramdisks for /dev and /var to reduce internal flash writes.
+
+3.4:
+
+Replaced flashfs script with new resling script.
+
+3.5:
+
+Added code to reinitialise /etc/mtab on boot.
+
+3.6:
+
+Mounted /dev and /var jffs2 directories as /dev.state and /var.state
+so that they can be used for persistent changes which are used to
+populate the ramdisks on the next boot.
+
+3.7:
+
+Added "Pluggable Personalities" - now runs diversion scripts from both
+the internal jffs2 area and also from an external drive attached at
+boot time.
+
+3.8:
+
+Enabled mounting of external drives earlier in the boot process, so
+that the rc, rc.sysinit, and rc.1 scripts can be diverted by external
+diversion scripts on an attached drive.
git.openpandora.org / openembedded.git / commitdiff