Gentoo Logo

A short guide to Gentoo/FreeBSD


1.  Introduction to FreeBSD

What is FreeBSD?

FreeBSD is a free (license) Unix-like operating system. Back in 1993 when development of 386BSD stopped, two projects were born: NetBSD, commonly known to run on a huge number of architectures, and FreeBSD which supports the x86, amd64, ia64, sparc64 and alpha platforms. FreeBSD is renowned for its stability, performance and security, thus being used from small to huge companies all over the world.

FreeBSD's current production release is version 7.1. Gentoo/FreeBSD is based on this version and older versions of Gentoo/FreeBSD are discontinued and no longer supported.

What is Gentoo/FreeBSD?

Gentoo/FreeBSD is a subproject of the Gentoo/Alt project, with the goal of providing a fully-capable FreeBSD operating system featuring design sensibilities taken from Gentoo Linux, such as the init system and the Portage package management system.

FreeBSD and Linux

Users migrating from Linux to FreeBSD commonly consider the two operating systems "almost the same". In fact, FreeBSD really shares a lot of similarities with Linux distributions in general. Nevertheless, it has some key differences that are worth noting:

  • Contrary to Linux, which actually only refers to the kernel, FreeBSD is a complete operating system, consisting of a C library, userland tools and much more. This development approach makes the overall system very consistent.
  • Contrary to the Linux kernel, FreeBSD development is not led by one person, but instead managed by a small group of people called the Core Team.

Besides, FreeBSD also has some technical differences which set it apart from Linux. Some of them are very important to know, even if you don't plan on joining the Gentoo/FreeBSD development effort:

  • To get run-time dynamic linking functions like dlopen(), programs do not need to be linked against libdl like on GNU/Linux. Instead they are linked against libc.
  • FreeBSD doesn't have an official tool for kernel compilation, thus you'll have to resolve feature dependencies on your own.
  • FreeBSD uses UFS/UFS-2 as its filesystems and has no official support for e.g. ReiserFS or XFS. However, there are projects for adding read-only support for these filesystems. Accessing ext2/ext3 partitions is already possible, but you cannot install your system on them. Version 7.0 added support for the ZFS filesystem.

2.  Installing Gentoo/FreeBSD

Booting the CD

After this short introduction, it's about time to finally install Gentoo/FreeBSD. We have an experimental mini bootcd that should be enough to proceed with the installation. It can be downloaded from our mirrors or this place.

First, boot the CD in order to begin the installation process. You will be presented with root prompt in a way pretty similar to the Gentoo/Linux installcds. There is no password. Unlike Linux, FreeBSD bases the name of your interface on the driver for the interface. For example, the Intel EtherExpress driver (fxp) appears as fxp0 (driver fxp, first network card). To see what your interface is, use ifconfig:

Code Listing 2.1: Finding out the network interface name using ifconfig

# ifconfig
        inet6 fe80::2d0::b7ff:febc:4fe3%fxp0 prefixlen 64 scopeid 0x1
        inet netmask 0xffffff00 broadcast
        ether 00:d0:b7:bc:4f:e3
        media: Ethernet autoselect (100baseTX <full-duplex>)
        status: active
lo0: flags=8007<LOOPBACK,MULTICAST> mtu 16384

Note: The output presented here will differ based on your network.


This can be done in several ways. If you are a Linux user and feel more comfortable with Linux partitioning tools, and you want to share the disk with a linux installation, please use what you already know to make a primary partition for Gentoo/FreeBSD. On the BSD land, partitions are called slices which is where labels are created to hold each filesystem.

Note: You can create up to 7 labels on a single slice, so all you really need is just a free primary partition.

If you are working from Linux fdisk, make sure the partition type is set to 0xa5 or 165 (FreeBSD). However, if you are going to use the whole disk for Gentoo/FreeBSD, the bootcd's fdisk will do the job just fine.

Note: If you are not familiar with these commands, please read the online manpages, they will make your life easier and less disaster-prone.

Code Listing 2.2: Running fdisk

# fdisk -u ad0

This will enter an interactive mode that will ask if you want to change anything on each "slice". You can skip existing ones until you get to your desired slice/partition. If you intend to use the whole disk, just run it with -i to clear the entire partition table. If you want to use the default FreeBSD bootloader add -B, or if you like the alternative boot0 use -b /boot/boot0 -B

