CRUX : Home

Home :: Documentation :: Download :: Development :: Community :: Wiki :: Ports :: Bugs :: Links :: About

Back to wiki start page

Categories: Install

Building a custom CRUX iso image file




Building a custom CRUX iso image file

Why you might want to build a custom CRUX iso image file

You might want to build your own crux iso image file for the following reasons:

- to add packages to the boot cd (like ssh and ping)
- to add drivers that are not included in the official crux iso image
- to create a custom install cd for your systems

My reasons for building a custom iso image were pretty simple. I wanted to add some drivers to the kernel, and add a few packages to the boot image so i could use network to copy files from remote systems if (and when) needed.

I did a lot of this by trial and error. Several points cost me a fair bit of time, so I thought I'd write this page to help some people avoid making the same mistakes. I'm sure there are better ways to do this, but I couldn't find a lot of detail on the specifics of how to do this. It is pretty straight forward once you get a sense of what goes into building a crux iso.


In order to build a crux iso image, you should be familiar with compiling the linux kernel, building ports packages, compiling software in general. It also helps if you are comfortable editing Makefiles and have some basic shell scripting skills.

You don't have to be an expert by any means -- I'm surely not an expert in any of this.


Crux is maintained using git. git is a version control system like cvs or svn.

You can find the crux sources at and the ISO source specifically at


For those who want the short version, here it is:

- cd to the directory you plan to work in
- clone the system/iso.git repo
- set up the branch to work in
- clone the ports/core.git, opt.git, xorg.git inside the iso/ports directory that is created when you pull the iso.git and set up the branches
- modify/add/remove the ports according to your needs
- modify the Makefile to your needs
- run make
mkdir -p /usr/src/crux/3.7
cd /usr/src/crux/3.7
git clone
cd iso
cd ports
git clone
git clone
git clone
(cd core; git checkout 3.7)
(cd opt; git checkout 3.7)
(cd xorg; git checkout 3.7)
cd ..
<edit Makefile if needed>
make kernel
make bootstrap
make iso

Hours later, when all the compiling is done, you should have a crux.iso image file in your working directory. Burn it to CD or mount it somewhere and enjoy!

Additional Information

Here are some further hints:

- you need the core ports collection
- create your own custom collection and copy what you want/need from opt to it (then modify the COLLECTIONS variable in the make file). This helps to keep the size (and build time) of your image down.
- edit the ISO_PACKAGES variable in the make file. Add any port that you need by specifying the port name (not including version or .tar.gz part of the file name). Look at the Makefile, it should be pretty obvious.
- you can update the kernel to a newer version than the one in the official image. the steps are basically:
- update the KERNEL_VERSION to the version you want to use ( at the time of this writing)
- copy the linux-<version>.config file to the new version (i.e. official iso image includes linux-2.6.20.config, update to linux-2.6.22.config)
- run make kernel to download and build the new kernel for use in the iso image

I highly recommend reading through the Makefile. Get familiar with what it does. You'll find ways to cut some corners here and there when building. For example, make iso rebuilds the kernel every time you run it. Add your own section (test-iso: maybe) that skips these steps. It will help save you some time.