doc/en/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.24 2011/01/13 04:28:00 robbat2 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="Author">
  <mail link="robbat2"/>
</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>6</version>
<date>2011-01-16</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>

<impo>
The <b>module*</b> variables are not cumulative. The more version-specific
variables will override the more general variables.
</impo>

<note>
Please note the difference between <b>module_</b> and <b>modules_</b>.
</note>

<p>
An in-depth example would be:
</p>

<pre caption="detailed example of /etc/conf.d/modules">
<comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
modules_2_6_23_gentoo_r5="ivtv"
<comment># Only load cx88_dvb for 2.6.23 kernels (other than -gentoo-r5)</comment>
modules_2_6_23="cx88_dvb"
<comment># Only load tun and usbserial for 2.6.x series kernels where x != 23</comment>
modules_2_6="tun usbserial"
<comment># Otherwise load ochi1394 and ieee1394</comment>
modules="ohci1394 ieee1394"

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

</body>
</section>

<!-- =============================================================== -->
<section id="boot">
<title>Boot runlevel</title>
<body>

<p>
The <c>boot</c> 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 <path>/proc</path> pseudo-filesystem is started at boot.
</p>

<p>
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, evms, and the like. You must ensure the appropriate initscript
for these services is in the <c>boot</c> runlevel, otherwise it's possible that
your system will not boot!
</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="Display all services in boot runlevel">
# <i>ls -l /etc/runlevels/boot/</i>
</pre>

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

<pre caption="Adding critical services to the boot runlevel">
# <i>rc-update add root boot</i>
# <i>rc-update add procfs boot</i>
# <i>rc-update add mtab boot</i>
# <i>rc-update add fsck boot</i>
# <i>rc-update add swap boot</i>
</pre>

<p>
If you know you use mdraid and lvm but do not see them above, you would run
the following to add initscripts to the <c>boot</c> runlevel:
</p>

<pre caption="Adding mdraid and lvm to the boot runlevel">
# <i>rc-update add mdraid boot</i>
# <i>rc-update add lvm boot</i>
</pre>

</body>
</section>
<!-- =============================================================== -->

<section>
<title>Udev</title>
<body>

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

<pre caption="Verifying udev">
# <i>ls -l /etc/runlevels/sysinit</i>
lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
/etc/init.d/udev
</pre>

<p>
If <c>udev</c> is not listed, add it to the correct runlevel:
</p>

<pre caption="Adding udev to the sysinit runlevel">
# <i>rc-update add udev sysinit</i>
</pre>

</body>
</section>
<!-- =============================================================== -->

<section>
<title>Network</title>
<body>

<p>
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 please perform the following:
</p>

<pre caption="Adding back missing net.eth0 script">
# <i>cd /etc/init.d</i>
# <i>ln -s net.lo net.eth0</i>
</pre>

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

<p>
Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
for configuration. Please review
<path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> 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:
</p>

<pre caption="Old /etc/conf.d/net style">
config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
</pre> 

<pre caption="New /etc/conf.d/net style">
config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
routes_eth0="default via 192.168.1.100
10.0.0.0/8 via 192.168.1.2"
</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>. Systems without a working real time clock
(RTC) chip should use <path>/etc/init.d/swclock</path>, which sets the system
time based on the mtime of a file which is created at system shutdown. The
initscripts in <path>/etc/init.d/</path> have also been renamed accordingly, so
make sure the appropriate script for your system has been added to the boot
runlevel.
</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. 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.
</p>

<p>
The proper value for this file is the path relative to your timezone from
<path>/usr/share/zoneinfo</path>. For example, for someone living on the east
coast of the United States, the following would be a correct setting:
</p>

<pre caption="/etc/timezone">
America/New_York
</pre>

</body>
</section>
<!-- =============================================================== -->

<section>
<title>XSESSION</title>
<body>

<p>
The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. Instead,
you can set the XSESSION variable per-user in <path>~/.bashrc</path> (or
equivalent), or system-wide in <path>/etc/env.d/</path>.
</p>

<p>
Here's an example of setting XSESSION for the whole system:
</p>

