Bundles

FreeBSDToGo generates custom bootable CDs based on the contents of 'bundles'. A bundle is just a special set of directories and files that specify the contents of your CD. FreeBSDToGo can turn a bundle into a tarball (for distribution) and can extract a tarball back into a directory tree.

Bundle Structure

Here is a description of the bundle directory structure:

bundle directory
|
+- packages/
+- copy/
+- patch/
+- rwmounts
+- bundle.conf (optional)
+- make.conf (optional)
+- prepatch.sh (optional shell script hook)
+- postpatch.sh (optional shell script hook)
+- prepackages.sh (optional shell script hook)
+- postpackages.sh (optional shell script hook)
+- precopy.sh (optional shell script hook)
+- postcopy.sh (optional shell script hook)
+- local.sh (optional shell script hook)

packages/

You probably want to use your bootable CD to run programs. Most of the programs you want to run are probably in the FreeBSD ports tree. In order to install programs from 'ports' onto a bootable CD, you use the packages/ directory.

The process is fairly straight-forward. First, you find (or make) a FreeBSD package. Next, you put this package into the packages/ directory of your bundle. When you use the FreeBSDToGo makefile to turn your bundle into a CD, the packages in your bundle's packages/ directory will automatically be installed. Note: Currently, package dependencies must be satisfied manually. For the time being, this is left as an exercise for the reader.

copy/

Now that you know how to install FreeBSD packages onto a bootable CD, you probably want to know how to add custom configuration files for those packages. You probably want to add other custom files, like /etc/rc.conf to your bootable CD, too. This is what the copy/ directory is for.

The copy/ directory simply contains a tree of files that are copied into your bootable CD's file system, at build-time. If you want to make your own /etc.rc.conf, simply add copy/etc/rc.conf to your bundle. If you want to run apache on your CD, for example, you probably want to have copy/usr/local/etc/apache/httpd.conf in your bundle. This file will be copied into your CD's filesystem, when you build your CD.

patch/

Sometimes, instead of wanting to replace the a default configuration file with your own version (with the copy/ method), you simply want to make a simple change to the default version. This is what the patch/ directory is for.

At build time, FreeBSDToGo traverses your bundle's patch/ directory, looking for patch files. When it finds a patch, it applies this patch to the file of the same name in your CD's filesystem. For example, patch/etc/master.passwd would be a patch that would be applied to /etc/master.passwd on your CD.

A perfect use for the patch/ directory is modifying /etc/master.passwd on your CD. FreeBSDToGo builds CDs from the FreeBSD source code. Over time, the default /etc/master.passwd in the FreeBSD source code changes. If you use patch/ instead of copy/ in the right places, you won't have to change your bundles as often, when creating new versions of your CDs.

Note: Patch files are created with the "diff" program. Learning to use "diff" properly is left as an exercise to the reader.

rwmounts

In order for FreeBSD to boot normally, certain parts of your filesystem need to be mounted read/write. FreeBSDToGo accomplishes this with MFS. The rwmounts file specifies a list of directories, one per line, without leading and trailing slashes, that will be mounted read/write at boot time. The default FreeBSDToGo bundle mounts /etc, /dev, /home, /tmp, and /var read/write. If you add any directories to this list, make sure you have enough room in MFS (and in memory) for that filesystem. Look at patch/etc/rc and copy/etc/rc.rwmounts in the default bundle, for more details.

bundle.conf

This file specifies some configuration options for your bundle. Look at defaults/bundle.conf in the FreeBSDToGo directory for more information.

make.conf

This file, if it exists in your bundle, will be used as the make.conf file for the "installworld" and "installkernel" sections of the CD build process. This can be useful for eliminating unnecessary programs from your CDs, through the numerous NO_* options in /etc/defaults/rc.conf. Do you really want to install bind on your bootable CD? Sendmail? Fortran? Note: If you use a make.conf in your bundle, make sure it matches the make.conf use used to build your kernel and world, or you will have problems.

Shell Script Hooks

FreeBSDToGo has a series of hooks, to allow local customization of a CD. These hooks come in the form of shell scripts which run at different stages of the CD build process. If you can't fit your customization into the other parts of the bundle (such as the 'copy', 'patch', and 'packages' directories), you should use these files to perform further customization.

Here is the list of shell scripts, and their meaning, in the order in which they run:

  1. prepackages.sh - runs directly before packages are installed from a bundle
  2. postpackages.sh - runs directly after packages are installed from a bundle
  3. prepatch.sh - runs directly before patches from a bundle are applied to the build directory
  4. postpatch.sh - runs directly after patches from a bundle are applied to the build directory
  5. precopy.sh - runs directly before the 'copy' directory is copied from a bundle to the build directory
  6. postcopy.sh - runs directly after the 'copy' directory is copied from a bundle to the build directory
  7. local.sh - runs last, after other hooks (and most of the build process) has finished