Gentoo FreeBSD

From Gentoo Wiki
Jump to: navigation, search
Sometimes, Gentoo/FreeBSD's @system is broken.

Please get latest information from "Depends on" of bug #462580.

Gentoo/FreeBSD is a Gentoo system based on FreeBSD. It is FreeBSD with the following changes:

  • Portage replaces ports.
  • The base system is managed by portage.
  • Software in ./contrib and ./crypto is replaced with Gentoo Linux versions.
  • The rc system is replaced with OpenRC.
  • Python, wget and bash are included in the base system to support portage.
  • FreeBSD's bootloader is removed from the base system (useful for jails).
Gentoo FreeBSD is not 100% binary-compatibility with regular FreeBSD due to SONAME differences. It is possible to workaround that by running regular FreeBSD in either a jail or chroot on Gentoo FreeBSD or vice versa.

Gentoo FreeBSD is also not 100% script-compatible with regular FreeBSD by default. Script compatibility can be restored by installing sys-freebsd/ubin-wrappers. This makes it possible to use *BSD software like pkgsrc.


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 11.0. Gentoo/FreeBSD is based on version 11.0 and older versions of Gentoo/FreeBSD are discontinued and no longer supported.

What is Gentoo/FreeBSD?

FreeBSD project is a sub-project of the Alt project 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 supports UFS/UFS2 and ZFS as native file systems.
  • FreeBSD also supports Linux filesystems, but you cannot install your system on them. ext2/ext3 supports read/write access. ReiserFS, XFS are read-only support. details please see FreeBSD's handbook 21.3. Linux® Filesystems


Part of x86-fbsd is out of date. Please install amd64-fbsd.


This guide provide minimal information about Gentoo/FreeBSD. You need specialized knowledge of Gentoo/Linux and FreeBSD. The Gentoo Linux Handbook and FreeBSD Handbook should be close friends.


Gentoo/FreeBSD doesn't have install media. Instead, you can use vanilla FreeBSD 9.0 or later version install media. Please get i386 or amd64 image. Of course, you can install Gentoo/FreeBSD with -bootonly.iso. Write to a CD or memory stick as necessary.

Boot your PC with a installation CD. Wait for display a dialog. Please choose Live CD, if a Welcome screen is displayed. Then login prompt, enter root.

If you have 4KB/sector HDD (aka AFT Drive)

Please select "2. [Esc]ape to loader prompt" at boot time if you have a 4KB/sector HDD.

Set the device name of your HDD with 4KB sectors in the boot loader. ada1 and ada2... to increase if you have more than one.


Optional: Setting keymap

If your keyboard is not an English 101 keyboard, please set keymap.

root #kbdcontrol -l uk.iso

A list of key map is available with the following command.

root #ls -1 /usr/share/syscons/keymaps | less

Network setting

First, create a directory /tmp/bsdinstall_etc to rewrite the resolv.conf:

root #mkdir -p /tmp/bsdinstall_etc

Identify your network devices. In this example the network interface is em0:

root #ifconfig
em0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
        ether 00:00:00:00:00:00
        media: Ethernet autoselect (1000baseT <full-duplex>)
        status: active
lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384
        inet6 ::1 prefixlen 128
        inet6 fe80::1%lo0 prefixlen 64 scopeid 0x3
        inet netmask 0xff000000
        nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL>

Set the default gateway and IP address.

When setting a static address:

root #ifconfig em0
root #route add default
root #echo "nameserver" > /etc/resolv.conf

When using DHCP:

root #dhclient em0

Optional: Installing via ssh

root #mkdir -p /tmp/etc
root #mount -t tmpfs tmpfs /tmp/etc
root #mount -t unionfs /tmp/etc /etc
root #passwd
root #echo "PermitRootLogin yes" >> /etc/ssh/sshd_config
root #/etc/rc.d/sshd onestart

Please connect with any ssh client. The username is root.

Setting the partition

grub2 doesn't have KEYWORDS="~amd64-fbsd ~x86-fbsd" yet. sys-freebsd/boot0 is recommended for bootloader on Gentoo/FreeBSD.
If you want to use grub2, you need 1 MB free space at the beginning of the disk (MBR) or bios-boot partition (GPT).

grub2 can not find freebsd-boot partition. Please set the bios-boot (GPT).

