summaryrefslogtreecommitdiff
path: root/packages/nslu2-binary-only/unslung-rootfs/README
blob: c750709e5fad55af1afe1c615b8e21b1bdeb38bf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
Unslung-6.x Family Release README INSTALLATION

You must follow the steps in this README *exactly*.  Do not skip any steps, and
do not skip ahead thinking you know what you are doing and don't need to follow
instructions step by step.

If at any time you have any questions concerning the installation or operation
of Unslung firmware, your first port of call should be the NSLU2-Linux wiki at:

     http://www.nslu2-linux.org

If you are looking for further Unslung notes - including ipkg usage, diversion
script details, or ChangeLog information, please consult the associated NOTES
file.

-------------------------------------------------------------------------------

There are three parts to completing the installation of the Unslung firmware:

     1 - PRE-INSTALLATION CONSIDERATIONS
     2 - FIRMWARE INSTALLATION DETAILS
     3 - UNSLINGING DETAILS


PRE-INSTALLATION CONSIDERATIONS

1) You *must* test telnet Redboot access first before you flash the Unslung
     firmware.  Failure to do so will mean you get no sympathy at all if you
     can't access Redboot when you need to recover from a bad flash.  See

     http://www.nslu2-linux.org/wiki/HowTo/TelnetIntoRedBoot

     - Redboot is the bootloader that runs when the device is first started,
          loading things into memory and starting Linux.  By testing your
          ability to telnet into Redboot, you are ensuring that if you injure
          your NSLU2 with a bad flash you should be able to follow the "How
          To Recover From A Bad Flash" instructions at

          http://www.nslu2-linux.org/wiki/HowTo/RecoverFromABadFlash

2) If you want to install any packages, then you must have an external disk.
     It is possible to make changes to the root filesystem in the internal
     flash storage, but the space is very limited.  In fact, just running
     "ipkg update" on an NSLU2 which does not have an external disk attached
     will most likely render the NSLU2 unusable due to filling up the flash (if
     this happens then you will need to follow the recovery instructions in
     the previous step).  So unless you are an expert, then use an external
     disk.

3) The external disk that you use as the target for package installation must
     be (or have previously been) formatted by the NSLU2.  It is possible to
     upgrade from all previous Unslung versions 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 all previous Unslung versions :-)

4) If you want to use a flash disk as the target for package installation,
     ensure that it is at least 256MB, plugged into port 1, and formatted
     via the Linksys web interface.

5) Please verify that any disks you are going to connect to the NSLU2 are
     recognized and working properly *before* updating your firmware (including
     any shares and data you had previously stored.)  If not, DO NOT CONTINUE.
     You may want to check out "How To Troubleshoot A Drive Missing Condition"
     at:

     http://www.nslu2-linux.org/wiki/HowTo/TroubleshootADriveMissingCondition

     - The only exception to this, of course, are those enclosures that the
          stock firmware does not support, but the Unslung firmware does
          support.

6) If you are upgrading your firmware, you should make a configuration backup
     via the Linksys web interface.  The configuration backup can be found
     under "Administration", "Advanced", and then "Backup."  The top section of
     that webpage is titled "Config Backup" and "Download" should be used to
     save your NSLU2 Users, Groups and Shares setup to a disk file.


FIRMWARE INSTALLATION DETAILS

1) Shutdown the NSLU2, and remove any disks that you may have plugged into the
     NSLU2.

     - Firmware upgrades must always be performed with *no* hard disks or flash
          disks attached.  This CANNOT be emphasized enough.  Are you sure you
          unplugged the disks before powering up?  If so, you may continue.

2-a) If you are installing Unslung 6.x onto an NSLU2 unit with Linksys standard
     firmware already installed, flash unslung-6.x.bin as you normally would
     flash new firmware (using the web interface "Upgrade Firmware" page).
     See your NSLU2 user manual for details if you don't know how to do this.

     - During firmware flashing, the top LED - Ready/Status - flashes red and
       green (approximately 5 minutes, but can be much longer).  

     - The NSLU2 will reboot after the flashing is complete.

2-b) If you are installing Unslung 6.x onto an NSLU2 unit with an existing
     version of nslu2-linux.org firmware already installed, you must first put
     the NSLU2 into RedBoot Upgrade Mode.

     - The NSLU2 should still be powered off at this point.  If not, shut it
       down again before proceeding.
     - Using a paper clip, push and hold in the reset button which is located
       on the back of the NSLU2 near the power socket.
     - While holding in the reset button, press and release the power button.
     - Watch the Ready/Status LED and as soon as it turns red, then quickly
       release the reset button.
     - You should now be in upgrade mode which is indicated by the Ready/Status
       LED alternating between red and green. 
     - Use either the Linux UpSlug tool or the Windows SerComm Upgrade tool to
       upload the new firmware - you can find download links at

	    http://www.nslu2-linux.org/wiki/HowTo/InstallUnslungFirmware

     - During firmware flashing, the top LED - Ready/Status - flashes red and
       green (approximately 5 minutes, but can be much longer).  

     - The NSLU2 will reboot after the flashing is complete.

3) Shutdown the NSLU2 (again), attach disk(s), and power it back up.

