Instructions to build Homeguy ============================= This file is an attempt to document the process to build the Homeguy Live CD based on a stock Ubuntu CD. Help us by improving this documentation. * Needed tools - squashfs module (Ubuntu has it) - squashfs-tools - mkisofs - rsync * Description of the different directories - cdrom: all the files contained in this directory will be copied at the root of the CD. - filesystem: all the files contained in this directory will be copied at the root of the Live CD filesystem. - uck: contains a modified version of the Ubuntu Customization Kit (UCK) - profile: contains the profile for creating the Live CD with UCK * Build Homeguy Live CD As root type the following command: # ./build_homeguy path_to_your_ubuntu_cd.iso This operation may take few minutes, depending on if you have already extracted the original ubuntu content or not. The creation process requires the ability for your system to mount squashfs filesystems. On Ubuntu, type "sudo modprobe squashfs". Other distributions may provide squashfs in a separate package. The following files have an impact on the generating of the Live CD: - profile/customize: customize the content of the filesystem - profile/customize_initrd: customize the initrd (not mandatory) - profile/customize_iso: customize the content of the CD ROM - profile/keep_iso_extraction: if this file is present, it will ensure that the content of the "remaster_iso" directory will be kept after generating. You should however be careful when using this property because the content of this directory is modified with the "iso_customization_script". In other words, if you removed a file in the "cdrom" directory or modified the "iso_customization" script then you should remove the "tmp/remaster-iso" directory to avoid unexpected behaviour. - profile/keep_rootfs_extraction: if this file is present, it will ensure that the content of the "remaster-root" directory will be kept after generating. You should however be careful when using this property because the content of this directory is modified with the "customization_script". In other words, if you removed a file in the "filesystem" directory or modified the "customization" script then you should remove the "tmp/remaster-root" directory to avoid unexpected behaviour. - profile/mkisofs_extra_options: put in this file the extra option that have to be passed to mkisofs, if any. - profile/iso_description: the name of the Live CD - profile/livecd_locale: restrain the locales for the boot time. * Modifying the Live CD ** Add/Remove packages bundled with the distribution In the profile directory, edit the customize script and update the PACKAGES_TO_INSTALL and PACKAGES_TO_REMOVE variable. If the package is not available from ubuntu packages list, you will need to update the etc/apt/source.list file in the filesystem directory as well to add the location of the packages repository containing the desired software. Make sure that the total size of the newly created ISO file does not exceed 700 MB. If not sure, you can remove some less important packages. ** Modify other content on the distribution filesystem Modification to the distribution are done through the "customize" script. Also, all files included in the filesystem directory will be copied to the distribution file system, with respect of the FS hierarchy. Place here the new content intended to appear on the distribution filesystem, such as configuration files, backgrounds images, scripts and other softwares that are not packaged as debian packages and are thus not installable as described above. ** Add/Remove files on the CDROM The customization of the files present on the CDROM is done through the "customize_iso" script located in the profile directory. Also, all the files located in the "cdrom" directory will be copied to the root of the generated ISO file. ** Include your own configuration files for IPv6 Mobility It can be useful to build a customized Live CD matching your configuration. Simply put the configuration files to the "cdrom/conf" directory respecting the name convention and they will be copied to the running system at boot time. Filenames must be one of the following: - mip6d.conf: custom Mobile IPv6 configuration file - mip6d_default: defaults for mip6d - ipsec.conf: custom IPsec configuration file - radvd.conf: custom RAdvd configuration file - quagga: directory containing custom configuration files for Quagga - racoon2: directory containing custom configuration files for Racoon2 In case you are building a master Live CD to be used with HAiku, you should not put any files in the "cdrom/conf" directory. * Test the Live CD Of course the best way to test the Live CD is to burn it and test on your computer. But you may want to check with a virtualization software as well. ** With Qemu (www.qemu.org) No solution yet to have the network working properly. You will have to boot on a real CD in order to test everything related to networking. Also, we strongly advise to install the kqemu accelerator module to have descent performance under qemu. Latest version of qemu cannot boot the Live CD and you will have to update its BIOS file. For qemu v0.9, type the following command as root: # wget -O /usr/share/qemu/bios.bin "http://cvs.savannah.nongnu.org/viewvc/*checkout*/qemu/pc-bios/bios.bin?revision=1.20&root=qemu" Then start qemu with the following command: $ qemu -cdrom /path/to/file.iso -boot d -m 256 This is generally a good idea to increase the amount of memory to allowed to qemu with the m flag. By default this value is set to 128 MB. ** With VirtualBox (www.virtualbox.org) Homeguy runs pretty good under Innotek VirtualBox. Moreover, network is working very well for IPv4 and also IPv6. Below is the procedure to define an interface that can be used for a virtual machine to provide external connectivity. The procedure is for a Debian GNU/linux system like Ubuntu but you can find information for other hosts in Virtual Box user manual: 1) Install some packages necessary to manage bridges and TAP interfaces: # sudo apt-get install uml-utilities bridge-utils 2) Permit the user that launch the virtual machine to access the interface: # sudo addgroup uml-net 3) Create a TAP interface that will be used by the virtual machine: # sudo vim /etc/network/interfaces +-----------------------------------------------+ | auto tap0 | | iface tap0 inet manual | | up ifconfig tap0 0.0.0.0 up | | down ifconfig tap0 down | | tunctl_user | +-----------------------------------------------+ 4) Create a bridge to link the TAP device to the rest of the world using the interface eth0 that is a real Ethernet device: (in the same file /etc/network/interfaces) +-----------------------------------------------+ | auto br0 | | iface br0 inet dhcp | | bridge_ports tap0 tap0 | +-----------------------------------------------+ 5) Activate the interfaces: # sudo ifup tap0 # sudo ifup br0 6) Link the virtual machine to the TAP interface by starting VirtualBox and attaching "Host interface" to tap0 Tested under an Ubuntu linux 7.04, VirtualBox 1.4.0.