User:SwifT/Wikified but not merged documents/Gentoo FreeBSD HOWTO

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.

What is FreeBSD?
FreeBSD is a free (license ) Unix-like operating system. Back in 1993 when development of386BSD 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 longer supported.

What is Gentoo/FreeBSD?
Gentoo/FreeBSD is a subproject of theGentoo/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 , 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.

First, boot the CD in order to begin the installation process. You'll be presented with a login screen. The username is , and there is no password. Next, run  to become root, and optionally setup a password. If you want to pass time during the installation process, you can run  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  :

Finding out the network interface name using ifconfig

If the original DHCP request during the CD bootup failed, you can use the  command to obtain an IP:

Obtaining a DHCP address using dhclient

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

Running the sysinstall command to fdisk the drive

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 , but with different arguments:

Running sysinstall to setup partition sizing and mount points

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. If you do not adjust the mount point, it will overwrite the FreeSBIE environment! As 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.

When choosing a different mountpoint than for your partition,   will actually create a 'd' slice, which the bootloader won't boot from. To fix this, run the following:

Fixing the root partition letter

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

Verifying the new disk layout was mounted with mount

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://distfiles.gentoo.org/experimental/x86/freebsd/stages/, grab the latest snapshot, and unpack it into the mountpoint:

Obtaining and unpacking a stage3 tarball

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

Mounting the /dev filesystem and chrooting

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

Obtaining the Portage tree

Setting up the profile and editing /etc/portage/make.conf

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

Rebuilding the FreeBSD core packages (optional)

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

Set the date and UTC time

Next, set your time zone information by using the correct listing in.

Setting your timezone

Edit to define the time zone you used previously.

Edit /etc/timezone

Kernel Installation
If you ran , the sources for the FreeBSD kernel were installed to. If you skipped this step, you can get them in the following way:

Getting the FreeBSD kernel 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:

Entering the kernel source directory

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

The kernel configuration directory

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

Copying over the GENERIC.hints file

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  command to do this. uses the given file (in this instance GENERIC) to copy over the required build files to a directory in the parent directory. is similiar to the file for the Linux kernel. Run  to produce the build directory:

Configuring the kernel build

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

Building and installing the kernel

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

Setting up the bootloader (boot0)
Installing and setting up boot0

If you need additional information on setting up , 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,.

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

Emerge grub

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

Setting up grub

To make the loader find the kernel on a specific slice (the default is 'a'), add a  line to the  file:

Tell the loader where to look for the kernel

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

Booting the kernel with no menu

System configuration
First, we are going to setup the filesystem mounting points in.

Editing the filesystem in /etc/fstab

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:

Adding your network adapter to the default runlevel

Your system's hostname can be changed in.

Setting up the machine's hostname

You should also configure your domain name, which is done in the file:

Setting the domainname

If you have a NIS domain, you need to define it in the file:

Setting the NIS domainname

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

Changing your keyboard layout (Optional)

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

Changing the root password and adding a new user

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

Rebooting the system

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.

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

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  on Freenode, as well as the gentoo-bsd mailing list.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Ignacio Arque-Latour
 * Michael Kohl
 * Otavio R. Piske
 * Aaron Walker
 * Chris White
 * Diego PettenÃ²
 * Joshua Saddler
 * Camille Huot
 * klondike