Baselayout and OpenRC Migration Guide |
Baselayout and OpenRC Migration GuideBaselayout 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). 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. 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 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. 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:
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:
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:
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:
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:
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:
If udev is not listed, add it to the correct runlevel:
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 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:
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:
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:
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.
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.
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="".
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. 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. 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. 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. |