OpenRC/Baselayout 1 to 2 migration

This guide provides instructions on migrating from baselayout-1 to baselayout-2 using OpenRC.

What is 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 is OpenRC?
OpenRC is a dependency-based rc (run command) system that works with the init program that is provided by the system, normally. OpenRC is not a replacement for. The default init system used by Gentoo Linux is, while Gentoo/FreeBSD uses the FreeBSD init provided by.

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 OpenRC was born.

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 the regular upgrade process by the package manager. The most important step comes after  and  packages have been installed. It is critical to ensure the files in are up to date by running dispatch-conf or a similar tool before rebooting the system. Failure to do so will result in an unbootable system and will require the use of a LiveCD to perform the steps below to repair the system.

Once the configuration files have been updated there are a few things to verify prior to rebooting.

has been deprecated. Any settings contained therein will need to be migrated to the appropriate settings in. Please read through and  and migrate the settings. Once complete, manually remove the file.

Kernel modules
Normally, when certain kernel modules are automatically loaded at boot they are placed into along with any parameters to be passed. In baselayout-2, this file is not used anymore. Instead, autoloaded modules and module parameters are placed in the file, no matter what 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 the root filesystem is mounted read/write, the filesystems are checked for errors, the mountpoints are available, and the pseudo-filesystem is started at boot.

With OpenRC, volume management services for block storage devices are no longer run automatically at boot. This includes LVM, RAID, swap, device-mapper (dm), dm-crypt, and the like. System administrators must ensure the appropriate initscript for these services has been added to the  runlevel, otherwise it is possible the system will not be able to boot.

While the OpenRC ebuild will attempt to do this migration, administrators should verify the volume management services have been migrated properly:

If, , , , and are missing in the above listing, perform the following commands to add them to the   runlevel:

If the system uses mdraid and LVM and they are not mentioned in the list above, then the following initscripts should be added to the  runlevel:

Udev
OpenRC no longer starts by default; 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, the 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:

When missing any other network initscripts, follow the instructions above to re-add them. Simply replace  with the name of the missing 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 separate entries, for example a static IP assignment would change as follows:

Clock
Clock settings have been renamed from to the system's native tool for adjusting the clock. 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 the 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 does not exist, it will need to be created with the appropriate timezone. Please review both of these files to ensure their contents.

The proper value for this file is the path relative to the timezone from the directory. For example, for users living on the east coast of the United States, the following would be a correct setting:

XSESSION
The  variable is no longer found in. Instead, the  variable can be set on a per-user basis in the  file (or equivalent), or system-wide in.

Here is an example of setting the default  for the whole system:

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

Boot log
Previously, the boot process could be logged using the package. However, OpenRC now handles all logging internally, so there is no need for the hacks that showconsole employed. showconsole can now be safely unmerged. To continue logging boot messages, set the appropriate variable in the  file. Logs will appear in.

and
With OpenRC, and  have been deprecated. During the migration to OpenRC, the files are moved to and gain the suffix  or. OpenRC then executes those in alpha-numeric order.

System sub-types: Virtualization special cases
In the early versions of OpenRC, explicit detect for multiple types of virtualization was performed, which was used to note when certain init scripts should be skipped, using the  call in the   functions.

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

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 the 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 finished updating the config files and initscripts, the last thing to do is to type reboot with root privileges at a terminal. This is necessary because system state information is not preserved during the upgrade, so a fresh boot is needed.

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</tt>. In OpenRC, the  action was removed; this functionality is supported by the /etc/init.d/service --nodeps stop</tt>, which also works in the old baselayout.

rootfs entry in
Previously, the initial  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.