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.0, 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 more worked on by the Gentoo/FreeBSD developers.

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

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.

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. Alternatively, you can also use the excellent FreeSBIE LiveCD as an installation medium for Gentoo/FreeBSD.

Before you can begin with the installation, you have to setup a hard disk for use with Gentoo/FreeBSD. This can either be done via sysinstall (available from a current FreeBSD installation as well as from within FreeSBIE) or by manually using the commands fdisk, disklabel and newfs. If you have never set up a FreeBSD system before, sysinstall may be the better option for you. In that case make sure that you don't use the sysinstall launched by FreeBSD's or FreeSBIE's installers, but use the following command instead:

# sysinstall diskPartitionEditor diskPartitionWrite diskLabelEditor diskLabelCommit

If you face difficulties while partitioning or formatting your hard disks, have a look at the great FreeBSD Handbook or hop onto #gentoo-bsd on the Freenode IRC server.

Once you're done setting up your disks, you have to create a mount point for your Gentoo/FreeBSD installation and mount all the necessary partitions.

# mkdir /mnt/gentoo
(Replace X with the correct numbers for your hard disk.)
# mount /dev/adXsXa /mnt/gentoo

If you're using the FreeSBIE LiveCD and you already had an UFS partition on your hard disk, it has already been mounted read-only to /mnt/ufs.1. If you want to use that location for your installation, you'll have to remount it in read-write mode:

# mount -u -o rw /mnt/ufs.1

Now that you have mounted the target partition, it is time to fetch and unpack a stage3 tarball.

# 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.0-stage-20060221.tar.bz2
# tar -jxvpf gentoo-freebsd-6.0-stage-20060221
(You can delete the tarball with the following command if you want to.)
# rm gentoo-freebsd-6.0-stage-20060221

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.

# cd /mnt/gentoo/usr/local/portage
# wget http://gentoo.osuosl.org/experimental/snapshots/portage-alt-overlay-latest.tar.bz2
# tar -xjf portage-alt-overlay-latest.tar.bz2
(You now can safely delete the snapshot with the following command.)
# rm portage-alt-overlay-latest.tar.bz2

Alternatively, you can also use Subversion to check out the current version of the overlay. If you are interested in this possibility, please refer to the Gentoo/ALT overlay documentation.

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.

# mount -t devfs none /mnt/gentoo/dev/
# cp /etc/resolv.conf /mnt/gentoo/etc
# chroot /mnt/gentoo/ /bin/bash
# source /etc/profile

After you got hold of the Gentoo/FreeBSD overlay, it's time to link /etc/make.profile to the correct profile and add get your /etc/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.

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

# ln -sf /usr/local/portage/portage-alt-overlay/profiles/default-bsd/fbsd/6.0/x86/ /etc/make.profile
(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)
# ee /etc/make.conf
(Please make sure you add at least the following entries:)
CHOST="i686-gentoo-freebsd6.0"
ACCEPT_KEYWORDS="~x86-fbsd"
FEATURES="-sandbox collision-protect"
PORTDIR_OVERLAY="/usr/local/portage/portage-alt-overlay"

In order to boot correctly, you will need to create the /proc directory.

# mkdir /proc

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

# emerge -e system

When you did emerge -e system, the sources for the FreeBSD kernel got 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 really 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.

Please note that currently only the "Traditional" way of building the kernel is supported on Gentoo/FreeBSD! Also note that make install will probably ask you for a /boot/device.hints file. A default version can be found in the conf subdirectory of the GENERIC configuration and is called GENERIC.hints.

Now is the time to do some basic system configuration and settings. First, we are going to setup the filesystem mounting points in /etc/fstab.

# ee /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/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 the Gentoo Handbook.

To have your network interface activated at boot time, you have to add it to the default runlevel.

# rc-update add net.rl0 default

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

# ee /etc/conf.d/hostname
(Set the HOSTNAME variable to your hostname)
HOSTNAME="tux"

You should also configure your domain name, which is done in the /etc/conf.d/domainname file:

# ee /etc/conf.d/domainname
(Set the DNSDOMAIN variable to your domain name)
DNSDOMAIN="homenetwork"

If you have a NIS domain, you need to define it in the /etc/conf.d/domainname file:

# ee /etc/conf.d/domainname
(Set the NISDOMAIN variable to your NIS domain name)
NISDOMAIN="my-nisdomain"

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.

# ee /etc/conf.d/syscons
KEYMAP="spanish.iso.acc"
(Possible layouts can be found in /usr/share/syscons/keymaps).

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

# passwd
(If you need help in adding a user please consult the FreeBSD handbook).
# adduser

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

# exit
# reboot

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.

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.

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.