== How does it work / architecture ==
Clients will boot from a read-only compressed file system (squashfs) which is
shared out by the server via nbd (network block device). A writeable overlay
directory is put on top of the squashfs using aufs ("another unionfs"). The
overlay directory is a NFS share exported by the server. Any changes you make
on the client are stored in that NFS share and are available across reboots.
The client can identify its overlay directory using the MAC address of the
network card which was used to boot the system.
The compressed file system is created using a plugin for ltsp-build-image
which adds the mythbuntu-specifics bits.
== Prerequisites ==
You need:
* a server. Any computer running hardy will do, but keep in mind that it should
be the same architecture as your client. While it's possible to generate a
diskless image on ppc for i386 clients, it won't be described here.
It's ok if your server is amd64, though.
* a DHCP server. This can be on the same computer as your server or on a
different box on your network. It's possible that you already have a DHCP
server on your network. If it's one of these SOHO routers/cable modems, you
need to make sure you can modify its configuration sufficiently. It's
probably easier to disable its dhcpd while you're testing.
As a special case, you can live without a (configurable) DHCP server if you
find a different way to load the kernel and its initramfs, eg using a USB pen
drive. However, this is not yet documented.
* a client. Any box capable of running mythfrontend should be OK. Having a lot
of RAM can be beneficial because swapping over network is slow. Network
swapping is enabled if you have less than 320M RAM. However, the default
configuration will not give you a lot of swap space.
Additionally, the client should be capable of booting over PXE. If your
network card does not support PXE, you can use etherboot (see below) to get
a PXE stack or a USB pen drive (or anything you can boot from) to bootstrap
your client.
* a fast internet connection or a local mirror which holds all relevant
packages. The build script downloads a lot of data.
== Getting started ==
Make yourself comfortable in front of your server.
* Install mythbuntu-diskless-server:
$ sudo aptitude install mythbuntu-diskless-server
This package will automatically pull in everything that's needed to build
the diskless image.
If you want to install a DHCP server as well, install
mythbuntu-diskless-server-standalone instead.
$ sudo apt-get install mythbuntu-diskless-server-standalone
We'll configure it later.
* Configure the overlay NFS export:
$ sudo dpkg-reconfigure mythbuntu-diskless-server
Answer both questions.
* Download an updated version of the mythbuntu-diskless LTSP plugin:
$ wget http://laga.ath.cx/030-mythbuntu
and copy it into the right place:
$ sudo cp 030-mythbuntu /usr/share/ltsp/plugins/ltsp-build-client/Ubuntu/030-mythbuntu
I realize it's unclean to overwrite files in /usr/share, but in this case
the update will also be shipped in the next LTSP upload. Consider it some kind
of time travel.
* Create the mythbuntu-diskless image
$ sudo ltsp-build-client --mythbuntu --mythbuntu-copy-user-credentials
This is going to take a while because it's downloading a lot of packages,
installing all of these packages into the chroot (usually /opt/ltsp/i386)
and turning the chroot into a compressed file system.
Make sure you read the output of
$ ltsp-build-client --extra--help
There are a lot of interesting options, eg --copy-sourceslist.
If your server is amd64 and your clients are i386, you should add
--arch i386 to the ltsp-build-client command line.
* Configure the DHCP server
If you installed mythbuntu-diskless-server-standalone, the configuration
file for your dhcpd is located at /etc/ltsp/dhcpd.conf.
Open this file in your favorite editor, eg
$ sudo editor /etc/ltsp/dhcpd.conf
and edit it to suit your network.
This step is a bit complicated. The Edubuntu people have some documentation
to help you understand what you want to do here:
http://doc.ubuntu.com/edubuntu/edubuntu/handbook/C/ch03s06.html
However, please note that mythbuntu-diskless, unlike Edubuntu,
will not detect and configure any unused interfaces automatically. This
part of the Edubuntu handbook does not apply.
If you want to use another computer on your network to handle DHCP requests,
you can find some example configuration files in
/usr/share/doc/ltsp-server/examples/. You might have to modify some entries
to point to your mythbuntu-diskless server.
In case you're using a SOHO router or any other setup, you'll have to figure
out how to configure it correctly. Be warned that it's probably impossible
to do that with some of these SOHO devices.
* Boot your client
You'll need to configure your client to use its PXE stack.
For devices with onboard network cards, the BIOS setup is usually the right
place to look. The same probably applies too regular PCI cards, too.
Some cards might require configuration using a card-specific utility,
although that's probably rare these days.
If you use etherboot, you'll need to configure your computer to boot from the
boot medium you've chosen.
Once you get to the login screen, you can log in using your user name and
password from your server (the one you were using when you built the image)
== Etherboot ==
See http://www.etherboot.org
If you'd like to generate an image, go to www.rom-o-matic.net,
select your network card, select your way of booting and dowload
the resulting file.
I'd probably for one of the "ISO bootable image" formats and put it
on a CD-RW for testing. "Floppy bootable ROM image" can also be a good choice
if you've still got a floppy disk. It's probably not the fastest method
of loading etherboot, but it's good for testing purposes.
== Cool! It works! What can I do now? ==
On the client:
* Watch TV
* run mythbuntu-control-centre and set up LIRC
* do anything else in mythbuntu-control-centre
* do _not_ install new packages.
It is certainly possible to install new
packages, but doing so means diverging from the original client environment.
It's better to install new packages on the server, see below.
There are a few exceptions to the rule: for some client-specific packages
like proprietary drivers which would conflict with other clients,
it is certainly acceptable to install these on the client.
On the server:
Switch to client environment first:
$ sudo chroot /opt/ltsp/i386
You probably also want to have /proc in there:
$ sudo mount -o bind /proc /opt/ltsp/i386/proc/
* Install additional packages:
# aptitude install your-package
* Update packages
# aptitude update && aptitude upgrade
aptitude safe-upgrade might be even better.
When you're done, type "exit" to exit the client environment.
* If you installed new packages, you have to update the compressed file system:
$ sudo ltsp-update-image
* If you only updated the kernel, run
$ sudo ltsp-update-kernels
== Help! It doesn't work! ==
+ Help! My client doesn't boot!
To find out why it's failing, you should edit
/var/lib/tftpboot/ltsp/i386/pxelinux.cfg/default on the server and remove
"quiet splash" from the kernel options.
Please gather as much information as possible and file a bug at
https://bugs.launchpad.net/ubuntu/+source/mythbuntu-diskless/
+ Help! My client doesn't start X correctly!
Bulletproof X should have avoided that. If it hasn't, there was probably
an error when creating the X config for your system.
On the server, you can review and modify the client's xorg.conf in
/var/cache/mythbuntu-diskless/overlay/$KEY/etc/X11/.
$KEY will usually be the MAC address of your client without colons.
+ Help! There was an error while running ltsp-build-client!
Please file a bug report at
https://bugs.launchpad.net/ubuntu/+source/mythbuntu-diskless/
and provide as much information as possible, including the exact error message.