The installation target device of serial ATA and IDE are /dev/ada*. SCSI and USB drive are /dev/da*. Please identify the HDD using ls /dev/ada* or dmesg | grep ada. In this case, the device is ada0:

root #dmesg | grep ada
ada0 at ata0 bus 0 scbus0 target 0 lun 0
ada0: <QEMU HARDDISK 0.15.> ATA-7 device
ada0: 16.700MB/s transfers (WDMA2, PIO 8192bytes)
ada0: 12288MB (25165824 512 byte sectors: 16H 63S/T 16383C)
ada0: Previously was known as ad0
Using the UFS2 file system (GPT)
GPT partition is the standard FreeBSD 9.0. Please read the next MBR section if you want use a MBR partition.

This example is simple only two partitions. If necessary, you can split /, /usr, /var, /tmp, and /home. Please set using gpart.

Partition Filesystem Size Description
/dev/ada0p1 none just a bit Reserved for bootloader
/dev/ada0p2 UFS2 + SU entire disk - swap space Root partition
/dev/ada0p3 swap Rest of the disk Swap partition
Please add options -a 4k to gpart add command of all, if you have AFT drive (4096 bytes/sector). Start of the partition is properly configured, you can get the best performance.
Using FreeBSD's default bootloader. [Recommend]
root #gpart create -s GPT ada0
root #gpart add -s 64k -t freebsd-boot ada0
root #gpart add -s 10G -t freebsd-ufs -l root ada0
root #gpart add -t freebsd-swap -l swap ada0

Please run gpart show in order to confirm results.

root #gpart show
=>      34  25165757  ada0  GPT  (12G)
        34       128     1  freebsd-boot  (64k)
       162  20971520     2  freebsd-ufs  (10G)
  20971682   4194109     3  freebsd-swap  (2G)

Results when you create a partition with option -a 4k.

root #gpart show
=>      34  25165757  ada0  GPT  (12G)
        34         6        - free -  (3.0k)
        40       128     1  freebsd-boot  (64k)
       168  20971520     2  freebsd-ufs  (10G)
  20971688   4194096     3  freebsd-swap  (2G)
  25165784         7        - free -  (3.5k)
Using grub2. [Experimental]
root #gpart create -s GPT ada0
root #gpart add -s 1024k -t bios-boot ada0
root #gpart add -s 10G -t freebsd-ufs -l root ada0
root #gpart add -t freebsd-swap -l swap ada0
Using the UFS2 file system (MBR)
Partition Filesystem Size Description
/dev/ada0s1a UFS2 + SU entire disk - swap space Root partition
/dev/ada0s1b swap Rest of the disk Swap partition
Using FreeBSD's default bootloader. [Recommend]
root #gpart create -s mbr ada0
root #gpart add -t freebsd ada0
root #gpart set -a active -i 1 ada0
root #gpart create -s bsd ada0s1
root #gpart add -s 10G -t freebsd-ufs ada0s1
root #gpart add -t freebsd-swap ada0s1
Using grub2. [Experimental]
root #gpart create -s mbr ada0
root #gpart add -b 1024k -t freebsd ada0
root #gpart set -a active -i 1 ada0
root #gpart create -s bsd ada0s1
root #gpart add -s 10G -t freebsd-ufs ada0s1
root #gpart add -t freebsd-swap ada0s1
Using the ZFS file system (experimental) / (GPT)
Using FreeBSD's default bootloader. [Recommend]
root #gpart create -s GPT ada0
root #gpart add -s 64k -t freebsd-boot ada0
root #gpart add -t freebsd-zfs -l zfs-system ada0
Using grub2. [Experimental]
root #gpart create -s GPT ada0
root #gpart add -s 1024k -t bios-boot ada0
root #gpart add -t freebsd-zfs -l zfs-system ada0

Creating and mounting a file system

Using the UFS2 file system

Please do not forget newfs -L option to label.

Add option -j to newfs to enable soft updates journaling. Add option -t to enable TRIM.

Your choice GPT:

root #newfs -L gfbsdroot -U /dev/ada0p2

Your choice MBR:

root #newfs -L gfbsdroot -U /dev/ada0s1a

And mount it:

root #mount /dev/ufs/gfbsdroot /mnt
root #swapon /dev/gpt/swap (GPT)
root #swapon /dev/ada0s1b (MBR)
Using the ZFS file system (experimental)

Load the kernel module in order to enable ZFS:

root #kldload zfs

Prepare the RAM disk to write /boot/zfs/zpool.cache:

root #mount -t tmpfs tmpfs /boot/zfs

Please use gnop if you have 4KB/sector HDD. You can get the best performance:

root #gnop create -S 4096 /dev/gpt/zfs-system

Creates a new storage pool. If you are using gnop, please specify /dev/gpt/zfs-system.nop instead of /dev/gpt/zfs-system.

root #zpool create zsys /dev/gpt/zfs-system
root #zfs set mountpoint=none zsys

Creates a new ZFS file system:

root #zfs create zsys/root
root #zfs set mountpoint=/mnt zsys/root
root #zfs mount -a
root #zfs create zsys/root/usr
root #zfs create zsys/root/var
root #zfs create zsys/root/tmp
root #zfs create zsys/home
root #zfs create -V 8gb zsys/swap
root #zfs set org.freebsd:swap=on zsys/swap
root #zfs set checksum=off zsys/swap
root #mkdir /mnt/home
root #mount -t zfs zsys/home /mnt/home

Downloading the stage3 tarball and Portage snapshot

Now, Gentoo/FreeBSD 9.0 stage3 is available for x86-fbsd. And Gentoo/FreeBSD 9.1 stage3 is available for amd64-fbsd.

If you want to use amd64-fbsd, please upgrade to 10.3 after the installation is complete. FreeBSD 9.1 is EOL on December 31, 2014. To use x86-fbsd, please upgrade to 10.3 after the installation is complete. FreeBSD 9.0 is EOL on March 31, 2013.

Unpacking stage3 and Portage snapshot

The following error may be displayed. Don't worry, please continue the installation. This problem will be fixed in 9.2. Details, see bug #469454
./bin/fuser: Can't create 'bin/fuser'
tar: Error exit delayed from previous errors.
root #cd /mnt
root #setenv LANG "en_US.UTF-8"
root #tar xjpf stage3-*.tar.bz2 -C /mnt
root #tar xjf portage-latest.tar.bz2 -C /mnt/usr

Entering the new environment

root #mount -t devfs devfs /mnt/dev
root #cp /etc/resolv.conf /mnt/etc/
root #chroot /mnt /bin/bash

Settings and install more in chroot environment

The first settings and time zone settings

env-update and time zone settings. Of course, you can modify /etc/portage/make.conf.

(chroot) root #env-update && source /etc/profile
(chroot) root #cp /usr/share/zoneinfo/GMT /etc/localtime (please select your time zone)
(chroot) root #emerge -u sys-apps/portage ; emerge sys-devel/libtool app-admin/eselect
(chroot) root #emerge app-editors/nano
(chroot) root #mv /etc/make.conf /etc/portage/ (if /etc/make.conf is exist.)
(chroot) root #nano -w /etc/portage/make.conf (if necessary)

Bug fixes (for x86-fbsd users, 9.0 stage3 only)

Bugs have been fixed in several packages. Please upgrade them. For details, see bug #324445, bug #412319, bug #417031 and bug #421191.

(chroot) root #emerge sys-devel/gcc-config
(chroot) root #emerge sys-freebsd/freebsd-mk-defs sys-freebsd/freebsd-lib app-arch/libarchive dev-libs/libedit

Special settings for ZFS

If you select ZFS file system, the following additional work is required.

(chroot) root #emerge flaggie
(chroot) root #flaggie +zfs
(chroot) root #emerge sys-devel/flex
(chroot) root #emerge sys-freebsd/freebsd-cddl
(chroot) root #emerge sys-freebsd/freebsd-lib sys-freebsd/freebsd-ubin sys-freebsd/boot0

Installing a kernel source

Unlike Gentoo/Linux, freebsd-sources package is the only sources.

(chroot) root #USE=symlink emerge freebsd-sources

Compiling and installing kernel

Now let's compile the kernel. For more information see the FreeBSD Handbook.

(chroot) root #emerge -u sys-devel/flex
(chroot) root #cd /usr/src/sys/i386/conf (case of x86-fbsd)
(chroot) root #cd /usr/src/sys/amd64/conf (case of amd64-fbsd)
(chroot) root #cp GENERIC.hints /boot/device.hints
(chroot) root #config GENERIC
(chroot) root #cd ../compile/GENERIC
(chroot) root #make cleandepend && make depend && make -j3 && make install

System settings

Familiar setting. Please refer to Gentoo Linux Handbook if you need more information.

