diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml index e602a93937..4dca4cd45b 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml @@ -293,10 +293,10 @@ MergeChanges /etc/ /var/named/etc/ /boot/device.hints &prompt.root; freebsd-update install If the update applies any kernel patches, the system will - need a reboot in order to boot into the patched kernel. - If the patch was applied to any running binaries, the affected + need a reboot in order to boot into the patched kernel. If + the patch was applied to any running binaries, the affected applications should be restarted so that the patched version - of the binary is used. + of the binary is used. The system can be configured to automatically check for updates once every day by adding this entry to @@ -304,23 +304,23 @@ MergeChanges /etc/ /var/named/etc/ /boot/device.hints @daily root freebsd-update cron - If patches exist, they will automatically be - downloaded but will not be applied. The - root user will be - sent an email so that the patches may be reviewed and manually + If patches exist, they will automatically be downloaded + but will not be applied. The root user will be sent an + email so that the patches may be reviewed and manually installed with freebsd-update install. If anything goes wrong, freebsd-update - has the ability to roll back the last set of changes with - the following command: + has the ability to roll back the last set of changes with the + following command: &prompt.root; freebsd-update rollback Uninstalling updates... done. - Again, the system should be restarted if the - kernel or any kernel modules were modified and any affected - binaries should be restarted. + Again, the system should be restarted if the kernel or any + kernel modules were modified and any affected binaries should + be restarted. Only the GENERIC kernel can be automatically updated by freebsd-update. @@ -329,15 +329,13 @@ Uninstalling updates... done. finishes installing the updates. However, freebsd-update will detect and update the GENERIC kernel if - /boot/GENERIC exists, - even if it is not the current running kernel of the - system. + /boot/GENERIC exists, even if it is not + the current running kernel of the system. - Always keep a copy of the - GENERIC kernel in - /boot/GENERIC. It - will be helpful in diagnosing a variety of problems and in + 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. Refer to either or for @@ -352,21 +350,21 @@ Uninstalling updates... done. Rebuilding and reinstalling a new custom kernel can then be performed in the usual way. - The updates distributed by - freebsd-update do not always involve the - kernel. It is not necessary to rebuild a custom kernel if - the kernel sources have not been modified by - freebsd-update install. - However, freebsd-update will always - update /usr/src/sys/conf/newvers.sh. - The current patch level, as indicated by the - -p number reported by - uname -r, is obtained from this file. - Rebuilding a custom kernel, even if nothing else changed, - allows uname 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. + The updates distributed by + freebsd-update do not always involve the + kernel. It is not necessary to rebuild a custom kernel if the + kernel sources have not been modified by + freebsd-update install. However, + freebsd-update will always update + /usr/src/sys/conf/newvers.sh. The + current patch level, as indicated by the -p + number reported by uname -r, is obtained + from this file. Rebuilding a custom kernel, even if nothing + else changed, allows uname 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. @@ -375,8 +373,8 @@ Uninstalling updates... done. Upgrades from one minor version of &os; to another, like from &os; 9.0 to &os; 9.1, are called minor version upgrades. - Major version upgrades occur when - &os; is upgraded from one major version to another, like from + Major version upgrades occur when &os; + is upgraded from one major version to another, like from &os; 9.X to &os; 10.X. Both types of upgrades can be performed by providing freebsd-update with a release version target. @@ -392,20 +390,19 @@ Uninstalling updates... done. GENERIC kernel. - The following command, when - run on a &os; 9.0 system, will upgrade it to - &os; 9.1: + The following command, when run on a &os; 9.0 system, + will upgrade it to &os; 9.1: - &prompt.root; freebsd-update -r 9.1-RELEASE upgrade + &prompt.root; freebsd-update -r 9.1-RELEASE upgrade - After the command has been received, - freebsd-update will evaluate the - configuration file and current system in an attempt to - gather the information necessary to perform the upgrade. A - screen listing will display which components have and have - not been detected. For example: + After the command has been received, + freebsd-update will evaluate the + configuration file and current system in an attempt to gather + the information necessary to perform the upgrade. A screen + listing will display which components have and have not been + detected. For example: - Looking up update.FreeBSD.org mirrors... 1 mirrors found. + Looking up update.FreeBSD.org mirrors... 1 mirrors found. Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. @@ -422,210 +419,201 @@ world/proflibs Does this look reasonable (y/n)? y - At this point, freebsd-update will - attempt to download all files required for the upgrade. In - some cases, the user may be prompted with questions - regarding what to install or how to proceed. + At this point, freebsd-update will + attempt to download all files required for the upgrade. In + 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: + 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 + WARNING: This system is running a "MYKERNEL" kernel, which is not a kernel configuration distributed as part of FreeBSD 9.0-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. + This warning may be safely ignored at this point. The + updated GENERIC kernel will be used as an + intermediate step in the upgrade process. - Once all the patches have been downloaded to the local - system, they will be applied. This process may take a - while, depending on the speed and workload of the machine. - Configuration files will then be merged. The merging - process requires some user intervention as a file may be - merged or an editor may appear on screen for a manual merge. - The results of every successful merge will be shown to the - user as the process continues. A failed or ignored merge - will cause the process to abort. Users may wish to make a - backup of /etc and - manually merge important files, such as - master.passwd or - group at a later time. + Once all the patches have been downloaded to the local + system, they will be applied. This process may take a while, + depending on the speed and workload of the machine. + Configuration files will then be merged. The merging process + requires some user intervention as a file may be merged or an + editor may appear on screen for a manual merge. The results + of every successful merge will be shown to the user as the + process continues. A failed or ignored merge will cause the + process to abort. Users may wish to make a backup of + /etc and manually merge important files, + such as master.passwd or + group at a later time. - - The system is not being altered yet as all patching - and merging is happening in another directory. Once all - patches have been applied successfully, all configuration - files have been merged and it seems the process will go - smoothly, the changes can be committed to disk by the - user using the following command: + + The system is not being altered yet as all patching and + merging is happening in another directory. Once all patches + have been applied successfully, all configuration files have + been merged and it seems the process will go smoothly, the + changes can be committed to disk by the user using the + following command: &prompt.root; freebsd-update install + - + The kernel and kernel modules will be patched first. If + the system is running with a custom kernel, use + &man.nextboot.8; to set the kernel for the next boot to the + updated /boot/GENERIC: - The kernel and kernel modules will be patched first. If - the system is - running with a custom kernel, use &man.nextboot.8; to set - the kernel for the next boot to the updated - /boot/GENERIC: + &prompt.root; nextboot -k GENERIC - &prompt.root; nextboot -k GENERIC + + Before rebooting with the GENERIC + kernel, make sure it contains all the drivers required for + the system to boot properly and connect to the network, if + the machine being updated is accessed remotely. In + particular, if the running custom kernel contains 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. It is + recommended to disable non-essential services as well as any + disk and network mounts until the upgrade process is + complete. + - - Before rebooting with the GENERIC - kernel, make sure it contains all the drivers required for - the system to boot properly and connect to the network, - if the machine being updated is accessed remotely. In - particular, if the running custom kernel contains 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. - It is recommended to disable non-essential services as - well as any disk and network mounts until the upgrade - process is complete. - + The machine should now be restarted with the updated + kernel: - The machine should now be restarted with the updated - kernel: + &prompt.root; shutdown -r now - &prompt.root; shutdown -r now + Once the system has come back online, restart + freebsd-update using the following command. + Since the state of the process has been saved, + freebsd-update will not start from the + beginning, but will instead move on to the next phase and + remove all old shared libraries and object files. - Once the system has come back online, restart - freebsd-update using the following - command. Since the state of the process has been saved, - freebsd-update will not start from the - beginning, but will instead move on to the next phase and - remove all old shared libraries and - object files. + &prompt.root; freebsd-update install - &prompt.root; freebsd-update install + + Depending upon whether any library version numbers were + bumped, there may only be two install phases instead of + three. + - - Depending upon whether any library version numbers - were bumped, there may only be two install phases instead - of three. - + The upgrade is now complete. If this was a major version + upgrade, reinstall all ports and packages as described in + . - The upgrade is now complete. If this was a major - version upgrade, reinstall all ports and packages as - described in . + + Custom Kernels with &os; 9.X and Later - - Custom Kernels with &os; 9.X and Later + Before using freebsd-update, ensure + that a copy of the GENERIC kernel + exists in /boot/GENERIC. If a custom + kernel has only been built once, the kernel in + /boot/kernel.old is the + GENERIC kernel. Simply rename this + directory to /boot/kernel. - Before using freebsd-update, ensure - that a copy of the GENERIC kernel - exists in /boot/GENERIC. If a custom - kernel has only been built once, the - kernel in /boot/kernel.old is - the GENERIC kernel. - Simply rename this directory to - /boot/kernel. + If a custom kernel has been built more than once or if + it is unknown how many times the custom kernel has been + built, obtain a copy of the GENERIC + kernel that matches the current version of the operating + system. If physical access to the system is available, a + copy of the GENERIC kernel can be + installed from the installation media: - If a custom kernel has been built more than once - or if it is unknown how many times the custom kernel - has been built, obtain a copy of the - GENERIC kernel that matches the - current version of the operating system. If physical - access to the system is available, a - copy of the GENERIC kernel can be - installed from the installation media: - - &prompt.root; mount /cdrom + &prompt.root; mount /cdrom &prompt.root; cd /cdrom/usr/freebsd-dist &prompt.root; tar -C/ -xvf kernel.txz boot/kernel/kernel - Alternately, the - GENERIC kernel may be rebuilt and - installed from source: + Alternately, the GENERIC kernel may + be rebuilt and installed from source: - &prompt.root; cd /usr/src + &prompt.root; cd /usr/src &prompt.root; make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null - For this kernel to be identified as the - GENERIC kernel by - freebsd-update, the - GENERIC configuration file must - not have been modified in any way. It is also - suggested that the kernel is built without any other - special options. + For this kernel to be identified as the + GENERIC kernel by + freebsd-update, the + GENERIC configuration file must not + have been modified in any way. It is also suggested that + the kernel is built without any other special + options. - Rebooting into the GENERIC kernel - is not required as freebsd-update only - needs /boot/GENERIC to exist. + Rebooting into the GENERIC kernel + is not required as freebsd-update only + needs /boot/GENERIC to exist. - - Custom Kernels with &os; 8.X + + Custom Kernels with &os; 8.X - On an &os; 8.X system, the instructions for - obtaining or building a - GENERIC kernel differ slightly. + On an &os; 8.X system, the instructions for + obtaining or building a GENERIC kernel + differ slightly. - Assuming physical access to the machine is - possible, a copy of the GENERIC - kernel can be installed from the installation media - using the following commands: + Assuming physical access to the machine is possible, a + copy of the GENERIC kernel can be + installed from the installation media using the following + commands: - &prompt.root; mount /cdrom + &prompt.root; mount /cdrom &prompt.root; cd /cdrom/X.Y-RELEASE/kernels &prompt.root; ./install.sh GENERIC - Replace X.Y-RELEASE - with the version of the release being used. - The GENERIC kernel will be - installed in /boot/GENERIC by - default. + Replace X.Y-RELEASE + with the version of the release being used. The + GENERIC kernel will be installed in + /boot/GENERIC by default. - To instead build the - GENERIC kernel from source: + To instead build the GENERIC kernel + from source: - &prompt.root; cd /usr/src + &prompt.root; cd /usr/src &prompt.root; env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null &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. + 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. - Rebooting into the GENERIC kernel - is not required. - + Rebooting into the GENERIC kernel + is not required. + Rebuilding Ports After a Major Version Upgrade - Generally, - installed applications will continue to work without problems - after minor version upgrades. Major versions use different - Application Binary Interfaces (ABIs), which - which will break most third-party - applications. After a - major version upgrade, all installed packages and - ports need to be upgraded using a utility such as - ports-mgmt/portmaster. A - rebuild of all installed applications can be - accomplished with this command: + Generally, installed applications will continue to work + without problems after minor version upgrades. Major + versions use different Application Binary Interfaces + (ABIs), which which will break most + third-party applications. After a major version upgrade, + all installed packages and ports need to be upgraded using a + utility such as ports-mgmt/portmaster. A + rebuild of all installed applications can be accomplished + with this command: - &prompt.root; portmaster -af + &prompt.root; portmaster -af - This command will display the configuration screens for - each application that has configurable options and wait for the user to interact with those - screens. To prevent this behavior, and use only the default - options, include in the above command. + This command will display the configuration screens for + each application that has configurable options and wait for + the user to interact with those screens. To prevent this + behavior, and use only the default options, include + in the above command. - Once the software upgrades are complete, finish the upgrade process with - a final call to freebsd-update in order - to tie up all the loose ends in the upgrade process: + Once the software upgrades are complete, finish the + upgrade process with a final call to + freebsd-update in order to tie up all the + loose ends in the upgrade process: &prompt.root; freebsd-update install @@ -634,8 +622,8 @@ before running "/usr/sbin/freebsd-update install" new custom kernel using the instructions in . - Reboot the machine into the new &os; version. The upgrade - process is now complete. + Reboot the machine into the new &os; version. The + upgrade process is now complete. @@ -643,15 +631,16 @@ before running "/usr/sbin/freebsd-update install" System State Comparison The state of the installed &os; version against a known - good copy can be tested using freebsd-update IDS. - This command evaluates the current version of system utilities, - libraries, and configuration files and can be used as a - built-in Intrusion Detection System (IDS). + good copy can be tested using + freebsd-update IDS. This command evaluates + the current version of system utilities, libraries, and + configuration files and can be used as a built-in Intrusion + Detection System (IDS). - This command is - not a replacement for a real IDS such - as security/snort. As + This command is not a replacement for a real + IDS such as + security/snort. As freebsd-update stores data on disk, the possibility of tampering is evident. While this possibility may be reduced using kern.securelevel and @@ -665,15 +654,16 @@ before running "/usr/sbin/freebsd-update install" linkend="security-ids"/> - To begin the comparison, - specify the output file to save the results to: + To begin the comparison, specify the output file to save + the results to: &prompt.root; freebsd-update IDS >> outfile.ids The system will now be inspected and a lengthy listing of - files, along with the SHA256 hash values for both the - known value in the release and the current installation, will - be sent to the specified output file. + files, along with the SHA256 hash values + for both the known value in the release and the current + installation, will be sent to the specified output + file. The entries in the listing are extremely long, but the output format may be easily parsed. For instance, to obtain a @@ -688,11 +678,10 @@ before running "/usr/sbin/freebsd-update install" This sample output has been truncated as many more files exist. Some files have natural modifications. For example, - /etc/passwd will be modified if - users have been added to the system. - Kernel modules may differ as - freebsd-update may have updated them. - To exclude specific files or directories, add them to the + /etc/passwd will be modified if users + have been added to the system. Kernel modules may differ as + freebsd-update may have updated them. To + exclude specific files or directories, add them to the IDSIgnorePaths option in /etc/freebsd-update.conf. @@ -1081,8 +1070,9 @@ before running "/usr/sbin/freebsd-update install" sites listed in . Users with very slow or limited Internet connectivity - can instead use CTM as described in , but it is - not as reliable as svn and + can instead use CTM as described in , + but it is not as reliable as + svn and svn is the recommended method for synchronizing source. @@ -1182,8 +1172,8 @@ before running "/usr/sbin/freebsd-update install" recent &os.stable; release from the &os; mirror sites or use a monthly snapshot built from &os.stable;. Refer to www.freebsd.org/snapshots for - more information about snapshots. + xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots + for more information about snapshots. To compile or upgrade to an existing &os; system to &os.stable;, use svn @@ -1194,8 +1184,7 @@ before running "/usr/sbin/freebsd-update install" stable/9, are listed at www.freebsd.org/releng. CTM () can be used if a reliable - Internet connection is not - available. + Internet connection is not available. @@ -1205,11 +1194,10 @@ before running "/usr/sbin/freebsd-update install" compiling , read /usr/src/Makefile carefully and follow the instructions in . Read - &a.stable; and /usr/src/UPDATING to - keep up-to-date on other bootstrapping procedures that - sometimes become necessary on the road to the next - release. + linkend="makeworld"/>. Read &a.stable; and + /usr/src/UPDATING to keep up-to-date + on other bootstrapping procedures that sometimes become + necessary on the road to the next release. @@ -1218,8 +1206,7 @@ before running "/usr/sbin/freebsd-update install" Synchronizing Source - There are various methods for - staying up-to-date with the + There are various methods for staying up-to-date with the &os; sources. This section compares the primary services, Subversion and CTM. @@ -1242,13 +1229,13 @@ before running "/usr/sbin/freebsd-update install" Subversion uses the pull model of updating sources. The user, or a cron script, invokes the - svn program which updates the local version of the source. - Subversion is the preferred method for - updating local source trees as updates are up-to-the-minute - and the user controls when updates are downloaded. It is easy to - restrict updates to specific files or directories and the - requested updates are generated on the fly by the server. How - to synchronize source using + svn program which updates the local version + of the source. Subversion is the + preferred method for updating local source trees as updates are + up-to-the-minute and the user controls when updates are + downloaded. It is easy to restrict updates to specific files or + directories and the requested updates are generated on the fly + by the server. How to synchronize source using Subversion is described in . @@ -1261,25 +1248,24 @@ before running "/usr/sbin/freebsd-update install" changes in files since its previous run is executed several times a day on the master CTM machine. Any detected changes are compressed, stamped with a sequence-number, and encoded for - transmission over email in printable ASCII only. Once downloaded, - these deltas can be run through - ctm.rmail which will automatically decode, - verify, and apply the changes to the user's copy of the sources. - This process is more efficient than + transmission over email in printable ASCII + only. Once downloaded, these deltas can + be run through ctm.rmail which will + automatically decode, verify, and apply the changes to the + user's copy of the sources. This process is more efficient than Subversion and places less strain on server resources since it is a push, rather than a pull, model. Instructions for using CTM to synchronize source can be found at . - If a user inadvertently wipes - out portions of the local archive, - Subversion will detect and rebuild - the damaged portions. CTM will not, - and if a user deletes some portion of the source tree + If a user inadvertently wipes out portions of the local + archive, Subversion will detect and + rebuild the damaged portions. CTM + will not, and if a user deletes some portion of the source tree and does not have a backup, they will have to start from scratch - from the most recent base delta and rebuild - it all with CTM. + from the most recent base delta and + rebuild it all with CTM. @@ -1456,12 +1442,13 @@ Script started, output file is /var/tmp/mw.out possible to boot with the newly updated kernel. If kern.securelevel has been raised above 1 and - noschg or similar flags have been set on the kernel - binary, drop the system into single-user mode first. - Otherwise, this command can be run from multi-user mode - without problems. See &man.init.8; for details about - kern.securelevel and &man.chflags.1; - for details about the various file flags. + noschg or similar flags have been set + on the kernel binary, drop the system into single-user + mode first. Otherwise, this command can be run from + multi-user mode without problems. See &man.init.8; for + details about kern.securelevel and + &man.chflags.1; for details about the various file + flags. &prompt.root; make installkernel