? 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.
+