FreeBSD Support

AoE support is available for FreeBSD kernels 4.11 and 5.3 by apply a patchfile to the kernel distribution as follows. Please note this driver is older than the current release and is provided as a convenience for users needing support for these older systems.

The patches are against the kernel sources as of 11/09/2004. Experience with cvsup(1), patch(1), kernel configuration and compilation, and system configuration are necessary for incorporating AoE into a system. For the inexperienced, most of this can be learned as you go; read the following notes carefully.

After incorporating AoE into your kernel, see Using AoE on FreeBSD for tips on using AoE with FreeBSD.

Adding AoE to FreeBSD

Table of Contents:

Using cvsup to get the sources
Using patch to apply the AoE patch
Configuring and building the kernel
Updating system files
Staying up to date

1. Using cvsup to get the sources

CVSup(1) is a software package for distributing and updating collections of files across a network. It contains a client program, cvsup, used to sync a collection against a cvsup server. In its simplest usage you give it a file specifying the details of its operation -- what server to use, what collection to retrieve, and where to put it -- and it just works. For an exposition of CVSup and its many features, please visit the FreeBSD Handbook section Using CVSup.

The remainder of this document assumes the sources are in /usr.

2. Using patch to apply the AoE patch

Patch(1) takes a patch file containing any of the four forms of difference listing produced by the diff(1) program and applies those differences to an original file or file tree, producing a patched version. The manpage referenced above is good reading if you've never used patch before.

The patchfiles for the source distributions supported are as follows:

4.11 - aoe-4.11-patch.2
5.3 - aoe-5.3-patch.4

To test apply the patchfile for 4.11 to cvsup'd sources installed in /usr/src you could run:

$ cd /usr/src
$ patch -Cusp1 </path/to/aoe-4.11-patch.2

If the patch is valid, no output will occur. If you do get error output, it is likely that the patch is out of date with respect to your sources. Contact me using the information at the bottom of this page if this occurs. To actually apply the patch, run the same command without -C as follows:

$ cd /usr/src
$ patch -usp1 </path/to/aoe-4.11-patch.2

What's in this patch, anyway?

All AoE patches modify the standard distribution as follows:

Add AoE loadable module and kernel config support.
Add man page for aoe(4).
Modify the etc/defaults/rc.conf file.

The 4.11 patch also has:

Modifications to vinum so it can use AoE devices in /dev.
Modifications to etc/MAKEDEV and etc/rc.

The 5.3 patch also adds:

etc/rc.d/aoe script for using aoe devices on boot.

3. Configuring and building the kernel

If you do not have experience configuring a FreeBSD kernel, I recommend reading Chapter 8 of the FreeBSD Handbook, Configuring the FreeBSD Kernel. It's a very simple procedure and something you should be familiar with if you want to get the most out of your system.

Turning on support for AoE in 4.11 requires at least one line added to your kernel config file:

options AOE_HOOK

This hook is necessary to permit AoE to use the network layer, both as a compiled in and run-time loadable module. This line is unnecessary and improper for 5.3 and up.

To compile AoE into the kernel, add the following line to your kernel config file:

device aoe

To build the kernel in /usr/src/sys, do the following:

$ cd /usr/src
$ make buildkernel KERNCONF=CONFIG_FILE
...
$ make installkernel KERNCONF=CONFIG_FILE

Replace CONFIG_FILE with the name of your kernel config file. If all is successful you will run the new kernel on your next boot.

4. Updating system files

As previously mentioned, the patch updated a few system files to support AoE. These files will be updated when you make and install "world" as explained in the FreeBSD Handbook section 19.4, Rebuilding World. Be sure to follow the steps including mergemaster.

Once completed, your system should be ready to use AoE devices.

5. Staying up to date

Once you've patched the standard src distribution you are left with the problem of how to keep the non-AoE parts of your src up to date. The best way to do this is to reverse the AoE patch, run cvsup, and then reapply the AoE patch. If you run cvsup over your patched sources, some files will be stepped on leaving your src distribution in a state where AoE is not functional *and* the AoE patch is useless. If this happens to you, start over from a clean cvsup.

To properly update your system, do the following (using 4.11, eg):

$ cd /usr/src
$ patch -Rusp1 </path/to/aoe-4.11-patch.2
(run cvsup)
$ patch -Cusp1 </path/to/aoe-4.11-patch.2
(and if no errors)
$ patch -usp1 </path/to/aoe-4.11-patch.2

After successfully patching your sources you may update your world and kernel as you see fit.

Please contact support@coraid.com with questions/comments.