OpenRC/Baselayout 1 to 2 migration

This guide shows you how to migrate from baselayout-1 to baselayout-2 and OpenRC.

What's baselayout?
Baselayout provides a basic set of files that are necessary for all systems to function properly, such as. It also provides the basic filesystem layout used by Gentoo (i.e.,  ,  ,  directories).

What's OpenRC?
OpenRC is a dependency-based rc system that works with whatever init is provided by the system, normally. However, it is not a replacement for. The default init used by Gentoo Linux is , while Gentoo/FreeBSD uses the FreeBSD init provided by.

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.

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  and   packages. It is critical that you run  and ensure your  is up to date before rebooting.Failure to do so will result in an unbootable systemand 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. Please read through and  and migrate the settings. Once you are complete, delete.

Kernel modules
Normally, when you want certain kernel modules automatically loaded at boot, you place them into 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,, no matter the kernel version.

An example old style configuration would be:

Converting the above example would result in the following:

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:

Boot runlevel
The  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 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  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:

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

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

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

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

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:

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

Also, (oldnet) no longer uses bash-style arrays for configuration. Please review 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:

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

Additionally, the  variable is no longer in this file. Its contents are instead found in the 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. For example, for someone living on the east coast of the United States, the following would be a correct setting:

XSESSION
The XSESSION variable is no longer found in. Instead, you can set the XSESSION variable per-user in (or equivalent), or system-wide in.

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

EDITOR and PAGER
The EDITOR variable is no longer found in. Both EDITOR and PAGER are set by default in. You should change this as needed in your (or equivalent) file or create  and set the system default there.

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

local.start and local.stop
With OpenRC, and  are deprecated. During the migration to OpenRC, the files are moved to and gain the suffix  or. 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. 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="".

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 which is superseded by.

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 pause action
Previously it was possible to temporarily stop a service without taking down all the depending services by using. In OpenRC, the  action was removed; this functionality is supported by the  , which also works in the old baselayout.

rootfs entry in /etc/mtab
Previously, the initial rootfs entry was removed from, 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.

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


 * cardoe
 * nightmorph
 * robbat2
 * uberlord