BabelBox: automated DebianInstaller testing and demo machine
This page is for historical purposes only. It is highly recommended to use the instructions from DebianInstaller/BabelBox which are considerably simpler and easy to setup
Babelbox is a system that is designed to demonstrate the automation capabilities of the Debian Installer. It focuses on the high number and quality of translations available for the installer. It is well suited to be used for a live demo on a booth in an expo or any other event.
For building Babelbox, two machines are needed:
- a boot server with a local mirror of Debian testing
- a demo machine being able to do PXE boot, with a BIOS allowing to set the boot order to PXE/hard disk. This machine will have its hard disk fully erased at each run.
An alternative setup based on the hd-media installation method is available from DebianInstaller/BabelBox. The advantage of that setup is that it only needs a single machine and can even be run without networking.
Note: the setup documented here has not been updated for some time and will probably need modifications before it will run.
General considerations about the demo machines
The boot server serves several purposes:
- DHCP/BOOTP server for answering the PXE boot requests from the demo machine
- TFTP server for the distribution of the netboot version of Debian installer
- WWW server for serving the few files needed at the end of the install on the demo server
- A FTP server or a web server for hosting and serving the local Debian mirror. This part is not mandatory as the files may be downloaded on Debian official mirrors if the demo machine is connected to the Internet. It is however highly recommended for speed issues as the
demo machine will download a big number of files from the mirror it uses. You should also avoid doing the demo on a connected network because it induces a rather high traffic.
- A DNS server for the mini-network used between the demo machine and the demo server. The server must be able to perform reverse DNS lookups on the demo machine when the demo machine will connect through SSH at the end of the install
- A local account is also needed which will be used for interactions between the demo machine and the boot server at the end of the installation
The demo machine
The only requirement for the demo machine is having enough hard disk space for a standard Debian desktop install (or the kind of install which will be automated). It must also have fully supported hardware requiring no special tweaking.
Details of the setup
The boot server must be connected directly to the demo machine by a private network. If it hosts a Debian mirror, there is not need for it to be connected on another network. In the example files, the boot server has the 192.168.142.1 address on the private network and the demo machine will have the 192.168.142.2 address.
Changing these addresses requires changing the logger script as well as the .ssh/known_hosts file in ssh-keys.tar.gz. You will also need to change the /var/www/babel/net.cfg file.
A local account with no special privileges must be created on the boot server. In the remaining of this document, this account is named "demo".
Be aware that you will give this account write access to the TFTP boot directory. You are thus advised to secure it properly. Anyway, you are strongly advised to have the demo running on an isolated network segment.
Untar the ssh-keys.tar.gz file in "demo" home directory. This will bring the correct authorized_keys file.
If you prefer, you may create your own keypair rather than using the one in the package file. Be aware to create it without passphrase and to put it in ssh-keys.tar.gz.
This local account will be used when the demo box will complete its install cycle. The SSH connection that is made at the end of the install uses this account to modify the PXELinux file on the fly. It will also be used or logging the demo box activities in a file on the boot server.
The DHCP server must be configured for delivering a dynamic address to the demo machine. It may be a fully dynamic server but be aware that it needs to point its clients to the TFTP server.
You are thus advised to restrict it to the demo machine in order to avoid booting the installer on every machine PXE booting on your network.
The example dhcp3.tar.gz file must be extracted in /etc/dhcp3 on the boot server. You must edit this file and put the correct MAC address for the demo server in the host babelbox section in this file.
The TFTP server must be able to boot Debian Installer. The following assumes that the tftpboot directory is /var/lib/tftpboot.
The following line should appear in inetd.conf:
tftp dgram udp wait root /usr/sbin/in.tftpd /usr/sbin/in.tftpd -u tftpd -s /var/lib/tftpboot
(the command line may vary, depending on the host system for the boot server)
The /var/lib/tftpboot directory must be writable by the local "demo" user.
The example tftpboot.tar.gz file must be extracted in /var/lib/tftpboot.
You must then add the kernel file and the initrd.gz file from a DebianInstaller netboot image. The kernel must be put as a file named linux in /var/lib/tftpboot and the initrd file must be named initrd.gz in the same directory.
The key file is the /var/lib/tftpboot/pxelinux.cfg/default file. The file provided in the tftpboot.tar.gz archive should fit most needs.
You may change the console-keymaps-at/keymap values in this file to the name of the keymap you want to use. This keymap MUST be supported in Debian Installer. You should choose the keymap suited for the keyboard you'll use on the demo machine.
Each entry must have a different "debian-installer/locale" value, suited for the relevant languages. This locale must be a valid locale. It is thus not recommended changing these values.
Create a text file of all languages for the demo, save it as "langlist" in the home directory of the demo user. A sample file with the DebianInstaller supported languages at the time of the first babelbox demo is given in the tftpboot.tar.gz file. A current limitation in the logger script (see below) requires avoiding duplicate entries for the same language (for instance, there should be zh_CN and zh_TW entries, or pt and pt_BR entries).
Define the first language entry on the "default" line in the TFTP "default" file.
Untar the content of the www.tar.gz file in the root of your web server. This will create a "babel/" directory there, with the needed files. Some may need to be edited to your needs. See below.
Also add the ssh-keys.tar.gz in the babel/files directory. This file should contain:
The SSH keypair is the one you have created previously. You can use the one offered here, or use your own keypair. The known_hosts file must contain the host public key of the boot server (you can create it by ssh'ing into it once from another machine). Of course, for this reason, you must regenerate ssh-keys.tar.gz.
Other files in babel/ are *.cfg files use for preseeding the installer. The main file in the example is bdesktop.cfg. If you prefer installing a base system instead of a full desktop system, a bbase.cfg file is also provided. You should then replace all occurrences of "bdesktop.cfg" by "bbase.cfg" in the pxelinux.cfg/default file.
Nothing special is needed here. The FTP server should host a full mirror for the architecture of the demo machine. Depending on the contents of the /var/www/babel/net.cfg file, it should contain a full mirror of testing or unstable. This mirror mustinclude the debian-installer section.
When the demo machine connects to the server by SSH, reverse DNS lookups are performed by the boot server. Thus, having a working reverse DNS helps speeding the connection here.
This page will soon provide an example BIND configuration file which serves this purpose.
Some tweaking is made in the postinstall.cfg file. Please read this file. It serves several purposes:
- have a localized GDM login screen. This is hacked by copying /etc/environment over /etc/default/gdm
- install the "logger" script which will connect to the boot server, switch the TFTP config file for the next language and write a log entry in the demo user home directory. This "logger" script need to be adapted to your local setup, especially the IP address of the boot server.
- erase the hard disk boot sector and reboot after a delay.
As all this must be done on the installed system and the postinstall.cfg is run from the DebianInstaller first stage, the trick is adding the required command in /etc/crontab on the installed system and have this run after some delay after the reboot.
Demo machine details
The demo machine must have a network card with PXE boot capabilities. You must setup the boot order of this machine to:
- hard disk
- PXE boot
- other boot
You must of course investigate the graphics card support. The provided files will overwrite the generated xorg.conf file by the file provided in www.tar.gz. You should then adapt this file to the demo machine.
Running the demo
At the beginning of the demo, the machine should not be able to boot on its hard disk. If a working operating system is installed (which is not a good idea as it will be erased by the demo), you must use its boot menu capabilities to force a PXE boot.
The machine will boot from the network, then receive the D-I kernel image and initrd from the TFTP server, and boot D-I.
The language, country, keyboard questions are preseeded from the kernel command line (see the TFTP default file), then the machine gets its IP address from the DHCP server and loads the preseeding files.
The first stage of the installer then runs automatically with nice localised messages showing up, the preseed/late_command from postinstall.cfg runs a command before the end of the installation and puts the required magic in the installed system /etc/crontab file. GRUB is installed at the end and the machine reboots.
The installed system boots up and reaches the GDM login screen (with a randomized theme, thanks to bug 351414). Then, after the delay defined in /etc/crontab by the preseed/late_command command from postinstall.cfg, the logger script connects to the demo server, switches the language for the next install, logs the new install in the demo user home directory and finally erases the hard disk first sector and reboots the system.
As the hard disk is not bootable anymore, the PXE boot starts again and the cycle continues...
The 2005 Babelbox demo featured an automatic opening of a Gnome session and a nice "welcome" message in the relevant language, contributed by the Debian Women project members and DebianInstaller translators.
This has been removed in the 2006 version because this required too much hacking for a not very spectacular effect (unless you boost the sound very loudly..which becomes quite annoying for other booths).
The original sounds are available in ChristianPerrier home page.
ssh-keys.tar.gz: SSH keys
dhcp3.tar.gz: DHCP daemon sample setup
tftpboot.tar.gz: contents of the tftpboot directory
www.tar.gz: contents of the /var/www directory
Many thanks to all people who helped setting up the first Babelbox demo at Solutions Linux, Paris 2005. Another Babelbox ran for Solutions Linux 2006, featuring the new graphical installer.
Special thanks to ONERA, the French Aerospace Lab, and François Mescam, my boss, for allowing me to use ONERA machines for the demo and spend some time in making it work.
Special thanks as well to all people who contributed the voices for the welcome messages in the 2005 Babelbox setup.
ChristianPerrier February 2005/February 2006