From 2ae8c70234d7044c4ac6a61f66646cb6e8f7c57e Mon Sep 17 00:00:00 2001 From: Manolis Kiagias Date: Fri, 2 Jan 2009 12:34:14 +0000 Subject: [PATCH] The freebsd-update utility can be used on systems with custom kernels. This update explains how to: - Use freebsd-update for security updates, recompiling the custom kernel when necessary - Install a fresh copy of GENERIC in /boot/GENERIC on systems lacking it - Use GENERIC as an intermediate step when upgrading to a newer release using the upgrade option of freebsd-update Reviewed by: rene, trhodes, pgj --- .../books/handbook/cutting-edge/chapter.sgml | 149 ++++++++++++++++-- 1 file changed, 136 insertions(+), 13 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml index 9639f8e08d..3d6247808c 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -294,17 +294,51 @@ MergeChanges /etc/ /var/named/etc/ or any kernel modules were modified. This will allow &os; to load the new binaries into memory. + The freebsd-update utility can + automatically update the GENERIC kernel only. + If a custom kernel is in use, it will have to be rebuilt and + reinstalled after freebsd-update finishes + installing the rest of the updates. However, + freebsd-update will detect and update the + GENERIC kernel in /boot/GENERIC (if it exists), even if + it is not the current (running) kernel of the system. + - The freebsd-update only works with - the GENERIC kernel. If any changes have - been made to GENERIC or a custom kernel - has been installed, freebsd-update will - not complete — failing in the former case and - producing an error in the latter. + It is a good idea to always keep a copy of the + GENERIC kernel in /boot/GENERIC. It will be helpful + in diagnosing a variety of problems, and in performing version + upgrades using freebsd-update as described in + section . + + + Unless the default configuration in + /etc/freebsd-update.conf has been changed, + freebsd-update will install the updated kernel + sources along with the rest of the updates. Rebuilding and + reinstalling your new custom kernel can then be performed in the usual + way. + + + The updates distributed via freebsd-update, + do not always involve the kernel. It will not be necessary to + rebuild your custom kernel if the kernel sources have not been + modified by the execution of + freebsd-update install. However, + freebsd-update will always update the + /usr/src/sys/conf/newvers.sh file. The current + patch level (as indicated by the -p number + reported by uname -r) is + obtained from this file. Rebuilding your custom kernel, even if + nothing else changed, will allow &man.uname.1; to accurately report + the current patch level of the system. This is particularly + helpful when maintaining multiple systems, as it allows for a quick + assessment of the updates installed in each one. - + Major and Minor Upgrades This process will remove old object files and @@ -324,12 +358,66 @@ MergeChanges /etc/ /var/named/etc/ any prompts during this process, removing the need for manual intervention during the build process. + If a custom kernel is in use, the upgrade process is slightly + more involved. A copy of the GENERIC kernel is + needed, and it should be placed in /boot/GENERIC. If the + GENERIC kernel is not already present in the + system, it may be obtained using one of the following methods: + + + + If a custom kernel has only been built once, the kernel in + /boot/kernel.old is + actually the GENERIC one. Simply rename this + directory to + /boot/GENERIC. + + + + Assuming physical access to the machine is possible, a copy + of the GENERIC kernel can be installed from + the CD-ROM media. Insert your installation disc and use the + following commands: + + &prompt.root; mount /cdrom +&prompt.root; cd /cdrom/X.Y-RELEASE/kernels +&prompt.root; ./install.sh GENERIC + + Replace X.Y-RELEASE + with the actual version of the release you are using. The + GENERIC kernel will be installed in /boot/GENERIC by default. + + + + Failing all the above, the GENERIC kernel + may be rebuilt and installed from the sources: + + &prompt.root; cd /usr/src +&prompt.root; env DESTDIR=/boot/GENERIC make kernel +&prompt.root; mv /boot/GENERIC/boot/kernel/* /boot/GENERIC +&prompt.root; rm -rf /boot/GENERIC/boot + + For this kernel to be picked up as GENERIC + by freebsd-update, the + GENERIC configuration file must not have been + modified in any way. It is also suggested that it is built + without any other special options (preferably with an empty + /etc/make.conf). + + + + Rebooting to the GENERIC kernel is not + required at this stage. + Major and minor version updates may be performed by providing freebsd-update with a release version target, for example, the following command will - update to &os; 6.3: + update to &os; 6.4: - &prompt.root; freebsd-update -r 6.3-RELEASE upgrade + &prompt.root; freebsd-update -r 6.4-RELEASE upgrade After the command has been received, freebsd-update will evaluate the @@ -339,7 +427,7 @@ MergeChanges /etc/ /var/named/etc/ what components have not been detected. For example: Looking up update.FreeBSD.org mirrors... 1 mirrors found. -Fetching metadata signature for 6.3-BETA1 from update1.FreeBSD.org... done. +Fetching metadata signature for 6.3-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. @@ -360,6 +448,18 @@ Does this look reasonable (y/n)? y some cases, the user may be prompted with questions regarding what to install or how to proceed. + When using a custom kernel, the above step will produce a warning + similar to the following: + + WARNING: This system is running a "MYKERNEL" kernel, which is not a +kernel configuration distributed as part of FreeBSD 6.3-RELEASE. +This kernel will not be updated: you MUST update the kernel manually +before running "/usr/sbin/freebsd-update install" + + This warning may be safely ignored at this point. The updated + GENERIC kernel will be used as an intermediate + step in the upgrade process. + After all patches have been downloaded to the local system, they will then be applied. This process may take a while depending on the speed and workload of the machine. @@ -388,9 +488,28 @@ Does this look reasonable (y/n)? y &prompt.root; freebsd-update install The kernel and kernel modules will be patched first. At - this point the machine must be rebooted. The following - command may be issued to restart the machine so the new - kernel will be loaded into memory: + this point the machine must be rebooted. If the system was running + with a custom kernel, use the &man.nextboot.8; command to set the + kernel for the next boot to /boot/GENERIC (which was + updated): + + &prompt.root; nextboot -k GENERIC + + + Before rebooting with the GENERIC kernel, + make sure it contains all drivers required for your system to boot + properly (and connect to the network, if the machine that is being + updated is accessed remotely). In particular, if the previously + running custom kernel contained built-in functionality usually + provided by kernel modules, make sure to temporarily load these + modules into the GENERIC kernel using the + /boot/loader.conf facility. You may also wish + to disable non-essential services, disk and network mounts, etc. + until the upgrade process is complete. + + + The machine should now be restarted with the updated kernel: &prompt.root; shutdown -r now @@ -431,6 +550,10 @@ Does this look reasonable (y/n)? y &prompt.root; freebsd-update install + If the GENERIC kernel was temporarily used, + this is the time to build and install a new custom kernel in the + usual way. + Reboot the machine into the new &os; version. The process is complete.