New Plugger How To
So you just got a new Plug - what now? Hopefully this will help.
Contents |
Logging in to the existing Ubuntu install
The Plug comes with a prerelease install of Ubuntu 9.04 "Jaunty Jackalope".1 Using this install via ethernet is really easy:
- You must have a DHCP server on your network. If you are using a home router, you probably do.
- Connect the Plug to both ethernet and power. It will boot and acquire an IP address via DHCP after a few minutes.
- Check your DHCP logs to find out what IP address the Plug got.
- Now SSH to the Plug using its IP address. On Linux or Mac, just do "ssh root@<ip>" (where <ip> is the plug's IP address). On Windows, Putty is an excellent SSH client.
- Log in to the Plug as user root, with the password "nosoup4u" (without quotes).
NOTE: If you don't have a router or you can't access the DHCP logs, don't despair! You can still connect to the plug using the USB cable which comes with the development kit. To learn how to connect to the serial console, please visit the Serial terminal program page.
1 From Q3 2011 Dreamplug comes with Debian GNU/Linux 5.0 (Lenny) pre-installed.
Pause for a second
This is a ton of fun and lets you do quite a lot. In what follows there are a lot of directions to bring your Plug up to a fully usable state. As you play around you'll find various minor deficiencies and annoyances. When you consult the forums and other sources of information there's a lot of mention of the "Alpha-6" firmware. This now called "Installer Firmware" is a more up to date image for the Plug that fixes a lot of stuff, but installing it does erase everything on the Plug. So before you monkey around too much with it, you might want to get up on that new version. It involves some USB stick copying, some running of scripts on a Linux box, and some connection to the Plug using USB, so if that sounds a little too much, wait on it. Play with your nice Plug, enjoy it. Otherwise - you might find going to the "Installer firmware" is an awesome next step. The directions are in the SheevaPlug Installer page.
Fixing the existing Ubuntu install
There are some quirks and misconfigurations involved in the standard Ubuntu install. Here are some fixes you might want to make:
- The DHCP client is configured to ignore any DNS servers returned by the DHCP server and use 127.0.0.1 instead, while there is no local DNS server. Consequently, you won't be able to connect to any hosts by name until you fix this. In order to fix it:
- Edit /etc/dhcp3/dhclient.conf and comment out or delete the line "supersede domain-name-servers 127.0.0.1;".
- Run "dhclient eth0".
- Try "ping kernel.org" - it should work.
- The directory /var/cache/apt/archives/partial which the APT package management system uses lives on a RAM disk, so it gets wiped on every boot. Marvell helpfully included a boot script to recreate the directory, but they not so helpfully failed to make the boot script actually work. Additionally, /tmp and /var/tmp have invalid permissions. To fix these problems:
- Edit /etc/rc.local. The two insmod commands fail, and because the shell is invoked with the -e flag (see first line of the file), a failing command causes the whole script to exit. Delete or comment out all lines except "mkdir -p /var/cache/apt/archives/partial" and add "chmod 1777 /tmp /var/tmp" before the mkdir. You might also want to add, after the mkdir, a line "/usr/sbin/ntpdate-debian" to automatically sync your clock over the network.
- Alternatively, replace /etc/rc.local with the following text:
#!/bin/sh -e # # rc.local # # This script is executed at the end of each multiuser runlevel. # Make sure that the script will "exit 0" on success or any other # value on error. # # In order to enable or disable this script just change the execution # bits. # # By default this script does nothing. chmod 1777 /tmp /var/tmp mkdir -p /var/cache/apt/archives/partial # optionally uncomment the follwoing line to enable clock sync on reboot #ntpdate-debian
- After editing, run "/etc/rc.local" from the command line.
- The TimeZone is not set. To fix it, just execute the following command as root and select the appropriate timezone for you: "dpkg-reconfigure tzdata"
If you are unfamiliar with Linux, you probably want to use the editor "nano". To edit a file, just type "nano <filename>", without the quotes.
Upgrading the existing Ubuntu install
It's easy to upgrade, but it's worth being careful - it's possible to get into a state in which you can't log in, and it's not understood what triggers this state. It seems possible that changing the hostname before upgrading causes the problem. If you want to avoid the problem, it's probably best to change as little as possible before upgrading.
Note: as of 10/10/2010, UBUNTU has removed Jaunty from the main package repository site at ports.ubuntu.com. In order to use the following, you will need to edit the file /etc/apt/sources.list. Change the first (only) line in the file to:
- "deb http://old-releases.ubuntu.com/ubuntu jaunty main restricted universe multiverse"
To upgrade:
- Run "apt-get update". The list of upgraded packages will be downloaded.
- Run "apt-get dist-upgrade". Let it run through the upgrade process.
- Run "apt-get autoremove" to remove unneeded libraries.
- You may want to test making a new ssh connection (while leaving your existing connection in place) to make sure logging in still works. If not, it's going to be easier to try to fix now than after a reboot!
- Reboot.
CAUTION! You should not dist-upgrade to any Ubuntu release newer than Jaunty (as long as the ARM processor is not supported by them). (Read this forum post for more)
Adding software to the Plug
Software is easy to add, but be careful - the Plug still only has 512M of storage out of the box. The two commands that are most useful for installing software are:
- To install a package, run "apt-get install <software package name>"
- To find the name of a package, run "apt-cache search <thing to search for>"
- To save space after installing things, run "apt-get clean":
root@ubuntu:~# df -h . Filesystem Size Used Avail Use% Mounted on rootfs 462M 314M 144M 69% / root@ubuntu:~# apt-get clean root@ubuntu:~# df -h . Filesystem Size Used Avail Use% Mounted on rootfs 462M 211M 247M 47% /
- If you're new to Linux or just rusty or forgetful, you might care to install the helpful "command-not-found" utility. When you type a command that the system knows about but doesn't presently have installed, it says so and tells you how to install it. Run "apt-get install command-not-found". On a fairly fresh system this will consume approximately 12MB of additional space. Log out and back in to see it in action:
root@debian:~# java The program 'java' is currently not installed. You can install it by typing: apt-get install kaffe -bash: java: command not found
Adding a USB hard drive to the Plug
If you're adding a brand new unpartitioned drive to your plug, you'll need to partition and format it before you can store any data on it. Once your plug has booted, connect your new USB drive. You can use the lsusb command to list all connected usb devices. This list should include your new USB drive. The Linux Foundation and Genesys Logic hubs are built into the plug. Device 4 (JMicron) is my USB drive.
sheevaplug-debian:~# lsusb Bus 001 Device 004: ID 152d:2339 JMicron Technology Corp. / JMicron USA Technology Corp. Bus 001 Device 003: ID 05e3:0726 Genesys Logic, Inc. Bus 001 Device 002: ID 05e3:0608 Genesys Logic, Inc. USB-2.0 4-Port HUB [Hama] Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Note: if you do not have the lsusb command, you may need to do:
apt-get install usbutils
You should also be able to list all the disk devices by doing one of the following commands
ls /dev/disk/by-id ls /dev/disk/by-path ls /dev/disk/by-uuid
Next, you'll need to setup a new partition table. Use fdisk -l to list all connected drives. This will tell you where the new drive is located. In this case, the disk is located at /dev/sdc
sheevaplug-debian:~# fdisk -l Disk /dev/sdc: 2000.3 GB, 2000398934016 bytes 255 heads, 63 sectors/track, 243201 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Disk identifier: 0x00000000 Disk /dev/sdc doesn't contain a valid partition table
Setting up the new partition is fairly simple. Use fdisk to create a new partition on the disk. The options I chose here are n for creating a new partition, p for creating a primary partition and 1 for making it the 1st primary partition. To use the entire disk as one partition, select the defaults for first and last cylinder. Finally, use the w command to write the new partition to disk.
sheevaplug-debian:~# fdisk /dev/sdc Command (m for help): n Command action e extended p primary partition (1-4) p Partition number (1-4): 1 First cylinder (1-243201, default 1): Using default value 1 Last cylinder or +size or +sizeM or +sizeK (1-243201, default 243201): Using default value 243201 Command (m for help): w The partition table has been altered! Calling ioctl() to re-read partition table. Syncing disks.
Use mkfs.ext3 to format the new partition. Note, on a large disk this can take some time. For a 2TB disk the process took around 20 minutes to complete.
mkfs.ext3 /dev/sdc1
The last thing to do is create a folder where you want the drive to be mounted and mount it.
sheevaplug-debian:~# mkdir /data sheevaplug-debian:~# mount /dev/sdc1 /data sheevaplug-debian:~# df -h Filesystem Size Used Avail Use% Mounted on tmpfs 251M 0 251M 0% /lib/init/rw udev 10M 744K 9.3M 8% /dev tmpfs 251M 4.0K 251M 1% /dev/shm rootfs 463M 204M 260M 44% / tmpfs 251M 0 251M 0% /var/cache/apt /dev/sdc1 1.8T 196M 1.7T 1% /data
