Differences between revisions 1 and 2
Revision 1 as of 2006-02-05 07:58:42
Size: 12531
Comment: create the Wiki page
Revision 2 as of 2006-02-05 08:26:50
Size: 9662
Comment: Big changes for the first version
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
BabelBox : an automated Debian Installer testing and demo machine
-----------------------------------------------------------------
= BabelBox : an automated DebianInstaller testing and demo machine =
Line 4: Line 3:
Principles:
----------
== Principles ==
Line 8: Line 6:
of the new installer software for Debian "sarge". of the Debian installer.
Line 10: Line 8:
It also enhances the high number and the quality of translation It also enhances the high number and the quality of translations
Line 15: Line 13:
-a DHCP/TFTP/WWW 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
 * a DHCP/TFTP/WWW 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
Line 19: Line 16:
The boot server
--------------
== The boot server ==
Line 24: Line 20:
-DHCP/BOOTP server for answering the PXE boot requests from the demo
machine
 * DHCP/BOOTP server for answering the PXE boot requests from the demo machine
Line 27: Line 22:
-TFTP server for the distribution of the netboot version of Debian
installer
 * TFTP server for the distribution of the netboot version of Debian installer
Line 30: Line 24:
-WWW server for serving the few files needed at the end of the install  * WWW server for serving the few files needed at the end of the install
Line 33: Line 27:
-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 connecteto 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 making the demo on a connected network.
 * 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.
Line 40: Line 30:
-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
 * 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
Line 43: Line 32:
The demo machine
----------------
 * 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
Line 46: Line 34:
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 autoimated). It must also have fully supported hardware
requiring no special tweaking.
== 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.
Line 52: Line 39:
The boot server - details
-------------------------
== The boot server ==
Line 55: Line 41:
 Local user
 ----------
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".
=== Local user ===
Line 61: Line 43:
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.
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".
Line 66: Line 45:
Pick up the SSH DSA keypair with no passphrase you'll find in
ssh-keys.tar.gz you'll find in babel-www.tar.gz and put its public
part in ~/.ssh/authorized_keys in the demo user home directory. Beware
the ~/.ssh must be 0700 and authorized_keys must be 0600.
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.
Line 71: Line 47:
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 babel/files/ssh-keys.tar.gz.
Pick up the SSH DSA keypair with no passphrase you'll find in ssh-keys.tar.gz you'll find in babel-www.tar.gz and put its public part in ~/.ssh/authorized_keys in the demo user home directory. Beware the ~/.ssh must be 0700 and authorized_keys must be 0600.
Line 75: Line 49:
This local account will be used when the demo box will complete its
install cycle. It will then SSH to the boot server and modify the
PXELinux file on the fly. This account will also be used for logging the demo box activities in a file on the boot server.
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 babel/files/ssh-keys.tar.gz.
Line 79: Line 51:
 DHCP server
 -----------
This local account will be used when the demo box will complete its install cycle. It will then SSH to the boot server and modify the PXELinux file on the fly. This account will also be used for logging the demo box activities in a file on the boot server.
Line 82: Line 53:
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.
=== DHCP server ===
Line 86: Line 55:
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 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.
Line 90: Line 57:
See the dhcp3.tar.gz file for the setup I used for the demo. 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.
Line 92: Line 59:
See the dhcp3.tar.gz file for the setup used for the demo.
Line 93: Line 61:
 TFTP server
----------
=== TFTP server ===
Line 96: Line 63:
The TFTP server must be able to boot Debian Installer. The Debian Installer
teams recommends using tftpd-hpa.
The TFTP server must be able to boot Debian Installer.
Line 108: Line 74:
image. Grab the netboot.tar.gz file from the Debian Installer pages
(
http://www.debian.org/devel/debian-installer) and untar it in this
directory.
image. Grab the netboot.tar.gz file from the [http://www.debian.org/devel/debian-installer Debian Installer pages] and untar it in this directory.
Line 113: Line 77:
Shorten the initrd image name as mush as possible (my example used "26.gz") so that the kernel command line space is not eaten. Shorten the initrd image name as much as possible so that the kernel command line space is not eaten.
Line 115: Line 79:
   Modifications to the /var/lib/tftpboot directory
   ------------------------------------------------
The pxelinux.cfg directory needs some tweaking. First create one default file with an entry named "babel-xx" for each language you wish to have the demo running with.
Line 118: Line 81:
The pxelinux.cfg directory needs some tweaking. First create one
default file with an entry named "desktop-xx" for each language you
wish to have the demo running with.
An example of this file is given in tftpboot.tar.gz in the babelbox distribution.
Line 122: Line 83:
An example of this file is given in tftpboot.tar.gz in the babelbox
distribution.
You may change the console-keymaps-at/keymap values 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.
Line 125: Line 85:
In this file, you may change countrychooser/shortlist for the country
of your choice. Use the ISO-3166 code of that country. You may use a
different country for each language but there's indeed no real point
in that.

Similarly, you may change the console-keymaps-at/keymap value to the
name of the keymap you want to use. This keymap MUST be supported in
Debian Installer. I suggest you choose the keymap for they keyboard
you'll use on the demo machine.

From one entry to another, the only changing value is the value of
"languagechooser/language-name". It MUST contain the English name of
the language EXACTLY SPELLED as it is in languagechooser. If you
supply an invalid value here, the demo will fail. If this language
name includes a space ("Norwegian Bokmal"), use quotes. Please note
that the use of quotes with 2.6 kernels is NOT supported. So, for such
languages, you MUST use a 2.4 kernel (you may use a 2.4 kernel
everywhere...I used a 2.6 kernel for the first babelbox demo but this
does not seem to be mandatory).

Again, be aware that the kernel command line length is LIMITED. The
entries in the example "default" file use it nearly completely, so
shorten everything that you can shorten (just remember the obfuscated
code contests...:-)).
Each entry must have a different "debian-installer/locale" value, suited for the relevant languages.
Line 152: Line 89:
the 39 D-I supported languages at the time of the first babelbox demo the DebiaInstaller supported languages at the time of the first babelbox demo
Line 155: Line 92:
Define the first language entry on the "default" line in the TFTP
"default" file.
Define the first language entry on the "default" line in the TFTP "default" file.
Line 158: Line 94:
 WWW server
----------
=== WWW server ===
Line 168: Line 103:
.ssh/id_dsa
.ssh/id_dsa.pub
.ssh/known_hosts
 * .ssh/id_dsa
 * .ssh/id_dsa.pub
 * .ssh/known_hosts
Line 172: Line 107:
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).
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).
Line 177: Line 110:
installer. The main file in my example is "bb.cfg". installer. The main file in the example is "bdesktop.cfg".
Line 179: Line 112:
Some other files in babel/files are custom packages I used during the
demo. See below for details. The APT packages should not be needed
anymore as they were used for circumventing a nasty bug in APT which
has been fixed since then.
==== The postinstall file : the GORY part ====
Line 184: Line 114:
The preinstall/postinstall file : the GORY part !
-------------------------------------------------
Some tweaking is made in the postinstall.cfg
file. Please read this file. It serves several purposes:
Line 187: Line 117:
Some tweaking is made in preinstall.cfg and postinstall.cfg
files. Please read these files and try understanding the magic I am
doing here..:-). There were several purposes:
 * have a localized GDM login screen. This is hacked by copying /etc/environment over /etc/default/gdm
Line 191: Line 119:
-have the "desktop" task work and be preseeded in the localized
 environments. I had to apply a patch to tasksel for that to
 workaround #278186. This bug should be fixed now and this may not more
 be needed. I've left it just in case. The APT packages were also locally built
 packages. They should not be needed anymore.

