DemoLinux HOWTO =============== Current Maintainer: Roberto Di Cosmo ($Header: /home/dicosmo/DemoLinux-HOWTO,v 1.6 2001/11/21 02:24:35 dicosmo Exp dicosmo $) Standard Disclaimer. -------------------- The material (information and programs) in this document are provided AS IS, without any expressed or implied warranty or claim of fitness for a particular purpose. Neither the author nor any contributors shell be liable for any damages done directly or indirectly by using the material presented in this document, even if they were warned of the possibility of such problems. Please understand that creating a working Live CD is a complex task: we try to make it simpler and to explain our procedures, but you assume the ultimate responsibility of your actions. Having that said, I still hope this material will be useful for its readers, and help them understand what the DemoLinux project is, how it is organised, and how one could modify an existing DemoLinux CD to add/remove applications. If you find a mistake, inaccuracy or other fault with any of this material, please let me know, via email. Also, the authors cannot guarantee any level of support in your projects, be they commercial or non-for-profit, even if they will gladly accept and acknowledge constructive suggestions and contributions to the project. YOU HAVE BEEN WARNED. Still here? Well, then let's see the juicy bits. Introduction. ------------- DemoLinux is a bootable CD-Rom in the style of Live CDs. It differs from many of the available Live CDs in its design goals and architecture. Design goals: ------------- - provide a bootable CD that autodetects most peripherals without user interaction, in order to become an easy-to-use off-the-shelf, dumb-proof platform to show off GNU/Linux and to demo GNU/Linux-cased software. The primary targeted end user of our DemoLinux effort was *not* a computer-literate person able to understand the details and modify the configuration of a GNU/Linux distribution, let alone able to use it as a recovery disk, diskless firewall or the like. Nevertheless, all these tasks *can*, and have actually been, performed using DemoLinux. - do not touch the user's machine hard disk unless explicitly requested to do so: the target being the general user, we do not want to hear stories of "GNU/Linux erasing Windows partitions" or the like. Nevertheless, once the user is confident, we want to provide him with convenient means to store part of the configuration data or personal data onto a file if a disk is present, without need to repartition it. This is what in DemoLinux lingo is called "anchoring". This principle can be extended to obtain a real "PC on a CD", by "anchoring" on a (possibly encrypted) remote filesystem. - provide a full-fledged GNU/Linux-based system, with appealing graphic interfaces (like Sawfish or KDE), compelling applications (like The Gimp, StarOffice, TeXmacs, etc.), and useful research and development tools (like OCaml, Elan, gcc, perl, python, etc.) - be "a fine product", that can generate a positive opinion of GNU/Linux and free software in general. This means we wanted to take into account functionality as well as aesthetics, having nice logos, nicely designed and packages CDs. This is also the reason why, even if one of the authors did write a quite successful short article about why one should use free software and not proprietary mouse traps, no such documents have been included in the CD yet. - be independent of any commercial distribution. We do love commercial distributions, as they are doing a excellent job out there, but we do not want to give the impression that we prefer one over another, or that we are doing free advertising for one of them. This is why, after a first release based on a Mandrake, we decided to stick with Debian for 2.0 and 3.0. But technically, there is more than this: our goal was to try and isolate distribution dependent details, in such a way that building a Mandrake/SuSE/RedHat/TurboLinux/Caldera/whatsoever -based DemoLinux should be as easy as possible. - make all this as simple as possible: the final goal would be to enable everybody to press her own personalized DemoLinux to show or carry along. In this respect, synergies with projects like Linux From Scratch or similar ones should be explored. Architecture: ------------- To achieve the design golas, we settled on the following three-layered file-system architecture i) the root file system always resides in a very small ramdisk, whose image is located into /.demolinux/images/ram2.gz and contains just links to the other filesystems, called "plume" (feather) and "plomb" (lead). In the current 3.0 version, this small filesystem looks like the following total 135 drwxr-xr-x 12 root root 1024 Dec 19 2000 . drwxr-xr-x 34 root root 4096 Aug 5 13:08 .. lrwxrwxrwx 1 root root 40 Dec 11 2000 .complement -> .plomb/.demolinux/images/ram2.complement drwxr-xr-x 2 root root 1024 Jan 10 2000 .demolinux drwxr-xr-x 2 root root 1024 Jan 7 2000 .host drwxr-xr-x 2 root root 1024 Jan 15 2000 .plomb drwxr-xr-x 2 root root 1024 Jul 19 1999 .plume -rw-r--r-- 1 root root 65536 Jul 5 19:42 TMP lrwxrwxrwx 1 root root 15 Dec 11 2000 bin -> .complement/bin lrwxrwxrwx 1 root root 11 Dec 11 2000 boot -> .plume/boot drwxr-xr-x 3 root root 7168 Feb 16 2000 dev drwxr-xr-x 4 root root 1024 Dec 19 2000 etc lrwxrwxrwx 1 root root 11 Dec 11 2000 home -> .plume/home lrwxrwxrwx 1 root root 15 Dec 11 2000 lib -> .complement/lib drwxr-xr-x 2 root root 12288 Dec 9 2000 lost+found lrwxrwxrwx 1 root root 10 Dec 11 2000 mnt -> .plume/mnt -rw-r--r-- 1 root root 37600 Dec 19 2000 modules.dep lrwxrwxrwx 1 root root 10 Dec 11 2000 opt -> .plume/opt dr-xr-xr-x 2 root root 1024 Apr 19 1996 proc lrwxrwxrwx 1 root root 11 Dec 11 2000 root -> .plume/root drwxr-xr-x 2 root root 1024 Jul 12 2000 sbin drwxrwxrwx 2 root root 1024 Jul 18 1999 tmp lrwxrwxrwx 1 root root 15 Dec 11 2000 usr -> .complement/usr lrwxrwxrwx 1 root root 15 Dec 11 2000 var -> .complement/var ii) the CD-ROM, which is found, and mounted as /.plomb, by the linuxrc program executed at boot in the initial ramdisk which is contained in the floppy image located at /.demolinux/images/boot.img The CD-Rom detection phase is a standard part of any Linux installation program, so we just adapted SuSE's linuxrc instead of writing our own, even if we do provide a simple 2 pages C program of our own design that works if the CD-Rom is on an EIDE drive. iii) an intermediate file system, mounted on /.plume, that gives us the necessary flexibility to allow diskless operation as well as "anchored" operation. This /.plume filesystem may be - a ramdisk (whose size may depend on the size of the available ram, but this size selection, that we did not implement yet, will probably not be necessary once we step up to a 2.4 kernel, that provides ramfs). In 3.0, we load a 9Mb ramdisk found in /.demolinux/images/plume.simple.9M.gz IMPORTANT: on the 2.2.x series, this small plume filesystem is a *compressed* ext2 filesystem, so you need a kernel with e2compr to read it as well as e2compr-aware e2fs-tools. - a loop file stored in a hard disk on the user's machine. If the user decides to "anchor" DemoLinux on a hard-disk, we propose him to copy on one of the available partitions (DOS/VFAT/ext2/reiserfs, but NOT NTFS!) two files, one for the swap, one for the "plume", chosen among different available sizes (the plume.candidat files in /.demolinux/images). This will create in the partition a directory named linuxdmo containing two files: swap.dmo (a file for the swap) plume-3.0.demo (the persistent file system) plume-3.0.dmo contains a small part of the file system on the CD (typically some frequently used binaries, the /home/demo and /root directories, as well as /etc and /tmp, /var/log and similar essential directories), plus a certain amount of free space. During the anchoring procedure we update plume-3.0.demo with all the informations known to the running DemoLinux (user language/keyboard, network addresses, detected devices etc.) The next time the user boots off DemoLinux on an "anchored" machine, DemoLinux will find the linuxdmo directory, mount it as /.plume and skip all other detection/configuration steps (this way, an "anchored" machine can be booted in DemoLinux quite quickly). To avoid compatibility issues (you anchor DemoLinux 1.0, then you boot DemoLinux 3.0 and everything crashes), new versions of DemoLinux use different names for the anchored plume filesystem (typically, DemoLinux x.y will use plume-x.y.dmo). - It would be pretty interesting, if we want to provide a really lightweight Network Computer solution, to mount part of /.plume over a secure network connection: my home directory could reside on a secure server somewhere, and I access it safely from anywhere in the world using my personalized DemoLinux. Typically, this could be based on the TCFS filesystem developed by the people at http://www.tcfs.it Design consideration for storing /.plume candidates: ---------------------------------------------------- As a consequence of the plethora of file systems that may be mounted as /.plume, one must be able to easily build a file system containing only selected parts of the CD files, and containing links to /.plomb for the files or directories we do not want to copy on the /.plume. One solution would be to just keep a description of these choices, and populate the selected /.plume at boot time; that would save space on the CD (no plume.simple.whatever to be stored), but turns out to be excessively slow. We decided instead to pre-build a file system image for each possible choice and keep it in /.demolinux/images: at run time, once the selection is made, /.plume is rebuilt with a simple and lightening fast dd command. This means we need a tool to rebuild these plume candidates automatically from the CD file system before generating the ISO image. The compressed file system -------------------------- To store the maximum information on a CD, and to improve performance, we use a transparently compressed variant of the ISO filesystem, which dates back to work of Eric Youngdale, modified extensively by Adam J. Richter, and finally fixed by Roberto Di Cosmo. The latest version is available on http://www.pps.jussieu.fr/~dicosmo/FreeSoftware/isocompr, for the 2.2.x kernel series. Porting to 2.4.x series is not impossible, and a very fast hack that does not handle SMP kernels does exist in Roberto's scratch space, but probably this work is pointless, since HPA's zisofs does the same in a much cleaner way for 2.4.x kernels (but ONLY for 2.4.x kernels). The current version of the compressed iso9660 patch for 2.2.18 kernels is made up of * a modified gzip, able to produce the blockwise compression need for random access to data contained on a compressed file (necessary in the transparent compression scheme adopted here). This is enabled with the -B option, and produces the .gZ files you see in the DemoLinux CD. * a modified mkisofs, that, when called with the -z option, produces an ISO image with the necessary information to tell a modified kernel about transparently compressed files * a kernel patch (for Linux 2.2.18) to allow the kernel to transparently decompressed blockwise compressed files. Notice that when mounting an ISO image containing .gZ files with a kernel able to recognize them, you dont see the .gZ extension, and the files are transparently decompressed. You can mount the ISO image with the "uncompress=n" option to disable the transparent decompression. ====================================================================================================== How do we create/modify a new DemoLinux-based CD? ------------------------------------------------- A simple example: changing the StarOffice version. ================================================== This is a simple example that will show you what need to be changed on a working DemoLinux CD to add another application. In this case, we actually REPLACE an existing application (StarOffice in a given language), by another version (StarOffice in another language), and show also how to use some pretty useful options of mkisofs to do this without actually modifying too much the CD image. Indeed, you have two options to add an application: i) do a full install of the DemoLinux CD, including the delta.tar.bz2 and dpkg-info.tar.bz2 extension archives, on an available partition, then boot off that partition, change what you want to change, then propagate the relevant changes into the "plumes" (by hand or via some script), then recompress all the files (but not the S01plume file in .demolinux, nor the files you wnat Windows users to be able to read). [This should be "the right way", but it is tricky and a bit of an overkill if you just want, say, to change the version of StarOffice] ii) short-circuit part of the process, by actually installing the application you want on your machine running some other distribution, but making sure that the demo user can use it, and that this application is reasonably separated from the rest by being fully isolated in some subdirectory (it is the case for StarOffice, OpenOffice, Acrobat Reader etc.). Then compress, and "graft" this subdirectory on a copy of the ISO image, after propagating the (minor) changes into the "plumes". We will detail this second process, in what follows, and look for volunteers to write down a similar guided example for the first process. Step one: get the tools! ------------------------ Make sure you have the proper tools to handle the compressed iso files: this includes a modified gzip, mkisofs and a patched kernel that supports at least e2compr. The sources of all this are available in sources.tar.bz2 (or a similarly named file) from ftp.demolinux.org. Step two: create a verbatim copy of the CD on a hard disk --------------------------------------------------------- Find a place on your machine that has enough space to hold a copy of the CD (~700Mb), plus some working space (~300Mb). To be safe, a 2Gb partition is a good choice. We assume now that the directory /dl has that much space available. Assume also you have a directory available on which to mount the CD image (or the actual CD, but the CD image will be much faster!). Now: i) mount the CD image: mount -o loop,uncompress=n demolinux-3.0.iso /scratch (the uncompress=n option tells a kernel featuring transparent iso compression not to decompress the data, letting the .gZ extension appear as they are) ii) copy verbatim the CD contents in /dl: cd /scratch; cp -a . /dl Nice, you have in /dl a writable copy of the (transparently compressed) CD! Step three: prepare your application ------------------------------------ Now, on your working machine, prepare the application you want to install, adapting it to DemoLinux. This means installing it, and making it usable for the demo user, with the proper userid and group id (those used in the DemoLinux CD!). More precisely i) install your version of StarOffice with the /net option in /usr/local/office52 ii) create a demo user in /home/demo with uid 1000 and gid 100 iii) create a scratch directory, say /toto/de for German StarOffice, and copy (with their full path!) /usr/local/office52 and /home/demo in it iv) find /toto -type f -exec gzip -B 4096 {} \; (i.e. compress with the DemoLinux modified gzip all files in /toto) Step four: create the modified ISO image ---------- Make sure you have another mount point available, say /mntdemo, on which to mount the "plumes" to propagate the necessary changes. Then you should be able to simply run the following script, that builds a modified iso image for each language of StarOffice in the /toto directory declared in the LANG variable. What the script does is to uncompress each of the vailable "plumes", copy into them the new version of /home/demo/office52, then recompress them, and then create the new ISO image by "excluding" the /usr/local/office52 directory previously on the CD, and "grafting" in its place the one you prepared into /toto/de (actually, it does this also for the office52 directories in /home/demo and /root). --------------------------------CUT HERE---------------------------------------------------- #!/bin/sh # # Scritp that centralizes the reconsruction of all localised variants # of DemoLinux. # Right now, this just means rebuilding the iso images with the grafted office. # SOFFICESBASE=/toto LANGS="it de" ISOS=/tmp # where to put the new iso image REPCOPIE=/dl VERSION=3.0 EXCLUDE="-m $REPCOPIE/usr/local/office52 -m $REPCOPIE/home/demo/office52 -m $REPCOPIE/home/demo/.user52.rdb.gZ" PLUME=/tmp/i18noffice.$$ PLUMEMNT=/mntdemo for l in $LANGS; do echo "Building variant for language $l: " echo " * Updating plumes:" for plume in $REPCOPIE/.demolinux/images/plume.simple.*M.gz $REPCOPIE/.demolinux/images/plume.complete.*M.bz2; do echo -n " -> $plume :" if [ `basename $plume .gz` = `basename $plume` ]; then UNZIP=bunzip2 ZIP=bzip2 else UNZIP=gzip -d ZIP=gzip fi $UNZIP -c $plume > $PLUME mount -o loop $PLUME $PLUMEMNT rm -rf $PLUMEMNT/home/demo/office52 cp -a $SOFFICESBASE/$l/home/demo/office52 $PLUMEMNT/home/demo/office52 rm -rf $PLUMEMNT/home/demo/.user52.rdb* cp -a $SOFFICESBASE/$l/home/demo/.user52.rdb* $PLUMEMNT/home/demo find /$PLUMEMNT/home/demo -type f -name "*.gZ" -exec gzip -d {} \; umount $PLUMEMNT $ZIP -c -9 $PLUME > $plume rm $PLUME echo "OK" done echo -n " * building ISO image:" SMALLOFFICE="-m $SOFFICEBASE/$l/usr/local/office52/help -m $SOFFICEBASE/$l/usr/local/office52/share/dict -m $SOFFICEBASE/$l/usr/local/office52/share/gallery -m $SOFFICEBASE/$l/usr/local/office52/share/samples -m $SOFFICEBASE/$l/usr/local/office52/share/template" mkisofs -z -L -R -J -nobak -graft-points -b .demolinux/images/boot.img -c boot.cat -P demolinux@demolinux.org -p demolinux@demolinux.org $EXCLUDE $SMALLOFFICE -o $ISOS/demolinux-$VERSION-$l.iso -v $REPCOPIE usr/local/office52/=$SOFFICESBASE/$l/usr/local/office52 home/demo/.user52.rdb.gZ=$SOFFICESBASE/$l/home/demo/.user52.rdb.gZ home/demo/office52/=$SOFFICESBASE/$l/home/demo/office52 2>log$l 2>log$l if [ $? -eq 0 ];then echo "OK" else echo "KO" fi done for file in $ISOS/*.iso; do echo -n "MD5 sum for $file " md5sum $file > $file.MD5 echo "OK" done --------------------------------CUT HERE---------------------------------------------------- Step five: TEST IT ------------------ Now you can write a CD-R, cross your fingers, and see if all worked out. If you find problems, try to check that you followed the procedure properly (did you use the right gid/uid? did you double check that the directory names you used match the usage in the script?). Or try to do by hand what the script tries to automate. =================================================================================================== N.B.: you are very welcome to discuss all this on the DemoLinux developer list, but please understand that the authors CANNOT promise to answer your questions timely (re-read the standard discalimer); cooperating with other people participating in the same experiment could be pretty useful. See www.demolinux.org for details on joining the mailing list. ===================================================================================================