? cutting-edge.diff Index: chapter.sgml =================================================================== RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v retrieving revision 1.231 diff -u -r1.231 chapter.sgml --- chapter.sgml 2 Nov 2008 14:37:48 -0000 1.231 +++ chapter.sgml 15 Dec 2008 18:21:15 -0000 @@ -72,6 +72,22 @@ How to rebuild and reinstall the entire base system with make buildworld (etc). + + + What utilities may be used to update the system and + the Ports Collection. + + + + How to use freebsd-update to apply + security patches and perform major and minor &os; + upgrades. + + + + How to compare the state of an installed system against + a known pristine copy. + Before reading this chapter, you should: @@ -1775,6 +1791,475 @@ DISTDIR. + + + + + + Tom + Rhodes + Written by + + + + + Colin + Percival + Based on notes provided by + + + + FreeBSD Update + + Cutting Edge + + freebsd-update + cutting-edge + + + 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. 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 + latest version of freebsd-update may + be installed by downloading the tar and + gzip'd package from the above + URL and installed with the following + commands: + + &prompt.root; gunzip -c freebsd-update-upgrade.tgz | tar xvf - +&prompt.root; mv freebsd-update.sh /usr/sbin/freebsd-update +&prompt.root; mv freebsd-update.conf /etc + + For all current releases, downloading the latest version + is not required. + + + 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 + + Cutting Edge + + Portsnap + Cutting-edge + + + 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. +