New Plugger How To
From PlugWiki
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". 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 it's 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).
If you don't have a router, or you don't have access to the router's DHCP logs, it is also possible to login using the supplied USB cable:
- You will need a terminal emulation program. If you are using Windows XP (or earlier) you already have a program called HyperTerminal. If you are running Windows Vista or 7, or you simply can't find HyperTerminal, TeraTerm does the trick. On Linux, screen or minicom should work.
- When you connect the USB cable, the built-in USB-to-Serial device on the Plug should install automatically.
- You will need to configure your terminal program to use this new serial port. You will also need to configure these settings:
- Baud: 115200
- Data: 8 bit
- Parity: None
- Stop: 1 bit
- Flow control: None
- On linux if the plug is your only USB serial device, try: screen /dev/ttyUSB0 115200
- You may need to reboot the Plug a couple of times, or tell your terminal program to disconnect and connect again a couple of times before you see anything, but with a little bit of patience you should see a login prompt.
- As above, you can now log in to the Plug as root, with the password "nosoup4u" (without quotes).
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 here SheevaPlug_Installer
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. 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.
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
What's Next
The HowTo's are quite comprehensive:
