Baselayout and OpenRC Migration Guide

1.  Background

What's baselayout?

Baselayout provides a basic set of files that are necessary for all systems to function properly, such as /etc/hosts. It also provides the basic filesystem layout used by Gentoo (i.e. /etc, /var, /usr, /home directories).

What's OpenRC?

OpenRC is a dependency-based rc system that works with whatever init is provided by the system, normally /sbin/init. However, it is not a replacement for /sbin/init. The default init used by Gentoo Linux is sys-apps/sysvinit, while Gentoo/FreeBSD uses the FreeBSD init provided by sys-freebsd/freebsd-sbin.

So why migrate?

Originally Gentoo's rc system was built into baselayout 1 and written entirely in bash. This led to several limitations. For example, certain system calls need to be accessed during boot and this required C-based callouts to be added. These callouts were each statically linked, causing the rc system to bloat over time.

Additionally, as Gentoo expanded to other platforms like Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based rc system. This led to a development of baselayout 2, which is written in C and only requires a POSIX-compliant shell. During the development of baselayout 2, it was determined that it was a better fit if baselayout merely provided the base files and filesystem layout for Gentoo and the rc system was broken off into its own package. Thus we have OpenRC.

OpenRC is primarily developed by Roy Marples and supports all current Gentoo variations (i.e. Gentoo Linux, Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as FreeBSD and NetBSD.

2.  Migration to OpenRC

Migration to OpenRC is fairly straightforward; it will be pulled in as part of your regular upgrade process by your package manager. The most important step actually comes after you install the new >=sys-apps/baselayout-2 and sys-apps/openrc packages. It is critical that you run dispatch-conf and ensure your /etc is up to date before rebooting. Failure to do so will result in an unbootable system and will require the use of the Gentoo LiveCD to perform the steps below to repair your system.

Once you've finished updating your config files, there are a few things to verify prior to rebooting.

/etc/conf.d/rc

/etc/conf.d/rc has been deprecated and any settings you have in there will need to be migrated to the appropriate settings in /etc/rc.conf. Please read through /etc/rc.conf and /etc/conf.d/rc and migrate the settings. Once you are complete, delete /etc/conf.d/rc.

Kernel modules

Normally, when you want certain kernel modules automatically loaded at boot, you place them into /etc/modules.autoload.d/kernel-2.6 along with any parameters you wanted to pass to them. In baselayout-2, this file is not used anymore. Instead, autoloaded modules and module parameters are placed in one file, /etc/conf.d/modules, no matter the kernel version.

An example old style configuration would be:

ivtv
cx88_dvb video_br=2

Converting the above example would result in the following:

# Modules autoloaded at boot
modules_2_6="ivtv cx88_dvb"
# Module parameters
module_cx88_dvb_args_2_6="video_br=2"

In the above examples, the modules and their parameters would only be passed to 2.6.x series kernels. The new configuration allows for fine grained control over the modules and parameters based on kernel version.

An in-depth example would be:

# Always load ochi1394 and ieee1394, no matter the kernel version
modules="ohci1394 ieee1394"
# Only load tun and usbserial for 2.6.x series kernels
modules_2_6="tun usbserial"
# Only load cx88_dvb for 2.6.23 kernels
modules_2_6_23="cx88_dvb"
# Only load ivtv for 2.6.23-gentoo-r5
modules_2_6_23_gentoo_r5="ivtv"

# For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb
module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
# For 2.6.x series kernels, always pass vendor and product
module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
# Always pass debug to ieee1394
module_ieee1394_args="debug" 

Boot runlevel

The boot runlevel performs several important steps for every machine. For example, making sure your root filesystem is mounted read/write, that your filesystems are checked for errors, that your mountpoints are available, and that the /proc pseudo-filesystem is started at boot.

With OpenRC, volume management services for your block storage devices are no longer run automatically at boot. This includes lvm, raid, swap, device-mapper (dm), dm-crypt, evms, and the like. You must ensure the appropriate initscript for these services is in the boot runlevel, otherwise it's possible that your system will not boot!

While the OpenRC ebuild will attempt to do this migration for you, you should verify that it migrated all the volume management services properly:

# ls -l /etc/runlevels/boot/

If you don't see root, procfs, mtab, swap, and fsck in the above listing, perform the following to add them to the boot runlevel:

# rc-update add root boot
# rc-update add procfs boot
# rc-update add mtab boot
# rc-update add fsck boot
# rc-update add swap boot

If you know you use mdraid and lvm but do not see them above, you would run the following to add initscripts to the boot runlevel:

# rc-update add raid boot
# rc-update add lvm boot

Udev

OpenRC no longer starts udev by default, but it does need to be present in the sysinit runlevel to be started. The OpenRC ebuild should detect if udev was previously enabled and add it to the sysinit runlevel. However, to be safe, check if udev is present:

# ls -l /etc/runlevels/sysinit
lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
/etc/init.d/udev

If udev is not listed, add it to the correct runlevel:

# rc-update add udev sysinit

Network

Due to baselayout and OpenRC being broken into two different packages, your net.eth0 initscript may disappear during the upgrade process. To replace this initscript please perform the following:

# cd /etc/init.d
# ln -s net.lo net.eth0

If you are missing any other network initscripts, follow the instructions above to re-add them. Simply replace eth0 with the name of your network device.

Also, /etc/conf.d/net no longer uses bash-style arrays for configuration. Please review /usr/share/doc/openrc/net.example for configuration instructions. Conversion should be relatively straight-forward, for example a static IP assignment would change as follows:

config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
routes_eth0=( "default via 192.168.1.100" )

config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
routes_eth0="default via 192.168.1.100"

Clock

Clock settings have been renamed from /etc/conf.d/clock to your system's native tool for adjusting the clock. This means on Linux it will be /etc/conf.d/hwclock and on FreeBSD it will be /etc/conf.d/adjkerntz. Systems without a working real time clock (RTC) chip should use /etc/init.d/swclock, which sets the system time based on the mtime of a file which is created at system shutdown. The initscripts in /etc/init.d/ have also been renamed accordingly, so make sure the appropriate script for your system has been added to the boot runlevel.

Additionally, the TIMEZONE variable is no longer in this file. Its contents are instead found in the /etc/timezone file. If it doesn't exist, you will of course have to create it with your timezone. Please review both of these files to ensure their correctness.

The proper value for this file is the path relative to your timezone from /usr/share/zoneinfo. For example, for someone living on the east coast of the United States, the following would be a correct setting:

America/New_York

XSESSION

The XSESSION variable is no longer found in /etc/rc.conf. Instead, you can set the XSESSION variable per-user in ~/.bashrc (or equivalent), or system-wide in /etc/env.d/.

Here's an example of setting XSESSION for the whole system:

# echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession

EDITOR and PAGER

The EDITOR variable is no longer found in /etc/rc.conf. Both EDITOR and PAGER are set by default in /etc/profile. You should change this as needed in your ~/.bashrc (or equivalent) file or create /etc/env.d/99editor and set the system default there.

Boot log

Previously, you could log the boot process by using app-admin/showconsole. However, OpenRC now handles all logging internally, so there's no need for the hacks that showconsole employed. You can safely unmerge showconsole. To continue logging boot messages, just set the appropriate variable in /etc/rc.conf. Logs will appear in /var/log/rc.log.

rc_logger="YES"

Finishing up

Once you've finished updating your config files and initscripts, the last thing to do is reboot. This is necessary because system state information is not preserved during the upgrade, so you'll need to provide it with a fresh boot.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.