Note: You can also make use of the config file functionality of FreeBSD fdisk with the -f parameter.

Make sure the slice is big enough to hold a portage tree and a swap label. More on portage tree size problems regarding inodes later.

This next step is done with disklabel. We will now create the labels that will hold the root filesystem and everything else.

Code Listing 2.3: Running disklabel

# disklabel -e ad0s1

If you check the manpage the format is pretty simple. the "a" label must be reserved for the "/" filesystem, aka "root", "b" label is reserved for swap space, and "c" is reserved as it defines the entire disk, must not be touched.

For the sizes of each filesystem please take a look at the FreeBSD Handbook, the swap recommendation can be ignored with nowadays ram memory sizes, but we may need a bigger /var label if we want to compile big things on Gentoo/FreeBSD

Now it's time to run newfs on our newly created labels. There are some things to consider before issuing the command for the root ("/") and /usr filesystems: The filesystem from where the kernel is loaded must not have soft_updates enabled; Our /usr filesystem must have enough inodes to hold the portage tree and the kernel soure tree (roughly over 20k inodes), plus a bit more for us to play with. Check newfs manpage for details, specifically -b -f and -i flags.

Code Listing 2.4: Creating filesystems

# newfs -L root -O2 -n /dev/ad0s1a
/dev/ad0s1a: 512.0MB (1048576 sectors) block size 16384, fragment size 2048
        using 4 cylinder groups of 128.02Mb, 8193 blks, 16448 inodes.
