From 71682c57b33707ffeea106d3a4115152accf1b75 Mon Sep 17 00:00:00 2001 From: Tom Rhodes Date: Tue, 23 Dec 2008 18:48:22 +0000 Subject: [PATCH] Merge the Updating chapter into the Cutting Edge chapter, and rename the new chapter "Updating and Upgrading FreeBSD." Update other chapters to reference the new chapter name. While here, add Audit chapter to the preface section. Reviewed by: murray, manolis, remko, pgj, -doc --- .../books/handbook/cutting-edge/chapter.sgml | 505 +++++++++++++++++- .../books/handbook/dtrace/chapter.sgml | 2 +- .../books/handbook/kernelconfig/chapter.sgml | 4 +- .../books/handbook/preface/preface.sgml | 15 +- .../books/handbook/serialcomms/chapter.sgml | 2 +- 5 files changed, 506 insertions(+), 22 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 67e1ac9220..6c1c26f2c2 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -4,7 +4,7 @@ $FreeBSD$ --> - + @@ -40,34 +40,49 @@ - The Cutting Edge + Updating and Upgrading &os; - + Synopsis - &os; is under constant development between releases. For - people who want to be on the cutting edge, there are several easy - mechanisms for keeping your system in sync with the latest - developments. Be warned—the cutting edge is not for everyone! + &os; is under constant development between releases. Some people + prefer to use the officially released versions, while others prefer + to keep in sync with the latest developments. However, even official + releases are often updated with security and other critical fixes. + Regardless of the version used, &os; provides all necessary tools + to keep your system updated, and also allows for easy upgrades between + versions. This chapter will help you decide if you want to track the development system, or stick with one of the released - versions. + versions. The basic tools for keeping your system up to date are + also presented. After reading this chapter, you will know: - The difference between the two development - branches: &os.stable; and &os.current;. + What utilities may be used to update the system and + the Ports Collection. How to keep your system up to date with + freebsd-update, CVSup, CVS, or CTM. + + How to compare the state of an installed system against + a known pristine copy. + + + + The difference between the two development + branches: &os.stable; and &os.current;. + + How to rebuild and reinstall the entire base system with make buildworld (etc). @@ -98,8 +113,470 @@ + + + + + Tom + Rhodes + Written by + + + + + Colin + Percival + Based on notes provided by + + + + FreeBSD Update + + Updating and Upgrading + + freebsd-update + updating-upgrading + + + Applying security patches is an important part of maintaining + computer software, especially the operating system. For the + longest time on &os; this process was not an easy one. Patches + had to be applied to the source code, the code rebuilt into + binaries, and then the binaries had to be re-installed. + + This is no longer the case as &os; now includes a utility + simply called freebsd-update. This utility + provides two separate functions. First, it allows for binary + security and errata updates to be applied to the &os; base system + without the build and install requirements. Second, the utility + supports minor and major release upgrades. + + + Binary updates are available for all architectures and + releases currently supported by the security team; however, + some features, such as the &os; operating system upgrades, + require the latest release of &man.freebsd-update.8; and + &os; 6.3 or greater. Before updating to a new release, the current + release announcements should be reviewed as they may contain + important information pertinent to the desired release. These + announcements may be viewed at the following link: + . + + + If a crontab utilizing the features + of freebsd-update exists, it must be + disabled before the following operation is started. + + + The Configuration File + + Some users may wish to tweak the configuration file, + allowing better control of the process. The options are + very well documented, but the following few may require a + bit more explanation: + + # Components of the base system which should be kept updated. +Components src world kernel + + This parameter controls what parts of &os; will be kept + up to date. The default is to update the source code, the + entire base system, and the kernel. Components are the + same as those available during the install, for instance, + adding "world/games" here would allow game patches to be + applied. Using "src/bin" would allow the source code in + src/bin to be + updated. + + The best option is to leave this at the default as + changing it to include specific items will require the user + to list every item they prefer to be updated. This could + have disastrous consequences as source code and binaries may + become out of sync. + + # Paths which start with anything matching an entry in an IgnorePaths +# statement will be ignored. +IgnorePaths + + Add paths, such as + /bin or + /sbin to leave these + specific directories untouched during the update + process. This option may be used to prevent + freebsd-update from overwriting local + modifications. + + # Paths which start with anything matching an entry in an UpdateIfUnmodified +# statement will only be updated if the contents of the file have not been +# modified by the user (unless changes are merged; see below). +UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile + + Update configuration files in the specified directories + only if they have not been modified. Any changes made by the + user will invalidate the automatic updating of these files. + There is another option, + KeepModifiedMetadata, which will instruct + freebsd-update to save the changes during + the merge. + + # When upgrading to a new &os; release, files which match MergeChanges +# will have any local changes merged into the version from the new release. +MergeChanges /etc/ /var/named/etc/ + + List of directories with configuration files that + freebsd-update should attempt merges in. + The file merge process is a series of &man.diff.1; patches + similar to &man.mergemaster.8; with fewer options, the merges + are either accepted, open an editor, or + freebsd-update will abort. When in doubt, + backup /etc and just + accept the merges. See for more + information about the mergemaster + command. + + # Directory in which to store downloaded updates and temporary +# files used by &os; Update. +# WorkDir /var/db/freebsd-update + + This directory is where all patches and temporary + files will be placed. In cases where the user is doing + a version upgrade, this location should have a least a + gigabyte of disk space available. + + # When upgrading between releases, should the list of Components be +# read strictly (StrictComponents yes) or merely as a list of components +# which *might* be installed of which &os; Update should figure out +# which actually are installed and upgrade those (StrictComponents no)? +# StrictComponents no + + When set to yes, + freebsd-update will assume that the + Components list is complete and will not + attempt to make changes outside of the list. Effectively, + freebsd-update will attempt to update + every file which belongs to the Components + list. + + + + Security Patches + + Security patches are stored on a remote machine and + may be downloaded and installed using the following + command: + + &prompt.root; freebsd-update fetch +&prompt.root; freebsd-update install + + If any kernel patches have been applied the system will + need a reboot. If all went well the system should be patched + and freebsd-update may be ran as a nightly + &man.cron.8; job. An entry in /etc/crontab + would be sufficient to accomplish this task: + + @daily root freebsd-update cron + + This entry states that once every day, the + freebsd-update will be ran. In this way, + using the argument, + freebsd-update will only check if updates + exist. If patches exist, they will automatically be downloaded + to the local disk but not applied. The + root user will be sent an email so they + may install them manually. + + If anything went wrong, freebsd-update + has the ability to roll back the last set of changes with + the following command: + + &prompt.root; freebsd-update rollback + + Once complete, the system should be restarted if the kernel + or any kernel modules were modified. This will allow &os; to + load the new binaries into memory. + + + 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. + + + + + Major and Minor Upgrades + + This process will remove old object files and + libraries which will break most third party applications. + It is recommended that all installed ports either be removed + and re-installed or upgraded later using the + ports-mgmt/portupgrade + utility. Most users will want to run a test build using + the following command: + + &prompt.root; portupgrade -af + + This will ensure everything will be re-installed + correctly. Note that setting the + BATCH environment variable to + yes will answer yes to + any prompts during this process, removing the need for + manual intervention during the build process. + + 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: + + &prompt.root; freebsd-update -r 6.3-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 update the system. A screen + listing will display what components have been detected and + 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 index... done. +Inspecting system... done. + +The following components of FreeBSD seem to be installed: +kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games +src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue +src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin +world/base world/info world/lib32 world/manpages + +The following components of FreeBSD do not seem to be installed: +kernel/generic world/catpages world/dict world/doc world/games +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. + + 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. + Configuration files will then be merged — this part + of the 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, all patching and + merging is happening in another directory. When all + patches have been applied successfully, all configuration + files have been merged and it seems the process will go + smoothly, the changes will need to be committed by the + user. + + + Once this process is complete, the upgrade may be committed + to disk using the following command. + + &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: + + &prompt.root; shutdown -r now + + Once the system has come back online, + freebsd-update will need to be started + again. The state of the process has been saved and thus, + freebsd-update will not start from the + beginning, but will remove all old shared libraries and object + files. To continue to this stage, issue the following + command: + + &prompt.root; freebsd-update install + + + Depending on whether any libraries version numbers got + bumped, there may only be two install phases instead of + three. + + + All third party software will now need to be rebuilt and + re-installed. This is required as installed software may + depend on libraries which have been removed during the upgrade + process. The + ports-mgmt/portupgrade + command may be used to automate this process. The following + commands may be used to begin this process: + + &prompt.root; portupgrade -f ruby +&prompt.root; rm /var/db/pkg/pkgdb.db +&prompt.root; portupgrade -f ruby18-bdb +&prompt.root; rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db +&prompt.root; portupgrade -af + + Once this has completed, finish the upgrade process with a + final call to freebsd-update. Issue the + following command to tie up all loose ends in the upgrade + process: + + &prompt.root; freebsd-update install + + Reboot the machine into the new &os; version. The process + is complete. + + + + System State Comparison + + The freebsd-update utility may be used + to test the state of the installed &os; version against a + known good copy. This option evaluates the current version + of system utilities, libraries, and configuration files. + To begin the comparison, issue the following command: + + &prompt.root; freebsd-update IDS >> outfile.ids + + + While the command name is IDS it should + in no way be a replacement for an intrusion detection system + such as security/snort. + As freebsd-update stores data on disk, the + possibility of tampering is evident. While this possibility + may be reduced by using the + kern.securelevel setting and storing the + freebsd-update data on a read only file + system when not in use, a better solution would be to + compare the system against a secure disk, such as a + DVD or securely stored external + USB disk device. + + + The system will now be inspected, and a list of files + along with their &man.sha256.1; hash values, both the known value + in the release and the current installed value, will be printed. This is why + the output has been sent to the + outfile.ids file. It scrolls by too + quickly for eye comparisons, and soon it fills up the console + buffer. + + These lines are also extremely long, but the output format + may be parsed quite easily. For instance, to obtain a list of + all files different from those in the release, issue the + following command: + + &prompt.root; cat outfile.ids | awk '{ print $1 }' | more +/etc/master.passwd +/etc/motd +/etc/passwd +/etc/pf.conf + + This output has been truncated, many more files exist. + Some of these files have natural modifications, the + /etc/passwd has been modified because + users have been added to the system. In some cases, there + may be other files, such as kernel modules, which 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. + + This system may be used as part of an elaborate upgrade + method, aside from the previously discussed version. + + + + + + + + Tom + Rhodes + Written by + + + + + Colin + Percival + Based on notes provided by + + + + Portsnap: A Ports Collection Update Tool + + Updating and Upgrading + + Portsnap + Updating and Upgrading + + + The base system of &os; includes a utility for updating + the Ports Collection too: the &man.portsnap.8; utility. Upon + execution, it will connect to a remote site, verify the secure + key, and download a new copy of the Ports Collection. The key + is used to verify the integrity of all downloaded files, ensuring + they have not been modified in-flight. To download the latest + Ports Collection files, issue the following command: + + &prompt.root; portsnap fetch +Looking up portsnap.FreeBSD.org mirrors... 3 mirrors found. +Fetching snapshot tag from portsnap1.FreeBSD.org... done. +Fetching snapshot metadata... done. +Updating from Wed Aug 6 18:00:22 EDT 2008 to Sat Aug 30 20:24:11 EDT 2008. +Fetching 3 metadata patches.. done. +Applying metadata patches... done. +Fetching 3 metadata files... done. +Fetching 90 patches.....10....20....30....40....50....60....70....80....90. done. +Applying patches... done. +Fetching 133 new ports or files... done. + + What this example shows is that &man.portsnap.8; + has found and verified + several patches to the current ports data. This also indicates + that the utility was run previously, if it was a first time + run, the collection would have simply been downloaded. + + When &man.portsnap.8; successfully completes + a fetch operation, the Ports Collection and + subsequent patches exist on the local system that have passed + verification. The updated files may be installed by + typing: + + &prompt.root; portsnap extract +/usr/ports/.cvsignore +/usr/ports/CHANGES +/usr/ports/COPYRIGHT +/usr/ports/GIDs +/usr/ports/KNOBS +/usr/ports/LEGAL +/usr/ports/MOVED +/usr/ports/Makefile +/usr/ports/Mk/bsd.apache.mk +/usr/ports/Mk/bsd.autotools.mk +/usr/ports/Mk/bsd.cmake.mk +... + + The process is now complete, and applications may be + installed or upgraded using the updated Ports Collection. + + To run both processes consecutively, issue the following + command: + + &prompt.root; portsnap fetch update + + - &os.current; vs. &os.stable; + Tracking a Development Branch -CURRENT -STABLE @@ -862,7 +1339,7 @@ &prompt.root; rm -rf * - + Recompile the Base System @@ -1219,7 +1696,7 @@ Script done, … If you are using &man.mergemaster.8; (as recommended), you can skip forward to the next section. + linkend="updating-upgrading-rebooting">next section. The simplest way to do this by hand is to install the files into a new directory, and then work through them looking @@ -1367,7 +1844,7 @@ Script done, … - + Rebooting You are now done. After you have verified that everything appears diff --git a/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml b/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml index 43220d3e52..8de18f0f0c 100644 --- a/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml @@ -84,7 +84,7 @@ that might make this chapter too large. Understand how to obtain and rebuild the &os; sources - (). + (). diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml index 2ae7f7e260..1facdd81a5 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml @@ -336,7 +336,7 @@ following line in &man.loader.conf.5: you to realize that you have deleted your custom kernel configuration file. Also, do not edit GENERIC directly, as it may get overwritten the next time you - update your source tree, and + update your source tree, and your kernel modifications will be lost. You might want to keep your kernel configuration file @@ -374,7 +374,7 @@ following line in &man.loader.conf.5: If you sync your source tree with the + linkend="updating-upgrading">sync your source tree with the latest sources of the &os; project, be sure to always check the file /usr/src/UPDATING before you perform any update diff --git a/en_US.ISO8859-1/books/handbook/preface/preface.sgml b/en_US.ISO8859-1/books/handbook/preface/preface.sgml index 237bde32ae..301081542d 100644 --- a/en_US.ISO8859-1/books/handbook/preface/preface.sgml +++ b/en_US.ISO8859-1/books/handbook/preface/preface.sgml @@ -35,8 +35,8 @@ - , DTrace, has been added with - information about the powerful DTrace performance analysis + , &dtrace;, has been added with + information about the powerful &dtrace; performance analysis tool. @@ -46,6 +46,12 @@ &os;, such as ZFS from &sun;. + + , Security Event Auditing, has + been added to cover the new auditing capabilities in &os; + and explain its use. + + , Virtualization, has been added with information about installing &os; on @@ -448,12 +454,13 @@ - , The Cutting Edge + , Updating and Upgrading &os; Explains the differences between FreeBSD-STABLE, FreeBSD-CURRENT, and FreeBSD releases. Describes which users would benefit from tracking a development system and outlines - that process. + that process. Covers the methods users may take to update their + system to the latest security release. diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml index 59d1b880f8..288374942d 100644 --- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml @@ -2688,7 +2688,7 @@ console="comconsole,vidconsole" Get the kernel source. (See ) + linkend="updating-upgrading">)