-have the sound work after the install. This is HIGHLY TRICKY. Please
 read the gory script in postinstall.cfg and try to get the
 point. Basically, this is about getting ALSA work without reboot and
 autoconfigured for your sound card. My script installs a few files
 which depend on the sound card I had for the babelbox demo. So you may
 have to change these files. Good luck..:-). You may contact Thomas
 Hood for help about that part.

-setup GDM for autologin the demo user (this is the "edit-on-the-fly"
 hack at the beginning of the postinstall.cfg file. Please don't
 laugh...)

-have a working sound for the Gnome session of the demo user and use
 /usr/share/sounds/welcome.wav files as the session welcome sound. This
 is why I untar a sample home directory for this user. This is also why
 I wget the welcome file from the boot server (the former install did
 set a symlink for it)

 The sound part is by far the worst horrible hack I've ever made. I'm
 pretty sure that a lot of clean enhancements can be made to it.


-install the "logger" script which will connect to the boot server,
 switch the TFTP config file for the next language, write a log entry
 somewhere, link the next sound file.

 This "logger" script need to be adapted to your local setup, especially the
 * 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
Line 226: Line 123:
-finally erase the hard disk boot sector and reboot after a delay.  * erase the hard disk boot sector and reboot after a delay.
Line 228: Line 125:
As all this must be done on the installed system and the postinstall.cfg is run from the DebiaInstaller first stage, the trick is adding the required comment in /etc/crontab on the installed system and have this run after some delay after the reboot.
Line 229: Line 127:
The demo machine setup
----------------------
=== The demo machine setup ===
Line 232: Line 129:
The demo machine must have a network card with PXE boot
capabiulities. You must setup the boot order of this machine to:
The demo machine must have a network card with PXE boot capabilities. You must setup the boot order of this machine to:
Line 235: Line 131:
-hard disk
-PXE boot
-other boot
 * hard disk
 * PXE boot
 * other boot
Line 239: Line 135:
You must of course investigate the graphics card support in case the
installer and subsequent X install do not properly set it up.
You must of course investigate the graphics card support in case the installer and subsequent X install do not properly set it up.
Line 242: Line 137:
A sound card adds the nice feature of getting a beautiful message at
the opening of the Gnome session.....provided you manage to get sound
working (see the gory details above).


The demo cycle
--------------
== The demo cycle ==
Line 261: Line 150:
The first stage of the installer later runs automatically with nice
localised messages showing up, GRUB is installed at the end and the
machine reboots.
The first stage of the installer then runs automatically with nice
localised messages showing up, the postinstall.cfg file 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.
Line 265: Line 153:
As the boot from hard disk comes first, the D-I second stage runs
automatically. There is no real fancy display here except long and
boring display from APT and dpkg. So, for languages which do not have
a dpkg and apt translation, the display is just English...

At the end of that (maybe long) part, GDM opens up....waits for a few
dozens seconds (see postinstall.cfg) and then opens a Gnome
session. If the sound is working you will then hear a message saying
"Hello and welcome to your new Debian system in <language>", of course
with the installation language.

