Annotation of wikisrc/guide/updating.mdwn, revision 1.4

1.4     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
1.1       jdf         5: # Updating an existing system from sources
                      6: 
                      7: A common mechanism for upgrading a NetBSD system to a newer version is by
                      8: rebuilding the system from sources and installing the results. This works both
                      9: for stable releases such as [NetBSD 5.0](/releases/formal-5/) and for
                     10: NetBSD-current. In particular, if you are running a stable NetBSD release in a
                     11: production environment, you are encouraged to perform this procedure regularly
                     12: in order to incorporate any security fixes that have been applied to the branch
                     13: since its release.
                     14: 
                     15: There are a variety of ways of achieving the goal of rebuilding NetBSD from
                     16: source, and this chapter will guide you through the variety of options that are
                     17: available. The chapter starts by showing first what the manual procedure looks
                     18: like, and proceeds to describe some of automation tools that simplify the
                     19: process.
                     20: 
1.2       jdf        21: **Note**: Please remember to check
1.1       jdf        22: [src/UPDATING](http://cvsweb.NetBSD.org/bsdweb.cgi/src/UPDATING) for the latest
                     23: changes and special instructions that may be involved in upgrading the system.*
                     24: 
                     25: ## Manual build and update procedure
                     26: 
                     27: Most of the following steps can be done as ordinary user. Only the installation
                     28: of a new kernel and the userland will require root privileges. Although `/usr`
                     29: is choosen as the working directory in the following examples, the procedure
                     30: can also take place in a user's home directory. Ordinary users have normally
                     31: not the permissions to make changes in `/usr`, but this can be changed by root.
                     32: 
                     33: Having up-to-date sources is a prerequisite for the following steps.
                     34: [[Fetching by CVS|guide/fetch#cvs] informs about the ways to retrieve or update
                     35: the sources for a release, stable or current branch (using CVS).
                     36: 
                     37: Please always refer to the output of **build.sh -h** and the files `UPDATING`
                     38: and `BUILDING` for details - it's worth it, there are *many* options that can
                     39: be set on the command line or in `/etc/mk.conf`
                     40: 
                     41: ### Building a new userland
                     42: 
                     43: The first step is to build the userland:
                     44: 
                     45:     $ cd /usr/src
                     46:     $ ./build.sh -O ../obj -T ../tools -U distribution
                     47: 
                     48: ### Building a new kernel
                     49: 
                     50: The next step will build the kernel:
                     51: 
                     52:     $ cd /usr/src
                     53:     $ ./build.sh -O ../obj -T ../tools kernel=<KERNEL>
                     54: 
                     55: ### Installing the kernel and userland
                     56: 
                     57: Installing the new kernel, rebooting (to ensure that the new kernel works) and
                     58: installing the new userland are the final steps of the updating procedure:
                     59: 
                     60:     $ cd /usr/src
                     61:     $ su
                     62:     # mv /netbsd /netbsd.old
                     63:     # mv /usr/obj/sys/arch/<ARCH>/compile/<KERNEL>/netbsd /
                     64:     # shutdown -r now
                     65:      ...
                     66:     $ cd /usr/src
                     67:     $ su
                     68:     # ./build.sh -O ../obj -T ../tools -U install=/
                     69: 
                     70: If the new kernel `netbsd` does not boot successfully, you can fall back on
                     71: booting the `netbsd.old` kernel.
                     72: 
                     73: ### Updating the system configuration files
                     74: 
                     75: Run the `etcupdate` script
                     76: ([etcupdate(8)](http://netbsd.gw.com/cgi-bin/man-cgi?etcupdate+8+NetBSD-5.0.1+i386))
                     77: and follow the instructions in the output for fixing obsolete files:
                     78: 
                     79:     # /usr/sbin/etcupdate -s /usr/src
                     80: 
                     81: Optionally reboot to ensure all running services are using the new binaries:
                     82: 
                     83:     # shutdown -r now
                     84: 
                     85: ### Summary
                     86: 
                     87:  1. From the root of the source tree:
                     88: 
                     89:         $ cd /usr/src
                     90: 
                     91:  2. Build the userland:
                     92: 
                     93:         $ ./build.sh -O ../obj -T ../tools -U -u distribution
                     94: 
                     95:  3. Build the kernel:
                     96: 
                     97:         $ ./build.sh -O ../obj -T ../tools -U -u kernel=GENERIC
                     98: 
                     99:  4. Install the kernel:
                    100: 
                    101:         $ cd ../obj/sys/arch/<ARCH>/compile/GENERIC
                    102:         $ su
                    103:         # mv /netbsd /netbsd.old
                    104:         # cp netbsd /netbsd
                    105: 
                    106:  5. Reboot into the new kernel:
                    107: 
                    108:         # shutdown -r now
                    109: 
                    110:  6. Install the new userland:
                    111: 
                    112:         $ cd /usr/src
                    113:         $ su
                    114:         # ./build.sh -O ../obj -T ../tools -U install=/
                    115: 
                    116:  7. Update the system and configuration files;:
                    117: 
                    118:         #  /usr/sbin/etcupdate -s /usr/src
                    119: 
1.2       jdf       120: **Note**: In the procedure above, the `-u` option indicates an update process,
                    121: and that a `make clean` operation should not be run before starting the build.
                    122: This is useful when doing an update from a previous build and/or a fresh build.
                    123: The `-U` option allows the entire build by a non-root user followed with an
                    124: install by root.
1.1       jdf       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: 
1.2       jdf       220: **Note**: If you have an an encrypted home partition, or another "special"
                    221: filesystem you store your sources on, you should backup them somehwere you can
                    222: easily access them! In case of a failed build you might want to rebuild without
                    223: being able to access an encrypted partition.
1.1       jdf       224: 
                    225: ### Tweak: Setting up nightly builds
                    226: 
                    227: The `pkgsrc/sysutils/sysbuild-user` package can be used to configure and
                    228: maintain an unprivileged system user to perform periodic (e.g. nightly) builds
                    229: from source. This can come in very handy to closely track NetBSD-current.
                    230: 
                    231: The installed user is appropriately named sysbuild, and is configured by
                    232: default to run a full system build overnight. The results are left in
                    233: `/home/sysbuild/release/<machine>/`, which is the convenient default of
                    234: sysupgrade's release directory. Any build failures will be reported to you by
                    235: email.
                    236: 
                    237: The behavior of sysbuild for this unprivileged user is configured in
                    238: `/home/sysbuild/default.conf`.
                    239: 
                    240: You can interact with sysbuild under this unprivileged user by running
                    241: commands of the form:
                    242: 
                    243:     # su - sysbuild /usr/pkg/bin/sysbuild ...
                    244: 
                    245: ## More details about the updating of configuration and startup files
                    246: 
                    247: [etcupdate(8)](http://netbsd.gw.com/cgi-bin/man-cgi?etcupdate+8+NetBSD-current)
                    248: is a script to help users compare, merge and install new configuration and
                    249: startup files (files found in the `etc.tgz` distribution set) in `/dev`, `/etc`
                    250: and `/root` after performing an operating system upgrade. The upgrade of the
                    251: operating system could have been performed either by compiling sources or by
                    252: extracting the distribution binaries.
                    253: 
                    254: ### Using etcupdate with source files
                    255: 
                    256: In case where the sources are in `/usr/src` the following command should be enough:
                    257: 
                    258:     # etcupdate
                    259: 
                    260: But what if your NetBSD sources are in an alternative location, such as in
                    261: `/home/jdoe/netbsd/src`? Don't worry, tell etcupdate the location of your
                    262: source tree with `-s srcdir` and it will work just fine:
                    263: 
                    264:     # etcupdate -s /home/jdoe/netbsd/src
                    265: 
                    266: ### Using etcupdate with binary distribution sets
                    267: 
                    268: Sometimes it's not convenient to have the sources around but you still want to
                    269: update the configuration and startup files. The solution is to feed `etc.tgz`
                    270: (or `xetc.tgz`) to etcupdate via the `-s tgzfile` switch:
                    271: 
                    272:     # etcupdate -s /some/where/etc.tgz
                    273: 
1.3       jdf       274: ### Using etcmanage instead of etcupdate
1.1       jdf       275: 
                    276: The `etcmanage` perl script (available from
                    277: [pkgsrc/sysutils/etcmanage](http://pkgsrc.se/sysutils/etcmanage) or as binary
                    278: package) is an alternative to etcupdate(8). It should be used in the following
                    279: way, in combination with
                    280: [postinstall(8)](http://netbsd.gw.com/cgi-bin/man-cgi?postinstall+8+NetBSD-5.0.1+i386):
                    281: 
                    282:     # /usr/pkg/bin/etcmanage
                    283:     # /usr/sbin/postinstall
                    284: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb