[BACK]Return to updating.mdwn CVS log [TXT] [DIR] Up to [NetBSD Developer Wiki] / wikisrc / guide

Diff for /wikisrc/guide/updating.mdwn between versions 1.6 and 1.7

version 1.6, 2021/01/01 18:22:22 version 1.7, 2021/04/12 13:15:03
Line 1 Line 1
 **Contents**  This page was moved to:
   [The NetBSD Guide - Updating an existing system from sources](//www.NetBSD.org/docs/guide/en/chap-updating.html)
 [[!toc levels=3]]  
   
 # Updating an existing system from sources  
   
 A common mechanism for upgrading a NetBSD system to a newer version is by  
 rebuilding the system from sources and installing the results. This works both  
 for stable releases such as [NetBSD 5.0](/releases/formal-5/) and for  
 NetBSD-current. In particular, if you are running a stable NetBSD release in a  
 production environment, you are encouraged to perform this procedure regularly  
 in order to incorporate any security fixes that have been applied to the branch  
 since its release.  
   
 There are a variety of ways of achieving the goal of rebuilding NetBSD from  
 source, and this chapter will guide you through the variety of options that are  
 available. The chapter starts by showing first what the manual procedure looks  
 like, and proceeds to describe some of automation tools that simplify the  
 process.  
   
 **Note**: Please remember to check  
 [src/UPDATING](http://cvsweb.NetBSD.org/bsdweb.cgi/src/UPDATING) for the latest  
 changes and special instructions that may be involved in upgrading the system.*  
   
 ## Manual build and update procedure  
   
 Most of the following steps can be done as ordinary user. Only the installation  
 of a new kernel and the userland will require root privileges. Although `/usr`  
 is choosen as the working directory in the following examples, the procedure  
 can also take place in a user's home directory. Ordinary users have normally  
 not the permissions to make changes in `/usr`, but this can be changed by root.  
   
 Having up-to-date sources is a prerequisite for the following steps.  
 [[Fetching by CVS|guide/fetch#cvs] informs about the ways to retrieve or update  
 the sources for a release, stable or current branch (using CVS).  
   
 Please always refer to the output of **build.sh -h** and the files `UPDATING`  
 and `BUILDING` for details - it's worth it, there are *many* options that can  
 be set on the command line or in `/etc/mk.conf`  
   
 ### Building a new userland  
   
 The first step is to build the userland:  
   
     $ cd /usr/src  
     $ ./build.sh -O ../obj -T ../tools -U distribution  
   
 ### Building a new kernel  
   
 The next step will build the kernel:  
   
     $ cd /usr/src  
     $ ./build.sh -O ../obj -T ../tools -U kernel=<KERNEL>  
   
 ### Installing the kernel and userland  
   
 Installing the new kernel, rebooting (to ensure that the new kernel works) and  
 installing the new userland are the final steps of the updating procedure:  
   
     $ cd /usr/src  
     $ su  
     # mv /netbsd /netbsd.old  
     # mv /usr/obj/sys/arch/<ARCH>/compile/<KERNEL>/netbsd /  
     # shutdown -r now  
      ...  
     $ cd /usr/src  
     $ su  
     # ./build.sh -O ../obj -T ../tools -U install=/  
   
 If the new kernel `netbsd` does not boot successfully, you can fall back on  
 booting the `netbsd.old` kernel.  
   
 ### Updating the system configuration files  
   
 Run the `etcupdate` script  
 ([[!template id=man name="etcupdate" section="8"]])  
 and follow the instructions in the output for fixing obsolete files:  
   
     # /usr/sbin/etcupdate -s /usr/src  
   
 Optionally reboot to ensure all running services are using the new binaries:  
   
     # shutdown -r now  
   
 ### Summary  
   
  1. From the root of the source tree:  
   
         $ cd /usr/src  
   
  2. Build the userland:  
   
         $ ./build.sh -O ../obj -T ../tools -U -u distribution  
   
  3. Build the kernel:  
   
         $ ./build.sh -O ../obj -T ../tools -U -u kernel=GENERIC  
   
  4. Install the kernel:  
   
         $ cd ../obj/sys/arch/<ARCH>/compile/GENERIC  
         $ su  
         # mv /netbsd /netbsd.old  
         # cp netbsd /netbsd  
   
  5. Reboot into the new kernel:  
   
         # shutdown -r now  
   
  6. Install the new userland:  
   
         $ cd /usr/src  
         $ su  
         # ./build.sh -O ../obj -T ../tools -U install=/  
   
  7. Update the system and configuration files;:  
   
         #  /usr/sbin/etcupdate -s /usr/src  
   
 **Note**: In the procedure above, the `-u` option indicates an update process,  
 and that a `make clean` operation should not be run before starting the build.  
 This is useful when doing an update from a previous build and/or a fresh build.  
 The `-U` option allows the entire build by a non-root user followed with an  
 install by root.  
   
 ## Using sysinst  
   
 It is also possible to use `sysinst` to install a freshly built system. The  
 steps are as follows:  
   
  1. Build a complete release:  
   
         $ ./build.sh -O ../obj -T ../tools -U -u -x release  
   
  2. The resulting install sets will be in the `/usr/obj/releasedir/` directory.  
  3. Copy the install kernel to the root directory of your NetBSD system, reboot  
     from it, and upgrade with `sysinst` (see  
         [[Upgrading NetBSD|guide/upgrading]]).  
   
   
 ## Using sysbuild and sysupgrade  
   
 The sysbuild and sysupgrade tools (currently available in  
 `pkgsrc/sysutils/sysbuild` and `pkgsrc/sysutils/sysupgrade` respectively)  
 automate the full process of rebuilding NetBSD from sources (*including the  
 retrieval of the sources from a CVS repository*) and installing the results  
 with minimal effort.  
   
 Both of these tools have configuration files to determine how to build a  
 release and how to install it. Among other things, these specify the CVS  
 repository to use, what architecture to build for, where to place the build  
 files and what steps to perform during an upgrade. The files can be found in  
 `/usr/pkg/etc/sysbuild/default.conf` and `/usr/pkg/etc/sysupgrade.conf`. The  
 default configuration of both tools should let you get started with minimal  
 effort.  
   
 In their simplest form, you can do a full NetBSD build and upgrade your system  
 to it by running these commands:  
   
     # sysbuild build  
     # sysupgrade auto ~/sysbuild/release/$(uname -m)  
   
 And that's all that it takes. These invocations will do the following:  
   
  1. Download the source trees from CVS into `/usr/src` and `/usr/xsrc`. The  
     latter is only fetched if your system has X11. And, if you already have  
     the sources in your system, this will only update them to the newest  
         version.  
  2. Build a new release into `~/sysbuild/<machine>/`. This per-machine  
     directory will include subdirectories like `obj`, `destdir`, etc. The  
     build results will be left in `~/sysbuild/release/<machine>/`.  
  3. Install a new kernel and unpack the new sets using the just-built release  
     files.  
  4. Run both etcupdate and postinstall to aid you in merging new configuration  
     changes into your system.  
   
 For more details, please see the included `sysbuild(1)` and `sysupgrade(8)`  
 manual pages, as well as the comments in the referenced configuration files.  
   
 ### Tweak: Building as non-root  
   
 The commands above depict the most basic and simple invocation of the tools  
 using the *default configuration files*. One drawback is that you require root  
 access during the build of the source tree so that sysbuild can upgrade the  
 source trees under `/usr/src` and `/usr/xsrc`. It is recommended that you avoid  
 building as root once you are familiar with the procedure, and this section  
 show what is needed to do so with sysbuild.  
   
 In order to build as non-root, you can either choose to store your source trees  
 out of `/usr` (easiest) or give permissions to your user to modify the trees  
 under `/usr` (good if you want to share the source tree with more than one  
 user).  
   
 If you want to store the source trees under your home directory, which is  
 convenient for development purposes, simply edit `/usr/pkg/etc/sysbuild.conf`  
 and add these settings:  
   
     SRCDIR="${HOME}/sysbuild/src"  
     [ ! -f /etc/mtree/set.xbase ] || XSRCDIR="${HOME}/sysbuild/xsrc"  
   
 Once this is done, the `sysbuild build` invocation show above should just work  
 under your unprivileged user. The upgrade procedure then becomes:  
   
     $ sysbuild build  
     ... become root ...  
     # sysupgrade auto ~/sysbuild/release/$(uname -m)  
   
 The other alternative, in case you want to maintain your source trees in the  
 locations described by  
 [[!template id=man name="hier" section="7"]], is  
 to do the following as root:  
   
     # mkdir -p /usr/src /usr/xsrc  
     # chown -R <your-user>:wsrc /usr/src /usr/xsrc  
     ... and optionally add <your-user> to wsrc in /etc/group ...  
   
 After this, the default configuration file of sysbuild will let you place the  
 files in these locations and let you do unprivileged builds.  
   
 **Note**: If you have an an encrypted home partition, or another "special"  
 filesystem you store your sources on, you should backup them somehwere you can  
 easily access them! In case of a failed build you might want to rebuild without  
 being able to access an encrypted partition.  
   
 ### Tweak: Setting up nightly builds  
   
 The `pkgsrc/sysutils/sysbuild-user` package can be used to configure and  
 maintain an unprivileged system user to perform periodic (e.g. nightly) builds  
 from source. This can come in very handy to closely track NetBSD-current.  
   
 The installed user is appropriately named sysbuild, and is configured by  
 default to run a full system build overnight. The results are left in  
 `/home/sysbuild/release/<machine>/`, which is the convenient default of  
 sysupgrade's release directory. Any build failures will be reported to you by  
 email.  
   
 The behavior of sysbuild for this unprivileged user is configured in  
 `/home/sysbuild/default.conf`.  
   
 You can interact with sysbuild under this unprivileged user by running  
 commands of the form:  
   
     # su - sysbuild /usr/pkg/bin/sysbuild ...  
   
 ## More details about the updating of configuration and startup files  
   
 [[!template id=man name="etcupdate" section="8"]]  
 is a script to help users compare, merge and install new configuration and  
 startup files (files found in the `etc.tgz` distribution set) in `/dev`, `/etc`  
 and `/root` after performing an operating system upgrade. The upgrade of the  
 operating system could have been performed either by compiling sources or by  
 extracting the distribution binaries.  
   
 ### Using etcupdate with source files  
   
 In case where the sources are in `/usr/src` the following command should be enough:  
   
     # etcupdate  
   
 But what if your NetBSD sources are in an alternative location, such as in  
 `/home/jdoe/netbsd/src`? Don't worry, tell etcupdate the location of your  
 source tree with `-s srcdir` and it will work just fine:  
   
     # etcupdate -s /home/jdoe/netbsd/src  
   
 ### Using etcupdate with binary distribution sets  
   
 Sometimes it's not convenient to have the sources around but you still want to  
 update the configuration and startup files. The solution is to feed `etc.tgz`  
 (or `xetc.tgz`) to etcupdate via the `-s tgzfile` switch:  
   
     # etcupdate -s /some/where/etc.tgz  
   
 ### Using etcmanage instead of etcupdate  
   
 The `etcmanage` perl script (available from  
 [pkgsrc/sysutils/etcmanage](http://pkgsrc.se/sysutils/etcmanage) or as binary  
 package) is an alternative to etcupdate(8). It should be used in the following  
 way, in combination with  
 [[!template id=man name="postinstall" section="8"]]:  
   
     # /usr/pkg/bin/etcmanage  
     # /usr/sbin/postinstall  
   
Removed from v.1.6  
changed lines
  Added in v.1.7

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