The session remains opened for a few minutes (see postinstall.cfg for
setting up the delay), then the hard disk first sector is erased and
The installed system boots up and reaches the GDM login screen (with a randomized theme). Then, after the delay defined in /etc/crontab by the postinstall.cfg file, the logger scripts connects to the demo server, switches the language for the next install, logs the new install and finally the hard disk first sector is erased and
Line 281: Line 157:
and here you are... and the cycle  continues...
Line 283: Line 159:
Sounds
------
=== Sounds ===
Line 286: Line 161:
The "welcome" sounds should be put in "babel/welcome" on the WWW
server. They should be named "welcome-xx.wav" where "xx" is the
languages ISO-639 code. You should use "pt_BR, zh_CN and zh_TW" for
these specific languages.
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.
Line 291: Line 163:
The voices have been contributed by several people around the world.
This project has been orginally proposed to the debian-women project
which explains why about half of the voices are women voices. Just
another way to promote gender equity in free software...:-)
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).
Line 296: Line 165:
More voices have been "collected" during this project. You will find
all voices at http://www.perrier.eu.org/debian/voices/
The original sounds are available in ChristianPerrier [http://www.perrier.eu.org/debian/voices home page].
Line 299: Line 167:
Thanks
------
== Thanks ==
Line 303: Line 170:
demo at Solutions Linux, Paris 2005. demo at Solutions Linux, Paris 2005. Another Babelbox ran for Solutions Linux 2006, featuring the new graphical installer.
Line 305: Line 172:
Special thanks to ONERA, the French Aeronautics and Space Research
Center, and François Mescam, my boss, for allowing me to use its
machines for the demo and spend some time in making it work.
Special thanks to ONERA, the French Aeronautics and Space Research Center, and François Mescam, my boss, for allowing me to use its machines for the demo and spend some time in making it work.
Line 309: Line 174:
Special thanks as well to all people who contributed the voices for
the welcome message.
Special thanks as well to all people who contributed the voices for the welcome messages in the 2005 Babelbox setup.

BabelBox : an automated DebianInstaller testing and demo machine

Principles

Babelbox is a system aimed at demonstrating the automation capabilities of the Debian installer.

It also enhances the high number and the quality of translations currently available for this installer.

For building Babelbox, two machines are needed:

  • a DHCP/TFTP/WWW 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

The boot server

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.

The boot server

Local user

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.

Pick up the SSH DSA keypair with no passphrase you'll find in ssh-keys.tar.gz you'll find in babel-www.tar.gz and put its public part in ~/.ssh/authorized_keys in the demo user home directory. Beware the ~/.ssh must be 0700 and authorized_keys must be 0600.

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 babel/files/ssh-keys.tar.gz.

This local account will be used when the demo box will complete its install cycle. It will then SSH to the boot server and modify the PXELinux file on the fly. This account will also be used for logging the demo box activities in a file on the boot server.

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

See the dhcp3.tar.gz file for the setup used for the demo.

TFTP server

The TFTP server must be able to boot Debian Installer.

The following line must appear in your 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 made writable by the local "demo" user.

This directory must contain a copy of the Debian Installer netboot image. Grab the netboot.tar.gz file from the [http://www.debian.org/devel/debian-installer Debian Installer pages] and untar it in this directory.

Move the kernel image and the initrd image at the top of the TFTP server tree. Shorten the initrd image name as much as possible so that the kernel command line space is not eaten.

The pxelinux.cfg directory needs some tweaking. First create one default file with an entry named "babel-xx" for each language you wish to have the demo running with.

An example of this file is given in tftpboot.tar.gz in the babelbox distribution.

You may change the console-keymaps-at/keymap values 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.

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 ?DebiaInstaller supported languages at the time of the first babelbox demo is given in the tftpboot.tar.gz file.

Define the first language entry on the "default" line in the TFTP "default" file.

WWW server

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.

This includes a tar file named ssh-keys.tar.gz in the babel/files directory. This file should contain:

  • .ssh/id_dsa
  • .ssh/id_dsa.pub
  • .ssh/known_hosts

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

Other files in babel/ are *.cfg files use for preseeding the installer. The main file in the example is "bdesktop.cfg".

The postinstall file : the GORY part

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 ?DebiaInstaller first stage, the trick is adding the required comment in /etc/crontab on the installed system and have this run after some delay after the reboot.

The demo machine setup

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 in case the installer and subsequent X install do not properly set it up.

The demo cycle

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, 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 load the preseeding file.

The first stage of the installer then runs automatically with nice localised messages showing up, the postinstall.cfg file 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). Then, after the delay defined in /etc/crontab by the postinstall.cfg file, the logger scripts connects to the demo server, switches the language for the next install, logs the new install and finally the hard disk first sector is erased and the system reboots.

As the hard disk is not bootable anymore, the PXE boot starts again and the cycle continues...

Sounds

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 [http://www.perrier.eu.org/debian/voices home page].

Thanks

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 Aeronautics and Space Research Center, and François Mescam, my boss, for allowing me to use its 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