nightmorph 08/04/11 23:59:51 Modified: metadoc.xml Added: openrc-migration.xml Log: added new openrc/baselayout-2 migration guide written by myself, cardoe, and uberlord. it's part of our sysadmin and upgrade categories. stabilization of the package will follow about 30 days from now, in the mean time, now it's hitting ~arch, so lots of our users will need to read this guide.
Revision Changes Path 1.210 xml/htdocs/doc/en/metadoc.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/metadoc.xml?rev=1.210&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/metadoc.xml?rev=1.210&content-type=text/plain diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/metadoc.xml?r1=1.209&r2=1.210 Index: metadoc.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v retrieving revision 1.209 retrieving revision 1.210 diff -u -r1.209 -r1.210 --- metadoc.xml 7 Apr 2008 05:48:48 -0000 1.209 +++ metadoc.xml 11 Apr 2008 23:59:51 -0000 1.210 @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd"> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.209 2008/04/07 05:48:48 nightmorph Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.210 2008/04/11 23:59:51 nightmorph Exp $ --> <metadoc lang="en"> - <version>1.131</version> + <version>1.132</version> <members> <lead>neysx</lead> <member>cam</member> @@ -408,6 +408,7 @@ <file id="pam-upgrade">/proj/en/base/pam/upgrade-0.99.xml</file> <file id="embedded-handbook">/proj/en/base/embedded/handbook/index.xml</file> <file id="texlive-migration-guide">/proj/en/tex/texlive-migration-guide.xml</file> + <file id="openrc-migration">/doc/en/openrc-migration.xml</file> </files> <docs> <doc fileid="name-logo"> @@ -879,6 +880,10 @@ <bug stopper="yes">115130</bug> </bugs> </doc> + <doc fileid="openrc-migration"> + <memberof>sysadmin_specific</memberof> + <memberof>upgrade</memberof> + </doc> <doc fileid="new-dev-training"> <memberof>project_devrel</memberof> </doc> 1.1 xml/htdocs/doc/en/openrc-migration.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openrc-migration.xml?rev=1.1&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openrc-migration.xml?rev=1.1&content-type=text/plain Index: openrc-migration.xml =================================================================== <?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.1 2008/04/11 23:59:51 nightmorph Exp $ --> <guide link="/doc/en/openrc-migration.xml"> <title>Baselayout and OpenRC Migration Guide</title> <author title="Author"> <mail link="cardoe"/> </author> <author title="Author"> <mail link="nightmorph"/> </author> <author title="Contributor"> <mail link="uberlord"/> </author> <abstract> This guide shows you how to migrate from baselayout-1 to baselayout-2 and OpenRC. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1.0</version> <date>2008-04-11</date> <chapter> <title>Background</title> <section> <title>What's baselayout?</title> <body> <p> Baselayout provides a basic set of files that are necessary for all systems to function properly, such as <path>/etc/hosts</path>. It also provides the basic filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>, <path>/usr</path>, <path>/home</path> directories). </p> </body> </section> <section> <title>What's OpenRC?</title> <body> <p> OpenRC is a dependency-based rc system that works with whatever init is provided by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided by <c>sys-freebsd/freebsd-sbin</c>. </p> </body> </section> <section> <title>So why migrate?</title> <body> <p> 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. </p> <p> 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. </p> <p> OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc";>Roy Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux, Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as FreeBSD and NetBSD. </p> </body> </section> </chapter> <chapter> <title>Migration to OpenRC</title> <section> <body> <p> 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 <c>>=sys-apps/baselayout-2</c> and <c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run <c>dispatch-conf</c> and ensure your <path>/etc</path> is up to date before rebooting. <brite>Failure to do so will result in an unbootable system</brite> and will require the use of the Gentoo LiveCD to perform the steps below to repair your system. </p> <p> Once you've finished updating your config files, there are a few things to verify prior to rebooting.</p> </body> </section> <section id="rc_conf"> <title>/etc/conf.d/rc</title> <body> <p> <path>/etc/conf.d/rc</path> has been deprecated and any settings you have in there will need to be migrated to the appropriate settings in <path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and <path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete, delete <path>/etc/conf.d/rc</path>. </p> </body> </section> <section id="modules"> <title>Kernel modules</title> <body> <p> Normally, when you want certain kernel modules automatically loaded at boot, you place them into <path>/etc/modules.autoload.d/kernel-2.6</path> 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, <path>/etc/conf.d/modules</path>, no matter the kernel version. </p> <p> An example old style configuration would be: </p> <pre caption="/etc/modules.autoload.d/kernel-2.6"> ivtv cx88_dvb video_br=2 </pre> <p> Converting the above example would result in the following: </p> <pre caption="/etc/conf.d/modules"> <comment># Modules autoloaded at boot</comment> modules_2_6="ivtv cx88_dvb" <comment># Module parameters</comment> module_cx88_dvb_args_2_6="video_br=2" </pre> <p> 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. </p> <p> An in-depth example would be: </p> <pre caption="detailed example of /etc/conf.d/modules"> <comment># Always load ochi1394 and ieee1394, no matter the kernel version</comment> modules="ohci1394 ieee1394" <comment># Only load tun and usbserial for 2.6.x series kernels</comment> modules_2_6="tun usbserial" <comment># Only load cx88_dvb for 2.6.23 kernels</comment> modules_2_6_23="cx88_dvb" <comment># Only load ivtv for 2.6.23-gentoo-r5</comment> modules_2_6_23_gentoo_r5="ivtv" <comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment> module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2" <comment># For 2.6.x series kernels, always pass vendor and product</comment> module_usbserial_args_2_6="vendor=0x1410 product=0x2110" <comment># Always pass debug to ieee1394</comment> module_ieee1394_args="debug" </pre> <note> Please note the difference between <b>module_</b> and <b>modules_</b>. </note> </body> </section> <section id="volume"> <title>Volume management</title> <body> <p> Volume management services for your block storage devices should be automatically migrated for you when you switch to OpenRC and baselayout-2. However, in case they aren't, you'll need to follow the instructions below. </p> <p> Volume management services for your block storage devices are no longer run by default. This means that lvm, raid, swap, device-mapper (dm), dm-crypt, evms, and the like will not be run automatically. If you use these addons, you will have to add the proper initscript to the <c>boot</c> runlevel. Otherwise, it's possible your system will not boot. When you install the various volume management services, they will install an appropriate initscript in <path>/etc/init.d</path>. You must ensure the appropriate initscript is in the <c>boot</c> runlevel. </p> <p> While the OpenRC ebuild will attempt to do this migration for you, you should verify that it migrated all the volume management services properly. </p> <pre caption="Check all services in boot runlevel"> # <i>ls -l /etc/runlevels/boot/</i> </pre> <p> If you know you use mdraid, lvm, and swap but do not see them above, you would run the following to add initscripts to the <c>boot</c> runlevel. </p> <pre caption="Adding missing volume management services to the boot runlevel"> # <i>rc-update add raid boot</i> # <i>rc-update add lvm boot</i> # <i>rc-update add swap boot</i> </pre> </body> </section> <section> <title>Clock</title> <body> <p> Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your system's native tool for adjusting the clock. This means on Linux it will be <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be <path>/etc/conf.d/adjkerntz</path>. </p> <p> Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its contents are instead found in the <path>/etc/timezone</path> file. Please review both of these files to ensure their correctness. </p> </body> </section> <section> <title>XSESSION</title> <body> <p> The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. The <c>x11-apps/xinit</c> package now provides <path>/etc/env.d/90xsession</path>, which can be used to set the XSESSION variable. </p> <p> This variable will <b>NOT</b> be migrated for you by default, so you will need to edit <path>/etc/env.d/90xsession</path>. </p> <impo> You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>, and then logout and login for it to take effect. </impo> </body> </section> <section> <title>EDITOR</title> <body> <p> The EDITOR variable is no longer found in <path>/etc/rc.conf</path>, and at this time is not provided by any other package. Users are encouraged to set it as needed in their <path>~/.bashrc</path> file or create <path>/etc/env.d/99editor</path> and set it there. </p> <impo> You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>, and then logout and login for it to take effect. If you set the variable in <path>~/.bashrc</path>, you can re-source the file with <c>source ~/.bashrc</c>. </impo> </body> </section> <section> <title>Finishing up</title> <body> <p> Once you've finished updating your config files and initscripts, the last thing to do is <b>reboot</b>. This is necessary because system state information is not preserved during the upgrade, so you'll need to provide it with a fresh boot. </p> </body> </section> </chapter> </guide> -- [email protected] mailing list
