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