1: # Updating an existing system from sources
2:
3: A common mechanism for upgrading a NetBSD system to a newer version is by
4: rebuilding the system from sources and installing the results. This works both
5: for stable releases such as [NetBSD 5.0](/releases/formal-5/) and for
6: NetBSD-current. In particular, if you are running a stable NetBSD release in a
7: production environment, you are encouraged to perform this procedure regularly
8: in order to incorporate any security fixes that have been applied to the branch
9: since its release.
10:
11: There are a variety of ways of achieving the goal of rebuilding NetBSD from
12: source, and this chapter will guide you through the variety of options that are
13: available. The chapter starts by showing first what the manual procedure looks
14: like, and proceeds to describe some of automation tools that simplify the
15: process.
16:
17: **Note**: Please remember to check
18: [src/UPDATING](http://cvsweb.NetBSD.org/bsdweb.cgi/src/UPDATING) for the latest
19: changes and special instructions that may be involved in upgrading the system.*
20:
21: ## Manual build and update procedure
22:
23: Most of the following steps can be done as ordinary user. Only the installation
24: of a new kernel and the userland will require root privileges. Although `/usr`
25: is choosen as the working directory in the following examples, the procedure
26: can also take place in a user's home directory. Ordinary users have normally
27: not the permissions to make changes in `/usr`, but this can be changed by root.
28:
29: Having up-to-date sources is a prerequisite for the following steps.
30: [[Fetching by CVS|guide/fetch#cvs] informs about the ways to retrieve or update
31: the sources for a release, stable or current branch (using CVS).
32:
33: Please always refer to the output of **build.sh -h** and the files `UPDATING`
34: and `BUILDING` for details - it's worth it, there are *many* options that can
35: be set on the command line or in `/etc/mk.conf`
36:
37: ### Building a new userland
38:
39: The first step is to build the userland:
40:
41: $ cd /usr/src
42: $ ./build.sh -O ../obj -T ../tools -U distribution
43:
44: ### Building a new kernel
45:
46: The next step will build the kernel:
47:
48: $ cd /usr/src
49: $ ./build.sh -O ../obj -T ../tools kernel=<KERNEL>
50:
51: ### Installing the kernel and userland
52:
53: Installing the new kernel, rebooting (to ensure that the new kernel works) and
54: installing the new userland are the final steps of the updating procedure:
55:
56: $ cd /usr/src
57: $ su
58: # mv /netbsd /netbsd.old
59: # mv /usr/obj/sys/arch/<ARCH>/compile/<KERNEL>/netbsd /
60: # shutdown -r now
61: ...
62: $ cd /usr/src
63: $ su
64: # ./build.sh -O ../obj -T ../tools -U install=/
65:
66: If the new kernel `netbsd` does not boot successfully, you can fall back on
67: booting the `netbsd.old` kernel.
68:
69: ### Updating the system configuration files
70:
71: Run the `etcupdate` script
72: ([etcupdate(8)](http://netbsd.gw.com/cgi-bin/man-cgi?etcupdate+8+NetBSD-5.0.1+i386))
73: and follow the instructions in the output for fixing obsolete files:
74:
75: # /usr/sbin/etcupdate -s /usr/src
76:
77: Optionally reboot to ensure all running services are using the new binaries:
78:
79: # shutdown -r now
80:
81: ### Summary
82:
83: 1. From the root of the source tree:
84:
85: $ cd /usr/src
86:
87: 2. Build the userland:
88:
89: $ ./build.sh -O ../obj -T ../tools -U -u distribution
90:
91: 3. Build the kernel:
92:
93: $ ./build.sh -O ../obj -T ../tools -U -u kernel=GENERIC
94:
95: 4. Install the kernel:
96:
97: $ cd ../obj/sys/arch/<ARCH>/compile/GENERIC
98: $ su
99: # mv /netbsd /netbsd.old
100: # cp netbsd /netbsd
101:
102: 5. Reboot into the new kernel:
103:
104: # shutdown -r now
105:
106: 6. Install the new userland:
107:
108: $ cd /usr/src
109: $ su
110: # ./build.sh -O ../obj -T ../tools -U install=/
111:
112: 7. Update the system and configuration files;:
113:
114: # /usr/sbin/etcupdate -s /usr/src
115:
116: **Note**: In the procedure above, the `-u` option indicates an update process,
117: and that a `make clean` operation should not be run before starting the build.
118: This is useful when doing an update from a previous build and/or a fresh build.
119: The `-U` option allows the entire build by a non-root user followed with an
120: install by root.
121:
122: ## Using sysinst
123:
124: It is also possible to use `sysinst` to install a freshly built system. The
125: steps are as follows:
126:
127: 1. Build a complete release:
128:
129: $ ./build.sh -O ../obj -T ../tools -U -u -x release
130:
131: 2. The resulting install sets will be in the `/usr/obj/releasedir/` directory.
132: 3. Copy the install kernel to the root directory of your NetBSD system, reboot
133: from it, and upgrade with `sysinst` (see
134: [[Upgrading NetBSD|guide/upgrading]]).
135:
136:
137: ## Using sysbuild and sysupgrade
138:
139: The sysbuild and sysupgrade tools (currently available in
140: `pkgsrc/sysutils/sysbuild` and `pkgsrc/sysutils/sysupgrade` respectively)
141: automate the full process of rebuilding NetBSD from sources (*including the
142: retrieval of the sources from a CVS repository*) and installing the results
143: with minimal effort.
144:
145: Both of these tools have configuration files to determine how to build a
146: release and how to install it. Among other things, these specify the CVS
147: repository to use, what architecture to build for, where to place the build
148: files and what steps to perform during an upgrade. The files can be found in
149: `/usr/pkg/etc/sysbuild/default.conf` and `/usr/pkg/etc/sysupgrade.conf`. The
150: default configuration of both tools should let you get started with minimal
151: effort.
152:
153: In their simplest form, you can do a full NetBSD build and upgrade your system
154: to it by running these commands:
155:
156: # sysbuild build
157: # sysupgrade auto ~/sysbuild/release/$(uname -m)
158:
159: And that's all that it takes. These invocations will do the following:
160:
161: 1. Download the source trees from CVS into `/usr/src` and `/usr/xsrc`. The
162: latter is only fetched if your system has X11. And, if you already have
163: the sources in your system, this will only update them to the newest
164: version.
165: 2. Build a new release into `~/sysbuild/<machine>/`. This per-machine
166: directory will include subdirectories like `obj`, `destdir`, etc. The
167: build results will be left in `~/sysbuild/release/<machine>/`.
168: 3. Install a new kernel and unpack the new sets using the just-built release
169: files.
170: 4. Run both etcupdate and postinstall to aid you in merging new configuration
171: changes into your system.
172:
173: For more details, please see the included `sysbuild(1)` and `sysupgrade(8)`
174: manual pages, as well as the comments in the referenced configuration files.
175:
176: ### Tweak: Building as non-root
177:
178: The commands above depict the most basic and simple invocation of the tools
179: using the *default configuration files*. One drawback is that you require root
180: access during the build of the source tree so that sysbuild can upgrade the
181: source trees under `/usr/src` and `/usr/xsrc`. It is recommended that you avoid
182: building as root once you are familiar with the procedure, and this section
183: show what is needed to do so with sysbuild.
184:
185: In order to build as non-root, you can either choose to store your source trees
186: out of `/usr` (easiest) or give permissions to your user to modify the trees
187: under `/usr` (good if you want to share the source tree with more than one
188: user).
189:
190: If you want to store the source trees under your home directory, which is
191: convenient for development purposes, simply edit `/usr/pkg/etc/sysbuild.conf`
192: and add these settings:
193:
194: SRCDIR="${HOME}/sysbuild/src"
195: [ ! -f /etc/mtree/set.xbase ] || XSRCDIR="${HOME}/sysbuild/xsrc"
196:
197: Once this is done, the `sysbuild build` invocation show above should just work
198: under your unprivileged user. The upgrade procedure then becomes:
199:
200: $ sysbuild build
201: ... become root ...
202: # sysupgrade auto ~/sysbuild/release/$(uname -m)
203:
204: The other alternative, in case you want to maintain your source trees in the
205: locations described by
206: [hier(7)](http://netbsd.gw.com/cgi-bin/man-cgi?hier+7+NetBSD-5.0.1+i386), is
207: to do the following as root:
208:
209: # mkdir -p /usr/src /usr/xsrc
210: # chown -R <your-user>:wsrc /usr/src /usr/xsrc
211: ... and optionally add <your-user> to wsrc in /etc/group ...
212:
213: After this, the default configuration file of sysbuild will let you place the
214: files in these locations and let you do unprivileged builds.
215:
216: **Note**: If you have an an encrypted home partition, or another "special"
217: filesystem you store your sources on, you should backup them somehwere you can
218: easily access them! In case of a failed build you might want to rebuild without
219: being able to access an encrypted partition.
220:
221: ### Tweak: Setting up nightly builds
222:
223: The `pkgsrc/sysutils/sysbuild-user` package can be used to configure and
224: maintain an unprivileged system user to perform periodic (e.g. nightly) builds
225: from source. This can come in very handy to closely track NetBSD-current.
226:
227: The installed user is appropriately named sysbuild, and is configured by
228: default to run a full system build overnight. The results are left in
229: `/home/sysbuild/release/<machine>/`, which is the convenient default of
230: sysupgrade's release directory. Any build failures will be reported to you by
231: email.
232:
233: The behavior of sysbuild for this unprivileged user is configured in
234: `/home/sysbuild/default.conf`.
235:
236: You can interact with sysbuild under this unprivileged user by running
237: commands of the form:
238:
239: # su - sysbuild /usr/pkg/bin/sysbuild ...
240:
241: ## More details about the updating of configuration and startup files
242:
243: [etcupdate(8)](http://netbsd.gw.com/cgi-bin/man-cgi?etcupdate+8+NetBSD-current)
244: is a script to help users compare, merge and install new configuration and
245: startup files (files found in the `etc.tgz` distribution set) in `/dev`, `/etc`
246: and `/root` after performing an operating system upgrade. The upgrade of the
247: operating system could have been performed either by compiling sources or by
248: extracting the distribution binaries.
249:
250: ### Using etcupdate with source files
251:
252: In case where the sources are in `/usr/src` the following command should be enough:
253:
254: # etcupdate
255:
256: But what if your NetBSD sources are in an alternative location, such as in
257: `/home/jdoe/netbsd/src`? Don't worry, tell etcupdate the location of your
258: source tree with `-s srcdir` and it will work just fine:
259:
260: # etcupdate -s /home/jdoe/netbsd/src
261:
262: ### Using etcupdate with binary distribution sets
263:
264: Sometimes it's not convenient to have the sources around but you still want to
265: update the configuration and startup files. The solution is to feed `etc.tgz`
266: (or `xetc.tgz`) to etcupdate via the `-s tgzfile` switch:
267:
268: # etcupdate -s /some/where/etc.tgz
269:
270: ### Using `etcmanage` instead of `etcupdate`
271:
272: The `etcmanage` perl script (available from
273: [pkgsrc/sysutils/etcmanage](http://pkgsrc.se/sysutils/etcmanage) or as binary
274: package) is an alternative to etcupdate(8). It should be used in the following
275: way, in combination with
276: [postinstall(8)](http://netbsd.gw.com/cgi-bin/man-cgi?postinstall+8+NetBSD-5.0.1+i386):
277:
278: # /usr/pkg/bin/etcmanage
279: # /usr/sbin/postinstall
280:
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to updating.mdwn CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [NetBSD Developer Wiki] / wikisrc / guide