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