====== Temporary Customizations ======

Voyage customizations ((Why Temporary? Because stable 'voyage-0.2' will have a real [[Customization]] frame work)) are easy. 

This page will give you some pointers on how to customize your voyage image **before** writing it to your removable media (usually compact flash card).

** Terminology **
  * ''host'' is your host computer system (desktop or laptop or whatever).
  * ''chroot'' is explained [[http://en.wikipedia.org/wiki/Chroot_jail|here]].\\ When you ''chroot'' into the voyage directory, it is similar (but not exactly like) running the voyage on your embedded system (only it runs on your host system).

===== Preparations =====
  * Download latest version of voyage (voyage-0.2pre2.tar.gz as of this writing)
  * as **root** ((You must be **root** for everything done on this page)), execute the following command:
<code>
host# tar -xzvf voyage-0.2pre2.tar.gz
</code>

===== Configurations =====
  * Some modifications are easier done on the host side, before **chroot**ing into the voyage image.
  * Edit ''ro/etc/resolv.conf'', to match your DNS servers.\\ The default ''resolv.conf'' contains:

<file>
nameserver 210.0.144.66
nameserver 210.0.144.26
</file>

  * Edit ''etc/apt/sources.list'', to add your preferred APT sources.\\ The default APT source is ''ftp://ftp.hk.debian.org/debian'', and adding a closer APT source will make your updating faster.\\ The default ''sources.list'' contains:

<file>
deb ftp://ftp.hk.debian.org/debian/ sarge main
deb http://security.debian.org/ sarge/updates main
deb http://www.voyage.hk/dists/0.2 ./
</file>

<nowiki>You can leave the ''http://www.voyage.hk/dists/0.2'' and the ''http://security.debian.org/'' sources, but the  ''ftp://ftp.hk.debian.org/debian/'' can be replaced with a closer mirror server</nowiki> (see [[http://www.debian.org/mirror/list|Debian mirror list]]).

  * Edit ''ro/etc/hostname'' to the desired hostname.
  * Create ''etc/hosts'' and add the following line:\\ (Replace ''hostname'' with your actual host name).
<file>
127.0.0.1 hostname
</file>

  * Edit the ''etc/network/interfaces'', add you own configuration.
  * Edit the ''etc/dnsmasq.conf'' file to enable the DHCP server.\\ You must also create ''ro/var/lib'' directory for dnsmasq to work.
<file>
dhcp-range=10.1.10.50,10.1.10.100,255.255.255.0,1h
dhcp-leasefile=/rw/var/lib/dnsmasq.leases
</file>

===== CHROOTing =====
  * Before **chroot**ing, you must copy the content of ''ro'' directory into ''rw'' directory.\\ This is necessary to emulate the behavior of the voyage boot process.\\ Many files in ''etc'' & ''var'' directories are soft-links to the ''rw'' directory.
<code>
host# cd voyage-0.2pre2
host# cp -r ro/* rw
host# cd ..
</code>

  * Run **chroot**:
<code>
host# chroot voyage-0.2pre2
</code>

  * Mount the ''proc'' file system (this is done from **within** the chroot)
<code>
chroot# mount -t proc none /proc
</code>

  * Your voyage image is now ready to run.

===== Things you can do inside the chroot =====
  * Run ''apt-get update'' & ''apt-get upgrade'' to upgrade your voyage system.\\ **Note:** This might considerably enlarge your voyage image.
  * Run ''apt-get install [package]'' to install new packages.
  * Change the ''root'' password (simply run ''passwd'').\\ This is useful if (like me) you don't have a serial NULL cable, and the first time boot on my WRAP board hangs while waiting for a new password.
  * 


===== Reducing the size of the image =====
(execute these from within the ''chroot'')
  * Install a package called ''localepurge'' (http://packages.debian.org/testing/admin/localepurge), and then run ''localepurge'' to free the locale information (This freed 16MB for me).
<code>
chroot# apt-get install localepurge
chroot# localepurge
</code>
  * Clean the local APT repository.\\ **Note:** Do this from the ''chroot'' (or you might damange your host system).
<code>
chroot# apt-get clean
chroot# echo > /etc/apt/sources.list
chroot# apt-get update
</code>
  * To see the list of installed packages, sorted by size, run the following command:
<code>
chroot# dpkg-query --showformat='${Status}\t${Installed-Size}\t${Package}\n' -W '*' | 
           grep "^install ok" |
           cut -f2,3 |
           sort -n -k1
</code>

===== Cleanups =====
  * Before leaving the chroot, be sure to unmount the ''proc'' filesystem:
<code>
chroot# umount /proc
chroot# exit
</code>

  * Delete the content of the ''rw'' directory (it will be re-created when the voyage boots):
<code>
host# rm -rf rw/*
</code>