Home Dokumentacje Baselayout and OpenRC Migration Guide
24 | 01 | 2020
Baselayout and OpenRC Migration Guide

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

Code Listing 2.1: /etc/modules.autoload.d/kernel-2.6

cx88_dvb video_br=2

Converting the above example would result in the following:

Code Listing 2.2: /etc/conf.d/modules

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

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.

Important: The module* variables are not cumulative. The more version-specific variables will override the more general variables.

Note: Please note the difference between module_ and modules_.

An in-depth example would be:

Code Listing 2.3: detailed example of /etc/conf.d/modules

# Only load ivtv for 2.6.23-gentoo-r5
# Only load cx88_dvb for 2.6.23 kernels (other than -gentoo-r5)
# 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
# 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

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:

Code Listing 2.4: Display all services in boot runlevel

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

Code Listing 2.5: Adding critical services 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:

Code Listing 2.6: Adding mdraid and lvm to the boot runlevel

# rc-update add mdraid boot
# rc-update add lvm boot


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:

Code Listing 2.7: Verifying udev

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

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

Code Listing 2.8: Adding udev to the sysinit runlevel

# rc-update add udev sysinit


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:

Code Listing 2.9: Adding back missing net.eth0 script

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

Code Listing 2.10: Old /etc/conf.d/net style

config_eth0=( " netmask brd" )
routes_eth0=( "default via" " via" )

Code Listing 2.11: New /etc/conf.d/net style

config_eth0=" netmask brd"
routes_eth0="default via via"


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:

Code Listing 2.12: /etc/timezone



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:

Code Listing 2.13: Setting XSESSION system-wide

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

Important: You must run env-update after creating a file in /etc/env.d, and then logout and login for it to take effect. If you set the variable in ~/.bashrc, you can re-source the file with source ~/.bashrc.


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.

Important: You must run env-update after creating a file in /etc/env.d, and then logout and login for it to take effect. If you set the variable in ~/.bashrc, you can re-source the file with source ~/.bashrc.

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.

Code Listing 2.14: Enabling boot logging in /etc/rc.conf


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="".

Important: If you do not have any specific sub-type, please use the default of an empty string "". If the variable is unset, you will be given a warning and we will attempt to use the old detection algorithm.

Note: If you do not know what value your system was using with the automatic detection, you should temporarily comment out the rc_sys variable and run the detection command, rc -S.

Code Listing 2.15: Setting system sub-type to none in /etc/rc.conf


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.

Subtype Description Notes
Default, no sub-type Not the same as unset; FreeBSD, Linux & NetBSD
jail FreeBSD jails
lxc Linux Containers Not auto-detected
openvz Linux OpenVZ
prefix Prefix Not auto-detected; FreeBSD, Linux & NetBSD
vserver Linux vserver
xen0 Xen0 Domain Linux & NetBSD
xenU XenU Domain Linux & NetBSD

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.


Linki sponsorowane

W celu realizacji usług i funkcji na witrynach internetowych ZUI "ELPRO" stosujemy pliki cookies. Korzystanie z witryny bez zmiany ustawień dotyczących plików cookies oznacza, że będą one zapisywane w urządzeniu wyświetlającym stronę internetową. Więcej szczegółów w Polityce plików cookies.

Akceptuję pliki cookies z tej witryny.