4) Verify your NSLU2 is working normally again at this point in the web
     interface.  In  particular, you should ensure that all your disks are still
     recognized as they were before you updated the firmware (including any
     shares and data you had previously stored.)  If not, DO NOT CONTINUE.
     You may want to check out "How To Troubleshoot A Drive Missing Condition"
     at:

     http://www.nslu2-linux.org/wiki/HowTo/TroubleshootADriveMissingCondition

     - If you are not "unslinging", you can stop at this point.  *HOWEVER!*,   
          the only reason for not unslinging would be in the case of a re-flash
          of the SAME firmware.  Even if this is a point firmware upgrade, you
          will need to unsling.

     ***** If you do not choose to do the unslinging procedure described below,
          DO NOT install packages unless you are SURE you know what you are
          doing!  "Bricking" your NSLU2 by not unslinging and then running ipkg
          is not just a possibility, it is a certainty.

5) Shutdown the NSLU2 and unplug *ALL* attached disks.

     - You must NOT have any disk plugged into the NSLU2 when you reboot to
          perform the next part of installation - the "Unslinging".


'UNSLINGING' DETAILS

"Unslinging" is the process of copying the root filesystem of your NSLU2 onto
an external disk, and configuring that external disk for installation of
packages. Basically it's a script (stored in /sbin/unsling) which copies all
the files from the internal jffs2 filesystem onto the external disk and tells
the internal firmware to load the root filesystem from the external disk when
booting in the future.

To run the unsling-script you have to be logged in as root (with a telnet
session).

NOTE:  There are two root-passwords.  One is saved in a internal file called
/usr/local/passwd (we know this one - it's "uNSLUng" and used when you boot
without a attached harddisk) the other is stored in a external file called
/share/hdd/conf/passwd (we don't know this one - it's used when you boot with a
external harddisk attached).  Later in the process you can change both of
them. That means:  Everytime you boot WITHOUT a attached harddisk you gain
root-access with the "uNSLUng" password.  If you boot WITH an attached harddisk,
you won't have access until you change the file /share/hdd/conf/passwd.

1) Power up the NSLU2 without any disks connected.

     - This only has to be done when you update the firmware.

     ***** To reiterate, you should not have a disk plugged in at this stage.
          If you powered up your NSLU2 with a disk attached, shutdown the
          NSLU2, unplug the disks, and power up again.

2) Enable telnet by going to "http://192.168.1.77/Management/telnet.cgi", and
     press the enable button.

     - 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.  Again 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).

     - 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 ****

3) 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.

     - If you are upgrading from a previous release of Unslung, please read

     http://www.nslu2-linux.org/wiki/Unslung/UpgradingToUnslung6

4) Identify which drive you wish you "unsling", and plug it in.  Note that for
     Unslung 6.x it is recommended that you plug the target disk into the Disk2
     port so that you can use the Disk1 port for attaching multiple ext3 and/or
     NTFS data disks via a USB hub.  For more information, see

     http://www.nslu2-linux.org/wiki/Unslung/WhichUSBPortforUnslung6

     Wait a minute or two while the disk is mounted.  Check the web
     interface to make sure that the disk has been recognised by the
     Linksys software.

     - 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 recognized in the
          web interface.

5) In the telnet session, run "/sbin/unsling disk1" or "/sbin/unsling disk2"
     (depending upon whether you want to unsling to a disk connected to the
     Disk1 port or the Disk2 port).  Again, we recommend for Unslung 6.x that
     you unsling to disk2.

     - 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.

     ***** 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.  Also note that simply editing the /etc/passwd file
          is not enough to permanently change a password.  See:
         
     http://www.nslu2-linux.org/wiki/HowTo/ChangePasswordsFromTheCommandLine

     NOTE: There are two root-passwords.  One is saved in a internal
          file called /usr/local/passwd (we know this one - it's "uNSLUng"
          and used when you boot without a attached harddisk) the other is
          stored in a external file called /share/hdd/conf/passwd (we don't
          know this one - it's used when you boot with a external harddisk
          attached).  That means: Everytime you boot WITHOUT a attached harddisk
          you gain root-access with the "uNSLUng" password.  If you boot
          WITH an attached harddisk, you won't have access until you change
          the file /share/hdd/conf/passwd.  So you should change this file
	  as soon as you unsling to an external disk, before you exit the
	  telnet session that you are using to unsling to the disk.

6) If you wish to migrate your packages from the old Unslung 3.x location in
     the /share/hdd/conf (disk1) or /share/flash/conf (disk2) partitions to the
     new Unslung 4.x, 5.x and 6.x location on the data partition, then run:  
     "/sbin/slingover disk1" (if your packages were previously on disk1 and you
     ran "/sbin/unsling disk1" in step 5) or "/sbin/slingover disk2" (if your
     packages were previously on disk2 and you ran "/sbin/unsling disk2" in
     step 5).

     - If your packages were not stored in /share/hdd/conf or /share/flash/conf
          (e.g. you had previously moved your packages from the conf partition
          to the data partition), then all bets are off and you will need to
          read the /sbin/slingover script and perform the appropriate steps
          manually.

7) Reboot.

     ***** DO NOT RUN ipkg BEFORE YOU REBOOT AND CONFIRM EXTERNAL ROOTFS *****

     - If you were to run ipkg when the root filesystem is loaded from the
          internal jffs2 filesystem, then you would fill the flash and cause
          your NSLU2 to no longer boot and require reflashing to recover.

8) Wait for the NSLU2 to boot, telnet in, and confirm that the root filesystem
     is being loaded from the external disk.

***** Congratulations, you're now Unslung! *****

Make sure you add an entry to the "The Unslung 6.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 using diversion scripts.

Read the NOTES file to expand the capabilities of your Unslung NSLU2!

Enjoy!