If you select UFS2:

(chroot) root #nano -w /etc/fstab
# Device	Mountpoint	FStype	Options	Dump	Pass#
/dev/ufs/gfbsdroot	/		ufs	rw	1	1

#your choice GPT (don't forget comment out)
#/dev/gpt/swap	none		swap	sw	0	0

#your choice MBR (don't forget comment out)
#/dev/ada0s1b	none		swap	sw	0	0

If you select ZFS. Note that the Pass# column should be zero for ZFS. Because ZFS doesn't support fsck.

(chroot) root #nano -w /etc/fstab
# Device	Mountpoint	FStype	Options	Dump	Pass#
#/dev/ad0s1a	/		ufs	rw	1	1
#/dev/ad0s1b	none		swap	sw	0	0
zsys/root	/		zfs	rw	0	0

Setting the host name

(chroot) root #nano -w /etc/conf.d/hostname
# (Set the hostname variable to your host name.  On BSD this is expected to be the FQDN.)

Editing network setting

(chroot) root #nano -w /etc/conf.d/net
# (Set the dns_domain variable to your domain name)

# Manually setting)
config_em0=" netmask"
routes_em0="default via"

# Using DHCP)

Adding net.em0 to the default runlevel

(chroot) root #cd /etc/init.d
(chroot) root #ln -s net.lo0 net.em0
(chroot) root #rc-update add net.em0 default

Setting keymap

Please edit /etc/conf.d/syscons if you want to change keymap.

(chroot) root #nano -w /etc/conf.d/syscons

A list of key map is available with the following command.

(chroot) root #ls -1 /usr/share/syscons/keymaps | less

Setting the root password

(chroot) root #passwd

Adding a User for Daily Use (sample)

(chroot) root #adduser
Username: nigoro
Full name:
Uid (Leave empty for default):
Login group [nigoro]:
Login group is nigoro. Invite nigoro into other groups? []: wheel
Login class [default]:
Shell (bash csh esh fish ksh sash sh tcsh zsh nologin) [sh]: bash
Home directory [/home/nigoro]:
Home directory permissions (Leave empty for default):
Use password-based authentication? [yes]:
Use an empty password? (yes/no) [no]:
Use a random password? (yes/no) [no]:
Enter password:
Enter password again:
Lock out the account after creation? [no]:
Username   : nigoro
Password   : *****
Full Name  :
Uid        : 1001
Class      :
Groups     : nigoro wheel
Home       : /home/nigoro
Home Mode  :
Shell      : /bin/bash
Locked     : no
OK? (yes/no): yes
adduser: INFO: Successfully added (nigoro) to the user database.
Add another user? (yes/no): no

You can run at startup sshd.

(chroot) root #emerge -u net-misc/openssh
(chroot) root #rc-update add sshd default
Special settings for ZFS

If you select ZFS file system, the following additional work is required.

(chroot) root #rc-update add zfs boot
(chroot) root #rc-update add zvol default
(chroot) root #echo 'zfs_load="YES"' >> /boot/loader.conf
(chroot) root #echo 'vfs.root.mountfrom="zfs:zsys/root"' >> /boot/loader.conf
Special settings for virtual machine

If you are installing on a virtual machine, require additional configuration.

(chroot) root #echo 'kern.hz=100' >> /boot/loader.conf

Installing the required packages

If dhcpcd is required if you want use DHCP:

(chroot) root #emerge net-misc/dhcpcd

Installing the boot loader

Let's install a boot loader to boot the Gentoo/FreeBSD:

(chroot) root #emerge sys-freebsd/boot0

Please see this section if you want to use grub2. But it is experimental!

Setting boot loader

Let's prepare for using sys-freebsd/boot0.

If you select UFS2 (GPT):

(chroot) root #gpart bootcode -b /boot/pmbr ada0
(chroot) root #gpart bootcode -p /boot/gptboot -i 1 ada0

If you select UFS2 (MBR):

(chroot) root #gpart bootcode -b /boot/boot0 ada0
(chroot) root #gpart bootcode -b /boot/boot ada0s1

If you select ZFS (GPT):

(chroot) root #gpart bootcode -b /boot/pmbr ada0
(chroot) root #gpart bootcode -p /boot/gptzfsboot -i 1 ada0

Exit from the chroot environment

Work done in the chroot environment, now exit the environment:

(chroot) root #exit

Cleaning up and setting the remaining