super-block backups (for fsck -b #) at:
 160, 262336, 524512, 786688
GEOM_LABEL: Label for provider ad0s1a is ufs/root.
# newfs -L usr -O2 -U -n -b 4096 /dev/ad0s1d
/dev/ad0s1d: 2508.8MB (5137944 sectors) block size 4096, fragment size 2048
        using 73 cylinder groups of 34.41Mb, 8808 blks, 4416 inodes.
super-block backups (for fsck -b #) at:
GEOM_LABEL: Label for provider ad0s1d is ufs/usr.
# newfs -L var -O2 -U -n /dev/ad0s1e
GEOM_LABEL: Label for provider ad0s1e is ufs/var.

Note: The GEOM_LABEL: are kernel messages stating that a new label provider was found on the specified device. This means you can access the same device, automagically, at boot time as /dev/ufs/root for /dev/ad0s1a or /dev/ufs/usr for /dev/ad0s1d

Now it's time to mount the filesystems. We have to mount "/usr" and "/var" on top of the mounted root filesystem, so let's proceed in order.

Code Listing 2.5: Mounting filesystems

# mount /dev/ufs/root /mnt/gentoo
# mkdir /mnt/gentoo/usr
# mkdir /mnt/gentoo/var
# mount /dev/ufs/usr /mnt/gentoo/usr
# mount /dev/ufs/var /mnt/gentoo/var

Now that you have created and mounted every filesystem required, it is time to start on the Gentoo setup.

Gentoo Setup

First, we need to download a stage3 tarball and unpack it into the chroot. Point your browser to, grab the latest snapshot, and unpack it into the mountpoint:

Code Listing 2.6: Obtaining and unpacking a stage3 tarball

# cd /mnt/gentoo
(Any other Gentoo mirror which includes the experimental/ directory will also work.)
# wget
# tar -jxvpf stage3-x86-freebsd-7.1.tar.bz2
(You can delete the tarball with the following command if you want to.)
# rm stage3-x86-freebsd-7.1.tar.bz2

In order for your install to work, you need to mount the /dev and /proc filesystems from the currently running system into the Gentoo/FreeBSD mount point before proceeding with the chroot.

Code Listing 2.7: Mounting the /dev & /proc filesystem and chrooting

# mount -t devfs none /mnt/gentoo/dev/
No need to mount another "procfs", we just bind the one already mounted
# mount_nullfs /proc /mnt/gentoo/proc
# cp /etc/resolv.conf /mnt/gentoo/etc/
# chroot /mnt/gentoo /bin/bash
# env-update && source /etc/profile

Now it's time to link /etc/make.profile to the correct profile and get your /etc/make.conf ready for Gentoo/FreeBSD.

You have to obtain a copy of the main Gentoo Portage tree, which depending on your connection might take quite a while.

Code Listing 2.8: Obtaining the Portage tree

# emerge --sync
(It's also possible to retrieve the Portage tree in another way:)
# cd /usr
# wget
# tar -xjf portage-latest.tar.bz2 -C /usr/

Code Listing 2.9: Setting up the profile and editing /etc/make.conf

# ln -sf /usr/portage/profiles/default/bsd/fbsd/x86/7.1 /etc/make.profile
# nano /etc/make.conf
(Please make sure you add at least the following entries:)

Note: The ~x86-fbsd keyword does not yet fully cover the same tree as ~x86, but please do not put ~x86 in ACCEPT_KEYWORDS. Rather use /etc/portage/package.keywords to test packages, and report working packages on Bugzilla.

If you changed the CHOST from the stage's default, you can now rebuild the system's core packages.

Code Listing 2.10: Rebuilding the FreeBSD core packages (optional)

(Verify gcc-config has gcc setup properly:)
# gcc-confing -l
(And, if required:)
# gcc-config 1
Now emerge the following in order:
# emerge binutils gcc
# emerge libtool
# emerge python libperl perl
At this point the toolchain should be well aware of the new CHOST
# emerge -e system

3.  Setting up for Booting

Set your time zone

First make sure your date and time is set correctly using date yyyymmddHHMM. Use UTC time.

Code Listing 3.1: Set the date and UTC time

(Check the clock)
# date
Mon Mar  6 00:14:13 UTC 2009

(Set the current date and time if required)
# date 200903060016 (Format is yyyymmddHHMM)
Mon Mar  6 00:16:00 UTC 2009

Next, set your time zone information by using the correct listing in /usr/share/zoneinfo.

Code Listing 3.2: Setting your timezone

# ls /usr/share/zoneinfo
(Using Brussels as an example)
# cp /usr/share/zoneinfo/Europe/Brussels /etc/localtime

# date
Wed Mar  8 00:46:05 CET 2006

Kernel Installation

If you ran emerge -e system, the sources for the FreeBSD kernel were installed to /usr/src/sys. If you skipped this step, you can get them in the following way:

Code Listing 3.3: Getting the FreeBSD kernel sources

# emerge freebsd-sources

Configuring and compiling a custom kernel is quite different from compiling Linux, so if you are not familiar with the process we encourage you to have a look at chapter 8 of the FreeBSD handbook. For now, you can do an installation of the GENERIC kernel, which works on most systems. To begin, enter the source directory for the kernel:

Important: Please note that currently only the "Traditional" way of building the kernel is supported on Gentoo/FreeBSD!

Code Listing 3.4: Entering the kernel source directory

# cd /usr/src/sys/

Looking over the layout, you'll see various architectures and subdirectories for various parts of the kernel. To begin the installation, we head into the i386/conf/ directory:

Code Listing 3.5: The kernel configuration directory

# cd i386/conf/
# ls
.cvsignore      GENERIC         Makefile        PAE
DEFAULTS        GENERIC.hints   NOTES           SMP

The main files to note are GENERIC and GENERIC.hints. As it will be needed by the installation of the kernel, go ahead and copy GENERIC.hints file to /boot/device.hints:

Code Listing 3.6: Copying over the GENERIC.hints file

# cp GENERIC.hints /boot/device.hints

This file is used by the kernel drivers for basic configuration information such as IRQ and video settings. Now it's time to configure the kernel. FreeBSD uses the config command to do this. config uses the given file (in this instance GENERIC) to copy over the required build files to a compile directory in the parent directory. GENERIC is similiar to the .config file for the Linux kernel. Run config to produce the build directory:

Code Listing 3.7: Configuring the kernel build

# config GENERIC
Kernel build directory is ../compile/GENERIC
Don't forget to ''make cleandepend; make depend''

config has created a GENERIC build directory for us in the parent directory. cd into it, then run the following to do a complete build:

Code Listing 3.8: Building and installing the kernel

# cd ../compile/GENERIC
# make cleandepend && make depend && make && make install

This will give us a complete kernel to work with. Now we'll need to setup the bootloader for the kernel to boot. The next chapter will discuss two methods of setting up the bootloader: boot0 and grub.

Setting up the bootloader (boot0)

Important: boot0 is the FreeBSD bootloader. Previously, it was the only supported bootloader until grub was introduced into ports with UFS slice support. To install and configure boot0, run the following. Remember to replace adXsY with the actual number and slice of your disk.

Code Listing 3.9: Installing and setting up boot0

# emerge boot0
(Leave the chroot environment)
# exit
(Issued from outside the chroot)
# fdisk -B -b /mnt/gentoo/boot/boot0 /dev/adX
# chroot /mnt/gentoo /bin/bash
# disklabel -B adXsY

If you need additional information on setting up boot0, please consult chapter 12 of the FreeBSD handbook. Now it's time to do some basic system configuration and settings.

The next section will look at using the alternative bootloader, grub.

Setting up the bootloader (grub)

As of grub 0.97-r1, UFS slices are readable to grub. This lets us use grub as a bootloader, the prefered method for those coming from a Linux background. To begin, emerge grub and setup the label as bootable. Remember to replace adXsY with the actual number and slice of your disk.

Code Listing 3.10: Emerge grub

# emerge grub
# disklabel -B adXsY

Now run grub to bring up the command prompt, and set up the partition as shown:

Code Listing 3.11: Setting up grub

(This is done to prevent disk error 29)
# sysctl kern.geom.debugflags=16
# grub
(Example using ad0s1d)
grub> root (hd0,0,d)
 Filesystem type is ufs2, partition type 0xa5

grub> setup (hd0)
 Checking if "/boot/grub/stage1" exists... yes
 Checking if "/boot/grub/stage2" exists... yes
 Checking if "/boot/grub/ufs2_stage1_5" exists... yes
 Running "embed /boot/grub/ufs2_stage1_5 (hd0)"... 14 sectors are embedded.
 Running "install /boot/grub/stage1 (hd0) (hd0)1+14 p (hd0,0,d)/boot/grub/stage
2 /boot/grub/menu.lst"... succeeded

grub> quit

To make the loader find the kernel on a specific slice (the default is 'a'), add a vfs.root.mountfrom line to the /boot/loader.conf file:

Code Listing 3.12: Tell the loader where to look for the kernel

# echo 'vfs.root.mountfrom="ufs:ad0s1d"' >> /boot/loader.conf

When you first boot, you may not receive a grub menu. If so, run this at the prompt:

Code Listing 3.13: Booting the kernel with no menu

grub> find /boot/grub/stage1
(The output here is what you'll use in the next command)

grub> kernel (hd0,0,d)/boot/loader
  [FreeBSD-a.out, loadaddr=0x200000, text=0x1000, data=0x3a000, bss=0x0, entry=0x200000]

grub> boot

Note: For more information on configuring grub, please refer to the Gentoo Linux Handbook.

Warning: Grub doesn't follow UFS symlinks so be sure to delete the /boot/grub/menu.lst symlink and to use menu.lst to setup Grub (grub.conf isn't used).

System configuration

First, we are going to setup the filesystem mounting points in /etc/fstab.

Code Listing 3.14: Editing the filesystem in /etc/fstab

# nano /etc/fstab
(This is an example, replace X and Y with the correct numbers for your hard disk.)
#Device         Mountpoint      Fstype          Options         Dump    Pass
/dev/adXsYb     none            swap            sw              0       0
/dev/adXsYa     /               ufs             rw              1       1
/dev/adXsYe     /usr            ufs             rw              2       2
/dev/adXsYd     /var            ufs             rw              2       2
/dev/acdX       /cdrom          cd9660          ro,noauto       0       0

Or using the labels given to each filesystem with newfs -L:

Code Listing 3.15: /etc/fstab using GEOM labels

#Device         Mountpoint      Fstype          Options         Dump    Pass
/dev/adXsYb     none            swap            sw              0       0
/dev/ufs/root   /               ufs             rw              1       1
/dev/ufs/usr    /usr            ufs             rw              2       2
/dev/ufs/var    /var            ufs             rw              2       2
/dev/acdX       /cdrom          cd9660          ro,noauto       0       0

Now would also be a good time to set up your network connection before the final reboot. You can find all the information necessary to configure your network in the Gentoo Handbook. To have your network interface activated at boot time, you have to add it to the default runlevel:

Code Listing 3.16: Adding your network adapter to the default runlevel

# rc-update add net.fxp0 default

Your system's hostname can be changed in /etc/conf.d/hostname.

Code Listing 3.17: Setting up the machine's hostname

# nano /etc/conf.d/hostname
(Set the HOSTNAME variable to your hostname)

Note: For more information on domainnames and networking, please refer to the Gentoo Linux Handbook, and please read the documentation in /etc/conf.d/net.example.

In case you need to use another keyboard layout for your language, you have to set the correct value in /etc/conf.d/syscons. The following example uses the Spanish layout, so you'll have to adjust it to your need if you want to use another one.

Code Listing 3.18: Changing your keyboard layout (Optional)

# nano /etc/conf.d/syscons
(Possible layouts can be found in /usr/share/syscons/keymaps).

Now would be a good time to set a password for the root user and to add another user account for your day-to-day work.

Code Listing 3.19: Changing the root password and adding a new user

# passwd
# adduser
Username: fred
Full Name: Fred Smith
(Accepting the default here, just hit Enter.)
Uid (Leave empty for default):
(OK to accept the default here as well; hit Enter.)
Login group [fred]:
(Enter your groups here, space separated. They must exist.)
Login group is fred. Invite fred into other groups? []: wheel portage
(OK to accept the default here, hit Enter)
Login class [default]:
(Somewhat of a personal preference.  Make sure the shell exists in /etc/shells)
Shell (sh bash tcsh csh esh ksh zsh sash nologin) [sh] bash
(OK to accept the default here, hit Enter for all these)
User password-based authentication [yes]
Use an empty password (yes/no) [no]:
Use a random password? (yes/no) [no]:
Enter password: password goes here
Enter password again: retype it
(OK to accept the default here, hit Enter)
Lock out the account after creation? [no]:
Username    : fred
Password    : *****
Full Name   : Fred Smith
(This will vary)
Uid         : 1002
Class       :
Groups      : fred wheel portage
Home        : /home/fred
Shell       : /bin/bash
Locked      : no
(Confirm the information is correct)
OK? (yes/no): yes
adduser: INFO: Sucessfully added (fred) to the user database
Add another user? (yes/no): no

Congratulations, you have just finished your Gentoo/FreeBSD installation which you can start exploring after the final reboot. Have fun!

Code Listing 3.20: Rebooting the system

# exit
# shutdown -r now

4.  Developing for Gentoo/FreeBSD

How to help

There are many things you could help with, depending on your skill level and spare time:

  • Working on current ebuilds: this means working closely with ebuild maintainers in order to create patches or modify ebuilds in a way that can be accepted into the main tree.
  • Security: if you are into security, we need you! Although security advisories from the FreeBSD project are tracked and fixed, we can always use help in this area.
  • Contacts: we need people who can get in touch with FreeBSD developers to maintain contacts between us and the original project to exchange patches and discuss various problems and their solutions. Note that this should never involve any kind of spamming of mailing lists or IRC channels.
  • Testing: the more people are actively using Gentoo/FreeBSD, the more bugs will be discovered, which helps us improving the quality of the port. If you are good at describing bugs or problems, we definitely want to hear from you.
  • Other areas where we need help include: system ebuilds, creation of installation CDs, documentation, kernel hacking.

5.  Contact

A list of Gentoo/FreeBSD developers can be found at the project page. Other ways to contact Gentoo/FreeBSD developers include our IRC Channel #gentoo-bsd on Freenode, as well as the gentoo-bsd mailing list.


Page updated January 24, 2009

Summary: This document gives some general information on FreeBSD, as well as installation instructions for Gentoo/FreeBSD. It also includes some reference for people interested in helping out with development.

Ignacio Arque-Latour

Michael Kohl

Otavio R. Piske

Aaron Walker

Chris White

Diego Pettenò

Javier Villavicencio

Joshua Saddler

Camille Huot

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.