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 was initially developed by Roy Marples until 2010, and is now maintained by the Gentoo OpenRC Project. OpenRC 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:

# Only load ivtv for 2.6.23-gentoo-r5
modules_2_6_23_gentoo_r5="ivtv"
# Only load cx88_dvb for 2.6.23 kernels (other than -gentoo-r5)
modules_2_6_23="cx88_dvb"
# Only load tun and usbserial for 2.6.x series kernels where x != 23
modules_2_6="tun usbserial"
# Otherwise load ochi1394 and ieee1394
modules="ohci1394 ieee1394"

# 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, 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 mdraid 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 and re-add it to the default runlevel, please perform the following:

# cd /etc/init.d
# ln -s net.lo net.eth0
# rc-update add net.eth0 default

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 (oldnet) no longer uses bash-style arrays for configuration. Please review /usr/share/doc/openrc-<version>/net.example for configuration instructions. Conversion should be relatively straight-forward, converting to newlines for seperate entries, 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" "10.0.0.0/8 via 192.168.1.2" )

config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
routes_eth0="default via 192.168.1.100
10.0.0.0/8 via 192.168.1.2"

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"

local.start and local.stop

With OpenRC, /etc/conf.d/local.start and local.stop are deprecated. During the migration to OpenRC, the files are moved to /etc/local.d and gain the suffix .start or .stop. OpenRC then executes those in alphabetic order.

System sub-types: Virtualization special cases

In the early versions of OpenRC, we explictly detected multiple types of virtualization, and used that detection to note when certain init scripts should be skipped, using the keyword call in the depend functions.

However, as of the 0.7.0 release, you are required to explicitly configure the sub-type using the rc_sys variable in /etc/rc.conf. The sub-type should be set to match the virtualization environment that the given root is in. In general, the non-empty rc_sys value should be within the virtual containers; The host node will have rc_sys="".

rc_sys=""

The detection algorithm had to be replaced with manual configuration due to the introduction of new sub-types and changes to the kernel that made prior detection unreliable.

Cleaning up stale configuration files

After migration, there will be files left on your file system that are not cleaned up by Portage. Those are configuration files which are protected by Portage' configuration file protection feature.

The most notable example would be /etc/conf.d/net.example which is superseded by /usr/share/doc/openrc-*/net.example.bz2.

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.

3. Changed functionality

The pause action

Previously it was possible to temporarily stop a service without taking down all the depending services by using /etc/init.d/service pause. In OpenRC, the pause action was removed; this functionality is supported by the /etc/init.d/service --nodeps stop, which also works in the old baselayout.

rootfs entry in /etc/mtab

Previously, the initial rootfs entry was removed from /etc/mtab, and only the real root / entry was present. The duplicate rootfs item was actually added back during shutdown. In OpenRC, both entries must be present for full support of initramfs and tmpfs-on-root. This also means that less writing is required during shutdown.

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.