<pre caption="Setting XSESSION system-wide">
# <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
</pre>

<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>EDITOR and PAGER</title>
<body>

<p>
The EDITOR variable is no longer found in <path>/etc/rc.conf</path>.  Both
EDITOR and PAGER are set by default in <path>/etc/profile</path>.  You should
change this as needed in your <path>~/.bashrc</path> (or equivalent) file or
create <path>/etc/env.d/99editor</path> and set the system default 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>Boot log</title>
<body>

<p>
Previously, you could log the boot process by using
<c>app-admin/showconsole</c>. However, OpenRC now handles all logging
internally, so there's no need for the hacks that <c>showconsole</c> employed.
You can safely unmerge <c>showconsole</c>. To continue logging boot messages,
just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear
in <path>/var/log/rc.log</path>.
</p>

<pre caption="Enabling boot logging in /etc/rc.conf">
rc_logger="YES"
</pre>

</body>
</section>
<!-- =============================================================== -->

<section id="rc_sys">
<title>System sub-types: Virtualization special cases</title>
<body>

<p>
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 <b>keyword</b> call in the <b>depend</b>
functions.
</p>

<p>
However, as of the 0.7.0 release, you are required to explicitly configure the
sub-type using the <b>rc_sys</b> variable in <path>/etc/rc.conf</path>. The
sub-type should be set to match the virtualization environment that the given
root is in. In general, the non-empty <b>rc_sys</b> value should be within the
virtual containers; The host node will have <b>rc_sys=""</b>.
</p>

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

<pre caption="Setting system sub-type to none in /etc/rc.conf">
rc_sys=""
</pre>

<p>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.</p>

<table>
<tr>
  <th>Subtype</th>
  <th>Description</th>
  <th>Notes</th>
</tr>
<tr>
  <ti></ti>
  <ti>Default, no sub-type</ti>
  <ti>Not the same as unset; FreeBSD, Linux &amp; NetBSD</ti>
</tr>
<tr>
  <ti>jail</ti>
  <ti>FreeBSD jails</ti>
  <ti></ti>
</tr>
<tr>
  <ti>lxc</ti>
  <ti>Linux Containers</ti>
  <ti>Not auto-detected</ti>
</tr>
<tr>
  <ti>openvz</ti>
  <ti>Linux OpenVZ</ti>
  <ti></ti>
</tr>
<tr>
  <ti>prefix</ti>
  <ti>Prefix</ti>
  <ti>Not auto-detected; FreeBSD, Linux &amp; NetBSD</ti>
</tr>
<tr>
  <ti>uml</ti>
  <ti>Usermode Linux</ti>
  <ti></ti>
</tr>
<tr>
  <ti>vserver</ti>
  <ti>Linux vserver</ti>
  <ti></ti>
</tr>
<tr>
  <ti>xen0</ti>
  <ti>Xen0 Domain</ti>
  <ti>Linux &amp; NetBSD</ti>
</tr>
<tr>
  <ti>xenU</ti>
  <ti>XenU Domain</ti>
  <ti>Linux &amp; NetBSD</ti>
</tr>
</table>

</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>
<chapter>
<title>Changed functionality</title>
<!-- =============================================================== -->

<section>
<title>The pause action</title>
<body>

<p>
Previously it was possible to temporarily stop a service without taking down all
the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
<c>pause</c> action was removed; this functionality is supported by the
<c>/etc/init.d/service --nodeps stop</c>, which also works in the old
baselayout.
</p>

</body>
</section>
<!-- =============================================================== -->

