Note: Almost all content here will eventually be revised and merged into the live-manual. Please do not add new content to the wiki, but contribute to the manual directly. |
Overview
You can customise Debian live by adding configuration and other files to the appropriate places in the {build root}/config directory. An efficient way of doing this is to develop and test configurations in a live system running in QEMU and then transfer them to your host system. To do this, you need some sort of network connection between the live (guest) system and the host system. A two-way system also enables you to upload files from the host system and test them on the live system without the need to rebuild the live system.
There are several ways to set up networking in QEMU (http://kidsquid.com/cgi-bin/moin.cgi/QemuNetwork). The method described here using a network bridge makes the guest live system appear on the same network as the host. This will work even if the host is a standalone machine providing that it has a network interface. If the host is connected to a network via a router, the live guest will appear on the whole network. If the network includes a gateway to the internet, the live guest will be able to access the internet too.
Here is an example of a small network (192.168.1.0) typical of a home network.
-------------
| router |
| 192.168.1.1 |
-------------
|
| ----------------------------------------------
|----| 192.168.1.3 (eg laptop, wlan0) |
| ----------------------------------------------
| ----------------------------------------------
|----| 192.168.1.4 (eg desktop, eth0) |
| ----------------------------------------------
| ----------------------------------------------
| | Host OS (running QEMU) ---------- |
|----| 192.168.1.2 (eth0) | Guest OS | |
|----| 192.168.1.5 <-----> 10.0.0.1 ---| 10.0.0.2 | |
| (eth0:1) (tap0) | (eth0) | |
| ---------- |
----------------------------------------------There are three computers connected by ADSL to the internet via a modem/router. The router (192.168.1.1) is the gateway to the internet. The host computer used to build Debian live has one ethernet interface with static IP address 192.168.1.2. The other two computers also have static IPs (192.168.1.3 and 192.168.1.4). This means that 192.168.1.5 is available and unused.
You give the host system's network interface card a second IP (192.168.1.5) for the virtual network to use. This means that anything using the existing interface (192.168.1.2) is unaffected. You create the emulated guest system by running QEMU. You create the emulated network interface card (nic) by running QEMU with the "-nic" option. You create a gateway (10.0.0.1) from the emulated network (10.0.0.0) to the original network (192.168.1.0) with a tun/tap device. You set up the tun/tap nic (tap0) on the host system by running QEMU with the "-net tap" option.
When all the new nics have been created you need to configure both networks - the real network (192.168.1.0) and the virtual network (10.0.0.0). Finally, you set up Network Address Translation (NAT) on the host using iptables. The NAT allows two-way communication between the host (192.168.1.5) and the live guest (10.0.0.2).
The setup and configuration of the host can be automated by putting the necessary commands in /etc/qemu-ifup. The configuration of the live guest can be found under {build root}/config/ directory.
Configure and build the live ISO
Install ssh
Install ssh for use in transferring files between host and live guest using scp. Modify {build-root}/config/chroot. (This should have been created previously by "lh_config".
# nano {build-root}/config/chrootModify the line for LH_PACKAGES:
LH_PACKAGES="openssh-client openssh-server"
Set up the emulated nic
Set up the emulated nic (eth0) with IP address 10.0.0.2, netmask 255.255.255.0 and gateway 10.0.0.1:
$ lh_config --bootappend "ip=eth0,10.0.0.2,255.255.255.0,10.0.0.1"
Set up the host
Install ssh
Install ssh for use in transferring files between host and live guest using scp.
# aptitude install openssh-client openssh-server
Load kernel modules
Load kernel modules for the tun/tap and NAT.
# modprobe tun iptable_nat
If you have installed the QEMU accelerator (kqemu), load the kqemu module.
# modprobe kqemu major=0
Assign a second IP address to the host's nic
# ifconfig eth0:1 192.168.1.5 netmask 255.255.255.0
Create the emulated nic and the tun/tap device
The tun/tap device and the emulated nic are created by running qemu with the "-net tap" and "-net nic" options. The tun/tap device will be named automatically - probably "tap0". For example:
# qemu -net tap -net nic -boot d -cdrom {build-root}/binary.iso -m 256 or, if you are using Daniel Baumann's QEMU package (http://wiki.debian.org/DebianLive/Virtualization)
# qemu -net tap -net nic -boot d -cdrom {build-root}/binary.iso -m 256 -kernel-kqemuOn the host, verify that tap0 has been created:
# ifconfig -a
Assign tap0 an IP address on the host computer and bring it up:
# ifconfig tap0 10.0.0.1 netmask 255.255.255.0 up
Check the routing for tap0 (destination 10.0.0.0) and eth0 (destination 192.168.1.0) on the host computer:
# route Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 10.0.0.0 * 255.255.255.0 U 0 0 0 tap0 192.168.1.0 * 255.255.255.0 U 0 0 0 eth0 default 192.168.1.1 0.0.0.0 UG 0 0 0 eth0
Enable ip forwarding
# echo 1 > /proc/sys/net/ipv4/ip_forward
Set up the 1:1 NAT between the host (192.168.1.5) and the live guest (10.0.0.2) with iptables.
# iptables -t nat -A PREROUTING -i eth0 -d 192.168.1.5 -j DNAT --to 10.0.0.2 # iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.2 -j SNAT --to 192.168.1.5
Test the network
Ping each system from the other
Ping the live guest from the host
$ ping -c 3 10.0.0.2 PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data. 64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=0.688 ms 64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=0.414 ms 64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=0.408 ms --- 10.0.0.2 ping statistics --- 3 packets transmitted, 3 received, 0% packet loss, time 1998ms rtt min/avg/max/mdev = 0.408/0.503/0.688/0.131 ms
Ping the host from the live guest
$ ping -c 3 192.168.1.2 PING 192.168.1.2 (192.168.1.2) 56(84) bytes of data. 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.756 ms 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.486 ms 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.810 ms --- 192.168.1.2 ping statistics --- 3 packets transmitted, 3 received, 0% packet loss, time 2021ms rtt min/avg/max/mdev = 0.486/0.684/0.810/0.141 ms
Log in with ssh
Log into the live guest
From the host log into the live guest.
$ ssh user@10.0.0.2 The authenticity of host '10.0.0.2 (10.0.0.2)' can't be established. RSA key fingerprint is 85:02:2d:61:c3:51:e6:c3:05:ae:06:fc:7f:d7:c4:6a. Are you sure you want to continue connecting (yes/no)?
Enter "yes".
Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '10.0.0.2' (RSA) to the list of known hosts. user@10.0.0.2's password:
(User "user"'s password is "live".)
Linux debian 2.6.18-4-486 #1 Wed May 9 22:23:40 UTC 2007 i686 The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. Last login: Fri Jun 22 08:47:13 2007 user@debian:~$
Enter "exit" or press Ctrl-D to log out.
$ exit
Log into the host
From the live quest, log into the host:
$ ssh {your-username}@192.168.1.2
[...]
$ Ctrl-D
Transfer files with scp (secure copy)
Eg to copy a file from the host to the live guest; on the host computer:
$ touch ~/junk.txt $ scp ~/junk.txt user@10.0.0.2:~/junk.txt The authenticity of host '10.0.0.2 (10.0.0.2)' can't be established. RSA key fingerprint is 85:02:2d:61:c3:51:e6:c3:05:ae:06:fc:7f:d7:c4:6a. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '10.0.0.2' (RSA) to the list of known hosts. user@10.0.0.2's password: junk.txt 100% 0 0.0KB/s 00:00
Check the live host:
$ ls junk.txt
Automate the host setup
Modify /etc/network/interfaces
Automate the bringing up fo the second IP for the host's nic.
# nano /etc/network/interfaces
Add an entry for eth0:1
auto eth0:1
iface eth0:1 inet static
address 192.168.1.5
network 192.168.1.0
netmask 255.255.255.0
broadcast 192.168.1.255
Modify /etc/modules
Make sure that the modules are loaded at boot time.
# nano /etc/modules
and add these entries:
# QEMU network kqemu major=0 tun iptable_nat
Modify /etc/qemu_ifup
/etc/qemu-ifup is called by qemu immediately after it creates the tun/tap device
# nano /etc/qemu_ifup
The new version should look something like this:
#!/bin/sh # original was just one line: #sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 # for networked Debian live guest: # Assign a second IP address to the host's nic. /sbin/ifconfig eth0:1 192.168.1.5 netmask 255.255.255.0 # Assign tap0 an IP address on the host computer and bring it up: /sbin/ifconfig tap0 10.0.0.1 netmask 255.255.255.0 up # Enable ip forwarding. echo 1 > /proc/sys/net/ipv4/ip_forward # Set up the 1:1 NAT between the host (192.168.1.5) and the live guest (10.0.0.0). iptables -t nat -A PREROUTING -i eth0 -d 192.168.1.5 -j DNAT --to 10.0.0.2 iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.2 -j SNAT --to 192.168.1.5
Improving the configuration
Configure a DNS nameserver on the live guest
You will need a DNS nameserver in order to browse the world wide web. Set a DNS nameserver in /etc/resolv.conf. Use the DNS supplied by your ISP, the IP of your router if it includes a DNS server, or an IP for OpenDNS eg 208.67.222.222. Edit the file in the live guest after it has booted.
$ sudo nano /etc/resolv.conf
Include a line like this:
nameserver 208.67.222.222
Test the nameserver:
$ ping -c 3 bbc.co.uk PING bbc.co.uk (212.58.224.131) 56(84) bytes of data. 64 bytes from rdirwww-vip.thdo.bbc.co.uk (212.58.224.131): icmp_seq=1 ttl=118 time=71.8 ms 64 bytes from rdirwww-vip.thdo.bbc.co.uk (212.58.224.131): icmp_seq=2 ttl=118 time=21.3 ms 64 bytes from rdirwww-vip.thdo.bbc.co.uk (212.58.224.131): icmp_seq=3 ttl=118 time=20.1 ms --- bbc.co.uk ping statistics --- 3 packets transmitted, 3 received, 0% packet loss, time 2000ms rtt min/avg/max/mdev = 20.120/37.760/71.843/24.105 ms
Give the live guest a permanent ssh identity
Every time you boot the live guest it installs ssh and generates a new key. When you ssh into the live guest from the host you confirm that you accept that key. It is stored in your ~/.ssh known_hosts. The next time you boot the live guest it generates a new key. When you try to ssh in from the host it notices the change, issues a warning and refuses to connect. You can fix this by removing the appropriate line from the host's ~/.ssh known_hosts file, but this is tedious.
To avoid this problem place a copy of the live guests /etc/ssh directory in {build-root}/config/chroot_local-includes/etc and rebuild the ISO.
From the live guest:
$ sudo scp -r /etc/ssh {your-username}@192.168.1.2:{build-root}/config/chroot_local-includes/etc
$ sudo haltFrom the host:
$ cd {build root}
$ lh_clean
$ lh_build
Configure sudo on the host to run QEMU
You must run QEMU as root privileges in order to create the tap device. It is a bad idea routinely to log in as root. A better idea is to use sudo. Configure the sudoers file with the visudo command. (If your default editor is nano, visudo will use nano and not vim.)
# visudo
Modify the file to give your chosen user(s) root access to QEMU. Here is an example:
# User alias specification
User_Alias VIRTUALISATION = {your-username}
# Cmnd alias specification
Cmnd_Alias QEMU = /usr/bin/qemu
# User privilege specification
#
#-----------------------------------------------------------
# User_Alias Host_Alias=(Runas_Alias) Authent Cmnd_Alias
# -ication
# ----------------------------------------------------------
# compulsory run on =run as which PASSWD: compulsory
# which user (root (default)
# hosts by default) or
# (PCs) NOPASSWD:
#-----------------------------------------------------------
root ALL =(ALL) ALL
VIRTUALISATION ALL =(root) NOPASSWD: QEMUYou can now run the emulator command by as a normal user by prefixing it with "sudo":
$ sudo qemu [...]