Do you want to reboot now ? Just a minute. ZFS user must have setting a little more.

Special settings for ZFS

If you select ZFS file system, the following additional work is required.

root #umount /mnt/dev
root #cd /
root #zpool set bootfs=zsys/root zsys
root #zpool export zsys
root #gnop destroy /dev/gpt/zfs-system.nop (please run if you are using gnop)
root #zpool import zsys
root #mkdir /mnt/boot/zfs
root #cp /boot/zfs/zpool.cache /mnt/boot/zfs/
root #zfs unmount -a
root #zfs set mountpoint=none zsys
root #zfs set mountpoint=/usr zsys/root/usr
root #zfs set mountpoint=/var zsys/root/var
root #zfs set mountpoint=/tmp zsys/root/tmp
root #zfs set mountpoint=/home zsys/home
root #zfs set mountpoint=legacy zsys/root


Don't have a problem? Now restart.

Don't forget to remove the Installation CD of FreeBSD.

root #shutdown -r now

Howto run G/FBSD in vanilla FreeBSD's jail

Details of jail, please see the FreeBSD Handbook.

Preparing directory

root #mkdir -p /usr/jail/gfbsd
root #cd /usr/jail/gfbsd

Downloading and Unpacking the stage3 tarball and Portage snapshot

root #tar xjpf stage3-*.tar.bz2
root #tar xjf portage-latest.tar.bz2 -C /usr/jail/gfbsd/usr


Configure jail to start with FreeBSD:

FILE /etc/rc.confExample for start automatically jail


# You will need to add the following line if you want network access.
# em0, please specify your network devices.

Setting to operate Gentoo/FreeBSD in jail:

root #echo 'rc_sys="jail"' >> /usr/jail/gfbsd/etc/rc.conf
root #echo 'hostname="gfbsd"' > /usr/jail/gfbsd/etc/conf.d/hostname
root #echo 'syslogd_args="-ss"' >> /usr/jail/gfbsd/etc/conf.d/syslogd
root #chroot /usr/jail/gfbsd /bin/bash
(chroot) root #rc-update add vixie-cron default
(chroot) root #exit

run jail

Let's run jail:

root #/etc/rc.d/jail start

Verify that it worked:

root #jls
   JID  IP Address      Hostname                      Path
     1    gfbsd                         /usr/jail/gfbsd

To enter the jail environment will use the jexec command:

root #jexec 1 /bin/bash

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.



All commands is not working after emerge sys-apps/baselayout

After failing to emerge baselayout, all commands will not work. For details see bug #436560.

root #ls
Shared object "" not found, required by "ls"

If you have not restarted the PC, please run this command first:

root #export LD_LIBRARY_PATH="/lib64:/usr/lib64"

If you restart or turn off your PC already, in order to restore you need FreeBSD installation media.

  1. boot using the installation media of FreeBSD.
  2. Live CD select
  3. Mount the root partition of G/FBSD (e.g. mount /dev/ufs/gfbsdroot /mnt)
  4. cd /mnt (Please replace to /mnt/, /mnt/usr, ... from /, /usr, ...)

Please check lib in /, /usr, /usr/local.

root #ls -l /lib /usr/lib /usr/local/lib
ls: /lib: No such file or directory
lrwxr-xr-x  1 root  wheel  5 Oct 14 06:41 /usr/lib -> lib64

lrwxr-xr-x  1 root  wheel  5 Oct 14 06:41 /usr/local/lib -> lib64

In this case, the symbolic link /lib is simply removed. Let's re-create symbolic link /lib.

root #ln -s lib64 /lib

You need to migrate from lib64 to lib before run emerge baselayout. Run the script for migration.

If boot your PC with a FreeBSD's installation media, please enter in G/FBSD run chroot /mnt !

root #bash /tmp/
root #emerge sys-apps/baselayout

Architecture independent issues

Emerge fails app-misc/screen

For details see bug #393039 and bug #409819.

Please use app-misc/tmux instead of app-misc/screen.

lex: not found

root #emerge --ask sys-devel/flex

cc: not found

For details see bug #412319:

root #emerge '>=sys-devel/gcc-config-1.7.1'

sys-freebsd/freebsd-usbin: fatal error: 'portability.h' file not found

For details see bug #601334.

sys-freebsd/freebsd-ubin: build fails, undefined reference to `yywrap'

For details see bug #607996.


See also