diff options
Diffstat (limited to 'en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml | 1701 |
1 files changed, 0 insertions, 1701 deletions
diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml deleted file mode 100644 index c558a2a901..0000000000 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ /dev/null @@ -1,1701 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - The FreeBSD Documentation Project - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="updating-upgrading"> - - <info> - <title>Updating and Upgrading &os;</title> - - <authorgroup> - <author> - <personname> - <firstname>Jim</firstname> - <surname>Mock</surname> - </personname> - <contrib>Restructured, reorganized, and parts updated - by </contrib> - </author> - <!-- Mar 2000 --> - </authorgroup> - - <authorgroup> - <author> - <personname> - <firstname>Jordan</firstname> - <surname>Hubbard</surname> - </personname> - <contrib>Original work by </contrib> - </author> - - <author> - <personname> - <firstname>Poul-Henning</firstname> - <surname>Kamp</surname> - </personname> - </author> - - <author> - <personname> - <firstname>John</firstname> - <surname>Polstra</surname> - </personname> - </author> - - <author> - <personname> - <firstname>Nik</firstname> - <surname>Clayton</surname> - </personname> - </author> - </authorgroup> - </info> - - <sect1 xml:id="updating-upgrading-synopsis"> - <title>Synopsis</title> - - <para>&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 the necessary tools to keep the system updated, and - allows for easy upgrades between versions. This chapter - describes how to track the development system and the basic - tools for keeping a &os; system up-to-date.</para> - - <para>After reading this chapter, you will know:</para> - - <itemizedlist> - <listitem> - <para>How to keep a &os; system up-to-date with - <application>freebsd-update</application> or - <application>Subversion</application>.</para> - </listitem> - - <listitem> - <para>How to compare the state of an installed system against - a known pristine copy.</para> - </listitem> - - <listitem> - <para>How to keep the installed documentation up-to-date with - <application>Subversion</application> or documentation - ports<!--, and <application>Docsnap</application>-->.</para> - </listitem> - - <listitem> - <para>The difference between the two development - branches: &os.stable; and &os.current;.</para> - </listitem> - - <listitem> - <para>How to rebuild and reinstall the entire base - system.</para> - </listitem> - </itemizedlist> - - <para>Before reading this chapter, you should:</para> - - <itemizedlist> - <listitem> - <para>Properly set up the network connection - (<xref linkend="advanced-networking"/>).</para> - </listitem> - - <listitem> - <para>Know how to install additional third-party - software (<xref linkend="ports"/>).</para> - </listitem> - </itemizedlist> - - <note> - <para>Throughout this chapter, <command>svnlite</command> is used to - obtain and update &os; sources. Optionally, the - <package>devel/subversion</package> port or - package may be used.</para> - </note> - </sect1> - - <sect1 xml:id="updating-upgrading-freebsdupdate"> - <info> - <title>&os; Update</title> - - <authorgroup> - <author> - <personname> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - </personname> - <contrib>Written by </contrib> - </author> - </authorgroup> - - <authorgroup> - <author> - <personname> - <firstname>Colin</firstname> - <surname>Percival</surname> - </personname> - <contrib>Based on notes provided by </contrib> - </author> - </authorgroup> - </info> - - <indexterm> - <primary>Updating and Upgrading</primary> - </indexterm> - <indexterm> - <primary>freebsd-update</primary> - <see>updating-upgrading</see> - </indexterm> - - <para>Applying security patches in a timely manner and upgrading - to a newer release of an operating system are important aspects - of ongoing system administration. &os; includes a utility - called <command>freebsd-update</command> which can be used to - perform both these tasks.</para> - - <para>This utility supports binary security and errata updates to - &os;, without the need to manually compile and install the patch - or a new kernel. Binary updates are available for all - architectures and releases currently supported by the security - team. The list of supported releases and their estimated - end-of-life dates are listed at <uri - xlink:href="https://www.FreeBSD.org/security/">https://www.FreeBSD.org/security/</uri>.</para> - - <para>This utility also supports operating system upgrades to - minor point releases as well as upgrades to another release - branch. Before upgrading to a new release, review its release - announcement as it contains important information pertinent to - the release. Release announcements are available from <uri - xlink:href="https://www.FreeBSD.org/releases/">https://www.FreeBSD.org/releases/</uri>.</para> - - <note> - <para>If a <command>crontab</command> utilizing the features of - &man.freebsd-update.8; exists, it must be disabled before - upgrading the operating system.</para> - </note> - - <para>This section describes the configuration file used by - <command>freebsd-update</command>, demonstrates how to apply a - security patch and how to upgrade to a minor or major operating - system release, and discusses some of the considerations when - upgrading the operating system.</para> - - <sect2 xml:id="freebsdupdate-config-file"> - <title>The Configuration File</title> - - <para>The default configuration file for - <command>freebsd-update</command> works as-is. Some users may - wish to tweak the default configuration in - <filename>/etc/freebsd-update.conf</filename>, allowing - better control of the process. The comments in this file - explain the available options, but the following may require a - bit more explanation:</para> - - <programlisting># Components of the base system which should be kept updated. -Components world kernel</programlisting> - - <para>This parameter controls which parts of &os; will be kept - up-to-date. The default is to update the entire base system - and the kernel. Individual components can instead be - specified, such as <literal>src/base</literal> or - <literal>src/sys</literal>. However, the best option is to - leave this at the default as changing it to include specific - items requires every needed item to be listed. Over time, - this could have disastrous consequences as source code and - binaries may become out of sync.</para> - - <programlisting># Paths which start with anything matching an entry in an IgnorePaths -# statement will be ignored. -IgnorePaths /boot/kernel/linker.hints</programlisting> - - <para>To leave specified directories, such as - <filename>/bin</filename> or <filename>/sbin</filename>, - untouched during the update process, add their paths to this - statement. This option may be used to prevent - <command>freebsd-update</command> from overwriting local - modifications.</para> - - <programlisting># 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</programlisting> - - <para>This option will only update unmodified configuration - files in the specified directories. Any changes made by the - user will prevent the automatic updating of these files. - There is another option, - <literal>KeepModifiedMetadata</literal>, which will instruct - <command>freebsd-update</command> to save the changes during - the merge.</para> - - <programlisting># 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/ /boot/device.hints</programlisting> - - <para>List of directories with configuration files that - <command>freebsd-update</command> should attempt to merge. - The file merge process is a series of &man.diff.1; patches - similar to &man.mergemaster.8;, but with fewer options. - Merges are either accepted, open an editor, or cause - <command>freebsd-update</command> to abort. When in doubt, - backup <filename>/etc</filename> and just accept the merges. - See &man.mergemaster.8; for more information about - <command>mergemaster</command>.</para> - - <programlisting># Directory in which to store downloaded updates and temporary -# files used by &os; Update. -# WorkDir /var/db/freebsd-update</programlisting> - - <para>This directory is where all patches and temporary files - are placed. In cases where the user is doing a version - upgrade, this location should have at least a gigabyte of disk - space available.</para> - - <programlisting># 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</programlisting> - - <para>When this option is set to <literal>yes</literal>, - <command>freebsd-update</command> will assume that the - <literal>Components</literal> list is complete and will not - attempt to make changes outside of the list. Effectively, - <command>freebsd-update</command> will attempt to update - every file which belongs to the <literal>Components</literal> - list.</para> - </sect2> - - <sect2 xml:id="freebsdupdate-security-patches"> - <title>Applying Security Patches</title> - - <para>The process of applying &os; security patches has been - simplified, allowing an administrator to keep a system fully - patched using <command>freebsd-update</command>. More - information about &os; security advisories can be found in - <xref linkend="security-advisories"/>.</para> - - <para>&os; security patches may be downloaded and installed - using the following commands. The first command will - determine if any outstanding patches are available, and if so, - will list the files that will be modifed if the patches are - applied. The second command will apply the patches.</para> - - <screen>&prompt.root; <userinput>freebsd-update fetch</userinput> -&prompt.root; <userinput>freebsd-update install</userinput></screen> - - <para>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 - applications should be restarted so that the patched version - of the binary is used.</para> - - <note> - <para>Usually, the user needs to be prepared to reboot the - system. To know if a reboot is required by a kernel update, - execute the commands <command>freebsd-version -k</command> - and <command>uname -r</command> and if it differs a reboot - is required.</para> - </note> - - <para>The system can be configured to automatically check for - updates once every day by adding this entry to - <filename>/etc/crontab</filename>:</para> - - <programlisting>@daily root freebsd-update cron</programlisting> - - <para>If patches exist, they will automatically be downloaded - but will not be applied. The <systemitem - class="username">root</systemitem> user will be sent an - email so that the patches may be reviewed and manually - installed with - <command>freebsd-update install</command>.</para> - - <para>If anything goes wrong, <command>freebsd-update</command> - has the ability to roll back the last set of changes with the - following command:</para> - - <screen>&prompt.root; <userinput>freebsd-update rollback</userinput> -Uninstalling updates... done.</screen> - - <para>Again, the system should be restarted if the kernel or any - kernel modules were modified and any affected binaries should - be restarted.</para> - - <para>Only the <filename>GENERIC</filename> kernel can be - automatically updated by <command>freebsd-update</command>. - If a custom kernel is installed, it will have to be rebuilt - and reinstalled after <command>freebsd-update</command> - finishes installing the updates. The default kernel name - is <emphasis>GENERIC</emphasis>. The &man.uname.1; command - may be used to verify its installation.</para> - - <note> - <para>Always keep a copy of the <filename>GENERIC</filename> - kernel in <filename>/boot/GENERIC</filename>. It will be - helpful in diagnosing a variety of problems and in - performing version upgrades. Refer to <xref - linkend="freebsd-update-custom-kernel-9x"/> for - instructions on how to get a copy of the - <filename>GENERIC</filename> kernel.</para> - </note> - - <para>Unless the default configuration in - <filename>/etc/freebsd-update.conf</filename> has been - changed, <command>freebsd-update</command> will install the - updated kernel sources along with the rest of the updates. - Rebuilding and reinstalling a new custom kernel can then be - performed in the usual way.</para> - - <para>The updates distributed by - <command>freebsd-update</command> do not always involve the - kernel. It is not necessary to rebuild a custom kernel if the - kernel sources have not been modified by - <command>freebsd-update install</command>. However, - <command>freebsd-update</command> will always update - <filename>/usr/src/sys/conf/newvers.sh</filename>. The - current patch level, as indicated by the <literal>-p</literal> - number reported by <command>uname -r</command>, is obtained - from this file. Rebuilding a custom kernel, even if nothing - else changed, allows <command>uname</command> 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.</para> - </sect2> - - <sect2 xml:id="freebsdupdate-upgrade"> - <title>Performing Major and Minor Version Upgrades</title> - - <para>Upgrades from one minor version of &os; to another, like - from &os; 9.0 to &os; 9.1, are called - <firstterm>minor version</firstterm> upgrades. - <firstterm>Major version</firstterm> 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 <command>freebsd-update</command> - with a release version target.</para> - - <note> - <para>If the system is running a custom kernel, make sure that - a copy of the <filename>GENERIC</filename> kernel exists in - <filename>/boot/GENERIC</filename> before starting the - upgrade. Refer to <xref - linkend="freebsd-update-custom-kernel-9x"/> for - instructions on how to get a copy of the - <filename>GENERIC</filename> kernel.</para> - </note> - - <para>The following command, when run on a &os; 9.0 system, - will upgrade it to &os; 9.1:</para> - - <screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen> - - <para>After the command has been received, - <command>freebsd-update</command> 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:</para> - - <screen>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. - -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)? <userinput>y</userinput></screen> - - <para>At this point, <command>freebsd-update</command> 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.</para> - - <para>When using a custom kernel, the above step will produce a - warning similar to the following:</para> - - <screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" 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"</screen> - - <para>This warning may be safely ignored at this point. The - updated <filename>GENERIC</filename> kernel will be used as an - intermediate step in the upgrade process.</para> - - <para>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 - <filename>/etc</filename> and manually merge important files, - such as <filename>master.passwd</filename> or - <filename>group</filename> at a later time.</para> - - <note> - <para>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:</para> - - <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> - </note> - - <para>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 <filename>/boot/GENERIC</filename>:</para> - - <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen> - - <warning> - <para>Before rebooting with the <filename>GENERIC</filename> - 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 - <filename>GENERIC</filename> kernel using the - <filename>/boot/loader.conf</filename> facility. It is - recommended to disable non-essential services as well as any - disk and network mounts until the upgrade process is - complete.</para> - </warning> - - <para>The machine should now be restarted with the updated - kernel:</para> - - <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> - - <para>Once the system has come back online, restart - <command>freebsd-update</command> using the following command. - Since the state of the process has been saved, - <command>freebsd-update</command> will not start from the - beginning, but will instead move on to the next phase and - remove all old shared libraries and object files.</para> - - <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> - - <note> - <para>Depending upon whether any library version numbers were - bumped, there may only be two install phases instead of - three.</para> - </note> - - <para>The upgrade is now complete. If this was a major version - upgrade, reinstall all ports and packages as described in - <xref linkend="freebsdupdate-portsrebuild"/>.</para> - - <sect3 xml:id="freebsd-update-custom-kernel-9x"> - <title>Custom Kernels with &os; 9.X and Later</title> - - <para>Before using <command>freebsd-update</command>, ensure - that a copy of the <filename>GENERIC</filename> kernel - exists in <filename>/boot/GENERIC</filename>. If a custom - kernel has only been built once, the kernel in - <filename>/boot/kernel.old</filename> is the - <literal>GENERIC</literal> kernel. Simply rename this - directory to <filename>/boot/GENERIC</filename>.</para> - - <para>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 <literal>GENERIC</literal> - kernel that matches the current version of the operating - system. If physical access to the system is available, a - copy of the <literal>GENERIC</literal> kernel can be - installed from the installation media:</para> - - <screen>&prompt.root; <userinput>mount /cdrom</userinput> -&prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput> -&prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen> - - <para>Alternately, the <literal>GENERIC</literal> kernel may - be rebuilt and installed from source:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput></screen> - - <para>For this kernel to be identified as the - <literal>GENERIC</literal> kernel by - <command>freebsd-update</command>, the - <filename>GENERIC</filename> configuration file must not - have been modified in any way. It is also suggested that - the kernel is built without any other special - options.</para> - - <para>Rebooting into the <filename>GENERIC</filename> kernel - is not required as <command>freebsd-update</command> only - needs <filename>/boot/GENERIC</filename> to exist.</para> - </sect3> - - <sect3 xml:id="freebsdupdate-portsrebuild"> - <title>Upgrading Packages After a Major Version - Upgrade</title> - - <para>Generally, installed applications will continue to work - without problems after minor version upgrades. Major - versions use different Application Binary Interfaces - (<acronym>ABI</acronym>s), which will break most - third-party applications. After a major version upgrade, - all installed packages and ports need to be upgraded. - Packages can be upgraded using <command>pkg - upgrade</command>. To upgrade installed ports, use a - utility such as - <package>ports-mgmt/portmaster</package>.</para> - - <para>A forced upgrade of all installed packages will replace - the packages with fresh versions from the repository even if - the version number has not increased. This is required - because of the ABI version change when upgrading between - major versions of &os;. The forced upgrade can be - accomplished by performing:</para> - - <screen>&prompt.root; <userinput>pkg-static upgrade -f</userinput></screen> - - <para>A rebuild of all installed applications can be - accomplished with this command:</para> - - <screen>&prompt.root; <userinput>portmaster -af</userinput></screen> - - <para>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 - <option>-G</option> in the above command.</para> - - <para>Once the software upgrades are complete, finish the - upgrade process with a final call to - <command>freebsd-update</command> in order to tie up all the - loose ends in the upgrade process:</para> - - <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> - - <para>If the <filename>GENERIC</filename> kernel was - temporarily used, this is the time to build and install a - new custom kernel using the instructions in <xref - linkend="kernelconfig"/>.</para> - - <para>Reboot the machine into the new &os; version. The - upgrade process is now complete.</para> - </sect3> - </sect2> - - <sect2 xml:id="freebsdupdate-system-comparison"> - <title>System State Comparison</title> - - <para>The state of the installed &os; version against a known - good copy can be tested using - <command>freebsd-update IDS</command>. This command evaluates - the current version of system utilities, libraries, and - configuration files and can be used as a built-in Intrusion - Detection System (<acronym>IDS</acronym>).</para> - - <warning> - <para>This command is not a replacement for a real - <acronym>IDS</acronym> such as - <package>security/snort</package>. As - <command>freebsd-update</command> stores data on disk, the - possibility of tampering is evident. While this possibility - may be reduced using <varname>kern.securelevel</varname> and - by storing the <command>freebsd-update</command> 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 <acronym>DVD</acronym> or securely stored external - <acronym>USB</acronym> disk device. An alternative method - for providing <acronym>IDS</acronym> functionality using a - built-in utility is described in <xref - linkend="security-ids"/></para> - </warning> - - <para>To begin the comparison, specify the output file to save - the results to:</para> - - <screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen> - - <para>The system will now be inspected and a lengthy listing of - files, along with the <acronym>SHA256</acronym> hash values - for both the known value in the release and the current - installation, will be sent to the specified output - file.</para> - - <para>The entries in the listing are extremely long, but the - output format may be easily parsed. For instance, to obtain a - list of all files which differ from those in the release, - issue the following command:</para> - - <screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput> -/etc/master.passwd -/etc/motd -/etc/passwd -/etc/pf.conf</screen> - - <para>This sample output has been truncated as many more files - exist. Some files have natural modifications. For example, - <filename>/etc/passwd</filename> will be modified if users - have been added to the system. Kernel modules may differ as - <command>freebsd-update</command> may have updated them. To - exclude specific files or directories, add them to the - <literal>IDSIgnorePaths</literal> option in - <filename>/etc/freebsd-update.conf</filename>.</para> - </sect2> - </sect1> - - <sect1 xml:id="updating-upgrading-documentation"> - <title>Updating the Documentation Set</title> - - <indexterm><primary>Updating and Upgrading</primary></indexterm> - - <indexterm> - <primary>Documentation</primary> - <see>Updating and Upgrading</see> - </indexterm> - - <para>Documentation is an integral part of the &os; operating - system. While an up-to-date version of the &os; documentation - is always available on the &os; web site (<link - xlink:href="&url.base;/doc/">https://www.freebsd.org/doc/</link>), - it can be handy to have an up-to-date, local copy of the &os; - website, handbooks, <acronym>FAQ</acronym>, and articles.</para> - - <para>This section describes how to use either source or the &os; - Ports Collection to keep a local copy of the &os; documentation - up-to-date.</para> - - <para>For information on editing and submitting corrections to the - documentation, refer to the &os; Documentation Project Primer - for New Contributors (<link - xlink:href="&url.books.fdp-primer;">https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para> - - <sect2 xml:id="updating-installed-documentation"> - <title>Updating Documentation from Source</title> - - <para>Rebuilding the &os; documentation from source requires a - collection of tools which are not part of the &os; base - system. The required tools can be installed from the - <package>textproc/docproj</package> package or port developed - by the &os; Documentation Project.</para> - - <para>Once installed, use <application>svnlite</application> to - fetch a clean copy of the documentation source:</para> - - <screen>&prompt.root; <userinput>svnlite checkout https://svn.FreeBSD.org/doc/head /usr/doc</userinput></screen> - - <para>The initial download of the documentation sources may take - a while. Let it run until it completes.</para> - - <para>Future updates of the documentation sources may be fetched - by running:</para> - - <screen>&prompt.root; <userinput>svnlite update /usr/doc</userinput></screen> - - <para>Once an up-to-date snapshot of the documentation sources - has been fetched to <filename>/usr/doc</filename>, everything - is ready for an update of the installed documentation.</para> - - <para>A full update of all available languages may be performed - by typing:</para> - - <screen>&prompt.root; <userinput>cd /usr/doc</userinput> -&prompt.root; <userinput>make install clean</userinput></screen> - - <para>If an update of only a specific language is desired, - <command>make</command> can be invoked in a language-specific - subdirectory of - <filename>/usr/doc</filename>:</para> - - <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput> -&prompt.root; <userinput>make install clean</userinput></screen> - - <para>An alternative way of updating the documentation is to run - this command from <filename>/usr/doc</filename> or the desired - language-specific subdirectory:</para> - - <screen>&prompt.root; <userinput>make update</userinput></screen> - - <para>The output formats that will be installed may be specified - by setting <varname>FORMATS</varname>:</para> - - <screen>&prompt.root; <userinput>cd /usr/doc</userinput> -&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen> - - <para>Several options are available to ease the process of - updating only parts of the documentation, or the build of - specific translations. These options can be set either as - system-wide options in <filename>/etc/make.conf</filename>, or - as command-line options passed to - <command>make</command>.</para> - - <para>The options include:</para> - - <variablelist> - <varlistentry> - <term><varname>DOC_LANG</varname></term> - - <listitem> - <para>The list of languages and encodings to build and - install, such as <literal>en_US.ISO8859-1</literal> for - English documentation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>FORMATS</varname></term> - - <listitem> - <para>A single format or a list of output formats to be - built. Currently, <literal>html</literal>, - <literal>html-split</literal>, <literal>txt</literal>, - <literal>ps</literal>, and <literal>pdf</literal> are - supported.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DOCDIR</varname></term> - - <listitem> - <para>Where to install the documentation. It defaults to - <filename>/usr/share/doc</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more <command>make</command> variables supported as - system-wide options in &os;, refer to - &man.make.conf.5;.</para> - </sect2> - - <sect2 xml:id="doc-ports-install-package"> - <info> - <title>Updating Documentation from Ports</title> - - <authorgroup> - <author> - <personname> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - </personname> - <contrib>Based on the work of </contrib> - </author> - </authorgroup> - </info> - - <indexterm> - <primary>Updating and Upgrading</primary> - </indexterm> - - <indexterm> - <primary>documentation package</primary> - <see>Updating and Upgrading</see> - </indexterm> - - <para>The previous section presented a method for updating the - &os; documentation from sources. This section describes an - alternative method which uses the Ports Collection and makes - it possible to:</para> - - <itemizedlist> - <listitem> - <para>Install pre-built packages of the documentation, - without having to locally build anything or install the - documentation toolchain.</para> - </listitem> - - <listitem> - <para>Build the documentation sources through the ports - framework, making the checkout and build steps a bit - easier.</para> - </listitem> - </itemizedlist> - - <para>This method of updating the &os; documentation is - supported by a set of documentation ports and packages which - are updated by the &a.doceng; on a monthly basis. These are - listed in the &os; Ports Collection, under the docs - category (<link - xlink:href="http://www.freshports.org/docs/">http://www.freshports.org/docs/</link>).</para> - - <para>Organization of the documentation ports is as - follows:</para> - - <itemizedlist> - <listitem> - <para>The <package>misc/freebsd-doc-en</package> package or - port installs all of the English documentation.</para> - </listitem> - - <listitem> - <para>The <package>misc/freebsd-doc-all</package> - meta-package or port installs all documentation in all - available languages.</para> - </listitem> - - <listitem> - <para>There is a package and port for each translation, such - as <package>misc/freebsd-doc-hu</package> for the - Hungarian documentation.</para> - </listitem> - </itemizedlist> - - <para>When binary packages are used, the &os; documentation will - be installed in all available formats for the given language. - For example, the following command will install the latest - package of the Hungarian documentation:</para> - - <screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen> - - <note> - <para>Packages use a format that differs from the - corresponding port's name: - <literal><replaceable>lang</replaceable>-freebsd-doc</literal>, - where <replaceable>lang</replaceable> is the short format of - the language code, such as <literal>hu</literal> for - Hungarian, or <literal>zh_cn</literal> for Simplified - Chinese.</para> - </note> - - <para>To specify the format of the documentation, build the port - instead of installing the package. For example, to build and - install the English documentation:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput> -&prompt.root; <userinput>make install clean</userinput></screen> - - <para>The port provides a configuration menu where the format to - build and install can be specified. By default, split - <acronym>HTML</acronym>, similar to the format used on <uri - xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>, - and <acronym>PDF</acronym> are selected.</para> - - <para>Alternately, several <command>make</command> options can - be specified when building a documentation port, - including:</para> - - <variablelist> - <varlistentry> - <term><varname>WITH_HTML</varname></term> - - <listitem> - <para>Builds the HTML format with a single HTML file per - document. The formatted documentation is saved to a - file called <filename>article.html</filename>, or - <filename>book.html</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>WITH_PDF</varname></term> - - <listitem> - <para>The formatted documentation is saved to a file - called <filename>article.pdf</filename> or - <filename>book.pdf</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DOCBASE</varname></term> - - <listitem> - <para>Specifies where to install the documentation. It - defaults to - <filename>/usr/local/share/doc/freebsd</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>This example uses variables to install the Hungarian - documentation as a <acronym>PDF</acronym> in the specified - directory:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-hu</userinput> -&prompt.root; <userinput>make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</userinput></screen> - - <para>Documentation packages or ports can be updated using the - instructions in <xref linkend="ports"/>. For example, the - following command updates the installed Hungarian - documentation using <package>ports-mgmt/portmaster</package> - by using packages only:</para> - - <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen> - </sect2> - </sect1> - - <sect1 xml:id="current-stable"> - <title>Tracking a Development Branch</title> - - <indexterm><primary>-CURRENT</primary></indexterm> - <indexterm><primary>-STABLE</primary></indexterm> - - <para>&os; has two development branches: &os.current; and - &os.stable;.</para> - - <para>This section provides an explanation of each branch and its - intended audience, as well as how to keep a system up-to-date - with each respective branch.</para> - - <sect2 xml:id="current"> - <title>Using &os.current;</title> - - <para>&os.current; is the <quote>bleeding edge</quote> of &os; - development and &os.current; users are expected to have a - high degree of technical skill. Less technical users who wish - to track a development branch should track &os.stable; - instead.</para> - - <para>&os.current; is the very latest source code for &os; and - includes works in progress, experimental changes, and - transitional mechanisms that might or might not be present in - the next official release. While many &os; developers compile - the &os.current; source code daily, there are short periods of - time when the source may not be buildable. These problems are - resolved as quickly as possible, but whether or not - &os.current; brings disaster or new functionality can be a - matter of when the source code was synced.</para> - - <para>&os.current; is made available for three primary interest - groups:</para> - - <orderedlist> - <listitem> - <para>Members of the &os; community who are actively - working on some part of the source tree.</para> - </listitem> - - <listitem> - <para>Members of the &os; community who are active testers. - They are willing to spend time solving problems, making - topical suggestions on changes and the general direction - of &os;, and submitting patches.</para> - </listitem> - - <listitem> - <para>Users who wish to keep an eye on things, use the - current source for reference purposes, or make the - occasional comment or code contribution.</para> - </listitem> - </orderedlist> - - <para>&os.current; should <emphasis>not</emphasis> be - considered a fast-track to getting new features before the - next release as pre-release features are not yet fully tested - and most likely contain bugs. It is not a quick way of - getting bug fixes as any given commit is just as likely to - introduce new bugs as to fix existing ones. &os.current; is - not in any way <quote>officially supported</quote>.</para> - - <indexterm> - <primary>-CURRENT</primary> - <secondary>using</secondary> - </indexterm> - - <para>To track &os.current;:</para> - - <orderedlist> - <listitem> - <para>Join the &a.current.name; and the - &a.svn-src-head.name; lists. This is - <emphasis>essential</emphasis> in order to see the - comments that people are making about the current state - of the system and to receive important bulletins about - the current state of &os.current;.</para> - - <para>The &a.svn-src-head.name; list records the commit log - entry for each change as it is made, along with any - pertinent information on possible side effects.</para> - - <para>To join these lists, go to &a.mailman.lists.link;, - click on the list to subscribe to, and follow the - instructions. In order to track changes to the whole - source tree, not just the changes to &os.current;, - subscribe to the &a.svn-src-all.name; list.</para> - </listitem> - - <listitem> - <para>Synchronize with the &os.current; sources. Typically, - <link linkend="svn">svnlite</link> is used to check out the - -CURRENT code from the <literal>head</literal> branch of - one of the Subversion mirror sites listed in - <xref linkend="svn-mirrors"/>.</para> - </listitem> - - <listitem> - <para>Due to the size of the repository, some users choose - to only synchronize the sections of source that interest - them or which they are contributing patches to. However, - users that plan to compile the operating system from - source must download <emphasis>all</emphasis> of - &os.current;, not just selected portions.</para> - - <para>Before compiling &os.current; - <indexterm> - <primary>-CURRENT</primary> - <secondary>compiling</secondary> - </indexterm>, read <filename>/usr/src/Makefile</filename> - very carefully and follow the instructions in - <xref linkend="makeworld"/>. - Read the &a.current; and - <filename>/usr/src/UPDATING</filename> to stay - up-to-date on other bootstrapping procedures that - sometimes become necessary on the road to the next - release.</para> - </listitem> - - <listitem> - <para>Be active! &os.current; users are encouraged to - submit their suggestions for enhancements or bug fixes. - Suggestions with accompanying code are always - welcome.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2 xml:id="stable"> - <title>Using &os.stable;</title> - - <para>&os.stable; is the development branch from which major - releases are made. Changes go into this branch at a slower - pace and with the general assumption that they have first been - tested in &os.current;. This is <emphasis>still</emphasis> a - development branch and, at any given time, the sources for - &os.stable; may or may not be suitable for general use. It is - simply another engineering development track, not a resource - for end-users. Users who do not have the resources to perform - testing should instead run the most recent release of - &os;.</para> - - <para>Those interested in tracking or contributing to the &os; - development process, especially as it relates to the next - release of &os;, should consider following &os.stable;.</para> - - <para>While the &os.stable; branch should compile and run at all - times, this cannot be guaranteed. Since more people run - &os.stable; than &os.current;, it is inevitable that bugs and - corner cases will sometimes be found in &os.stable; that were - not apparent in &os.current;. For this reason, one should not - blindly track &os.stable;. It is particularly important - <emphasis>not</emphasis> to update any production servers to - &os.stable; without thoroughly testing the code in a - development or testing environment.</para> - - <para>To track &os.stable;:</para> - - <indexterm> - <primary>-STABLE</primary> - <secondary>using</secondary> - </indexterm> - <orderedlist> - <listitem> - <para>Join the &a.stable.name; list in order to stay - informed of build dependencies that may appear in - &os.stable; or any other issues requiring special - attention. Developers will also make announcements in - this mailing list when they are contemplating some - controversial fix or update, giving the users a chance to - respond if they have any issues to raise concerning the - proposed change.</para> - - <para>Join the relevant <application>svn</application> list - for the branch being tracked. For example, users - tracking the 9-STABLE branch should join the - &a.svn-src-stable-9.name; list. This list records the - commit log entry for each change as it is made, along - with any pertinent information on possible - side effects.</para> - - <para>To join these lists, go to &a.mailman.lists.link;, - click on the list to subscribe to, and follow the - instructions. In order to track changes for the whole - source tree, subscribe to &a.svn-src-all.name;.</para> - </listitem> - - <listitem> - <para>To install a new &os.stable; system, install the most - recent &os.stable; release from the <link - linkend="mirrors">&os; mirror sites</link> or use a - monthly snapshot built from &os.stable;. Refer to <link - xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots</link> - for more information about snapshots.</para> - - <para>To compile or upgrade to an existing &os; system to - &os.stable;, use <link linkend="svn">svn</link> - <indexterm> - <primary>Subversion</primary> - </indexterm> to check out the source for the desired - branch. Branch names, such as - <literal>stable/9</literal>, are listed at <link - xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</para> - </listitem> - - <listitem> - <para>Before compiling or upgrading to &os.stable; - <indexterm> - <primary>-STABLE</primary> - <secondary>compiling</secondary> - </indexterm>, read <filename>/usr/src/Makefile</filename> - carefully and follow the instructions in <xref - linkend="makeworld"/>. Read the &a.stable; and - <filename>/usr/src/UPDATING</filename> to keep up-to-date - on other bootstrapping procedures that sometimes become - necessary on the road to the next release.</para> - </listitem> - </orderedlist> - </sect2> - </sect1> - - <sect1 xml:id="makeworld"> - <title xml:id="updating-src">Updating &os; from Source</title> - - <para>Updating &os; by compiling from source offers several - advantages over binary updates. Code can be built with options - to take advantage of specific hardware. Parts of the base - system can be built with non-default settings, or left out - entirely where they are not needed or desired. The build - process takes longer to update a system than just installing - binary updates, but allows complete customization to produce - a tailored version of &os;.</para> - - <sect2 xml:id="updating-src-quick-start"> - <title>Quick Start</title> - - <para>This is a quick reference for the typical steps used to - update &os; by building from source. Later sections describe - the process in more detail.</para> - - <procedure> - <step> - <title>Update and Build</title> - - <screen>&prompt.root; <userinput>svnlite update /usr/src</userinput> <co xml:id="updating-src-qs-svnup"/> -<emphasis>check <filename>/usr/src/UPDATING</filename></emphasis> <co xml:id="updating-src-qs-review-updating"/> -&prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd"/> -&prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput> <co xml:id="updating-src-qs-buildworld"/> -&prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput> <co xml:id="updating-src-qs-kernel"/> -&prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-reboot"/> -&prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd2"/> -&prompt.root; <userinput>make installworld</userinput> <co xml:id="updating-src-qs-installworld"/> -&prompt.root; <userinput>mergemaster -Ui</userinput> <co xml:id="updating-src-qs-mergemaster"/> -&prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-shutdown"/></screen> - - <calloutlist> - <callout arearefs="updating-src-qs-svnup"> - <para>Get the latest version of the source. See - <xref linkend="updating-src-obtaining-src"/> for - more information on obtaining and updating - source.</para> - </callout> - - <callout arearefs="updating-src-qs-review-updating"> - <para>Check <filename>/usr/src/UPDATING</filename> - for any manual steps required before or after building - from source.</para> - </callout> - - <callout arearefs="updating-src-qs-cd"> - <para>Go to the source directory.</para> - </callout> - - <callout arearefs="updating-src-qs-buildworld"> - <para>Compile the world, everything except the - kernel.</para> - </callout> - - <callout arearefs="updating-src-qs-kernel"> - <para>Compile and install the kernel. This is - equivalent to <command>make buildkernel - installkernel</command>.</para> - </callout> - - <callout arearefs="updating-src-qs-reboot"> - <para>Reboot the system to the new kernel.</para> - </callout> - - <callout arearefs="updating-src-qs-cd2"> - <para>Go to the source directory.</para> - </callout> - - <callout arearefs="updating-src-qs-installworld"> - <para>Install the world.</para> - </callout> - - <callout arearefs="updating-src-qs-mergemaster"> - <para>Update and merge configuration files in - <filename>/etc/</filename>.</para> - </callout> - - <callout arearefs="updating-src-qs-shutdown"> - <para>Restart the system to use the newly-built world - and kernel.</para> - </callout> - </calloutlist> - </step> - </procedure> - </sect2> - - <sect2 xml:id="updating-src-preparing"> - <title>Preparing for a Source Update</title> - - <para>Read <filename>/usr/src/UPDATING</filename>. Any manual - steps that must be performed before or after an update are - described in this file.</para> - </sect2> - - <sect2 xml:id="updating-src-obtaining-src"> - <title>Updating the Source</title> - - <para>&os; source code is located in - <filename>/usr/src/</filename>. The preferred method of - updating this source is through the - <application>Subversion</application> version control system. - Verify that the source code is under version control:</para> - - <screen>&prompt.root; <userinput>svnlite info /usr/src</userinput> -Path: /usr/src -Working Copy Root Path: /usr/src -...</screen> - - <para>This indicates that <filename>/usr/src/</filename> - is under version control and can be updated with - &man.svnlite.1;:</para> - - <screen xml:id="synching">&prompt.root; <userinput>svnlite update /usr/src</userinput></screen> - - <para>The update process can take some time if the directory has - not been updated recently. After it finishes, the source code - is up to date and the build process described in the next - section can begin.</para> - - <note xml:id="updating-src-obtaining-src-checkout"> - <title>Obtaining the Source</title> - - <para>If the output says - <literal>'/usr/src' is not a working copy</literal>, the - files there are missing or were installed with a different - method. A new checkout of the source is required.</para> - - <table xml:id="updating-src-obtaining-src-repopath"> - <title>&os; Versions and Repository Paths</title> - - <tgroup cols="3"> - <thead> - <row> - <entry><command>uname -r</command> Output</entry> - <entry>Repository Path</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal><replaceable>X.Y</replaceable>-RELEASE</literal></entry> - <entry><literal>base/releng/</literal><replaceable>X.Y</replaceable></entry> - <entry>The Release version plus only critical security - and bug fix patches. This branch is recommended - for most users.</entry> - </row> - - <row xml:id="STABLE"> - <entry><literal><replaceable>X.Y</replaceable>-STABLE</literal></entry> - <entry><literal>base/stable/</literal><replaceable>X</replaceable></entry> - <entry> - <para>The Release version plus all additional - development on that branch. - <emphasis>STABLE</emphasis> refers to the - Applications Binary Interface - (<acronym>ABI</acronym>) not changing, so software - compiled for earlier versions still runs. For - example, software compiled to run on &os; 10.1 - will still run on &os; 10-STABLE compiled - later.</para> - - <para>STABLE branches occasionally have bugs or - incompatibilities which might affect users, - although these are typically fixed quickly.</para> - </entry> - </row> - - <row> - <entry><literal><replaceable>X</replaceable>-CURRENT</literal></entry> - <entry><literal>base/head/</literal></entry> - <entry>The latest unreleased development version of - &os;. The CURRENT branch can have major bugs or - incompatibilities and is recommended only for - advanced users.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Determine which version of &os; is being used with - &man.uname.1;:</para> - - <screen>&prompt.root; <userinput>uname -r</userinput> -10.3-RELEASE</screen> - - <para>Based on - <xref linkend="updating-src-obtaining-src-repopath"/>, the - source used to update <literal>10.3-RELEASE</literal> has - a repository path of <literal>base/releng/10.3</literal>. - That path is used when checking out the source:</para> - - <screen>&prompt.root; <userinput>mv /usr/src /usr/src.bak</userinput> <co xml:id="updating-src-obtaining-src-mv"/> -&prompt.root; <userinput>svnlite checkout https://svn.freebsd.org/base/<replaceable>releng/10.3</replaceable> /usr/src</userinput> <co xml:id="updating-src-obtaining-src-checkout-cmd"/></screen> - - <calloutlist> - <callout arearefs="updating-src-obtaining-src-mv"> - <para>Move the old directory out of the way. If there are - no local modifications in this directory, it can be - deleted.</para> - </callout> - - <callout arearefs="updating-src-obtaining-src-checkout-cmd"> - <para>The path from - <xref linkend="updating-src-obtaining-src-repopath"/> is - added to the repository <acronym>URL</acronym>. The - third parameter is the destination directory for the - source code on the local system.</para> - </callout> - </calloutlist> - </note> - </sect2> - - <sect2 xml:id="updating-src-building"> - <title>Building from Source</title> - - <para>The <emphasis>world</emphasis>, or all - of the operating system except the kernel, is compiled. This - is done first to provide up-to-date tools to build the kernel. - Then the kernel itself is built:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildworld</userinput> -&prompt.root; <userinput>make buildkernel</userinput></screen> - - <para>The compiled code is written to - <filename>/usr/obj</filename>.</para> - - <para>These are the basic steps. Additional options to control - the build are described below.</para> - - <sect3 xml:id="updating-src-building-clean-build"> - <title>Performing a Clean Build</title> - - <para>Some versions of the &os; build system leave - previously-compiled code in the temporary object directory, - <filename>/usr/obj</filename>. This can speed up later - builds by avoiding recompiling code that has not changed. - To force a clean rebuild of everything, use - <buildtarget>cleanworld</buildtarget> before starting - a build:</para> - - <screen>&prompt.root; <userinput>make cleanworld</userinput></screen> - </sect3> - - <sect3 xml:id="updating-src-building-jobs"> - <title>Setting the Number of Jobs</title> - - <para>Increasing the number of build jobs on multi-core - processors can improve build speed. Determine the number of - cores with <command>sysctl hw.ncpu</command>. Processors - vary, as do the build systems used with different versions - of &os;, so testing is the only sure method to tell how a - different number of jobs affects the build speed. For a - starting point, consider values between half and double the - number of cores. The number of jobs is specified with - <option>-j</option>.</para> - - <example xml:id="updating-src-building-jobs-example"> - <title>Increasing the Number of Build Jobs</title> - - <para>Building the world and kernel with four jobs:</para> - - <screen>&prompt.root; <userinput>make -j4 buildworld buildkernel</userinput></screen> - </example> - </sect3> - - <sect3 xml:id="updating-src-building-only-kernel"> - <title>Building Only the Kernel</title> - - <para>A <buildtarget>buildworld</buildtarget> must be - completed if the source code has changed. After that, a - <buildtarget>buildkernel</buildtarget> to build a kernel can - be run at any time. To build just the kernel:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildkernel</userinput></screen> - </sect3> - - <sect3 xml:id="updating-src-building-custom-kernel"> - <title>Building a Custom Kernel</title> - - <para>The standard &os; kernel is based on a - <emphasis>kernel config file</emphasis> called - <filename>GENERIC</filename>. The - <filename>GENERIC</filename> kernel includes the most - commonly-needed device drivers and options. Sometimes it - is useful or necessary to build a custom kernel, adding or - removing device drivers or options to fit a specific - need.</para> - - <para>For example, someone developing a small embedded - computer with severely limited <acronym>RAM</acronym> could - remove unneeded device drivers or options to make the kernel - slightly smaller.</para> - - <para>Kernel config files are located in - <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/</filename>, - where <replaceable>arch</replaceable> is the output from - <command>uname -m</command>. On most computers, that is - <literal>amd64</literal>, giving a config file directory of - <filename>/usr/src/sys/<replaceable>amd64</replaceable>/conf/</filename>.</para> - - <tip> - <para><filename>/usr/src</filename> can be deleted or - recreated, so it is preferable to keep custom kernel - config files in a separate directory, like - <filename>/root</filename>. Link the kernel config file - into the <filename>conf</filename> directory. If that - directory is deleted or overwritten, the kernel config - can be re-linked into the new one.</para> - </tip> - - <para>A custom config file can be created by copying the - <filename>GENERIC</filename> config file. In this example, - the new custom kernel is for a storage server, so is named - <filename>STORAGESERVER</filename>:</para> - - <screen>&prompt.root; <userinput>cp /usr/src/sys/amd64/conf/GENERIC /root/STORAGESERVER</userinput> -&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput> -&prompt.root; <userinput>ln -s /root/STORAGESERVER .</userinput></screen> - - <para><filename>/root/STORAGESERVER</filename> is then edited, - adding or removing devices or options as shown in - &man.config.5;.</para> - - <para>The custom kernel is built by setting - <varname>KERNCONF</varname> to the kernel config file on the - command line:</para> - - <screen>&prompt.root; <userinput>make buildkernel KERNCONF=STORAGESERVER</userinput></screen> - </sect3> - </sect2> - - <sect2 xml:id="updating-src-installing"> - <title>Installing the Compiled Code</title> - - <para>After the <buildtarget>buildworld</buildtarget> and - <buildtarget>buildkernel</buildtarget> steps have been - completed, the new kernel and world are installed:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make installkernel</userinput> -&prompt.root; <userinput>shutdown -r now</userinput> -&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make installworld</userinput> -&prompt.root; <userinput>shutdown -r now</userinput></screen> - - <para>If a custom kernel was built, <varname>KERNCONF</varname> - must also be set to use the new custom kernel:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make installkernel KERNCONF=STORAGESERVER</userinput> -&prompt.root; <userinput>shutdown -r now</userinput> -&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make installworld</userinput> -&prompt.root; <userinput>shutdown -r now</userinput></screen> - </sect2> - - <sect2 xml:id="updating-src-completing"> - <title>Completing the Update</title> - - <para>A few final tasks complete the update. Any modified - configuration files are merged with the new versions, outdated - libraries are located and removed, then the system is - restarted.</para> - - <sect3 xml:id="updating-src-completing-merge-mergemaster"> - <title>Merging Configuration Files with - &man.mergemaster.8;</title> - - <para>&man.mergemaster.8; provides an easy - way to merge changes that have been made to system - configuration files with new versions of those files.</para> - - <para>With <option>-Ui</option>, &man.mergemaster.8; - automatically updates files that have not been user-modified - and installs new files that are not already present:</para> - - <screen>&prompt.root; <userinput>mergemaster -Ui</userinput></screen> - - <para>If a file must be manually merged, an interactive - display allows the user to choose which portions of the - files are kept. See &man.mergemaster.8; for more - information.</para> - </sect3> - - <sect3 xml:id="updating-src-completing-check-old"> - <title>Checking for Outdated Files and Libraries</title> - - <para>Some obsolete files or directories can remain after an - update. These files can be located:</para> - - <screen>&prompt.root; <userinput>make check-old</userinput></screen> - - <para>and deleted:</para> - - <screen>&prompt.root; <userinput>make delete-old</userinput></screen> - - <para>Some obsolete libraries can also remain. These can be - detected with:</para> - - <screen>&prompt.root; <userinput>make check-old-libs</userinput></screen> - - <para>and deleted with</para> - - <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> - - <para>Programs which were still using those old libraries will - stop working when the library has been deleted. These - programs must be rebuilt or replaced after deleting the old - libraries.</para> - - <tip> - <para>When all the old files or directories are known to be - safe to delete, pressing <keycap>y</keycap> and - <keycap>Enter</keycap> to delete each file can be avoided - by setting <varname>BATCH_DELETE_OLD_FILES</varname> in - the command. For example:</para> - - <screen>&prompt.root; <userinput>make BATCH_DELETE_OLD_FILES=yes delete-old-libs</userinput></screen> - </tip> - </sect3> - - <sect3 xml:id="updating-src-completing-restart"> - <title>Restarting After the Update</title> - - <para>The last step after updating is to restart the computer - so all the changes take effect:</para> - - <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> - </sect3> - </sect2> - </sect1> - - <sect1 xml:id="small-lan"> - <info> - <title>Tracking for Multiple Machines</title> - - <authorgroup> - <author> - <personname> - <firstname>Mike</firstname> - <surname>Meyer</surname> - </personname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - </info> - - <indexterm> - <primary>NFS</primary> - <secondary>installing multiple machines</secondary> - </indexterm> - - <para>When multiple machines need to track the same source tree, - it is a waste of disk space, network bandwidth, and - <acronym>CPU</acronym> cycles to have each system download the - sources and rebuild everything. The solution is to have one - machine do most of the work, while the rest of the machines - mount that work via <acronym>NFS</acronym>. This section - outlines a method of doing so. For more information about using - <acronym>NFS</acronym>, refer to <xref - linkend="network-nfs"/>.</para> - - <para>First, identify a set of machines which will run the same - set of binaries, known as a <firstterm>build set</firstterm>. - Each machine can have a custom kernel, but will run the same - userland binaries. From that set, choose a machine to be the - <firstterm>build machine</firstterm> that the world and kernel - are built on. Ideally, this is a fast machine that has - sufficient spare <acronym>CPU</acronym> to run <command>make - buildworld</command> and <command>make - buildkernel</command>.</para> - - <para>Select a machine to be the <firstterm>test - machine</firstterm>, which will test software updates before - they are put into production. This <emphasis>must</emphasis> be - a machine that can afford to be down for an extended period of - time. It can be the build machine, but need not be.</para> - - <para>All the machines in this build set need to mount - <filename>/usr/obj</filename> and <filename>/usr/src</filename> - from the build machine via <acronym>NFS</acronym>. For multiple - build sets, <filename>/usr/src</filename> should be on one build - machine, and <acronym>NFS</acronym> mounted on the rest.</para> - - <para>Ensure that <filename>/etc/make.conf</filename> and - <filename>/etc/src.conf</filename> on all the machines in the - build set agree with the build machine. That means that the - build machine must build all the parts of the base system that - any machine in the build set is going to install. Also, each - build machine should have its kernel name set with - <varname>KERNCONF</varname> in - <filename>/etc/make.conf</filename>, and the build machine - should list them all in its <varname>KERNCONF</varname>, - listing its own kernel first. The build machine must have the - kernel configuration files for each machine in its <filename - >/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>.</para> - - <para>On the build machine, build the kernel and world as - described in <xref linkend="makeworld"/>, but do not install - anything on the build machine. Instead, install the built - kernel on the test machine. On the test machine, mount - <filename>/usr/src</filename> and - <filename>/usr/obj</filename> via <acronym>NFS</acronym>. Then, - run <command>shutdown now</command> to go to single-user mode in - order to install the new kernel and world and run - <command>mergemaster</command> as usual. When done, reboot to - return to normal multi-user operations.</para> - - <para>After verifying that everything on the test machine is - working properly, use the same procedure to install the new - software on each of the other machines in the build set.</para> - - <para>The same methodology can be used for the ports tree. The - first step is to share <filename>/usr/ports</filename> via - <acronym>NFS</acronym> to all the machines in the build set. To - configure <filename>/etc/make.conf</filename> to share - distfiles, set <varname>DISTDIR</varname> to a common shared - directory that is writable by whichever user <systemitem - class="username">root</systemitem> is mapped to by the - <acronym>NFS</acronym> mount. Each machine should set - <varname>WRKDIRPREFIX</varname> to a local build directory, if - ports are to be built locally. Alternately, if the build system - is to build and distribute packages to the machines in the build - set, set <varname>PACKAGES</varname> on the build system to a - directory similar to <varname>DISTDIR</varname>.</para> - </sect1> -</chapter> |