<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter3. Õpdating an existing system from sources</title>
<link rel="stylesheet" type="text/css" href="/global.css">
<meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
<link rel="home" href="index.html" title="The NetBSD Guide">
<link rel="up" href="part-compile.html" title="Part Ö. Âuilding the system">
<link rel="prev" href="chap-kernel.html" title="Chapter2. Ãompiling the kernel">
<link rel="next" href="chap-inst-media.html" title="Chapter4. Âuilding NetBSD installation media">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter3. Õpdating an existing system from sources</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="chap-kernel.html">Prev</a>/td>
<th width="60%" align="center">Part Ö. Âuilding the system</th>
<td width="20%" align="right">a accesskey="n" href="chap-inst-media.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="chap-updating"></a>Chapter3. Õpdating an existing system from sources</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="sect1"><a href="chap-updating.html#updating-procedure">33.1. Manual build and update procedure</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="chap-updating.html#updating-userland">33.1.1. Building a new userland</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#updating-kernel">33.1.2. Building a new kernel</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#updating-installing">33.1.3. Installing the kernel and userland</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#updating-configfiles">33.1.4. Updating the system configuration files</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#updating-summary">33.1.5. Summary</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="chap-updating.html#updating-sysinst">33.2. Using sysinst</a></span></dt>
<dt><span class="sect1"><a href="chap-updating.html#updating-sysbuild-sysupgrade">33.3. Using sysbuild and sysupgrade</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="chap-updating.html#building-as-non-root">33.3.1. Tweak: Building as non-root</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#setting-up-nightly-builds">33.3.2. Tweak: Setting up nightly builds</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="chap-updating.html#updating-etcupdate">33.4. More details about the updating of configuration and startup files</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="chap-updating.html#updating-etcupdate-source">33.4.1. Using etcupdate with source files</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#updating-etcupdate-binary">33.4.2. Using etcupdate with binary distribution sets</a></span></dt>
<dt><span class="sect2"><a href="chap-updating.html#updating-etcmanage">33.4.3. Using <code class="filename">etcmanage</code> instead of <code class="filename">etcupdate</code></a></span></dt>
</dl></dd>
</dl>
</div>
<p>A common mechanism for upgrading a NetBSD system to a newer
version is by rebuilding the system from sources and installing the
results. This works both for stable releases such as <a class="ulink" href="../releases/formal-5/" target="_top">NetBSD 5.0</a> and for NetBSD-current.
In particular, if you are running a stable NetBSD release in a
production environment, you are encouraged to perform this procedure
regularly in order to incorporate any security fixes that have been
applied to the branch since its release.</p>
<p>There are a variety of ways of achieving the goal of rebuilding
NetBSD from source, and this chapter will guide you through the
variety of options that are available. The chapter starts by showing
first what the manual procedure looks like, and proceeds to describe
some of automation tools that simplify the process.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
<span class="emphasis"><em>Please remember to check
<a class="ulink" href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/UPDATING" target="_top">src/UPDATING</a>
for the latest changes and special instructions that may be involved
in upgrading the system.</em></span>
</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="updating-procedure"></a>33.1. Íanual build and update procedure</h2></div></div></div>
<p>Most of the following steps can be done as ordinary user.
Only the installation of a new kernel and the userland will require
root privileges.
Although <code class="filename">/usr</code> is choosen as the working
directory in the following examples, the procedure can also
take place in a user's home directory. Ordinary users have normally not
the permissions to make changes in <code class="filename">/usr</code>,
but this can be changed by root.
</p>
<p>Having up-to-date sources is a prerequisite for the following steps.
<a class="xref" href="chap-fetch.html#chap-fetch-cvs" title="30.4. Æetching by CVS">Section0.4, “Fetching by CVS”</a> informs about
the ways to retrieve or update the sources for a release, stable or current
branch (using CVS).</p>
<p>
Please always refer to the output of <span class="command"><strong>build.sh -h</strong></span>
and the files <code class="filename">UPDATING</code> and
<code class="filename">BUILDING</code> for details - it's worth
it, there are <span class="emphasis"><em>many</em></span> options that can
be set on the command line or in
<code class="filename">/etc/mk.conf</code>
</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-userland"></a>33.1.1. Âuilding a new userland</h3></div></div></div>
<p>The first step is to build the userland:</p>
<pre class="screen">
<code class="prompt">$</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U distribution</code></strong></pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-kernel"></a>33.1.2. Âuilding a new kernel</h3></div></div></div>
<p>The next step will build the kernel:</p>
<pre class="screen">
<code class="prompt">$</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U kernel=<KERNEL></code></strong>
</pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-installing"></a>33.1.3. Énstalling the kernel and userland</h3></div></div></div>
<p>Installing the new kernel, rebooting (to ensure that the new kernel
works) and installing the new userland are the final steps of the updating
procedure:</p>
<pre class="screen">
<code class="prompt">$</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>su</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mv /netbsd /netbsd.old</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mv /usr/obj/sys/arch/<ARCH>/compile/<KERNEL>/netbsd /</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>shutdown -r now</code></strong>
...
<code class="prompt">$</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>su</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U install=/</code></strong></pre>
<p>If the new kernel <code class="filename">netbsd</code> does not boot
successfully, you can fall back on booting the
<code class="filename">netbsd.old</code> kernel.</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-configfiles"></a>33.1.4. Õpdating the system configuration files</h3></div></div></div>
<p>
Updating your system's configuration files is done in two steps. First,
<a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?postinstall+8.i386+NetBSD-7.1.2"><span class="citerefentry"><span class="refentrytitle">postinstall</span>(8)</span></a> is used to check and fix things that can be easily
automated. Afterwards, <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?etcupdate+8.i386+NetBSD-7.1.2"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> is used to merge the remaining
configuration file changes.
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>/usr/sbin/postinstall -s /usr/src check</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>/usr/sbin/postinstall -s /usr/src fix</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>/usr/sbin/etcupdate -s /usr/src</code></strong></pre>
<p>
</p>
<p>
Optionally reboot to ensure all running services are using the new binaries:
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>shutdown -r now</code></strong></pre>
<p>
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-summary"></a>33.1.5. Óummary</h3></div></div></div>
<div class="procedure"><ol class="procedure" type="1">
<li class="step">
<p>From the root of the source tree:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>cd /usr/src</code></strong></pre>
</li>
<li class="step">
<p>Build the userland:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U -u distribution</code></strong></pre>
</li>
<li class="step">
<p>Build the kernel:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U -u kernel=GENERIC</code></strong></pre>
</li>
<li class="step">
<p>Install the kernel:
</p>
<pre class="screen">
<code class="prompt">$</code> <strong class="userinput"><code>cd ../obj/sys/arch/<ARCH>/compile/GENERIC</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>su</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mv /netbsd /netbsd.old</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>cp netbsd /netbsd</code></strong></pre>
</li>
<li class="step">
<p>Reboot into the new kernel:
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>shutdown -r now</code></strong></pre>
</li>
<li class="step">
<p>Install the new userland:
</p>
<pre class="screen">
<code class="prompt">$</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>su</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U install=/</code></strong></pre>
</li>
<li class="step">
<p>Update the system and configuration files;:
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code> /usr/sbin/etcupdate -s /usr/src</code></strong></pre>
</li>
</ol></div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
In the procedure above, the <code class="option">-u</code> option indicates an update process,
and that a make clean operation should not be run before starting the build. This is
useful when doing an update from a previous build and/or a fresh build. The
<code class="option">-U</code> option allows the entire build by a non-root user
followed with an install by root.
</p>
</div>
</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="updating-sysinst"></a>33.2. Õsing sysinst</h2></div></div></div>
<p> It is also possible to use <code class="filename">sysinst</code> to install a freshly
built system. The steps are as follows:</p>
<div class="procedure"><ol class="procedure" type="1">
<li class="step">
<p>Build a complete release:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>./build.sh -O ../obj -T ../tools -U -u -x release</code></strong></pre>
<p>
</p>
</li>
<li class="step"><p>The resulting install sets will be in the
<code class="filename">/usr/obj/releasedir/</code> directory.</p></li>
<li class="step"><p>Copy the install kernel to the root directory of your NetBSD system,
reboot from it, and upgrade with <code class="filename">sysinst</code>
(see <a class="xref" href="chap-upgrading.html" title="Chapter. Õpgrading NetBSD">Chapter, <i>Upgrading NetBSD</i></a>).</p></li>
</ol></div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="updating-sysbuild-sysupgrade"></a>33.3. Õsing sysbuild and sysupgrade</h2></div></div></div>
<p>The <span class="application">sysbuild</span> and
<span class="application">sysupgrade</span> tools (currently available in
<code class="filename">pkgsrc/sysutils/sysbuild</code> and
<code class="filename">pkgsrc/sysutils/sysupgrade</code> respectively) automate
the full process of rebuilding NetBSD from sources
(<span class="emphasis"><em>including the retrieval of the sources from a CVS
repository</em></span>) and installing the results with minimal
effort.</p>
<p>Both of these tools have configuration files to determine how to
build a release and how to install it. Among other things, these
specify the CVS repository to use, what architecture to build for,
where to place the build files and what steps to perform during an
upgrade. The files can be found in
<code class="filename">/usr/pkg/etc/sysbuild/default.conf</code> and
<code class="filename">/usr/pkg/etc/sysupgrade.conf</code>. The default
configuration of both tools should let you get started with minimal
effort.</p>
<p>In their simplest form, you can do a full NetBSD build and
upgrade your system to it by running these commands:</p>
<pre class="screen">
<code class="prompt">#</code> <strong class="userinput"><code>sysbuild build</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>sysupgrade auto ~/sysbuild/release/$(uname -m)</code></strong>
</pre>
<p>And that's all that it takes. These invocations will do the
following:</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p>Download the source trees from CVS into
<code class="filename">/usr/src</code> and <code class="filename">/usr/xsrc</code>.
The latter is only fetched if your system has X11. And, if you
already have the sources in your system, this will only update
them to the newest version.</p></li>
<li class="listitem"><p>Build a new release into
<code class="filename">~/sysbuild/<machine>/</code>. This
per-machine directory will include subdirectories like
<code class="filename">obj</code>, <code class="filename">destdir</code>, etc. The
build results will be left in
<code class="filename">~/sysbuild/release/<machine>/</code>.</p></li>
<li class="listitem"><p>Install a new kernel and unpack the new sets using the
just-built release files.</p></li>
<li class="listitem"><p>Run both <span class="application">etcupdate</span> and
<span class="application">postinstall</span> to aid you in merging new
configuration changes into your system.</p></li>
</ol></div>
<p>For more details, please see the included sysbuild(1) and
sysupgrade(8) manual pages, as well as the comments in the referenced
configuration files.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="building-as-non-root"></a>33.3.1. Ôweak: Building as non-root</h3></div></div></div>
<p>The commands above depict the most basic and simple invocation
of the tools using the <span class="emphasis"><em>default configuration
files</em></span>. One drawback is that you require root access
during the build of the source tree so that
<span class="application">sysbuild</span> can upgrade the source trees
under <code class="filename">/usr/src</code> and
<code class="filename">/usr/xsrc</code>. It is recommended that you avoid
building as root once you are familiar with the procedure, and this
section show what is needed to do so with
<span class="application">sysbuild</span>.</p>
<p>In order to build as non-root, you can either choose to store
your source trees out of <code class="filename">/usr</code> (easiest) or give
permissions to your user to modify the trees under
<code class="filename">/usr</code> (good if you want to share the source tree
with more than one user).</p>
<p>If you want to store the source trees under your home
directory, which is convenient for development purposes, simply edit
<code class="filename">/usr/pkg/etc/sysbuild.conf</code> and add these
settings:</p>
<pre class="programlisting">
SRCDIR="${HOME}/sysbuild/src"
[ ! -f /etc/mtree/set.xbase ] || XSRCDIR="${HOME}/sysbuild/xsrc"
</pre>
<p>Once this is done, the "sysbuild build" invocation show above
should just work under your unprivileged user. The upgrade
procedure then becomes:</p>
<pre class="screen">
<code class="prompt">$</code> <strong class="userinput"><code>sysbuild build</code></strong>
... become root ...
<code class="prompt">#</code> <strong class="userinput"><code>sysupgrade auto ~/sysbuild/release/$(uname -m)</code></strong>
</pre>
<p>The other alternative, in case you want to maintain your
source trees in the locations described by <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?hier+7.i386+NetBSD-7.1.2"><span class="citerefentry"><span class="refentrytitle">hier</span>(7)</span></a>, is to do
the following as root:</p>
<pre class="screen">
<code class="prompt">#</code> <strong class="userinput"><code>mkdir -p /usr/src /usr/xsrc</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>chown -R <your-user>:wsrc /usr/src /usr/xsrc</code></strong>
... and optionally add <your-user> to wsrc in /etc/group ...
</pre>
<p>After this, the default configuration file of
<span class="application">sysbuild</span> will let you place the files in
these locations and let you do unprivileged builds.</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="setting-up-nightly-builds"></a>33.3.2. Ôweak: Setting up nightly builds</h3></div></div></div>
<p>The <code class="filename">pkgsrc/sysutils/sysbuild-user</code> package
can be used to configure and maintain an unprivileged system user to
perform periodic (e.g. nightly) builds from source. This can come
in very handy to closely track NetBSD-current.</p>
<p>The installed user is appropriately named sysbuild, and is
configured by default to run a full system build overnight. The
results are left in
<code class="filename">/home/sysbuild/release/<machine>/</code>, which
is the convenient default of <span class="application">sysupgrade</span>'s
release directory. Any build failures will be reported to you by
email.</p>
<p>The behavior of <span class="application">sysbuild</span> for this
unprivileged user is configured in
<code class="filename">/home/sysbuild/default.conf</code>.</p>
<p>You can interact with <span class="application">sysbuild</span>
under this unprivileged user by running commands of the form:</p>
<pre class="screen">
<code class="prompt">#</code> <strong class="userinput"><code>su - sysbuild /usr/pkg/bin/sysbuild ...</code></strong>
</pre>
</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="updating-etcupdate"></a>33.4. Íore details about the updating of configuration and startup files</h2></div></div></div>
<p><code class="filename">etcupdate</code> is a script to help users compare,
merge and install new configuration and startup files (files found in the etc.tgz
distribution set) in /dev, /etc and /root after performing an operating
system upgrade. The upgrade of the operating system could have
been performed either by compiling sources or by extracting
the distribution binaries.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-etcupdate-source"></a>33.4.1. Õsing etcupdate with source files</h3></div></div></div>
<p>
In case where the sources are in /usr/src the following command should be
enough:
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate</code></strong></pre>
<p>
But what if your NetBSD sources are in an alternative location, such as
in <code class="filename">/home/jdoe/netbsd/src</code>? Don't worry, tell
etcupdate the location of your source tree with -s srcdir and it will work
just fine:
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate -s /home/jdoe/netbsd/src</code></strong></pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-etcupdate-binary"></a>33.4.2. Õsing etcupdate with binary distribution sets</h3></div></div></div>
<p>
Sometimes it's not convenient to have the sources around but you still
want to update the configuration and startup files.
The solution is to feed etc.tgz (or xetc.tgz) to etcupdate via
the -s tgzfile switch.
</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate -s /some/where/etc.tgz</code></strong></pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="updating-etcmanage"></a>33.4.3. Õsing <code class="filename">etcmanage</code> instead of <code class="filename">etcupdate</code>
</h3></div></div></div>
<p>The <code class="filename">etcmanage</code> perl script (available from
<a class="ulink" href="http://pkgsrc.se/sysutils/etcmanage" target="_top">pkgsrc/sysutils/etcmanage</a>
or as binary package) is an alternative to <code class="filename">etcupdate</code>.
It should be used in the following way, in combination with <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?postinstall+8.i386+NetBSD-7.1.2"><span class="citerefentry"><span class="refentrytitle">postinstall</span>(8)</span></a>:
</p>
<pre class="screen">
<code class="prompt">#</code> <strong class="userinput"><code>/usr/pkg/bin/etcmanage</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>/usr/sbin/postinstall</code></strong></pre>
<p>
</p>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="chap-kernel.html">Prev</a>/td>
<td width="20%" align="center"><a accesskey="u" href="part-compile.html">Up</a></td>
<td width="40%" align="right">a accesskey="n" href="chap-inst-media.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter2. Ãompiling the kernel/td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Ãhapter4. Âuilding NetBSD installation media</td>
</tr>
</table>
</div>
</body>
</html>