A short guide to Gentoo/FreeBSDIgnacio Arque-LatourMichael KohlOtavio R. PiskeAaron WalkerChris White
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.
2.62006-10-06Introduction to FreeBSDWhat 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 version is 6.1, which is also used as the
foundation for the Gentoo/FreeBSD project. The previous 5.x branch is being
continued by the FreeBSD project as a service release, but is no longer worked
on by the Gentoo/FreeBSD developers.

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.

Installing Gentoo/FreeBSDBooting 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.0! Experimental versions can be downloaded
from FreeSBIE's Bittorrent tracker and
version 20060118 has been tested to work for the purposes described in this document.

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:

There is a bug in the
minimal Freesbie CD that prevents the creation of the
/mnt/gentoo mount point. To avoid this, use /mnt
instead of /mnt/gentoo in the following sections.
Partitioning the Drive

Now that we have a mount point, it's time to partition the drive. This is done
with the sysinstall command:

# 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:

# 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/gentoo. 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
process.

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/gentoo). You can verify this worked by
running mount:

# mount
...
/dev/ad0s1d on /mnt/gentoo (ufs, local)

Now that you have mounted the target partition, 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
http://gentoo.osuosl.org/experimental/x86/freebsd/stages/, grab the
latest snapshot, and unpack it into the mountpoint:

# cd /mnt/gentoo/(Any other Gentoo mirror which includes the experimental/ directory will also work.)
# wget http://gentoo.osuosl.org/experimental/x86/freebsd/stages/gentoo-freebsd-6.1-stage-20060802.tar.bz2
# tar -jxvpf gentoo-freebsd-6.1-stage-20060802.tar.bz2(You can delete the tarball with the following command if you want to.)
# rm gentoo-freebsd-6.1-stage-20060802.tar.bz2

Before chrooting into the newly-extracted stage, you first must obtain an
up-to-date copy of the Gentoo/FreeBSD overlay. The easiest way to achieve this
is to to get our latest snapshot which you then extract to
/mnt/gentoo/usr/local/portage.

Sandbox is disabled as it has not yet been ported to Gentoo/FreeBSD.
You can have a very limited system by using ~x86-fbsd keyword alone; you might
want to put ~x86 in your ACCEPT_KEYWORDS if you want access to more packages
but you might find broken dependencies and non-working packages; please rather
use package.keywords when testing packages and report working ones on Bugzilla for the product Gentoo/Alt.

If you want, you can now rebuild the system's core packages.

# emerge -e system

Setting up for BootingKernel 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:

# 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:

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

# 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:

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:

# 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:

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: grub and boot0.

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.

# emerge grub
# disklabel -B adXsY

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

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

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.

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:

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.

# nano /etc/conf.d/syscons
KEYMAP="spanish.iso.acc"
(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.

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

# exit
# reboot

Developing for Gentoo/FreeBSDHow 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, baselayout,
creation of installation CDs, documentation, kernel hacking.

Known issues

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 BSD" product for your submission.

glib and gnome in general need a lot of fixes to be backported.

The init system currently provided by Gentoo/FreeBSD's baselayout package is
not the same version used by Gentoo Linux and lacks some of its features. Work
on making newer versions working is underway.

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.