org.handhelds.familiar/packages/nslu2-binary-only/unslung-rootfs-2.3r63/NOTES

   1 Unslung-6.x Family Release Notes
   2
   3 Unslung is a replacement firmware image for the Linksys NSLU2 which is designed
   4 to allow you to make changes to the root filesystem (including the installation
   5 of downloadable packages) while still providing all the standard product
   6 functionality.
   7
   8 If, at any time, you have any questions concerning the installation or
   9 operation of Unslung firmware, your first port of call should be the
  10 NSLU2-Linux wiki at:
  11
  12         http://www.nslu2-linux.org
  13
  14 Specifically, check the HowTos and the Frequently Asked Questions before
  15 posting to the mailing list or asking a question in the IRC channel
  16 [#nslu2-general @ irc.freenode.net].
  17
  18 OK! Now that that's out of the way...
  19
  20 This file is provided to give general information and usage notes for the
  21 Unslung 6.x firmware.  If you are looking for installation instructions, please
  22 stop now and go to the README file.  Follow the README instructions WORD for
  23 WORD to keep from turning your NSLU2 into a brick.  The information contained
  24 in this file will make more sense if you have already "unslung" your NSLU2.
  25
  26 --------------------------------------------------------------------------------
  27
  28 These "Notes" are divided into four sections:
  29
  30      1 - GENERAL INFORMATION
  31      2 - IPKG PACKAGES
  32      3 - DIVERSION SCRIPTS
  33      4 - CHANGELOG
  34
  35
  36 GENERAL INFORMATION
  37
  38 As stated above, Unslung firmware is a replacement firmware image for the
  39 Linksys NSLU2.  The Unslung firmware is intended to be used for loading new
  40 packages (giving enhanced or additional functionality) with minimal changes
  41 to the standard user interface and firmware.  The differences in the Unslung 6.x
  42 firmware from the standard Linksys 2.3R63 firmware can be found at:
  43
  44         http://www.nslu2-linux.org/wiki/Unslung/UnslungFeatures
  45
  46 For more information about the Unslung firmware, including details on how to
  47 build it from source code yourself, look at:
  48
  49         http://www.nslu2-linux.org/wiki/Unslung
  50
  51 There are several assumptions made in this Notes.  One, you've successfully
  52 unslung your NSLU2, and can verify the basic Linksys functionality (samba
  53 users, groups, and shares setup with the Linksys interface).  Two, that you can
  54 get telnet or ssh shell access to your NSLU2 from any computer on the same
  55 network as the NSLU2.  Three, that you have read and understand the NSLU2-linux
  56 community rules at:
  57
  58      http://www.nslu2-linux.org/wiki/Main/HomePage
  59
  60 If you understand the third assumption, then you also understand that there is
  61 an emphasis on using and developing the NSLU2-Linux wiki.  Clarifications and
  62 further documentation is always welcomed on the wiki.
  63
  64 If you are experienced with the Linux operating system, then you can make
  65 changes directly to the root filesystem - changes which are persistent across
  66 reboot.  If you want to get involved, then check the NSLU2-linux wiki at:
  67
  68      http://www.nslu2-linux.org/wiki/Main/HowToGetInvolved
  69
  70
  71 IPKG PACKAGES
  72
  73 Packages require you to be running Unslung firmware (as you may have already
  74 guessed!)  In general, ipkg packages are commonly available software packages
  75 that have been ported to the NSLU2 - giving enhanced or additional
  76 functionality.  If you run into problems or have specific question with a
  77 certain package, you should look on the Internet for the general documentation
  78 about the package first.  If your problem is specific to the NSLU2 port, then
  79 check for further documentation for the corresponding package on the
  80 NSLU2-Linux wiki at:
  81
  82      http://www.nslu2-linux.org/wiki/Unslung/Packages
  83
  84 When you "unsling" an external disk (check the README for instructions),
  85 downloaded packages will be installed onto that external disk.  The number of
  86 packages that you can install is only limited by the size of the "data"
  87 partition on the external disk.  Note that you *must* *not* install any
  88 packages before you have booted with an external "Unslung" disk.  To do so will
  89 almost certainly cause your internal jffs2 flash memory become full, and cause
  90 you to have to reflash your NSLU2.
  91
  92 Package Installation Details
  93
  94      1) Check for network connectivity to the package repository from the NSLU2
  95           first:  "ping ipkg.nslu2-linux.org"
  96
  97           - If this does not work, then please check the NSLU2 DNS settings in
  98                the web interface (under "Administration", "LAN").
  99
 100      3) Update the list of available packages from new feeds:  "ipkg update"
 101
 102      4) Check the list of available packages for ones that you want on your
 103           NSLU2:  "ipkg list"
 104
 105      5) Install the packages:  "ipkg install <package-name>"
 106
 107 Most packages put their startup scripts into /opt/etc/init.d - which the
 108 Unslung firmware automatically runs at boot.  Some other packages are run from
 109 the cron or xinetd daemons.
 110
 111 You can also check the ipkg command arguments simply by typing "ipkg" at the
 112 prompt.
 113
 114
 115 DIVERSION SCRIPTS
 116
 117 Diversion scripts are used to start packages, set variables or function
 118 definitions at the time of the NSLU2 boot.  The diversion mechanism allows you
 119 to add to, or even replace the Linksys script functionality.  They "divert" the
 120 normal boot scripts to perform the needed action(s) and then can either "return
 121 1" to continue normal factory script progress or "return 0" to abort the
 122 diverted factory script.  The diversion of startup scripts is done at the
 123 lowest granularity, so you can just divert the rc.xinetd script and leave all
 124 others unchanged.  You are advised to use diversion scripts rather than editing
 125 system files directly (as this will allow you to upgrade the Unslung firmware
 126 in the future without having to make all of your changes again).
 127
 128      - Note:  If you do need to edit the system files directly, you can use the
 129           "resling" script to save and load your modified system files.  See
 130           the NSLU2-Linux wiki at:
 131
 132           http://www.nslu2-linux.org/wiki/Unslung/ReSling
 133
 134 Diversion scripts go in the /unslung directory (you may have to create that
 135 directory first).  Note that after you have unslung to an external disk, then
 136 the diversion scripts will be stored on that external disk (along with the rest
 137 of the root filesystem).  This means that recovering from an incorrect
 138 diversion script is as simple as powering off, unplugging the disk, powering
 139 on, hot-plugging the disk (note that the diversion scripts will only run if the
 140 disk is attached at boot), and fix or remove the diversion script.
 141
 142 You may divert as many or as few scripts as you like. Simply add the name of
 143 the standard rc script into the appropriate /unslung directory and it will be
 144 run.
 145
 146 For example, I have a script /unslung/rc.local:
 147
 148 #! /bin/sh
 149 /opt/bin/do_foo
 150 return 1
 151
 152 That will run at the beginning of the normal /etc/rc.d/rc.local, and then
 153 the rest of the factory rc.local will be executed.  If I do NOT want to run
 154 the factory rc.local, my script would be:
 155
 156 #!/bin/sh
 157 /opt/bin/do_foo
 158 return 0
 159
 160 That is, if the diversion script returns with something other than 0, it will
 161 run the rest of the factory script.
 162
 163 Note that any variable definitions or function declarations are allowed to
 164 happen before the diversion script is called.  This allows you to use the
 165 variables and functions defined by the factory script.
 166
 167 Also not that telnet is not enabled by default - there is an openssh package
 168 and a dropbear package that either can replace telnet access with secure shell
 169 access.
 170
 171      - Dropbear package details on NSLU2-Linux wiki at:
 172
 173           http://www.nslu2-linux.org/wiki/HowTo/UseDropBearForRemoteAccess
 174
 175 The rationale behind not enabling telnet by default is ensure that an Unslung
 176 NSLU2 has the same network footprint as a stock NSLU2 with Linksys firmware.
 177 That said, if you want to enable telnet on boot, then install the xinetd
 178 package (which enables telnet by default).
 179
 180
 181 CHANGELOG
 182
 183 1.11:
 184
 185 First public release
 186
 187 1.12:
 188
 189 Added a symlink to slingbox for gzip.  Added flashfs (as simple utility for
 190 preserving user files across hard disk formats during beta testing).
 191
 192 1.13:
 193
 194 Added LD_LIBRARY_PATH to /etc/profile (only works for telnet and ssh access,
 195 not for serial or diversion scripts).
 196
 197 1.14:
 198
 199 Added Unslung Doc link to the User Guide page.
 200
 201 2.3:
 202
 203 Moved development to OpenEmbedded.
 204
 205 2.4:
 206
 207 Updated to the latest ipk binary instead of the simple script.
 208
 209 2.5:
 210
 211 Added the real wget (instead of using the busybox version).  This is so we can
 212 support .netrc files for commercial packages.
 213
 214 2.6:
 215
 216 Fixed the unsling script so it removes conflicting files on an upgrade.
 217
 218 2.7:
 219
 220 Began development of the -able variant.
 221
 222 2.8:
 223
 224 Added the patch for genesys enclosures.
 225
 226 2.9:
 227
 228 Reorganized the various variants into a more consistent scheme.
 229
 230 2.10:
 231
 232 Added the ext3flash-on-disk1 functionality.
 233
 234 2.11:
 235
 236 Added the README to /opt/doc.
 237
 238 2.12:
 239
 240 First public release of 2.x firmware.
 241
 242 3.1:
 243
 244 Added jffs2 functionality.
 245
 246 3.2:
 247
 248 Incorporated switchbox functionality.
 249
 250 3.3:
 251
 252 Added ramdisks for /dev and /var to reduce internal flash writes.
 253
 254 3.4:
 255
 256 Replaced flashfs script with new resling script.
 257
 258 3.5:
 259
 260 Added code to reinitialize /etc/mtab on boot.
 261
 262 3.6:
 263
 264 Mounted /dev and /var jffs2 directories as /dev.state and /var.state so that
 265 they can be used for persistent changes which are used to populate the ramdisks
 266 on the next boot.
 267
 268 3.7:
 269
 270 Added "Pluggable Personalities" - now runs diversion scripts from both the
 271 internal jffs2 area and also from an external drive attached at boot time.
 272
 273 3.8:
 274
 275 Enabled mounting of external drives earlier in the boot process, so that the
 276 rc, rc.sysinit, and rc.1 scripts can be diverted by external diversion scripts
 277 on an attached drive.
 278
 279 3.9:
 280
 281 Moved a number of -able kernel features (such as USB devfs support) into
 282 -standard.
 283
 284 3.10:
 285
 286 Added support for unslung-start and unslung-stop diversion scripts, and package
 287 shutdown scripts (K??foo).
 288
 289 3.11:
 290
 291 Added NFS kernel support (both client and server, and both V2 and V3
 292 protocols).
 293
 294 3.12:
 295
 296 Added basic maintenance mode support.  If /.ramdisk exists in the jffs2
 297 filesystem, then the jffs2 filesystem is copied into a ramdisk on boot, and run
 298 from there.  This allows for updating firmware using the web interface.
 299
 300 3.13:
 301
 302 Added recovery mode support.  If a viable root filesystem cannot be found, then
 303 switchbox drops into a basic recovery shell, with a telnet daemon running as
 304 192.168.1.77 with no password.  This behavior can also be forced with a
 305 /.recovery file in the jffs2 filesystem.
 306
 307 3.14:
 308
 309 Added web control of maintenance mode.  You have to enable maintenance mode and
 310 reboot before the firmware upgrade page allows you to enter a filename for the
 311 new firmware.
 312
 313 3.15:
 314
 315 Added confirmation dialog boxes to the maintenance mode web control.
 316
 317 3.16:
 318
 319 First public release of 3.x firmware.
 320
 321 3.17:
 322
 323 Fixed syslog issue.  Added FP patches.
 324
 325 3.18:
 326
 327 Fixed a number of minor issues regarding file permissions.
 328 Added support for unslinging to the data partition.
 329
 330 4.1:
 331
 332 Split from 3.x stream to allow parallel development.
 333
 334 4.2:
 335
 336 New switchbox implementation with NFS and external USB disk root filesystem support.
 337
 338 4.3:
 339
 340 Enabled devfs.
 341
 342 4.4:
 343
 344 Changed slingbox program locations to match those of OpenSlug so that
 345 we can use the same switchbox for both.
 346
 347 4.5:
 348
 349 Enabled RAID support modules and USB camera support modules.
 350
 351 4.6:
 352
 353 Merged unslung-standard and unslung-able, and created the oe feed for
 354 downloadable kernel modules. Updated the unsling script to support
 355 external rootfs.
 356
 357 4.7:
 358
 359 Enabled lots of traffic shaping modules.  Enabled support for external
 360 disks on sda1, sda2, sdb1 and sdb2.
 361
 362 4.8:
 363
 364 Made Unslung *not* create ramdisk for /var and /dev when you've
 365 unslung to an external disk.  Fixed nsswitch.conf.  Updated the feed
 366 locations.  Added /dev/st devices for tape drive support.
 367
 368 4.9:
 369
 370 Updated the unslung script to give feedback on the rootfs transfer,
 371 and to preserve an existing upkg database on the target disk.  Added
 372 more device nodes to support the new downloadable kernel modules.
 373
 374 4.10:
 375
 376 Made Unslung wait until quota checking is complete before running
 377 package startup scripts.  Simplified unsling to support disk1 and
 378 disk2 (data partitions) only.
 379
 380 4.11:
 381
 382 Removed /tmp ramdisk if unslung to an external disk.  Now clears /tmp
 383 and /mnt/backup on each boot.
 384
 385 4.12:
 386
 387 Updated to the latest ipkg version.
 388
 389 4.13:
 390
 391 Added /dev/sdd and /dev/sde device nodes.
 392 Added support for alternate rootfs under expert user control.
 393
 394 4.14:
 395
 396 Added audio support to the kernel.  Increased the USB disk startup
 397 wait to 10 seconds, and added the ability to divert rc.bootbin to the
 398 startup scripts.
 399
 400 4.15:
 401
 402 Added /dev/dsp and updated the README and NOTES files.
 403
 404 4.16:
 405
 406 Added the /sbin/slingover script for migrating packages from the 3.x locations.
 407
 408 4.17:
 409
 410 Developer-only release booting straight from jffs2 instead of using switchbox.
 411
 412 4.18:
 413
 414 A number of /linuxrc fixes.  Removed support for alternate rootfs under expert
 415 user control (expert users can now just edit the /linuxrc in jffs2 directly).
 416
 417 4.19:
 418
 419 Removed all trace of switchbox from the firmware.  This saves 128Kb of flash,
 420 and about 1MB of RAM.
 421
 422 4.20:
 423
 424 First public release of 4.x firmware.
 425
 426 5.1:
 427
 428 Upgraded to Linksys firmware V2.3R29, but kept telnetd.
 429
 430 5.2:
 431
 432 Removed the ipkg link, and made unsling put it back on an external disk.
 433
 434 5.3:
 435
 436 Replaced maintenance mode with code to allow entry into RedBoot Upgrade Mode.
 437
 438 5.4:
 439
 440 Removed all maintenance mode support, and also removed support for rootfs on
 441 jffs2 but packages on external disk (it's either all or nothing).
 442 Removed unused /mnt/sda1, /mnt/sda2, /mnt/sdb1, and /mnt/sdb2.
 443 Disabled the download process (superceded by upgrade mode).
 444 Disabled the generation of the "ourtelnetrescue" user (too insecure).
 445 Added disk auto-wait countdown to /linuxrc (courtesy of glc).
 446
 447 5.5:
 448
 449 First public release of 5.x firmware.
 450
 451 6.0:
 452
 453 First alpha release of 6.x Unslung firmware, based on Linksys V2.3R63 firmware.