</chapter>
</guide>
1	nightmorph	1.1	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	robbat2	1.25	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.24 2011/01/13 04:28:00 robbat2 Exp $ -->
4	nightmorph	1.1
5			<guide link="/doc/en/openrc-migration.xml">
6			<title>Baselayout and OpenRC Migration Guide</title>
7
8			<author title="Author">
9			<mail link="cardoe"/>
10			</author>
11			<author title="Author">
12			<mail link="nightmorph"/>
13			</author>
14	robbat2	1.20	<author title="Author">
15			<mail link="robbat2"/>
16			</author>
17	nightmorph	1.1	<author title="Contributor">
18			<mail link="uberlord"/>
19			</author>
20
21			<abstract>
22			This guide shows you how to migrate from baselayout-1 to baselayout-2 and
23			OpenRC.
24			</abstract>
25
26			<!-- The content of this document is licensed under the CC-BY-SA license -->
27			<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
28			<license/>
29
30	robbat2	1.25	<version>6</version>
31			<date>2011-01-16</date>
32	nightmorph	1.1
33			<chapter>
34			<title>Background</title>
35	robbat2	1.22
36			<!-- =============================================================== -->
37	nightmorph	1.1	<section>
38			<title>What's baselayout?</title>
39			<body>
40
41			<p>
42			Baselayout provides a basic set of files that are necessary for all systems to
43			function properly, such as <path>/etc/hosts</path>. It also provides the basic
44			filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>,
45			<path>/usr</path>, <path>/home</path> directories).
46			</p>
47
48			</body>
49			</section>
50	robbat2	1.22	<!-- =============================================================== -->
51
52	nightmorph	1.1	<section>
53			<title>What's OpenRC?</title>
54			<body>
55
56			<p>
57			OpenRC is a dependency-based rc system that works with whatever init is provided
58			by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a
59			replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux
60			is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided
61			by <c>sys-freebsd/freebsd-sbin</c>.
62			</p>
63	nightmorph	1.16
64	nightmorph	1.1	</body>
65			</section>
66	robbat2	1.22	<!-- =============================================================== -->
67
68	nightmorph	1.1	<section>
69			<title>So why migrate?</title>
70			<body>
71
72			<p>
73			Originally Gentoo's rc system was built into baselayout 1 and written entirely
74			in bash. This led to several limitations. For example, certain system calls need
75			to be accessed during boot and this required C-based callouts to be added. These
76			callouts were each statically linked, causing the rc system to bloat over time.
77			</p>
78
79			<p>
80			Additionally, as Gentoo expanded to other platforms like
81			Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based
82			rc system. This led to a development of baselayout 2, which is written in
83			C and only requires a POSIX-compliant shell. During the development of
84			baselayout 2, it was determined that it was a better fit if baselayout merely
85			provided the base files and filesystem layout for Gentoo and the rc system
86			was broken off into its own package. Thus we have OpenRC.
87			</p>
88
89			<p>
90			OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc">Roy
91			Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux,
92			Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as
93			FreeBSD and NetBSD.
94			</p>
95
96			</body>
97			</section>
98	robbat2	1.22	<!-- =============================================================== -->
99
100	nightmorph	1.1	</chapter>
101			<chapter>
102			<title>Migration to OpenRC</title>
103	robbat2	1.22
104			<!-- =============================================================== -->
105	nightmorph	1.1	<section>
106			<body>
107
108			<p>
109	nightmorph	1.4	Migration to OpenRC is fairly straightforward; it will be pulled in as part of
110			your regular upgrade process by your package manager. The most important step
111			actually comes after you install the new <c>>=sys-apps/baselayout-2</c> and
112			<c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run
113			<c>dispatch-conf</c> and ensure your <path>/etc</path> is up to date before
114			rebooting. <brite>Failure to do so will result in an unbootable system</brite>
115			and will require the use of the Gentoo LiveCD to perform the steps below to
116			repair your system.
117	nightmorph	1.1	</p>
118
119			<p>
120			Once you've finished updating your config files, there are a few things to
121	nightmorph	1.4	verify prior to rebooting.
122			</p>
123	nightmorph	1.1
124			</body>
125			</section>
126	robbat2	1.22	<!-- =============================================================== -->
127	nightmorph	1.1
128			<section id="rc_conf">
129			<title>/etc/conf.d/rc</title>
130			<body>
131
132			<p>
133			<path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
134			there will need to be migrated to the appropriate settings in
135			<path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
136			<path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
137			delete <path>/etc/conf.d/rc</path>.
138			</p>
139
140			</body>
141			</section>
142	robbat2	1.22	<!-- =============================================================== -->
143
144	nightmorph	1.1	<section id="modules">
145			<title>Kernel modules</title>
146			<body>
147
148			<p>
149			Normally, when you want certain kernel modules automatically loaded at boot, you
150			place them into <path>/etc/modules.autoload.d/kernel-2.6</path> along with any
151			parameters you wanted to pass to them. In baselayout-2, this file is not used
152			anymore. Instead, autoloaded modules and module parameters are placed in one
153			file, <path>/etc/conf.d/modules</path>, no matter the kernel version.
154			</p>
155
156			<p>
157			An example old style configuration would be:
158			</p>
159
160			<pre caption="/etc/modules.autoload.d/kernel-2.6">
161			ivtv
162			cx88_dvb video_br=2
163			</pre>
164
165			<p>
166			Converting the above example would result in the following:
167			</p>
168
169			<pre caption="/etc/conf.d/modules">
170			<comment># Modules autoloaded at boot</comment>
171			modules_2_6="ivtv cx88_dvb"
172			<comment># Module parameters</comment>
173			module_cx88_dvb_args_2_6="video_br=2"
174			</pre>
175
176			<p>
177			In the above examples, the modules and their parameters would only be passed
178			to 2.6.x series kernels. The new configuration allows for fine grained
179			control over the modules and parameters based on kernel version.
180			</p>
181
182	robbat2	1.21	<impo>
183			The <b>module*</b> variables are not cumulative. The more version-specific
184			variables will override the more general variables.
185			</impo>
186
187			<note>
188			Please note the difference between <b>module_</b> and <b>modules_</b>.
189			</note>
190
191	nightmorph	1.1	<p>
192			An in-depth example would be:
193			</p>
194
195			<pre caption="detailed example of /etc/conf.d/modules">
196			<comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
197			modules_2_6_23_gentoo_r5="ivtv"
198	robbat2	1.21	<comment># Only load cx88_dvb for 2.6.23 kernels (other than -gentoo-r5)</comment>
199			modules_2_6_23="cx88_dvb"
200			<comment># Only load tun and usbserial for 2.6.x series kernels where x != 23</comment>
201			modules_2_6="tun usbserial"
202			<comment># Otherwise load ochi1394 and ieee1394</comment>
203			modules="ohci1394 ieee1394"
204	nightmorph	1.1
205			<comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment>
206			module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
207			<comment># For 2.6.x series kernels, always pass vendor and product</comment>
208			module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
209			<comment># Always pass debug to ieee1394</comment>
210			module_ieee1394_args="debug"
211			</pre>
212
213			</body>
214			</section>
215	robbat2	1.22
216			<!-- =============================================================== -->
217	nightmorph	1.5	<section id="boot">
218			<title>Boot runlevel</title>
219	nightmorph	1.1	<body>
220
221			<p>
222	nightmorph	1.5	The <c>boot</c> runlevel performs several important steps for every machine. For
223			example, making sure your root filesystem is mounted read/write, that your
224			filesystems are checked for errors, that your mountpoints are available, and
225			that the <path>/proc</path> pseudo-filesystem is started at boot.
226	nightmorph	1.1	</p>
227
228			<p>
229	nightmorph	1.5	With OpenRC, volume management services for your block storage devices are no
230			longer run automatically at boot. This includes lvm, raid, swap, device-mapper
231			(dm), dm-crypt, evms, and the like. You must ensure the appropriate initscript
232			for these services is in the <c>boot</c> runlevel, otherwise it's possible that
233			your system will not boot!
234	nightmorph	1.1	</p>
235
236			<p>
237			While the OpenRC ebuild will attempt to do this migration for you, you should
238	nightmorph	1.5	verify that it migrated all the volume management services properly:
239	nightmorph	1.1	</p>
240
241	nightmorph	1.5	<pre caption="Display all services in boot runlevel">
242	nightmorph	1.1	# <i>ls -l /etc/runlevels/boot/</i>
243			</pre>
244
245			<p>
246	nightmorph	1.5	If you don't see root, procfs, mtab, swap, and fsck in the above listing,
247			perform the following to add them to the <c>boot</c> runlevel:
248	nightmorph	1.1	</p>
249
250	nightmorph	1.9	<pre caption="Adding critical services to the boot runlevel">
251	nightmorph	1.5	# <i>rc-update add root boot</i>
252			# <i>rc-update add procfs boot</i>
253			# <i>rc-update add mtab boot</i>
254			# <i>rc-update add fsck boot</i>
255	nightmorph	1.1	# <i>rc-update add swap boot</i>
256			</pre>
257
258	nightmorph	1.2	<p>
259	nightmorph	1.5	If you know you use mdraid and lvm but do not see them above, you would run
260			the following to add initscripts to the <c>boot</c> runlevel:
261	nightmorph	1.2	</p>
262
263	nightmorph	1.17	<pre caption="Adding mdraid and lvm to the boot runlevel">
264			# <i>rc-update add mdraid boot</i>
265	nightmorph	1.5	# <i>rc-update add lvm boot</i>
266	nightmorph	1.2	</pre>
267
268	nightmorph	1.1	</body>
269			</section>
270	robbat2	1.22	<!-- =============================================================== -->
271
272	nightmorph	1.1	<section>
273	nightmorph	1.13	<title>Udev</title>
274			<body>
275
276			<p>
277			OpenRC no longer starts <c>udev</c> by default, but it does need to be present
278	nightmorph	1.14	in the <c>sysinit</c> runlevel to be started. The OpenRC ebuild should detect if
279			<c>udev</c> was previously enabled and add it to the <c>sysinit</c> runlevel.
280	nightmorph	1.13	However, to be safe, check if <c>udev</c> is present:
281			</p>
282
283			<pre caption="Verifying udev">
284	nightmorph	1.14	# <i>ls -l /etc/runlevels/sysinit</i>
285			lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
286	nightmorph	1.13	/etc/init.d/udev
287			</pre>
288
289			<p>
290			If <c>udev</c> is not listed, add it to the correct runlevel:
291			</p>
292
293	nightmorph	1.14	<pre caption="Adding udev to the sysinit runlevel">
294			# <i>rc-update add udev sysinit</i>
295	nightmorph	1.13	</pre>
296
297			</body>
298			</section>
299	robbat2	1.22	<!-- =============================================================== -->
300
301	nightmorph	1.13	<section>
302	nightmorph	1.9	<title>Network</title>
303			<body>
304
305			<p>
306			Due to baselayout and OpenRC being broken into two different packages, your
307			net.eth0 initscript may disappear during the upgrade process. To replace this
308			initscript please perform the following:
309			</p>
310
311			<pre caption="Adding back missing net.eth0 script">
312			# <i>cd /etc/init.d</i>
313			# <i>ln -s net.lo net.eth0</i>
314			</pre>
315
316			<p>
317			If you are missing any other network initscripts, follow the instructions above
318	nightmorph	1.10	to re-add them. Simply replace <c>eth0</c> with the name of your network
319	nightmorph	1.9	device.
320			</p>
321
322	nightmorph	1.10	<p>
323	robbat2	1.20	Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
324			for configuration. Please review
325	nightmorph	1.17	<path>/usr/share/doc/openrc-<version>/net.example</path> for configuration
326	robbat2	1.20	instructions. Conversion should be relatively straight-forward, converting to
327			newlines for seperate entries, for example a static IP assignment would change
328			as follows:
329	nightmorph	1.10	</p>
330
331			<pre caption="Old /etc/conf.d/net style">
332			config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
333	robbat2	1.20	routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
334	nightmorph	1.10	</pre>
335
336			<pre caption="New /etc/conf.d/net style">
337			config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
338	robbat2	1.20	routes_eth0="default via 192.168.1.100
339			10.0.0.0/8 via 192.168.1.2"
340	nightmorph	1.10	</pre>
341
342	nightmorph	1.9	</body>
343			</section>
344	robbat2	1.22	<!-- =============================================================== -->
345
346	nightmorph	1.9	<section>
347	nightmorph	1.1	<title>Clock</title>
348			<body>
349
350			<p>
351			Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
352			system's native tool for adjusting the clock. This means on Linux it will be
353			<path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
354	nightmorph	1.16	<path>/etc/conf.d/adjkerntz</path>. Systems without a working real time clock
355			(RTC) chip should use <path>/etc/init.d/swclock</path>, which sets the system
356			time based on the mtime of a file which is created at system shutdown. The
357			initscripts in <path>/etc/init.d/</path> have also been renamed accordingly, so
358			make sure the appropriate script for your system has been added to the boot
359	nightmorph	1.2	runlevel.
360	nightmorph	1.1	</p>
361
362			<p>
363			Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
364	vapier	1.8	contents are instead found in the <path>/etc/timezone</path> file. If it
365			doesn't exist, you will of course have to create it with your timezone. Please
366			review both of these files to ensure their correctness.
367	nightmorph	1.1	</p>
368
369	nightmorph	1.9	<p>
370			The proper value for this file is the path relative to your timezone from
371			<path>/usr/share/zoneinfo</path>. For example, for someone living on the east
372			coast of the United States, the following would be a correct setting:
373			</p>
374
375			<pre caption="/etc/timezone">
376			America/New_York
377			</pre>
378
379	nightmorph	1.1	</body>
380			</section>
381	robbat2	1.22	<!-- =============================================================== -->
382
383	nightmorph	1.1	<section>
384			<title>XSESSION</title>
385			<body>
386
387			<p>
388	nightmorph	1.15	The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. Instead,
389			you can set the XSESSION variable per-user in <path>~/.bashrc</path> (or
390			equivalent), or system-wide in <path>/etc/env.d/</path>.
391	nightmorph	1.1	</p>
392
393			<p>
394	nightmorph	1.15	Here's an example of setting XSESSION for the whole system:
395	nightmorph	1.1	</p>
396
397	nightmorph	1.15	<pre caption="Setting XSESSION system-wide">
398			# <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
399			</pre>
400
401	nightmorph	1.1	<impo>
402			You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
403	nightmorph	1.15	and then logout and login for it to take effect. If you set the variable in
404			<path>~/.bashrc</path>, you can re-source the file with <c>source
405			~/.bashrc</c>.
406	nightmorph	1.1	</impo>
407
408			</body>
409			</section>
410	robbat2	1.22	<!-- =============================================================== -->
411
412	nightmorph	1.1	<section>
413	nightmorph	1.15	<title>EDITOR and PAGER</title>
414	nightmorph	1.1	<body>
415
416			<p>
417	vapier	1.7	The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
418	nightmorph	1.12	EDITOR and PAGER are set by default in <path>/etc/profile</path>. You should
419			change this as needed in your <path>~/.bashrc</path> (or equivalent) file or
420			create <path>/etc/env.d/99editor</path> and set the system default there.
421	nightmorph	1.1	</p>
422
423			<impo>
424			You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
425			and then logout and login for it to take effect. If you set the variable in
426			<path>~/.bashrc</path>, you can re-source the file with <c>source
427			~/.bashrc</c>.
428			</impo>
429
430			</body>
431			</section>
432	robbat2	1.22	<!-- =============================================================== -->
433
434	nightmorph	1.1	<section>
435	nightmorph	1.11	<title>Boot log</title>
436			<body>
437
438			<p>
439			Previously, you could log the boot process by using
440			<c>app-admin/showconsole</c>. However, OpenRC now handles all logging
441			internally, so there's no need for the hacks that <c>showconsole</c> employed.
442			You can safely unmerge <c>showconsole</c>. To continue logging boot messages,
443			just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear
444			in <path>/var/log/rc.log</path>.
445			</p>
446
447			<pre caption="Enabling boot logging in /etc/rc.conf">
448			rc_logger="YES"
449			</pre>
450
451			</body>
452			</section>
453	robbat2	1.22	<!-- =============================================================== -->
454
455	robbat2	1.23	<section id="rc_sys">
456			<title>System sub-types: Virtualization special cases</title>
457			<body>
458
459			<p>
460			In the early versions of OpenRC, we explictly detected multiple types of
461			virtualization, and used that detection to note when certain init scripts
462			should be skipped, using the <b>keyword</b> call in the <b>depend</b>
463			functions.
464			</p>
465
466			<p>
467			However, as of the 0.7.0 release, you are required to explicitly configure the
468	robbat2	1.25	sub-type using the <b>rc_sys</b> variable in <path>/etc/rc.conf</path>. The
469			sub-type should be set to match the virtualization environment that the given
470			root is in. In general, the non-empty <b>rc_sys</b> value should be within the
471			virtual containers; The host node will have <b>rc_sys=""</b>.
472	robbat2	1.23	</p>
473
474			<impo>
475			If you do not have any specific sub-type, please use the default of an empty
476			string <b>""</b>. If the variable is unset, you will be given a warning and we
477			will attempt to use the old detection algorithm.
478			</impo>
479
480			<pre caption="Setting system sub-type to none in /etc/rc.conf">
481			rc_sys=""
482			</pre>
483
484			<p>The detection algorithm had to be replaced with manual configuration due to
485			the introduction of new sub-types and changes to the kernel that made prior
486			detection unreliable.</p>
487
488			<table>
489			<tr>
490			<th>Subtype</th>
491			<th>Description</th>
492			<th>Notes</th>
493			</tr>
494			<tr>
495			<ti></ti>
496			<ti>Default, no sub-type</ti>
497			<ti>Not the same as unset; FreeBSD, Linux & NetBSD</ti>
498			</tr>
499			<tr>
500			<ti>jail</ti>
501			<ti>FreeBSD jails</ti>
502			<ti></ti>
503			</tr>
504			<tr>
505			<ti>lxc</ti>
506			<ti>Linux Containers</ti>
507			<ti>Not auto-detected</ti>
508			</tr>
509			<tr>
510			<ti>openvz</ti>
511			<ti>Linux OpenVZ</ti>
512			<ti></ti>
513			</tr>
514			<tr>
515			<ti>prefix</ti>
516			<ti>Prefix</ti>
517			<ti>Not auto-detected; FreeBSD, Linux & NetBSD</ti>
518			</tr>
519			<tr>
520			<ti>uml</ti>
521			<ti>Usermode Linux</ti>
522			<ti></ti>
523			</tr>
524			<tr>
525			<ti>vserver</ti>
526			<ti>Linux vserver</ti>
527			<ti></ti>
528			</tr>
529			<tr>
530			<ti>xen0</ti>
531			<ti>Xen0 Domain</ti>
532			<ti>Linux & NetBSD</ti>
533			</tr>
534			<tr>
535			<ti>xenU</ti>
536			<ti>XenU Domain</ti>
537			<ti>Linux & NetBSD</ti>
538			</tr>
539			</table>
540
541			</body>
542			</section>
543			<!-- =============================================================== -->
544
545	nightmorph	1.11	<section>
546	nightmorph	1.1	<title>Finishing up</title>
547			<body>
548
549			<p>
550			Once you've finished updating your config files and initscripts, the last thing
551			to do is <b>reboot</b>. This is necessary because system state information is
552			not preserved during the upgrade, so you'll need to provide it with a fresh
553			boot.
554			</p>
555
556			</body>
557			</section>
558	robbat2	1.22	<!-- =============================================================== -->
559
560	nightmorph	1.1	</chapter>
561	jkt	1.19	<chapter>
562			<title>Changed functionality</title>
563	robbat2	1.22	<!-- =============================================================== -->
564
565	jkt	1.19	<section>
566			<title>The pause action</title>
567			<body>
568
569			<p>
570			Previously it was possible to temporarily stop a service without taking down all
571			the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
572			<c>pause</c> action was removed; this functionality is supported by the
573			<c>/etc/init.d/service --nodeps stop</c>, which also works in the old
574			baselayout.
575			</p>
576
577			</body>
578			</section>
579	robbat2	1.22	<!-- =============================================================== -->
580
581	jkt	1.19	</chapter>
582	nightmorph	1.1	</guide>