File:  [NetBSD Developer Wiki] / wikisrc / guide / Attic / updating.txt
Revision 1.1: download - view: text, annotated - select for diffs
Fri Mar 1 11:45:37 2013 UTC (7 years, 7 months ago) by jdf
Branches: MAIN
CVS tags: HEAD
Move the updating chapter from the guide to the wiki.

    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