Builder/HowToCreateYourOwnGNULinuxDistribution — gNewSense GNU/Linux

As part of creating gNewSense, we created our Builder which allows for the creation of a new GNU/Linux distribution based on Ubuntu Hardy. From a simple config file you can choose the name of your distribution, release, tagline and what packages you’d like to be installed/removed by default. Graphics will be automatically generated. These scripts are obviously biased towards producing gNewSense, but should provide a good base to work off. Note that there is no need to follow these steps to use gNewSense, you can download an iso from one of the Mirrors.

You’ll need at least 80GB of free disk space, and preferably a very fast Internet connection (you’ll be pulling 40GB of data). This can be run on any Debian derivative capable of bootstrapping Ubuntu Hardy (8.04). All commands must be run as root.

If you have any queries, please drop into our IRC channel. This is still very much beta software.

Step 1: GPG key

More recent versions of apt require GPG signed release files in a repository to ensure the integrity of the distribution, so our first step is to create a GPG key.

 gpg --gen-key

will let you do this. Make sure the key has a blank password. Take a note of the fingerprint of the key as you’ll need it later for the config file.

Step 2: Checkout builder

To run the build scripts, you will need to get a bazaar checkout.

Make sure you have bazaar installed:

 apt-get install bzr

Then download Builder (it’s about 35 MiB):

 bzr branch bzr://bzr.gnewsense.org/builder/
 cd builder

To also get the source packages specific to gNewSense, check them out with mr (this can be a big download, depending on the packages that have been added):

 apt-get install mr
 cd packages
 mkdir deltah{,-security,-updates,-backports}
 mr -c gnewsense.mrconfig checkout

Step 3: Configuration

Copy the config file to config.local, then open config.local in a text editor. The settings you need to worry about most are listed below, with a short description. Changing the others will lead to better personalisation (see the comments in config/config.local for what setings do).

MIRRORLOCAL is the path to your Ubuntu mirror (used in step 4)

MIRROR is either the mirror you setup in step 5, or an Ubuntu mirror being served via http. It should contain the security packages.

DISTRONAME is what you want to call your distribution which should consist of only letters and numbers.

SIGNINGKEY is your GPG key id from step 1, it should not contain any spaces.

ALL_REPO_ARCHES Lists all architectures you want in your distribution. only i386 is supported currently.

REPOAPT is where the build scripts will pull packages from, so you should setup Apache to serve this.

DOMAIN is used to create the default sources.list when installing. We assume an Ubuntu-like setup where you have archive.DOMAIN and security.DOMAIN and subdomains for all the country codes.

REPODST is where your distributions mirror will be built in the filesystem ($BASEDIR/$DISTRONAME_L by default).

Ensure you remove the following lines from config.local, or you will cause a loop in the scripts:

 # Allow for local customisations
 if [ -r config.local ]; then . config.local; fi

 if [ -r config.auto ]; then . config.auto; else exit 1; fi

These lines must remain in the file config.

Step 4: Debmirror

Here we create a keyring for the mirror, so you can stay in ‘secure apt’ mode.

 sudo mkdir /the/target/directory-keyring

Import the Ubuntu keyring, this is what the upstream packages are checked against.

 gpg --no-default-keyring --keyring /the/target/directory-keyring/trustedkeys.gpg --import /usr/share/keyrings/ubuntu-archive-keyring.gpg

This mirror will require approximately 50GB for i386 only, and 70GB for both i386 and amd64. This mirror should be created on a hard drive with at least 10GB of space free after the mirror has been created.

export GNUPGHOME=/home/mirrorkeyring

 debmirror --verbose --progress --method=http --host=ie.archive.ubuntu.com --arch=i386 --source 
 --dist=hardy,hardy-security,hardy-updates,hardy-backports --section=main,main/debian-installer,universe 
--root=ubuntu /the/target/directory

unset $GNUPGHOME

/the/target/directory should be the path you set in $MIRRORLOCAL

Step 5: Packages

You’ll need a number of packages for Builder to run properly.

 apt-get install reprepro debmirror build-essential apache2 subversion cdebootstrap debootstrap imagemagick apt-utils
 apt-get install squashfs-tools netpbm syslinux bittornado fakeroot devscripts equivs sharutils mkisofs

If there is packages missing from this list, please let us know.

Step 6: Setting up $REPODST

Hard linking of $REPODST (distribution target directory) is handled by gen-repo, so you are not required to do it by hand.

To do intial repository setup, run gen-repo

 ./gen-repo

For gen-livecd to work, you will need to serve $REPODST with Apache (or another http server). The simplest way to do this is symlink $REPODST into /var/www/$DISTRONAME_L, and leave the $REPOAPT variable alone.

 mkdir -p /var/www/
 ln -s $REPODST /var/www/$DISTRONAME_L

At this point its also sensible to make your local Ubuntu mirror (made in step 4) available via http

 ln -s /the/target/directory /var/www/ubuntu/

Step 7: Generate the repository

 ./do-update

This will take a while. The repository will possibly be in an inconsistent state while this is running, which is why you only push your changes to a mirror in Step 7. Every time there’s new versions upstream (e.g. security updates) re-run do-update (and debmirror if needed).

If you are running a 32bit userland on a 64bit kernel, install the linux32 package and use

 ./gen-repo && linux32 ./do-update

Step 8: Generate the LiveCD

 ./gen-livecd

The created image will be placed in $LIVECDDIR/$DISTRONAME_L-livecd-$RELEASE-$ARCHTOBUILD-$LIVECD_VERSION.iso

 ./gen-cdsource
 ./stage-cd

Will prepare a source tarball and push the iso to $LIVECDDIR

Step 9: Push your repository to a mirror and publicise

You can now publish your repository (the dists and pool) directories as well as your LiveCD to your mirror and publicise your new distribution to the world.

 ./push-repo
 ./push-cd

© Brian Brazil 2006 — 2009

© Karl Goetz 2009 — 2010