Drop well known password for root.
[freedombox/freedom-maker.git] / README
1 <!-- -*- mode: markdown; mode: auto-fill; fill-column: 80 -*- -->
2
3 # Freedom-Maker - Bdale's Building Tools for the FreedomBox Project
4
5 Welcome to the FreedomBox!  This project is the central hub of the FreedomBox
6 project, it builds and installs the file-system image that turns any computer
7 into a FreedomBox.
8
9 There are a couple ways to use this system:
10
11 1. If you just want to use a FreedomBox and don't care about changing
12    how it works or mucking about in its insides (if you're like most
13    people), you should use one of the pre-built systems we've already
14    put together.
15
16    If you don't have a DreamPlug or don't know what one is, make sure
17    to ask for a copy of the VirtualBox image.  If you do have a
18    DreamPlug, then you should get a pre-built image from someone and
19    copy it to an SD card or USB drive.  If you don't have a JTAG or
20    don't know what one is, make sure to ask for the SD card (not the
21    USB) version.
22
23 2. If you want to change and build on it, you can use:
24
25    A. A USB stick.  This requires a JTAG, but doesn't require opening up the
26       DreamPlug, or,
27
28    B. A microSD card and adapter.  You can use the one from inside the
29       DreamPlug.  You won't need a JTAG, but you will need to open the DreamPlug
30       and void the warranty.
31
32 # Warning!
33
34 There are no training wheels.  Read the scripts and understand what
35 they're going to do before you run them.
36
37 # Recent Firmware Necessary!
38
39 If you received your DreamPlug from GlobalScale during or after fall of 2012,
40 you probably don't need to reflash your DreamPlug and can try skipping directly
41 to the *To Use It* section.
42
43 Modern kernels need a relatively recent version of the u-boot firmware.  If
44 you still use old firmware (including what Global Scale ships on the units by
45 default), then you need to update, which requires having the JTAG dongle (to
46 gain console serial port access).  One way to know you've got old firmware
47 is if booting a Linux kernel results in errors about corrupt gzip data and
48 a failure to launch the kernel.
49
50 Note that re-flashing firmware will erase all configuration variables.  If
51 preserving your exising boot config is important, use printenv and make notes
52 before proceeding.  Also note that any time you're re-flashing boot firmware,
53 there is a slight chance you could 'brick' your device leaving it unbootable.
54 If that happens, the JTAG interface can be used to recover.  See the *Errors* ->
55 *Unbricking a DreamPlug* section of this document.
56
57 ## Updating DreamPlug's U-Boot
58
59 MAKE SURE YOU READ AND UNDERSTAND THIS SECTION IN ITS ENTIRETY BEFORE STARTING.
60
61 You can also review these instructions online:
62
63     http://wiki.debian.org/FreedomBox/Firmware
64
65 These instructions are from Ian Campbell, using uboot version 2012.04.01-2,
66 which is the current version in Debian's Wheezy release (as of December 12,
67 2012).
68
69 First, prepare your system::
70
71     # wget http://http.debian.net/debian/pool/main/u/u-boot/u-boot_2012.04.01-2_armel.deb
72     # dpkg-deb -x u-boot_2012.04.01-2_armel.deb u-boot_2012.04.01-2_armel
73     # cp -r u-boot_2012.04.01-2_armel/usr/lib/u-boot/dreamplug /mnt
74
75 Move the USB drive to your DreamPlug, and connect to your system via the JTAG
76 dongle.  Connect the UART DreamPlug port to the JTAG Board's UART port or
77 connect the JTAG DreamPlug port to the JTAG Board's JTAG port.  Next, plug the
78 USB cord into your main system and access the serial port with::
79
80     # screen /dev/ttyUSB0 115200
81
82 Now, interrupt the boot process.  You'll need to save your DreamPlug's Ethernet
83 interface MAC addresses because they'll be erased during the update and we'll
84 need to restore them at the end of the process.  If you don't save the MAC
85 addresses, the FreedomBox will automatically create random MAC addresses during
86 the box's first boot.  Letting the box set a random MAC address should be a last
87 resort, because those MAC addresses are unusual and can easily identify your
88 system as a FreedomBox.
89
90 To find the current MAC addresses, run:
91
92     > printenv
93
94 The MAC addresses will be on lines like these.  Save the whole line:
95
96     > ethaddr=F0:AD:4E:00:00:00
97     > eth1addr=F0:AD:4E:00:00:01
98
99 Now that you've recorded the MAC addresses for each interface, you need to write
100 the new uBoot file.  If you get to the "sf erase" step, *make sure to complete
101 the "sf write" step before turning off your plug.* If you turn off your plug
102 before finishing the write step, your plug will be unbootable.
103
104 Load and write the new bootloader:
105
106     > usb start
107     > fatload usb 2 0x6400000 dreamplug/u-boot.kwb
108     > sf probe 0
109     > sf erase 0x0 0x80000
110     > sf write 0x6400000 0x0 0xFILESIZE
111
112 You must, of course, fill in the size of u-boot.kwb file you're loading in hex.
113 Use this chart to determine what size to use for the last line:
114
115     | File Size | Code Line                      |
116     |-----------+--------------------------------|
117     |    196076 | sf write 0x6400000 0x0 0x2FDEC |
118
119 If your u-boot.kwb was 196076 bytes, the last command would look like:
120
121     > sf write 0x6400000 0x0 0x2FDEC
122
123 ### My File Size Isn't Listed!
124
125 If your file size isn't listed, we'll need to figure out what should go in the
126 last line manually.  To convert the file's size to hex, try entering the file
127 size in bytes (which you can get from running `ls -l u-boot.kwb` at a command
128 prompt) into the following search:
129
130     https://duckduckgo.com/?q=10 in hex
131
132 This handy table lists the file sizes for all versions we know of:
133
134     | Modification Date   | File Size | Hex Size | md5sum |
135     |---------------------+-----------+----------+--------|
136     | May 31, 2012, 21:19 |    196076 |    2FDEC | 4312c71b98049eab73332a3f283a1c5c
137
138 At this point, you should be able to reset the DreamPlug and have it boot to a
139 serial console prompt.  If that fails, you'll need real JTAG magic to try again.
140 That JTAG magic is described in the *Errors* -> *Unbricking a DreamPlug* section
141 at the end of this document.
142
143 Note that freedom-maker now includes DreamPlug firmware in the FAT partition on
144 USB stick targets.  To use a freedom-maker USB stick to update your u-boot,
145 ignore the instructions above about how to wget and extract the firmware, and
146 just connect to the DreamPlug and follow the bootloader instructions.
147
148 After you restore your microSD card to the DreamPlug, you should try booting it.
149 If the boot fails because of an "Invalid boot device", you'll need to interrupt
150 the boot process again to update the firmware with the settings described in the
151 *Errors* -> *Unbricking a DreamPlug* section, at the end of this document.
152
153 # To Use It
154
155 You'll need to copy the image to the memory card or USB stick:
156
157 1. Figure out which device your card actually is.
158
159    A. Unplug your card.
160
161    B. Run "df" to show you the list of devices your computer actually knows
162       about.
163
164    C. Plug your card in.
165
166    D. Run "df" again, your computer should know about a new device or two: your
167       memory card.  It's probably "/dev/sd(someletter)".  It *won't be*
168       /dev/sda.
169
170 2. Decompress the image:
171
172         $ tar -xjvf freedombox-unstable_*.tar.bz2
173
174 3. Copy the image to your card.  Whatever you do, make sure you don't copy it to
175    /dev/sda.  That'll break your system.
176
177         # dd bs=1M if=freedombox-unstable_*.img of=/dev/sd(thesameletter)
178
179    When picking a device, use the drive-letter destination, like /dev/sdb, not a
180    numbered destination, like /dev/sdb1.  The device-without-a-number refers to
181    the entire device, while the device-with-a-number refers to a specific
182    partition.  We want to use the whole device.
183
184 Now, what you need to do depends on whether you're using the microSD card or USB
185 stick method:
186
187 - USB drive: You'll hook the JTAG up to the DreamPlug before booting and use the
188   JTAG to control the boot process, so we can boot from the USB drive.
189
190 - microSD card: You'll put the microSD card into the DreamPlug's internal
191   microSD card slot and boot the DreamPlug.  It'll restart once to finish the
192   install process, then it's ready to use.
193
194 ## Running from a microSD Card
195
196 When DD has finished, take the microSD card out of your computer and plug it
197 into your DreamPlug.  If you have a JTAG, you can connect directly to the box to
198 watch it boot by running:
199
200     $ sudo screen /dev/ttyUSB0 115200
201
202 You'll see the DreamPlug restart once during the boot process.  If you don't
203 have a JTAG, wait a while (5 minutes or less) and it'll be available over SSH
204 (port 22).  You might need to use nmap to find it:
205
206     $ nmap -p 22 --open -sV 192.168.0.0/24
207
208     ...
209     Interesting ports on 192.168.0.13:
210     PORT   STATE SERVICE VERSION
211     22/tcp open  ssh     OpenSSH 6.0p1 Debian 2 (protocol 2.0)
212     Service Info: OS: Linux
213     ...
214
215 Once you've found it, SSH into the box:
216
217     $ ssh root@192.168.0.13
218
219 ## Running from a USB Stick
220
221 Move the USB stick to the DreamPlug, obtain a serial console, and hit reset.  A
222 good way to access the serial console (actually USB serial emulation provided by
223 the optional JTAG dongle), is to use 'screen', like so:
224
225     # sudo screen /dev/ttyUSB0 115200
226
227 If ``screen`` fails, see the *Errors* -> *Troubleshooting Screen* section at the
228 end of this document.
229
230 Interrupt the boot by pressing a key during the autoboot countdown, and type the
231 following to boot from the USB stick:
232
233     setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
234     setenv x_bootcmd_kernel fatload usb 2 0x6400000 uImage
235     setenv x_bootcmd_initrd fatload usb 2 0x6900000 uInitrd
236     setenv x_bootargs console=ttyS0,115200
237     setenv x_bootargs_root root=/dev/sdc2 rootdelay=10
238     boot
239
240 The system should boot to a login prompt, using only the bits on the stick.
241
242 The default root password is 'freedom'.  The normal user is "fbx" and the
243 password is "frdm".
244
245 - - - - -
246
247 If booting from the USB stick fails because u-boot in the Dreamplug doesn't
248 recognize the FAT partition on your stick, it may be because the partition
249 type code isn't one of the FAT variants that u-boot recognizes.  It's not
250 clear what the root cause is yet, but if this happens, plug the USB stick
251 into a Linux machine and use your favorite partition editor (fdisk works)
252 to change the type of partition 1 to something like '6' which is simple
253 FAT16, then write the change.  This won't change the *contents* of the
254 partition, but it may allow u-boot to recognize it.
255
256 - - - - -
257
258 To set things up to boot from the internal microSD card, once you're logged into
259 the system booted from root on USB stick you can use:
260
261     /usr/sbin/copy2dream
262
263 Note that if you don't have a reasonable system date and time set in the
264 DreamPlug before running this command, you may see a long stream of warnings
265 from tar about timestamps being in the future.  It is safe to ignore these.
266
267 After copy2dream completes, you may need to update /etc/fstab by hand since
268 copy2dream does not yet understand UUIDs in that file.
269
270 On reboot, you may want to interrupt the boot and type the following to ensure
271 you boot from the internal microSD by default.  This bootcmd line elides the
272 time-consuming attempts to boot from gigE, which makes boot go much faster.  If
273 you flashed the bootloader, you'll need to replace the *ethaddr* and *eth1addr*
274 lines with the MAC addresses you previously recorded.  If you didn't record MAC
275 addresses, completely exclude those two lines.
276
277     setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
278     setenv x_bootcmd_kernel fatload usb 0 0x6400000 uImage
279     setenv x_bootcmd_initrd fatload usb 0 0x6900000 uInitrd
280     setenv x_bootargs console=ttyS0,115200
281     setenv x_bootargs_root root=/dev/sda2 rootdelay=10
282     setenv ethaddr=F0:AD:4E:00:00:00
283     setenv eth1addr=F0:AD:4E:00:00:01
284     saveenv
285     reset
286
287 Congratulations, you're done!  To connect your DreamPlug to the Internet, plug
288 an Ethernet cord from the box's *eth0* port into your router.  The *eth0* port
289 is the inner Ethernet port.  To connect to the Internet through your DreamPlug,
290 plug your computer's Ethernet port into the box's eth1 port.  The *eth1* port is
291 the outer Ethernet port.
292
293 # To Make It
294
295 To build the image, download and install the dependencies for each of the images
296 you want to build.
297
298 Required for all images:
299
300     # apt-get -y install git python-docutils mktorrent vmdebootstrap dosfstools
301
302 Required for VirtualBox:
303
304     # apt-get -y install extlinux virtualbox
305
306 Required for RaspberryPi:
307
308     # apt-get -y install qemu-user-static binfmt-support
309
310 Required for DreamPlug:
311
312     # apt-get -y install qemu-user-static binfmt-support u-boot-tools
313
314 Now, fetch the git source of freedom-maker and build the image you want:
315
316     $ git clone http://anonscm.debian.org/git/freedombox/freedom-maker.git freedom-maker
317     $ make -C freedom-maker dreamplug-image raspberry-image virtualbox-image
318
319 If you only want one of the possible images of DreamPlug, RaspberryPi and
320 VirtualBox, remove the rest from the make command line.  The images will show up
321 in freedom-maker/build/.
322
323 *dd* the images to the SD card (for DreamPlug and RaspberryPi), or create a new
324 VM for the VirtualBox hard drive file, and boot the client.
325
326 # To Understand It
327
328 Be aware that this is a *very* imcomplete solution for now, suitable only
329 for developers .. you will want to at least do things like create unique
330 ssh host keys for your device!
331
332 Digging into the code should be fairly straightforward.  There are only six
333 files you need to be aware of:
334
335 - /Makefile: The makefile that describes and builds the system.
336 - /bin/mk_dreamplug_rootfs: Builds the DreamPlug's root file-system.
337 - /bin/mk_virtualbox_image: Builds the VirtualBox image.
338 - /source: The root file system.
339
340 ## Makefile
341
342 There are three major targets to be aware of:
343
344 - dreamplug-image: This builds an image for the DreamPlug's internal SD card.
345 - raspberry-image: This builds an image for the RasbperryPi's SD card.
346 - virtualbox-image: This builds an image for the VirtualBox virtualization tool.
347
348 ## /bin/mk_freedombox_image
349
350 Starts building the image by running vmdebootstrap.
351
352 ## /bin/mk_virtualbox_image
353
354 Adds FreedomBox specific customizations to the image.
355
356 # Errors
357
358 This section documents known errors with the process and what you can do about
359 them.
360
361 ## Invalid boot device
362
363 If, while booting your DreamPlug, you receive this error message:
364
365     2 Storage Device(s) found
366
367     ** Invalid boot device **
368
369     ** Invalid boot device **
370     Wrong Image Format for bootm command
371     ERROR: can't get kernel image!
372
373 Make sure you've updated your DreamPlug to boot from the internal microSD card.
374 You'll need to plug in the JTAG and interrupt the boot process to paste in these
375 commands:
376
377     setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
378     setenv x_bootcmd_kernel fatload usb 0 0x6400000 uImage
379     setenv x_bootcmd_initrd fatload usb 0 0x6900000 uInitrd
380     setenv x_bootargs console=ttyS0,115200
381     setenv x_bootargs_root root=/dev/sda2 rootdelay=10
382     saveenv
383     reset
384
385 ## Troubleshooting Screen
386
387 If screen fails when you're running:
388
389     $ sudo screen /dev/ttyUSB0 115200
390
391 First, verify that the ``usbserial`` module is loaded:
392
393     $ sudo modprobe usbserial
394     $ sudo lsmod | grep usbserial
395
396 Then, make sure your JTAG is plugged into both your DreamPlug and USB ports and
397 verify that you can access the ``/dev/ttyUSB0`` device:
398
399     $ sudo tail -f /dev/ttyUSB0
400
401 If that fails, you can try creating the device:
402
403     $ sudo mknod /dev/ttyUSB0 c 188 0
404
405 You may then be able to access the device via tail or screen.  If not, then
406 [DIYF](https://duckduckgo.com).
407
408 ## Unbricking a DreamPlug
409
410 You should first try to follow the
411 [simpler instructions from GlobalScale](https://code.google.com/p/dreamplug/downloads/detail?name=DreamPlug-Reflash%20uboot%20guide_%20Aug-28-2012.pdf&can=2&q=).
412 Search for the
413 "[Reflash uboot guide](https://code.google.com/p/dreamplug/downloads/list)" if
414 the link doesn't work.
415
416 If those instructions don't work, you should then try these instructions.
417
418 These instructions were copied and edited from:
419
420     https://www.newit.co.uk/forum/index.php?PHPSESSID=t9b8s83gen1h10m65p0s3q4md6&topic=2835.0
421
422 These instructions should get you from a Bricked DreamPlug to getting uboot
423 running in RAM ready to restore your system from USB/TFTP.  They should be used
424 if you erased your DreamPlug's bootloader and shut it off before writing the new
425 bootloader.
426
427 1. Edit your /etc/apt/sources.list to make sure you're using Wheezy or later.
428
429 2. First, install the required packages:
430
431         $ sudo apt-get install openocd telnet screen
432
433 3. Connect & Power up your device with the mini usb cable and JTAG.
434
435 4. Open a terminal session and connect to the plug console:
436
437         $ sudo screen /dev/ttyUSB0 115200
438
439 5. Open a 2nd terminal session.
440
441         $ wget http://www.downloadsnewit.co.uk/u-boot/recovery/dreamplug/u-boot.elf
442         $ sudo openocd -f /usr/share/openocd/scripts/board/sheevaplug.cfg -s /usr/share/openocd/scripts
443
444 6. You should see output similar to this:
445
446         Open On-Chip Debugger 0.4.0 (2010-10-08-15:52)
447         Licensed under GNU GPL v2
448         For bug reports, read
449            http://openocd.berlios.de/doc/doxygen/bugs.html
450         2000 kHz
451         trst_and_srst separate srst_gates_jtag trst_push_pull srst_open_drain
452         jtag_nsrst_delay: 200
453         jtag_ntrst_delay: 200
454         dcc downloads are enabled
455         Warn : use 'feroceon.cpu' as target identifier, not '0'
456         Info : clock speed 2000 kHz
457         Info : JTAG tap: feroceon.cpu tap/device found: 0x20a023d3 (mfg: 0x1e9, part: 0x0a02, ver: 0x2)
458         Info : Embedded ICE version 0
459         Info : feroceon.cpu: hardware has 1 breakpoint/watchpoint unit
460
461 7. If you are using a JTAG and getting errors at this point replug or even swap
462    JTAG cables and retry.
463
464 8. Next open a 3rd terminal session.
465
466         $ telnet localhost 4444
467
468 9. Output should look like this:
469
470         Trying ::1...
471         Trying 127.0.0.1...
472         Connected to localhost.
473         Escape character is '^]'.
474         Open On-Chip Debugger
475         >
476
477 10. Then, in that third seesion, run:
478
479         reset;sheevaplug_init;load_image u-boot.elf;resume 0x00600000
480
481 11. Now you should see Uboot starting to run in the 1st terminal session and you
482     are ready to start restoring your plug.
483
484 12. **DON'T turn off your DreamPlug.**  Follow the "Updating the DreamPlug's
485     U-Boot" instructions.