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