This document is not valid and is not maintained anymore.
A short guide to Gentoo/FreeBSD
Introduction to FreeBSD
What is FreeBSD?
Be sure to read the Gentoo/FreeBSD wiki page for up-to-date
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
version 6.2 and older versions of Gentoo/FreeBSD are discontinued and no
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
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
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.
Booting the CD
After this short introduction, it's about time to finally install
Gentoo/FreeBSD. Unfortunately, we currently lack our own installation media, so
you have to choose between two alternative installation methods. The first
would be to use an existing FreeBSD installation to partition your hard drive
and use it as a base for installing Gentoo/FreeBSD. This guide will describe how
to use the FreeSBIE LiveCD as
an installation medium for Gentoo/FreeBSD.
If you are intending to use FreeSBIE for installing Gentoo/FreeBSD, please make
sure to use a version based on FreeBSD 6.x, such as FreeSBIE 2.0 (or one of its
release candidates). You can download it from FreeSBIE's Bittorrent tracker.
First, boot the CD in order to begin the installation process. You'll be
presented with a login screen. The username is freesbie, and there is
no password. Next, run sudo su to become root, and optionally setup a
password. If you want to pass time during the installation process, you can run
startx to enter into an Xfce environment, suitable for web browsing,
AIM, and other things. 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
fxp0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::2d0::b7ff:febc:4fe3%fxp0 prefixlen 64 scopeid 0x1
inet 192.168.0.106 netmask 0xffffff00 broadcast 192.168.0.255
media: Ethernet autoselect (100baseTX <full-duplex>)
lo0: flags=8007<LOOPBACK,MULTICAST> mtu 16384
If the original DHCP request during the CD bootup failed, you can use the
dhclient command to obtain an IP:
Code Listing 2.2: Obtaining a DHCP address using dhclient
# dhclient fxp0
DHCPDISCOVER on fxp0 to 255.255.255.255 port 67 interval 9
DHCPOFFER from 192.168.0.1
DHCPREQUEST on fxp0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.1
bound to 192.168.0.106 -- renewal in 302400 seconds
The output presented here will differ based on your network.
Partitioning the Drive
Now that we have a mount point, it's time to partition the drive. This is done
with the sysinstall command:
Code Listing 2.3: Running the sysinstall command to fdisk the drive
# sysinstall diskPartitionEditor diskPartitionWrite
We recommend that you use the default layout. Press enter at the dialog, then
press a followed by q to accept the default layout. The next
screen will present you with the option of a bootloader. For this option,
choose "None" as we'll be installing the bootloader later on. Next comes the
actual partition sizing and mount points.
This next step also uses sysinstall, but with different arguments:
Code Listing 2.4: Running sysinstall to setup partition sizing and mount points
# sysinstall diskLabelEditor diskLabelCommit
Here, we'll refrain from using the automatic layout, and create one giant root
partition, followed by a swap partition. Hit c to create a new
partition. A dialog prompts you to enter a size. Go ahead and do so, using
MB/GB for setting different sizes, or C for cylinders. For root, choose FS as
the partition type, and set the mount point as /mnt/. If
you do not adjust the mount point, it will overwrite the FreeSBIE
environment! As /boot is not a separate partition, you'll
need to disable soft-updates, or your system will not boot! To do so, use the
arrow keys to navigate to your newly created partition, then hit the s
key, until "Newfs" contains no +S. Now navigate the arrow keys until
the "Disk" line is highlighted, and hit c again to create a swap
partition. Generally, we recommend a swap space that is twice the size of your
RAM. Choose SWAP as the partition type, and don't worry about soft-updates, as
it does not apply to swap. Now we're finished, so hit q to finish the
When choosing a different mountpoint than / for your partition,
sysinstall will actually create a 'd' slice, which the bootloader won't
boot from. To fix this, run the following:
Please, make sure ad0s1 is unmounted before running the following command,
otherwise it will not work.
Code Listing 2.5: Fixing the root partition letter
# disklabel ad0s1 | sed 's/^ d:/ a:/' | disklabel -R ad0s1 /dev/stdin
This will finalize the partitioning process, and format the drive in UFS for
FreeBSD to utilize. This will also mount the drive for you at the mount point
specified earlier (/mnt/). You can verify this worked by
Code Listing 2.6: Verifying the new disk layout was mounted with mount
/dev/ad0s1a on /mnt (ufs, local)
Now that you have mounted the target partition, it is time to start on the
First, we need to download a stage3 tarball and unpack it into the chroot.
Point your browser to
http://distfiles.gentoo.org/experimental/x86/freebsd/stages/, grab the
latest snapshot, and unpack it into the mountpoint:
Code Listing 2.7: Obtaining and unpacking a stage3 tarball
# cd /mnt/
# wget http://distfiles.gentoo.org/experimental/x86/freebsd/stages/stage3-x86-freebsd-6.2-r1.tar.bz2
# tar -jxvpf stage3-x86-freebsd-6.2-r1.tar.bz2
# rm stage3-x86-freebsd-6.2-r1.tar.bz2
If you want you can use the transition overlay that contains semi-experimental
ebuilds with patches not yet in the main Portage tree, but does allow a wider
range of supported packages, please refer to the Gentoo/ALT
overlay documentation. Please note that the overlay is not critical and
you can easily install and use Gentoo/FreeBSD without it.
In order for your install to work, you need to mount the /dev
filesystem from the currently running system into the Gentoo/FreeBSD mount
point before proceeding with the chroot.
Code Listing 2.8: Mounting the /dev filesystem and chrooting
# mount -t devfs none /mnt/dev/
# cp /etc/resolv.conf /mnt/etc/
# chroot /mnt/ /bin/bash
# env-update && source /etc/profile
After you obtain the Gentoo/FreeBSD overlay, it's time to link
/etc/portage/make.profile to the correct profile and get your
/etc/portage/make.conf ready for Gentoo/FreeBSD.
Now, 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.9: Obtaining the Portage tree
# emerge --sync
# cd /
# wget http://distfiles.gentoo.org/snapshots/portage-latest.tar.bz2
# tar -xjf portage-latest.tar.bz2 -C /usr/
# emerge --metadata
Code Listing 2.10: Setting up the profile and editing /etc/portage/make.conf
# ln -sf /usr/portage/profiles/default-bsd/fbsd/6.2/x86/ /etc/portage/make.profile
# nano /etc/portage/make.conf
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.accept_keywords to test packages, and
report working packages on Bugzilla.
If you want, you can now rebuild the system's core packages.
Code Listing 2.11: Rebuilding the FreeBSD core packages (optional)
# emerge -e system
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
Mon Mar 6 00:14:13 UTC 2006
# date 200603060016
Mon Mar 6 00:16:00 UTC 2006
Next, set your time zone information by using the correct listing in
Code Listing 3.2: Setting your timezone
# ls /usr/share/zoneinfo
# cp /usr/share/zoneinfo/Europe/Brussels /etc/localtime
Wed Mar 8 00:46:05 CET 2006
Edit /etc/timezone to define the time zone you used
Code Listing 3.3: Edit /etc/timezone
# nano -w /etc/timezone
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.4: 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
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:
Please note that currently only the "Traditional" way of building the kernel is
supported on Gentoo/FreeBSD!
Code Listing 3.5: 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
Code Listing 3.6: The kernel configuration directory
# cd i386/conf/
.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.7: 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 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.8: 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.9: 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)
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.10: Installing and setting up boot0
# emerge boot0
# fdisk -B -b /mnt/boot/boot0 /dev/adX
# chroot /mnt/ /bin/bash
# disklabel -B adXsY
If you need additional information on setting up boot0, please consult
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.11: Emerge grub
# emerge grub
# disklabel -B adXsY
Now run grub to bring up the command prompt, and set up the partition as
Code Listing 3.12: Setting up grub
# sysctl kern.geom.debugflags=16
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
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
Code Listing 3.13: 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
Code Listing 3.14: Booting the kernel with no menu
grub> find /boot/grub/stage1
grub> kernel (hd0,0,d)/boot/loader
[FreeBSD-a.out, loadaddr=0x200000, text=0x1000, data=0x3a000, bss=0x0, entry=0x200000]
For more information on configuring grub, please refer to the Gentoo
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).
First, we are going to setup the filesystem mounting points in
Code Listing 3.15: Editing the filesystem in /etc/fstab
# nano /etc/fstab
#Device Mountpoint Fstype Options Dump Pass
/dev/adXsYb none swap sw 0 0
/dev/adXsYa / ufs rw 1 1
/dev/adXsYe /usr/home ufs rw 2 2
/dev/adXsYd /tmp 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
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
You should also configure your domain name, which is done in the
Code Listing 3.18: Setting the domainname
# nano /etc/conf.d/domainname
If you have a NIS domain, you need to define it in the
Code Listing 3.19: Setting the NIS domainname
# nano /etc/conf.d/domainname
For more information on domainnames and networking, please refer to the Gentoo
Linux Handbook, and please read the documentation in
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.20: Changing your keyboard layout (Optional)
# nano /etc/conf.d/syscons
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.21: Changing the root password and adding a new user
Full Name: Fred Smith
Uid (Leave empty for default):
Login group [fred]:
Login group is fred. Invite fred into other groups? : wheel portage
Login class [default]:
Shell (sh bash tcsh csh esh ksh zsh sash nologin) [sh] bash
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
Lock out the account after creation? [no]:
Username : fred
Password : *****
Full Name : Fred Smith
Uid : 1002
Groups : fred wheel portage
Home : /home/fred
Shell : /bin/bash
Locked : no
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.22: Rebooting the system
Developing for Gentoo/FreeBSD
How to help
There are many things you could help with, depending on your skill level and
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
Other areas where we need help include: system ebuilds, creation of
installation CDs, documentation, kernel hacking.
At the moment, there are still quite a lot of known issues. Here are the ones
really worth noting:
Some init scripts depend on the clock service which we don't provide right
now. You can just remove it from the dependencies of the script and report
that on our Bugzilla. Please
remember to use the "Gentoo/Alt" product for your submission.
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
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.