aboutsummaryrefslogtreecommitdiff
path: root/zh_TW.UTF-8/books/handbook
diff options
context:
space:
mode:
authorLi-Wen Hsu <lwhsu@FreeBSD.org>2015-04-14 21:06:08 +0000
committerLi-Wen Hsu <lwhsu@FreeBSD.org>2015-04-14 21:06:08 +0000
commit5764da7bbfceab797f79cc134f13855a7bbe608e (patch)
tree4c20dfb55dffbbe58ad041c24723dcb111076695 /zh_TW.UTF-8/books/handbook
parentbbb438489b67fb551f4ee18ab3d0bf418e263b69 (diff)
downloaddoc-5764da7bbfceab797f79cc134f13855a7bbe608e.tar.gz
doc-5764da7bbfceab797f79cc134f13855a7bbe608e.zip
Traditional Chinese handbook update:
- Catch up the latest handbook architecture - Translate "cutting-edge" chapter PR: 193066, 193715, 193750 Differential Revision: https://reviews.freebsd.org/D2284 Submitted by: RayCherng Yu <raycherng@gmail.com> Reviewed by: delphij, wblock Approved by: delphij, wblock
Notes
Notes: svn path=/head/; revision=46538
Diffstat (limited to 'zh_TW.UTF-8/books/handbook')
-rw-r--r--zh_TW.UTF-8/books/handbook/Makefile93
-rw-r--r--zh_TW.UTF-8/books/handbook/basics/chapter.xml838
-rw-r--r--zh_TW.UTF-8/books/handbook/basics/disk-layout.kilbin0 -> 1450 bytes
-rw-r--r--zh_TW.UTF-8/books/handbook/book.xml52
-rw-r--r--zh_TW.UTF-8/books/handbook/bsdinstall/Makefile15
-rw-r--r--zh_TW.UTF-8/books/handbook/bsdinstall/chapter.xml2743
-rw-r--r--zh_TW.UTF-8/books/handbook/chapters.ent14
-rw-r--r--zh_TW.UTF-8/books/handbook/colophon.xml25
-rw-r--r--zh_TW.UTF-8/books/handbook/config/chapter.xml43
-rw-r--r--zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml3123
-rw-r--r--zh_TW.UTF-8/books/handbook/disks/chapter.xml4925
-rw-r--r--zh_TW.UTF-8/books/handbook/dtrace/Makefile15
-rw-r--r--zh_TW.UTF-8/books/handbook/dtrace/chapter.xml359
-rw-r--r--zh_TW.UTF-8/books/handbook/eresources/chapter.xml111
-rw-r--r--zh_TW.UTF-8/books/handbook/filesystems/Makefile15
-rw-r--r--zh_TW.UTF-8/books/handbook/filesystems/chapter.xml219
-rw-r--r--zh_TW.UTF-8/books/handbook/geom/chapter.xml920
-rw-r--r--zh_TW.UTF-8/books/handbook/install/chapter.xml486
-rw-r--r--zh_TW.UTF-8/books/handbook/jails/chapter.xml4
-rw-r--r--zh_TW.UTF-8/books/handbook/kernelconfig/chapter.xml4
-rw-r--r--zh_TW.UTF-8/books/handbook/mirrors/chapter.xml3658
-rw-r--r--zh_TW.UTF-8/books/handbook/network-servers/chapter.xml8326
-rw-r--r--zh_TW.UTF-8/books/handbook/ports/chapter.xml658
-rw-r--r--zh_TW.UTF-8/books/handbook/preface/preface.xml134
-rw-r--r--zh_TW.UTF-8/books/handbook/security/chapter.xml7209
-rw-r--r--zh_TW.UTF-8/books/handbook/serialcomms/chapter.xml2
-rw-r--r--zh_TW.UTF-8/books/handbook/zfs/chapter.xml4332
27 files changed, 22919 insertions, 15404 deletions
diff --git a/zh_TW.UTF-8/books/handbook/Makefile b/zh_TW.UTF-8/books/handbook/Makefile
index 6dee2d0433..99d75e5e6f 100644
--- a/zh_TW.UTF-8/books/handbook/Makefile
+++ b/zh_TW.UTF-8/books/handbook/Makefile
@@ -1,9 +1,18 @@
#
# $FreeBSD$
-# Original revision: 1.108
#
-# Build the FreeBSD Handbook.
+# Build the FreeBSD Handbook (Traditional Chinese).
#
+# Original revision: r46480
+#
+
+# ------------------------------------------------------------------------
+# To add a new chapter to the Handbook:
+#
+# - Update this Makefile, chapters.ent and book.xml
+# - Add a descriptive entry for the new chapter in preface/preface.xml
+#
+# ------------------------------------------------------------------------
.PATH: ${.CURDIR}/../../share/xml/glossary
@@ -20,7 +29,63 @@ IMAGES_EN = advanced-networking/isdn-bus.eps
IMAGES_EN+= advanced-networking/isdn-twisted-pair.eps
IMAGES_EN+= advanced-networking/natd.eps
IMAGES_EN+= advanced-networking/net-routing.pic
+IMAGES_EN+= advanced-networking/pxe-nfs.png
IMAGES_EN+= advanced-networking/static-routes.pic
+IMAGES_EN+= bsdinstall/bsdinstall-adduser1.png
+IMAGES_EN+= bsdinstall/bsdinstall-adduser2.png
+IMAGES_EN+= bsdinstall/bsdinstall-adduser3.png
+IMAGES_EN+= bsdinstall/bsdinstall-boot-loader-menu.png
+IMAGES_EN+= bsdinstall/bsdinstall-boot-options-menu.png
+IMAGES_EN+= bsdinstall/bsdinstall-newboot-loader-menu.png
+IMAGES_EN+= bsdinstall/bsdinstall-choose-mode.png
+IMAGES_EN+= bsdinstall/bsdinstall-config-components.png
+IMAGES_EN+= bsdinstall/bsdinstall-config-hostname.png
+IMAGES_EN+= bsdinstall/bsdinstall-config-keymap.png
+IMAGES_EN+= bsdinstall/bsdinstall-config-services.png
+IMAGES_EN+= bsdinstall/bsdinstall-config-crashdump.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv4-dhcp.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv4.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv4-static.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv6.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv6-static.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-slaac.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-network-ipv4-dns.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-wireless-accesspoints.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-wireless-scan.png
+IMAGES_EN+= bsdinstall/bsdinstall-configure-wireless-wpa2setup.png
+IMAGES_EN+= bsdinstall/bsdinstall-distfile-extracting.png
+IMAGES_EN+= bsdinstall/bsdinstall-distfile-fetching.png
+IMAGES_EN+= bsdinstall/bsdinstall-distfile-verifying.png
+IMAGES_EN+= bsdinstall/bsdinstall-final-confirmation.png
+IMAGES_EN+= bsdinstall/bsdinstall-finalconfiguration.png
+IMAGES_EN+= bsdinstall/bsdinstall-final-modification-shell.png
+IMAGES_EN+= bsdinstall/bsdinstall-keymap-10.png
+IMAGES_EN+= bsdinstall/bsdinstall-keymap-select-default.png
+IMAGES_EN+= bsdinstall/bsdinstall-mainexit.png
+IMAGES_EN+= bsdinstall/bsdinstall-netinstall-files.png
+IMAGES_EN+= bsdinstall/bsdinstall-netinstall-mirrorselect.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-entire-part.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-guided-disk.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-guided-manual.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-manual-addpart.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-manual-create.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-manual-partscheme.png
+IMAGES_EN+= bsdinstall/bsdinstall-part-review.png
+IMAGES_EN+= bsdinstall/bsdinstall-post-root-passwd.png
+IMAGES_EN+= bsdinstall/bsdinstall-set-clock-local-utc.png
+IMAGES_EN+= bsdinstall/bsdinstall-timezone-confirm.png
+IMAGES_EN+= bsdinstall/bsdinstall-timezone-country.png
+IMAGES_EN+= bsdinstall/bsdinstall-timezone-region.png
+IMAGES_EN+= bsdinstall/bsdinstall-timezone-zone.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-disk_info.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-disk_select.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-geli_password.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-menu.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-partmenu.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-vdev_invalid.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-vdev_type.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-warning.png
IMAGES_EN+= geom/striping.pic
IMAGES_EN+= install/adduser1.scr
IMAGES_EN+= install/adduser2.scr
@@ -28,6 +93,7 @@ IMAGES_EN+= install/adduser3.scr
IMAGES_EN+= install/boot-loader-menu.scr
IMAGES_EN+= install/boot-mgr.scr
IMAGES_EN+= install/config-country.scr
+IMAGES_EN+= install/config-keymap.scr
IMAGES_EN+= install/console-saver1.scr
IMAGES_EN+= install/console-saver2.scr
IMAGES_EN+= install/console-saver3.scr
@@ -104,13 +170,6 @@ IMAGES_EN+= security/ipsec-network.pic
IMAGES_EN+= security/ipsec-crypt-pkt.pic
IMAGES_EN+= security/ipsec-encap-pkt.pic
IMAGES_EN+= security/ipsec-out-pkt.pic
-IMAGES_EN+= vinum/vinum-concat.pic
-IMAGES_EN+= vinum/vinum-mirrored-vol.pic
-IMAGES_EN+= vinum/vinum-raid10-vol.pic
-IMAGES_EN+= vinum/vinum-raid5-org.pic
-IMAGES_EN+= vinum/vinum-simple-vol.pic
-IMAGES_EN+= vinum/vinum-striped-vol.pic
-IMAGES_EN+= vinum/vinum-striped.pic
IMAGES_EN+= virtualization/parallels-freebsd1.png
IMAGES_EN+= virtualization/parallels-freebsd2.png
IMAGES_EN+= virtualization/parallels-freebsd3.png
@@ -175,7 +234,9 @@ IMAGES_LIB+= callouts/15.png
# XML content
SRCS+= audit/chapter.xml
SRCS+= book.xml
+SRCS+= bsdinstall/chapter.xml
SRCS+= colophon.xml
+SRCS+= dtrace/chapter.xml
SRCS+= advanced-networking/chapter.xml
SRCS+= basics/chapter.xml
SRCS+= bibliography/chapter.xml
@@ -186,6 +247,8 @@ SRCS+= desktop/chapter.xml
SRCS+= disks/chapter.xml
SRCS+= eresources/chapter.xml
SRCS+= firewalls/chapter.xml
+SRCS+= zfs/chapter.xml
+SRCS+= filesystems/chapter.xml
SRCS+= geom/chapter.xml
SRCS+= install/chapter.xml
SRCS+= introduction/chapter.xml
@@ -205,8 +268,6 @@ SRCS+= preface/preface.xml
SRCS+= printing/chapter.xml
SRCS+= security/chapter.xml
SRCS+= serialcomms/chapter.xml
-SRCS+= users/chapter.xml
-SRCS+= vinum/chapter.xml
SRCS+= virtualization/chapter.xml
SRCS+= x11/chapter.xml
@@ -230,8 +291,6 @@ DOC_PREFIX?= ${.CURDIR}/../../..
XMLDOCS= lastmod:::mirrors.lastmod.inc \
mirrors-ftp-index:::mirrors.xml.ftp.index.inc \
mirrors-ftp:::mirrors.xml.ftp.inc \
- mirrors-cvsup-index:::mirrors.xml.cvsup.index.inc \
- mirrors-cvsup:::mirrors.xml.cvsup.inc \
eresources-index:::eresources.xml.www.index.inc \
eresources:::eresources.xml.www.inc
DEPENDSET.DEFAULT= transtable mirror
@@ -245,12 +304,6 @@ PARAMS.mirrors-ftp-index+= --param 'type' "'ftp'" \
PARAMS.mirrors-ftp+= --param 'type' "'ftp'" \
--param 'proto' "'ftp'" \
--param 'target' "'handbook/mirrors/chapter.xml'"
-PARAMS.mirrors-cvsup-index+= --param 'type' "'cvsup'" \
- --param 'proto' "'cvsup'" \
- --param 'target' "'index'"
-PARAMS.mirrors-cvsup+= --param 'type' "'cvsup'" \
- --param 'proto' "'cvsup'" \
- --param 'target' "'handbook/mirrors/chapter.xml'"
PARAMS.eresources-index+= --param 'type' "'www'" \
--param 'proto' "'http'" \
--param 'target' "'index'"
@@ -261,8 +314,6 @@ PARAMS.eresources+= --param 'type' "'www'" \
SRCS+= mirrors.lastmod.inc \
mirrors.xml.ftp.inc \
mirrors.xml.ftp.index.inc \
- mirrors.xml.cvsup.inc \
- mirrors.xml.cvsup.index.inc \
eresources.xml.www.inc \
eresources.xml.www.index.inc
diff --git a/zh_TW.UTF-8/books/handbook/basics/chapter.xml b/zh_TW.UTF-8/books/handbook/basics/chapter.xml
index 3ddf7df0aa..5c8d788ee7 100644
--- a/zh_TW.UTF-8/books/handbook/basics/chapter.xml
+++ b/zh_TW.UTF-8/books/handbook/basics/chapter.xml
@@ -1,19 +1,26 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The FreeBSD Documentation Project
+ The FreeBSD Traditional Chinese Project
$FreeBSD$
- Original revision: 1.152
+ Original revision: r46052
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="basics">
- <info><title>UNIX 基礎概念</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="basics">
+ <!--
+ <chapterinfo>
<authorgroup>
- <author><personname><firstname>Chris</firstname><surname>Shumway</surname></personname><contrib>Rewritten by </contrib></author>
+ <author>
+ <firstname>Chris</firstname>
+ <surname>Shumway</surname>
+ <contrib>Rewritten by in Mar 2000</contrib>
+ </author>
</authorgroup>
-
- </info>
-
-
+ </chapterinfo>
+ -->
+ <title>UNIX 基礎概念</title>
<sect1 xml:id="basics-synopsis">
<title>概述</title>
@@ -29,44 +36,61 @@
<listitem>
<para>如何使用 FreeBSD 的<quote>virtual consoles</quote>。</para>
</listitem>
+
<listitem>
<para>&unix; 檔案權限運作的方式以及 &os; 中檔案的 flags。</para>
</listitem>
+
<listitem>
<para>預設的 &os; 檔案系統配置。</para>
</listitem>
+
<listitem>
<para>&os; 的磁碟結構。</para>
</listitem>
+
<listitem>
<para>如何掛載(mount)、卸載(umount)檔案系統</para>
</listitem>
+
<listitem>
<para>什麼是processes、daemons 以及 signals 。</para>
</listitem>
+
<listitem>
<para>什麼是 shell ,以及如何變更您預設的登入環境。</para>
</listitem>
+
<listitem>
<para>如何使用基本的文字編輯器。</para>
</listitem>
+
<listitem>
<para>什麼是 devices 和 device nodes 。</para>
</listitem>
+
<listitem>
<para>&os; 下使用的 binary 格式。</para>
</listitem>
+
<listitem>
<para>如何閱讀 manual pages 以獲得更多的資訊。</para>
</listitem>
</itemizedlist>
-
</sect1>
<sect1 xml:id="consoles">
<title>Virtual Consoles 和終端機</title>
- <indexterm><primary>virtual consoles</primary></indexterm>
- <indexterm><primary>terminals</primary></indexterm>
+
+ <indexterm>
+ <primary>virtual consoles</primary>
+ </indexterm>
+ <indexterm>
+ <primary>terminals</primary>
+ </indexterm>
+ <indexterm>
+ <primary>console</primary>
+ </indexterm>
<para>有很多方法可以操作 FreeBSD ,其中一種就是在文字終端機上打字。
如此使用 FreeBSD 即可輕易的體會到 &unix; 作業系統的威力和彈性。
@@ -279,6 +303,798 @@ options SC_PIXEL_MODE</programlisting>
</sect2>
</sect1>
+ <sect1 xml:id="users-synopsis">
+ <title>Users and Basic Account Management</title>
+
+ <para>&os; allows multiple users to use the computer at the same
+ time. While only one user can sit in front of the screen and
+ use the keyboard at any one time, any number of users can log
+ in to the system through the network. To use the system, each
+ user should have their own user account.</para>
+
+ <para>This chapter describes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The different types of user accounts on a
+ &os; system.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to add, remove, and modify user accounts.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to set limits to control the
+ resources that users and
+ groups are allowed to access.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to create groups and add users as members of a
+ group.</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2 xml:id="users-introduction">
+ <title>Account Types</title>
+
+ <para>Since all access to the &os; system is achieved using
+ accounts and all processes are run by users, user and account
+ management is important.</para>
+
+ <para>There are three main types of accounts: system accounts,
+ user accounts, and the superuser account.</para>
+
+ <sect3 xml:id="users-system">
+ <title>System Accounts</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>system</secondary>
+ </indexterm>
+
+ <para>System accounts are used to run services such as DNS,
+ mail, and web servers. The reason for this is security; if
+ all services ran as the superuser, they could act without
+ restriction.</para>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary><systemitem
+ class="username">daemon</systemitem></secondary>
+ </indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary><systemitem
+ class="username">operator</systemitem></secondary>
+ </indexterm>
+
+ <para>Examples of system accounts are
+ <systemitem class="username">daemon</systemitem>,
+ <systemitem class="username">operator</systemitem>,
+ <systemitem class="username">bind</systemitem>,
+ <systemitem class="username">news</systemitem>, and
+ <systemitem class="username">www</systemitem>.</para>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary><systemitem
+ class="username">nobody</systemitem></secondary>
+ </indexterm>
+
+ <para><systemitem class="username">nobody</systemitem> is the
+ generic unprivileged system account. However, the more
+ services that use
+ <systemitem class="username">nobody</systemitem>, the more
+ files and processes that user will become associated with,
+ and hence the more privileged that user becomes.</para>
+ </sect3>
+
+ <sect3 xml:id="users-user">
+ <title>User Accounts</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>user</secondary>
+ </indexterm>
+
+ <para>User accounts are assigned to real people and are used
+ to log in and use the system. Every person accessing the
+ system should have a unique user account. This allows the
+ administrator to find out who is doing what and prevents
+ users from clobbering the settings of other users.</para>
+
+ <para>Each user can set up their own environment to
+ accommodate their use of the system, by configuring their
+ default shell, editor, key bindings, and language
+ settings.</para>
+
+ <para>Every user account on a &os; system has certain
+ information associated with it:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>User name</term>
+
+ <listitem>
+ <para>The user name is typed at the
+ <prompt>login:</prompt> prompt. Each user must have
+ a unique user name. There are a number of rules for
+ creating valid user names which are documented in
+ &man.passwd.5;. It is recommended to use user names
+ that consist of eight or fewer, all lower case
+ characters in order to maintain backwards
+ compatibility with applications.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Password</term>
+
+ <listitem>
+ <para>Each account has an associated password.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User ID (<acronym>UID</acronym>)</term>
+
+ <listitem>
+ <para>The User ID (<acronym>UID</acronym>) is a number
+ used to uniquely identify the user to the &os; system.
+ Commands that allow a user name to be specified will
+ first convert it to the <acronym>UID</acronym>. It is
+ recommended to use a UID less than 65535, since higher
+ values may cause compatibility issues with some
+ software.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Group ID (<acronym>GID</acronym>)</term>
+
+ <listitem>
+ <para>The Group ID (<acronym>GID</acronym>) is a number
+ used to uniquely identify the primary group that the
+ user belongs to. Groups are a mechanism for
+ controlling access to resources based on a user's
+ <acronym>GID</acronym> rather than their
+ <acronym>UID</acronym>. This can significantly reduce
+ the size of some configuration files and allows users
+ to be members of more than one group. It is
+ recommended to use a GID of 65535 or lower as higher
+ GIDs may break some software.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Login class</term>
+
+ <listitem>
+ <para>Login classes are an extension to the group
+ mechanism that provide additional flexibility when
+ tailoring the system to different users. Login
+ classes are discussed further in
+ <xref linkend="users-limiting"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Password change time</term>
+
+ <listitem>
+ <para>By default, passwords do not expire. However,
+ password expiration can be enabled on a per-user
+ basis, forcing some or all users to change their
+ passwords after a certain amount of time has
+ elapsed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Account expiry time</term>
+
+ <listitem>
+ <para>By default, &os; does not expire accounts. When
+ creating accounts that need a limited lifespan, such
+ as student accounts in a school, specify the account
+ expiry date using &man.pw.8;. After the expiry time
+ has elapsed, the account cannot be used to log in to
+ the system, although the account's directories and
+ files will remain.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User's full name</term>
+
+ <listitem>
+ <para>The user name uniquely identifies the account to
+ &os;, but does not necessarily reflect the user's real
+ name. Similar to a comment, this information can
+ contain spaces, uppercase characters, and be more
+ than 8 characters long.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Home directory</term>
+
+ <listitem>
+ <para>The home directory is the full path to a directory
+ on the system. This is the user's starting directory
+ when the user logs in. A common convention is to put
+ all user home directories under <filename
+ class="directory"><replaceable>/home/username</replaceable></filename>
+ or <filename
+ class="directory"><replaceable>/usr/home/username</replaceable></filename>.
+ Each user stores their personal files and
+ subdirectories in their own home directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User shell</term>
+
+ <listitem>
+ <para>The shell provides the user's default environment
+ for interacting with the system. There are many
+ different kinds of shells and experienced users will
+ have their own preferences, which can be reflected in
+ their account settings.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 xml:id="users-superuser">
+ <title>The Superuser Account</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>superuser (root)</secondary>
+ </indexterm>
+
+ <para>The superuser account, usually called
+ <systemitem class="username">root</systemitem>, is used to
+ manage the system with no limitations on privileges. For
+ this reason, it should not be used for day-to-day tasks like
+ sending and receiving mail, general exploration of the
+ system, or programming.</para>
+
+ <para>The superuser, unlike other user accounts, can operate
+ without limits, and misuse of the superuser account may
+ result in spectacular disasters. User accounts are unable
+ to destroy the operating system by mistake, so it is
+ recommended to login as a user account and to only become
+ the superuser when a command requires extra
+ privilege.</para>
+
+ <para>Always double and triple-check any commands issued as
+ the superuser, since an extra space or missing character can
+ mean irreparable data loss.</para>
+
+ <para>There are several ways to gain superuser privilege.
+ While one can log in as
+ <systemitem class="username">root</systemitem>, this is
+ highly discouraged.</para>
+
+ <para>Instead, use &man.su.1; to become the superuser. If
+ <literal>-</literal> is specified when running this command,
+ the user will also inherit the root user's environment. The
+ user running this command must be in the
+ <systemitem class="groupname">wheel</systemitem> group or
+ else the command will fail. The user must also know the
+ password for the
+ <systemitem class="username">root</systemitem> user
+ account.</para>
+
+ <para>In this example, the user only becomes superuser in
+ order to run <command>make install</command> as this step
+ requires superuser privilege. Once the command completes,
+ the user types <command>exit</command> to leave the
+ superuser account and return to the privilege of their user
+ account.</para>
+
+ <example>
+ <title>Install a Program As the Superuser</title>
+
+ <screen>&prompt.user; <userinput>configure</userinput>
+&prompt.user; <userinput>make</userinput>
+&prompt.user; <userinput>su -</userinput>
+Password:
+&prompt.root; <userinput>make install</userinput>
+&prompt.root; <userinput>exit</userinput>
+&prompt.user;</screen>
+ </example>
+
+ <para>The built-in &man.su.1; framework works well for single
+ systems or small networks with just one system
+ administrator. An alternative is to install the
+ <package>security/sudo</package> package or port. This
+ software provides activity logging and allows the
+ administrator to configure which users can run which
+ commands as the superuser.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="users-modifying">
+ <title>Managing Accounts</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>modifying</secondary>
+ </indexterm>
+
+ <para>&os; provides a variety of different commands to manage
+ user accounts. The most common commands are summarized in
+ <xref linkend="users-modifying-utilities"/>, followed by some
+ examples of their usage. See the manual page for each utility
+ for more details and usage examples.</para>
+
+ <table frame="none" pgwide="1"
+ xml:id="users-modifying-utilities">
+ <title>Utilities for Managing User Accounts</title>
+
+ <tgroup cols="2">
+ <colspec colwidth="1*"/>
+ <colspec colwidth="2*"/>
+
+ <thead>
+ <row>
+ <entry>Command</entry>
+ <entry>Summary</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>&man.adduser.8;</entry>
+ <entry>The recommended command-line application for
+ adding new users.</entry>
+ </row>
+
+ <row>
+ <entry>&man.rmuser.8;</entry>
+ <entry>The recommended command-line application for
+ removing users.</entry>
+ </row>
+
+ <row>
+ <entry>&man.chpass.1;</entry>
+ <entry>A flexible tool for changing user database
+ information.</entry>
+ </row>
+
+ <row>
+ <entry>&man.passwd.1;</entry>
+ <entry>The command-line tool to change user
+ passwords.</entry>
+ </row>
+
+ <row>
+ <entry>&man.pw.8;</entry>
+ <entry>A powerful and flexible tool for modifying all
+ aspects of user accounts.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect3 xml:id="users-adduser">
+ <title><command>adduser</command></title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>adding</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><command>adduser</command></primary>
+ </indexterm>
+ <indexterm>
+ <primary><filename>/usr/share/skel</filename></primary>
+ </indexterm>
+ <indexterm>
+ <primary>skeleton directory</primary>
+ </indexterm>
+
+ <para>The recommended program for adding new users is
+ &man.adduser.8;. When a new user is added, this program
+ automatically updates <filename>/etc/passwd</filename> and
+ <filename>/etc/group</filename>. It also creates a home
+ directory for the new user, copies in the default
+ configuration files from
+ <filename>/usr/share/skel</filename>, and can optionally
+ mail the new user a welcome message. This utility must be
+ run as the superuser.</para>
+
+ <para>The &man.adduser.8; utility is interactive and walks
+ through the steps for creating a new user account. As seen
+ in <xref linkend="users-modifying-adduser"/>, either input
+ the required information or press <keycap>Return</keycap>
+ to accept the default value shown in square brackets.
+ In this example, the user has been invited into the
+ <systemitem class="groupname">wheel</systemitem> group,
+ allowing them to become the superuser with &man.su.1;.
+ When finished, the utility will prompt to either
+ create another user or to exit.</para>
+
+ <example xml:id="users-modifying-adduser">
+ <title>Adding a User on &os;</title>
+
+ <screen>&prompt.root; <userinput>adduser</userinput>
+Username: <userinput>jru</userinput>
+Full name: <userinput>J. Random User</userinput>
+Uid (Leave empty for default):
+Login group [jru]:
+Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput>
+Login class [default]:
+Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput>
+Home directory [/home/jru]:
+Home directory permissions (Leave empty for default):
+Use password-based authentication? [yes]:
+Use an empty password? (yes/no) [no]:
+Use a random password? (yes/no) [no]:
+Enter password:
+Enter password again:
+Lock out the account after creation? [no]:
+Username : jru
+Password : ****
+Full Name : J. Random User
+Uid : 1001
+Class :
+Groups : jru wheel
+Home : /home/jru
+Shell : /usr/local/bin/zsh
+Locked : no
+OK? (yes/no): <userinput>yes</userinput>
+adduser: INFO: Successfully added (jru) to the user database.
+Add another user? (yes/no): <userinput>no</userinput>
+Goodbye!
+&prompt.root;</screen>
+ </example>
+
+ <note>
+ <para>Since the password is not echoed when typed, be
+ careful to not mistype the password when creating the user
+ account.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="users-rmuser">
+ <title><command>rmuser</command></title>
+
+ <indexterm>
+ <primary><command>rmuser</command></primary>
+ </indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>removing</secondary>
+ </indexterm>
+
+ <para>To completely remove a user from the system, run
+ &man.rmuser.8; as the superuser. This command performs the
+ following steps:</para>
+
+ <procedure>
+ <step>
+ <para>Removes the user's &man.crontab.1; entry, if one
+ exists.</para>
+ </step>
+
+ <step>
+ <para>Removes any &man.at.1; jobs belonging to the
+ user.</para>
+ </step>
+
+ <step>
+ <para>Kills all processes owned by the user.</para>
+ </step>
+
+ <step>
+ <para>Removes the user from the system's local password
+ file.</para>
+ </step>
+
+ <step>
+ <para>Optionally removes the user's home directory, if it
+ is owned by the user.</para>
+ </step>
+
+ <step>
+ <para>Removes the incoming mail files belonging to the
+ user from <filename>/var/mail</filename>.</para>
+ </step>
+
+ <step>
+ <para>Removes all files owned by the user from temporary
+ file storage areas such as
+ <filename>/tmp</filename>.</para>
+ </step>
+
+ <step>
+ <para>Finally, removes the username from all groups to
+ which it belongs in <filename>/etc/group</filename>. If
+ a group becomes empty and the group name is the same as
+ the username, the group is removed. This complements
+ the per-user unique groups created by
+ &man.adduser.8;.</para>
+ </step>
+ </procedure>
+
+ <para>&man.rmuser.8; cannot be used to remove superuser
+ accounts since that is almost always an indication of
+ massive destruction.</para>
+
+ <para>By default, an interactive mode is used, as shown
+ in the following example.</para>
+
+ <example>
+ <title><command>rmuser</command> Interactive Account
+ Removal</title>
+
+ <screen>&prompt.root; <userinput>rmuser jru</userinput>
+Matching password entry:
+jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
+Is this the entry you wish to remove? <userinput>y</userinput>
+Remove user's home directory (/home/jru)? <userinput>y</userinput>
+Removing user (jru): mailspool home passwd.
+&prompt.root;</screen>
+ </example>
+ </sect3>
+
+ <sect3 xml:id="users-chpass">
+ <title><command>chpass</command></title>
+
+ <indexterm>
+ <primary><command>chpass</command></primary>
+ </indexterm>
+
+ <para>Any user can use &man.chpass.1; to change their default
+ shell and personal information associated with their user
+ account. The superuser can use this utility to change
+ additional account information for any user.</para>
+
+ <para>When passed no options, aside from an optional username,
+ &man.chpass.1; displays an editor containing user
+ information. When the user exits from the editor, the user
+ database is updated with the new information.</para>
+
+ <note>
+ <para>This utility will prompt for the user's password when
+ exiting the editor, unless the utility is run as the
+ superuser.</para>
+ </note>
+
+ <para>In <xref linkend="users-modifying-chpass-su"/>, the
+ superuser has typed <command>chpass jru</command> and is
+ now viewing the fields that can be changed for this user.
+ If <systemitem class="username">jru</systemitem> runs this
+ command instead, only the last six fields will be displayed
+ and available for editing. This is shown in
+ <xref linkend="users-modifying-chpass-ru"/>.</para>
+
+ <example xml:id="users-modifying-chpass-su">
+ <title>Using <command>chpass</command> as
+ Superuser</title>
+
+ <screen>#Changing user database information for jru.
+Login: jru
+Password: *
+Uid [#]: 1001
+Gid [# or name]: 1001
+Change [month day year]:
+Expire [month day year]:
+Class:
+Home directory: /home/jru
+Shell: /usr/local/bin/zsh
+Full Name: J. Random User
+Office Location:
+Office Phone:
+Home Phone:
+Other information:</screen>
+ </example>
+
+ <example xml:id="users-modifying-chpass-ru">
+ <title>Using <command>chpass</command> as Regular
+ User</title>
+
+ <screen>#Changing user database information for jru.
+Shell: /usr/local/bin/zsh
+Full Name: J. Random User
+Office Location:
+Office Phone:
+Home Phone:
+Other information:</screen>
+ </example>
+
+ <note>
+ <para>The commands &man.chfn.1; and &man.chsh.1; are links
+ to &man.chpass.1;, as are &man.ypchpass.1;,
+ &man.ypchfn.1;, and &man.ypchsh.1;. Since
+ <acronym>NIS</acronym> support is automatic, specifying
+ the <literal>yp</literal> before the command is not
+ necessary. How to configure NIS is covered in <xref
+ linkend="network-servers"/>.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="users-passwd">
+ <title><command>passwd</command></title>
+
+ <indexterm>
+ <primary><command>passwd</command></primary>
+ </indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>changing password</secondary>
+ </indexterm>
+
+ <para>Any user can easily change their password using
+ &man.passwd.1;. To prevent accidental or unauthorized
+ changes, this command will prompt for the user's original
+ password before a new password can be set:</para>
+
+ <example>
+ <title>Changing Your Password</title>
+
+ <screen>&prompt.user; <userinput>passwd</userinput>
+Changing local password for jru.
+Old password:
+New password:
+Retype new password:
+passwd: updating the database...
+passwd: done</screen>
+ </example>
+
+ <para>The superuser can change any user's password by
+ specifying the username when running &man.passwd.1;. When
+ this utility is run as the superuser, it will not prompt for
+ the user's current password. This allows the password to be
+ changed when a user cannot remember the original
+ password.</para>
+
+ <example>
+ <title>Changing Another User's Password as the
+ Superuser</title>
+
+ <screen>&prompt.root; <userinput>passwd jru</userinput>
+Changing local password for jru.
+New password:
+Retype new password:
+passwd: updating the database...
+passwd: done</screen>
+ </example>
+
+ <note>
+ <para>As with &man.chpass.1;, &man.yppasswd.1; is a link to
+ &man.passwd.1;, so <acronym>NIS</acronym> works with
+ either command.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="users-pw">
+ <title><command>pw</command></title>
+
+ <indexterm>
+ <primary><command>pw</command></primary>
+ </indexterm>
+
+ <para>The &man.pw.8; utility can create, remove,
+ modify, and display users and groups. It functions as a
+ front end to the system user and group files. &man.pw.8;
+ has a very powerful set of command line options that make it
+ suitable for use in shell scripts, but new users may find it
+ more complicated than the other commands presented in this
+ section.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="users-groups">
+ <title>Managing Groups</title>
+
+ <indexterm>
+ <primary>groups</primary>
+ </indexterm>
+ <indexterm>
+ <primary><filename>/etc/groups</filename></primary>
+ </indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>groups</secondary>
+ </indexterm>
+
+ <para>A group is a list of users. A group is identified by its
+ group name and <acronym>GID</acronym>. In &os;, the kernel
+ uses the <acronym>UID</acronym> of a process, and the list of
+ groups it belongs to, to determine what the process is allowed
+ to do. Most of the time, the <acronym>GID</acronym> of a user
+ or process usually means the first group in the list.</para>
+
+ <para>The group name to <acronym>GID</acronym> mapping is listed
+ in <filename>/etc/group</filename>. This is a plain text file
+ with four colon-delimited fields. The first field is the
+ group name, the second is the encrypted password, the third
+ the <acronym>GID</acronym>, and the fourth the comma-delimited
+ list of members. For a more complete description of the
+ syntax, refer to &man.group.5;.</para>
+
+ <para>The superuser can modify <filename>/etc/group</filename>
+ using a text editor. Alternatively, &man.pw.8; can be used to
+ add and edit groups. For example, to add a group called
+ <systemitem class="groupname">teamtwo</systemitem> and then
+ confirm that it exists:</para>
+
+ <example>
+ <title>Adding a Group Using &man.pw.8;</title>
+
+ <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:</screen>
+ </example>
+
+ <para>In this example, <literal>1100</literal> is the
+ <acronym>GID</acronym> of
+ <systemitem class="groupname">teamtwo</systemitem>. Right
+ now, <systemitem class="groupname">teamtwo</systemitem> has no
+ members. This command will add
+ <systemitem class="username">jru</systemitem> as a member of
+ <systemitem class="groupname">teamtwo</systemitem>.</para>
+
+ <example>
+ <title>Adding User Accounts to a New Group Using
+ &man.pw.8;</title>
+
+ <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:jru</screen>
+ </example>
+
+ <para>The argument to <option>-M</option> is a comma-delimited
+ list of users to be added to a new (empty) group or to replace
+ the members of an existing group. To the user, this group
+ membership is different from (and in addition to) the user's
+ primary group listed in the password file. This means that
+ the user will not show up as a member when using
+ <option>groupshow</option> with &man.pw.8;, but will show up
+ when the information is queried via &man.id.1; or a similar
+ tool. When &man.pw.8; is used to add a user to a group, it
+ only manipulates <filename>/etc/group</filename> and does not
+ attempt to read additional data from
+ <filename>/etc/passwd</filename>.</para>
+
+ <example>
+ <title>Adding a New Member to a Group Using &man.pw.8;</title>
+
+ <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:jru,db</screen>
+ </example>
+
+ <para>In this example, the argument to <option>-m</option> is a
+ comma-delimited list of users who are to be added to the
+ group. Unlike the previous example, these users are appended
+ to the group and do not replace existing users in the
+ group.</para>
+
+ <example>
+ <title>Using &man.id.1; to Determine Group Membership</title>
+
+ <screen>&prompt.user; <userinput>id jru</userinput>
+uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen>
+ </example>
+
+ <para>In this example,
+ <systemitem class="username">jru</systemitem> is a member of
+ the groups <systemitem class="groupname">jru</systemitem> and
+ <systemitem class="groupname">teamtwo</systemitem>.</para>
+
+ <para>For more information about this command and the format of
+ <filename>/etc/group</filename>, refer to &man.pw.8; and
+ &man.group.5;.</para>
+ </sect2>
+ </sect1>
+
<sect1 xml:id="permissions">
<title>權限</title>
<indexterm><primary>UNIX</primary></indexterm>
diff --git a/zh_TW.UTF-8/books/handbook/basics/disk-layout.kil b/zh_TW.UTF-8/books/handbook/basics/disk-layout.kil
new file mode 100644
index 0000000000..85820c2878
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/basics/disk-layout.kil
Binary files differ
diff --git a/zh_TW.UTF-8/books/handbook/book.xml b/zh_TW.UTF-8/books/handbook/book.xml
index b6fa191bcf..bc2e056417 100644
--- a/zh_TW.UTF-8/books/handbook/book.xml
+++ b/zh_TW.UTF-8/books/handbook/book.xml
@@ -1,24 +1,32 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
+<!--
+ The FreeBSD Documentation Project
+ The FreeBSD Traditional Chinese Documentation Project
+
+ Original revision: r45698
+ $FreeBSD$
+-->
+
<!ENTITY % chapters SYSTEM "chapters.ent">
%chapters;
<!ENTITY % txtfiles SYSTEM "txtfiles.ent">
%txtfiles;
]>
-<!--
- The FreeBSD Documentation Project
- $FreeBSD$
- Original revision: 1.163
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW">
- <info><title>FreeBSD 使用手冊</title>
-
+<book xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="zh_tw">
+
+ <info>
+ <title>FreeBSD 使用手冊</title>
- <author><orgname>FreeBSD 文件計畫</orgname></author>
+ <author>
+ <orgname>FreeBSD 文件計畫</orgname>
+ </author>
- <pubdate>February 1999</pubdate>
+ <pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
@@ -37,6 +45,12 @@
<year>2006</year>
<year>2007</year>
<year>2008</year>
+ <year>2009</year>
+ <year>2010</year>
+ <year>2011</year>
+ <year>2012</year>
+ <year>2013</year>
+ <year>2014</year>
<holder>FreeBSD 文件計畫</holder>
</copyright>
@@ -50,9 +64,8 @@
&tm-attrib.adaptec;
&tm-attrib.adobe;
&tm-attrib.apple;
- &tm-attrib.corel;
&tm-attrib.creative;
- &tm-attrib.cvsup;
+ &tm-attrib.google;
&tm-attrib.heidelberger;
&tm-attrib.ibm;
&tm-attrib.ieee;
@@ -60,19 +73,12 @@
&tm-attrib.intuit;
&tm-attrib.linux;
&tm-attrib.lsilogic;
- &tm-attrib.m-systems;
- &tm-attrib.macromedia;
&tm-attrib.microsoft;
- &tm-attrib.netscape;
- &tm-attrib.nexthop;
&tm-attrib.opengroup;
&tm-attrib.oracle;
- &tm-attrib.powerquest;
&tm-attrib.realnetworks;
&tm-attrib.redhat;
- &tm-attrib.sap;
&tm-attrib.sun;
- &tm-attrib.symantec;
&tm-attrib.themathworks;
&tm-attrib.thomson;
&tm-attrib.usrobotics;
@@ -86,6 +92,7 @@
<abstract>
<para>歡迎使用FreeBSD! 本使用手冊涵蓋範圍包括了
+ <emphasis>FreeBSD &rel3.current;-RELEASE</emphasis>、
<emphasis>FreeBSD &rel2.current;-RELEASE</emphasis> 和
<emphasis>FreeBSD &rel.current;-RELEASE</emphasis> 的安裝和日常使用。
這份使用手冊是很多人的集體創作,而且仍然『持續不斷』的進行中。
@@ -140,6 +147,7 @@
</partintro>
&chap.introduction;
+ &chap.bsdinstall;
&chap.install;
&chap.basics;
&chap.ports;
@@ -177,7 +185,6 @@
</itemizedlist>
<para>這些章節中有些需要您預先閱讀些相關文件,在各章節開頭的概要內會提及。</para>
-
</partintro>
&chap.desktop;
@@ -202,17 +209,18 @@
&chap.config;
&chap.boot;
- &chap.users;
&chap.security;
&chap.jails;
&chap.mac;
&chap.audit;
&chap.disks;
&chap.geom;
- &chap.vinum;
+ &chap.zfs;
+ &chap.filesystems;
&chap.virtualization;
&chap.l10n;
&chap.cutting-edge;
+ &chap.dtrace;
</part>
<part xml:id="network-communication">
diff --git a/zh_TW.UTF-8/books/handbook/bsdinstall/Makefile b/zh_TW.UTF-8/books/handbook/bsdinstall/Makefile
new file mode 100644
index 0000000000..0ad1b83553
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/bsdinstall/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= bsdinstall/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/zh_TW.UTF-8/books/handbook/bsdinstall/chapter.xml b/zh_TW.UTF-8/books/handbook/bsdinstall/chapter.xml
new file mode 100644
index 0000000000..6c81ead5c9
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/bsdinstall/chapter.xml
@@ -0,0 +1,2743 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ 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="bsdinstall">
+
+ <info>
+ <title>Installing &os;&nbsp;9.<replaceable>X</replaceable> and
+ Later</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Jim</firstname>
+ <surname>Mock</surname>
+ </personname>
+
+ <contrib>Restructured, reorganized, and parts rewritten
+ by </contrib>
+ </author>
+ </authorgroup>
+<!---
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Randy</firstname>
+ <surname>Pratt</surname>
+ </personname>
+ <contrib>The sysinstall walkthrough, screenshots, and general
+ copy by </contrib>
+ </author>
+ </authorgroup>-->
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Gavin</firstname>
+ <surname>Atkinson</surname>
+ </personname>
+
+ <contrib>Updated for bsdinstall by </contrib>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Warren</firstname>
+ <surname>Block</surname>
+ </personname>
+ </author>
+ </authorgroup>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Allan</firstname>
+ <surname>Jude</surname>
+ </personname>
+
+ <contrib>Updated for root-on-ZFS by </contrib>
+ </author>
+ </authorgroup>
+ </info>
+
+ <sect1 xml:id="bsdinstall-synopsis">
+ <title>Synopsis</title>
+
+ <indexterm><primary>installation</primary></indexterm>
+
+ <para>Beginning with &os;&nbsp;9.0-RELEASE, &os; provides an easy
+ to use, text-based installation
+ program named <application>bsdinstall</application>. This
+ chapter describes how to install &os; using
+ <application>bsdinstall</application>. The use of
+ <application>sysinstall</application>, which is the installation
+ program used by &os;&nbsp;8.x, is covered in <xref
+ linkend="install"/>.</para>
+
+ <para>In general, the installation instructions in this chapter
+ are written for the &i386; and <acronym>AMD64</acronym>
+ architectures. Where applicable, instructions specific to other
+ platforms will be listed. There may be minor differences
+ between the installer and what is shown here, so use this
+ chapter as a general guide rather than as a set of literal
+ instructions.</para>
+
+ <note>
+ <para>Users who prefer to install &os; using a graphical
+ installer may be interested in
+ <application>pc-sysinstall</application>, the installer used
+ by the PC-BSD Project. It can be used to install either a
+ graphical desktop (PC-BSD) or a command line version of &os;.
+ Refer to the PC-BSD Users Handbook for details (<link
+ xlink:href="http://wiki.pcbsd.org/index.php/PC-BSD%C2%AE_Users_Handbook/10.1">http://wiki.pcbsd.org/index.php/PC-BSD%C2%AE_Users_Handbook/10.1</link>).</para>
+ </note>
+
+ <para>After reading this chapter, you will know:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The minimum hardware requirements and &os; supported
+ architectures.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to create the &os; installation media.</para>
+ </listitem>
+
+<!-- WB: verify this, including GPT partition notation (ada0p2)
+ <listitem>
+ <para>How &os; subdivides and refers to hard disks.</para>
+ </listitem> -->
+
+ <listitem>
+ <para>How to start
+ <application>bsdinstall</application>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The questions <application>bsdinstall</application> will
+ ask, what they mean, and how to answer them.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to troubleshoot a failed installation.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to access a live version of &os; before committing
+ to an installation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Before reading this chapter, you should:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Read the supported hardware list that shipped with the
+ version of &os; to be installed and verify that the system's
+ hardware is supported.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-hardware">
+ <title>Minimum Hardware Requirements</title>
+
+ <para>The hardware requirements to install &os; vary by the &os;
+ version and the hardware architecture. Hardware architectures
+ and devices supported by a &os; release are listed in the
+ Hardware Notes file. Usually named
+ <filename>HARDWARE.TXT</filename>, the file is located in the
+ root directory of the release media. Copies of the supported
+ hardware list are also available on the Release Information page
+ of the &os; web site (<link
+ xlink:href="&url.base;/releases/index.html">http://www.FreeBSD.org/releases/index.html</link>).</para>
+
+ <para>A &os; installation will require at least 64&nbsp;MB of
+ <acronym>RAM</acronym> and 1.5&nbsp;GB of free hard drive space
+ for the most minimal installation. However, that is a
+ <emphasis>very</emphasis> minimal install, leaving almost no
+ free space. A more realistic minimum is 4&nbsp;GB without a
+ graphical environment, and 8&nbsp;GB or more if a graphical user
+ interface will be used. Third-party application software
+ requires more space. It is recommended to increase
+ <acronym>RAM</acronym> and hard drive space to meet the needs of
+ the applications that will be used and the amount of data that
+ will be stored.</para>
+
+ <para>The processor requirements for each architecture can be
+ summarized as follows:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>&arch.amd64;</term>
+ <listitem>
+ <para>There are two classes of processors capable of running
+ &arch.amd64;. The first are <acronym>AMD64</acronym>
+ processors, including the &amd.athlon;64 and &amd.opteron;
+ processors.</para>
+
+ <para>The second class of processors includes those using
+ the &intel;&nbsp;EM64T architecture. Examples of these
+ processors include all multi-core &intel;&nbsp;&xeon;
+ processors except Sossaman, the single-core
+ &intel;&nbsp;&xeon; processors Nocona, Irwindale, Potomac,
+ and Cranford, the &intel;&nbsp;&core;&nbsp;2 (not Core
+ Duo) and later processors, all &intel;&nbsp;&pentium; D
+ processors, the &intel;&nbsp;&pentium; 4s and Celeron Ds
+ using the Cedar Mill core, and some &intel;&nbsp;&pentium;
+ 4s and Celeron Ds using the Prescott core.</para>
+
+ <para>Both Uniprocessor (<acronym>UP</acronym>) and
+ Symmetric Multi-processor (<acronym>SMP</acronym>)
+ configurations are supported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>&arch.i386;</term>
+ <listitem>
+ <para>Almost all i386-compatible processors with a floating
+ point unit are supported. All &intel; processors 486 or
+ higher are supported.</para>
+
+ <para>&os; will take advantage of Physical Address
+ Extensions (<acronym>PAE</acronym>) support on
+ <acronym>CPU</acronym>s that support this feature. A
+ kernel with the <acronym>PAE</acronym> feature enabled
+ will detect memory above 4&nbsp;GB and allow it to be used
+ by the system. This feature places constraints on the
+ device drivers and other features of &os; which may be
+ used; refer to &man.pae.4; for details.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ia64</term>
+ <listitem>
+ <para>Currently supported processors are the &itanium; and
+ the &itanium; 2. Supported chipsets include the HP zx1,
+ &intel; 460GX, and &intel; E8870. Both Uniprocessor
+ (<acronym>UP</acronym>) and Symmetric Multi-processor
+ (<acronym>SMP</acronym>) configurations are
+ supported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pc98</term>
+ <listitem>
+ <para>NEC PC-9801/9821 series with almost all
+ i386-compatible processors, including 80486, &pentium;,
+ &pentium; Pro, and &pentium; II, are all supported. All
+ i386-compatible processors by AMD, Cyrix, IBM, and IDT are
+ also supported. EPSON PC-386/486/586 series, which are
+ compatible with NEC PC-9801 series, are supported. The
+ NEC FC-9801/9821 and NEC SV-98 series should be
+ supported.</para>
+
+ <para>High-resolution mode is not supported. NEC
+ PC-98XA/XL/RL/XL^2, and NEC PC-H98 series are supported in
+ normal (PC-9801 compatible) mode only. The
+ <acronym>SMP</acronym>-related features of &os; are not
+ supported. The New Extend Standard Architecture
+ (<acronym>NESA</acronym>) bus used in the PC-H98, SV-H98,
+ and FC-H98 series, is not supported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>&arch.powerpc;</term>
+ <listitem>
+ <para>All New World <acronym>ROM</acronym> &apple;
+ &mac; systems with built-in <acronym>USB</acronym>
+ are supported. <acronym>SMP</acronym> is supported on
+ machines with multiple <acronym>CPU</acronym>s.</para>
+
+ <para>A 32-bit kernel can only use the first 2&nbsp;GB of
+ <acronym>RAM</acronym>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>&arch.sparc64;</term>
+ <listitem>
+ <para>Systems supported by &os;/&arch.sparc64; are listed at
+ the FreeBSD/sparc64 Project (<link
+ xlink:href="&url.base;/platforms/sparc.html">http://www.freebsd.org/platforms/sparc.html</link>).</para>
+
+ <para><acronym>SMP</acronym> is supported on all systems
+ with more than 1 processor. A dedicated disk is required
+ as it is not possible to share a disk with another
+ operating system at this time.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-pre">
+ <title>Pre-Installation Tasks</title>
+
+ <para>Once it has been determined that the system meets the
+ minimum hardware requirements for installing &os;, the
+ installation file should be downloaded and the installation
+ media prepared. Before doing this, check that the system is
+ ready for an installation by verifying the items in this
+ checklist:</para>
+
+ <procedure>
+ <step>
+ <title>Back Up Important Data</title>
+
+ <para>Before installing any operating system,
+ <emphasis>always</emphasis> backup all important data first.
+ Do not store the backup on the system being installed.
+ Instead, save the data to a removable disk such as a
+ <acronym>USB</acronym> drive, another system on the network,
+ or an online backup service. Test the backup before
+ starting the installation to make sure it contains all of
+ the needed files. Once the installer formats the system's
+ disk, all data stored on that disk will be lost.</para>
+ </step>
+
+ <step>
+ <title>Decide Where to Install &os;</title>
+
+ <para>If &os; will be the only operating system installed,
+ this step can be skipped. But if &os; will share the disk
+ with another operating system, decide which disk or
+ partition will be used for &os;.</para>
+
+ <para>In the &arch.i386; and &arch.amd64; architectures, disks
+ can be divided into multiple partitions using one of two
+ partitioning schemes. A traditional <firstterm>Master Boot
+ Record</firstterm> (<acronym>MBR</acronym>) holds a
+ partition table defining up to four <firstterm>primary
+ partitions</firstterm>. For historical reasons, &os;
+ calls these primary partition
+ <firstterm>slices</firstterm>. One of these primary
+ partitions can be made into an <firstterm>extended
+ partition</firstterm> containing multiple
+ <firstterm>logical partitions</firstterm>. The
+ <firstterm>GUID Partition Table</firstterm>
+ (<acronym>GPT</acronym>) is a newer and simpler method of
+ partitioning a disk. Common <acronym>GPT</acronym>
+ implementations allow up to 128 partitions per disk,
+ eliminating the need for logical partitions.</para>
+
+ <warning>
+ <para>Some older operating systems, like &windows;&nbsp;XP,
+ are not compatible with the <acronym>GPT</acronym>
+ partition scheme. If &os; will be sharing a disk with
+ such an operating system, <acronym>MBR</acronym>
+ partitioning is required.</para>
+ </warning>
+
+ <para>The &os; boot loader requires either a primary or
+ <acronym>GPT</acronym> partition. If all of the primary or
+ <acronym>GPT</acronym> partitions are already in use, one
+ must be freed for &os;. To create a partition without
+ deleting existing data, use a partition resizing tool to
+ shrink an existing partition and create a new partition
+ using the freed space.</para>
+
+ <para>A variety of free and commercial partition resizing
+ tools are listed at <link
+ xlink:href="http://en.wikipedia.org/wiki/List_of_disk_partitioning_software">http://en.wikipedia.org/wiki/List_of_disk_partitioning_software</link>.
+ <application>GParted Live</application> (<link
+ xlink:href="http://gparted.sourceforge.net/livecd.php">http://gparted.sourceforge.net/livecd.php</link>)
+ is a free live <acronym>CD</acronym> which includes the
+ <application>GParted</application> partition editor.
+ <application>GParted</application> is also included with
+ many other Linux live <acronym>CD</acronym>
+ distributions.</para>
+
+ <warning>
+ <para>When used properly, disk shrinking utilities can
+ safely create space for creating a new partition. Since
+ the possibility of selecting the wrong partition exists,
+ always backup any important data and verify the integrity
+ of the backup before modifying disk partitions.</para>
+ </warning>
+
+ <para>Disk partitions containing different operating systems
+ make it possible to install multiple operating systems on
+ one computer. An alternative is to use virtualization
+ (<xref linkend="virtualization"/>) which allows multiple
+ operating systems to run at the same time without modifying
+ any disk partitions.</para>
+ </step>
+
+ <step>
+ <title>Collect Network Information</title>
+
+ <para>Some &os; installation methods require a network
+ connection in order to download the installation files.
+ After any installation, the installer will offer to setup
+ the system's network interfaces.</para>
+
+ <para>If the network has a <acronym>DHCP</acronym> server, it
+ can be used to provide automatic network configuration. If
+ <acronym>DHCP</acronym> is not available, the following
+ network information for the system must be obtained from the
+ local network administrator or Internet service
+ provider:</para>
+
+ <orderedlist xml:id="bsdinstall-collect-network-information">
+ <title>Required Network Information</title>
+
+ <listitem>
+ <para><acronym>IP</acronym> address</para>
+ </listitem>
+
+ <listitem>
+ <para>Subnet mask</para>
+ </listitem>
+
+ <listitem>
+ <para><acronym>IP</acronym> address of default
+ gateway</para>
+ </listitem>
+
+ <listitem>
+ <para>Domain name of the network</para>
+ </listitem>
+
+ <listitem>
+ <para><acronym>IP</acronym> addresses of the network's
+ <acronym>DNS</acronym> servers</para>
+ </listitem>
+ </orderedlist>
+ </step>
+
+ <step>
+ <title>Check for &os; Errata</title>
+
+ <para>Although the &os;&nbsp;Project strives to ensure that
+ each release of &os; is as stable as possible, bugs
+ occasionally creep into the process. On very rare occasions
+ those bugs affect the installation process. As these
+ problems are discovered and fixed, they are noted in the
+ &os; Errata (<link
+ xlink:href="&url.base;/releases/&rel.current;R/errata.html">http://www.freebsd.org/releases/&rel.current;R/errata.html</link>)
+ on the &os; web site. Check the errata before installing to
+ make sure that there are no problems that might affect the
+ installation.</para>
+
+ <para>Information and errata for all the releases can be found
+ on the release information section of the &os; web site
+ (<link
+ xlink:href="&url.base;/releases/index.html">http://www.freebsd.org/releases/index.html</link>).</para>
+ </step>
+ </procedure>
+
+ <sect2 xml:id="bsdinstall-installation-media">
+ <title>Prepare the Installation Media</title>
+
+ <para>The &os; installer is not an application that can be run
+ from within another operating system. Instead, download a
+ &os; installation file, burn it to the media associated with
+ its file type and size (<acronym>CD</acronym>,
+ <acronym>DVD</acronym>, or <acronym>USB</acronym>), and boot
+ the system to install from the inserted media.</para>
+
+ <para>&os; installation files are available at <link
+ xlink:href="&url.base;/where.html#download">www.freebsd.org/where.html#download</link>.
+ Each installation file's name includes the release version of
+ &os;, the architecture, and the type of file. For example, to
+ install &os; 10.0 on an &arch.amd64; system from a
+ <acronym>DVD</acronym>, download
+ <filename>FreeBSD-10.0-RELEASE-amd64-dvd1.iso</filename>, burn
+ this file to a <acronym>DVD</acronym>, and boot the system
+ with the <acronym>DVD</acronym> inserted.</para>
+
+ <para>Several file types are available, though not all file
+ types are available for all architectures. The possible file
+ types are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>-bootonly.iso</literal>: This is the smallest
+ installation file as it only contains the installer. A
+ working Internet connection is required during
+ installation as the installer will download the files it
+ needs to complete the &os; installation. This file should
+ be burned to a <acronym>CD</acronym> using a
+ <acronym>CD</acronym> burning application.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-disc1.iso</literal>: This file contains all
+ of the files needed to install &os;, its source, and the
+ Ports Collection. It should be burned to a
+ <acronym>CD</acronym> using a <acronym>CD</acronym>
+ burning application.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-dvd1.iso</literal>: This file contains all
+ of the files needed to install &os;, its source, and the
+ Ports Collection. It also contains a set of popular
+ binary packages for installing a window manager and some
+ applications so that a complete system can be installed
+ from media without requiring a connection to the Internet.
+ This file should be burned to a <acronym>DVD</acronym>
+ using a <acronym>DVD</acronym> burning application.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-memstick.img</literal>: This file contains
+ all of the files needed to install &os;, its source, and
+ the Ports Collection. It should be burned to a
+ <acronym>USB</acronym> stick using the instructions
+ below.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Also download <filename>CHECKSUM.SHA256</filename> from
+ the same directory as the image file and use it to check the
+ image file's integrity by calculating a
+ <firstterm>checksum</firstterm>. &os; provides &man.sha256.1;
+ for this, while other operating systems have similar programs.
+ Compare the calculated checksum with the one shown in
+ <filename>CHECKSUM.SHA256</filename>. The checksums must
+ match exactly. If the checksums do not match, the file is
+ corrupt and should be downloaded again.</para>
+
+ <sect3 xml:id="bsdinstall-usb">
+ <title>Writing an Image File to <acronym>USB</acronym></title>
+
+ <para>The <filename>*.img</filename> file is an
+ <emphasis>image</emphasis> of the complete contents of a
+ memory stick. It <emphasis>cannot</emphasis> be copied to
+ the target device as a file. Several applications are
+ available for writing the <filename>*.img</filename> to a
+ <acronym>USB</acronym> stick. This section describes two of
+ these utilities.</para>
+
+ <important>
+ <para>Before proceeding, back up any important data on the
+ <acronym>USB</acronym> stick. This procedure will erase
+ the existing data on the stick.</para>
+ </important>
+
+ <procedure xml:id="bsdinstall-usb-dd">
+ <title>Using <command>dd</command> to Write the
+ Image</title>
+
+ <warning>
+ <para>This example uses <filename>/dev/da0</filename> as
+ the target device where the image will be written. Be
+ <emphasis>very careful</emphasis> that the correct
+ device is used as this command will destroy the existing
+ data on the specified target device.</para>
+ </warning>
+
+ <step>
+ <para>The &man.dd.1; command-line utility is
+ available on BSD, &linux;, and &macos; systems. To burn
+ the image using <command>dd</command>, insert the
+ <acronym>USB</acronym> stick and determine its device
+ name. Then, specify the name of the downloaded
+ installation file and the device name for the
+ <acronym>USB</acronym> stick. This example burns the
+ &arch.amd64; installation image to the first
+ <acronym>USB</acronym> device on an existing &os;
+ system.</para>
+
+ <screen>&prompt.root; <userinput>dd if=<replaceable>FreeBSD-10.0-RELEASE-amd64-memstick.img</replaceable> of=/dev/<replaceable>da0</replaceable> bs=64k</userinput></screen>
+
+ <para>If this command fails, verify that the
+ <acronym>USB</acronym> stick is not mounted and that the
+ device name is for the disk, not a partition. Some
+ operating systems might require this command to be run
+ with &man.sudo.8;. Systems like &linux; might buffer
+ writes. To force all writes to complete, use
+ &man.sync.8;.</para>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>Using &windows; to Write the Image</title>
+
+ <warning>
+ <para>Be sure to give the correct drive letter as the
+ existing data on the specified drive will be overwritten
+ and destroyed.</para>
+ </warning>
+
+ <step>
+ <title>Obtaining <application>Image Writer for
+ &windows;</application></title>
+
+ <para><application>Image Writer for
+ &windows;</application> is a free application that can
+ correctly write an image file to a memory stick.
+ Download it from <uri
+ xlink:href="https://launchpad.net/win32-image-writer/">https://launchpad.net/win32-image-writer/</uri>
+ and extract it into a folder.</para>
+ </step>
+
+ <step>
+ <title>Writing the Image with Image Writer</title>
+
+ <para>Double-click the
+ <application>Win32DiskImager</application> icon to start
+ the program. Verify that the drive letter shown under
+ <computeroutput>Device</computeroutput> is the drive
+ with the memory stick. Click the folder icon and select
+ the image to be written to the memory stick. Click
+ <guibutton>[&nbsp;Save&nbsp;]</guibutton> to accept the
+ image file name. Verify that everything is correct, and
+ that no folders on the memory stick are open in other
+ windows. When everything is ready, click
+ <guibutton>[&nbsp;Write&nbsp;]</guibutton> to write the
+ image file to the memory stick.</para>
+ </step>
+ </procedure>
+
+ <para>You are now ready to start installing &os;.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-start">
+ <title>Starting the Installation</title>
+
+ <important>
+ <para>By default, the installation will not make any changes to
+ the disk(s) before the following message:</para>
+
+ <programlisting>Your changes will now be written to disk. If you
+have chosen to overwrite existing data, it will
+be PERMANENTLY ERASED. Are you sure you want to
+commit your changes?</programlisting>
+
+ <para>The install can be exited at any time prior to this
+ warning. If
+ there is a concern that something is incorrectly configured,
+ just turn the computer off before this point and no changes
+ will be made to the system's disks.</para>
+ </important>
+
+ <para>This section describes how to boot the system from the
+ installation media which was prepared using the instructions in
+ <xref linkend="bsdinstall-installation-media"/>. When using a
+ bootable USB stick, plug in the <acronym>USB</acronym> stick
+ before turning on the computer. When booting from
+ <acronym>CD</acronym> or <acronym>DVD</acronym>, turn on the
+ computer and insert the media at the first opportunity. How to
+ configure the system to boot from the inserted media depends
+ upon the architecture.</para>
+
+ <sect2 xml:id="bsdinstall-starting-i386">
+ <title>Booting on &i386; and &arch.amd64;</title>
+
+ <para>These architectures provide a <acronym>BIOS</acronym>
+ menu for selecting the boot device. Depending upon the
+ installation media being used, select the
+ <acronym>CD</acronym>/<acronym>DVD</acronym> or
+ <acronym>USB</acronym> device as the first boot device. Most
+ systems also provide a key for selecting the boot device
+ during startup without having to enter the
+ <acronym>BIOS</acronym>. Typically, the key is either
+ <keycap>F10</keycap>, <keycap>F11</keycap>,
+ <keycap>F12</keycap>, or <keycap>Escape</keycap>.</para>
+
+ <para>If the computer loads the existing operating system
+ instead of the &os; installer, then either:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The installation media was not inserted early enough
+ in the boot process. Leave the media inserted and try
+ restarting the computer.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <acronym>BIOS</acronym> changes were incorrect or
+ not saved. Double-check that the right boot device is
+ selected as the first boot device.</para>
+ </listitem>
+
+ <listitem>
+ <para>This system is too old to support booting from the
+ chosen media. In this case, the <application>Plop Boot
+ Manager</application> (<link
+ xlink:href="http://www.plop.at/en/bootmanager.html">http://www.plop.at/en/bootmanager.html</link>)
+ can be used to boot the system from the selected
+ media.</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+
+ <sect2>
+ <title>Booting on &powerpc;</title>
+
+ <para>On most machines, holding <keycap>C</keycap> on the
+ keyboard during boot will boot from the <acronym>CD</acronym>.
+ Otherwise, hold <keycombo action="simul">
+ <keycap>Command</keycap>
+ <keycap>Option</keycap>
+ <keycap>O</keycap>
+ <keycap>F</keycap>
+ </keycombo>, or
+ <keycombo action="simul">
+ <keycap>Windows</keycap>
+ <keycap>Alt</keycap>
+ <keycap>O</keycap>
+ <keycap>F</keycap>
+ </keycombo> on non-&apple; keyboards. At the
+ <prompt>0 &gt;</prompt> prompt, enter</para>
+
+ <screen><userinput>boot cd:,\ppc\loader cd:0</userinput></screen>
+ </sect2>
+
+ <sect2>
+ <title>Booting on &sparc64;</title>
+
+ <para>Most &sparc64; systems are set up to boot automatically
+ from disk. To install &os; from a <acronym>CD</acronym>
+ requires a break into the <acronym>PROM</acronym>.</para>
+
+ <para>To do this, reboot the system and wait until the boot
+ message appears. The message depends on the model, but should
+ look something like this:</para>
+
+ <screen>Sun Blade 100 (UltraSPARC-IIe), Keyboard Present
+Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved.
+OpenBoot 4.2, 128 MB memory installed, Serial #51090132.
+Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen>
+
+ <para>If the system proceeds to boot from disk at this point,
+ press <keycombo
+ action="simul"><keycap>L1</keycap><keycap>A</keycap></keycombo>
+ or <keycombo
+ action="simul"><keycap>Stop</keycap><keycap>A</keycap></keycombo>
+ on the keyboard, or send a <command>BREAK</command> over the
+ serial console. When using <application>tip</application> or
+ <application>cu</application>, <command>~#</command> will
+ issue a BREAK. The <acronym>PROM</acronym> prompt will be
+ <prompt>ok</prompt> on systems with one
+ <acronym>CPU</acronym> and <prompt>ok {0} </prompt> on
+ <acronym>SMP</acronym> systems, where the digit indicates the
+ number of the active <acronym>CPU</acronym>.</para>
+
+ <para>At this point, place the <acronym>CD</acronym> into the
+ drive and type <command>boot cdrom</command> from the
+ <acronym>PROM</acronym> prompt.</para>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-view-probe">
+ <title>&os; Boot Menu</title>
+
+ <para>Once the system boots from the installation media, a menu
+ similar to the following will be displayed:</para>
+
+ <figure xml:id="bsdinstall-newboot-loader-menu">
+ <title>&os; Boot Loader Menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-newboot-loader-menu"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>By default, the menu will wait ten seconds for user input
+ before booting into the &os; installer or, if &os; is already
+ installed, before booting into &os;. To pause the boot timer
+ in order to review the selections, press
+ <keycap>Space</keycap>. To select an option, press its
+ highlighted number, character, or key. The following options
+ are available.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>Boot Multi User</literal>: This will
+ continue the &os; boot process. If the boot timer has
+ been paused, press <keycap>1</keycap>, upper- or
+ lower-case <keycap>B</keycap>, or
+ <keycap>Enter</keycap>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Boot Single User</literal>: This mode can be
+ used to fix an existing &os; installation as described in
+ <xref linkend="boot-singleuser"/>. Press
+ <keycap>2</keycap> or the upper- or lower-case
+ <keycap>S</keycap> to enter this mode.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Escape to loader prompt</literal>: This will
+ boot the system into a repair prompt that contains a
+ limited number of low-level commands. This prompt is
+ described in <xref linkend="boot-loader"/>. Press
+ <keycap>3</keycap> or <keycap>Esc</keycap> to boot into
+ this prompt.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Reboot</literal>: Reboots the system.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Configure Boot Options</literal>: Opens the
+ menu shown in, and described under, <xref
+ linkend="bsdinstall-boot-options-menu"/>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <figure xml:id="bsdinstall-boot-options-menu">
+ <title>&os; Boot Options Menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-boot-options-menu"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The boot options menu is divided into two sections. The
+ first section can be used to either return to the main boot
+ menu or to reset any toggled options back to their
+ defaults.</para>
+
+ <para>The next section is used to toggle the available options
+ to <literal>On</literal> or <literal>Off</literal> by pressing
+ the option's highlighted number or character. The system will
+ always boot using the settings for these options until they
+ are modified. Several options can be toggled using this
+ menu:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>ACPI Support</literal>: If the system hangs
+ during boot, try toggling this option to
+ <literal>Off</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Safe Mode</literal>: If the system still
+ hangs during boot even with <literal>ACPI
+ Support</literal> set to <literal>Off</literal>, try
+ setting this option to <literal>On</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Single User</literal>: Toggle this option to
+ <literal>On</literal> to fix an existing &os; installation
+ as described in <xref linkend="boot-singleuser"/>. Once
+ the problem is fixed, set it back to
+ <literal>Off</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Verbose</literal>: Toggle this option to
+ <literal>On</literal> to see more detailed messages during
+ the boot process. This can be useful when troubleshooting
+ a piece of hardware.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>After making the needed selections, press
+ <keycap>1</keycap> or <keycap>Backspace</keycap> to return to
+ the main boot menu, then press <keycap>Enter</keycap> to
+ continue booting into &os;. A series of boot messages will
+ appear as &os; carries out its hardware device probes and
+ loads the installation program. Once the boot is complete,
+ the welcome menu shown in <xref
+ linkend="bsdinstall-choose-mode"/> will be displayed.</para>
+
+ <figure xml:id="bsdinstall-choose-mode">
+ <title>Welcome Menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-choose-mode"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Press <keycap>Enter</keycap> to select the default of
+ <guibutton>[&nbsp;Install&nbsp;]</guibutton> to enter the
+ installer. The rest of this chapter describes how to use this
+ installer. Otherwise, use the right or left arrows or the
+ colorized letter to select the desired menu item. The
+ <guibutton>[&nbsp;Shell&nbsp;]</guibutton> can be used to
+ access a &os; shell in order to use command line utilities to
+ prepare the disks before installation. The
+ <guibutton>[&nbsp;Live CD&nbsp;]</guibutton> option can be
+ used to try out &os; before installing it. The live version
+ is described in <xref linkend="using-live-cd"/>.</para>
+
+ <tip>
+ <para>To review the boot messages, including the hardware
+ device probe, press the upper- or lower-case
+ <keycap>S</keycap> and then <keycap>Enter</keycap> to access
+ a shell. At the shell prompt, type <command>more
+ /var/run/dmesg.boot</command> and use the space bar to
+ scroll through the messages. When finished, type
+ <command>exit</command> to return to the welcome
+ menu.</para>
+ </tip>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="using-bsdinstall">
+ <title>Using <application>bsdinstall</application></title>
+
+ <para>This section shows the order of the
+ <application>bsdinstall</application> menus and the type of
+ information that will be asked before the system is installed.
+ Use the arrow keys to highlight a menu option, then
+ <keycap>Space</keycap> to select or deselect that menu item.
+ When finished, press <keycap>Enter</keycap> to save the
+ selection and move onto the next screen.</para>
+
+ <sect2 xml:id="bsdinstall-keymap">
+ <title>Selecting the Keymap Menu</title>
+
+ <para>Depending on the system console being used,
+ <application>bsdinstall</application> may initially display
+ the menu shown in <xref
+ linkend="bsdinstall-keymap-select-default"/>.</para>
+
+ <figure xml:id="bsdinstall-keymap-select-default">
+ <title>Keymap Selection</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-keymap-select-default"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>To configure the keyboard layout, press
+ <keycap>Enter</keycap> with
+ <guibutton>[&nbsp;YES&nbsp;]</guibutton> selected, which will
+ display the menu shown in <xref
+ linkend="bsdinstall-config-keymap"/>. To instead use the
+ default layout, use the arrow key to select
+ <guibutton>[&nbsp;NO&nbsp;]</guibutton> and press
+ <keycap>Enter</keycap> to skip this menu screen.</para>
+
+ <figure xml:id="bsdinstall-config-keymap">
+ <title>Selecting Keyboard Menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-config-keymap"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>When configuring the keyboard layout, use the up and down
+ arrows to select the keymap that most closely represents the
+ mapping of the keyboard attached to the system. Press
+ <keycap>Enter</keycap> to save the selection.</para>
+
+ <note>
+ <para>Pressing <keycap>Esc</keycap> will exit this menu and
+ use the default keymap. If the choice of keymap is not
+ clear, <guimenuitem>United States of America
+ ISO-8859-1</guimenuitem> is also a safe option.</para>
+ </note>
+
+ <para>In &os; 10.0-RELEASE and later, this menu has been
+ enhanced. The full selection of keymaps is shown, with the
+ default preselected. In addition, when selecting a different
+ keymap, a dialog is displayed that allows the user to try the
+ keymap and ensure it is correct before proceeding.</para>
+
+ <figure xml:id="bsdinstall-keymap-10">
+ <title>Enhanced Keymap Menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-keymap-10"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-hostname">
+ <title>Setting the Hostname</title>
+
+ <para>The next <application>bsdinstall</application> menu is
+ used to set the hostname for the newly installed
+ system.</para>
+
+ <figure xml:id="bsdinstall-config-hostname">
+ <title>Setting the Hostname</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-config-hostname"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Type in a hostname that is unique for the network. It
+ should be a fully-qualified hostname, such as <systemitem
+ class="fqdomainname">machine3.example.com</systemitem>.</para>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-components">
+ <title>Selecting Components to Install</title>
+
+ <para>Next, <application>bsdinstall</application> will prompt to
+ select optional components to install.</para>
+
+ <figure xml:id="bsdinstall-config-components">
+ <title>Selecting Components to Install</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-config-components"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Deciding which components to install will depend largely
+ on the intended use of the system and the amount of disk space
+ available. The &os; kernel and userland, collectively known
+ as the <firstterm>base system</firstterm>, are always
+ installed. Depending on the architecture, some of these
+ components may not appear:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>doc</literal> - Additional documentation,
+ mostly of historical interest, to install into
+ <filename>/usr/share/doc</filename>. The documentation
+ provided by the FreeBSD Documentation Project may be
+ installed later using the instructions in <xref
+ linkend="updating-upgrading-documentation"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>games</literal> - Several traditional
+ <acronym>BSD</acronym> games, including
+ <application>fortune</application>,
+ <application>rot13</application>, and others.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>lib32</literal> - Compatibility libraries for
+ running 32-bit applications on a 64-bit version of
+ &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>ports</literal> - The &os; Ports Collection
+ is a collection of files which automates the downloading,
+ compiling and installation of third-party software
+ packages. <xref linkend="ports"/> discusses how to use
+ the Ports Collection.</para>
+
+ <warning>
+ <para>The installation program does not check for
+ adequate disk space. Select this option only if
+ sufficient hard disk space is available. The &os; Ports
+ Collection takes up about &ports.size; of disk
+ space.</para>
+ </warning>
+ </listitem>
+
+ <listitem>
+ <para><literal>src</literal> - The complete &os; source code
+ for both the kernel and the userland. Although not
+ required for the majority of applications, it may be
+ required to build device drivers, kernel modules, or some
+ applications from the Ports Collection. It is also used
+ for developing &os; itself. The full source tree requires
+ 1&nbsp;GB of disk space and recompiling the entire &os;
+ system requires an additional 5&nbsp;GB of space.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-netinstall">
+ <title>Installing from the Network</title>
+
+ <para>The menu shown in <xref
+ linkend="bsdinstall-netinstall-notify"/> only appears when
+ installing from a <filename>-bootonly.iso</filename>
+ <acronym>CD</acronym> as this installation media does not hold
+ copies of the installation files. Since the installation
+ files must be retrieved over a network connection, this menu
+ indicates that the network interface must be first
+ configured.</para>
+
+ <figure xml:id="bsdinstall-netinstall-notify">
+ <title>Installing from the Network</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-netinstall-files"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>To configure the network connection, press
+ <keycap>Enter</keycap> and follow the instructions in <xref
+ linkend="bsdinstall-config-network-dev"/>. Once the
+ interface is configured, select a mirror site that is
+ located in the same region of the world as the computer on
+ which &os; is being installed. Files can be retrieved more
+ quickly when the mirror is close to the target computer,
+ reducing installation time.</para>
+
+ <figure xml:id="bsdinstall-netinstall-mirror">
+ <title>Choosing a Mirror</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-netinstall-mirrorselect"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Installation will then continue as if the installation
+ files were located on the local installation media.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-partitioning">
+ <title>Allocating Disk Space</title>
+
+ <para>The next menu is used to determine the method for
+ allocating disk space. The options available in the menu
+ depend upon the version of &os; being installed.</para>
+
+ <figure xml:id="bsdinstall-part-guided-manual">
+ <title>Partitioning Choices on &os; 9.x</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-part-guided-manual"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <figure xml:id="bsdinstall-zfs-partmenu">
+ <title>Partitioning Choices on &os; 10.x and Higher</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-zfs-partmenu"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para><literal>Guided</literal> partitioning automatically sets up
+ the disk partitions, <literal>Manual</literal> partitioning
+ allows advanced users to create customized partitions from menu
+ options, and <literal>Shell</literal> opens a shell prompt where
+ advanced users can create customized partitions using
+ command-line utilities like &man.gpart.8;, &man.fdisk.8;, and
+ &man.bsdlabel.8;. <literal>ZFS</literal> partitioning, only
+ available in &os; 10 and later, creates an optionally encrypted
+ root-on-ZFS system with support for <firstterm>boot
+ environments</firstterm>.</para>
+
+ <para>This section describes what to consider when laying out the
+ disk partitions. It then demonstrates how to use the different
+ partitioning methods.</para>
+
+ <sect2 xml:id="configtuning-initial">
+ <title>Designing the Partition Layout</title>
+
+ <indexterm><primary>partition layout</primary></indexterm>
+ <indexterm>
+ <primary><filename>/etc</filename></primary>
+ </indexterm>
+ <indexterm>
+ <primary><filename>/var</filename></primary>
+ </indexterm>
+ <indexterm>
+ <primary><filename>/usr</filename></primary>
+ </indexterm>
+
+ <para>When laying out file systems, remember that hard drives
+ transfer data faster from the outer tracks to the inner.
+ Thus, smaller and heavier-accessed file systems should be
+ closer to the outside of the drive, while larger partitions
+ like <filename>/usr</filename> should be placed toward the
+ inner parts of the disk. It is a good idea to create
+ partitions in an order similar to: <filename>/</filename>,
+ swap, <filename>/var</filename>, and
+ <filename>/usr</filename>.</para>
+
+ <para>The size of the <filename>/var</filename> partition
+ reflects the intended machine's usage. This partition is
+ used to hold mailboxes, log files, and printer spools.
+ Mailboxes and log files can grow to unexpected sizes
+ depending on the number of users and how long log files are
+ kept. On average, most users rarely need more than about a
+ gigabyte of free disk space in
+ <filename>/var</filename>.</para>
+
+ <note>
+ <para>Sometimes, a lot of disk space is required in
+ <filename>/var/tmp</filename>. When new software is
+ installed, the packaging tools extract a temporary copy of
+ the packages under <filename>/var/tmp</filename>. Large
+ software packages, like <application>Firefox</application>,
+ <application>OpenOffice</application> or
+ <application>LibreOffice</application> may be tricky to
+ install if there is not enough disk space under
+ <filename>/var/tmp</filename>.</para>
+ </note>
+
+ <para>The <filename>/usr</filename> partition holds many of the
+ files which support the system, including the &os; Ports
+ Collection and system source code. At least 2 gigabytes is
+ recommended for this partition.</para>
+
+ <para>When selecting partition sizes, keep the space
+ requirements in mind. Running out of space in one partition
+ while barely using another can be a hassle.</para>
+
+ <indexterm>
+ <primary>swap sizing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>swap partition</primary>
+ </indexterm>
+
+ <para>As a rule of thumb, the swap partition should be about
+ double the size of physical memory (<acronym>RAM</acronym>).
+ Systems with minimal <acronym>RAM</acronym> may perform
+ better with more swap. Configuring too little swap can lead
+ to inefficiencies in the <acronym>VM</acronym> page scanning
+ code and might create issues later if more memory is
+ added.</para>
+
+ <para>On larger systems with multiple <acronym>SCSI</acronym>
+ disks or multiple <acronym>IDE</acronym> disks operating on
+ different controllers, it is recommended that swap be
+ configured on each drive, up to four drives. The swap
+ partitions should be approximately the same size. The
+ kernel can handle arbitrary sizes but internal data structures
+ scale to 4 times the largest swap partition. Keeping the swap
+ partitions near the same size will allow the kernel to
+ optimally stripe swap space across disks. Large swap sizes
+ are fine, even if swap is not used much. It might be easier
+ to recover from a runaway program before being forced to
+ reboot.</para>
+
+ <para>By properly partitioning a system, fragmentation
+ introduced in the smaller write heavy partitions will not
+ bleed over into the mostly read partitions. Keeping the
+ write loaded partitions closer to the disk's edge will
+ increase <acronym> I/O</acronym> performance in the
+ partitions where it occurs the most. While
+ <acronym>I/O</acronym> performance in the larger partitions
+ may be needed, shifting them more toward the edge of the disk
+ will not lead to a significant performance improvement over
+ moving <filename>/var</filename> to the edge.</para>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-part-guided">
+ <title>Guided Partitioning</title>
+
+ <para>When this method is selected, a menu will display the
+ available disk(s). If multiple disks are connected, choose
+ the one where &os; is to be installed.</para>
+
+ <figure xml:id="bsdinstall-part-guided-disk">
+ <title>Selecting from Multiple Disks</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-part-guided-disk"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Once the disk is selected, the next menu prompts to
+ install to either the entire disk or to create a partition
+ using free space. If
+ <guibutton>[&nbsp;Entire&nbsp;Disk&nbsp;]</guibutton> is
+ chosen, a general partition layout filling the whole disk is
+ automatically created. Selecting
+ <guibutton>[&nbsp;Partition&nbsp;]</guibutton> creates a
+ partition layout from the unused space on the disk.</para>
+
+ <figure xml:id="bsdinstall-part-entire-part">
+ <title>Selecting Entire Disk or Partition</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-part-entire-part"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>After the partition layout has been created, review it to
+ ensure it meets the needs of the installation. Selecting
+ <guibutton>[&nbsp;Revert&nbsp;]</guibutton> will reset the
+ partitions to their original values and pressing
+ <guibutton>[&nbsp;Auto&nbsp;]</guibutton> will recreate the
+ automatic &os; partitions. Partitions can also be manually
+ created, modified, or deleted. When the partitioning is
+ correct, select <guibutton>[&nbsp;Finish&nbsp;]</guibutton> to
+ continue with the installation.</para>
+
+ <figure xml:id="bsdinstall-part-review">
+ <title>Review Created Partitions</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-part-review"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-part-manual">
+ <title>Manual Partitioning</title>
+
+ <para>Selecting this method opens the partition editor:</para>
+
+ <figure xml:id="bsdinstall-part-manual-create">
+ <title>Manually Create Partitions</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-part-manual-create"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Highlight the installation drive
+ (<filename>ada0</filename> in this example) and select
+ <guibutton>[&nbsp;Create&nbsp;]</guibutton> to display a menu
+ of available partition schemes:</para>
+
+ <figure xml:id="bsdinstall-part-manual-partscheme">
+ <title>Manually Create Partitions</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-part-manual-partscheme"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para><acronym>GPT</acronym> is usually the most appropriate
+ choice for &arch.amd64; computers. Older computers that are
+ not compatible with <acronym>GPT</acronym> should use
+ <acronym>MBR</acronym>. The other partition schemes are
+ generally used for uncommon or older computers.</para>
+
+ <table frame="none" rowsep="1" pgwide="1">
+ <title>Partitioning Schemes</title>
+
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry align="left">Abbreviation</entry>
+ <entry align="left">Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>APM</entry>
+ <entry>Apple Partition Map, used by &powerpc;.</entry>
+ </row>
+
+ <row>
+ <entry>BSD</entry>
+ <entry><acronym>BSD</acronym> label without an
+ <acronym>MBR</acronym>, sometimes called
+ <firstterm>dangerously dedicated mode</firstterm> as
+ non-<acronym>BSD</acronym> disk utilities may not
+ recognize it.</entry>
+ </row>
+
+ <row>
+ <entry>GPT</entry>
+ <entry>GUID Partition Table (<link
+ xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</link>).</entry>
+ </row>
+
+ <row>
+ <entry>MBR</entry>
+ <entry>Master Boot Record (<link
+ xlink:href="http://en.wikipedia.org/wiki/Master_boot_record">http://en.wikipedia.org/wiki/Master_boot_record</link>).</entry>
+ </row>
+
+ <row>
+ <entry>PC98</entry>
+ <entry><acronym>MBR</acronym> variant used by NEC PC-98
+ computers (<link
+ xlink:href="http://en.wikipedia.org/wiki/Pc9801">http://en.wikipedia.org/wiki/Pc9801</link>).</entry>
+ </row>
+
+ <row>
+ <entry>VTOC8</entry>
+ <entry>Volume Table Of Contents used by Sun SPARC64 and
+ UltraSPARC computers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>After the partitioning scheme has been selected and
+ created, select <guibutton>[&nbsp;Create&nbsp;]</guibutton>
+ again to create the partitions.</para>
+
+ <figure xml:id="bsdinstall-part-manual-addpart">
+ <title>Manually Create Partitions</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-part-manual-addpart"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>A standard &os; <acronym>GPT</acronym> installation uses
+ at least three partitions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>freebsd-boot</literal> - Holds the &os; boot
+ code.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>freebsd-ufs</literal> - A &os;
+ <acronym>UFS</acronym> file system.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>freebsd-swap</literal> - &os; swap
+ space.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Another partition type worth noting is
+ <literal>freebsd-zfs</literal>, used for partitions that will
+ contain a &os; <acronym>ZFS</acronym> file system (<xref
+ linkend="zfs"/>). Refer to &man.gpart.8; for
+ descriptions of the available <acronym>GPT</acronym> partition
+ types.</para>
+
+ <para>Multiple file system partitions can be created and some
+ people prefer a traditional layout with separate partitions
+ for <filename>/</filename>, <filename>/var</filename>,
+ <filename>/tmp</filename>, and <filename>/usr</filename>. See
+ <xref linkend="bsdinstall-part-manual-splitfs"/> for an
+ example.</para>
+
+ <para>The <literal>Size</literal> may be entered with common
+ abbreviations: <emphasis>K</emphasis> for kilobytes,
+ <emphasis>M</emphasis> for megabytes, or
+ <emphasis>G</emphasis> for gigabytes.</para>
+
+ <tip>
+ <para>Proper sector alignment provides the best performance,
+ and making partition sizes even multiples of 4K-bytes helps
+ to ensure alignment on drives with either 512-byte or
+ 4K-byte sectors. Generally, using partition sizes that are
+ even multiples of 1M or 1G is the easiest way to make sure
+ every partition starts at an even multiple of 4K. There is
+ one exception: the <emphasis>freebsd-boot</emphasis>
+ partition should be no larger than 512K due to current boot
+ code limitations.</para>
+ </tip>
+
+ <para>A <literal>Mountpoint</literal> is needed if the partition
+ will contain a file system. If only a single
+ <acronym>UFS</acronym> partition will be created, the
+ mountpoint should be <filename>/</filename>.</para>
+
+ <para>The <literal>Label</literal> is a name by which the
+ partition will be known. Drive names or numbers can change if
+ the drive is connected to a different controller or port, but
+ the partition label does not change. Referring to labels
+ instead of drive names and partition numbers in files like
+ <filename>/etc/fstab</filename> makes the system more tolerant
+ to hardware changes. <acronym>GPT</acronym> labels appear in
+ <filename>/dev/gpt/</filename> when a disk is attached. Other
+ partitioning schemes have different label capabilities and
+ their labels appear in different directories in
+ <filename>/dev/</filename>.</para>
+
+ <tip>
+ <para>Use a unique label on every partition to avoid
+ conflicts from identical labels. A few letters from the
+ computer's name, use, or location can be added to the label.
+ For instance, use <literal>labroot</literal> or
+ <literal>rootfslab</literal> for the <acronym>UFS</acronym>
+ root partition on the computer named
+ <literal>lab</literal>.</para>
+ </tip>
+
+ <example xml:id="bsdinstall-part-manual-splitfs">
+ <title>Creating Traditional Split File System
+ Partitions</title>
+
+ <para>For a traditional partition layout where the
+ <filename>/</filename>, <filename>/var</filename>,
+ <filename>/tmp</filename>, and <filename>/usr</filename>
+ directories are separate file systems on their own
+ partitions, create a <acronym>GPT</acronym> partitioning
+ scheme, then create the partitions as shown. Partition
+ sizes shown are typical for a 20G target disk. If more
+ space is available on the target disk, larger swap or
+ <filename>/var</filename> partitions may be useful. Labels
+ shown here are prefixed with <literal>ex</literal> for
+ <quote>example</quote>, but readers should use other unique
+ label values as described above.</para>
+
+ <para>By default, &os;'s <filename>gptboot</filename> expects
+ the first <acronym>UFS</acronym> partition to be the
+ <filename>/</filename> partition.</para>
+
+ <informaltable frame="none">
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Partition Type</entry>
+ <entry>Size</entry>
+ <entry>Mountpoint</entry>
+ <entry>Label</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>freebsd-boot</literal></entry>
+ <entry><literal>512K</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>freebsd-ufs</literal></entry>
+ <entry><literal>2G</literal></entry>
+ <entry><filename>/</filename></entry>
+ <entry><literal>exrootfs</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>freebsd-swap</literal></entry>
+ <entry><literal>4G</literal></entry>
+ <entry></entry>
+ <entry><literal>exswap</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>freebsd-ufs</literal></entry>
+ <entry><literal>2G</literal></entry>
+ <entry><filename>/var</filename></entry>
+ <entry><literal>exvarfs</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>freebsd-ufs</literal></entry>
+ <entry><literal>1G</literal></entry>
+ <entry><filename>/tmp</filename></entry>
+ <entry><literal>extmpfs</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>freebsd-ufs</literal></entry>
+ <entry>accept the default (remainder of the
+ disk)</entry>
+ <entry><filename>/usr</filename></entry>
+ <entry><literal>exusrfs</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </example>
+
+ <para>After the custom partitions have been created, select
+ <guibutton>[&nbsp;Finish&nbsp;]</guibutton> to continue with
+ the installation.</para>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-part-zfs">
+ <title>Root-on-ZFS Automatic Partitioning</title>
+
+ <para>Support for automatic creation of root-on-ZFS
+ installations was added in &os; 10.0-RELEASE. This
+ partitioning mode only works with whole disks and will erase
+ the contents of the entire disk. The installer will
+ automatically create partitions aligned to 4k boundaries and
+ force <acronym>ZFS</acronym> to use 4k sectors. This is safe
+ even with 512 byte sector disks, and has the added benefit of
+ ensuring that pools created on 512 byte disks will be able to
+ have 4k sector disks added in the future, either as additional
+ storage space or as replacements for failed disks. The
+ installer can also optionally employ <acronym>GELI</acronym>
+ disk encryption as described in <xref
+ linkend="disks-encrypting-geli"/>.
+ If encryption is enabled, a 2&nbsp;GB unencrypted boot pool
+ containing the <filename>/boot</filename> directory is
+ created. It holds the kernel and other files necessary to
+ boot the system. A swap partition of a user selectable size
+ is also created, and all remaining space is used for the
+ <acronym>ZFS</acronym> pool.</para>
+
+ <para>The main <acronym>ZFS</acronym> configuration menu offers
+ a number of options to control the creation of the
+ pool.</para>
+
+ <figure xml:id="bsdinstall-zfs-menu">
+ <title><acronym>ZFS</acronym> Partitioning Menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-zfs-menu"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Select <keycap>T</keycap> to configure the <literal>Pool
+ Type</literal> and the disk(s) that will constitute the
+ pool. The automatic <acronym>ZFS</acronym> installer
+ currently only supports the creation of a single top level
+ vdev, except in stripe mode. To create more complex pools,
+ use the instructions in <xref
+ linkend="bsdinstall-part-shell"/> to create the pool. The
+ installer supports the creation of various pool types,
+ including stripe (not recommended, no redundancy), mirror
+ (best performance, least usable space), and RAID-Z 1, 2, and 3
+ (with the capability to withstand the concurrent failure of 1,
+ 2, and 3 disks, respectively). while selecting the pool type,
+ a tooltip is displayed across the bottom of the screen with
+ advice about the number of required disks, and in the case of
+ RAID-Z, the optimal number of disks for each
+ configuration.</para>
+
+ <figure xml:id="bsdinstall-zfs-vdev_type">
+ <title><acronym>ZFS</acronym> Pool Type</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-zfs-vdev_type"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Once a <literal>Pool Type</literal> has been selected, a
+ list of available disks is displayed, and the user is prompted
+ to select one or more disks to make up the pool. The
+ configuration is then validated, to ensure enough disks are
+ selected. If not, select <guibutton>&lt;Change
+ Selection&gt;</guibutton> to return to the list of disks, or
+ <guibutton>&lt;Cancel&gt;</guibutton> to change the pool
+ type.</para>
+
+ <figure xml:id="bsdinstall-zfs-disk_select">
+ <title>Disk Selection</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-zfs-disk_select"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <figure xml:id="bsdinstall-zfs-vdev_invalid">
+ <title>Invalid Selection</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-zfs-vdev_invalid"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>If one or more disks are missing from the list, or if
+ disks were attached after the installer was started, select
+ <guibutton>- Rescan Devices</guibutton> to repopulate the list
+ of available disks. To ensure that the correct disks are
+ selected, so as not to accidently destroy the wrong disks, the
+ <guibutton>- Disk Info</guibutton> menu can be used to inspect
+ each disk, including its partition table and various other
+ information such as the device model number and serial number,
+ if available.</para>
+
+ <figure xml:id="bsdinstall-zfs-disk_info">
+ <title>Analysing a Disk</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-zfs-disk_info"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The main <acronym>ZFS</acronym> configuration menu also
+ allows the user to enter a pool name, disable forcing 4k
+ sectors, enable or disable encryption, switch between
+ <acronym>GPT</acronym> (recommended) and
+ <acronym>MBR</acronym> partition table types, and select the
+ amount of swap space. Once all options have been set to the
+ desired values, select the
+ <guibutton>&gt;&gt;&gt;&nbsp;Install</guibutton> option at the
+ top of the menu.</para>
+
+ <para>If <acronym>GELI</acronym> disk encryption was enabled,
+ the installer will prompt twice for the passphrase to be used
+ to encrypt the disks.</para>
+
+ <figure xml:id="bsdinstall-zfs-geli_password">
+ <title>Disk Encryption Password</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-zfs-geli_password"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The installer then offers a last chance to cancel before
+ the contents of the selected drives are destroyed to create
+ the <acronym>ZFS</acronym> pool.</para>
+
+ <figure xml:id="bsdinstall-zfs-warning">
+ <title>Last Chance</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-zfs-warning"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The installation then proceeds normally.</para>
+
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-part-shell">
+ <title>Shell Mode Partitioning</title>
+
+ <para>When creating advanced installations, the
+ <application>bsdinstall</application> paritioning menus may
+ not provide the level of flexibility required. Advanced users
+ can select the <guibutton>Shell</guibutton> option from the
+ partitioning menu in order to manually partition the drives,
+ create the file system(s), populate
+ <filename>/tmp/bsdinstall_etc/fstab</filename>, and mount the
+ file systems under <filename>/mnt</filename>. Once this is
+ done, type <command>exit</command> to return to
+ <application>bsdinstall</application> and continue the
+ installation.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-final-warning">
+ <title>Committing to the Installation</title>
+
+ <para>Once the disks are configured, the next menu provides the
+ last chance to make changes before the selected hard drive(s)
+ are formatted. If changes need to be made, select
+ <guibutton>[&nbsp;Back&nbsp;]</guibutton> to return to the main
+ partitioning menu.
+ <guibutton>[&nbsp;Revert&nbsp;&amp;&nbsp;Exit&nbsp;]</guibutton>
+ will exit the installer without making any changes to the hard
+ drive.</para>
+
+ <figure xml:id="bsdinstall-final-confirmation">
+ <title>Final Confirmation</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-final-confirmation"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>To instead start the actual installation, select
+ <guibutton>[&nbsp;Commit&nbsp;]</guibutton> and press
+ <keycap>Enter</keycap>.</para>
+
+ <para>Installation time will vary depending on the distributions
+ chosen, installation media, and speed of the computer. A series
+ of messages will indicate the progress.</para>
+
+ <para>First, the installer formats the selected disk(s) and
+ initializes the partitions. Next, in the case of a bootonly
+ media, it downloads the selected components:</para>
+
+ <figure xml:id="bsdinstall-distfile-fetching">
+ <title>Fetching Distribution Files</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-distfile-fetching"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Next, the integrity of the distribution files is verified
+ to ensure they have not been corrupted during download or
+ misread from the installation media:</para>
+
+ <figure xml:id="bsdinstall-distfile-verify">
+ <title>Verifying Distribution Files</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-distfile-verifying"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Finally, the verified distribution files are extracted to
+ the disk:</para>
+
+ <figure xml:id="bsdinstall-distfile-extract">
+ <title>Extracting Distribution Files</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-distfile-extracting"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Once all requested distribution files have been extracted,
+ <application>bsdinstall</application> displays the first
+ post-installation configuration screen. The available
+ post-configuration options are described in the next
+ section.</para>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-post">
+ <title>Post-Installation</title>
+
+ <para>Once &os; is installed,
+ <application>bsdinstall</application> will prompt to configure
+ several options before booting into the newly installed system.
+ This section describes these configuration options.</para>
+
+ <tip>
+ <para>Once the system has booted,
+ <command>bsdconfig</command> provides a menu-driven method for
+ configuring the system using these and additional
+ options.</para>
+ </tip>
+
+ <sect2 xml:id="bsdinstall-post-root">
+ <title>Setting the <systemitem
+ class="username">root</systemitem> Password</title>
+
+ <para>First, the <systemitem class="username">root</systemitem>
+ password must be set. While entering the password, the
+ characters being typed are not displayed on the screen. After
+ the password has been entered, it must be entered again. This
+ helps prevent typing errors.</para>
+
+ <figure xml:id="bsdinstall-post-set-root-passwd">
+ <title>Setting the <systemitem
+ class="username">root</systemitem> Password</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-post-root-passwd"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-config-network-dev">
+ <title>Configuring Network Interfaces</title>
+
+ <para>Next, a list of the network interfaces found on the
+ computer is shown. Select the interface to configure.</para>
+
+ <note>
+ <para>The network configuration menus will be skipped if the
+ network was previously configured as part of a
+ <emphasis>bootonly</emphasis> installation.</para>
+ </note>
+
+ <figure xml:id="bsdinstall-configure-net-interface">
+ <title>Choose a Network Interface</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>If an Ethernet interface is selected, the installer will
+ skip ahead to the menu shown in <xref
+ linkend="bsdinstall-configure-net-ipv4"/>. If a wireless
+ network interface is chosen, the system will instead scan for
+ wireless access points:</para>
+
+ <figure xml:id="bsdinstall-wireless-scan">
+ <title>Scanning for Wireless Access Points</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-wireless-scan"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Wireless networks are identified by a Service Set
+ Identifier (<acronym>SSID</acronym>), a short, unique name
+ given to each network. <acronym>SSIDs</acronym> found during
+ the scan are listed, followed by a description of the
+ encryption types available for that network. If the desired
+ <acronym>SSID</acronym> does not appear in the list, select
+ <guibutton>[&nbsp;Rescan&nbsp;]</guibutton> to scan again. If
+ the desired network still does not appear, check for problems
+ with antenna connections or try moving the computer closer to
+ the access point. Rescan after each change is made.</para>
+
+ <figure xml:id="bsdinstall-wireless-accesspoints">
+ <title>Choosing a Wireless Network</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-wireless-accesspoints"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Next, enter the encryption information for connecting to
+ the selected wireless network. <acronym>WPA2</acronym>
+ encryption is strongly recommended as older encryption types,
+ like <acronym>WEP</acronym>, offer little security. If the
+ network uses <acronym>WPA2</acronym>, input the password, also
+ known as the Pre-Shared Key (<acronym>PSK</acronym>). For
+ security reasons, the characters typed into the input box are
+ displayed as asterisks.</para>
+
+ <figure xml:id="bsdinstall-wireless-wpa2">
+ <title>WPA2 Setup</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-wireless-wpa2setup"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Next, choose whether or not an <acronym>IPv4</acronym>
+ address should be configured on the Ethernet or wireless
+ interface:</para>
+
+ <figure xml:id="bsdinstall-configure-net-ipv4">
+ <title>Choose <acronym>IPv4</acronym> Networking</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>There are two methods of <acronym>IPv4</acronym>
+ configuration. <acronym>DHCP</acronym> will automatically
+ configure the network interface correctly and should be used
+ if the network provides a <acronym>DHCP</acronym> server.
+ Otherwise, the addressing information needs to be input
+ manually as a static configuration.</para>
+
+ <note>
+ <para>Do not enter random network information as it will not
+ work. If a <acronym>DHCP</acronym> server is not available,
+ obtain the information listed in <xref
+ linkend="bsdinstall-collect-network-information"/> from
+ the network administrator or Internet service
+ provider.</para>
+ </note>
+
+ <para>If a <acronym>DHCP</acronym> server is available, select
+ <guibutton>[&nbsp;Yes&nbsp;]</guibutton> in the next menu to
+ automatically configure the network interface. The installer
+ will appear to pause for a minute or so as it finds the
+ <acronym>DHCP</acronym> server and obtains the addressing
+ information for the system.</para>
+
+ <figure xml:id="bsdinstall-net-ipv4-dhcp">
+ <title>Choose <acronym>IPv4</acronym> <acronym>DHCP</acronym>
+ Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-dhcp"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>If a <acronym>DHCP</acronym> server is not available,
+ select <guibutton>[&nbsp;No&nbsp;]</guibutton> and input the
+ following addressing information in this menu:</para>
+
+ <figure xml:id="bsdinstall-net-ipv4-static">
+ <title><acronym>IPv4</acronym> Static Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-static"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>IP Address</literal> - The
+ <acronym>IPv4</acronym> address assigned to this computer.
+ The address must be unique and not already in use by
+ another piece of equipment on the local network.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Subnet Mask</literal> - The subnet mask for
+ the network.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Default Router</literal> - The
+ <acronym>IP</acronym> address of the network's default
+ gateway.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The next screen will ask if the interface should be
+ configured for <acronym>IPv6</acronym>. If
+ <acronym>IPv6</acronym> is available and desired, choose
+ <guibutton>[&nbsp;Yes&nbsp;]</guibutton> to select it.</para>
+
+ <figure xml:id="bsdinstall-net-ipv6">
+ <title>Choose IPv6 Networking</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para><acronym>IPv6</acronym> also has two methods of
+ configuration. StateLess Address AutoConfiguration
+ (<acronym>SLAAC</acronym>) will automatically request the
+ correct configuration information from a local router. Refer
+ to <link
+ xlink:href="http://tools.ietf.org/html/rfc4862">http://tools.ietf.org/html/rfc4862</link>
+ for more information. Static configuration requires manual
+ entry of network information.</para>
+
+ <para>If an <acronym>IPv6</acronym> router is available, select
+ <guibutton>[&nbsp;Yes&nbsp;]</guibutton> in the next menu to
+ automatically configure the network interface. The installer
+ will appear to pause for a minute or so as it finds the router
+ and obtains the addressing information for the system.</para>
+
+ <figure xml:id="bsdinstall-net-ipv6-slaac">
+ <title>Choose IPv6 SLAAC Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface-slaac"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>If an <acronym>IPv6</acronym> router is not available,
+ select <guibutton>[&nbsp;No&nbsp;]</guibutton> and input the
+ following addressing information in this menu:</para>
+
+ <figure xml:id="bsdinstall-net-ipv6-static">
+ <title>IPv6 Static Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6-static"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>IPv6 Address</literal> - The
+ <acronym>IPv6</acronym> address assigned to this computer.
+ The address must be unique and not already in use by
+ another piece of equipment on the local network.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Default Router</literal> - The
+ <acronym>IPv6</acronym> address of the network's default
+ gateway.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The last network configuration menu is used to configure
+ the Domain Name System (<acronym>DNS</acronym>) resolver,
+ which converts hostnames to and from network addresses. If
+ <acronym>DHCP</acronym> or <acronym>SLAAC</acronym> was used
+ to autoconfigure the network interface, the <literal>Resolver
+ Configuration</literal> values may already be filled in.
+ Otherwise, enter the local network's domain name in the
+ <literal>Search</literal> field. <literal>DNS #1</literal>
+ and <literal>DNS #2</literal> are the <acronym>IPv4</acronym>
+ and/or <acronym>IPv6</acronym> addresses of the
+ <acronym>DNS</acronym> servers. At least one
+ <acronym>DNS</acronym> server is required.</para>
+
+ <figure xml:id="bsdinstall-net-dns-config">
+ <title>DNS Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-configure-network-ipv4-dns"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-timezone">
+ <title>Setting the Time Zone</title>
+
+ <para>The next menu asks if the system clock uses
+ <acronym>UTC</acronym> or local time. When in doubt, select
+ <guibutton>[&nbsp;No&nbsp;]</guibutton> to choose the more
+ commonly-used local time.</para>
+
+ <figure xml:id="bsdinstall-local-utc">
+ <title>Select Local or UTC Clock</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-set-clock-local-utc"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The next series of menus are used to determine the correct
+ local time by selecting the geographic region, country, and
+ time zone. Setting the time zone allows the system to
+ automatically correct for regional time changes, such as
+ daylight savings time, and perform other time zone related
+ functions properly.</para>
+
+ <para>The example shown here is for a machine located in the
+ Eastern time zone of the United States. The selections will
+ vary according to the geographical location.</para>
+
+ <figure xml:id="bsdinstall-timezone-region">
+ <title>Select a Region</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-timezone-region"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The appropriate region is selected using the arrow keys
+ and then pressing <keycap>Enter</keycap>.</para>
+
+ <figure xml:id="bsdinstall-timezone-country">
+ <title>Select a Country</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-timezone-country"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Select the appropriate country using the arrow keys and
+ press <keycap>Enter</keycap>.</para>
+
+ <figure xml:id="bsdinstall-timezone-zone">
+ <title>Select a Time Zone</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-timezone-zone"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The appropriate time zone is selected using the arrow keys
+ and pressing <keycap>Enter</keycap>.</para>
+
+ <figure xml:id="bsdinstall-timezone-confirmation">
+ <title>Confirm Time Zone</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-timezone-confirm"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Confirm the abbreviation for the time zone is correct. If
+ it is, press <keycap>Enter</keycap> to continue with the
+ post-installation configuration.</para>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-sysconf">
+ <title>Enabling Services</title>
+
+ <para>The next menu is used to configure which system services
+ will be started whenever the system boots. All of these
+ services are optional. Only start the services that are
+ needed for the system to function.</para>
+
+ <figure xml:id="bsdinstall-config-serv">
+ <title>Selecting Additional Services to Enable</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-config-services"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Here is a summary of the services which can be enabled in
+ this menu:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>sshd</literal> - The Secure Shell
+ (<acronym>SSH</acronym>) daemon is used to remotely access
+ a system over an encrypted connection. Only enable this
+ service if the system should be available for remote
+ logins.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>moused</literal> - Enable this service if the
+ mouse will be used from the command-line system
+ console.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>ntpd</literal> - The Network Time Protocol
+ (<acronym>NTP</acronym>) daemon for automatic clock
+ synchronization. Enable this service if there is a
+ &windows;, Kerberos, or <acronym>LDAP</acronym> server on
+ the network.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>powerd</literal> - System power control
+ utility for power control and energy saving.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-crashdump">
+ <title>Enabling Crash Dumps</title>
+
+ <para>The next menu is used to configure whether or not crash
+ dumps should be enabled. Enabling crash dumps can be useful
+ in debugging issues with the system, so users are encouraged
+ to enable crash dumps.</para>
+
+ <figure xml:id="bsdinstall-config-crashdump">
+ <title>Enabling Crash Dumps</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-config-crashdump"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-addusers">
+ <title>Add Users</title>
+
+ <para>The next menu prompts to create at least one user account.
+ It is recommended to login to the system using a user account
+ rather than as <systemitem class="username">root</systemitem>.
+ When logged in as <systemitem
+ class="username">root</systemitem>, there are essentially no
+ limits or protection on what can be done. Logging in as a
+ normal user is safer and more secure.</para>
+
+ <para>Select <guibutton>[&nbsp;Yes&nbsp;]</guibutton> to add new
+ users.</para>
+
+ <figure xml:id="bsdinstall-add-user1">
+ <title>Add User Accounts</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-adduser1"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Follow the prompts and input the requested information for
+ the user account. The example shown in <xref
+ linkend="bsdinstall-add-user2"/> creates the <systemitem
+ class="username">asample</systemitem> user account.</para>
+
+ <figure xml:id="bsdinstall-add-user2">
+ <title>Enter User Information</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-adduser2"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Here is a summary of the information to input:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>Username</literal> - The name the user will
+ enter to log in. A common convention is to use the first
+ letter of the first name combined with the last name, as
+ long as each username is unique for the system. The
+ username is case sensitive and should not contain any
+ spaces.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Full name</literal> - The user's full name.
+ This can contain spaces and is used as a description for
+ the user account.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Uid</literal> - User <acronym>ID</acronym>.
+ Typically, this is left blank so the system will assign a
+ value.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Login group</literal> - The user's group.
+ Typically this is left blank to accept the default.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Invite <replaceable>user</replaceable> into
+ other groups?</literal> - Additional groups to which the
+ user will be added as a member. If the user needs
+ administrative access, type <literal>wheel</literal>
+ here.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Login class</literal> - Typically left blank
+ for the default.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Shell</literal> - Type in one of the listed
+ values to set the interactive shell for the user. Refer
+ to <xref linkend="shells"/> for more information about
+ shells.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Home directory</literal> - The user's home
+ directory. The default is usually correct.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Home directory permissions</literal> -
+ Permissions on the user's home directory. The default is
+ usually correct.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Use password-based authentication?</literal>
+ - Typically <literal>yes</literal> so that the user is
+ prompted to input their password at login.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Use an empty password?</literal> -
+ Typically <literal>no</literal> as it is insecure to have
+ a blank password.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Use a random password?</literal> - Typically
+ <literal>no</literal> so that the user can set their own
+ password in the next prompt.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Enter password</literal> - The password for
+ this user. Characters typed will not show on the
+ screen.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Enter password again</literal> - The password
+ must be typed again for verification.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Lock out the account after
+ creation?</literal> - Typically <literal>no</literal> so
+ that the user can login.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>After entering everything, a summary is shown for review.
+ If a mistake was made, enter <literal>no</literal> and try
+ again. If everything is correct, enter <literal>yes</literal>
+ to create the new user.</para>
+
+ <figure xml:id="bsdinstall-add-user3">
+ <title>Exit User and Group Management</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-adduser3"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>If there are more users to add, answer the <literal>Add
+ another user?</literal> question with
+ <literal>yes</literal>. Enter <literal>no</literal> to finish
+ adding users and continue the installation.</para>
+
+ <para>For more information on adding users and user management,
+ see <xref linkend="users-synopsis"/>.</para>
+ </sect2>
+
+ <sect2 xml:id="bsdinstall-final-conf">
+ <title>Final Configuration</title>
+
+ <para>After everything has been installed and configured, a
+ final chance is provided to modify settings.</para>
+
+ <figure xml:id="bsdinstall-final-config">
+ <title>Final Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-finalconfiguration"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Use this menu to make any changes or do any additional
+ configuration before completing the installation.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>Add User</literal> - Described in <xref
+ linkend="bsdinstall-addusers"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Root Password</literal> - Described in <xref
+ linkend="bsdinstall-post-root"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Hostname</literal> - Described in <xref
+ linkend="bsdinstall-hostname"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Network</literal> - Described in <xref
+ linkend="bsdinstall-config-network-dev"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Services</literal> - Described in <xref
+ linkend="bsdinstall-sysconf"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Time Zone</literal> - Described in <xref
+ linkend="bsdinstall-timezone"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>Handbook</literal> - Download and install the
+ &os; Handbook.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>After any final configuration is complete, select
+ <guibutton>Exit</guibutton>.</para>
+
+ <figure xml:id="bsdinstall-final-modification-shell">
+ <title>Manual Configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="bsdinstall/bsdinstall-final-modification-shell"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para><application>bsdinstall</application> will prompt if there
+ are any additional configuration that needs to be done before
+ rebooting into the new system. Select
+ <guibutton>[&nbsp;Yes&nbsp;]</guibutton> to exit to a shell
+ within the new system or
+ <guibutton>[&nbsp;No&nbsp;]</guibutton> to proceed to the last
+ step of the installation.</para>
+
+ <figure xml:id="bsdinstall-final-main">
+ <title>Complete the Installation</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bsdinstall/bsdinstall-mainexit"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>If further configuration or special setup is needed,
+ select <guibutton>[&nbsp;Live&nbsp;CD&nbsp;]</guibutton> to
+ boot the install media into Live <acronym>CD</acronym>
+ mode.</para>
+
+ <para>If the installation is complete, select
+ <guibutton>[&nbsp;Reboot&nbsp;]</guibutton> to reboot the
+ computer and start the new &os; system. Do not forget to
+ remove the &os; install media or the computer may boot from it
+ again.</para>
+
+ <para>As &os; boots, informational messages are displayed.
+ After the system finishes booting, a login prompt is
+ displayed. At the <prompt>login:</prompt> prompt, enter the
+ username added during the installation. Avoid logging in as
+ <systemitem class="username">root</systemitem>. Refer to
+ <xref linkend="users-superuser"/> for instructions on how to
+ become the superuser when administrative access is
+ needed.</para>
+
+ <para>The messages that appeared during boot can be reviewed by
+ pressing <keycap>Scroll-Lock</keycap> to turn on the
+ scroll-back buffer. The <keycap>PgUp</keycap>,
+ <keycap>PgDn</keycap>, and arrow keys can be used to scroll
+ back through the messages. When finished, press
+ <keycap>Scroll-Lock</keycap> again to unlock the display and
+ return to the console. To review these messages once the
+ system has been up for some time, type <command>less
+ /var/run/dmesg.boot</command> from a command prompt. Press
+ <keycap>q</keycap> to return to the command line after
+ viewing.</para>
+
+ <para>If <application>sshd</application> was enabled in <xref
+ linkend="bsdinstall-config-serv"/>, the first boot may be
+ a bit slower as the system will generate the
+ <acronym>RSA</acronym> and <acronym>DSA</acronym> keys.
+ Subsequent boots will be faster. The fingerprints of the keys
+ will be displayed, as seen in this example:</para>
+
+ <screen>Generating public/private rsa1 key pair.
+Your identification has been saved in /etc/ssh/ssh_host_key.
+Your public key has been saved in /etc/ssh/ssh_host_key.pub.
+The key fingerprint is:
+10:a0:f5:af:93:ae:a3:1a:b2:bb:3c:35:d9:5a:b3:f3 root@machine3.example.com
+The key's randomart image is:
++--[RSA1 1024]----+
+| o.. |
+| o . . |
+| . o |
+| o |
+| o S |
+| + + o |
+|o . + * |
+|o+ ..+ . |
+|==o..o+E |
++-----------------+
+Generating public/private dsa key pair.
+Your identification has been saved in /etc/ssh/ssh_host_dsa_key.
+Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub.
+The key fingerprint is:
+7e:1c:ce:dc:8a:3a:18:13:5b:34:b5:cf:d9:d1:47:b2 root@machine3.example.com
+The key's randomart image is:
++--[ DSA 1024]----+
+| .. . .|
+| o . . + |
+| . .. . E .|
+| . . o o . . |
+| + S = . |
+| + . = o |
+| + . * . |
+| . . o . |
+| .o. . |
++-----------------+
+Starting sshd.</screen>
+
+ <para>Refer to <xref linkend="openssh"/> for more information
+ about fingerprints and <acronym>SSH</acronym>.</para>
+
+ <para>&os; does not install a graphical environment by default.
+ Refer to <xref linkend="x11"/> for more information about
+ installing and configuring a graphical window manager.</para>
+
+ <para>Proper shutdown of a &os; computer helps protect data and
+ hardware from damage. <emphasis>Do not turn off the power
+ before the system has been properly shut down!</emphasis> If
+ the user is a member of the <systemitem
+ class="groupname">wheel</systemitem> group, become the
+ superuser by typing <command>su</command> at the command line
+ and entering the <systemitem
+ class="username">root</systemitem> password. Then, type
+ <command>shutdown -p now</command> and the system will shut
+ down cleanly, and if the hardware supports it, turn itself
+ off.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="bsdinstall-install-trouble">
+ <title>Troubleshooting</title>
+
+ <indexterm>
+ <primary>installation</primary>
+ <secondary>troubleshooting</secondary>
+ </indexterm>
+ <para>This section covers basic installation
+ troubleshooting, such as common problems people have
+ reported.</para>
+
+ <para>Check the Hardware Notes (<link
+ xlink:href="&url.base;/releases/index.html">http://www.freebsd.org/releases/index.html</link>)
+ document for the version of &os; to make sure the hardware is
+ supported. If the hardware is supported and lock-ups or other
+ problems occur, build a custom kernel using the instructions in
+ <xref linkend="kernelconfig"/> to add support for devices which
+ are not present in the <filename>GENERIC</filename> kernel. The
+ default kernel assumes that most hardware devices are in their
+ factory default configuration in terms of
+ <acronym>IRQ</acronym>s, <acronym>I/O</acronym> addresses, and
+ <acronym>DMA</acronym> channels. If the hardware has been
+ reconfigured, a custom kernel configuration file can tell &os;
+ where to find things.</para>
+
+ <note>
+ <para>Some installation problems can be avoided or alleviated by
+ updating the firmware on various hardware components, most
+ notably the motherboard. Motherboard firmware is usually
+ referred to as the <acronym>BIOS</acronym>. Most motherboard
+ and computer manufacturers have a website for upgrades and
+ upgrade information.</para>
+
+ <para>Manufacturers generally advise against upgrading the
+ motherboard <acronym>BIOS</acronym> unless there is a good
+ reason for doing so, like a critical update. The upgrade
+ process <emphasis>can</emphasis> go wrong, leaving the
+ <acronym>BIOS</acronym> incomplete and the computer
+ inoperative.</para>
+ </note>
+
+ <para>If the system hangs while probing hardware during boot, or
+ it behaves strangely during install, <acronym>ACPI</acronym> may
+ be the culprit. &os; makes extensive use of the system
+ <acronym>ACPI</acronym> service on the &arch.i386;,
+ &arch.amd64;, and ia64 platforms to aid in system configuration
+ if it is detected during boot. Unfortunately, some bugs still
+ exist in both the <acronym>ACPI</acronym> driver and within
+ system motherboards and <acronym>BIOS</acronym> firmware.
+ <acronym>ACPI</acronym> can be disabled by setting the
+ <literal>hint.acpi.0.disabled</literal> hint in the third stage
+ boot loader:</para>
+
+ <screen><userinput>set hint.acpi.0.disabled="1"</userinput></screen>
+
+ <para>This is reset each time the system is booted, so it is
+ necessary to add <literal>hint.acpi.0.disabled="1"</literal> to
+ the file <filename>/boot/loader.conf</filename>. More
+ information about the boot loader can be found in <xref
+ linkend="boot-synopsis"/>.</para>
+ </sect1>
+
+ <sect1 xml:id="using-live-cd">
+ <title>Using the Live <acronym>CD</acronym></title>
+
+ <para>The welcome menu of <application>bsdinstall</application>,
+ shown in <xref linkend="bsdinstall-choose-mode"/>, provides a
+ <guibutton>[&nbsp;Live&nbsp;CD&nbsp;]</guibutton> option. This
+ is useful for those who are still wondering whether &os; is the
+ right operating system for them and want to test some of the
+ features before installing.</para>
+
+ <para>The following points should be noted before using the
+ <guibutton>[&nbsp;Live&nbsp;CD&nbsp;]</guibutton>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>To gain access to the system, authentication is
+ required. The username is <systemitem
+ class="username">root</systemitem> and the password is
+ blank.</para>
+ </listitem>
+
+ <listitem>
+ <para>As the system runs directly from the installation media,
+ performance will be significantly slower than that of a
+ system installed on a hard disk.</para>
+ </listitem>
+
+ <listitem>
+ <para>This option only provides a command prompt and not a
+ graphical interface.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/handbook/chapters.ent b/zh_TW.UTF-8/books/handbook/chapters.ent
index fc0c4577d0..f21646792b 100644
--- a/zh_TW.UTF-8/books/handbook/chapters.ent
+++ b/zh_TW.UTF-8/books/handbook/chapters.ent
@@ -8,7 +8,7 @@
Chapters should be listed in the order in which they are referenced.
$FreeBSD$
- Original revision: 1.33
+ Original revision: r45602
-->
<!ENTITY chap.preface SYSTEM "preface/preface.xml">
@@ -17,6 +17,7 @@
<!-- Part One -->
<!ENTITY chap.introduction SYSTEM "introduction/chapter.xml">
<!ENTITY chap.install SYSTEM "install/chapter.xml">
+ <!ENTITY chap.bsdinstall SYSTEM "bsdinstall/chapter.xml">
<!ENTITY chap.basics SYSTEM "basics/chapter.xml">
<!ENTITY chap.ports SYSTEM "ports/chapter.xml">
<!ENTITY chap.x11 SYSTEM "x11/chapter.xml">
@@ -31,15 +32,14 @@
<!-- Part Three -->
<!ENTITY chap.config SYSTEM "config/chapter.xml">
<!ENTITY chap.boot SYSTEM "boot/chapter.xml">
- <!ENTITY chap.users SYSTEM "users/chapter.xml">
<!ENTITY chap.security SYSTEM "security/chapter.xml">
<!ENTITY chap.jails SYSTEM "jails/chapter.xml">
<!ENTITY chap.mac SYSTEM "mac/chapter.xml">
<!ENTITY chap.audit SYSTEM "audit/chapter.xml">
<!ENTITY chap.disks SYSTEM "disks/chapter.xml">
<!ENTITY chap.geom SYSTEM "geom/chapter.xml">
+ <!ENTITY chap.zfs SYSTEM "zfs/chapter.xml">
<!ENTITY chap.filesystems SYSTEM "filesystems/chapter.xml">
- <!ENTITY chap.vinum SYSTEM "vinum/chapter.xml">
<!ENTITY chap.virtualization SYSTEM "virtualization/chapter.xml">
<!ENTITY chap.l10n SYSTEM "l10n/chapter.xml">
<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.xml">
@@ -55,14 +55,12 @@
<!-- Part Five (appendices) -->
<!ENTITY chap.mirrors SYSTEM "mirrors/chapter.xml">
- <!ENTITY chap.mirrors.lastmod.inc SYSTEM "mirrors.lastmod.inc">
- <!ENTITY chap.mirrors.ftp.index.inc SYSTEM "mirrors.xml.ftp.index.inc">
+ <!ENTITY chap.mirrors.lastmod.inc SYSTEM "mirrors.lastmod.inc">
+ <!ENTITY chap.mirrors.ftp.index.inc SYSTEM "mirrors.xml.ftp.index.inc">
<!ENTITY chap.mirrors.ftp.inc SYSTEM "mirrors.xml.ftp.inc">
- <!ENTITY chap.mirrors.cvsup.index.inc SYSTEM "mirrors.xml.cvsup.index.inc">
- <!ENTITY chap.mirrors.cvsup.inc SYSTEM "mirrors.xml.cvsup.inc">
<!ENTITY chap.bibliography SYSTEM "bibliography/chapter.xml">
<!ENTITY chap.eresources SYSTEM "eresources/chapter.xml">
- <!ENTITY chap.eresources.www.index.inc SYSTEM "eresources.xml.www.index.inc">
+ <!ENTITY chap.eresources.www.index.inc SYSTEM "eresources.xml.www.index.inc">
<!ENTITY chap.eresources.www.inc SYSTEM "eresources.xml.www.inc">
<!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.xml">
<!ENTITY chap.freebsd-glossary SYSTEM "../../share/xml/glossary.ent">
diff --git a/zh_TW.UTF-8/books/handbook/colophon.xml b/zh_TW.UTF-8/books/handbook/colophon.xml
index 0ded28baa5..0d92858c71 100644
--- a/zh_TW.UTF-8/books/handbook/colophon.xml
+++ b/zh_TW.UTF-8/books/handbook/colophon.xml
@@ -2,20 +2,19 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD$
+ $FreeBSD$
-->
-<colophon xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="colophon">
+<colophon xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="colophon">
+
<para>This book is the combined work of hundreds of contributors to
<quote>The FreeBSD Documentation Project</quote>. The text is
- authored in SGML
- according to the DocBook DTD and is formatted from SGML into many
- different presentation formats using <application>Jade</application>,
- an open source DSSSL
- engine. Norm Walsh's DSSSL stylesheets were used with an
- additional customization layer to provide the presentation
- instructions for <application>Jade</application>. The printed
- version of this document would not be possible without Donald
- Knuth's &tex; typesetting language,
- Leslie Lamport's <application>LaTeX</application>, or Sebastian
- Rahtz's <application>JadeTeX</application> macro package.</para>
+ authored in XML according to the DocBook DTD and is formatted
+ from XML into many different presentation formats using
+ XSLT. The printed version of this
+ document would not be possible without Donald Knuth's
+ &tex; typesetting language, Leslie
+ Lamport's <application>LaTeX</application>, or Sebastian Rahtz's
+ <application>JadeTeX</application> macro package.</para>
</colophon>
diff --git a/zh_TW.UTF-8/books/handbook/config/chapter.xml b/zh_TW.UTF-8/books/handbook/config/chapter.xml
index 07b0409d8b..a49c151144 100644
--- a/zh_TW.UTF-8/books/handbook/config/chapter.xml
+++ b/zh_TW.UTF-8/books/handbook/config/chapter.xml
@@ -1,26 +1,49 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The FreeBSD Documentation Project
+ The FreeBSD Traditional Chinese Project
$FreeBSD$
- Original revision: 1.213
- Chased revision: 1.221
+ Original revision: r46049
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="config-tuning">
- <info><title>設定與效能調校(Tuning)</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="config-tuning">
+
+ <info>
+ <title>設定與效能調校(Tuning)</title>
+
<authorgroup>
- <author><personname><firstname>Chern</firstname><surname>Lee</surname></personname><contrib>Written by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Chern</firstname>
+ <surname>Lee</surname>
+ </personname>
+ <contrib>Written by </contrib>
+ </author>
</authorgroup>
+
<authorgroup>
- <author><personname><firstname>Mike</firstname><surname>Smith</surname></personname><contrib>Based on a tutorial written by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Mike</firstname>
+ <surname>Smith</surname>
+ </personname>
+ <contrib>Based on a tutorial written by </contrib>
+ </author>
</authorgroup>
+
<authorgroup>
- <author><personname><firstname>Matt</firstname><surname>Dillon</surname></personname><contrib>Also based on tuning(7) written by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Matt</firstname>
+ <surname>Dillon</surname>
+ </personname>
+ <contrib>Also based on tuning(7) written by </contrib>
+ </author>
</authorgroup>
</info>
-
-
<sect1 xml:id="config-synopsis">
<title>概述</title>
@@ -70,6 +93,7 @@
</itemizedlist>
</sect1>
+ <!-- moved to bsdinstall/chapter.xml
<sect1 xml:id="configtuning-initial">
<title>一開始的規劃</title>
@@ -172,6 +196,7 @@
</sect2>
</sect1>
+ -->
<sect1 xml:id="configtuning-core-configuration">
<title>最主要的設定檔</title>
diff --git a/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml b/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml
index ef0d9a6c6d..149aa1c2c9 100644
--- a/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml
+++ b/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml
@@ -1,1178 +1,1803 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The FreeBSD Documentation Project
+ The FreeBSD Traditional Chinese Project
$FreeBSD$
- Original revision: 1.225
+ Original revision: 46272
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cutting-edge">
- <info><title>更新、升級 FreeBSD</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="updating-upgrading">
+
+ <info>
+ <title>更新、升級 &os;</title>
+
<authorgroup>
- <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured, reorganized, and parts updated by </contrib></author>
+ <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>
+ <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="cutting-edge-synopsis">
+ <sect1 xml:id="updating-upgrading-synopsis">
<title>概述</title>
- <para>&os; 是個持續發展的作業系統。對於喜歡追求新鮮、刺激的使用者而言,
- 有很多方法可以使您的系統輕鬆更新為最新版。
- 注意:並非每個人都適合這麼做! 本章主要是協助您決定到底要跟開發版本,
- 或是要使用較穩定的釋出版。
- </para>
+ <para>&os; 是個持續發展的作業系統。有些人喜歡官方釋出的版本,
+有些人則喜歡和官方最新的開發版本保持同步。然而即使是官方釋出的版本仍然時常有安全性更新或和其他緊急修復。無論使用哪種版本,&os;都提供所有必須的工具來讓系統保持最新,而且可以輕易升級不同版本。本章將描述如何追蹤開發版本,和保持&os;系統維持最新的基本工具。</para>
<para>讀完這章,您將了解︰</para>
<itemizedlist>
- <listitem><para>&os.stable; 與 &os.current; 這兩分支的不同之處;</para>
+ <listitem>
+ <para>如何使用
+ <application>freebsd-update</application>,
+ <application>Subversion</application>, 或
+ <application>CTM</application> 讓 &os; 系統保持在最新的版本。</para>
</listitem>
- <listitem><para>如何以
- <application>CSup</application>,
- <application>CVSup</application>,
- <application>CVS</application> 或
- <application>CTM</application> 來更新你的系統</para>
+
+ <listitem>
+ <para>如何比較安裝系統和原始複製的狀態。</para>
</listitem>
- <listitem><para>如何以 <command>make buildworld</command>
- 等指令來重新編譯、安裝整個 base system。</para>
+
+ <listitem>
+ <para>如何使用
+ <application>Subversion</application>或是documentation
+ ports<!--, and <application>Docsnap</application>-->來使已安裝的文件保持最新。</para>
+ </listitem>
+
+ <listitem>
+ <para>兩個開發分支的差異:&os.stable; 和 &os.current;。</para>
</listitem>
+ <listitem>
+ <para>如何重新編譯和重新安裝整個基礎系統。</para>
+ </listitem>
</itemizedlist>
<para>在開始閱讀這章之前,您需要︰</para>
<itemizedlist>
- <listitem><para>先設好你的網路(<xref linkend="advanced-networking"/>)。
- </para>
+ <listitem>
+ <para>設定好你的網路
+ (<xref linkend="advanced-networking"/>)。</para>
+ </listitem>
+
+ <listitem>
+ <para>知道如何安裝第三方軟體
+ (<xref linkend="ports"/>).</para>
</listitem>
- <listitem><para>知道如何透過 port/package 安裝軟體(<xref linkend="ports"/>)。</para></listitem>
</itemizedlist>
+
+ <note>
+ <para>本章中,使用 <command>svn</command> 來獲得和更新 &os; 原始碼。
+ 為了能使用他,首先要安裝 <package>devel/subversion</package>
+ port 或 package。</para>
+ </note>
</sect1>
- <sect1 xml:id="current-stable">
- <title>&os.current; vs. &os.stable;</title>
- <indexterm><primary>-CURRENT</primary></indexterm>
- <indexterm><primary>-STABLE</primary></indexterm>
+ <sect1 xml:id="updating-upgrading-freebsdupdate">
+ <info>
+ <title>&os; Update</title>
- <para>FreeBSD 有兩個發展分支:&os.current; 及
- &os.stable;。本節將會陸續介紹,並介紹它們分別又是如何更新。
- 首先,先介紹 &os.current;,接著再介紹 &os.stable;。</para>
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Written by </contrib>
+ </author>
+ </authorgroup>
- <sect2 xml:id="current">
- <title>使用最新的 &os; CURRENT</title>
-
- <para>這裡再次強調,&os.current; 是 &os; 開發的 <quote>最前線</quote>。
- &os.current; 使用者須有較強的技術能力,
- 而且應該要有能力自己解決困難的系統問題。 若您是 &os; 新手,
- 那麼請在安裝前最好先三思。</para>
-
- <sect3>
- <title>什麼是 &os.current;?</title>
- <indexterm><primary>snapshot</primary></indexterm>
-
- <para>&os.current; 是 &os; 的最新版。它包含:
- 仍在研發階段、實驗性質的修改、過渡時期的機制,
- 這些東西在下一次正式 relase 的版本可能會有,也可能不會有的。
- 儘管有許多 &os; 開發者每天都會編譯 &os.current; source code,
- 但有時這些原始碼是無法編譯成功。 雖然,這些問題通常會儘快解決,
- 但 &os.current; 到底是帶來浩劫或是多了想要用的新功能、改善,
- 這點主要取決於您更新原始碼的時機為何而定!</para>
- </sect3>
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Colin</firstname>
+ <surname>Percival</surname>
+ </personname>
+ <contrib>Based on notes provided by </contrib>
+ </author>
+ </authorgroup>
+ </info>
- <sect3>
- <title>誰需要 &os.current;?</title>
+ <indexterm>
+ <primary>Updating and Upgrading</primary>
+ </indexterm>
+ <indexterm>
+ <primary>freebsd-update</primary>
+ <see>updating-upgrading</see>
+ </indexterm>
- <para>&os.current; 適合下列這三類人:</para>
+ <para>即時應用安全性更新與升級作業系統到新的發行版本對一個持續運作的系統是重要的。&os; 包括一個叫 <command>freebsd-update</command> 的工具程式可以執行這兩項任務。</para>
+ <para>這個工具程式支援 &os; 二進制安全性與和錯誤更新,
+不需要手動編譯和安裝修復或新核心。
+安全性團隊目前支援的所有架構和發行版都可以取得二進制更新。
+目前支援的發行版列表和他們的支援期限都列於
+ <uri
+ xlink:href="http://www.FreeBSD.org/security/">http://www.FreeBSD.org/security/</uri>。</para>
+
+ <para>這個工具程式也支援作業系統升級到次要的發行版本和升級到令一個發行版分支升級到新的發行版本前,要檢查他的發行宣告,因為他包含發行版本相關的重要資訊。發行公告可以由<uri
+ xlink:href="http://www.FreeBSD.org/releases/">http://www.FreeBSD.org/releases/</uri>取得。</para>
+
+ <note>
+ <para>如果有使用<command>crontab</command>來執行
+ &man.freebsd-update.8;,那必須在升級作業系統前先停用。</para>
+ </note>
+
+ <para>這節描述 <command>freebsd-update</command> 使用的設定檔,
+示範如何運用安全性修補和如何升級到主要或次要的作業系統發行版,
+以及討論某些升級作業系統的考量。 </para>
+
+ <sect2 xml:id="freebsdupdate-config-file">
+ <title>設定檔</title>
+
+ <para>
+ <command>freebsd-update</command>預設的設定檔不需變更即可運作。
+有些使用者可能想要調校預設的設定檔 <filename>/etc/freebsd-update.conf</filename>
+來對程序有更好的控制。這個設定檔的註解說明了可以使用的選項,
+但以下可能需要更多一些的解釋:
+ </para>
- <orderedlist>
- <listitem>
- <para>&os; 社群成員:積極專注於 source tree 的某一部份,
- 以及認為保持為 <quote>current(最新狀態)</quote>
- 為絕對需求的人。</para>
- </listitem>
+ <programlisting># Components of the base system which should be kept updated.
+Components world kernel</programlisting>
+
+ <para>這個參數控制 &os; 的哪個部份將保持最新。
+ 預設是將更新整個 base system 和核心。
+個別元件可以被指定,
+例如:<literal>src/base</literal> 或 <literal>src/sys</literal>。
+然而最好的選項是維持預設設定,
+因為改變設定去包括特定項目,則每個需要的項目都必須要列出。
+時間一久可能會因為原始碼和二進制檔案沒有更新而造成慘重的後果。</para>
+
+ <programlisting># Paths which start with anything matching an entry in an IgnorePaths
+# statement will be ignored.
+IgnorePaths /boot/kernel/linker.hints</programlisting>
+
+ <para>保持特定的目錄,例如
+ <filename>/bin</filename> 或 <filename>/sbin</filename>,
+ 在更新過程不被更動,可以將他們的路徑加到此敘述中。
+ 這個選項可以防止 <command>freebsd-update</command>覆蓋本機的修改。</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>這個選項只會更新特定目錄中未修改的設定檔。
+ 任何使用者修改的檔案都不會自動更新。
+ 有另一個選項──
+ <literal>KeepModifiedMetadata</literal>會指示
+ <command>freebsd-update</command> 在合併時將改變儲存下來</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>列出 <command>freebsd-update</command>應嘗試合併的設定檔目錄。
+ 檔案合併過程是一系列類似&man.mergemaster.8;的&man.diff.1;修補,
+但是選項比較少。
+ 合併可以接受,開啟編輯器,或是令<command>freebsd-update</command>中止。
+如果有疑慮,備份 <filename>/etc</filename>,然後同意合併。
+ 更多關於<command>mergemaster</command>的資訊,
+參見 <xref linkend="mergemaster"/>。
+ </para>
- <listitem>
- <para>&os; 社群成員:為了確保 &os.current;
- 能夠儘可能地維持在最穩定的狀態,
- 而主動花時間解決問題的測試者。 此外,還有對 &os;
- 能提出具體建議以及改善方向,並提出 patch 修正檔的人。</para>
- </listitem>
+ <programlisting># Directory in which to store downloaded updates and temporary
+# files used by &os; Update.
+# WorkDir /var/db/freebsd-update</programlisting>
- <listitem>
- <para>只是關心或者想參考(比如,只是<emphasis>閱讀</emphasis>,
- 而非執行)的人。
- 這些人有時也會做些註解,或貢獻原始碼。</para>
- </listitem>
- </orderedlist>
- </sect3>
+ <para>這個目錄是所有修補檔和暫存檔放置處。
+ 當使用者進行版本升級時,這個位置應該要有至少1GB的可用磁碟空間。</para>
- <sect3>
- <title>&os.current; <emphasis>並不是</emphasis> 什麼?</title>
+ <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>
- <orderedlist>
- <listitem>
- <para>追求最新功能。 聽說裡面有些很酷的新功能,
- 並希望成為您周圍的人中第一個嘗試的人,
- 因此將 &os.current; 視為取得搶鮮版的捷徑。
- 儘管,您能夠因此首先瞭解到最新的功能,
- 但這也意味著若出現新的 bug 時,您也是首當其衝。</para>
- </listitem>
+ <para>當這個選項設定為<literal>yes</literal>,
+ <command>freebsd-update</command> 將會假設
+ <literal>Components</literal> 列表已完成,將不會嘗試做列表外的改變。
+ 實際上 <command>freebsd-update</command>將嘗試更新每一個屬於
+ <literal>Components</literal> 列表的檔案。</para>
+ </sect2>
- <listitem>
- <para>修復 bug 的速成法。 因為 &os.current;
- 的任何版本在修復已知 bug 的同時,又可能會產生新的 bug。
- </para>
- </listitem>
+ <sect2 xml:id="freebsdupdate-security-patches">
+ <title>運用安全性修補</title>
- <listitem>
- <para>無所不在的 <quote>officially supported</quote>。
- 我們會盡力協助上述 &os.current; 的那三種類別的
- <quote>legitimate</quote> 使用者,
- 但我們<emphasis>沒時間</emphasis>為他們提供技術支援。
- 這不代表我們很惡劣,或是不想幫助人(若是的話,
- 我們也不會為 &os; 努力了)
- ,實在是因為我們分身乏術,無法每天回答數百個問題,
- <emphasis>而同時</emphasis>繼續開發 &os;。
- 可以確定的一點就是,
- 在改善 &os; 或是回答大量有關實驗碼的問題之間,
- 若要做個選擇的話,開發者會選擇前者。</para>
- </listitem>
- </orderedlist>
- </sect3>
+ <para>運用 &os; 安全性修補的過程已經被簡化,
+ 允許系統管理員使用<command>freebsd-update</command>保持系統更新。
+ 更多關於&os; 安全性報告的資訊可以參考
+ <xref linkend="security-advisories"/>。</para>
- <sect3>
- <title>使用 &os.current;</title>
+ <para>&os; 安全性修補可以使用以下指令下載與安裝。
+ 第一個指令將決定是否有尚未完成的修補,如果有,將列出執行修補將會變更的檔案清單。第二個指令將會執行修補。
+ </para>
- <orderedlist>
- <listitem>
- <para>加入 &a.current.name;<indexterm><primary>-CURRENT</primary><secondary>using</secondary></indexterm> 及 &a.cvsall.name; 論壇。
- 這不單只是個建議,也是 <emphasis>必須</emphasis> 作的。
- 若您沒訂閱 <emphasis>&a.current.name;</emphasis>
- ,那麼就會錯過別人對目前系統狀態的說明,而枯耗在別人已解的問題。
- 更重要的是,可能會錯失一些對己身所管系統安危相當重要的公告。
- </para>
-
- <para>在 &a.cvsall.name; 上則可以看到每個 commit 紀錄,
- 因為這些記錄會連帶影響其他相關資訊。</para>
-
- <para>要訂閱這些論壇或其他論壇,請參考 &a.mailman.lists.link;
- 並點選想訂閱的部分即可。 至於其他後續步驟如何進行,
- 在那裡會有說明。</para>
- </listitem>
+ <screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
+&prompt.root; <userinput>freebsd-update install</userinput></screen>
- <listitem>
- <para>從 &os; <link linkend="mirrors">mirror 站</link>
- 取得原始碼。 有兩種方式可以達成:</para>
-
- <orderedlist>
- <listitem>
- <para>以 <link linkend="cvsup">csup</link><indexterm><primary><command>cvsup</command></primary></indexterm> 或
- <link linkend="cvsup">cvsup</link> 程式搭配位於
- <filename>/usr/share/examples/cvsup</filename> 檔名為
- <filename>standard-supfile</filename> 的
- <filename>supfile</filename>。
- 這是大家最常推薦的方式,因為它可以讓您把整個 tree 都抓回來,
- 之後就只取有更新的部分即可。
- 此外,許多人會把 <command>csup</command> 或
- <command>cvsup</command> 放到
- <command>cron</command><indexterm><primary><command>cron</command></primary></indexterm> 以定期自動更新。
- 您須要自訂前述的 <filename>supfile</filename> 範例檔,
- 並針對自身網路環境以調整 <link linkend="cvsup">csup</link>
- 或 <link linkend="cvsup">cvsup</link><indexterm><primary>-CURRENT</primary><secondary>Syncing with <application>CVSup</application></secondary></indexterm> 相關設定。</para>
- </listitem>
-
- <listitem>
- <para>使用 <application>CTM</application><indexterm><primary>-CURRENT</primary><secondary>Syncing with CTM</secondary></indexterm> 工具。 若網路環境不佳
- (上網費用貴,或只能用 email 而已)
- <application>CTM</application> 會比較適合您的需求。
- 然而,這也有一些爭議並且常抓到一些有問題的檔案。 因此,
- 很少人會用它。 這也註定了不能長期依賴這個更新方式。
- 若是使用 9600&nbsp;bps modem 或頻寬更大的上網者,建議使用
- <application>CVSup</application>
- 。</para>
- </listitem>
- </orderedlist>
- </listitem>
+ <para>如果更新執行任何核心修補,系統將會重新開機以使用修補過的核心。
+如果在任何執行中的二進位檔進行修補,被影響的應用程式將會重新啟動來使用修補過的二進位檔。</para>
- <listitem>
- <para>若抓 source code 是要用來跑的,而不僅只是看看而已,
- 那麼就抓 <emphasis>整個</emphasis> &os.current;,而不要只抓部分。
- 因為大部分的 source code 都會相依到其他 source code 環節部分,
- 若是您只編譯其中一部份,保證會很麻煩。</para>
-
- <para>在編譯 &os.current;<indexterm><primary>-CURRENT</primary><secondary>compiling</secondary></indexterm> 之前,請仔細閱讀
- <filename>/usr/src</filename> 內的 <filename>Makefile</filename>。
- 儘管只是升級部分東西而已,您至少也要先 <link linkend="makeworld">
- 裝新的 kernel 以及重新編譯 world</link>。 此外,多多閱讀
- &a.current; 以及 <filename>/usr/src/UPDATING</filename>
- 也是必須的,
- 才能知道目前進度是怎樣以及下一版會有什麼新東西。</para>
- </listitem>
+ <para>將以下項目加入 <filename>/etc/crontab</filename> 系統可以每天自動檢查是否有更新:</para>
- <listitem>
- <para>熱血!若您正在跑 &os.current;,
- 我們很想知道您對於它的想法是什麼,尤其是加強哪些功能,
- 或該修正哪些錯誤的建議。 如果您在建議時能附上相關程式碼的話,
- 那真是太棒了!</para>
- </listitem>
- </orderedlist>
- </sect3>
+ <programlisting>@daily root freebsd-update cron</programlisting>
+
+ <para>如果有新的修補,它們將會自動下載,但是還不會執行。
+ 管理者<systemitem
+ class="username">root</systemitem> 將會收到email來檢視修補然後手動執行
+ <command>freebsd-update install</command> 來安裝</para>
+
+ <para>如果有發生任何錯誤,<command>freebsd-update</command>
+ 可以使用以下指令回溯最後的變更:</para>
+
+ <screen>&prompt.root; <userinput>freebsd-update rollback</userinput>
+Uninstalling updates... done.</screen>
+
+ <para>再次,如果核心或任何核心模組有變更,系統將重新開機,受影響的二進位檔會重新執行。
+ </para>
+
+ <para>只有 <filename>GENERIC</filename> 核心可以自動被
+ <command>freebsd-update</command> 更新。
+ 如果有安裝自訂的核心,在<command>freebsd-update</command>
+ 完成安裝更新後,將會被重新編譯和重新安裝。
+ 然而,如果 <filename>/boot/GENERIC</filename> 存在,
+ <command>freebsd-update</command>將會偵測和更新 <filename>GENERIC</filename> 核心,
+ 即使他並非目前系統正在執行的核心。</para>
+
+ <note>
+ <para>永遠在 <filename>/boot/GENERIC</filename> 保留一份 <filename>GENERIC</filename>
+ 核心的備份。這對於診斷不同的問題與版本的升級有幫助。
+ 參考<xref
+ linkend="freebsd-update-custom-kernel-9x"/> 或 <xref
+ linkend="freebsd-update-custom-kernel-8x"/> 關於如何備份
+ <filename>GENERIC</filename> 核心的說明</para>
+ </note>
+
+ <para>除非 <filename>/etc/freebsd-update.conf</filename> 的預設設定被改變,
+ <command>freebsd-update</command>將安裝更新過的核心原始碼和其餘的更新
+ 然後就可以照平常的方式重新編譯和重新安裝新的自訂核心。</para>
+
+ <para>以 <command>freebsd-update</command> 發行的更新並非總是包含核心。
+ 如果核心的原始碼沒有被 <command>freebsd-update install</command> 變更,並不需要重新編譯自訂核心。
+ 然而 <command>freebsd-update</command> 總是會更新
+ <filename>/usr/src/sys/conf/newvers.sh</filename>。目前修補的程度,
+ 如同執行 <command>uname -r</command> 顯示的 <literal>-p</literal>
+ 數字是由這個檔案取得。
+ 即使沒有做任何改變,重新編譯核心會讓 <command>uname</command> 正確地報告目前系統修補的程度。
+ 這對於維護多個系統特別有幫助,可以讓你快速評估每個系統安裝的更新。</para>
</sect2>
- <sect2 xml:id="stable">
- <title>使用最新的 &os; STABLE</title>
+ <sect2 xml:id="freebsdupdate-upgrade">
+ <title>執行主要和次要的版本升級</title>
- <sect3>
- <title>什麼是 &os.stable;?</title>
- <indexterm><primary>-STABLE</primary></indexterm>
+ <para>從&os;的次要版本升級到另一個版本,例如從
+ &os;&nbsp;9.0 到 &os;&nbsp;9.1, 叫作
+ <firstterm>次要版本</firstterm>更新。
+ <firstterm>主要版本</firstterm>更新發生在當 &os;
+ 從一個主要版本升級到主要版本升級到另一個主要版本時
+,例如從 &os;&nbsp;9.X 到 &os;&nbsp;10.X。
+兩種更新都可以透過提供 <command>freebsd-update</command> 發行版本來執行。</para>
- <para>&os.stable; 是我們的開發分支,主要的發行版就由此而來。
- 這個分支會以不同速度作修改變化,並且假設這些是第一次進入 &os.current;
- 進行測試。 然而,這 <emphasis>仍然</emphasis> 屬於開發中的分支,
- 也就是說在某些時候,&os.stable; 可能會、也可能不會符合一些特殊需求。
- 它只不過是另一個開發分支而已,可能不太適合一般使用者。</para>
- </sect3>
+ <note>
+ <para>如果系統正在執行自訂的核心,開始升級前,
+ 確定 <filename>GENERIC</filename> 核心的副本在
+ <filename>/boot/GENERIC</filename>。
+ 參考<xref
+ linkend="freebsd-update-custom-kernel-9x"/> 或 <xref
+ linkend="freebsd-update-custom-kernel-8x"/> 關於如何製作
+ <filename>GENERIC</filename>核心副本的說明。</para>
+ </note>
- <sect3>
- <title>誰需要 &os.stable;?</title>
-
- <para>若您有興趣去追蹤、貢獻 FreeBSD 開發過程或作些貢獻,
- 尤其是會跟 FreeBSD 接下來的 <quote>關鍵性</quote> 發行有關,
- 應該考慮採用 &os.stable;。</para>
-
- <para>雖然安全漏洞的修補也會進入 &os.stable; 分支,
- 但不必僅僅因此而 <emphasis>需要</emphasis> 去用 &os.stable;。
- FreeBSD 每項 security advisory(安全公告)
- 都會解說如何去修復有受到影響的版本
- <footnote><para>然而,這也不一定是正確,我們不可能永遠支援 FreeBSD
- 昔日的各種發行版本,儘管每個發行版發佈之後,都仍會持續支援數年之久。
- 若欲瞭解 FreeBSD 目前對於舊版的支援政策細節,請參閱 <link xlink:href="&url.base;/security/">http://www.FreeBSD.org/security/</link>
- 。</para>
- </footnote>
- ,若僅因為安全因素而去採用開發分支,雖然會解決現有已知問題,
- 但也可能帶來一些潛藏的問題。</para>
-
- <para>儘管我們盡力確保 &os.stable; 分支在任何時候均能正確編譯、運作,
- 但沒人能夠擔保它隨時都可以符合上述目的。 此外,雖然原始碼在進入
- &os.stable; 之前,都會先在 &os.current; 開發完畢,但使用 &os.current;
- 的人畢竟遠比 &os.stable; 使用者來的少,所以通常有些問題,可能在
- &os.current; 比較沒人注意到,隨著 &os.stable;
- 使用者的廣泛使用才會浮現。</para>
-
- <para>由於上述這些理由,我們<emphasis>並不推薦</emphasis> 盲目追隨
- &os.stable;,而且更重要的是,別在原始碼尚未經完整測試之前,
- 就衝動把 production server 轉移到 &os.stable; 環境。</para>
-
- <para>若您沒有這些多的時間、精神的話,那推薦您使用最新的 FreeBSD
- 發行版即可,並採用其所提供的 binary 更新機制來完成升級轉移。</para>
- </sect3>
+ <para>以下的指令執行在 &os;&nbsp;9.0 系統時,
+ 將會把系統升級至 &os;&nbsp;9.1:</para>
- <sect3>
- <title>使用 &os.stable;</title>
+ <screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen>
- <orderedlist>
- <listitem>
- <para>訂閱 &a.stable.name;<indexterm><primary>-STABLE</primary><secondary>using</secondary></indexterm> list。 可以讓您隨時瞭解 &os.stable;
- 的軟體編譯時的相依關係,以及其他需特別注意的問題。
- 開發者在考慮一些有爭議的修正或更新時,就會先在這裡發信說明,
- 給使用者有機會可以反應,
- 看他們對所提的更改是否有什麼建議或問題。</para>
+ <para>當收到這個指令後,
+ <command>freebsd-update</command> 將會評估設定檔和目前的系統來收集升級需要的資訊。
+ 螢幕上的清單會顯示偵測到或沒偵測到哪些元件。例如: </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.
- <para>而 &a.cvsall.name; list 這邊可以看到每個 commit log,
- 其中包括了許多中肯的資訊,例如一些可能發生的邊際效應等等。</para>
+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
- <para>想要加入這些通信論壇的話,只要到 &a.mailman.lists.link;
- 點下想訂閱的 list 即可。 其餘的步驟在網頁上會有說明。</para>
- </listitem>
+The following components of FreeBSD do not seem to be installed:
+kernel/generic world/catpages world/dict world/doc world/games
+world/proflibs
- <listitem>
- <para>若打算要安裝一個全新的系統,並且希望裝 &os.stable;
- 每月定期的 snapshot,那麼請參閱 <link xlink:href="&url.base;/snapshots/">Snapshots</link> 網頁以瞭解相關細節。
- 此外,也可從 <link linkend="mirrors">mirror 站</link>
- 來安裝最新的 &os.stable; 發行版,並透過下列的的說明來更新到最新的
- &os.stable; 原始碼。</para>
-
- <para>若已裝的是 &os; 以前的版本,而想透過原始碼方式來升級,
- 那麼也是可以利用 &os; <link linkend="mirrors">mirror 站</link>
- 來完成。 以下介紹兩種方式:</para>
-
- <orderedlist>
- <listitem>
- <para>以 <link linkend="cvsup">csup</link><indexterm><primary><command>cvsup</command></primary></indexterm> 或
- <link linkend="cvsup">cvsup</link> 程式搭配位於
- <filename>/usr/share/examples/cvsup</filename> 檔名為
- <filename>stable-supfile</filename> 的
- <filename>supfile</filename>。 這是大家最常推薦的方式,
- 因為它可以讓你把整個 tree 都抓回來,
- 之後就只取有更新的部分即可。
- 此外,許多人會把 <command>csup</command> 或
- <command>cvsup</command> 放到 <command>cron</command><indexterm><primary><command>cron</command></primary></indexterm>
- 以定期自動更新。 您須要自訂前述的
- <filename>supfile</filename> 範例檔,並針對自身網路環境以調整
- <link linkend="cvsup">csup</link> 或
- <link linkend="cvsup">cvsup</link><indexterm><primary>-STABLE</primary><secondary>syncing with <application>CVSup</application></secondary></indexterm> 相關設定。</para>
- </listitem>
-
- <listitem>
- <para>使用 <application>CTM</application><indexterm><primary>-STABLE</primary><secondary>syncing with CTM</secondary></indexterm> 更新工具。
- 若網路不快或網路費用貴,那麼可以考慮採用。</para>
- </listitem>
- </orderedlist>
- </listitem>
+Does this look reasonable (y/n)? <userinput>y</userinput></screen>
- <listitem>
- <para>一般而言,若常需存取最新原始碼,而不計較網路頻寬的話,
- 可以使用 <command>csup</command> 或 <command>cvsup</command>
- 或 <command>ftp</command>。 否則,就考慮
- <application>CTM</application>。</para>
- </listitem>
+ <para>此時,<command>freebsd-update</command> 將嘗試下載所有升級需要的檔案。
+在某些案例,使用者會被提示一些關於安裝什麼或是如何進行的問題。</para>
- <listitem>
- <para>在編譯 &os.stable;<indexterm><primary>-STABLE</primary><secondary>compiling</secondary></indexterm> 之前,請先仔細閱讀
- <filename>/usr/src</filename> 內的 <filename>Makefile</filename>
- 檔。 儘管只是升級部分東西而已,您至少也要先 <link linkend="makeworld">裝新的 kernel 以及重新編譯 world</link>。
- 此外,多多閱讀 &a.stable; 以及
- <filename>/usr/src/UPDATING</filename> 也是必備的,
- 這樣才能知道目前進度是怎樣,以及下一版會有哪些新東西。</para>
- </listitem>
- </orderedlist>
- </sect3>
- </sect2>
- </sect1>
+ <para>當使用自訂核心,上述的步驟將會產生如下列的警告:</para>
- <sect1 xml:id="synching">
- <title>更新你的 Source</title>
+ <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>&os; 計劃原始碼有許多透過網路(或 email)的方式來更新,
- 無論是更新那一塊領域,這些全由您自行決定。 我們主要提供的是 <link linkend="anoncvs">Anonymous CVS</link>、<link linkend="cvsup">CVSup</link>
- 、<link linkend="ctm">CTM</link>。</para>
+ <para>這個警告可以安全地忽略,升級過程將會立即使用更新過的
+ <filename>GENERIC</filename> 核心</para>
- <warning>
- <para>雖然可以只更新部分原始碼,但唯一支援的更新流程是更新整個 tree,
- 並且重編 userland(比如:由使用者去執行的所有程式,像是
- <filename>/bin</filename>、<filename>/sbin</filename> 內的程式)以及
- kernel 原始碼。
- 若只更新部分的 source tree、或只有 kernel 部分、或只有 userland
- 部分,通常會造成一些錯誤,像是:編譯錯誤、kernel panic、資料毀損等
- 。</para>
- </warning>
+ <para>一旦所有的修補都被下載到本地的系統,
+ 它們將會被運用。這個過程可能會花點時間,取決於機器的速度和工作量
+ 設定檔將會被合併。
+ 合併的過程中當檔案被合併或是手動合併螢幕上出現編輯器時需要使用者介入。
+ 每一個成功合併的結果將會顯示給使用者。
+ 失敗或是被忽略的合併將會使程序中斷。使用者稍候可能想要備份
+ <filename>/etc</filename> 和手動合併重要的檔案,例如:
+ <filename>master.passwd</filename> 或
+ <filename>group</filename> 。</para>
- <indexterm>
- <primary>CVS</primary>
- <secondary>anonymous</secondary>
- </indexterm>
+ <note>
+ <para>當所有修補和合併在另一個目錄進行時,系統還不會被警告。
+ 一旦所有修補都成功運用,所有設定檔都被合併,而且過程順利,使用者可以以下指令來將這些改變付諸於磁碟上:</para>
- <para><application>Anonymous CVS</application> 及
- <application>CVSup</application> 均是採 <emphasis>pull</emphasis>
- 模式來更新原始碼。 以 <application>CVSup</application> 為例,
- 使用者(或 <command>cron</command> script)會執行 <command>cvsup</command>
- 程式,後者會與某一台 <command>cvsupd</command> 伺服器作些互動,
- 以更新相關原始碼檔案。 您所收到更新會是當時最新的,
- 而且只會收到需更新的部分。 此外,也可以很輕鬆去設定要更新的範圍。
- 更新會由伺服器跟本機比對之後,丟出當時您所需要的更新檔案給你。
- <application>Anonymous CVS</application> 的概念相對於
- <application>CVSup</application> 來得更簡單些,因為它只是
- <application>CVS</application> 的延伸而已,一樣讓你可從遠端的
- CVS repository 取出最新原始碼。 然而 <application>CVSup</application>
- 在這方面會更有效率,不過 <application>Anonymous CVS</application>
- 對新手而言,是用起來比較簡單。</para>
+ <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
+ </note>
- <indexterm>
- <primary><application>CTM</application></primary>
- </indexterm>
- <para>另一種方式則是 <application>CTM</application>。
- 它並不是以交談式介面來比對您所擁有的 sources 和伺服器上的 sources
- 或是您取得的更新部份。 相反的,會有一個 script
- 檔專門用來辨識變更過的檔案,這個程式是由 CTM 伺服器來執行,
- 每天會比對數次,並把兩次執行期間內變更過的檔案加以壓縮,
- 並給它們一個序號,然後就加以編碼(只用 printable ASCII 字元),
- 並以 email 的方式寄出。 當您收到它的時候,這些 <quote>CTM deltas</quote>
- 就可以由 &man.ctm.rmail.1; 程式來處理,該程式會自動解碼、確認、
- 套用這些變更。 這程序比 <application>CVSup</application> 來說是快得多了,
- 而且,這個模式對我們的伺服器來說是比較輕鬆的,因為這是一個
- <emphasis>push</emphasis> 的模式,而非 <emphasis>pull</emphasis>
- 的模式。</para>
-
- <para>當然,這樣做也會帶來一些不便。 若不小心把您部份的程式清除掉了,
- <application>CVSup</application> 會偵測出來,並自動為您把不足的部份補齊。
- <application>CTM</application> 並不會為您做這些動作。
- 若清掉了您的部份 source (而且沒備份),您可以從頭開始(從最新的 CVS
- <quote>base delta</quote>)並用 <application>CTM</application> 來重建它們
- ,或是用 <application>Anonymous CVS</application> 來完成,
- 只要把不正確的地方砍掉,再重新做同步的動作即可。</para>
- </sect1>
+ <para>核心和核心模組將會先被修補。如果系統正在執行自訂核心,使用
+ &man.nextboot.8; 指令設定下次開機的核心為更新過的
+ <filename>/boot/GENERIC</filename>:</para>
- <sect1 xml:id="makeworld">
- <title>重新編譯 <quote>world</quote></title>
+ <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>
- <indexterm>
- <primary>Rebuilding <quote>world</quote></primary>
- </indexterm>
- <para>在更新 &os; 的 source tree 到最新之後(無論是 &os.stable;、
- &os.current; 等等),接下來就可以用這些 source tree 來重新編譯系統
- 。</para>
+ <warning>
+ <para>如果機器以遠端遙控來更新,
+ 使用<filename>GENERIC</filename>核心重新開機前,
+ 確定他包含所有系統開機需要的驅動程式而且連接網路,
+ 特別是當執行的自訂核心包含核心模組提供內建功能時,
+ 確定暫時地使用 <filename>/boot/loader.conf</filename> 工具載入這些模組到 <filename>GENERIC</filename> 核心。
+ 建議停用非必須的服務和磁碟與網路掛載直到升級程序完成。
+ </para>
+ </warning>
- <warning>
- <title>做好備份</title>
+ <para>機器現在應該更新過的核心重新開機:
+ </para>
- <para>在作任何大動作 <emphasis>之前</emphasis>
- 要記得先把系統作備份的重要性無須強調。 儘管重新編譯 world 是
- (只要有照文件指示去作的話)一件很簡單的事情,但出錯也是在所難免的。
- 另外,別人在 source tree 不慎搞混的錯誤,也可能會造成系統無法開機
- 。</para>
+ <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
- <para>請確認自己已作妥相關備份,並且手邊有 fixit 磁片或開機光碟。
- 您可能永遠也用不到這些東西,
- 但安全第一總比事後說抱歉來得好吧!</para>
- </warning>
+ <para>一旦系統重新上線,使用以下指令重新開始
+ <command>freebsd-update</command>。
+ 因為程序的狀態已被儲存,
+ <command>freebsd-update</command> 將不會重頭開始,他會進行到下一個階段
+ ,移除所有舊的共用程式庫和目標檔。</para>
- <warning>
- <title>訂閱相關的 Mailing List</title>
+ <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
- <indexterm><primary>mailing list</primary></indexterm>
- <para>&os.stable; 以及 &os.current; 分支,本質上就是屬於 <emphasis>
- 開發階段</emphasis>。 為 &os; 作貢獻的也都是人,偶爾也會犯錯誤。</para>
+ <note>
+ <para>根據程式庫版本編號, 可能有兩個而不是三個安裝階段。</para>
+ </note>
+
+ <para>升級程序現在完成了。如果這是主要的版本升級,參考
+ <xref linkend="freebsdupdate-portsrebuild"/>
+ 的描述重新安裝所有的ports和套件。</para>
+
+ <sect3 xml:id="freebsd-update-custom-kernel-9x">
+ <title> &os;&nbsp;9.X 以上自訂核心</title>
+
+ <para>使用 <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/kernel</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>
- <para>有時候這些錯誤並無大礙,只是會讓系統產生新的錯誤警告而已。
- 有時則是災難,可能會導致不能開機或檔案系統的毀損(或更糟)。</para>
+ <sect3 xml:id="freebsd-update-custom-kernel-8x">
+ <title>&os;&nbsp;8.X 自訂核心</title>
+
+ <para>On an &os;&nbsp;8.X system, the instructions for
+ obtaining or building a <filename>GENERIC</filename> kernel
+ differ slightly.</para>
+
+ <para>Assuming physical access to the machine is possible, a
+ copy of the <filename>GENERIC</filename> kernel can be
+ installed from the installation media using the following
+ commands:</para>
+
+ <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
+&prompt.root; <userinput>./install.sh GENERIC</userinput></screen>
+
+ <para>Replace <filename
+ ><replaceable>X.Y-RELEASE</replaceable></filename>
+ with the version of the release being used. The
+ <filename>GENERIC</filename> kernel will be installed in
+ <filename>/boot/GENERIC</filename> by default.</para>
+
+ <para>To instead build the <filename>GENERIC</filename> kernel
+ from source:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput>
+&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
+&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>
+
+ <para>For this kernel to be picked up as
+ <filename>GENERIC</filename> by
+ <command>freebsd-update</command>, the
+ <filename>GENERIC</filename> configuration file must not
+ have been modified in any way. It is also suggested that it
+ is built without any other special options.</para>
+
+ <para>Rebooting into the <filename>GENERIC</filename> kernel
+ is not required.</para>
+ </sect3>
- <para>若遇到類似問題,貼封標題為 <quote>heads up(注意)</quote>
- 開頭的信到相關的 mailing list,並講清楚問題點以及會影響哪些系統。
- 在問題獲解決後,再貼標題為 <quote>all clear(已解決)</quote>
- 開頭的聲明信。</para>
+ <sect3 xml:id="freebsdupdate-portsrebuild">
+ <title>主要版本更新後更新 Packages</title>
- <para>若用的是 &os.stable; 或 &os.current;,卻又不閱讀 &a.stable; 或
- &a.current; 的討論,那麼會是自找麻煩而已。</para>
- </warning>
+ <para>一般來說,次要版本更新後安裝的應用程式可以沒有問題地繼續執行。
+ 主要版本間使用不同的應用程式二進位介面 Application Binary Interfaces
+ (<acronym>ABI</acronym>s),會破壞大部份第三方應用程式。
+ 主要版本更新後,所有安裝的套件和 ports 需要使用應用程式來升級,例如
+ <package>ports-mgmt/portmaster</package>
+ 重新編譯所有應用程式,可以使用以下指令完成:</para>
- <warning>
- <title>不要用 <command>make world</command></title>
+ <screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
- <para>一堆早期的舊文件都會建議說使用 <command>make world</command>。
- 這樣做會跳過一些重要步驟,建議只有在你知道自己在作什麼,再這麼做。
- 在絕大多數的情況下,請不要亂用 <command>make world</command>,
- 而該改用下面介紹的方式。</para>
- </warning>
+ <para>這個指令將會顯示每個程式的設定選項設定畫面,等待使用者的互動。
+ 如果要使用預設的選項,可以在上述指令使用<option>-G</option>選項。
+ </para>
- <sect2>
- <title>更新系統的標準方式</title>
+ <para>一旦軟體升級完成, 執行
+ <command>freebsd-update</command> 來完成所有升級過程的零碎事情 :</para>
- <para>要升級系統前,一定要先查閱 <filename>/usr/src/UPDATING</filename>
- 文件,以瞭解 buildworld 之前需要作哪些事情或注意事項,
- 然後才用下列步驟:</para>
+ <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
- <screen>&prompt.root; <userinput>make buildworld</userinput>
-&prompt.root; <userinput>make buildkernel</userinput>
-&prompt.root; <userinput>make installkernel</userinput>
-&prompt.root; <userinput>reboot</userinput></screen>
+ <para>如果是暫時使用 <filename>GENERIC</filename> 核心,
+ 現在請使用
+ <xref linkend="kernelconfig"/>的說明編譯和安裝新的自訂核心。</para>
- <note>
- <para>在少數狀況,可能需要先在 <buildtarget>buildworld</buildtarget>
- 步驟之前先作 <command>mergemaster -p</command> 才能完成。
- 至於何時需要或不需要,請參閱 <filename>UPDATING</filename> 內的說明。
- 一般來說,只要不是進行跨版號(major)的 &os; 版本升級,
- 就可略過這步驟。</para>
- </note>
+ <para>重新開機進入新版的 &os;。現在已經完成升級過程了。
+ </para>
+ </sect3>
+ </sect2>
- <para>完成 <buildtarget>installkernel</buildtarget> 之後,需要重開機並切到
- single user 模式(舉例:也可以在 loader 提示符號後面加上
- <command>boot -s</command>)。 接下來執行:</para>
+ <sect2 xml:id="freebsdupdate-system-comparison">
+ <title>系統狀態比較</title>
- <screen>&prompt.root; <userinput>mergemaster -p</userinput>
-&prompt.root; <userinput>make installworld</userinput>
-&prompt.root; <userinput>mergemaster</userinput>
-&prompt.root; <userinput>reboot</userinput></screen>
+ <para>已安裝的 &os; 版本可以使用 <command>freebsd-update IDS</command>
+來跟另一個已知好的複製版本來做測試。
+這個指令評估系統應用程式,程式庫和設定檔案目前的版本,
+可以被當成內建的入侵偵測系統來使用 (<acronym>IDS</acronym>)。</para>
<warning>
- <title>Read Further Explanations</title>
-
- <para>上述步驟只是協助您升級的簡單說明而已,若要清楚瞭解每一步驟,
- 尤其是若欲自行打造 kernel 設定,就更該閱讀下面的內容。</para>
+ <para>這個指令不是取代真正的
+ <acronym>IDS</acronym> ,例如
+ <package>security/snort</package>。當
+ <command>freebsd-update</command> 儲存資料在磁碟裡,是有被竄改的可能性
+ 可以使用 <varname>kern.securelevel</varname>
+ 或是將沒有在使用的 <command>freebsd-update</command>
+ 的資料儲存在唯讀檔案系統來減少這樣的可能性,
+ 比較好的解決方法是將系統和安全的磁碟,例如
+ <acronym>DVD</acronym> 或是安全的外接
+ <acronym>USB</acronym> 磁碟裝置做比較。
+ 另類的方法是使用在 <xref linkend="security-ids"/> 描述的內建應用程式提供的
+ <acronym>IDS</acronym> 功能</para>
</warning>
- </sect2>
- <sect2>
- <title>閱讀 <filename>/usr/src/UPDATING</filename></title>
+ <para>為了開始比較,先指定特定的輸出檔案來儲存結果:</para>
- <para>在作任何事情之前,請務必先閱讀
- <filename>/usr/src/UPDATING</filename> (或在 source code 內類似的文件)
- 。 這份文件會寫到可能遭遇的問題,或指定那些會執行的指令順序為何。
- 如果你機器現在的 <filename>UPDATING</filename>
- 文件與這邊的描述有衝突、矛盾之處,那麼請以機器上的
- <filename>UPDATING</filename> 為準。</para>
+ <screen>&prompt.root; <userinput>freebsd-update IDS &gt;&gt; outfile.ids</userinput></screen>
- <important>
- <para>然而,如同先前所述,單單只靠閱讀 <filename>UPDATING</filename>
- 並不能完全取代 mailing list。 這兩者都是互補的,而不相排斥。</para>
- </important>
- </sect2>
+ <para>現在系統將會被檢查,
+ 而包含已知發行版和現在安裝版的<acronym>SHA256</acronym>雜湊值
+ 的冗長檔案清單將會被送至指定的輸出檔。</para>
- <sect2>
- <title>檢查 <filename>/etc/make.conf</filename></title>
- <indexterm>
- <primary><filename>make.conf</filename></primary>
- </indexterm>
+ <para>清單的項目相當長,但是輸出格式很容易被分析。
+ 例如,要獲得一個和發行版不同的檔案清單,可以下以下指令:</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>檢查
- <filename>/usr/share/examples/etc/make.conf</filename>
- 以及
- <filename>/etc/make.conf</filename>。 第一份文件乃是一些系統預設值
- &ndash; 不過,大部分都被註解起來。 為了在重新編譯時能夠使用這些,
- 請把這些設定加到 <filename>/etc/make.conf</filename>。 請注意在
- <filename>/etc/make.conf</filename> 的任何設定也會影響到每次使用
- <command>make</command> 的結果,
- 因此設定一些適合自己系統的選項會是不錯的作法。</para>
-
- <para>一般使用者通常會從
- <filename>/usr/share/examples/etc/make.conf</filename> 複製
- <varname>CFLAGS</varname> 以及 <varname>NO_PROFILE</varname>
- 之類的設定到 <filename>/etc/make.conf</filename>,並解除相關註解印記
- 。</para>
-
- <para>此外,也可以試試看其他設定 (<varname>COPTFLAGS</varname>、
- <varname>NOPORTDOCS</varname> 等等),是否符合自己所需。</para>
+ <para>這個輸出範例已經被截短,原來有更多的檔案存在。
+ 有些檔案自然會有修改。例如,如果有使用者被加入系統,
+ <filename>/etc/passwd</filename> 會被修改
+ 如果 <command>freebsd-update</command> 有更新過,核心模組可能會不同
+ 為了要排除特定的檔案或目錄,把它們加到<filename>/etc/freebsd-update.conf</filename> 裡的 <literal>IDSIgnorePaths</literal> 選項。</para>
</sect2>
+ </sect1>
- <sect2>
- <title>更新 <filename>/etc</filename> 內的設定檔</title>
+ <sect1 xml:id="updating-upgrading-documentation">
+ <title>更新文件組</title>
- <para>在 <filename>/etc</filename> 目錄會有系統的相關設定檔,
- 以及開機時的各項服務啟動 script。 有些 script 隨 FreeBSD
- 版本的不同而有些差異。</para>
+ <indexterm><primary>更新和升級</primary></indexterm>
- <para>其中有些設定檔會在每日運作的系統裡也會用到。 尤其是
- <filename>/etc/group</filename>。</para>
+ <indexterm>
+ <primary>文件</primary>
+ <see>更新和升級</see>
+ </indexterm>
- <para>有時候在 <command>make installworld</command> 安裝過程中,
- 會需要先建立某些特定帳號或群組。 在進行升級之前,它們可能並不存在,
- 因此升級時就會造成問題。 有時候 <command>make buildworld</command>
- 會先檢查這些所需的帳號或群組是否已有存在。</para>
+ <para>文件是&os;作業系統不可或缺的一部份。
+ 最新版本的 &os; 文件可以在
+ &os; 網站取得(<link
+ xlink:href="&url.base;/doc/">http://www.freebsd.org/doc/</link>),
+ 很方便有一份最新的&os;
+ 網站,使用手冊, <acronym>常見問答</acronym>和文章的本地端副本。</para>
- <para>舉個這樣的例子,像是某次升級之後必須新增 <systemitem class="username">smmsp</systemitem>
- 帳號。 若使用者尚未新增該帳號就要完成升級操作的話,
- 會在 &man.mtree.8; 嘗試建立 <filename>/var/spool/clientmqueue</filename>
- 時發生失敗。</para>
+ <para>這一節描述如何使用原始碼或是
+ &os; Ports 管理機制將
+ 本地端&os;文件保持最新。</para>
- <para>解法是在 buildworld 階段之前,先執行 &man.mergemaster.8; 並搭配
- <option>-p</option> 選項。 它會比對那些執行
- <buildtarget>buildworld</buildtarget> 或
- <buildtarget>installworld</buildtarget> 所需之關鍵設定檔。
- 若你所用的是早期仍未支援 <option>-p</option> 的
- <command>mergemaster</command> 版本,那麼直接使用 source tree
- 內的新版即可:</para>
+ <para>編輯和發佈文件更正的資訊
+ 請參考 &os; 文件計劃新貢獻者入門書
+ (<link
+ xlink:href="&url.books.fdp-primer;">http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para>
- <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/mergemaster</userinput>
-&prompt.root; <userinput>./mergemaster.sh -p</userinput></screen>
+ <sect2 xml:id="updating-installed-documentation">
+ <title>從原始碼更新文件</title>
- <tip>
- <para>若您是偏執狂(paranoid),
- 可以像下面這樣去試著檢查系統上有哪些檔案屬於已改名或被刪除的群組
- :</para>
+ <para>重新從原始碼編譯&os; 文件需要一些不是屬於
+ &os; 基礎系統的工具
+ 這些需要的工具包括
+ <application>svn</application> 可以從
+ <package>textproc/docproj</package> 套件安裝或是
+ &os; 文件計劃的開發的port</para>
- <screen>&prompt.root; <userinput>find / -group GID -print</userinput></screen>
+ <para>一旦安裝好,請使用 <application>svn</application>
+ 來取得乾淨的文件原始碼副本。
+ 將 <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>
+ 置換成 <xref linkend="svn-mirrors"/> 裡地理位置和你最近的鏡像站:</para>
- <para>這會顯示所有符合要找的 <replaceable>GID</replaceable> 群組
- (可以是群組名稱,或者是群組的數字代號)的所有檔案。</para>
- </tip>
- </sect2>
+ <screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen>
- <sect2 xml:id="makeworld-singleuser">
- <title>切換到 Single User 模式</title>
- <indexterm><primary>single-user mode</primary></indexterm>
+ <para>第一次下載文件原始碼需要花點時間,請讓他執行完畢</para>
- <para>您可能會想在 single user 模式下編譯系統。
- 除了可以明顯更快完成之外,安裝過程中將會牽涉許多重要的系統檔案,
- 包括所有系統 binaries、libraries、include 檔案等。
- 若在運作中的系統(尤其有許多使用者在用的時候)內更改這些檔案,
- 那簡直是自找麻煩的作法。</para>
+ <para>將來文件原始碼更新的取得可以執行:</para>
- <indexterm><primary>multi-user mode</primary></indexterm>
- <para>另一種模式是先在 multi-user 模式下編譯好系統,然後再切到 single user
- 模式去安裝。 若您比較喜歡這種方式,只需在 build(編譯過程) 完成之後,
- 再去執行下面的步驟即可。 一直到可切換 single user 模式時,再去執行
- <buildtarget>installkernel</buildtarget> 或
- <buildtarget>installworld</buildtarget> 即可。</para>
+ <screen>&prompt.root; <userinput>svn update /usr/doc</userinput></screen>
- <para>切換為 root 身份打:</para>
+ <para>當最新的文件原始碼快照已經抓取到
+ <filename>/usr/doc</filename>,一切都已就緒可以對已安裝的文件進行更新。</para>
- <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
+ <para>要完整更新所有語言,可以執行:</para>
- <para>這樣就會從原本的 multi-user 模式切換到 single user 模式。</para>
+ <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
- <para>除此之外也可以重開機,接著在開機選單處選擇
- <quote>single user</quote> 選項。 如此一來就會進入 single user 模式,
- 然後在 shell 提示符號處輸入:</para>
+ <para>如果只要更新一個特定的語言,可以在 <filename>/usr/doc</filename>
+中特定語言的子目錄執行 <command>make</command>:</para>
- <screen>&prompt.root; <userinput>fsck -p</userinput>
-&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput>
-&prompt.root; <userinput>swapon -a</userinput></screen>
+ <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
- <para>這樣會先檢查檔案系統,並重新將 <filename>/</filename>
- 改以可讀寫的模式掛載,以及 <filename>/etc/fstab</filename>
- 內所設定的其他 UFS 檔案系統,最後啟用 swap 磁區。</para>
+ <para>另一個更新文件的方法是在 <filename>/usr/doc</filename>
+或特定語言的子目錄執行:</para>
+ <screen>&prompt.root; <userinput>make update</userinput></screen>
- <note>
- <para>若 CMOS 時鐘是設為當地時間,而非 GMT 時區(若 &man.date.1;
- 指令沒顯示正確的時間、時區),那可能需要再輸入下列指令:</para>
-<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
+ <para>輸出格式可以經由設定 <varname>FORMATS</varname> 來指:</para>
- <para>這步驟可以確認您的當地時區設定是否正確 &mdash;
- 否則日後會造成一些問題。</para>
- </note>
+ <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
- </sect2>
+ <para>有幾個選項可以使得只要更新部份文件或是建立特定翻譯的過程更加簡易。
+這些選項可以在 <filename>/etc/make.conf</filename> 中設定成整個系統的選項,
+或是經由命令列傳送給 <command>make</command>。</para>
- <sect2>
- <title>移除 <filename>/usr/obj</filename></title>
+ <para>這些選項包括:</para>
- <para>在重新編譯系統的過程中,編譯結果會放到(預設情況)
- <filename>/usr/obj</filename> 內。 這裡面的目錄會對應到
- <filename>/usr/src</filename> 的目錄結構。</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>DOC_LANG</varname></term>
- <para>砍掉這目錄,可以讓以後的 <command>make buildworld</command>
- 過程更快一些,而且可避免以前編譯的東西跟現在的混淆在一起的相依錯亂
- 。</para>
+ <listitem>
+ <para>要建立或是安裝的語言和編碼清單,例如英文文件用
+ <literal>en_US.ISO8859-1</literal>。</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>FORMATS</varname></term>
- <para>而有些 <filename>/usr/obj</filename> 內的檔案可能會設定不可更動的
- flag(細節請參閱 &man.chflags.1;),而必須先拿掉這些 flag 設定才行
- 。</para>
+ <listitem>
+ <para>單一格式或是要建立的輸出格式清單。目前支援 <literal>html</literal>,
+ <literal>html-split</literal>, <literal>txt</literal>,
+ <literal>ps</literal>, 和 <literal>pdf</literal>。</para>
+ </listitem>
+ </varlistentry>
- <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
-&prompt.root; <userinput>chflags -R noschg *</userinput>
-&prompt.root; <userinput>rm -rf *</userinput></screen>
+ <varlistentry>
+ <term><varname>DOCDIR</varname></term>
+
+ <listitem>
+ <para>安裝文件的位置。預設裝在
+ <filename>/usr/share/doc</filename>。</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>更多關於&os;全系統的<command>make</command> 變數,
+ 請參考&man.make.conf.5;。</para>
</sect2>
- <sect2 xml:id="cutting-edge-compilebase">
- <title>重新編譯 Base System</title>
-
- <sect3>
- <title>保留編譯的紀錄</title>
-
- <para>建議養成好習慣,把執行 &man.make.1; 時產生的紀錄存起來。
- 這樣若有哪邊出錯,就會有錯誤訊息的紀錄。 雖然單單這樣,
- 你可能不知道如何分析是哪邊出了岔,但若把你問題記錄貼到 &os; 相關的
- mailing list 就可以有人可以幫忙看是怎麼一回事情。</para>
-
- <para>最簡單的方是就是用 &man.script.1; 指令,並加上參數
- (你想存放記錄的檔案位置、檔名)即可。
- 這步驟應該在重新編譯系統時就要作,然後在完成編譯後輸入
- <userinput>exit</userinput> 即可離開。</para>
-
- <screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
-Script started, output file is /var/tmp/mw.out
-&prompt.root; <userinput>make TARGET</userinput>
-<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>
-&prompt.root; <userinput>exit</userinput>
-Script done, &hellip;</screen>
-
- <para>對了,還有一點儘量<emphasis>別把</emphasis>檔案存到
- <filename>/tmp</filename> 目錄內。 因為重開機之後,
- 這目錄內的東西都會被清空。 比較妥善的地方是
- <filename>/var/tmp</filename> (如上例所示) 或者是
- <systemitem class="username">root</systemitem> 的家目錄。</para>
- </sect3>
+ <sect2 xml:id="doc-ports-install-package">
+ <info>
+ <title>從 Ports 更新文件</title>
- <sect3 xml:id="make-buildworld">
- <title>編譯 Base System</title>
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ </personname>
+ <contrib>Based on the work of </contrib>
+ </author>
+ </authorgroup>
+ </info>
- <para>首先請先切換到 <filename>/usr/src</filename> 目錄:</para>
+ <indexterm>
+ <primary>Updating and Upgrading</primary>
+ </indexterm>
- <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
+ <indexterm>
+ <primary>documentation package</primary>
+ <see>Updating and Upgrading</see>
+ </indexterm>
- <para>(當然,除非你把 source code 放到其他地方,若真是這樣,
- 就切換到那個目錄即可)。</para>
- <indexterm><primary><command>make</command></primary></indexterm>
+ <para>前一節說明了從原始碼更新 &os; 文件的方法。本節敘述使用 Ports Collection 的另一種方法:</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&nbsp;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>
- <para>使用 &man.make.1; 指令來重新編譯 world。
- 這指令會從 <filename>Makefile</filename> 檔(這檔會寫 &os;
- 的程式該如何重新編譯、以哪些順序來編譯等等)去讀取相關指令。</para>
+ <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>一般下指令的格式如下:</para>
+ <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>make -x -DVARIABLE target</userinput></screen>
+ <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
- <para>在這個例子,<option>-<replaceable>x</replaceable></option>
- 是你想傳給 &man.make.1; 的選項,細節說明請參閱 &man.make.1; 說明,
- 裡面有相關範例說明。</para>
+ <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><option>-D<replaceable>VARIABLE</replaceable></option>
- 則是把變數設定傳給 <filename>Makefile</filename>。 這些變數會控制
- <filename>Makefile</filename> 的行為。 這些設定與
- <filename>/etc/make.conf</filename> 的變數設定是一樣,
- 只是另一種設定方式而已。</para>
+ <para>Alternately, several <command>make</command> options can
+ be specified when building a documentation port,
+ including:</para>
- <screen>&prompt.root; <userinput>make -DNO_PROFILE target</userinput></screen>
+ <variablelist>
+ <varlistentry>
+ <term><varname>WITH_HTML</varname></term>
- <para>上面的例子則是另一種設定方式,也就是哪些不要。
- 這個例子中的意思是不去編譯 profiled libraries,效果就如同設定在
- <filename>/etc/make.conf</filename> 的</para>
+ <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>
- <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting>
+ <varlistentry>
+ <term><varname>WITH_PDF</varname></term>
- <para><replaceable>target</replaceable> 則是告訴 &man.make.1;
- 該去做哪些。 每個 <filename>Makefile</filename> 都會定義不同的
- <quote>targets</quote>,然後依您所給的 target 就會決定會做哪些動作
- 。</para>
+ <listitem>
+ <para>The formatted documentation is saved to a file
+ called <filename>article.pdf</filename> or
+ <filename>book.pdf</filename>.</para>
+ </listitem>
+ </varlistentry>
- <para>Some targets are listed in the
- <filename>Makefile</filename>, but are not meant for you to run.
- Instead, they are used by the build process to break out the
- steps necessary to rebuild the system into a number of
- sub-steps.</para>
+ <varlistentry>
+ <term><varname>DOCBASE</varname></term>
- <para>Most of the time you will not need to pass any parameters to
- &man.make.1;, and so your command like will look like
- this:</para>
+ <listitem>
+ <para>Specifies where to install the documentation. It
+ defaults to
+ <filename>/usr/local/share/doc/freebsd</filename>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <screen>&prompt.root; <userinput>make target</userinput></screen>
+ <para>This example uses variables to install the Hungarian
+ documentation as a <acronym>PDF</acronym> in the specified
+ directory:</para>
- <para>Where <replaceable>target</replaceable> will be one of
- many build options. The first target should always be
- <varname>buildworld</varname>.</para>
+ <screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu
+&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen>
- <para>As the names imply, <buildtarget>buildworld</buildtarget>
- builds a complete new tree under <filename>/usr/obj</filename>,
- and <buildtarget>installworld</buildtarget>, another target, installs this tree on
- the current machine.</para>
+ <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>
- <para>Having separate options is very useful for two reasons. First, it allows you
- to do the build safe in the knowledge that no components of
- your running system will be affected. The build is
- <quote>self hosted</quote>. Because of this, you can safely
- run <buildtarget>buildworld</buildtarget> on a machine running
- in multi-user mode with no fear of ill-effects. It is still
- recommended that you run the
- <buildtarget>installworld</buildtarget> part in single user
- mode, though.</para>
+ <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen>
+ </sect2>
+ </sect1>
- <para>Secondly, it allows you to use NFS mounts to upgrade
- multiple machines on your network. If you have three machines,
- <systemitem>A</systemitem>, <systemitem>B</systemitem> and <systemitem>C</systemitem> that you want to upgrade, run <command>make
- buildworld</command> and <command>make installworld</command> on
- <systemitem>A</systemitem>. <systemitem>B</systemitem> and <systemitem>C</systemitem> should then NFS mount <filename>/usr/src</filename>
- and <filename>/usr/obj</filename> from <systemitem>A</systemitem>, and you can then run
- <command>make installworld</command> to install the results of
- the build on <systemitem>B</systemitem> and <systemitem>C</systemitem>.</para>
+ <sect1 xml:id="current-stable">
+ <title>追蹤發展分支</title>
- <para>Although the <buildtarget>world</buildtarget> target still exists,
- you are strongly encouraged not to use it.</para>
+ <indexterm><primary>-CURRENT</primary></indexterm>
+ <indexterm><primary>-STABLE</primary></indexterm>
- <para>Run</para>
+ <para>&os; 有兩個發展分支: &os.current; and
+ &os.stable;.</para>
- <screen>&prompt.root; <userinput>make buildworld</userinput></screen>
+ <para>本節將將解釋每個分支和他的預設的使用者,以及如何保持每個分支系統在最新。</para>
- <para>It is possible to specify a <option>-j</option> option to
- <command>make</command> which will cause it to spawn several
- simultaneous processes. This is most useful on multi-CPU machines.
- However, since much of the compiling process is IO bound rather
- than CPU bound it is also useful on single CPU machines.</para>
+ <sect2 xml:id="current">
+ <title>使用 &os.current;</title>
+
+ <para>&os.current; 是 &os; 開發的<quote>最前線</quote>,&os.current;的使用者應有較強的技術能力。
+ 技術能力較弱的使用者想追蹤發展分支應該追蹤 &os.stable;。</para>
+
+ <para>&os.current; 是 &os; 最新的原始碼,包括正在進行的工作,
+ 實驗性的改變,以及可能會或可能不會在下一個官方發行版出現的過渡時期機制。
+ 而許多 &os; 開發者每天編譯
+ &os.current; 原始碼,可能有一段短暫的時間原始碼無法編譯成功。
+ 這些問題會儘快被解決,但是無論
+ &os.current; 帶來災難或是新功能,在同步原始碼時都要考量的問題。</para>
+
+ <para>&os.current; 適合下列三類人:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>積極致力於某一部份原始碼樹的 &os; 社群成員。</para>
+ </listitem>
+
+ <listitem>
+ <para>擔任積極測試者的 &os; 社群成員。
+ 他們願意花時間解決問題,提出 &os; 改變的建議和的大方向,並發布修補。</para>
+ </listitem>
+
+ <listitem>
+ <para>關注某些事物,或是想參考目前的原始碼,或是偶爾提供註解或貢獻原始碼的使用者。</para>
+ </listitem>
+ </orderedlist>
+
+ <para>&os.current; <emphasis>不應該</emphasis>被認為是在下一版發行前
+ 取得最新功能的快速途徑,因為尚未發行的功能並未被完整測試,很可能有bug。
+ 他也不是一個取得bug修補的快速方式,
+ 因為任何已知bug的修補有可能產生新的bug。
+ &os.current; 沒有任何
+ <quote>官方支援</quote>。</para>
- <para>On a typical single-CPU machine you would run:</para>
+ <indexterm>
+ <primary>-CURRENT</primary>
+ <secondary>using</secondary>
+ </indexterm>
- <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
+ <para>追蹤 &os.current;:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>加入 &a.current.name; 和
+ &a.svn-src-head.name; 郵件論壇。這是<emphasis>必須的</emphasis>
+ 以查看人們關於系統目前狀態的評論並接收 &os.current; 目前狀態的重要公告。</para>
+
+ <para> &a.svn-src-head.name; 論壇紀錄每一次修改的紀錄,
+ 和可能產生的副作用的相關資訊 </para>
+
+ <para>前往 &a.mailman.lists.link;,點選論壇來訂閱,照網頁指示的步驟作,
+ 為了追蹤整個原始碼樹,不是只有 &os.current; 的改變,請訂閱
+ &a.svn-src-all.name;論壇。</para>
+ </listitem>
+
+ <listitem>
+ <para>同步 &os.current; 原始碼。
+ 通常使用 <link linkend="svn">svn</link> 來檢查<xref linkend="svn-mirrors"/>
+ 列出的 Subversion 鏡像站 <literal>head</literal> 分支的-CURRENT 原始碼。</para>
+
+ <para>網路很慢或是受到限制的使用者可以如<xref linkend="ctm"/>
+ 所描述的,使用 CTM 來替代,但是他並不如 <application>svn</application>
+ 一樣值得信賴, <application>svn</application> 是建議的同步原始碼的方法。</para>
+ </listitem>
+
+ <listitem>
+ <para> 由於程式碼庫的大小的,
+ 有些使用者選擇只同步部份他們有興趣或提供修補貢獻的部份原始碼。然而,
+ 計劃從原始碼編譯整個作業系統的使用者必須下載 <emphasis>全部</emphasis>
+ 的&os.current;,而不是只有選擇的部份。</para>
+
+ <para>編譯 &os.current; 前
+ <indexterm>
+ <primary>-CURRENT</primary>
+ <secondary>compiling</secondary>
+ </indexterm>,請非常仔細地閱讀 <filename>/usr/src/Makefile</filename>
+ 並遵從 <xref linkend="makeworld"/>的指示。
+ 閱讀 &a.current; 和 <filename>/usr/src/UPDATING</filename>
+ 來掌握下一發行版的最新狀態。</para>
+ </listitem>
+
+ <listitem>
+ <para>熱血!很鼓勵 &os.current; 使用者
+ 發表他們對加強哪些功能或是修復哪些錯誤的建議。
+ 如果您在建議時能附上相關程式碼的話, 那真是太棒了!</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
- <para>&man.make.1; will then have up to 4 processes running at any one
- time. Empirical evidence posted to the mailing lists shows this
- generally gives the best performance benefit.</para>
+ <sect2 xml:id="stable">
+ <title>使用 &os.stable;</title>
- <para>If you have a multi-CPU machine and you are using an SMP
- configured kernel try values between 6 and 10 and see how they speed
- things up.</para>
- </sect3>
+ <para>主要發行版就是由 &os.stable; 這個開發分支而來。
+ 修改進入這個分支的速度比較慢,
+ 並且假設這些修改已經先在 &os.current; 測試過。
+ 這<emphasis>仍然</emphasis>是一個開發分支,而且在任何時候,&os.stable; 的原始碼都可能適合或不適合一般的使用。他就只是另一個開發分支,不是給終端使用者用的。
+ 沒有要進行測試的使用者應該執行最新的 &os; 發行版。</para>
- <sect3>
- <title>Timings</title>
- <indexterm>
- <primary>rebuilding <quote>world</quote></primary>
- <secondary>timings</secondary>
- </indexterm>
+ <para>若有興趣去追蹤、貢獻 &os; 開發過程,尤其是會跟
+ &os;接下來的發行版有關的人,應該考慮採用 &os.stable;。</para>
- <para>Many factors influence the build time, but fairly recent
- machines may only take a one or two hours to build
- the &os.stable; tree, with no tricks or shortcuts used during the
- process. A &os.current; tree will take somewhat longer.</para>
- </sect3>
- </sect2>
+ <para>儘管 &os.stable; 應該在任何時候均能正確編譯、運作,但是沒有人能擔保一定如此。因為使用 &os.stable; 的人比 &os.current;多,無可避免地,
+ 有時候會在 &os.stable; 發現錯誤和極端的狀況,而這在 &os.current; 並非顯而易見。
+ 由於上述這些理由,我們並不建議盲目追隨 &os.stable;。
+ 特別重要的是
+ <emphasis>不要</emphasis>在沒有於開發或測試環境完整測試程式碼之前,
+ 升級任何上線的伺服器到 &os.stable;。</para>
+
+ <para>追蹤 &os.stable;:</para>
- <sect2>
- <title>Compile and Install a New Kernel</title>
<indexterm>
- <primary>kernel</primary>
- <secondary>compiling</secondary>
+ <primary>-STABLE</primary>
+ <secondary>using</secondary>
</indexterm>
+ <orderedlist>
+ <listitem>
+ <para>訂閱&a.stable.name;論壇來隨時瞭解 &os.stable; 編譯時的相依關係
+ 或是其他特別需要注意的議題。
+ 開發者在考慮一些有爭議的修正或更新時,就會先在這裡發信說明, 給使用者有機會可以反應, 看他們對所提的更改是否有什麼建議或問題。</para>
+
+ <para>訂閱要追蹤分支的 <application>svn</application>相關論壇。
+ 例如,追蹤9-STABLE分支的使用者應該訂閱&a.svn-src-stable-9.name;論壇。
+ 這個論壇紀錄每一次修改的紀錄,和可能產生的副作用的相關資訊。</para>
+
+ <para>前往&a.mailman.lists.link;,點選論壇來訂閱,照網頁指示的步驟作,
+ 為了追蹤整個原始碼樹,請訂閱&a.svn-src-all.name;論壇。</para>
+ </listitem>
+
+ <listitem>
+ <para>要安裝一個新的 &os.stable; 系統,
+ 從<link linkend="mirrors"> &os; 鏡像站</link>安裝最新的 &os.stable; 發行版
+ 或使用從 &os.stable;每個月的 snapshot built來安裝。更多關於快照的資訊,
+ 請參考<link xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots</link>。</para>
+
+ <para>要編譯或升級已經安裝的 &os; 系統至 &os.stable;,
+ 請使用<link linkend="svn">svn</link>
+ <indexterm>
+ <primary>Subversion</primary>
+ </indexterm> 來檢查要安裝分支的原始碼。
+ 分支的名稱,例如
+ <literal>stable/9</literal>,列在<link
+ xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>。
+ 如果沒有可靠的網際網路連線可以使用CTM (<xref linkend="ctm"/>) 。
+</para>
+ </listitem>
+
+ <listitem>
+ <para>在編譯或升級到 &os.stable; 之前
+ <indexterm>
+ <primary>-STABLE</primary>
+ <secondary>compiling</secondary>
+ </indexterm>, 請仔細閱讀 <filename>/usr/src/Makefile</filename>
+ 並遵照<xref
+ linkend="makeworld"/>的指示。閱讀 &a.stable; 和
+ <filename>/usr/src/UPDATING</filename>下一發行版的最新狀態。</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="synching">
+ <title>同步原始碼</title>
- <para>To take full advantage of your new system you should recompile the
- kernel. This is practically a necessity, as certain memory structures
- may have changed, and programs like &man.ps.1; and &man.top.1; will
- fail to work until the kernel and source code versions are the
- same.</para>
-
- <para>The simplest, safest way to do this is to build and install a
- kernel based on <filename>GENERIC</filename>. While
- <filename>GENERIC</filename> may not have all the necessary devices
- for your system, it should contain everything necessary to boot your
- system back to single user mode. This is a good test that the new
- system works properly. After booting from
- <filename>GENERIC</filename> and verifying that your system works you
- can then build a new kernel based on your normal kernel configuration
- file.</para>
-
- <para>On &os; it is important to <link linkend="make-buildworld">build world</link> before building a
- new kernel.</para>
-
- <note><para>If you want to build a custom kernel, and already have a configuration
- file, just use <literal>KERNCONF=MYKERNEL</literal>
- like this:</para>
+ <para>有幾種不同的方法保持 &os; 原始碼在最新狀態。
+ 這節比較這兩個主要的方法: <application>Subversion</application> 和 <application>CTM</application>。</para>
- <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make buildkernel KERNCONF=MYKERNEL</userinput>
-&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen>
+ <warning>
+ <para>雖然有可能只更新部份原始碼樹,但是唯一支援的更新步驟是更新整個樹併重新編譯所有在使用者空間的程式,
+ 例如在<filename>/bin</filename> 和
+ <filename>/sbin</filename>,以及核心原始碼。
+ 只更新部份原始碼樹,只更新核心,或只更新使用者空間的程式時常會導致編譯錯誤,核心錯誤或是資料惡化等問題。</para>
+ </warning>
+
+ <indexterm>
+ <primary>Subversion</primary>
+ </indexterm>
+
+ <para><application>Subversion</application>使用更新原始碼的
+ <emphasis>pull</emphasis> 模型。使用者,或是
+ <command>cron</command> 手稿語言, 呼叫更新本地端原始碼的
+ <command>svn</command> 程式。
+ <application>Subversion</application> is the
+ preferred method for updating local source trees as updates are
+ up-to-the-minute and the user controls when updates are
+ downloaded. It is easy to restrict updates to specific files or
+ directories and the requested updates are generated on the fly
+ by the server. 如何使用How to synchronize source using
+ <application>Subversion</application>同步原始碼,描述於<xref
+ linkend="svn"/>。</para>
+
+ <indexterm>
+ <primary><application>CTM</application></primary>
+ </indexterm>
+ <para><application>CTM</application> does not interactively
+ compare the local sources with those on the master archive or
+ otherwise pull them across. Instead, a script which identifies
+ changes in files since its previous run is executed several
+ times a day on the master CTM machine. Any detected changes are
+ compressed, stamped with a sequence-number, and encoded for
+ transmission over email in printable <acronym>ASCII</acronym>
+ only. Once downloaded, these <firstterm>deltas</firstterm> can
+ be run through <command>ctm.rmail</command> which will
+ automatically decode, verify, and apply the changes to the
+ user's copy of the sources. This process is more efficient than
+ <application>Subversion</application> and places less strain on
+ server resources since it is a <emphasis>push</emphasis>, rather
+ than a <emphasis>pull</emphasis>, model. Instructions for using
+ <application>CTM</application> to synchronize source can be
+ found at <xref linkend="ctm"/>.</para>
+
+ <para>If a user inadvertently wipes out portions of the local
+ archive, <application>Subversion</application> will detect and
+ rebuild the damaged portions. <application>CTM</application>
+ will not, and if a user deletes some portion of the source tree
+ and does not have a backup, they will have to start from scratch
+ from the most recent <firstterm>base delta</firstterm> and
+ rebuild it all with <application>CTM</application>.</para>
+ </sect1>
+
+ <sect1 xml:id="makeworld">
+ <title>重新編譯 World</title>
+
+ <indexterm>
+ <primary>Rebuilding <quote>world</quote></primary>
+ </indexterm>
+ <para>一旦本地端的原始碼樹和 &os; 的特定版本同步後,
+ 例如 &os.stable; or &os.current;,原始碼樹就可以用來重新編譯系統。
+ 這個過程叫重新編譯 world。</para>
+
+ <para>重新編譯 world <emphasis>之前</emphasis> ,請確定執行以下任務:</para>
+
+ <procedure>
+ <title>編譯 world <emphasis>之前</emphasis> 執行這些任務</title>
+
+ <step>
+ <para>備份所有重要資料到另一個系統或是可攜式媒體,
+ 檢查備份的完整性,手邊準備一個可以開機的安裝媒體。
+ 再次強調在重新編譯系統
+ <emphasis>之前</emphasis>,製作系統的備份是非常重要的。 While
+ rebuilding world is an easy task, there will inevitably be
+ times when mistakes in the source tree render the system
+ unbootable. You will probably never have to use the backup,
+ but it is better to be safe than sorry!</para>
+ </step>
+
+ <step>
+ <indexterm><primary>mailing list</primary></indexterm>
+ <para>Review the recent &a.stable.name; or &a.current.name;
+ entries, depending upon the branch being tracked. Be aware
+ of any known problems and which systems are affected. If a
+ known issue affects the version of synchronized code, wait
+ for an <quote>all clear</quote> announcement to be posted
+ stating that the problem has been solved. Resynchronize the
+ sources to ensure that the local version of source has the
+ needed fix.</para>
+ </step>
+
+ <step>
+ <para>Read <filename>/usr/src/UPDATING</filename> for any
+ extra steps necessary for that version of the source. This
+ file contains important information about potential problems
+ and may specify the order to run certain commands. Many
+ upgrades require specific additional steps such as renaming
+ or deleting specific files prior to installing the new
+ world. These will be listed at the end of this file where
+ the currently recommended upgrade sequence is explicitly
+ spelled out. If <filename>UPDATING</filename> contradicts
+ any steps in this chapter, the instructions in
+ <filename>UPDATING</filename> take precedence and should be
+ followed.</para>
+ </step>
+ </procedure>
+
+ <warning>
+ <title>不要使用 <command>make world</command></title>
+
+ <para>某些比較老的文件建議使用 <command>make
+ world</command>。然而,這個指令掠略過某些重要的步驟,只適合專家使用。
+ 大部分的情況,使用 <command>make world</command>都是錯誤的,應該用這裡描述的步驟代替。
+ </para>
+ </warning>
+
+ <sect2 xml:id="canonical-build">
+ <title>程序概要</title>
+
+ <para>The build world process assumes an upgrade from an older
+ &os; version using the source of a newer version that was
+ obtained using the instructions in <xref
+ linkend="synching"/>.</para>
+
+ <para>In &os;, the term <quote>world</quote> includes the
+ kernel, core system binaries, libraries, programming files,
+ and built-in compiler. The order in which these components
+ are built and installed is important.</para>
+
+ <para>For example, the old compiler might have a bug and not be
+ able to compile the new kernel. Since the new kernel should
+ be built with the new compiler, the new compiler must be
+ built, but not necessarily installed, before the new kernel is
+ built.</para>
+
+ <para>The new world might rely on new kernel features, so the
+ new kernel must be installed before the new world is
+ installed. The old world might not run correctly on the new
+ kernel, so the new world must be installed immediately upon
+ installing the new kernel.</para>
+
+ <para>Some configuration changes must be made before the new
+ world is installed, but others might break the old world.
+ Hence, two different configuration upgrade steps are used.
+ For the most part, the update process only replaces or adds
+ files and existing old files are not deleted. Since this can
+ cause problems, <filename>/usr/src/UPDATING</filename> will
+ indicate if any files need to be manually deleted and at which
+ step to do so.</para>
+
+ <para>These concerns have led to the recommended upgrade
+ sequence described in the following procedure.</para>
+
+ <note>
+ <para>It is a good idea to save the output from running
+ <command>make</command> to a file. If something goes wrong,
+ a copy of the error message can be posted to one of the &os;
+ mailing lists.</para>
+
+ <para>The easiest way to do this is to use
+ <command>script</command> with a parameter that specifies
+ the name of the file to save all output to. Do not save the
+ output to <filename>/tmp</filename> as this directory may be
+ cleared at next reboot. A better place to save the file is
+ <filename>/var/tmp</filename>. Run this command immediately
+ before rebuilding the world, and then type
+ <userinput>exit</userinput> when the process has
+ finished:</para>
+
+ <screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
+Script started, output file is /var/tmp/mw.out</screen>
</note>
- <para>Note that if you have raised <literal>kern.securelevel</literal>
- above 1 <emphasis>and</emphasis> you have set either the
- <literal>noschg</literal> or similar flags to your kernel binary, you
- might find it necessary to drop into single user mode to use
- <buildtarget>installkernel</buildtarget>. Otherwise you should be able
- to run both these commands from multi user mode without
- problems. See &man.init.8; for details about
- <literal>kern.securelevel</literal> and &man.chflags.1; for details
- about the various file flags.</para>
- </sect2>
+ <procedure>
+ <title>Overview of Build World Process</title>
+
+ <para>The commands used in the build world process should be
+ run in the order specified here. This section summarizes
+ the function of each command.</para>
+
+ <step>
+ <para>If the build world process has previously been run on
+ this system, a copy of the previous build may still exist
+ in <filename>/usr/obj</filename>. To
+ speed up the new build world process, and possibly save
+ some dependency headaches, remove this directory if it
+ already exists:</para>
+
+ <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/*</userinput>
+&prompt.root; <userinput>rm -rf /usr/obj</userinput></screen>
+ </step>
+
+ <step>
+ <para>Compile the new compiler and a few related tools, then
+ use the new compiler to compile the rest of the new world.
+ The result is saved to <filename
+ >/usr/obj</filename>.</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildworld</userinput></screen>
+ </step>
+
+ <step>
+ <para>Use the new compiler residing in <filename
+ >/usr/obj</filename> to build the new
+ kernel, in order to protect against compiler-kernel
+ mismatches. This is necessary, as certain memory
+ structures may have changed, and programs like
+ <command>ps</command> and <command>top</command> will fail
+ to work if the kernel and source code versions are not the
+ same.</para>
+
+ <screen>&prompt.root; <userinput>make buildkernel</userinput></screen>
+ </step>
+
+ <step>
+ <para>Install the new kernel and kernel modules, making it
+ possible to boot with the newly updated kernel. If
+ <varname>kern.securelevel</varname> has been raised above
+ <literal>1</literal> <emphasis>and</emphasis>
+ <literal>noschg</literal> or similar flags have been set
+ on the kernel binary, drop the system into single-user
+ mode first. Otherwise, this command can be run from
+ multi-user mode without problems. See &man.init.8; for
+ details about <varname>kern.securelevel</varname> and
+ &man.chflags.1; for details about the various file
+ flags.</para>
+
+ <screen>&prompt.root; <userinput>make installkernel</userinput></screen>
+ </step>
+
+ <step>
+ <para>Drop the system into single-user mode in order to
+ minimize problems from updating any binaries that are
+ already running. It also minimizes any problems from
+ running the old world on a new kernel.</para>
+
+ <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
+
+ <para>Once in single-user mode, run these commands if the
+ system is formatted with UFS:</para>
+
+ <screen>&prompt.root; <userinput>mount -u /</userinput>
+&prompt.root; <userinput>mount -a -t ufs</userinput>
+&prompt.root; <userinput>swapon -a</userinput></screen>
+
+ <para>If the system is instead formatted with ZFS, run these
+ two commands. This example assumes a zpool name of
+ <literal>zroot</literal>:</para>
+
+ <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput>
+&prompt.root; <userinput>zfs mount -a</userinput></screen>
+ </step>
+
+ <step>
+ <para>Optional: If a keyboard mapping other than the default
+ US English is desired, it can be changed with
+ &man.kbdmap.1;:</para>
+
+ <screen>&prompt.root; <userinput>kbdmap</userinput></screen>
+ </step>
+
+ <step>
+ <para>Then, for either file system, if the
+ <acronym>CMOS</acronym> clock is set to local time (this
+ is true if the output of &man.date.1; does not show the
+ correct time and zone), run:</para>
+
+ <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
+ </step>
+
+ <step>
+ <para>Remaking the world will not update certain
+ directories, such as <filename>/etc</filename>,
+ <filename>/var</filename> and <filename>/usr</filename>,
+ with new or changed configuration files. The next step is
+ to perform some initial configuration file updates
+ to <filename>/etc</filename> in
+ preparation for the new world. The following command
+ compares only those files that are essential for the
+ success of <buildtarget>installworld</buildtarget>. For
+ instance, this step may add new groups, system accounts,
+ or startup scripts which have been added to &os; since the
+ last update. This is necessary so that the
+ <buildtarget>installworld</buildtarget> step will be able
+ to use any new system accounts, groups, and scripts.
+ Refer to <xref linkend="mergemaster"/> for more detailed
+ instructions about this command:</para>
+
+ <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
+ </step>
+
+ <step>
+ <para>Install the new world and system binaries from
+ <filename>/usr/obj</filename>.</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installworld</userinput></screen>
+ </step>
+
+ <step>
+ <para>Update any remaining configuration files.</para>
+
+ <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
+ </step>
+
+ <step>
+ <para>Delete any obsolete files. This is important as they
+ may cause problems if left on the disk.</para>
+
+ <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
+ </step>
+
+ <step>
+ <para>A full reboot is now needed to load the new kernel and
+ new world with the new configuration files.</para>
+
+ <screen>&prompt.root; <userinput>reboot</userinput></screen>
+ </step>
+
+ <step>
+ <para>Make sure that all installed ports have first been
+ rebuilt before old libraries are removed using the
+ instructions in <xref linkend="ports-upgrading"/>. When
+ finished, remove any obsolete libraries to avoid conflicts
+ with newer ones. For a more detailed description of this
+ step, refer to <xref linkend="make-delete-old"/>.</para>
+
+ <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
+ </step>
+ </procedure>
- <sect2>
- <title>Reboot into Single User Mode</title>
<indexterm><primary>single-user mode</primary></indexterm>
- <para>You should reboot into single user mode to test the new kernel
- works. Do this by following the instructions in
- <xref linkend="makeworld-singleuser"/>.</para>
+ <para>If the system can have a window of down-time, consider
+ compiling the system in single-user mode instead of compiling
+ the system in multi-user mode, and then dropping into
+ single-user mode for the installation. Reinstalling the
+ system touches a lot of important system files, all the
+ standard system binaries, libraries, and include files.
+ Changing these on a running system, particularly one with
+ active users, is asking for trouble.</para>
</sect2>
- <sect2 xml:id="make-installworld">
- <title>Install the New System Binaries</title>
+ <sect2 xml:id="src-updating">
+ <title>Configuration Files</title>
- <para>If you were building a version of &os; recent enough to have
- used <command>make buildworld</command> then you should now use
- <buildtarget>installworld</buildtarget> to install the new system
- binaries.</para>
+ <indexterm>
+ <primary><filename>make.conf</filename></primary>
+ </indexterm>
- <para>Run</para>
+ <para>This build world process uses several configuration
+ files.</para>
+
+ <para>The <filename>Makefile</filename> located in
+ <filename>/usr/src</filename> describes how the programs that
+ comprise &os; should be built and the order in which they
+ should be built.</para>
+
+ <para>The options available to <command>make</command> are
+ described in &man.make.conf.5; and some common examples are
+ included in
+ <filename>/usr/share/examples/etc/make.conf</filename>. Any
+ options which are added to <filename>/etc/make.conf</filename>
+ will control the how <command>make</command> runs and builds
+ programs. These options take effect every time
+ <command>make</command> is used, including compiling
+ applications from the Ports Collection, compiling custom C
+ programs, or building the &os; operating system. Changes to
+ some settings can have far-reaching and potentially surprising
+ effects. Read the comments in both locations and keep in mind
+ that the defaults have been chosen for a combination of
+ performance and safety.</para>
- <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make installworld</userinput></screen>
+ <indexterm>
+ <primary><filename>src.conf</filename></primary>
+ </indexterm>
+
+ <para>How the operating system is built from source code is
+ controlled by <filename>/etc/src.conf</filename>. Unlike
+ <filename>/etc/make.conf</filename>, the contents of
+ <filename>/etc/src.conf</filename> only take effect when the
+ &os; operating system itself is being built. Descriptions of
+ the many options available for this file are shown in
+ &man.src.conf.5;. Be cautious about disabling seemingly
+ unneeded kernel modules and build options. Sometimes there
+ are unexpected or subtle interactions.</para>
+ </sect2>
+
+ <sect2 xml:id="make-buildworld">
+ <title>Variables and Targets</title>
+
+ <para>The general format for using <command>make</command> is as
+ follows:</para>
+
+ <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
+
+ <para>In this example,
+ <option>-<replaceable>x</replaceable></option> is an option
+ passed to <command>make</command>. Refer to &man.make.1; for
+ examples of the available options.</para>
+
+ <para>To pass a variable, specify the variable name with
+ <option>-D<replaceable>VARIABLE</replaceable></option>. The
+ behavior of the <filename>Makefile</filename> is controlled by
+ variables. These can either be set in
+ <filename>/etc/make.conf</filename> or they can be specified
+ when using <command>make</command>. For example, this
+ variable specifies that profiled libraries should not be
+ built:</para>
+
+ <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
+
+ <para>It corresponds with this setting in
+ <filename>/etc/make.conf</filename>:</para>
+
+ <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting>
+
+ <para>The <replaceable>target</replaceable> tells
+ <command>make</command> what to do and the
+ <filename>Makefile</filename> defines the available targets.
+ Some targets are used by the build process to break out the
+ steps necessary to rebuild the system into a number of
+ sub-steps.</para>
+
+ <para>Having separate options is useful for two reasons. First,
+ it allows for a build that does not affect any components of a
+ running system. Because of this,
+ <buildtarget>buildworld</buildtarget> can be safely run on a
+ machine running in multi-user mode. It is still recommended
+ that <buildtarget>installworld</buildtarget> be run in part in
+ single-user mode, though.</para>
+
+ <para>Secondly, it allows <acronym>NFS</acronym> mounts to be
+ used to upgrade multiple machines on a network, as described
+ in <xref linkend="small-lan"/>.</para>
+
+ <para>It is possible to specify <option>-j</option> which will
+ cause <command>make</command> to spawn several simultaneous
+ processes. Since much of the compiling process is
+ <acronym>I/O</acronym>-bound rather than
+ <acronym>CPU</acronym>-bound, this is useful on both single
+ <acronym>CPU</acronym> and multi-<acronym>CPU</acronym>
+ machines.</para>
+
+ <para>On a single-<acronym>CPU</acronym> machine, run the
+ following command to have up to 4 processes running at any one
+ time. Empirical evidence posted to the mailing lists shows
+ this generally gives the best performance benefit.</para>
+
+ <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
+
+ <para>On a multi-<acronym>CPU</acronym> machine, try values
+ between <literal>6</literal> and <literal>10</literal> to see
+ how they speed things up.</para>
+
+ <indexterm>
+ <primary>rebuilding <quote>world</quote></primary>
+ <secondary>timings</secondary>
+ </indexterm>
<note>
- <para>If you specified variables on the <command>make
- buildworld</command> command line, you must specify the same
- variables in the <command>make installworld</command> command
- line. This does not necessarily hold true for other options;
- for example, <option>-j</option> must never be used with
- <buildtarget>installworld</buildtarget>.</para>
+ <para>If any variables were specified to <command>make
+ buildworld</command>, specify the same variables to
+ <command>make installworld</command>. However,
+ <option>-j</option> must <emphasis>never</emphasis> be used
+ with <buildtarget>installworld</buildtarget>.</para>
- <para>For example, if you ran:</para>
+ <para>For example, if this command was used:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
- <para>you must install the results with:</para>
+ <para>Install the results with:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
- <para>otherwise it would try to install profiled libraries that
- had not been built during the <command>make buildworld</command>
- phase.</para>
+ <para>Otherwise, the second command will try to install
+ profiled libraries that were not built during the
+ <command>make buildworld</command> phase.</para>
</note>
</sect2>
- <sect2>
- <title>Update Files Not Updated by <command>make installworld</command></title>
+ <sect2 xml:id="mergemaster">
+ <info>
+ <title>Merging Configuration Files</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </info>
- <para>Remaking the world will not update certain directories (in
- particular, <filename>/etc</filename>, <filename>/var</filename> and
- <filename>/usr</filename>) with new or changed configuration files.</para>
+ <indexterm>
+ <primary>
+ <command>mergemaster</command>
+ </primary>
+ </indexterm>
- <para>The simplest way to update these files is to use
- &man.mergemaster.8;, though it is possible to do it manually
- if you would prefer to do that. Regardless of which way you
- choose, be sure to make a backup of <filename>/etc</filename> in
- case anything goes wrong.</para>
+ <para>&os; provides the &man.mergemaster.8; Bourne script to aid
+ in determining the differences between the configuration files
+ in <filename>/etc</filename>, and the configuration files in
+ <filename>/usr/src/etc</filename>. This is the recommended
+ solution for keeping the system configuration files up to date
+ with those located in the source tree.</para>
+
+ <para>Before using <command>mergemaster</command>, it is
+ recommended to first copy the existing
+ <filename>/etc</filename> somewhere safe. Include
+ <option>-R</option> which does a recursive copy and
+ <option>-p</option> which preserves times and the ownerships
+ on files:</para>
+
+ <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
+
+ <para>When run, <command>mergemaster</command> builds a
+ temporary root environment, from <filename>/</filename> down,
+ and populates it with various system configuration files.
+ Those files are then compared to the ones currently installed
+ in the system. Files that differ will be shown in
+ &man.diff.1; format, with the <option>+</option> sign
+ representing added or modified lines, and <option>-</option>
+ representing lines that will be either removed completely or
+ replaced with a new file. Refer to &man.diff.1; for more
+ information about how file differences are shown.</para>
+
+ <para>Next, <command>mergemaster</command> will display each
+ file that differs, and present options to: delete the new
+ file, referred to as the temporary file, install the temporary
+ file in its unmodified state, merge the temporary file with
+ the currently installed file, or view the results
+ again.</para>
+
+ <para>Choosing to delete the temporary file will tell
+ <command>mergemaster</command> to keep the current file
+ unchanged and to delete the new version. This option is not
+ recommended. To get help at any time, type
+ <keycap>?</keycap> at the <command>mergemaster</command>
+ prompt. If the user chooses to skip a file, it will be
+ presented again after all other files have been dealt
+ with.</para>
+
+ <para>Choosing to install the unmodified temporary file will
+ replace the current file with the new one. For most
+ unmodified files, this is the best option.</para>
+
+ <para>Choosing to merge the file will present a text editor, and
+ the contents of both files. The files can be merged by
+ reviewing both files side by side on the screen, and choosing
+ parts from both to create a finished product. When the files
+ are compared side by side, <keycap>l</keycap> selects the left
+ contents and <keycap>r</keycap> selects contents from the
+ right. The final output will be a file consisting of both
+ parts, which can then be installed. This option is
+ customarily used for files where settings have been modified
+ by the user.</para>
+
+ <para>Choosing to view the results again will redisplay the file
+ differences.</para>
+
+ <para>After <command>mergemaster</command> is done with the
+ system files, it will prompt for other options. It may prompt
+ to rebuild the password file and will finish up with an option
+ to remove left-over temporary files.</para>
+<!--
+Probably not needed as changes should be minimal and mergemaster does
+a good job of merging.
+ <tip>
+ <title>Name the New Root Directory
+ (<filename>/var/tmp/root</filename>)
+ with a Time Stamp, so You Can Easily Compare Differences
+ Between Versions</title>
+
+ <para>Frequently rebuilding world entails frequently
+ updating <filename>/etc</filename>
+ as well, which can be a bit of a chore.</para>
+
+ <para>To speed up this process, use the following
+ procedure to keep a copy of the last set of changed files
+ that were merged into <filename>/etc</filename>.</para>
+
+ <procedure>
+ <step>
+ <para>Make the world as normal. When updating
+ <filename>/etc</filename> and the
+ other directories, give the target directory a name
+ based on the current date:</para>
+
+ <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>
+&prompt.root; <userinput>cd /usr/src/etc</userinput>
+&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \
+ distrib-dirs distribution</userinput></screen>
+ </step>
+
+ <step>
+ <para>Merge in the changes from this directory as
+ outlined above. <emphasis>Do not</emphasis> remove
+ the <filename>/var/tmp/root-20130214</filename>
+ directory when you have finished.</para>
+ </step>
+
+ <step>
+ <para>After downloading the latest version of the
+ source and remaking it, follow step 1. Create a new
+ directory, which reflects the new date. This example
+ uses
+ <filename>/var/tmp/root-20130221</filename>.</para>
+ </step>
+
+ <step>
+ <para>Use &man.diff.1; to see the differences that have
+ been made in the intervening week by creating a
+ recursive diff between the two directories:</para>
+
+ <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
+&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>
+
+ <para>Typically, this will be a much smaller set of
+ differences than those between
+ <filename>/var/tmp/root-20130221/etc</filename> and
+ <filename>/etc</filename>. Because the set of
+ differences is smaller, it is easier to migrate those
+ changes across into <filename>/etc</filename>.</para>
+ </step>
+
+ <step>
+ <para>When finished, remove the older of the two
+ <filename>/var/tmp/root-*</filename>
+ directories:</para>
+
+ <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>
+ </step>
+
+ <step>
+ <para>Repeat this process whenever merging
+ in changes to <filename>/etc</filename>.</para>
+ </step>
+ </procedure>
+
+ <para>Use &man.date.1; to automate the generation of the
+ directory names:</para>
+
+ <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
+ </tip>
+ -->
+ </sect2>
+
+ <sect2 xml:id="make-delete-old">
+ <info>
+ <title>Deleting Obsolete Files and Libraries</title>
- <sect3 xml:id="mergemaster">
- <info><title><command>mergemaster</command></title>
<authorgroup>
- <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Anton</firstname>
+ <surname>Shterenlikht</surname>
+ </personname>
+ <contrib>Based on notes provided by </contrib>
+ </author>
</authorgroup>
</info>
-
- <indexterm><primary><command>mergemaster</command></primary></indexterm>
-
- <para>The &man.mergemaster.8; utility is a Bourne script that will
- aid you in determining the differences between your configuration files
- in <filename>/etc</filename>, and the configuration files in
- the source tree <filename>/usr/src/etc</filename>. This is
- the recommended solution for keeping the system configuration files up to date
- with those located in the source tree.</para>
-
- <para>To begin simply type <command>mergemaster</command> at your prompt, and
- watch it start going. <command>mergemaster</command> will then build a
- temporary root environment, from <filename>/</filename> down, and populate
- it with various system configuration files. Those files are then compared
- to the ones currently installed in your system. At this point, files that
- differ will be shown in &man.diff.1; format, with the <option>+</option> sign
- representing added or modified lines, and <option>-</option> representing
- lines that will be either removed completely, or replaced with a new line.
- See the &man.diff.1; manual page for more information about the &man.diff.1;
- syntax and how file differences are shown.</para>
-
- <para>&man.mergemaster.8; will then show you each file that displays variances,
- and at this point you will have the option of either deleting the new file (referred
- to as the temporary file), installing the temporary file in its unmodified state,
- merging the temporary file with the currently installed file, or viewing the
- &man.diff.1; results again.</para>
-
- <para>Choosing to delete the temporary file will tell &man.mergemaster.8; that we
- wish to keep our current file unchanged, and to delete the new version.
- This option is not recommended, unless you see no
- reason to change the current file. You can get help at any time by
- typing <keycap>?</keycap> at the &man.mergemaster.8; prompt. If the user
- chooses to skip a file, it will be presented again after all other files
- have been dealt with.</para>
-
- <para>Choosing to install the unmodified temporary file will replace the
- current file with the new one. For most unmodified files, this is the best
- option.</para>
-
- <para>Choosing to merge the file will present you with a text editor,
- and the contents of both files. You can now merge them by
- reviewing both files side by side on the screen, and choosing parts from
- both to create a finished product. When the files are compared side by side,
- the <keycap>l</keycap> key will select the left contents and the
- <keycap>r</keycap> key will select contents from your right.
- The final output will be a file consisting of both parts, which can then be
- installed. This option is customarily used for files where settings have been
- modified by the user.</para>
-
- <para>Choosing to view the &man.diff.1; results again will show you the file differences
- just like &man.mergemaster.8; did before prompting you for an option.</para>
-
- <para>After &man.mergemaster.8; is done with the system files you will be
- prompted for other options. &man.mergemaster.8; may ask if you want to rebuild
- the password file and will finish up with an option to
- remove left-over temporary files.</para>
- </sect3>
- <sect3>
- <title>Manual Update</title>
+ <indexterm>
+ <primary>Deleting obsolete files and directories</primary>
+ </indexterm>
- <para>If you wish to do the update manually, however,
- you cannot just copy over the files from
- <filename>/usr/src/etc</filename> to <filename>/etc</filename> and
- have it work. Some of these files must be <quote>installed</quote>
- first. This is because the <filename>/usr/src/etc</filename>
- directory <emphasis>is not</emphasis> a copy of what your
- <filename>/etc</filename> directory should look like. In addition,
- there are files that should be in <filename>/etc</filename> that are
- not in <filename>/usr/src/etc</filename>.</para>
+ <para>As a part of the &os; development lifecycle, files and
+ their contents occasionally become obsolete. This may be
+ because functionality is implemented elsewhere, the version
+ number of the library has changed, or it was removed from the
+ system entirely. These obsoleted files, libraries, and
+ directories should be removed when updating the system.
+ This ensures that the system is not cluttered with old files
+ which take up unnecessary space on the storage and backup
+ media. Additionally, if the old library has a security or
+ stability issue, the system should be updated to the newer
+ library to keep it safe and to prevent crashes caused by the
+ old library. Files, directories, and libraries which are
+ considered obsolete are listed in
+ <filename>/usr/src/ObsoleteFiles.inc</filename>. The
+ following instructions should be used to remove obsolete files
+ during the system upgrade process.</para>
+
+ <para>After the <command>make installworld</command> and the
+ subsequent <command>mergemaster</command> have finished
+ successfully, check for obsolete files and libraries:</para>
- <para>If you are using &man.mergemaster.8; (as recommended),
- you can skip forward to the <link linkend="cutting-edge-rebooting">next
- section</link>.</para>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make check-old</userinput></screen>
- <para>The simplest way to do this by hand is to install the
- files into a new directory, and then work through them looking
- for differences.</para>
+ <para>If any obsolete files are found, they can be deleted using
+ the following command:</para>
- <warning>
- <title>Backup Your Existing <filename>/etc</filename></title>
+ <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
+
+ <para>A prompt is displayed before deleting each obsolete file.
+ To skip the prompt and let the system remove these files
+ automatically, use
+ <varname>BATCH_DELETE_OLD_FILES</varname>:</para>
+
+ <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
- <para>Although, in theory, nothing is going to touch this directory
- automatically, it is always better to be sure. So copy your
- existing <filename>/etc</filename> directory somewhere safe.
- Something like:</para>
+ <para>The same goal can be achieved by piping these commands
+ through <command>yes</command>:</para>
- <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
+ <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
- <para><option>-R</option> does a recursive copy, <option>-p</option>
- preserves times, ownerships on files and suchlike.</para>
+ <warning>
+ <title>Warning</title>
+
+ <para>Deleting obsolete files will break applications that
+ still depend on those obsolete files. This is especially
+ true for old libraries. In most cases, the programs, ports,
+ or libraries that used the old library need to be recompiled
+ before <command>make delete-old-libs</command> is
+ executed.</para>
</warning>
- <para>You need to build a dummy set of directories to install the new
- <filename>/etc</filename> and other files into.
- <filename>/var/tmp/root</filename> is a reasonable choice, and
- there are a number of subdirectories required under this as
- well.</para>
+ <para>Utilities for checking shared library dependencies include
+ <package>sysutils/libchk</package> and
+ <package>sysutils/bsdadminscripts</package>.</para>
- <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
-&prompt.root; <userinput>cd /usr/src/etc</userinput>
-&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>
-
- <para>This will build the necessary directory structure and install the
- files. A lot of the subdirectories that have been created under
- <filename>/var/tmp/root</filename> are empty and should be deleted.
- The simplest way to do this is to:</para>
-
- <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
-&prompt.root; <userinput>find -d . -type d | xargs rmdir 2&gt;/dev/null</userinput></screen>
-
- <para>This will remove all empty directories. (Standard error is
- redirected to <filename>/dev/null</filename> to prevent the warnings
- about the directories that are not empty.)</para>
-
- <para><filename>/var/tmp/root</filename> now contains all the files that
- should be placed in appropriate locations below
- <filename>/</filename>. You now have to go through each of these
- files, determining how they differ with your existing files.</para>
-
- <para>Note that some of the files that will have been installed in
- <filename>/var/tmp/root</filename> have a leading <quote>.</quote>. At the
- time of writing the only files like this are shell startup files in
- <filename>/var/tmp/root/</filename> and
- <filename>/var/tmp/root/root/</filename>, although there may be others
- (depending on when you are reading this). Make sure you use
- <command>ls -a</command> to catch them.</para>
-
- <para>The simplest way to do this is to use &man.diff.1; to compare the
- two files:</para>
-
- <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>
-
- <para>This will show you the differences between your
- <filename>/etc/shells</filename> file and the new
- <filename>/var/tmp/root/etc/shells</filename> file. Use these to decide whether to
- merge in changes that you have made or whether to copy over your old
- file.</para>
-
- <tip>
- <title>Name the New Root Directory
- (<filename>/var/tmp/root</filename>) with a Time Stamp, so You Can
- Easily Compare Differences Between Versions</title>
-
- <para>Frequently rebuilding the world means that you have to update
- <filename>/etc</filename> frequently as well, which can be a bit of
- a chore.</para>
-
- <para>You can speed this process up by keeping a copy of the last set
- of changed files that you merged into <filename>/etc</filename>.
- The following procedure gives one idea of how to do this.</para>
-
- <procedure>
- <step>
- <para>Make the world as normal. When you want to update
- <filename>/etc</filename> and the other directories, give the
- target directory a name based on the current date. If you were
- doing this on the 14th of February 1998 you could do the
- following:</para>
-
- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput>
-&prompt.root; <userinput>cd /usr/src/etc</userinput>
-&prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \
- distrib-dirs distribution</userinput></screen>
- </step>
-
- <step>
- <para>Merge in the changes from this directory as outlined
- above.</para>
-
- <para><emphasis>Do not</emphasis> remove the
- <filename>/var/tmp/root-19980214</filename> directory when you
- have finished.</para>
- </step>
-
- <step>
- <para>When you have downloaded the latest version of the source
- and remade it, follow step 1. This will give you a new
- directory, which might be called
- <filename>/var/tmp/root-19980221</filename> (if you wait a week
- between doing updates).</para>
- </step>
-
- <step>
- <para>You can now see the differences that have been made in the
- intervening week using &man.diff.1; to create a recursive diff
- between the two directories:</para>
-
- <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
-&prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen>
-
- <para>Typically, this will be a much smaller set of differences
- than those between
- <filename>/var/tmp/root-19980221/etc</filename> and
- <filename>/etc</filename>. Because the set of differences is
- smaller, it is easier to migrate those changes across into your
- <filename>/etc</filename> directory.</para>
- </step>
-
- <step>
- <para>You can now remove the older of the two
- <filename>/var/tmp/root-*</filename> directories:</para>
-
- <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen>
- </step>
-
- <step>
- <para>Repeat this process every time you need to merge in changes
- to <filename>/etc</filename>.</para>
- </step>
- </procedure>
-
- <para>You can use &man.date.1; to automate the generation of the
- directory names:</para>
-
- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
- </tip>
- </sect3>
- </sect2>
+ <para>Obsolete shared libraries can conflict with newer
+ libraries, causing messages like these:</para>
- <sect2 xml:id="cutting-edge-rebooting">
- <title>Rebooting</title>
+ <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
+/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
- <para>You are now done. After you have verified that everything appears
- to be in the right place you can reboot the system. A simple
- &man.shutdown.8; should do it:</para>
+ <para>To solve these problems, determine which port installed
+ the library:</para>
- <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
- </sect2>
+ <screen>&prompt.root; <userinput>pkg which /usr/local/lib/libtiff.so</userinput>
+ /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
+&prompt.root; <userinput>pkg which /usr/local/lib/libXext.so</userinput>
+ /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>
- <sect2>
- <title>Finished</title>
+ <para>Then deinstall, rebuild, and reinstall the port. To
+ automate this process,
+ <package>ports-mgmt/portmaster</package> can be used. After
+ all ports are rebuilt and no longer use the old libraries,
+ delete the old libraries using the following command:</para>
- <para>You should now have successfully upgraded your &os; system.
- Congratulations.</para>
+ <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
- <para>If things went slightly wrong, it is easy to rebuild a particular
- piece of the system. For example, if you accidentally deleted
- <filename>/etc/magic</filename> as part of the upgrade or merge of
- <filename>/etc</filename>, the &man.file.1; command will stop working.
- In this case, the fix would be to run:</para>
+ <para>If something goes wrong, it is easy to rebuild a
+ particular piece of the system. For example, if
+ <filename>/etc/magic</filename> was accidentally deleted as
+ part of the upgrade or merge of <filename>/etc</filename>,
+ <command>file</command> will stop working. To fix this,
+ run:</para>
- <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
+ <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
</sect2>
- <sect2>
- <title>Questions</title>
+ <sect2 xml:id="updating-questions">
+ <title>Common Questions</title>
- <qandaset>
- <qandaentry>
- <question>
- <para>Do I need to re-make the world for every change?</para>
- </question>
+ <variablelist>
+ <varlistentry>
+ <term>Do I need to re-make the world for every
+ change?</term>
- <answer>
- <para>There is no easy answer to this one, as it depends on the
- nature of the change. For example, if you just ran <application>CVSup</application>, and
- it has shown the following files as being updated:</para>
+ <listitem>
+ <para>It depends upon the nature of the change. For
+ example, if <application>svn</application> only shows
+ the following files as being updated:</para>
<screen><filename>src/games/cribbage/instr.c</filename>
<filename>src/games/sail/pl_main.c</filename>
@@ -1180,356 +1805,272 @@ Script done, &hellip;</screen>
<filename>src/release/sysinstall/media.c</filename>
<filename>src/share/mk/bsd.port.mk</filename></screen>
- <para>it probably is not worth rebuilding the entire world.
- You could just go to the appropriate sub-directories and
- <command>make all install</command>, and that's about it. But
- if something major changed, for example
- <filename>src/lib/libc/stdlib</filename> then you should either
- re-make the world, or at least those parts of it that are
- statically linked (as well as anything else you might have added
- that is statically linked).</para>
-
- <para>At the end of the day, it is your call. You might be happy
- re-making the world every fortnight say, and let changes
- accumulate over that fortnight. Or you might want to re-make
- just those things that have changed, and be confident you can
- spot all the dependencies.</para>
-
- <para>And, of course, this all depends on how often you want to
- upgrade, and whether you are tracking &os.stable; or
- &os.current;.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>My compile failed with lots of signal 11<indexterm>
- <primary>signal 11</primary></indexterm> (or other signal
- number) errors. What has happened?</para>
- </question>
-
- <answer>
- <para>This is normally indicative of hardware problems.
- (Re)making the world is an effective way to stress test your
- hardware, and will frequently throw up memory problems. These
- normally manifest themselves as the compiler mysteriously dying
- on receipt of strange signals.</para>
-
- <para>A sure indicator of this is if you can restart the make and
- it dies at a different point in the process.</para>
-
- <para>In this instance there is little you can do except start
- swapping around the components in your machine to determine
- which one is failing.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Can I remove <filename>/usr/obj</filename> when I have
- finished?</para>
- </question>
-
- <answer>
- <para>The short answer is yes.</para>
-
- <para><filename>/usr/obj</filename> contains all the object files
- that were produced during the compilation phase. Normally, one
- of the first steps in the <command>make buildworld</command> process is to
- remove this directory and start afresh. In this case, keeping
- <filename>/usr/obj</filename> around after you have finished
- makes little sense, and will free up a large chunk of disk space
- (currently about 340&nbsp;MB).</para>
-
- <para>However, if you know what you are doing you can have
- <command>make buildworld</command> skip this step. This will make subsequent
- builds run much faster, since most of sources will not need to
- be recompiled. The flip side of this is that subtle dependency
- problems can creep in, causing your build to fail in odd ways.
- This frequently generates noise on the &os; mailing lists,
- when one person complains that their build has failed, not
- realizing that it is because they have tried to cut
- corners.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Can interrupted builds be resumed?</para>
- </question>
-
- <answer>
- <para>This depends on how far through the process you got before
- you found a problem.</para>
-
- <para><emphasis>In general</emphasis> (and this is not a hard and
- fast rule) the <command>make buildworld</command> process builds new
- copies of essential tools (such as &man.gcc.1;, and
- &man.make.1;) and the system libraries. These tools and
- libraries are then installed. The new tools and libraries are
- then used to rebuild themselves, and are installed again. The
- entire system (now including regular user programs, such as
- &man.ls.1; or &man.grep.1;) is then rebuilt with the new
- system files.</para>
-
- <para>If you are at the last stage, and you know it (because you
- have looked through the output that you were storing) then you
- can (fairly safely) do:</para>
-
- <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
-&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
+ <para>it probably is not worth rebuilding the entire
+ world. Instead, go into the appropriate sub-directories
+ and run <command>make all install</command>. But if
+ something major changes, such as
+ <filename>src/lib/libc/stdlib</filename>, consider
+ rebuilding world.</para>
+
+ <para>Some users rebuild world every fortnight and let
+ changes accumulate over that fortnight. Others only
+ re-make those things that have changed and are careful
+ to spot all the dependencies. It all depends on how
+ often a user wants to upgrade and whether they are
+ tracking &os.stable; or &os.current;.</para>
+ </listitem>
+ </varlistentry>
- <para>This will not undo the work of the previous
- <command>make buildworld</command>.</para>
+ <varlistentry>
+ <term>What would cause a compile to fail with lots of
+ signal 11<indexterm>
+ <primary>signal 11</primary>
+ </indexterm>
+ (or other signal number) errors?</term>
- <para>If you see the message:</para>
+ <listitem>
+ <para>This normally indicates a hardware problem.
+ Building world is an effective way to stress test
+ hardware, especially memory. A sure indicator of a
+ hardware issue is when <application>make</application>
+ is restarted and it dies at a different point in the
+ process.</para>
+
+ <para>To resolve this error, swap out the components in
+ the machine, starting with RAM, to determine which
+ component is failing.</para>
+ </listitem>
+ </varlistentry>
- <screen>--------------------------------------------------------------
+ <varlistentry>
+ <term>Can <filename>/usr/obj</filename>
+ be removed when finished?</term>
+
+ <listitem>
+ <para>This directory contains all the object files that
+ were produced during the compilation phase. Normally,
+ one of the first steps in the <command>make
+ buildworld</command> process is to remove this
+ directory and start afresh. Keeping
+ <filename>/usr/obj</filename> around when finished makes
+ little sense, and its removal frees up a approximately
+ 2GB of disk space.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Can interrupted builds be resumed?</term>
+
+ <listitem>
+ <para>This depends on how far into the process the
+ problem occurs. In general, <command>make
+ buildworld</command> builds new copies of essential
+ tools and the system libraries. These tools and
+ libraries are then installed, used to rebuild
+ themselves, and are installed again. The rest of the
+ system is then rebuilt with the new system
+ tools.</para>
+
+ <para>During the last stage, it is fairly safe to run
+ these commands as they will not undo the work of the
+ previous <command>make buildworld</command>:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
+
+ <para>If this message appears:</para>
+
+ <screen>--------------------------------------------------------------
Building everything..
--------------------------------------------------------------</screen>
- <para>in the <command>make buildworld</command> output then it is
- probably fairly safe to do so.</para>
+ <para>in the <command>make buildworld</command> output,
+ it is probably fairly safe to do so.</para>
- <para>If you do not see that message, or you are not sure, then it
- is always better to be safe than sorry, and restart the build
+ <para>If that message is not displayed, it is always
+ better to be safe than sorry and to restart the build
from scratch.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How can I speed up making the world?</para>
- </question>
-
- <answer>
- <itemizedlist>
- <listitem>
- <para>Run in single user mode.</para>
- </listitem>
-
- <listitem>
- <para>Put the <filename>/usr/src</filename> and
- <filename>/usr/obj</filename> directories on separate
- file systems held on separate disks. If possible, put these
- disks on separate disk controllers.</para>
- </listitem>
-
- <listitem>
- <para>Better still, put these file systems across multiple
- disks using the &man.ccd.4; (concatenated disk
- driver) device.</para>
- </listitem>
-
- <listitem>
- <para>Turn off profiling (set <quote>NO_PROFILE=true</quote> in
- <filename>/etc/make.conf</filename>). You almost certainly
- do not need it.</para>
- </listitem>
-
- <listitem>
- <para>Also in <filename>/etc/make.conf</filename>, set
- <varname>CFLAGS</varname> to something like <option>-O
- -pipe</option>. The optimization <option>-O2</option> is much
- slower, and the optimization difference between
- <option>-O</option> and <option>-O2</option> is normally
- negligible. <option>-pipe</option> lets the compiler use
- pipes rather than temporary files for communication, which
- saves disk access (at the expense of memory).</para>
- </listitem>
-
- <listitem>
- <para>Pass the <option>-j<replaceable>n</replaceable></option> option to &man.make.1; to
- run multiple processes in parallel. This usually helps
- regardless of whether you have a single or a multi processor
- machine.</para>
- </listitem>
-
- <listitem><para>The file system holding
- <filename>/usr/src</filename> can be mounted (or remounted)
- with the <option>noatime</option> option. This prevents the
- file system from recording the file access time. You probably
- do not need this information anyway.</para>
-
- <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
-
- <warning>
- <para>The example assumes <filename>/usr/src</filename> is
- on its own file system. If it is not (if it is a part of
- <filename>/usr</filename> for example) then you will
- need to use that file system mount point, and not
- <filename>/usr/src</filename>.</para>
- </warning>
- </listitem>
-
- <listitem>
- <para>The file system holding <filename>/usr/obj</filename> can
- be mounted (or remounted) with the <option>async</option>
- option. This causes disk writes to happen asynchronously.
- In other words, the write completes immediately, and the
- data is written to the disk a few seconds later. This
- allows writes to be clustered together, and can be a
- dramatic performance boost.</para>
-
- <warning>
- <para>Keep in mind that this option makes your file system
- more fragile. With this option there is an increased
- chance that, should power fail, the file system will be in
- an unrecoverable state when the machine restarts.</para>
-
- <para>If <filename>/usr/obj</filename> is the only thing on
- this file system then it is not a problem. If you have
- other, valuable data on the same file system then ensure
- your backups are fresh before you enable this
- option.</para>
- </warning>
-
- <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
-
- <warning>
- <para>As above, if <filename>/usr/obj</filename> is not on
- its own file system, replace it in the example with the
- name of the appropriate mount point.</para>
- </warning>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What do I do if something goes wrong?</para>
- </question>
-
- <answer>
- <para>Make absolutely sure your environment has no
- extraneous cruft from earlier builds. This is simple
- enough.</para>
-
- <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Is it possible to speed up making the world?</term>
+
+ <listitem>
+ <para>Several actions can speed up the build world
+ process. For example, the entire process can be run
+ from single-user mode. However, this will prevent users
+ from having access to the system until the process is
+ complete.</para>
+
+ <para>Careful file system design or the use of ZFS
+ datasets can make a difference. Consider putting
+ <filename>/usr/src</filename> and
+ <filename>/usr/obj</filename> on
+ separate file systems. If possible, place the file
+ systems on separate disks on separate disk controllers.
+ When mounting <filename
+ >/usr/src</filename>, use
+ <option>noatime</option> which prevents the file system
+ from recording the file access time. If <filename
+ >/usr/src</filename> is not on its
+ own file system, consider remounting <filename
+ >/usr</filename> with
+ <option>noatime</option>.</para>
+
+ <para>The file system holding <filename
+ >/usr/obj</filename> can be mounted
+ or remounted with <option>async</option> so that disk
+ writes happen asynchronously. The write completes
+ immediately, and the data is written to the disk a few
+ seconds later. This allows writes to be clustered
+ together, and can provide a dramatic performance
+ boost.</para>
+
+ <warning>
+ <para>Keep in mind that this option makes the file
+ system more fragile. With this option, there is an
+ increased chance that, should power fail, the file
+ system will be in an unrecoverable state when the
+ machine restarts.</para>
+
+ <para>If <filename>/usr/obj</filename> is the only
+ directory on this file system, this is not a problem.
+ If you have other, valuable data on the same file
+ system, ensure that there are verified backups before
+ enabling this option.</para>
+ </warning>
+
+ <para>Turn off profiling by setting
+ <quote>NO_PROFILE=true</quote> in
+ <filename>/etc/make.conf</filename>.</para>
+
+ <para>Pass <option>-j<replaceable>n</replaceable></option>
+ to &man.make.1; to run multiple processes in parallel.
+ This usually helps on both single- and multi-processor
+ machines.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>What if something goes wrong?</term>
+
+ <listitem>
+ <para>First, make absolutely sure that the environment has
+ no extraneous cruft from earlier builds:</para>
+
+ <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make cleandir</userinput>
&prompt.root; <userinput>make cleandir</userinput></screen>
- <para>Yes, <command>make cleandir</command> really should
- be run twice.</para>
+ <para>Yes, <command>make cleandir</command> really should
+ be run twice.</para>
- <para>Then restart the whole process, starting
- with <command>make buildworld</command>.</para>
+ <para>Then, restart the whole process, starting with
+ <command>make buildworld</command>.</para>
- <para>If you still have problems, send the error and the
- output of <command>uname -a</command> to &a.questions;.
- Be prepared to answer other questions about your
- setup!</para>
- </answer>
- </qandaentry>
- </qandaset>
+ <para>If problems persist, send the error and the output
+ of <command>uname -a</command> to &a.questions;. Be
+ prepared to answer other questions about the
+ setup!</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
</sect1>
<sect1 xml:id="small-lan">
- <info><title>Tracking for Multiple Machines</title>
+ <info>
+ <title>追蹤多追蹤多部機器</title>
+
<authorgroup>
- <author><personname><firstname>Mike</firstname><surname>Meyer</surname></personname><contrib>Contributed by </contrib></author>
+ <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>
+ <secondary>安裝多部機器</secondary>
</indexterm>
- <para>If you have multiple machines that you want to track the
- same source tree, then having all of them download sources and
- rebuild everything seems like a waste of resources: disk space,
- network bandwidth, and CPU cycles. It is, and the solution is
- to have one machine do most of the work, while the rest of the
- machines mount that work via NFS. This section outlines a
- method of doing so.</para>
-
- <sect2 xml:id="small-lan-preliminaries">
- <title>Preliminaries</title>
-
- <para>First, identify a set of machines that is going to run
- the same set of binaries, which we will call a
- <emphasis>build set</emphasis>. Each machine can have a
- custom kernel, but they will be running the same userland
- binaries. From that set, choose a machine to be the
- <emphasis>build machine</emphasis>. It is going to be the
- machine that the world and kernel are built on. Ideally, it
- should be a fast machine that has sufficient spare CPU to
- run <command>make buildworld</command> and
- <command>make buildkernel</command>. You will also want to
- choose a machine to be the <emphasis>test
- machine</emphasis>, which will test software updates before they
- are put into production. This <emphasis>must</emphasis> be a
- machine that you can afford to have 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 same machine, and at
- the same point. Ideally, those are on two different drives
- on the build machine, but they can be NFS mounted on that machine
- as well. If you have multiple build sets,
- <filename>/usr/src</filename> should be on one build machine, and
- NFS mounted on the rest.</para>
-
- <para>Finally make sure that
- <filename>/etc/make.conf</filename> on all the machines in
- the build set agrees 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 <varname>KERNCONF</varname>, listing
- its own kernel first. The build machine must have the kernel
- configuration files for each machine in
- <filename>/usr/src/sys/arch/conf</filename>
- if it is going to build their kernels.</para>
- </sect2>
-
- <sect2>
- <title>The Base System</title>
-
- <para>Now that all that is done, you are ready to build
- everything. Build the kernel and world as described in <xref linkend="make-buildworld"/> on the build machine,
- but do not install anything. After the build has finished, go
- to the test machine, and install the kernel you just
- built. If this machine mounts <filename>/usr/src</filename>
- and <filename>/usr/obj</filename> via NFS, when you reboot
- to single user you will need to enable the network and mount
- them. The easiest way to do this is to boot to multi-user,
- then run <command>shutdown now</command> to go to single user
- mode. Once there, you can install the new kernel and world and run
- <command>mergemaster</command> just as you normally would. When
- done, reboot to return to normal multi-user operations for this
- machine.</para>
-
- <para>After you are certain 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>
- </sect2>
-
- <sect2>
- <title>Ports</title>
-
- <para>The same ideas can be used for the ports tree. The first
- critical step is mounting <filename>/usr/ports</filename> from
- the same machine to all the machines in the build set. You can
- then set up <filename>/etc/make.conf</filename> properly to share
- distfiles. You should set <varname>DISTDIR</varname> to a
- common shared directory that is writable by whichever user
- <systemitem class="username">root</systemitem> is mapped to by your NFS mounts. Each
- machine should set <varname>WRKDIRPREFIX</varname> to a
- local build directory. Finally, if you are going to be
- building and distributing packages, you should set
- <varname>PACKAGES</varname> to a directory similar to
- <varname>DISTDIR</varname>.</para>
- </sect2>
+ <para>當有多部機器需要追蹤同一個原始碼樹,
+ 會浪費磁碟空間,網路頻寬,和
+ <acronym>中央處理器</acronym>周期來讓每個系統下載原始碼和編譯所有東西。
+ 解決方法是有解決方法是有一台機器做大部份的工作,剩下的機器經由
+ <acronym>NFS</acronym>來掛載這個工作。這一節概述了一個如此做的方法。
+ 更多關於使用 <acronym>NFS</acronym>的資訊,請參考<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>
diff --git a/zh_TW.UTF-8/books/handbook/disks/chapter.xml b/zh_TW.UTF-8/books/handbook/disks/chapter.xml
index f659610fd1..474aee65ad 100644
--- a/zh_TW.UTF-8/books/handbook/disks/chapter.xml
+++ b/zh_TW.UTF-8/books/handbook/disks/chapter.xml
@@ -1,17 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The FreeBSD Documentation Project
+ The FreeBSD Traditional Chinese Project
$FreeBSD$
- Original revision: 1.246
+ Original revision: r46056
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="disks">
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="disks">
+
<title>儲存設備篇</title>
<sect1 xml:id="disks-synopsis">
<title>概述</title>
-
<para>本章涵蓋如何在 FreeBSD 下使用碟片裝置
<footnote>
<para>譯註:雖然有些設備沒有『碟片』,例如 USB 隨身碟,
@@ -343,327 +346,152 @@
</sect2>
</sect1>
- <sect1 xml:id="raid">
- <title>RAID</title>
-
- <sect2 xml:id="raid-soft">
- <title>軟體 RAID</title>
-
- <sect3 xml:id="ccd">
- <info><title>連接式磁碟裝置驅動程式(CCD, Concatenated Disk Driver) 設定</title>
- <authorgroup>
- <author><personname><firstname>Christopher</firstname><surname>Shumway</surname></personname><contrib>Original work by </contrib></author>
- </authorgroup>
- <authorgroup>
- <author><personname><firstname>Jim</firstname><surname>Brown</surname></personname><contrib>Revised by </contrib></author>
- </authorgroup>
- </info>
-
-
-
-<indexterm><primary>RAID</primary><secondary>software</secondary></indexterm>
-<indexterm>
- <primary>RAID</primary><secondary>CCD</secondary>
-</indexterm>
-
- <para>對大容量儲存設備而言,最關鍵的要素乃是速度、可靠性及價格。
- 然而這三者往往難以兼顧:快速可靠的設備通常很貴;
- 而降低成本通常也犧牲了速度或可靠性。</para>
-
- <para>接下來要介紹的系統,價格是最重要的考量,接下來是速度,
- 最後才是可靠性。 順序如此是因為資料傳輸的速度最終取決於網路,
- 而儘管可靠性十分重要,卻有簡單的取代方案:
- 將資料完整備份於 CD-R 中。</para>
-
- <para>選擇大容量儲存設備方案時,首先要定義您的需求。
- 如果您重視速度或可靠性甚於價格,接下來的介紹恐非您所需。</para>
-
- <sect4 xml:id="ccd-installhw">
- <title>安裝硬體</title>
-
- <para>除了系統磁碟外,下面介紹的 CCD 磁碟陣列將使用到三顆 30GB、
- 5400 RPM 的 Western Digital IDE 磁碟,以提供約 90GB 的儲存空間。
- 最理想的情況是每個磁碟由獨立使用的排線連接獨立使用的 IDE 控制器,
- 不過為了降低成本,利用 jumper 設定磁碟,使每個 IDE 控制器可連接
- 一個主磁碟加一個副磁碟,如此可不必加裝額外的 IDE 控制器。</para>
-
- <para>開機後,BIOS 應該設定成自重偵測磁碟。更重要的是 FreeBSD 應該
- 要偵測到它們:</para>
-
- <programlisting>ad0: 19574MB &lt;WDC WD205BA&gt; [39770/16/63] at ata0-master UDMA33
-ad1: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata0-slave UDMA33
-ad2: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata1-master UDMA33
-ad3: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata1-slave UDMA33</programlisting>
-
- <note>
- <para>如果 FreeBSD 沒有偵測到所有磁碟,請確認 jumper 都設定正確。
- 許多 IDE 磁碟可以設定成 <quote>Cable Select</quote>
- (根據排線位置決定),這<emphasis>並非</emphasis> master(主磁碟)
- 或 slave(副磁碟)。 請參閱磁碟的說明文件以正確設定 jumper
- 。</para></note>
-
- <para>接下來,考慮如何將它們變成檔案系統的一部份。您可以參考
- &man.vinum.8;(<xref linkend="vinum-vinum"/>) 及 &man.ccd.4;。
- 在此我們選擇 &man.ccd.4;。</para>
- </sect4>
-
- <sect4 xml:id="ccd-setup">
- <title>設定 CCD</title>
-
- <para>&man.ccd.4; 可以將多個磁碟接起來成為一個大磁碟。要使用
- &man.ccd.4;,您的 kernel 需要支援 &man.ccd.4;。將這行加入到
- kernel 設定檔,並重編、重安裝 kernel:</para>
-
- <programlisting>device ccd</programlisting>
-
- <para>也可以載入 kernel 動態模組來支援 &man.ccd.4;。</para>
-
- <para>使用 &man.ccd.4; 請先用 &man.bsdlabel.8; 來初始磁碟:</para>
-
- <programlisting>bsdlabel -r -w ad1 auto
-bsdlabel -r -w ad2 auto
-bsdlabel -r -w ad3 auto</programlisting>
-
- <para>上述指令會建立 <filename>ad1c</filename>,
- <filename>ad2c</filename> 和 <filename>ad3c</filename>,
- 這些 bsdlabel 都使用了整個磁碟。</para>
-
- <para>下一步是修改 label type,同樣用 &man.bsdlabel.8; 來處理:</para>
-
- <programlisting>bsdlabel -e ad1
-bsdlabel -e ad2
-bsdlabel -e ad3</programlisting>
-
- <para>這個指令會打開一個編輯器(預設是 &man.vi.1;,可以用
- <envar>EDITOR</envar> 環境變數來指定其它編輯器),並將目前磁碟的 label
- 資訊顯示在該編輯器裡。</para>
-
- <para>一個還未變動過的磁碟 label 資訊看起來會像這樣:</para>
-
- <programlisting>8 partitions:
-# size offset fstype [fsize bsize bps/cpg]
- c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)</programlisting>
-
- <para>在此我們要新增一個 <literal>e</literal> partition 給
- &man.ccd.4; 使用。 通常複製 <literal>c</literal> partition 那一行,
- 再把 <option>fstype</option> 那一行改成
- <userinput>4.2BSD</userinput> 就可以了。
- 改完之後看起來應該會像這樣:</para>
-
- <programlisting>8 partitions:
-# size offset fstype [fsize bsize bps/cpg]
- c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)
- e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)</programlisting>
-
- </sect4>
-
- <sect4 xml:id="ccd-buildingfs">
- <title>建立檔案系統</title>
-
- <para>現在所有的磁碟都已經建好 bsdlabel 了,可以開始建立 &man.ccd.4;。
- 用 &man.ccdconfig.8; 來建立 &man.ccd.4;,參考下面的指令:</para>
-
- <programlisting>ccdconfig ccd0<co xml:id="co-ccd-dev"/> 32<co xml:id="co-ccd-interleave"/> 0<co xml:id="co-ccd-flags"/> /dev/ad1e<co xml:id="co-ccd-devs"/> /dev/ad2e /dev/ad3e</programlisting>
-
- <para>每個參數的作用如下:</para>
-
- <calloutlist>
- <callout arearefs="co-ccd-dev">
- <para>第一個參數是要設定的裝置名稱,在這個例子裡是
- <filename>/dev/ccd0c</filename>。其中 <filename>/dev/</filename>
- 可有可無。</para>
- </callout>
-
- <callout arearefs="co-ccd-interleave">
-
- <para>「interleave」的大小。所謂 interleave 是指一排磁碟區塊
- (disk block)的大小,通常以 512 bytes 為單位,所以 interleave
- 設為 32 即為 16,384 bytes。</para>
- </callout>
-
- <callout arearefs="co-ccd-flags">
- <para>&man.ccdconfig.8; 設定模式的參數。如果您打算啟用磁碟鏡設
- (drive mirroring),您可以在此指定參數。這個例子沒有使用鏡設,
- 所以設成 0。</para>
- </callout>
-
- <callout arearefs="co-ccd-devs">
- <para>&man.ccdconfig.8; 最後的參數是要加入到陣列的所有磁碟。
- 請使用完整的路徑。</para>
- </callout>
- </calloutlist>
-
-
- <para>執行 &man.ccdconfig.8; 之後,&man.ccd.4;
- 已設定完成可供建立檔案系統。 請參考 &man.newfs.8; 或輸入:</para>
-
- <programlisting>newfs /dev/ccd0c</programlisting>
-
-
- </sect4>
-
- <sect4 xml:id="ccd-auto">
- <title>讓一切自動完成</title>
-
- <para>通常您會希望每次開機時都能自動掛上(mount) &man.ccd.4;。
- 用下面的指令將您目前的設定寫入 <filename>/etc/ccd.conf</filename>
- :</para>
-
- <programlisting>ccdconfig -g &gt; /etc/ccd.conf</programlisting>
-
- <para>如果 <filename>/etc/ccd.conf</filename> 存在,每次開機時
- <command>/etc/rc</command> 都會執行 <command>ccdconfig -C</command>
- 。 如此便可自動設定 &man.ccd.4; 以便之後掛上(mount)檔案系統。
- </para>
-
- <note><para>如果您開機時選擇進入單人模式(single mode),在掛上
- (&man.mount.8;) &man.ccd.4; 的檔案系統之前您得先執行設定的指令:
- </para>
-
- <programlisting>ccdconfig -C</programlisting>
- </note>
-
- <para>要在每次開機時自動掛上(mount) &man.ccd.4;,請在
- <filename>/etc/fstab</filename> 加入 &man.ccd.4;:
- </para>
+ <sect1 xml:id="disks-growing">
+ <info>
+ <title>Resizing and Growing Disks</title>
- <programlisting>/dev/ccd0c /media ufs rw 2 2</programlisting>
- </sect4>
- </sect3>
-
- <sect3 xml:id="vinum">
- <title>Vinum 容量管理系統</title>
-
-<indexterm><primary>RAID</primary><secondary>software</secondary></indexterm>
-<indexterm>
- <primary>RAID</primary>
- <secondary>Vinum</secondary>
-</indexterm>
-
- <para>Vinum 容量管理系統(以下簡稱 Vinum) 可視為一種虛擬磁碟。
- 它將區塊裝置(block device) 的介面與對應資料的方式切割開來,比起原本
- slice 劃分的磁碟,Vinum 可增加了彈性、效能和穩定度
- <footnote><para>譯註:原文這裡是用「和」,但要視實際使用方式而定。
- 例如用 RAID-0 就不會增加穩定度 :)。</para></footnote>
- &man.vinum.8; 實作了 RAID-0、RAID-1 和 RAID-5 等模組,
- 它們都可以單獨使用,也可以互相搭配使用。</para>
-
- <para>請見 <xref linkend="vinum-vinum"/> 以參考更多關於
- &man.vinum.8; 的資訊。</para>
- </sect3>
- </sect2>
-
- <sect2 xml:id="raid-hard">
- <title>硬體 RAID</title>
-
- <indexterm>
- <primary>RAID</primary>
- <secondary>hardware</secondary>
- </indexterm>
-
- <para>FreeBSD 也支援許多硬體 <acronym>RAID</acronym> 控制器。
- 這些控制器自行掌控一個小型的 <acronym>RAID</acronym> 系統,
- 因此不需要特定軟體來管理。</para>
-
- <para>透過控制器上的 <acronym>BIOS</acronym> 幾乎能控制所有的操作。
- 接下來將簡單介紹如何設定 Promise <acronym>IDE</acronym>
- <acronym>RAID</acronym> 控制卡。首先確認控制卡已安裝,接著開機。
- 它應該會提示一些資訊<footnote><para>譯註:例如按 F1 可以進入控制卡
- BIOS 之類的資訊。</para></footnote>。依指示進入控制卡的設定畫面,
- 從這裡您可以將全部的硬體結合成一個大磁碟。完成之後,FreeBSD
- 將只會看到這個大磁碟。當然您也可以使用其它的
- <acronym>RAID</acronym> 模式。</para>
- </sect2>
-
- <sect2>
- <title>重建(rebuild) ATA RAID1 陣列</title>
-
- <para>FreeBSD 允許您熱插拔磁碟陣列裡壞掉的磁碟,
- 當然在重開機前就得先發現。</para>
-
- <para>也許您會在 <filename>/var/log/messages</filename>(或 &man.dmesg.8;
- 的輸出) 看到類似下面的訊息:</para>
-
- <programlisting>ad6 on monster1 suffered a hard error.
-ad6: READ command timeout tag=0 serv=0 - resetting
-ad6: trying fallback to PIO mode
-ata3: resetting devices .. done
-ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11)\\
-status=59 error=40
-ar0: WARNING - mirror lost</programlisting>
-
- <para>請用 &man.atacontrol.8; 來得到更多資訊:</para>
-
- <screen>&prompt.root; <userinput>atacontrol list</userinput>
-ATA channel 0:
- Master: no device present
- Slave: acd0 &lt;HL-DT-ST CD-ROM GCR-8520B/1.00&gt; ATA/ATAPI rev 0
-
-ATA channel 1:
- Master: no device present
- Slave: no device present
-
-ATA channel 2:
- Master: ad4 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
- Slave: no device present
-
-ATA channel 3:
- Master: ad6 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
- Slave: no device present
-
-&prompt.root; <userinput>atacontrol status ar0</userinput>
-ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED</screen>
-
- <procedure>
- <step>
- <para>首先您得將損壞磁碟所在的 ata channel 卸載(detach),
- 如此才能安全地移除:</para>
-
- <screen>&prompt.root; <userinput>atacontrol detach ata3</userinput></screen>
- </step>
-
- <step>
- <para>用好的磁碟換下損壞的。</para>
- </step>
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Allan</firstname>
+ <surname>Jude</surname>
+ </personname>
+ <contrib>Originally contributed by </contrib>
+ </author>
+ </authorgroup>
+ </info>
- <step>
- <para>重新載入(re-attach) ata channel:</para>
+ <indexterm>
+ <primary>disks</primary>
+ <secondary>resizing</secondary>
+ </indexterm>
- <screen>&prompt.root; <userinput>atacontrol attach ata3</userinput>
-Master: ad6 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
-Slave: no device present</screen>
- </step>
+ <para>A disk's capacity can increase without any changes to the
+ data already present. This happens commonly with virtual
+ machines, when the virtual disk turns out to be too small and is
+ enlarged. Sometimes a disk image is written to a
+ <acronym>USB</acronym> memory stick, but does not use the full
+ capacity. Here we describe how to resize or
+ <emphasis>grow</emphasis> disk contents to take advantage of
+ increased capacity.</para>
+
+ <para>Determine the device name of the disk to be resized by
+ inspecting <filename>/var/run/dmesg.boot</filename>. In this
+ example, there is only one <acronym>SATA</acronym> disk in the
+ system, so the drive will appear as
+ <filename>ada0</filename>.</para>
- <step>
- <para>將新的磁碟加入原本的磁碟陣列成為備援(spare) 磁碟:</para>
+ <indexterm><primary>partitions</primary></indexterm>
+ <indexterm>
+ <primary><command>gpart</command></primary>
+ </indexterm>
- <screen>&prompt.root; <userinput>atacontrol addspare ar0 ad6</userinput></screen>
- </step>
+ <para>List the partitions on the disk to see the current
+ configuration:</para>
- <step>
- <para>重建磁碟陣列:</para>
+ <screen>&prompt.root; <userinput>gpart show <replaceable>ada0</replaceable></userinput>
+=> 34 83886013 ada0 GPT (48G) [CORRUPT]
+ 34 128 1 freebsd-boot (64k)
+ 162 79691648 2 freebsd-ufs (38G)
+ 79691810 4194236 3 freebsd-swap (2G)
+ 83886046 1 - free - (512B)</screen>
- <screen>&prompt.root; <userinput>atacontrol rebuild ar0</userinput></screen>
- </step>
+ <note>
+ <para>If the disk was formatted with the <link
+ xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">
+ <acronym>GPT</acronym></link> partitioning scheme, it may show
+ as <quote>corrupted</quote> because the <acronym>GPT</acronym>
+ backup partition table is no longer at the end of the
+ drive. Fix the backup
+ partition table with
+ <command>gpart</command>:</para>
+
+ <screen>&prompt.root; <userinput>gpart recover <replaceable>ada0</replaceable></userinput>
+ada0 recovered</screen>
+ </note>
- <step>
- <para>可以用下面指定來確認重建的進度:</para>
+ <para>Now the additional space on the disk is available for
+ use by a new partition, or an existing partition can be
+ expanded:</para>
+
+ <screen>&prompt.root; <userinput>gpart show <replaceable>ada0</replaceable></userinput>
+=> 34 102399933 ada0 GPT (48G)
+ 34 128 1 freebsd-boot (64k)
+ 162 79691648 2 freebsd-ufs (38G)
+ 79691810 4194236 3 freebsd-swap (2G)
+ 83886046 18513921 - free - (8.8G)</screen>
+
+ <para>Partitions can only be resized into contiguous free space.
+ Here, the last partition on the disk is the swap partition, but
+ the second partition is the one that needs to be resized. Swap
+ partitions only contain temporary data, so it can safely be
+ unmounted, deleted, and then recreated after resizing other
+ partitions.</para>
+
+ <screen>&prompt.root; <userinput>swapoff <replaceable>/dev/ada0p3</replaceable></userinput>
+&prompt.root; <userinput>gpart delete -i <replaceable>3</replaceable> <replaceable>ada0</replaceable></userinput>
+ada0p3 deleted
+&prompt.root; <userinput>gpart show <replaceable>ada0</replaceable></userinput>
+=> 34 102399933 ada0 GPT (48G)
+ 34 128 1 freebsd-boot (64k)
+ 162 79691648 2 freebsd-ufs (38G)
+ 79691810 22708157 - free - (10G)</screen>
+
+ <warning>
+ <para>There is risk of data loss when modifying the partition
+ table of a mounted file system. It is best to perform the
+ following steps on an unmounted file system while running from
+ a live <acronym>CD-ROM</acronym> or <acronym>USB</acronym>
+ device. However, if absolutely necessary, a mounted file
+ system can be resized after disabling GEOM safety
+ features:</para>
+
+ <screen>&prompt.root; <userinput>sysctl kern.geom.debugflags=16</userinput></screen>
+ </warning>
+
+ <para>Resize the partition, leaving room to recreate a swap
+ partition of the desired size. This only modifies the size of
+ the partition. The file system in the partition will be
+ expanded in a separate step.</para>
+
+ <screen>&prompt.root; <userinput>gpart resize -i <replaceable>2</replaceable> -a 4k -s <replaceable>47G</replaceable> <replaceable>ada0</replaceable></userinput>
+ada0p2 resized
+&prompt.root; <userinput>gpart show <replaceable>ada0</replaceable></userinput>
+=> 34 102399933 ada0 GPT (48G)
+ 34 128 1 freebsd-boot (64k)
+ 162 98566144 2 freebsd-ufs (47G)
+ 98566306 3833661 - free - (1.8G)</screen>
+
+ <para>Recreate the swap partition:</para>
+
+ <screen>&prompt.root; <userinput>gpart add -t freebsd-swap -a 4k <replaceable>ada0</replaceable></userinput>
+ada0p3 added
+&prompt.root; <userinput>gpart show <replaceable>ada0</replaceable></userinput>
+=> 34 102399933 ada0 GPT (48G)
+ 34 128 1 freebsd-boot (64k)
+ 162 98566144 2 freebsd-ufs (47G)
+ 98566306 3833661 3 freebsd-swap (1.8G)
+&prompt.root; <userinput>swapon <replaceable>/dev/ada0p3</replaceable></userinput></screen>
+
+ <para>Grow the <acronym>UFS</acronym> file system to use the new
+ capacity of the resized partition:</para>
- <screen>&prompt.root; <userinput>dmesg | tail -10</userinput>
-[output removed]
-ad6: removed from configuration
-ad6: deleted from ar0 disk1
-ad6: inserted into ar0 disk1 as spare
+ <note>
+ <para>Growing a live <acronym>UFS</acronym> file system is only
+ possible in &os; 10.0-RELEASE and later. For earlier
+ versions, the file system must not be mounted.</para>
+ </note>
-&prompt.root; <userinput>atacontrol status ar0</userinput>
-ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed</screen>
- </step>
+ <screen>&prompt.root; <userinput>growfs <replaceable>/dev/ada0p2</replaceable></userinput>
+Device is mounted read-write; resizing will result in temporary write suspension for /.
+It's strongly recommended to make a backup before growing the file system.
+OK to grow file system on /dev/ada0p2, mounted on /, from 38GB to 47GB? [Yes/No] <userinput>Yes</userinput>
+super-block backups (for fsck -b #) at:
+ 80781312, 82063552, 83345792, 84628032, 85910272, 87192512, 88474752,
+ 89756992, 91039232, 92321472, 93603712, 94885952, 96168192, 97450432</screen>
- <step>
- <para>等重建完就完成了。</para>
- </step>
- </procedure>
- </sect2>
+ <para>Both the partition and the file system on it have now been
+ resized to use the newly-available disk space.</para>
</sect1>
<sect1 xml:id="usb-disks">
@@ -777,223 +605,176 @@ umass0: detached</screen>
</sect1>
<sect1 xml:id="creating-cds">
- <info><title>Creating and Using Optical Media (CDs)</title>
+ <info>
+ <title>Creating and Using <acronym>CD</acronym> Media</title>
+
<authorgroup>
- <author><personname><firstname>Mike</firstname><surname>Meyer</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Mike</firstname>
+ <surname>Meyer</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
</authorgroup>
-
</info>
-
<indexterm>
- <primary>CDROMs</primary>
+ <primary><acronym>CD-ROM</acronym>s</primary>
<secondary>creating</secondary>
</indexterm>
- <sect2>
- <title>Introduction</title>
-
- <para>CDs have a number of features that differentiate them from
- conventional disks. Initially, they were not writable by the
- user. They are designed so that they can be read continuously without
- delays to move the head between tracks. They are also much easier
- to transport between systems than similarly sized media were at the
- time.</para>
-
- <para>CDs do have tracks, but this refers to a section of data to
- be read continuously and not a physical property of the disk. To
- produce a CD on FreeBSD, you prepare the data files that are going
- to make up the tracks on the CD, then write the tracks to the
- CD.</para>
-
- <indexterm><primary>ISO 9660</primary></indexterm>
- <indexterm>
- <primary>file systems</primary>
- <secondary>ISO 9660</secondary>
- </indexterm>
- <para>The ISO 9660 file system was designed to deal with these
- differences. It unfortunately codifies file system limits that were
- common then. Fortunately, it provides an extension mechanism that
- allows properly written CDs to exceed those limits while still
- working with systems that do not support those extensions.</para>
+ <para>Compact Disc (<acronym>CD</acronym>) media provide a number
+ of features that differentiate them from conventional disks.
+ They are designed so that they can be read continuously without
+ delays to move the head between tracks. While
+ <acronym>CD</acronym> media do have tracks, these refer to a
+ section of data to be read continuously, and not a physical
+ property of the disk. The <acronym>ISO</acronym> 9660 file
+ system was designed to deal with these differences.</para>
+
+ <indexterm><primary><acronym>ISO</acronym>
+ 9660</primary></indexterm>
+ <indexterm>
+ <primary>file systems</primary>
+ <secondary>ISO 9660</secondary>
+ </indexterm>
- <indexterm>
- <primary><package>sysutils/cdrtools</package></primary>
- </indexterm>
- <para>The <package>sysutils/cdrtools</package>
- port includes &man.mkisofs.8;, a program that you can use to
- produce a data file containing an ISO 9660 file
- system. It has options that support various extensions, and is
- described below.</para>
+ <indexterm>
+ <primary><acronym>CD</acronym> burner</primary>
+ <secondary><acronym>ATAPI</acronym></secondary>
+ </indexterm>
- <indexterm>
- <primary>CD burner</primary>
- <secondary>ATAPI</secondary>
- </indexterm>
- <para>Which tool to use to burn the CD depends on whether your CD burner
- is ATAPI or something else. ATAPI CD burners use the <command>burncd</command> program that is part of
- the base system. SCSI and USB CD burners should use
- <command>cdrecord</command> from
- the <package>sysutils/cdrtools</package> port.</para>
+ <para>The &os; Ports Collection provides several utilities for
+ burning and duplicating audio and data <acronym>CD</acronym>s.
+ This chapter demonstrates the use of several command line
+ utilities. For <acronym>CD</acronym> burning software with a
+ graphical utility, consider installing the
+ <package>sysutils/xcdroast</package> or
+ <package>sysutils/k3b</package> packages or ports.</para>
- <para><command>burncd</command> has a limited number of
- supported drives. To find out if a drive is supported, see the
- <link xlink:href="http://www.freebsd.dk/ata/">CD-R/RW supported
- drives</link> list.</para>
+ <sect2 xml:id="atapicam">
+ <info>
+ <title>Supported Devices</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </info>
- <note>
<indexterm>
- <primary>CD burner</primary>
+ <primary><acronym>CD</acronym> burner</primary>
<secondary>ATAPI/CAM driver</secondary>
</indexterm>
- <para>If you run &os;&nbsp;5.X, &os;&nbsp;4.8-RELEASE version or
- higher, it will be possible to use <command>cdrecord</command> and other tools
- for SCSI drives on an ATAPI hardware with the <link linkend="atapicam">ATAPI/CAM module</link>.</para>
- </note>
- <para>If you want a CD burning software with a graphical user
- interface, you should have a look to
- <application>X-CD-Roast</application> or
- <application>K3b</application>. These tools are available as
- packages or from the <package>sysutils/xcdroast</package> and <package>sysutils/k3b</package> ports.
- <application>X-CD-Roast</application> and
- <application>K3b</application> require the <link linkend="atapicam">ATAPI/CAM module</link> with ATAPI
- hardware.</para>
- </sect2>
+ <para>The <filename>GENERIC</filename> kernel provides support
+ for <acronym>SCSI</acronym>, <acronym>USB</acronym>, and
+ <acronym>ATAPI</acronym> <acronym>CD</acronym> readers and
+ burners. If a custom kernel is used, the options that need to
+ be present in the kernel configuration file vary by the type
+ of device.</para>
+
+ <para>For a <acronym>SCSI</acronym> burner, make sure these
+ options are present:</para>
+
+ <programlisting>device scbus # SCSI bus (required for ATA/SCSI)
+device da # Direct Access (disks)
+device pass # Passthrough device (direct ATA/SCSI access)
+device cd # needed for CD and DVD burners</programlisting>
+
+ <para>For a <acronym>USB</acronym> burner, make sure these
+ options are present:</para>
+
+ <programlisting>device scbus # SCSI bus (required for ATA/SCSI)
+device da # Direct Access (disks)
+device pass # Passthrough device (direct ATA/SCSI access)
+device cd # needed for CD and DVD burners
+device uhci # provides USB 1.x support
+device ohci # provides USB 1.x support
+device ehci # provides USB 2.0 support
+device xhci # provides USB 3.0 support
+device usb # USB Bus (required)
+device umass # Disks/Mass storage - Requires scbus and da</programlisting>
+
+ <para>For an <acronym>ATAPI</acronym> burner, make sure these
+ options are present:</para>
+
+ <programlisting>device ata # Legacy ATA/SATA controllers
+device scbus # SCSI bus (required for ATA/SCSI)
+device pass # Passthrough device (direct ATA/SCSI access)
+device cd # needed for CD and DVD burners</programlisting>
- <sect2 xml:id="mkisofs">
- <title>mkisofs</title>
+ <note>
+ <para>On &os; versions prior to 10.x, this line is also
+ needed in the kernel configuration file if the burner is an
+ <acronym>ATAPI</acronym> device:</para>
- <para>The &man.mkisofs.8; program, which is part of the
- <package>sysutils/cdrtools</package> port,
- produces an ISO 9660 file system
- that is an image of a directory tree in the &unix; file system name
- space. The simplest usage is:</para>
+ <programlisting>device atapicam</programlisting>
- <screen>&prompt.root; <userinput>mkisofs -o imagefile.iso /path/to/tree</userinput></screen>
+ <para>Alternately, this driver can be loaded at boot time by
+ adding the following line to
+ <filename>/boot/loader.conf</filename>:</para>
- <indexterm>
- <primary>file systems</primary>
- <secondary>ISO 9660</secondary>
- </indexterm>
- <para>This command will create an <replaceable>imagefile.iso</replaceable>
- containing an ISO 9660 file system that is a copy of the tree at
- <replaceable>/path/to/tree</replaceable>. In the process, it will
- map the file names to names that fit the limitations of the
- standard ISO 9660 file system, and will exclude files that have
- names uncharacteristic of ISO file systems.</para>
+ <programlisting>atapicam_load="YES"</programlisting>
- <indexterm>
- <primary>file systems</primary>
- <secondary>HFS</secondary>
- </indexterm>
- <indexterm>
- <primary>file systems</primary>
- <secondary>Joliet</secondary>
- </indexterm>
- <para>A number of options are available to overcome those
- restrictions. In particular, <option>-R</option> enables the
- Rock Ridge extensions common to &unix; systems, <option>-J</option>
- enables Joliet extensions used by Microsoft systems, and
- <option>-hfs</option> can be used to create HFS file systems used
- by &macos;.</para>
-
- <para>For CDs that are going to be used only on FreeBSD systems,
- <option>-U</option> can be used to disable all filename
- restrictions. When used with <option>-R</option>, it produces a
- file system image that is identical to the FreeBSD tree you started
- from, though it may violate the ISO 9660 standard in a number of
- ways.</para>
+ <para>This will require a reboot of the system as this driver
+ can only be loaded at boot time.</para>
+ </note>
- <indexterm>
- <primary>CDROMs</primary>
- <secondary>creating bootable</secondary>
- </indexterm>
- <para>The last option of general use is <option>-b</option>. This is
- used to specify the location of the boot image for use in producing an
- <quote>El Torito</quote> bootable CD. This option takes an
- argument which is the path to a boot image from the top of the
- tree being written to the CD. By default, &man.mkisofs.8; creates an
- ISO image in the so-called <quote>floppy disk emulation</quote> mode,
- and thus expects the boot image to be exactly 1200, 1440 or
- 2880&nbsp;KB in size. Some boot loaders, like the one used by the
- FreeBSD distribution disks, do not use emulation mode; in this case,
- the <option>-no-emul-boot</option> option should be used. So, if
- <filename>/tmp/myboot</filename> holds a bootable FreeBSD system
- with the boot image in
- <filename>/tmp/myboot/boot/cdboot</filename>, you could produce the
- image of an ISO 9660 file system in
- <filename>/tmp/bootable.iso</filename> like so:</para>
+ <para>To verify that &os; recognizes the device, run
+ <command>dmesg</command> and look for an entry for the device.
+ On systems prior to 10.x, the device name in the first line of
+ the output will be <filename>acd0</filename> instead of
+ <filename>cd0</filename>.</para>
+
+ <screen>&prompt.user; <userinput>dmesg | grep cd</userinput>
+cd0 at ahcich1 bus 0 scbus1 target 0 lun 0
+cd0: &lt;HL-DT-ST DVDRAM GU70N LT20&gt; Removable CD-ROM SCSI-0 device
+cd0: Serial Number M3OD3S34152
+cd0: 150.000MB/s transfers (SATA 1.x, UDMA6, ATAPI 12bytes, PIO 8192bytes)
+cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed</screen>
+ </sect2>
- <screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen>
+ <sect2 xml:id="cdrecord">
+ <title>Burning a <acronym>CD</acronym></title>
- <para>Having done that, if you have <filename>md</filename>
- configured in your kernel, you can mount the file system with:</para>
+ <para>In &os;, <command>cdrecord</command> can be used to burn
+ <acronym>CD</acronym>s. This command is installed with the
+ <package>sysutils/cdrtools</package> package or port.</para>
- <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /tmp/bootable.iso -u 0</userinput>
-&prompt.root; <userinput>mount -t cd9660 /dev/md0 /mnt</userinput></screen>
+ <note>
+ <para>&os; 8.x includes the built-in
+ <command>burncd</command> utility for burning
+ <acronym>CD</acronym>s using an <acronym>ATAPI</acronym>
+ <acronym>CD</acronym> burner. Refer to the manual page for
+ <command>burncd</command> for usage examples.</para>
+ </note>
- <para>At which point you can verify that <filename>/mnt</filename>
- and <filename>/tmp/myboot</filename> are identical.</para>
+ <para>While <command>cdrecord</command> has many options, basic
+ usage is simple. Specify the name of the
+ <acronym>ISO</acronym> file to burn and, if the system has
+ multiple burner devices, specify the name of the device to
+ use:</para>
- <para>There are many other options you can use with
- &man.mkisofs.8; to fine-tune its behavior. In particular:
- modifications to an ISO 9660 layout and the creation of Joliet
- and HFS discs. See the &man.mkisofs.8; manual page for details.</para>
- </sect2>
+ <screen>&prompt.root; <userinput>cdrecord <replaceable>dev=device</replaceable> <replaceable>imagefile.iso</replaceable></userinput></screen>
- <sect2 xml:id="burncd">
- <title>burncd</title>
- <indexterm>
- <primary>CDROMs</primary>
- <secondary>burning</secondary>
- </indexterm>
- <para>If you have an ATAPI CD burner, you can use the
- <command>burncd</command> command to burn an ISO image onto a
- CD. <command>burncd</command> is part of the base system, installed
- as <filename>/usr/sbin/burncd</filename>. Usage is very simple, as
- it has few options:</para>
-
- <screen>&prompt.root; <userinput>burncd -f cddevice data imagefile.iso fixate</userinput></screen>
-
- <para>Will burn a copy of <replaceable>imagefile.iso</replaceable> on
- <replaceable>cddevice</replaceable>. The default device is
- <filename>/dev/acd0</filename>. See &man.burncd.8; for options to
- set the write speed, eject the CD after burning, and write audio
- data.</para>
- </sect2>
+ <para>To determine the device name of the burner, use
+ <option>-scanbus</option> which might produce results like
+ this:</para>
- <sect2 xml:id="cdrecord">
- <title>cdrecord</title>
-
- <para>If you do not have an ATAPI CD burner, you will have to use
- <command>cdrecord</command> to burn your
- CDs. <command>cdrecord</command> is not part of the base system;
- you must install it from either the port at <package>sysutils/cdrtools</package>
- or the appropriate
- package. Changes to the base system can cause binary versions of
- this program to fail, possibly resulting in a
- <quote>coaster</quote>. You should therefore either upgrade the
- port when you upgrade your system, or if you are <link linkend="stable">tracking -STABLE</link>, upgrade the port when a
- new version becomes available.</para>
-
- <para>While <command>cdrecord</command> has many options, basic usage
- is even simpler than <command>burncd</command>. Burning an ISO 9660
- image is done with:</para>
-
- <screen>&prompt.root; <userinput>cdrecord dev=device imagefile.iso</userinput></screen>
-
- <para>The tricky part of using <command>cdrecord</command> is finding
- the <option>dev</option> to use. To find the proper setting, use
- the <option>-scanbus</option> flag of <command>cdrecord</command>,
- which might produce results like this:</para>
<indexterm>
- <primary>CDROMs</primary>
- <secondary>burning</secondary>
+ <primary><acronym>CD-ROM</acronym>s</primary>
+ <secondary>burning</secondary>
</indexterm>
<screen>&prompt.root; <userinput>cdrecord -scanbus</userinput>
-Cdrecord-Clone 2.01 (i386-unknown-freebsd7.0) Copyright (C) 1995-2004 J&ouml;rg Schilling
-Using libscg version 'schily-0.1'
+ProDVD-ProBD-Clone 3.00 (amd64-unknown-freebsd10.0) Copyright (C) 1995-2010 J&ouml;rg Schilling
+Using libscg version 'schily-0.9'
scsibus0:
0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk
0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk
@@ -1013,590 +794,648 @@ scsibus1:
1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner
1,7,0 107) *</screen>
- <para>This lists the appropriate <option>dev</option> value for the
- devices on the list. Locate your CD burner, and use the three
- numbers separated by commas as the value for
- <option>dev</option>. In this case, the CRW device is 1,5,0, so the
- appropriate input would be
- <option>dev=1,5,0</option>. There are easier
- ways to specify this value; see &man.cdrecord.1; for
- details. That is also the place to look for information on writing
- audio tracks, controlling the speed, and other things.</para>
- </sect2>
-
- <sect2 xml:id="duplicating-audiocds">
- <title>Duplicating Audio CDs</title>
+ <para>Locate the entry for the <acronym>CD</acronym> burner and
+ use the three numbers separated by commas as the value for
+ <option>dev</option>. In this case, the Yamaha burner device
+ is <literal>1,5,0</literal>, so the appropriate input to
+ specify that device is <option>dev=1,5,0</option>. Refer to
+ the manual page for <command>cdrecord</command> for other ways
+ to specify this value and for information on writing audio
+ tracks and controlling the write speed.</para>
- <para>You can duplicate an audio CD by extracting the audio data from
- the CD to a series of files, and then writing these files to a blank
- CD. The process is slightly different for ATAPI and SCSI
- drives.</para>
-
- <procedure>
- <title>SCSI Drives</title>
+ <para>Alternately, run the following command to get the device
+ address of the burner:</para>
- <step>
- <para>Use <command>cdda2wav</command> to extract the audio.</para>
+ <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
+&lt;MATSHITA CDRW/DVD UJDA740 1.00&gt; at scbus1 target 0 lun 0 (cd0,pass0)</screen>
- <screen>&prompt.user; <userinput>cdda2wav -v255 -D2,0 -B -Owav</userinput></screen>
- </step>
+ <para>Use the numeric values for <literal>scbus</literal>,
+ <literal>target</literal>, and <literal>lun</literal>. For
+ this example, <literal>1,0,0</literal> is the device name to
+ use.</para>
+ </sect2>
- <step>
- <para>Use <command>cdrecord</command> to write the
- <filename>.wav</filename> files.</para>
+ <sect2 xml:id="mkisofs">
+ <title>Writing Data to an <acronym>ISO</acronym> File
+ System</title>
+
+ <para>In order to produce a data <acronym>CD</acronym>, the data
+ files that are going to make up the tracks on the
+ <acronym>CD</acronym> must be prepared before they can be
+ burned to the <acronym>CD</acronym>. In &os;,
+ <package>sysutils/cdrtools</package> installs
+ <command>mkisofs</command>, which can be used to produce an
+ <acronym>ISO</acronym> 9660 file system that is an image of a
+ directory tree within a &unix; file system. The simplest
+ usage is to specify the name of the <acronym>ISO</acronym>
+ file to create and the path to the files to place into the
+ <acronym>ISO</acronym> 9660 file system:</para>
+
+ <screen>&prompt.root; <userinput>mkisofs -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/tree</replaceable></userinput></screen>
- <screen>&prompt.user; <userinput>cdrecord -v dev=2,0 -dao -useinfo *.wav</userinput></screen>
+ <indexterm>
+ <primary>file systems</primary>
+ <secondary>ISO 9660</secondary>
+ </indexterm>
- <para>Make sure that <replaceable>2,0</replaceable> is set
- appropriately, as described in <xref linkend="cdrecord"/>.</para>
- </step>
- </procedure>
+ <para>This command maps the file names in the specified path to
+ names that fit the limitations of the standard
+ <acronym>ISO</acronym> 9660 file system, and will exclude
+ files that do not meet the standard for <acronym>ISO</acronym>
+ file systems.</para>
- <procedure>
- <title>ATAPI Drives</title>
+ <indexterm>
+ <primary>file systems</primary>
+ <secondary>Joliet</secondary>
+ </indexterm>
- <step>
- <para>The ATAPI CD driver makes each track available as
- <filename>/dev/acddtnn</filename>,
- where <replaceable>d</replaceable> is the drive number, and
- <replaceable>nn</replaceable> is the track number written with two
- decimal digits, prefixed with zero as needed.
- So the first track on the first disk is
- <filename>/dev/acd0t01</filename>, the second is
- <filename>/dev/acd0t02</filename>, the third is
- <filename>/dev/acd0t03</filename>, and so on.</para>
-
- <para>Make sure the appropriate files exist in
- <filename>/dev</filename>. If the entries are missing,
- force the system to retaste the media:</para>
-
- <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=/dev/null count=1</userinput></screen>
+ <para>A number of options are available to overcome the
+ restrictions imposed by the standard. In particular,
+ <option>-R</option> enables the Rock Ridge extensions common
+ to &unix; systems and <option>-J</option> enables Joliet
+ extensions used by &microsoft; systems.</para>
- </step>
+ <para>For <acronym>CD</acronym>s that are going to be used only
+ on &os; systems, <option>-U</option> can be used to disable
+ all filename restrictions. When used with
+ <option>-R</option>, it produces a file system image that is
+ identical to the specified &os; tree, even if it violates the
+ <acronym>ISO</acronym> 9660 standard.</para>
- <step>
- <para>Extract each track using &man.dd.1;. You must also use a
- specific block size when extracting the files.</para>
+ <indexterm>
+ <primary><acronym>CD-ROM</acronym>s</primary>
+ <secondary>creating bootable</secondary>
+ </indexterm>
- <screen>&prompt.root; <userinput>dd if=/dev/acd0t01 of=track1.cdr bs=2352</userinput>
-&prompt.root; <userinput>dd if=/dev/acd0t02 of=track2.cdr bs=2352</userinput>
-...
-</screen>
- </step>
+ <para>The last option of general use is <option>-b</option>.
+ This is used to specify the location of a boot image for use
+ in producing an <quote>El Torito</quote> bootable
+ <acronym>CD</acronym>. This option takes an argument which is
+ the path to a boot image from the top of the tree being
+ written to the <acronym>CD</acronym>. By default,
+ <command>mkisofs</command> creates an <acronym>ISO</acronym>
+ image in <quote>floppy disk emulation</quote> mode, and thus
+ expects the boot image to be exactly 1200, 1440 or
+ 2880&nbsp;KB in size. Some boot loaders, like the one used by
+ the &os; distribution media, do not use emulation mode. In
+ this case, <option>-no-emul-boot</option> should be used. So,
+ if <filename>/tmp/myboot</filename> holds a bootable &os;
+ system with the boot image in
+ <filename>/tmp/myboot/boot/cdboot</filename>, this command
+ would produce
+ <filename>/tmp/bootable.iso</filename>:</para>
- <step>
- <para>Burn the extracted files to disk using
- <command>burncd</command>. You must specify that these are audio
- files, and that <command>burncd</command> should fixate the disk
- when finished.</para>
+ <screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen>
- <screen>&prompt.root; <userinput>burncd -f /dev/acd0 audio track1.cdr track2.cdr ... fixate</userinput></screen>
- </step>
- </procedure>
- </sect2>
+ <para>The resulting <acronym>ISO</acronym> image can be mounted
+ as a memory disk with:</para>
- <sect2 xml:id="imaging-cd">
- <title>Duplicating Data CDs</title>
+ <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /tmp/bootable.iso -u 0</userinput>
+&prompt.root; <userinput>mount -t cd9660 /dev/md0 /mnt</userinput></screen>
- <para>You can copy a data CD to a image file that is
- functionally equivalent to the image file created with
- &man.mkisofs.8;, and you can use it to duplicate
- any data CD. The example given here assumes that your CDROM
- device is <filename>acd0</filename>. Substitute your
- correct CDROM device.</para>
+ <para>One can then verify that <filename>/mnt</filename> and
+ <filename>/tmp/myboot</filename> are identical.</para>
- <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=file.iso bs=2048</userinput></screen>
+ <para>There are many other options available for
+ <command>mkisofs</command> to fine-tune its behavior. Refer
+ to &man.mkisofs.8; for details.</para>
- <para>Now that you have an image, you can burn it to CD as
- described above.</para>
+ <note>
+ <para>It is possible to copy a data <acronym>CD</acronym> to
+ an image file that is functionally equivalent to the image
+ file created with <command>mkisofs</command>. To do so, use
+ <filename>dd</filename> with the device name as the input
+ file and the name of the <acronym>ISO</acronym> to create as
+ the output file:</para>
+
+ <screen>&prompt.root; <userinput>dd if=/dev/<replaceable>cd0</replaceable> of=<replaceable>file.iso</replaceable> bs=2048</userinput></screen>
+
+ <para>The resulting image file can be burned to
+ <acronym>CD</acronym> as described in <xref
+ linkend="cdrecord"/>.</para>
+ </note>
</sect2>
<sect2 xml:id="mounting-cd">
- <title>Using Data CDs</title>
-
- <para>Now that you have created a standard data CDROM, you
- probably want to mount it and read the data on it. By
- default, &man.mount.8; assumes that a file system is of type
- <literal>ufs</literal>. If you try something like:</para>
-
- <screen>&prompt.root; <userinput>mount /dev/cd0 /mnt</userinput></screen>
-
- <para>you will get a complaint about <errorname>Incorrect super
- block</errorname>, and no mount. The CDROM is not a
- <literal>UFS</literal> file system, so attempts to mount it
- as such will fail. You just need to tell &man.mount.8; that
- the file system is of type <literal>ISO9660</literal>, and
- everything will work. You do this by specifying the
- <option>-t cd9660</option> option &man.mount.8;. For
- example, if you want to mount the CDROM device,
- <filename>/dev/cd0</filename>, under
- <filename>/mnt</filename>, you would execute:</para>
-
- <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen>
-
- <para>Note that your device name
- (<filename>/dev/cd0</filename> in this example) could be
- different, depending on the interface your CDROM uses. Also,
- the <option>-t cd9660</option> option just executes
- &man.mount.cd9660.8;. The above example could be shortened
- to:</para>
-
-<screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0 /mnt</userinput></screen>
-
- <para>You can generally use data CDROMs from any vendor in this
- way. Disks with certain ISO 9660 extensions might behave
- oddly, however. For example, Joliet disks store all filenames
- in two-byte Unicode characters. The FreeBSD kernel does not
- speak Unicode (yet!), so non-English characters show up as
- question marks. (The FreeBSD
- CD9660 driver includes hooks to load an appropriate Unicode
- conversion table on the fly. Modules for some of the common
- encodings are available via the
- <package>sysutils/cd9660_unicode</package> port.)</para>
-
- <para>Occasionally, you might get <errorname>Device not
- configured</errorname> when trying to mount a CDROM. This
- usually means that the CDROM drive thinks that there is no
- disk in the tray, or that the drive is not visible on the bus.
- It can take a couple of seconds for a CDROM drive to realize
- that it has been fed, so be patient.</para>
-
- <para>Sometimes, a SCSI CDROM may be missed because it did not
- have enough time to answer the bus reset. If you have a SCSI
- CDROM please add the following option to your kernel
- configuration and <link linkend="kernelconfig-building">rebuild your kernel</link>.</para>
+ <title>Using Data <acronym>CD</acronym>s</title>
- <programlisting>options SCSI_DELAY=15000</programlisting>
+ <para>Once an <acronym>ISO</acronym> has been burned to a
+ <acronym>CD</acronym>, it can be mounted by specifying the
+ file system type, the name of the device containing the
+ <acronym>CD</acronym>, and an existing mount point:</para>
- <para>This tells your SCSI bus to pause 15 seconds during boot,
- to give your CDROM drive every possible chance to answer the
- bus reset.</para>
- </sect2>
-
- <sect2 xml:id="rawdata-cd">
- <title>Burning Raw Data CDs</title>
-
- <para>You can choose to burn a file directly to CD, without
- creating an ISO 9660 file system. Some people do this for
- backup purposes. This runs more quickly than burning a
- standard CD:</para>
-
- <screen>&prompt.root; <userinput>burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate</userinput></screen>
-
- <para>In order to retrieve the data burned to such a CD, you
- must read data from the raw device node:</para>
-
- <screen>&prompt.root; <userinput>tar xzvf /dev/acd1</userinput></screen>
+ <screen>&prompt.root; <userinput>mount -t cd9660 <replaceable>/dev/cd0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
- <para>You cannot mount this disk as you would a normal CDROM.
- Such a CDROM cannot be read under any operating system
- except FreeBSD. If you want to be able to mount the CD, or
- share data with another operating system, you must use
- &man.mkisofs.8; as described above.</para>
- </sect2>
-
- <sect2 xml:id="atapicam">
- <info><title>Using the ATAPI/CAM Driver</title>
- <authorgroup>
- <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author>
- </authorgroup>
- </info>
+ <para>Since <command>mount</command> assumes that a file system
+ is of type <literal>ufs</literal>, a <errorname>Incorrect
+ super block</errorname> error will occur if <literal>-t
+ cd9660</literal> is not included when mounting a data
+ <acronym>CD</acronym>.</para>
-
+ <para>While any data <acronym>CD</acronym> can be mounted this
+ way, disks with certain <acronym>ISO</acronym> 9660 extensions
+ might behave oddly. For example, Joliet disks store all
+ filenames in two-byte Unicode characters. If some non-English
+ characters show up as question marks, specify the local
+ charset with <option>-C</option>. For more information, refer
+ to &man.mount.cd9660.8;.</para>
- <indexterm>
- <primary>CD burner</primary>
- <secondary>ATAPI/CAM driver</secondary>
- </indexterm>
+ <note>
+ <para>In order to do this character conversion with the help
+ of <option>-C</option>, the kernel requires the
+ <filename>cd9660_iconv.ko</filename> module to be loaded.
+ This can be done either by adding this line to
+ <filename>loader.conf</filename>:</para>
- <para>This driver allows ATAPI devices (CD-ROM, CD-RW, DVD
- drives etc...) to be accessed through the SCSI subsystem, and
- so allows the use of applications like <package>sysutils/cdrdao</package> or
- &man.cdrecord.1;.</para>
+ <programlisting>cd9660_iconv_load="YES"</programlisting>
- <para>To use this driver, you will need to add the following
- line to your kernel configuration file:</para>
+ <para>and then rebooting the machine, or by directly loading
+ the module with <command>kldload</command>.</para>
+ </note>
- <programlisting>device atapicam</programlisting>
+ <para>Occasionally, <errorname>Device not configured</errorname>
+ will be displayed when trying to mount a data
+ <acronym>CD</acronym>. This usually means that the
+ <acronym>CD</acronym> drive thinks that there is no disk in
+ the tray, or that the drive is not visible on the bus. It
+ can take a couple of seconds for a <acronym>CD</acronym>
+ drive to realize that a media is present, so be
+ patient.</para>
+
+ <para>Sometimes, a <acronym>SCSI</acronym>
+ <acronym>CD</acronym> drive may be missed because it did not
+ have enough time to answer the bus reset. To resolve this,
+ a custom kernel can be created which increases the default
+ <acronym>SCSI</acronym> delay. Add the following option to
+ the custom kernel configuration file and rebuild the kernel
+ using the instructions in <xref
+ linkend="kernelconfig-building"/>:</para>
- <para>You also need the following lines in your kernel
- configuration file:</para>
+ <programlisting>options SCSI_DELAY=15000</programlisting>
- <programlisting>device ata
-device scbus
-device cd
-device pass</programlisting>
+ <para>This tells the <acronym>SCSI</acronym> bus to pause 15
+ seconds during boot, to give the <acronym>CD</acronym>
+ drive every possible chance to answer the bus reset.</para>
- <para>which should already be present.</para>
+ <note>
+ <para>It is possible to burn a file directly to
+ <acronym>CD</acronym>, without creating an
+ <acronym>ISO</acronym> 9660 file system. This is known as
+ burning a raw data <acronym>CD</acronym> and some people do
+ this for backup purposes.</para>
+
+ <para>This type of disk can not be mounted as a normal data
+ <acronym>CD</acronym>. In order to retrieve the data burned
+ to such a <acronym>CD</acronym>, the data must be read from
+ the raw device node. For example, this command will extract
+ a compressed tar file located on the second
+ <acronym>CD</acronym> device into the current working
+ directory:</para>
+
+ <screen>&prompt.root; <userinput>tar xzvf /dev/<replaceable>cd1</replaceable></userinput></screen>
+
+ <para> In order to mount a data <acronym>CD</acronym>, the
+ data must be written using
+ <command>mkisofs</command>.</para>
+ </note>
+ </sect2>
- <para>Then rebuild, install your new kernel, and reboot your
- machine. During the boot process, your burner should show up,
- like so:</para>
+ <sect2 xml:id="duplicating-audiocds">
+ <title>Duplicating Audio <acronym>CD</acronym>s</title>
- <screen>acd0: CD-RW &lt;MATSHITA CD-RW/DVD-ROM UJDA740&gt; at ata1-master PIO4
-cd0 at ata1 bus 0 target 0 lun 0
-cd0: &lt;MATSHITA CDRW/DVD UJDA740 1.00&gt; Removable CD-ROM SCSI-0 device
-cd0: 16.000MB/s transfers
-cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed</screen>
+ <para>To duplicate an audio <acronym>CD</acronym>, extract the
+ audio data from the <acronym>CD</acronym> to a series of
+ files, then write these files to a blank
+ <acronym>CD</acronym>.</para>
- <para>The drive could now be accessed via the
- <filename>/dev/cd0</filename> device name, for example to
- mount a CD-ROM on <filename>/mnt</filename>, just type the
- following:</para>
+ <para><xref linkend="using-cdrecord"/> describes how to
+ duplicate and burn an audio <acronym>CD</acronym>. If the
+ &os; version is less than 10.0 and the device is
+ <acronym>ATAPI</acronym>, the <option>atapicam</option> module
+ must be first loaded using the instructions in <xref
+ linkend="atapicam"/>.</para>
- <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen>
+ <procedure xml:id="using-cdrecord">
+ <title>Duplicating an Audio <acronym>CD</acronym></title>
- <para>As <systemitem class="username">root</systemitem>, you can run the following
- command to get the SCSI address of the burner:</para>
+ <step>
+ <para>The <package>sysutils/cdrtools</package> package or
+ port installs <command>cdda2wav</command>. This command
+ can be used to extract all of the audio tracks, with each
+ track written to a separate <acronym>WAV</acronym> file in
+ the current working directory:</para>
+
+ <screen>&prompt.user; <userinput>cdda2wav -vall -B -Owav</userinput></screen>
+
+ <para>A device name does not need to be specified if there
+ is only one <acronym>CD</acronym> device on the system.
+ Refer to the <command>cdda2wav</command> manual page for
+ instructions on how to specify a device and to learn more
+ about the other options available for this command.</para>
+ </step>
- <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
-&lt;MATSHITA CDRW/DVD UJDA740 1.00&gt; at scbus1 target 0 lun 0 (pass0,cd0)</screen>
+ <step>
+ <para>Use <command>cdrecord</command> to write the
+ <filename>.wav</filename> files:</para>
- <para>So <literal>1,0,0</literal> will be the SCSI address to
- use with &man.cdrecord.1; and other SCSI application.</para>
+ <screen>&prompt.user; <userinput>cdrecord -v dev=<replaceable>2,0</replaceable> -dao -useinfo *.wav</userinput></screen>
- <para>For more information about ATAPI/CAM and SCSI system,
- refer to the &man.atapicam.4; and &man.cam.4; manual
- pages.</para>
+ <para>Make sure that <replaceable>2,0</replaceable> is set
+ appropriately, as described in <xref
+ linkend="cdrecord"/>.</para>
+ </step>
+ </procedure>
</sect2>
</sect1>
<sect1 xml:id="creating-dvds">
- <info><title>Creating and Using Optical Media (DVDs)</title>
+ <info>
+ <title>Creating and Using <acronym>DVD</acronym> Media</title>
+
<authorgroup>
- <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
</authorgroup>
<authorgroup>
- <author><personname><firstname>Andy</firstname><surname>Polyakov</surname></personname><contrib>With inputs from </contrib></author>
+ <author>
+ <personname>
+ <firstname>Andy</firstname>
+ <surname>Polyakov</surname>
+ </personname>
+ <contrib>With inputs from </contrib>
+ </author>
</authorgroup>
-
</info>
-
<indexterm>
- <primary>DVD</primary>
+ <primary><acronym>DVD</acronym></primary>
<secondary>burning</secondary>
</indexterm>
- <sect2>
- <title>Introduction</title>
-
- <para>Compared to the CD, the DVD is the next generation of
- optical media storage technology. The DVD can hold more data
- than any CD and is nowadays the standard for video
- publishing.</para>
+ <para>Compared to the <acronym>CD</acronym>, the
+ <acronym>DVD</acronym> is the next generation of optical media
+ storage technology. The <acronym>DVD</acronym> can hold more
+ data than any <acronym>CD</acronym> and is the standard for
+ video publishing.</para>
- <para>Five physical recordable formats can be defined for what
- we will call a recordable DVD:</para>
+ <para>Five physical recordable formats can be defined for a
+ recordable <acronym>DVD</acronym>:</para>
- <itemizedlist>
- <listitem>
- <para>DVD-R: This was the first DVD recordable format
- available. The DVD-R standard is defined by the <link xlink:href="http://www.dvdforum.com/forum.shtml">DVD Forum</link>.
- This format is write once.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>DVD-R: This was the first <acronym>DVD</acronym>
+ recordable format available. The DVD-R standard is defined
+ by the <link
+ xlink:href="http://www.dvdforum.com/forum.shtml"><acronym>DVD</acronym>
+ Forum</link>. This format is write once.</para>
+ </listitem>
- <listitem>
- <para>DVD-RW: This is the rewriteable version of
- the DVD-R standard. A DVD-RW can be rewritten about 1000
- times.</para>
- </listitem>
+ <listitem>
+ <para><acronym>DVD-RW</acronym>: This is the rewritable
+ version of the DVD-R standard. A
+ <acronym>DVD-RW</acronym> can be rewritten about 1000
+ times.</para>
+ </listitem>
- <listitem>
- <para>DVD-RAM: This is also a rewriteable format
- supported by the DVD Forum. A DVD-RAM can be seen as a
- removable hard drive. However, this media is not
- compatible with most DVD-ROM drives and DVD-Video players;
- only a few DVD writers support the DVD-RAM format.</para>
- </listitem>
+ <listitem>
+ <para><acronym>DVD-RAM</acronym>: This is a rewritable format
+ which can be seen as a removable hard drive. However, this
+ media is not compatible with most
+ <acronym>DVD-ROM</acronym> drives and DVD-Video players as
+ only a few <acronym>DVD</acronym> writers support the
+ <acronym>DVD-RAM</acronym> format. Refer to <xref
+ linkend="creating-dvd-ram"/> for more information on
+ <acronym>DVD-RAM</acronym> use.</para>
+ </listitem>
- <listitem>
- <para>DVD+RW: This is a rewriteable format defined by
- the <link xlink:href="http://www.dvdrw.com/">DVD+RW
- Alliance</link>. A DVD+RW can be rewritten about 1000
- times.</para>
- </listitem>
+ <listitem>
+ <para><acronym>DVD+RW</acronym>: This is a rewritable format
+ defined by the <link
+ xlink:href="http://www.dvdrw.com/"><acronym>DVD+RW</acronym>
+ Alliance</link>. A <acronym>DVD+RW</acronym> can be
+ rewritten about 1000 times.</para>
+ </listitem>
- <listitem>
- <para>DVD+R: This format is the write once variation
- of the DVD+RW format.</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>DVD+R: This format is the write once variation of the
+ <acronym>DVD+RW</acronym> format.</para>
+ </listitem>
+ </itemizedlist>
- <para>A single layer recordable DVD can hold up to
- 4,700,000,000&nbsp;bytes which is actually 4.38&nbsp;GB or
- 4485&nbsp;MB (1 kilobyte is 1024 bytes).</para>
+ <para>A single layer recordable <acronym>DVD</acronym> can hold up
+ to 4,700,000,000&nbsp;bytes which is actually 4.38&nbsp;GB or
+ 4485&nbsp;MB as 1 kilobyte is 1024 bytes.</para>
- <note>
- <para>A distinction must be made between the physical media and
- the application. For example, a DVD-Video is a specific
- file layout that can be written on any recordable DVD
- physical media: DVD-R, DVD+R, DVD-RW etc. Before choosing
- the type of media, you must be sure that both the burner and the
- DVD-Video player (a standalone player or a DVD-ROM drive on
- a computer) are compatible with the media under consideration.</para></note>
- </sect2>
+ <note>
+ <para>A distinction must be made between the physical media and
+ the application. For example, a DVD-Video is a specific file
+ layout that can be written on any recordable
+ <acronym>DVD</acronym> physical media such as DVD-R, DVD+R, or
+ <acronym>DVD-RW</acronym>. Before choosing the type of media,
+ ensure that both the burner and the DVD-Video player are
+ compatible with the media under consideration.</para>
+ </note>
<sect2>
<title>Configuration</title>
- <para>The program &man.growisofs.1; will be used to perform DVD
- recording. This command is part of the
- <application>dvd+rw-tools</application> utilities (<package>sysutils/dvd+rw-tools</package>). The
- <application>dvd+rw-tools</application> support all DVD media
- types.</para>
+ <para>To perform <acronym>DVD</acronym> recording, use
+ &man.growisofs.1;. This command is part of the
+ <package>sysutils/dvd+rw-tools</package> utilities which
+ support all <acronym>DVD</acronym> media types.</para>
- <para>These tools use the SCSI subsystem to access to the
- devices, therefore the <link linkend="atapicam">ATAPI/CAM
- support</link> must be added to your kernel. If your burner
- uses the USB interface this addition is useless, and you should
- read the <xref linkend="usb-disks"/> for more details on USB
- devices configuration.</para>
+ <para>These tools use the <acronym>SCSI</acronym> subsystem to
+ access the devices, therefore <link
+ linkend="atapicam">ATAPI/CAM support</link> must be loaded
+ or statically compiled into the kernel. This support is not
+ needed if the burner uses the <acronym>USB</acronym>
+ interface. Refer to <xref linkend="usb-disks"/> for more
+ details on <acronym>USB</acronym> device configuration.</para>
- <para>You also have to enable DMA access for ATAPI devices, this
- can be done in adding the following line to the
- <filename>/boot/loader.conf</filename> file:</para>
+ <para>DMA access must also be enabled for
+ <acronym>ATAPI</acronym> devices, by adding the following line
+ to <filename>/boot/loader.conf</filename>:</para>
<programlisting>hw.ata.atapi_dma="1"</programlisting>
- <para>Before attempting to use the
- <application>dvd+rw-tools</application> you should consult the
- <link xlink:href="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">dvd+rw-tools'
- hardware compatibility notes</link> for any information
- related to your DVD burner.</para>
+ <para>Before attempting to use
+ <application>dvd+rw-tools</application>, consult the <link
+ xlink:href="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">Hardware
+ Compatibility Notes</link>.</para>
<note>
- <para>If you want a graphical user interface, you should have
- a look to <application>K3b</application> (<package>sysutils/k3b</package>) which provides a
- user friendly interface to &man.growisofs.1; and many others
+ <para>For a graphical user interface, consider using
+ <package>sysutils/k3b</package> which provides a user
+ friendly interface to &man.growisofs.1; and many other
burning tools.</para>
</note>
</sect2>
<sect2>
- <title>Burning Data DVDs</title>
+ <title>Burning Data <acronym>DVD</acronym>s</title>
- <para>The &man.growisofs.1; command is a frontend to <link linkend="mkisofs">mkisofs</link>, it will invoke
- &man.mkisofs.8; to create the file system layout and will
- perform the write on the DVD. This means you do not need to
- create an image of the data before the burning process.</para>
+ <para>Since &man.growisofs.1; is a front-end to <link
+ linkend="mkisofs">mkisofs</link>, it will invoke
+ &man.mkisofs.8; to create the file system layout and perform
+ the write on the <acronym>DVD</acronym>. This means that an
+ image of the data does not need to be created before the
+ burning process.</para>
- <para>To burn onto a DVD+R or a DVD-R the data from the <filename>/path/to/data</filename> directory, use the
- following command:</para>
+ <para>To burn to a DVD+R or a DVD-R the data in
+ <filename>/path/to/data</filename>, use the following
+ command:</para>
- <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z /dev/cd0 -J -R /path/to/data</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>
- <para>The options <option>-J -R</option> are passed to
- &man.mkisofs.8; for the file system creation (in this case: an
- ISO 9660 file system with Joliet and Rock Ridge extensions),
- consult the &man.mkisofs.8; manual page for more
+ <para>In this example, <option>-J -R</option> is passed to
+ &man.mkisofs.8; to create an ISO 9660 file system with Joliet
+ and Rock Ridge extensions. Refer to &man.mkisofs.8; for more
details.</para>
- <para>The option <option>-Z</option> is used for the initial
- session recording in any case: multiple sessions or not. The
- DVD device, <replaceable>/dev/cd0</replaceable>, must be
- changed according to your configuration. The
- <option>-dvd-compat</option> parameter will close the disk,
- the recording will be unappendable. In return this should provide better
- media compatibility with DVD-ROM drives.</para>
+ <para>For the initial session recording, <option>-Z</option> is
+ used for both single and multiple sessions. Replace
+ <replaceable>/dev/cd0</replaceable>, with the name of the
+ <acronym>DVD</acronym> device. Using
+ <option>-dvd-compat</option> indicates that the disk will be
+ closed and that the recording will be unappendable. This
+ should also provide better media compatibility with
+ <acronym>DVD-ROM</acronym> drives.</para>
- <para>It is also possible to burn a pre-mastered image, for
- example to burn the image
- <replaceable>imagefile.iso</replaceable>, we will run:</para>
+ <para>To burn a pre-mastered image, such as
+ <replaceable>imagefile.iso</replaceable>, use:</para>
- <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z /dev/cd0=imagefile.iso</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen>
<para>The write speed should be detected and automatically set
- according to the media and the drive being used. If you want
- to force the write speed, use the <option>-speed=</option>
- parameter. For more information, read the &man.growisofs.1;
- manual page.</para>
+ according to the media and the drive being used. To force the
+ write speed, use <option>-speed=</option>. Refer to
+ &man.growisofs.1; for example usage.</para>
+
+ <note>
+ <para>In order to support working files larger than 4.38GB, an
+ UDF/ISO-9660 hybrid file system must be created by passing
+ <option>-udf -iso-level 3</option> to &man.mkisofs.8; and
+ all related programs, such as &man.growisofs.1;. This is
+ required only when creating an ISO image file or when
+ writing files directly to a disk. Since a disk created this
+ way must be mounted as an UDF file system with
+ &man.mount.udf.8;, it will be usable only on an UDF aware
+ operating system. Otherwise it will look as if it contains
+ corrupted files.</para>
+
+ <para>To create this type of ISO file:</para>
+
+ <screen>&prompt.user; <userinput>mkisofs -R -J -udf -iso-level 3 -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/data</replaceable></userinput></screen>
+
+ <para>To burn files directly to a disk:</para>
+
+ <screen>&prompt.root; <userinput>growisofs -dvd-compat -udf -iso-level 3 -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>
+
+ <para>When an ISO image already contains large files, no
+ additional options are required for &man.growisofs.1; to
+ burn that image on a disk.</para>
+
+ <para>Be sure to use an up-to-date version of
+ <package>sysutils/cdrtools</package>, which contains
+ &man.mkisofs.8;, as an older version may not contain large
+ files support. If the latest version does not work, install
+ <package>sysutils/cdrtools-devel</package> and read its
+ &man.mkisofs.8;.</para>
+ </note>
</sect2>
<sect2>
- <title>Burning a DVD-Video</title>
+ <title>Burning a <acronym>DVD</acronym>-Video</title>
<indexterm>
- <primary>DVD</primary>
- <secondary>DVD-Video</secondary>
+ <primary><acronym>DVD</acronym></primary>
+ <secondary>DVD-Video</secondary>
</indexterm>
- <para>A DVD-Video is a specific file layout based on ISO 9660
- and the micro-UDF (M-UDF) specifications. The DVD-Video also
- presents a specific data structure hierarchy, it is the reason
- why you need a particular program such as <package>multimedia/dvdauthor</package> to author the
- DVD.</para>
-
- <para>If you already have an image of the DVD-Video file system,
- just burn it in the same way as for any image, see the
- previous section for an example. If you have made the DVD
- authoring and the result is in, for example, the directory
- <filename>/path/to/video</filename>, the
- following command should be used to burn the DVD-Video:</para>
-
- <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -dvd-video /path/to/video</userinput></screen>
-
- <para>The <option>-dvd-video</option> option will be passed down to
- &man.mkisofs.8; and will instruct it to create a DVD-Video file system
- layout. Beside this, the <option>-dvd-video</option> option
- implies <option>-dvd-compat</option> &man.growisofs.1;
- option.</para>
+ <para>A DVD-Video is a specific file layout based on the ISO
+ 9660 and micro-UDF (M-UDF) specifications. Since DVD-Video
+ presents a specific data structure hierarchy, a particular
+ program such as <package>multimedia/dvdauthor</package> is
+ needed to author the <acronym>DVD</acronym>.</para>
+
+ <para>If an image of the DVD-Video file system already exists,
+ it can be burned in the same way as any other image. If
+ <command>dvdauthor</command> was used to make the
+ <acronym>DVD</acronym> and the result is in
+ <filename>/path/to/video</filename>, the following command
+ should be used to burn the DVD-Video:</para>
+
+ <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -dvd-video <replaceable>/path/to/video</replaceable></userinput></screen>
+
+ <para><option>-dvd-video</option> is passed to &man.mkisofs.8;
+ to instruct it to create a DVD-Video file system layout.
+ This option implies the <option>-dvd-compat</option>
+ &man.growisofs.1; option.</para>
</sect2>
<sect2>
- <title>Using a DVD+RW</title>
+ <title>Using a <acronym>DVD+RW</acronym></title>
<indexterm>
- <primary>DVD</primary>
- <secondary>DVD+RW</secondary>
+ <primary><acronym>DVD</acronym></primary>
+ <secondary><acronym>DVD+RW</acronym></secondary>
</indexterm>
- <para>Unlike CD-RW, a virgin DVD+RW needs to be formatted before
- first use. The &man.growisofs.1; program will take care of it
- automatically whenever appropriate, which is the
- <emphasis>recommended</emphasis> way. However you can use the
- <command>dvd+rw-format</command> command to format the
- DVD+RW:</para>
+ <para>Unlike CD-RW, a virgin <acronym>DVD+RW</acronym> needs to
+ be formatted before first use. It is
+ <emphasis>recommended</emphasis> to let &man.growisofs.1; take
+ care of this automatically whenever appropriate. However, it
+ is possible to use <command>dvd+rw-format</command> to format
+ the <acronym>DVD+RW</acronym>:</para>
- <screen>&prompt.root; <userinput>dvd+rw-format /dev/cd0</userinput></screen>
+ <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen>
- <para>You need to perform this operation just once, keep in mind
- that only virgin DVD+RW medias need to be formatted. Then you
- can burn the DVD+RW in the way seen in previous
- sections.</para>
+ <para>Only perform this operation once and keep in mind that
+ only virgin <acronym>DVD+RW</acronym> medias need to be
+ formatted. Once formatted, the <acronym>DVD+RW</acronym> can
+ be burned as usual.</para>
- <para>If you want to burn new data (burn a totally new file
- system not append some data) onto a DVD+RW, you do not need to
- blank it, you just have to write over the previous recording
- (in performing a new initial session), like this:</para>
+ <para>To burn a totally new file system and not just append some
+ data onto a <acronym>DVD+RW</acronym>, the media does not need
+ to be blanked first. Instead, write over the previous
+ recording like this:</para>
- <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -J -R /path/to/newdata</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/newdata</replaceable></userinput></screen>
- <para>DVD+RW format offers the possibility to easily append data
- to a previous recording. The operation consists in merging a
- new session to the existing one, it is not multisession
- writing, &man.growisofs.1; will <emphasis>grow</emphasis> the
- ISO 9660 file system present on the media.</para>
+ <para>The <acronym>DVD+RW</acronym> format supports appending
+ data to a previous recording. This operation consists of
+ merging a new session to the existing one as it is not
+ considered to be multi-session writing. &man.growisofs.1;
+ will <emphasis>grow</emphasis> the ISO 9660 file system
+ present on the media.</para>
- <para>For example, if we want to append data to our previous
- DVD+RW, we have to use the following:</para>
+ <para>For example, to append data to a
+ <acronym>DVD+RW</acronym>, use the following:</para>
- <screen>&prompt.root; <userinput>growisofs -M /dev/cd0 -J -R /path/to/nextdata</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen>
- <para>The same &man.mkisofs.8; options we used to burn the
+ <para>The same &man.mkisofs.8; options used to burn the
initial session should be used during next writes.</para>
<note>
- <para>You may want to use the <option>-dvd-compat</option>
- option if you want better media compatibility with DVD-ROM
- drives. In the DVD+RW case, this will not prevent you from
- adding data.</para>
+ <para>Use <option>-dvd-compat</option> for better media
+ compatibility with <acronym>DVD-ROM</acronym> drives. When
+ using <acronym>DVD+RW</acronym>, this option will not
+ prevent the addition of data.</para>
</note>
- <para>If for any reason you really want to blank the media, do
- the following:</para>
+ <para>To blank the media, use:</para>
- <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0=/dev/zero</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable>=<replaceable>/dev/zero</replaceable></userinput></screen>
</sect2>
<sect2>
- <title>Using a DVD-RW</title>
+ <title>Using a <acronym>DVD-RW</acronym></title>
<indexterm>
- <primary>DVD</primary>
- <secondary>DVD-RW</secondary>
+ <primary><acronym>DVD</acronym></primary>
+ <secondary><acronym>DVD-RW</acronym></secondary>
</indexterm>
- <para>A DVD-RW accepts two disc formats: the incremental
- sequential one and the restricted overwrite. By default
- DVD-RW discs are in sequential format.</para>
+ <para>A <acronym>DVD-RW</acronym> accepts two disc formats:
+ incremental sequential and restricted overwrite. By default,
+ <acronym>DVD-RW</acronym> discs are in sequential
+ format.</para>
- <para>A virgin DVD-RW can be directly written without the need
- of a formatting operation, however a non-virgin DVD-RW in
- sequential format needs to be blanked before to be able to
- write a new initial session.</para>
+ <para>A virgin <acronym>DVD-RW</acronym> can be directly written
+ without being formatted. However, a non-virgin
+ <acronym>DVD-RW</acronym> in sequential format needs to be
+ blanked before writing a new initial session.</para>
- <para>To blank a DVD-RW in sequential mode, run:</para>
+ <para>To blank a <acronym>DVD-RW</acronym> in sequential
+ mode:</para>
- <screen>&prompt.root; <userinput>dvd+rw-format -blank=full /dev/cd0</userinput></screen>
+ <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen>
<note>
- <para>A full blanking (<option>-blank=full</option>) will take
- about one hour on a 1x media. A fast blanking can be
- performed using the <option>-blank</option> option if the
- DVD-RW will be recorded in Disk-At-Once (DAO) mode. To burn
- the DVD-RW in DAO mode, use the command:</para>
-
- <screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z /dev/cd0=imagefile.iso</userinput></screen>
-
- <para>The <option>-use-the-force-luke=dao</option> option
- should not be required since &man.growisofs.1; attempts to
- detect minimally (fast blanked) media and engage DAO
- write.</para>
-
- <para>In fact one should use restricted overwrite mode with
- any DVD-RW, this format is more flexible than the default
- incremental sequential one.</para>
+ <para>A full blanking using <option>-blank=full</option> will
+ take about one hour on a 1x media. A fast blanking can be
+ performed using <option>-blank</option>, if the
+ <acronym>DVD-RW</acronym> will be recorded in Disk-At-Once
+ (DAO) mode. To burn the <acronym>DVD-RW</acronym> in DAO
+ mode, use the command:</para>
+
+ <screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen>
+
+ <para>Since &man.growisofs.1; automatically attempts to detect
+ fast blanked media and engage DAO write,
+ <option>-use-the-force-luke=dao</option> should not be
+ required.</para>
+
+ <para>One should instead use restricted overwrite mode with
+ any <acronym>DVD-RW</acronym> as this format is more
+ flexible than the default of incremental sequential.</para>
</note>
- <para>To write data on a sequential DVD-RW, use the same
- instructions as for the other DVD formats:</para>
+ <para>To write data on a sequential <acronym>DVD-RW</acronym>,
+ use the same instructions as for the other
+ <acronym>DVD</acronym> formats:</para>
- <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -J -R /path/to/data</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>
- <para>If you want to append some data to your previous
- recording, you will have to use the &man.growisofs.1;
- <option>-M</option> option. However, if you perform data
- addition on a DVD-RW in incremental sequential mode, a new
- session will be created on the disc and the result will be a
- multi-session disc.</para>
+ <para>To append some data to a previous recording, use
+ <option>-M</option> with &man.growisofs.1;. However, if data
+ is appended on a <acronym>DVD-RW</acronym> in incremental
+ sequential mode, a new session will be created on the disc and
+ the result will be a multi-session disc.</para>
- <para>A DVD-RW in restricted overwrite format does not need to
- be blanked before a new initial session, you just have to
- overwrite the disc with the <option>-Z</option> option, this
- is similar to the DVD+RW case. It is also possible to grow an
- existing ISO 9660 file system written on the disc in a same
- way as for a DVD+RW with the <option>-M</option> option. The
- result will be a one-session DVD.</para>
+ <para>A <acronym>DVD-RW</acronym> in restricted overwrite format
+ does not need to be blanked before a new initial session.
+ Instead, overwrite the disc with <option>-Z</option>. It is
+ also possible to grow an existing ISO 9660 file system written
+ on the disc with <option>-M</option>. The result will be a
+ one-session <acronym>DVD</acronym>.</para>
- <para>To put a DVD-RW in the restricted overwrite format, the
- following command must be used:</para>
+ <para>To put a <acronym>DVD-RW</acronym> in restricted overwrite
+ format, the following command must be used:</para>
- <screen>&prompt.root; <userinput>dvd+rw-format /dev/cd0</userinput></screen>
+ <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen>
- <para>To change back to the sequential format use:</para>
+ <para>To change back to sequential format, use:</para>
- <screen>&prompt.root; <userinput>dvd+rw-format -blank=full /dev/cd0</userinput></screen>
+ <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen>
</sect2>
<sect2>
- <title>Multisession</title>
-
- <para>Very few DVD-ROM drives support
- multisession DVDs, they will most of time, hopefully, only read
- the first session. DVD+R, DVD-R and DVD-RW in sequential
- format can accept multiple sessions, the notion of multiple
- sessions does not exist for the DVD+RW and the DVD-RW
+ <title>Multi-Session</title>
+
+ <para>Few <acronym>DVD-ROM</acronym> drives support
+ multi-session DVDs and most of the time only read the first
+ session. DVD+R, DVD-R and <acronym>DVD-RW</acronym> in
+ sequential format can accept multiple sessions. The notion
+ of multiple sessions does not exist for the
+ <acronym>DVD+RW</acronym> and the <acronym>DVD-RW</acronym>
restricted overwrite formats.</para>
- <para>Using the following command after an initial (non-closed)
- session on a DVD+R, DVD-R, or DVD-RW in sequential format,
- will add a new session to the disc:</para>
+ <para>Using the following command after an initial non-closed
+ session on a DVD+R, DVD-R, or <acronym>DVD-RW</acronym> in
+ sequential format, will add a new session to the disc:</para>
- <screen>&prompt.root; <userinput>growisofs -M /dev/cd0 -J -R /path/to/nextdata</userinput></screen>
+ <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen>
- <para>Using this command line with a DVD+RW or a DVD-RW in restricted
- overwrite mode, will append data in merging the new session to
- the existing one. The result will be a single-session disc.
- This is the way used to add data after an initial write on these
- medias.</para>
+ <para>Using this command with a <acronym>DVD+RW</acronym> or a
+ <acronym>DVD-RW</acronym> in restricted overwrite mode will
+ append data while merging the new session to the existing one.
+ The result will be a single-session disc. Use this method to
+ add data after an initial write on these types of
+ media.</para>
<note>
- <para>Some space on the media is used between each session for
- end and start of sessions. Therefore, one should add
- sessions with large amount of data to optimize media space.
- The number of sessions is limited to 154 for a DVD+R,
- about 2000 for a DVD-R, and 127 for a DVD+R Double
+ <para>Since some space on the media is used between each
+ session to mark the end and start of sessions, one should
+ add sessions with a large amount of data to optimize media
+ space. The number of sessions is limited to 154 for a
+ DVD+R, about 2000 for a DVD-R, and 127 for a DVD+R Double
Layer.</para>
</note>
</sect2>
@@ -1604,1378 +1443,798 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c
<sect2>
<title>For More Information</title>
- <para>To obtain more information about a DVD, the
- <command>dvd+rw-mediainfo
- /dev/cd0</command> command can be
- ran with the disc in the drive.</para>
+ <para>To obtain more information about a <acronym>DVD</acronym>,
+ use <command>dvd+rw-mediainfo
+ <replaceable>/dev/cd0</replaceable></command> while the
+ disc in the specified drive.</para>
- <para>More information about the
+ <para>More information about
<application>dvd+rw-tools</application> can be found in
- the &man.growisofs.1; manual page, on the <link xlink:href="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools
- web site</link> and in the <link xlink:href="http://lists.debian.org/cdwrite/">cdwrite mailing
- list</link> archives.</para>
+ &man.growisofs.1;, on the <link
+ xlink:href="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools
+ web site</link>, and in the <link
+ xlink:href="http://lists.debian.org/cdwrite/">cdwrite
+ mailing list</link> archives.</para>
<note>
- <para>The <command>dvd+rw-mediainfo</command> output of the
- resulting recording or the media with issues is mandatory
- for any problem report. Without this output, it will be
- quite impossible to help you.</para>
+ <para>When creating a problem report related to the use of
+ <application>dvd+rw-tools</application>, always include the
+ output of <command>dvd+rw-mediainfo</command>.</para>
</note>
</sect2>
- </sect1>
-
- <sect1 xml:id="floppies">
- <info><title>Creating and Using Floppy Disks</title>
- <authorgroup>
- <author><personname><firstname>Julio</firstname><surname>Merino</surname></personname><contrib>Original work by </contrib></author>
- </authorgroup>
-
- <authorgroup>
- <author><personname><firstname>Martin</firstname><surname>Karlsson</surname></personname><contrib>Rewritten by </contrib></author>
- </authorgroup>
-
- </info>
-
-
-
- <para>Storing data on floppy disks is sometimes useful, for
- example when one does not have any other removable storage media
- or when one needs to transfer small amounts of data to another
- computer.</para>
-
- <para>This section will explain how to use floppy disks in
- FreeBSD. It will primarily cover formatting and usage of
- 3.5inch DOS floppies, but the concepts are similar for other
- floppy disk formats.</para>
-
- <sect2>
- <title>Formatting Floppies</title>
-
- <sect3>
- <title>The Device</title>
-
- <para>Floppy disks are accessed through entries in
- <filename>/dev</filename>, just like other devices. To
- access the raw floppy disk, simply use
- <filename>/dev/fdN</filename>.</para>
-
- </sect3>
-
- <sect3>
- <title>Formatting</title>
-
- <para>A floppy disk needs to be low-level formated before it
- can be used. This is usually done by the vendor, but
- formatting is a good way to check media integrity. Although
- it is possible to force larger (or smaller) disk sizes,
- 1440kB is what most floppy disks are designed for.</para>
-
- <para>To low-level format the floppy disk you need to use
- &man.fdformat.1;. This utility expects the device name as an
- argument.</para>
-
- <para>Make note of any error messages, as these can help
- determine if the disk is good or bad.</para>
-
- <sect4>
- <title>Formatting Floppy Disks</title>
-
- <para>Use the
- <filename>/dev/fdN</filename>
- devices to format the floppy. Insert a new 3.5inch floppy
- disk in your drive and issue:</para>
-
- <screen>&prompt.root; <userinput>/usr/sbin/fdformat -f 1440 /dev/fd0</userinput></screen>
-
- </sect4>
- </sect3>
- </sect2>
-
- <sect2>
- <title>The Disk Label</title>
-
- <para>After low-level formatting the disk, you will need to
- place a disk label on it. This disk label will be destroyed
- later, but it is needed by the system to determine the size of
- the disk and its geometry later.</para>
-
- <para>The new disk label will take over the whole disk, and will
- contain all the proper information about the geometry of the
- floppy. The geometry values for the disk label are listed in
- <filename>/etc/disktab</filename>.</para>
-
- <para>You can run now &man.bsdlabel.8; like so:</para>
-
- <screen>&prompt.root; <userinput>/sbin/bsdlabel -B -r -w /dev/fd0 fd1440</userinput></screen>
-
- <note><para>Since &os;&nbsp;5.1-RELEASE, the &man.bsdlabel.8;
- utility replaces the old &man.bsdlabel.8; program. With
- &man.bsdlabel.8; a number of obsolete options and parameters
- have been retired; in the example above the option
- <option>-r</option> should be removed. For more
- information, please refer to the &man.bsdlabel.8;
- manual page.</para></note>
-
- </sect2>
-
- <sect2>
- <title>The File System</title>
-
- <para>Now the floppy is ready to be high-level formated. This
- will place a new file system on it, which will let FreeBSD read
- and write to the disk. After creating the new file system, the
- disk label is destroyed, so if you want to reformat the disk, you
- will have to recreate the disk label.</para>
-
- <para>The floppy's file system can be either UFS or FAT.
- FAT is generally a better choice for floppies.</para>
-
- <para>To put a new file system on the floppy, issue:</para>
-
- <screen>&prompt.root; <userinput>/sbin/newfs_msdos /dev/fd0</userinput></screen>
-
- <para>The disk is now ready for use.</para>
- </sect2>
-
-
- <sect2>
- <title>Using the Floppy</title>
-
- <para>To use the floppy, mount it with &man.mount.msdos.8;. One can also use
- <package>emulators/mtools</package> from the ports
- collection.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="backups-tapebackups">
- <title>Creating and Using Data Tapes</title>
-
- <indexterm><primary>tape media</primary></indexterm>
- <para>The major tape media are the 4mm, 8mm, QIC, mini-cartridge and
- DLT.</para>
- <sect2 xml:id="backups-tapebackups-4mm">
- <title>4mm (DDS: Digital Data Storage)</title>
+ <sect2 xml:id="creating-dvd-ram">
+ <title>Using a <acronym>DVD-RAM</acronym></title>
<indexterm>
- <primary>tape media</primary>
- <secondary>DDS (4mm) tapes</secondary>
+ <primary><acronym>DVD</acronym></primary>
+ <secondary><acronym>DVD-RAM</acronym></secondary>
</indexterm>
- <indexterm>
- <primary>tape media</primary>
- <secondary>QIC tapes</secondary>
- </indexterm>
- <para>4mm tapes are replacing QIC as the workstation backup media of
- choice. This trend accelerated greatly when Conner purchased Archive,
- a leading manufacturer of QIC drives, and then stopped production of
- QIC drives. 4mm drives are small and quiet but do not have the
- reputation for reliability that is enjoyed by 8mm drives. The
- cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51
- x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short
- head life for the same reason, both use helical scan.</para>
-
- <para>Data throughput on these drives starts ~150&nbsp;kB/s, peaking at ~500&nbsp;kB/s.
- Data capacity starts at 1.3&nbsp;GB and ends at 2.0&nbsp;GB. Hardware
- compression, available with most of these drives, approximately
- doubles the capacity. Multi-drive tape library units can have 6
- drives in a single cabinet with automatic tape changing. Library
- capacities reach 240&nbsp;GB.</para>
-
- <para>The DDS-3 standard now supports tape capacities up to 12&nbsp;GB (or
- 24&nbsp;GB compressed).</para>
-
- <para>4mm drives, like 8mm drives, use helical-scan. All the benefits
- and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para>
-
- <para>Tapes should be retired from use after 2,000 passes or 100 full
- backups.</para>
- </sect2>
- <sect2 xml:id="backups-tapebackups-8mm">
- <title>8mm (Exabyte)</title>
- <indexterm>
- <primary>tape media</primary>
- <secondary>Exabyte (8mm) tapes</secondary>
- </indexterm>
+ <para><acronym>DVD-RAM</acronym> writers can use either a
+ <acronym>SCSI</acronym> or <acronym>ATAPI</acronym> interface.
+ For <acronym>ATAPI</acronym> devices, DMA access has to be
+ enabled by adding the following line to
+ <filename>/boot/loader.conf</filename>:</para>
- <para>8mm tapes are the most common SCSI tape drives; they are the best
- choice of exchanging tapes. Nearly every site has an Exabyte 2&nbsp;GB 8mm
- tape drive. 8mm drives are reliable, convenient and quiet. Cartridges
- are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm).
- One downside of 8mm tape is relatively short head and tape life due to
- the high rate of relative motion of the tape across the heads.</para>
-
- <para>Data throughput ranges from ~250&nbsp;kB/s to ~500&nbsp;kB/s. Data sizes start
- at 300&nbsp;MB and go up to 7&nbsp;GB. Hardware compression, available with
- most of these drives, approximately doubles the capacity. These
- drives are available as single units or multi-drive tape libraries
- with 6 drives and 120 tapes in a single cabinet. Tapes are changed
- automatically by the unit. Library capacities reach 840+&nbsp;GB.</para>
-
- <para>The Exabyte <quote>Mammoth</quote> model supports 12&nbsp;GB on one tape
- (24&nbsp;GB with compression) and costs approximately twice as much as
- conventional tape drives.</para>
-
- <para>Data is recorded onto the tape using helical-scan, the heads are
- positioned at an angle to the media (approximately 6 degrees). The
- tape wraps around 270 degrees of the spool that holds the heads. The
- spool spins while the tape slides over the spool. The result is a
- high density of data and closely packed tracks that angle across the
- tape from one edge to the other.</para>
- </sect2>
+ <programlisting>hw.ata.atapi_dma="1"</programlisting>
- <sect2 xml:id="backups-tapebackups-qic">
- <title>QIC</title>
- <indexterm>
- <primary>tape media</primary>
- <secondary>QIC-150</secondary>
- </indexterm>
+ <para>A <acronym>DVD-RAM</acronym> can be seen as a removable
+ hard drive. Like any other hard drive, the
+ <acronym>DVD-RAM</acronym> must be formatted before it can be
+ used. In this example, the whole disk space will be formatted
+ with a standard UFS2 file system:</para>
- <para>QIC-150 tapes and drives are, perhaps, the most common tape drive
- and media around. QIC tape drives are the least expensive <quote>serious</quote>
- backup drives. The downside is the cost of media. QIC tapes are
- expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB
- data storage. But, if your needs can be satisfied with a half-dozen
- tapes, QIC may be the correct choice. QIC is the
- <emphasis>most</emphasis> common tape drive. Every site has a QIC
- drive of some density or another. Therein lies the rub, QIC has a
- large number of densities on physically similar (sometimes identical)
- tapes. QIC drives are not quiet. These drives audibly seek before
- they begin to record data and are clearly audible whenever reading,
- writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 152 x
- 102 x 17 mm).</para>
-
- <para>Data throughput ranges from ~150&nbsp;kB/s to ~500&nbsp;kB/s. Data capacity
- ranges from 40&nbsp;MB to 15&nbsp;GB. Hardware compression is available on many
- of the newer QIC drives. QIC drives are less frequently installed;
- they are being supplanted by DAT drives.</para>
-
- <para>Data is recorded onto the tape in tracks. The tracks run along
- the long axis of the tape media from one end to the other. The number
- of tracks, and therefore the width of a track, varies with the tape's
- capacity. Most if not all newer drives provide backward-compatibility
- at least for reading (but often also for writing). QIC has a good
- reputation regarding the safety of the data (the mechanics are simpler
- and more robust than for helical scan drives).</para>
-
- <para>Tapes should be retired from use after 5,000 backups.</para>
- </sect2>
+ <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/dev/acd0</replaceable> bs=2k count=1</userinput>
+&prompt.root; <userinput>bsdlabel -Bw <replaceable>acd0</replaceable></userinput>
+&prompt.root; <userinput>newfs <replaceable>/dev/acd0</replaceable></userinput></screen>
- <sect2 xml:id="backups-tapebackups-dlt">
- <title>DLT</title>
- <indexterm>
- <primary>tape media</primary>
- <secondary>DLT</secondary>
- </indexterm>
+ <para>The <acronym>DVD</acronym> device,
+ <filename>acd0</filename>, must be changed according to the
+ configuration.</para>
- <para>DLT has the fastest data transfer rate of all the drive types
- listed here. The 1/2" (12.5mm) tape is contained in a single spool
- cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a
- swinging gate along one entire side of the cartridge. The drive
- mechanism opens this gate to extract the tape leader. The tape leader
- has an oval hole in it which the drive uses to <quote>hook</quote> the tape. The
- take-up spool is located inside the tape drive. All the other tape
- cartridges listed here (9 track tapes are the only exception) have
- both the supply and take-up spools located inside the tape cartridge
- itself.</para>
-
- <para>Data throughput is approximately 1.5&nbsp;MB/s, three times the throughput of
- 4mm, 8mm, or QIC tape drives. Data capacities range from 10&nbsp;GB to 20&nbsp;GB
- for a single drive. Drives are available in both multi-tape changers
- and multi-tape, multi-drive tape libraries containing from 5 to 900
- tapes over 1 to 20 drives, providing from 50&nbsp;GB to 9&nbsp;TB of
- storage.</para>
-
- <para>With compression, DLT Type IV format supports up to 70&nbsp;GB
- capacity.</para>
-
- <para>Data is recorded onto the tape in tracks parallel to the direction
- of travel (just like QIC tapes). Two tracks are written at once.
- Read/write head lifetimes are relatively long; once the tape stops
- moving, there is no relative motion between the heads and the
- tape.</para>
- </sect2>
+ <para>Once the <acronym>DVD-RAM</acronym> has been formatted, it
+ can be mounted as a normal hard drive:</para>
- <sect2>
- <title xml:id="backups-tapebackups-ait">AIT</title>
- <indexterm>
- <primary>tape media</primary>
- <secondary>AIT</secondary>
- </indexterm>
-
- <para>AIT is a new format from Sony, and can hold up to 50&nbsp;GB (with
- compression) per tape. The tapes contain memory chips which retain an
- index of the tape's contents. This index can be rapidly read by the
- tape drive to determine the position of files on the tape, instead of
- the several minutes that would be required for other tapes. Software
- such as <application>SAMS:Alexandria</application> can operate forty or more AIT tape libraries,
- communicating directly with the tape's memory chip to display the
- contents on screen, determine what files were backed up to which
- tape, locate the correct tape, load it, and restore the data from the
- tape.</para>
-
- <para>Libraries like this cost in the region of $20,000, pricing them a
- little out of the hobbyist market.</para>
- </sect2>
-
- <sect2>
- <title>Using a New Tape for the First Time</title>
-
- <para>The first time that you try to read or write a new, completely
- blank tape, the operation will fail. The console messages should be
- similar to:</para>
-
- <screen>sa0(ncr1:4:0): NOT READY asc:4,1
-sa0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
-
- <para>The tape does not contain an Identifier Block (block number 0).
- All QIC tape drives since the adoption of QIC-525 standard write an
- Identifier Block to the tape. There are two solutions:</para>
-
- <itemizedlist>
- <listitem>
- <para><command>mt fsf 1</command> causes the tape drive to write an
- Identifier Block to the tape.</para>
- </listitem>
-
- <listitem>
- <para>Use the front panel button to eject the tape.</para>
-
- <para>Re-insert the tape and <command>dump</command> data to
- the tape.</para>
-
- <para><command>dump</command> will report <errorname>DUMP: End of tape
- detected</errorname> and the console will show: <errorname>HARDWARE
- FAILURE info:280 asc:80,96</errorname>.</para>
-
- <para>rewind the tape using: <command>mt rewind</command>.</para>
-
- <para>Subsequent tape operations are successful.</para>
- </listitem>
- </itemizedlist>
+ <screen>&prompt.root; <userinput>mount <replaceable>/dev/acd0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+ <para>Once mounted, the <acronym>DVD-RAM</acronym> will be both
+ readable and writeable.</para>
</sect2>
</sect1>
- <sect1 xml:id="backups-floppybackups">
- <title>Backups to Floppies</title>
-
- <sect2 xml:id="floppies-using">
- <title>Can I Use Floppies for Backing Up My Data?</title>
- <indexterm><primary>backup floppies</primary></indexterm>
- <indexterm><primary>floppy disks</primary></indexterm>
-
- <para>Floppy disks are not really a suitable media for
- making backups as:</para>
-
- <itemizedlist>
- <listitem>
- <para>The media is unreliable, especially over long periods of
- time.</para>
- </listitem>
-
- <listitem>
- <para>Backing up and restoring is very slow.</para>
- </listitem>
-
- <listitem>
- <para>They have a very limited capacity (the days of backing up
- an entire hard disk onto a dozen or so floppies has long since
- passed).</para>
- </listitem>
- </itemizedlist>
-
- <para>However, if you have no other method of backing up your data then
- floppy disks are better than no backup at all.</para>
-
- <para>If you do have to use floppy disks then ensure that you use good
- quality ones. Floppies that have been lying around the office for a
- couple of years are a bad choice. Ideally use new ones from a
- reputable manufacturer.</para>
- </sect2>
-
- <sect2 xml:id="floppies-creating">
- <title>So How Do I Backup My Data to Floppies?</title>
-
- <para>The best way to backup to floppy disk is to use
- &man.tar.1; with the <option>-M</option> (multi
- volume) option, which allows backups to span multiple
- floppies.</para>
+ <sect1 xml:id="floppies">
+ <title>Creating and Using Floppy Disks</title>
- <para>To backup all the files in the current directory and sub-directory
- use this (as <systemitem class="username">root</systemitem>):</para>
+<!--
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Julio</firstname>
+ <surname>Merino</surname>
+ </personname>
+ <contrib>Original work by </contrib>
+ </author>
+ </authorgroup>
- <screen>&prompt.root; <userinput>tar Mcvf /dev/fd0 *</userinput></screen>
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Martin</firstname>
+ <surname>Karlsson</surname>
+ </personname>
+ <contrib>Rewritten by </contrib>
+ </author>
+ </authorgroup>
+ -->
- <para>When the first floppy is full &man.tar.1; will prompt you to
- insert the next volume (because &man.tar.1; is media independent it
- refers to volumes; in this context it means floppy disk).</para>
+ <para>This section explains how to format a 3.5 inch floppy disk
+ in &os;.</para>
- <screen>Prepare volume #2 for /dev/fd0 and hit return:</screen>
+ <procedure>
+ <title>Steps to Format a Floppy</title>
- <para>This is repeated (with the volume number incrementing) until all
- the specified files have been archived.</para>
- </sect2>
+ <para>A floppy disk needs to be low-level formatted before it
+ can be used. This is usually done by the vendor, but
+ formatting is a good way to check media integrity. To
+ low-level format the floppy disk on &os;, use
+ &man.fdformat.1;. When using this utility, make note of any
+ error messages, as these can help determine if the disk is
+ good or bad.</para>
- <sect2 xml:id="floppies-compress">
- <title>Can I Compress My Backups?</title>
- <indexterm>
- <primary><command>tar</command></primary>
- </indexterm>
- <indexterm>
- <primary><command>gzip</command></primary>
- </indexterm>
- <indexterm><primary>compression</primary></indexterm>
+ <step>
+ <para>To format the floppy, insert a new 3.5 inch floppy disk
+ into the first floppy drive and issue:</para>
- <para>Unfortunately, &man.tar.1; will not allow the
- <option>-z</option> option to be used for multi-volume archives.
- You could, of course, &man.gzip.1; all the files,
- &man.tar.1; them to the floppies, then
- &man.gunzip.1; the files again!</para>
- </sect2>
+ <screen>&prompt.root; <userinput>/usr/sbin/fdformat -f 1440 /dev/fd0</userinput></screen>
+ </step>
- <sect2 xml:id="floppies-restoring">
- <title>How Do I Restore My Backups?</title>
+ <step>
+ <para>After low-level formatting the disk, create a disk label
+ as it is needed by the system to determine the size of the
+ disk and its geometry. The supported geometry values are
+ listed in <filename>/etc/disktab</filename>.</para>
- <para>To restore the entire archive use:</para>
+ <para>To write the disk label, use &man.bsdlabel.8;:</para>
- <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0</userinput></screen>
+ <screen>&prompt.root; <userinput>/sbin/bsdlabel -B -w /dev/fd0 fd1440</userinput></screen>
+ </step>
- <para>There are two ways that you can use to restore only
- specific files. First, you can start with the first floppy
- and use:</para>
+ <step>
+ <para>The floppy is now ready to be high-level formatted with
+ a file system. The floppy's file system can be either UFS
+ or FAT, where FAT is generally a better choice for
+ floppies.</para>
- <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0 filename</userinput></screen>
+ <para>To format the floppy with FAT, issue:</para>
- <para>The utility &man.tar.1; will prompt you to insert subsequent floppies until it
- finds the required file.</para>
+ <screen>&prompt.root; <userinput>/sbin/newfs_msdos /dev/fd0</userinput></screen>
+ </step>
+ </procedure>
- <para>Alternatively, if you know which floppy the file is on then you
- can simply insert that floppy and use the same command as above. Note
- that if the first file on the floppy is a continuation from the
- previous one then &man.tar.1; will warn you that it cannot
- restore it, even if you have not asked it to!</para>
- </sect2>
+ <para>The disk is now ready for use. To use the floppy, mount it
+ with &man.mount.msdosfs.8;. One can also install and use
+ <package>emulators/mtools</package> from the Ports
+ Collection.</para>
</sect1>
- <sect1 xml:id="backup-strategies">
- <info><title>Backup Strategies</title>
- <authorgroup>
- <author><personname><firstname>Lowell</firstname><surname>Gilbert</surname></personname><contrib>Original work by </contrib></author>
+ <sect1 xml:id="backup-basics">
+ <title>Backup Basics</title>
+
+<!--
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Lowell</firstname>
+ <surname>Gilbert</surname>
+ </personname>
+ <contrib>Original work by </contrib>
+ </author>
</authorgroup>
-
- </info>
+ -->
-
+ <para>Implementing a backup plan is essential in order to have the
+ ability to recover from disk failure, accidental file deletion,
+ random file corruption, or complete machine destruction,
+ including destruction of on-site backups.</para>
- <para>The first requirement in devising a backup plan is to make sure that
- all of the following problems are covered:</para>
+ <para>The backup type and schedule will vary, depending upon the
+ importance of the data, the granularity needed for file
+ restores, and the amount of acceptable downtime. Some possible
+ backup techniques include:</para>
<itemizedlist>
<listitem>
- <para>Disk failure</para>
+ <para>Archives of the whole system, backed up onto permanent,
+ off-site media. This provides protection against all of the
+ problems listed above, but is slow and inconvenient to
+ restore from, especially for non-privileged users.</para>
</listitem>
+
<listitem>
- <para>Accidental file deletion</para>
+ <para>File system snapshots, which are useful for restoring
+ deleted files or previous versions of files.</para>
</listitem>
+
<listitem>
- <para>Random file corruption</para>
+ <para>Copies of whole file systems or disks which are
+ sychronized with another system on the network using a
+ scheduled <package>net/rsync</package>.</para>
</listitem>
+
<listitem>
- <para>Complete machine destruction (e.g. fire), including destruction
- of any on-site backups.</para>
+ <para>Hardware or software <acronym>RAID</acronym>, which
+ minimizes or avoids downtime when a disk fails.</para>
</listitem>
</itemizedlist>
- <para>It is perfectly possible that some systems will be best served by
- having each of these problems covered by a completely different
- technique. Except for strictly personal systems with very low-value
- data, it is unlikely that one technique would cover all of them.</para>
+ <para>Typically, a mix of backup techniques is used. For
+ example, one could create a schedule to automate a weekly, full
+ system backup that is stored off-site and to supplement this
+ backup with hourly ZFS snapshots. In addition, one could make a
+ manual backup of individual directories or files before making
+ file edits or deletions.</para>
- <para>Some of the techniques in the toolbox are:</para>
-
- <itemizedlist>
- <listitem>
- <para>Archives of the whole system, backed up onto permanent media
- offsite. This actually provides protection against all of the
- possible problems listed above, but is slow and inconvenient to
- restore from. You can keep copies of the backups onsite and/or
- online, but there will still be inconveniences in restoring files,
- especially for non-privileged users.</para>
- </listitem>
-
- <listitem>
- <para>Filesystem snapshots. This is really only helpful in the
- accidental file deletion scenario, but it can be
- <emphasis>very</emphasis> helpful in that case, and is quick and
- easy to deal with.</para>
- </listitem>
+ <para>This section describes some of the utilities which can be
+ used to create and manage backups on a &os; system.</para>
- <listitem>
- <para>Copies of whole filesystems and/or disks (e.g. periodic rsync of
- the whole machine). This is generally most useful in networks with
- unique requirements. For general protection against disk failure,
- it is usually inferior to <acronym>RAID</acronym>. For restoring
- accidentally deleted files, it can be comparable to
- <acronym>UFS</acronym> snapshots, but that depends on your
- preferences.</para>
- </listitem>
+ <sect2>
+ <title>File System Backups</title>
- <listitem>
- <para><acronym>RAID</acronym>. Minimizes or avoids downtime when a
- disk fails. At the expense of having to deal with disk failures
- more often (because you have more disks), albeit at a much lower
- urgency.</para>
- </listitem>
+ <indexterm>
+ <primary>backup software</primary>
+ <secondary>dump / restore</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><command>dump</command></primary>
+ </indexterm>
+ <indexterm>
+ <primary><command>restore</command></primary>
+ </indexterm>
- <listitem>
- <para>Checking fingerprints of files. The &man.mtree.8; utility is
- very useful for this. Although it is not a backup technique, it
- helps guarantee that you will notice when you need to resort to your
- backups. This is particularly important for offline backups, and
- should be checked periodically.</para>
- </listitem>
- </itemizedlist>
+ <para>The traditional &unix; programs for backing up a file
+ system are &man.dump.8;, which creates the backup, and
+ &man.restore.8;, which restores the backup. These utilities
+ work at the disk block level, below the abstractions of the
+ files, links, and directories that are created by file
+ systems. Unlike other backup software,
+ <command>dump</command> backs up an entire file system and is
+ unable to backup only part of a file system or a directory
+ tree that spans multiple file systems. Instead of writing
+ files and directories, <command>dump</command> writes the raw
+ data blocks that comprise files and directories.</para>
- <para>It is quite easy to come up with even more techniques, many of them
- variations on the ones listed above. Specialized requirements will
- usually lead to specialized techniques (for example, backing up a live
- database usually requires a method particular to the database software
- as an intermediate step). The important thing is to know what dangers
- you want to protect against, and how you will handle each.</para>
- </sect1>
+ <note>
+ <para>If <command>dump</command> is used on the root
+ directory, it will not back up <filename>/home</filename>,
+ <filename>/usr</filename> or many other directories since
+ these are typically mount points for other file systems or
+ symbolic links into those file systems.</para>
+ </note>
- <sect1 xml:id="backup-basics">
- <title>Backup Basics</title>
+ <para>When used to restore data, <command>restore</command>
+ stores temporary files in <filename>/tmp/</filename> by
+ default. When using a recovery disk with a small
+ <filename>/tmp</filename>, set <envar>TMPDIR</envar> to a
+ directory with more free space in order for the restore to
+ succeed.</para>
- <para>The three major backup programs are
- &man.dump.8;,
- &man.tar.1;,
- and
- &man.cpio.1;.</para>
+ <para>When using <command>dump</command>, be aware that some
+ quirks remain from its early days in Version 6 of
+ AT&amp;T &unix;,circa 1975. The default parameters assume a
+ backup to a 9-track tape, rather than to another type of media
+ or to the high-density tapes available today. These defaults
+ must be overridden on the command line.</para>
- <sect2>
- <title>Dump and Restore</title>
<indexterm>
- <primary>backup software</primary>
- <secondary>dump / restore</secondary>
+ <primary><filename>.rhosts</filename></primary>
</indexterm>
- <indexterm><primary><command>dump</command></primary></indexterm>
- <indexterm><primary><command>restore</command></primary></indexterm>
-
- <para>The traditional &unix; backup programs are
- <command>dump</command> and <command>restore</command>. They
- operate on the drive as a collection of disk blocks, below the
- abstractions of files, links and directories that are created by
- the file systems. <command>dump</command> backs up an entire
- file system on a device. It is unable to backup only part of a
- file system or a directory tree that spans more than one
- file system. <command>dump</command> does not write files and
- directories to tape, but rather writes the raw data blocks that
- comprise files and directories.</para>
-
- <note><para>If you use <command>dump</command> on your root directory, you
- would not back up <filename>/home</filename>,
- <filename>/usr</filename> or many other directories since
- these are typically mount points for other file systems or
- symbolic links into those file systems.</para></note>
-
- <para><command>dump</command> has quirks that remain from its early days in
- Version 6 of AT&amp;T UNIX (circa 1975). The default
- parameters are suitable for 9-track tapes (6250 bpi), not the
- high-density media available today (up to 62,182 ftpi). These
- defaults must be overridden on the command line to utilize the
- capacity of current tape drives.</para>
-
- <indexterm><primary><filename>.rhosts</filename></primary></indexterm>
- <para>It is also possible to backup data across the network to a
- tape drive attached to another computer with <command>rdump</command> and
- <command>rrestore</command>. Both programs rely upon &man.rcmd.3; and
- &man.ruserok.3; to access the remote tape drive. Therefore,
- the user performing the backup must be listed in the
- <filename>.rhosts</filename> file on the remote computer. The
- arguments to <command>rdump</command> and <command>rrestore</command> must be suitable
- to use on the remote computer. When
- <command>rdump</command>ing from a FreeBSD computer to an
- Exabyte tape drive connected to a Sun called
- <systemitem>komodo</systemitem>, use:</para>
-
- <screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2&gt;&amp;1</userinput></screen>
-
- <para>Beware: there are security implications to
- allowing <filename>.rhosts</filename> authentication. Evaluate your
- situation carefully.</para>
-
- <para>It is also possible to use <command>dump</command> and
- <command>restore</command> in a more secure fashion over
- <command>ssh</command>.</para>
+ <para>It is possible to backup a file system across the network
+ to a another system or to a tape drive attached to another
+ computer. While the &man.rdump.8; and &man.rrestore.8;
+ utilities can be used for this purpose, they are not
+ considered to be secure.</para>
+
+ <para>Instead, one can use <command>dump</command> and
+ <command>restore</command> in a more secure fashion over an
+ <acronym>SSH</acronym> connection. This example creates a
+ full, compressed backup of <filename>/usr</filename> and sends
+ the backup file to the specified host over a
+ <acronym>SSH</acronym> connection.</para>
<example>
- <title>Using <command>dump</command> over <application>ssh</application></title>
+ <title>Using <command>dump</command> over
+ <application>ssh</application></title>
<screen>&prompt.root; <userinput>/sbin/dump -0uan -f - /usr | gzip -2 | ssh -c blowfish \
targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz</userinput></screen>
-
</example>
- <para>Or using <command>dump</command>'s built-in method,
- setting the environment variable <envar>RSH</envar>:</para>
+ <para>This example sets <envar>RSH</envar> in order to write the
+ backup to a tape drive on a remote system over a
+ <acronym>SSH</acronym> connection:</para>
<example>
- <title>Using <command>dump</command> over <application>ssh</application> with <envar>RSH</envar> set</title>
-
- <screen>&prompt.root; <userinput>RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0 /usr</userinput></screen>
+ <title>Using <command>dump</command> over
+ <application>ssh</application> with <envar>RSH</envar>
+ Set</title>
+ <screen>&prompt.root; <userinput>env RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0 /usr</userinput></screen>
</example>
-
</sect2>
<sect2>
- <title><command>tar</command></title>
+ <title>Directory Backups</title>
+
<indexterm>
- <primary>backup software</primary>
- <secondary><command>tar</command></secondary>
+ <primary>backup software</primary>
+ <secondary><command>tar</command></secondary>
</indexterm>
- <para>&man.tar.1; also dates back to Version 6 of AT&amp;T UNIX
- (circa 1975). <command>tar</command> operates in cooperation
- with the file system; it writes files and
- directories to tape. <command>tar</command> does not support the
- full range of options that are available from &man.cpio.1;, but
- it does not require the unusual command
- pipeline that <command>cpio</command> uses.</para>
+ <para>Several built-in utilities are available for backing up
+ and restoring specified files and directories as
+ needed.</para>
+
+ <para>A good choice for making a backup of all of the files in a
+ directory is &man.tar.1;. This utility dates back to Version
+ 6 of AT&amp;T &unix; and by default assumes a recursive backup
+ to a local tape device. Switches can be used to instead
+ specify the name of a backup file.</para>
<indexterm><primary><command>tar</command></primary></indexterm>
- <para>On FreeBSD 5.3 and later, both GNU <command>tar</command>
- and the default <command>bsdtar</command> are available. The
- GNU version can be invoked with <command>gtar</command>. It
- supports remote devices using the same syntax as
- <command>rdump</command>. To <command>tar</command> to an
- Exabyte tape drive connected to a Sun called
- <systemitem>komodo</systemitem>, use:</para>
+ <para>This example creates a compressed backup of the current
+ directory and saves it to
+ <filename>/tmp/mybackup.tgz</filename>. When creating a
+ backup file, make sure that the backup is not saved to the
+ same directory that is being backed up.</para>
- <screen>&prompt.root; <userinput>/usr/bin/gtar cf komodo:/dev/nsa8 . 2&gt;&amp;1</userinput></screen>
+ <example>
+ <title>Backing Up the Current Directory with
+ <command>tar</command></title>
- <para>The same could be accomplished with
- <command>bsdtar</command> by using a pipeline and
- <command>rsh</command> to send the data to a remote tape
- drive.</para>
+ <screen>&prompt.root; <userinput>tar czvf <replaceable>/tmp/mybackup.tgz</replaceable> . </userinput></screen>
+ </example>
- <screen>&prompt.root; <userinput>tar cf - . | rsh hostname dd of=tape-device obs=20b</userinput></screen>
+ <para>To restore the entire backup, <command>cd</command> into
+ the directory to restore into and specify the name of the
+ backup. Note that this will overwrite any newer versions of
+ files in the restore directory. When in doubt, restore to a
+ temporary directory or specify the name of the file within the
+ backup to restore.</para>
- <para>If you are worried about the security of backing up over a
- network you should use the <command>ssh</command> command
- instead of <command>rsh</command>.</para>
- </sect2>
+ <example>
+ <title>Restoring Up the Current Directory with
+ <command>tar</command></title>
- <sect2>
- <title><command>cpio</command></title>
- <indexterm>
- <primary>backup software</primary>
- <secondary><command>cpio</command></secondary>
- </indexterm>
+ <screen>&prompt.root; <userinput>tar xzvf <replaceable>/tmp/mybackup.tgz</replaceable></userinput></screen>
+ </example>
- <para>&man.cpio.1; is the original &unix; file interchange tape
- program for magnetic media. <command>cpio</command> has options
- (among many others) to perform byte-swapping, write a number of
- different archive formats, and pipe the data to other programs.
- This last feature makes <command>cpio</command> an excellent
- choice for installation media. <command>cpio</command> does not
- know how to walk the directory tree and a list of files must be
- provided through <filename>stdin</filename>.</para>
- <indexterm><primary><command>cpio</command></primary></indexterm>
-
- <para><command>cpio</command> does not support backups across
- the network. You can use a pipeline and <command>rsh</command>
- to send the data to a remote tape drive.</para>
-
- <screen>&prompt.root; <userinput>for f in directory_list; do</userinput>
-<userinput>find $f &gt;&gt; backup.list</userinput>
-<userinput>done</userinput>
-&prompt.root; <userinput>cpio -v -o --format=newc &lt; backup.list | ssh user@host "cat &gt; backup_device"</userinput></screen>
-
- <para>Where <replaceable>directory_list</replaceable> is the list of
- directories you want to back up,
- <replaceable>user</replaceable>@<replaceable>host</replaceable> is the
- user/hostname combination that will be performing the backups, and
- <replaceable>backup_device</replaceable> is where the backups should
- be written to (e.g., <filename>/dev/nsa0</filename>).</para>
- </sect2>
+ <para>There are dozens of available switches which are described
+ in &man.tar.1;. This utility also supports the use of exclude
+ patterns to specify which files should not be included when
+ backing up the specified directory or restoring files from a
+ backup.</para>
- <sect2>
- <title><command>pax</command></title>
<indexterm>
- <primary>backup software</primary>
- <secondary><command>pax</command></secondary>
+ <primary>backup software</primary>
+ <secondary><command>cpio</command></secondary>
</indexterm>
- <indexterm><primary><command>pax</command></primary></indexterm>
- <indexterm><primary>POSIX</primary></indexterm>
- <indexterm><primary>IEEE</primary></indexterm>
- <para>&man.pax.1; is IEEE/&posix;'s answer to
- <command>tar</command> and <command>cpio</command>. Over the
- years the various versions of <command>tar</command> and
- <command>cpio</command> have gotten slightly incompatible. So
- rather than fight it out to fully standardize them, &posix;
- created a new archive utility. <command>pax</command> attempts
- to read and write many of the various <command>cpio</command>
- and <command>tar</command> formats, plus new formats of its own.
- Its command set more resembles <command>cpio</command> than
- <command>tar</command>.</para>
- </sect2>
+ <para>To create a backup using a specified list of files and
+ directories, &man.cpio.1; is a good choice. Unlike
+ <command>tar</command>, <command>cpio</command> does not know
+ how to walk the directory tree and it must be provided the
+ list of files to backup.</para>
- <sect2 xml:id="backups-programs-amanda">
- <title><application>Amanda</application></title>
- <indexterm>
- <primary>backup software</primary>
- <secondary><application>Amanda</application></secondary>
- </indexterm>
- <indexterm><primary><application>Amanda</application></primary></indexterm>
-
- <!-- Remove link until <port> tag is available -->
- <para><application>Amanda</application> (Advanced Maryland
- Network Disk Archiver) is a client/server backup system,
- rather than a single program. An <application>Amanda</application> server will backup to
- a single tape drive any number of computers that have <application>Amanda</application>
- clients and a network connection to the <application>Amanda</application> server. A
- common problem at sites with a number of large disks is
- that the length of time required to backup to data directly to tape
- exceeds the amount of time available for the task. <application>Amanda</application>
- solves this problem. <application>Amanda</application> can use a <quote>holding disk</quote> to
- backup several file systems at the same time. <application>Amanda</application> creates
- <quote>archive sets</quote>: a group of tapes used over a period of time to
- create full backups of all the file systems listed in <application>Amanda</application>'s
- configuration file. The <quote>archive set</quote> also contains nightly
- incremental (or differential) backups of all the file systems.
- Restoring a damaged file system requires the most recent full
- backup and the incremental backups.</para>
-
- <para>The configuration file provides fine control of backups and the
- network traffic that <application>Amanda</application> generates. <application>Amanda</application> will use any of the
- above backup programs to write the data to tape. <application>Amanda</application> is available
- as either a port or a package, it is not installed by default.</para>
- </sect2>
+ <para>For example, a list of files can be created using
+ <command>ls</command> or <command>find</command>. This
+ example creates a recursive listing of the current directory
+ which is then piped to <command>cpio</command> in order to
+ create an output backup file named
+ <filename>/tmp/mybackup.cpio</filename>.</para>
- <sect2>
- <title>Do Nothing</title>
-
- <para><quote>Do nothing</quote> is not a computer program, but it is the
- most widely used backup strategy. There are no initial costs. There
- is no backup schedule to follow. Just say no. If something happens
- to your data, grin and bear it!</para>
-
- <para>If your time and your data is worth little to nothing, then
- <quote>Do nothing</quote> is the most suitable backup program for your
- computer. But beware, &unix; is a useful tool, you may find that within
- six months you have a collection of files that are valuable to
- you.</para>
-
- <para><quote>Do nothing</quote> is the correct backup method for
- <filename>/usr/obj</filename> and other directory trees that can be
- exactly recreated by your computer. An example is the files that
- comprise the HTML or &postscript; version of this Handbook.
- These document formats have been created from SGML input
- files. Creating backups of the HTML or &postscript; files is
- not necessary. The SGML files are backed up regularly.</para>
- </sect2>
+ <example>
+ <title>Using<command>ls</command> and <command>cpio</command>
+ to Make a Recursive Backup of the Current Directory</title>
+
+ <screen>&prompt.root; <userinput>ls -R | cpio -ovF <replaceable>/tmp/mybackup.cpio</replaceable></userinput></screen>
+ </example>
- <sect2>
- <title>Which Backup Program Is Best?</title>
<indexterm>
- <primary>LISA</primary>
+ <primary>backup software</primary>
+ <secondary><command>pax</command></secondary>
</indexterm>
+ <indexterm><primary><command>pax</command></primary></indexterm>
+ <indexterm><primary>POSIX</primary></indexterm>
+ <indexterm><primary>IEEE</primary></indexterm>
- <para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky
- torture tested all the backup programs discussed here. The clear
- choice for preserving all your data and all the peculiarities of &unix;
- file systems is <command>dump</command>. Elizabeth created file systems containing
- a large variety of unusual conditions (and some not so unusual ones)
- and tested each program by doing a backup and restore of those
- file systems. The peculiarities included: files with holes, files with
- holes and a block of nulls, files with funny characters in their
- names, unreadable and unwritable files, devices, files that change
- size during the backup, files that are created/deleted during the
- backup and more. She presented the results at LISA V in Oct. 1991.
- See <link xlink:href="http://berdmann.dyndns.org/zwicky/testdump.doc.html">torture-testing
- Backup and Archive Programs</link>.</para>
- </sect2>
+ <para>A backup utility which tries to bridge the features
+ provided by <command>tar</command> and <command>cpio</command>
+ is &man.pax.1;. Over the years, the various versions of
+ <command>tar</command> and <command>cpio</command> became
+ slightly incompatible. &posix; created <command>pax</command>
+ which attempts to read and write many of the various
+ <command>cpio</command> and <command>tar</command> formats,
+ plus new formats of its own.</para>
- <sect2>
- <title>Emergency Restore Procedure</title>
+ <para>The <command>pax</command> equivalent to the previous
+ examples would be:</para>
- <sect3>
- <title>Before the Disaster</title>
-
- <para>There are only four steps that you need to perform in
- preparation for any disaster that may occur.</para>
- <indexterm>
- <primary><command>bsdlabel</command></primary>
- </indexterm>
-
- <para>First, print the bsdlabel from each of your disks
- (e.g. <command>bsdlabel da0 | lpr</command>), your file system table
- (<filename>/etc/fstab</filename>) and all boot messages,
- two copies of
- each.</para>
-
- <indexterm><primary>fix-it floppies</primary></indexterm>
- <para>Second, determine that the boot and fix-it floppies
- (<filename>boot.flp</filename> and <filename>fixit.flp</filename>)
- have all your devices. The easiest way to check is to reboot your
- machine with the boot floppy in the floppy drive and check the boot
- messages. If all your devices are listed and functional, skip on to
- step three.</para>
-
- <para>Otherwise, you have to create two custom bootable
- floppies which have a kernel that can mount all of your disks
- and access your tape drive. These floppies must contain:
- <command>fdisk</command>, <command>bsdlabel</command>,
- <command>newfs</command>, <command>mount</command>, and
- whichever backup program you use. These programs must be
- statically linked. If you use <command>dump</command>, the
- floppy must contain <command>restore</command>.</para>
-
- <para>Third, create backup tapes regularly. Any changes that you make
- after your last backup may be irretrievably lost. Write-protect the
- backup tapes.</para>
-
- <para>Fourth, test the floppies (either <filename>boot.flp</filename>
- and <filename>fixit.flp</filename> or the two custom bootable
- floppies you made in step two.) and backup tapes. Make notes of the
- procedure. Store these notes with the bootable floppy, the
- printouts and the backup tapes. You will be so distraught when
- restoring that the notes may prevent you from destroying your backup
- tapes (How? In place of <command>tar xvf /dev/sa0</command>, you
- might accidentally type <command>tar cvf /dev/sa0</command> and
- over-write your backup tape).</para>
-
- <para>For an added measure of security, make bootable floppies and two
- backup tapes each time. Store one of each at a remote location. A
- remote location is NOT the basement of the same office building. A
- number of firms in the World Trade Center learned this lesson the
- hard way. A remote location should be physically separated from
- your computers and disk drives by a significant distance.</para>
-
- <example>
- <title>A Script for Creating a Bootable Floppy</title>
-
- <programlisting><![CDATA[#!/bin/sh
-#
-# create a restore floppy
-#
-# format the floppy
-#
-PATH=/bin:/sbin:/usr/sbin:/usr/bin
+ <example>
+ <title>Backing Up the Current Directory with
+ <command>pax</command></title>
-fdformat -q fd0
-if [ $? -ne 0 ]
-then
- echo "Bad floppy, please use a new one"
- exit 1
-fi
+ <screen>&prompt.root; <userinput>pax -wf <replaceable>/tmp/mybackup.pax</replaceable> .</userinput></screen>
+ </example>
+ </sect2>
-# place boot blocks on the floppy
-#
-bsdlabel -w -B /dev/fd0c fd1440
+ <sect2 xml:id="backups-tapebackups">
+ <title>Using Data Tapes for Backups</title>
-#
-# newfs the one and only partition
-#
-newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/fd0a
+ <indexterm><primary>tape media</primary></indexterm>
-#
-# mount the new floppy
-#
-mount /dev/fd0a /mnt
+ <para>While tape technology has continued to evolve, modern
+ backup systems tend to combine off-site backups with local
+ removable media. &os; supports any tape drive that uses
+ <acronym>SCSI</acronym>, such as <acronym>LTO</acronym> or
+ <acronym>DAT</acronym>. There is limited support for
+ <acronym>SATA</acronym> and <acronym>USB</acronym> tape
+ drives.</para>
-#
-# create required directories
-#
-mkdir /mnt/dev
-mkdir /mnt/bin
-mkdir /mnt/sbin
-mkdir /mnt/etc
-mkdir /mnt/root
-mkdir /mnt/mnt # for the root partition
-mkdir /mnt/tmp
-mkdir /mnt/var
+ <para>For <acronym>SCSI</acronym> tape devices, &os; uses the
+ &man.sa.4; driver and the <filename>/dev/sa0</filename>,
+ <filename>/dev/nsa0</filename>, and
+ <filename>/dev/esa0</filename> devices. The physical device
+ name is <filename>/dev/sa0</filename>. When
+ <filename>/dev/nsa0</filename> is used, the backup application
+ will not rewind the tape after writing a file, which allows
+ writing more than one file to a tape. Using
+ <filename>/dev/esa0</filename> ejects the tape after the
+ device is closed.</para>
-#
-# populate the directories
-#
-if [ ! -x /sys/compile/MINI/kernel ]
-then
- cat &lt;&lt; EOM
-The MINI kernel does not exist, please create one.
-Here is an example config file:
-#
-# MINI - A kernel to get FreeBSD onto a disk.
-#
-machine "i386"
-cpu "I486_CPU"
-ident MINI
-maxusers 5
+ <para>In &os;, <command>mt</command> is used to control
+ operations of the tape drive, such as seeking through files on
+ a tape or writing tape control marks to the tape. For
+ example, the first three files on a tape can be preserved by
+ skipping past them before writing a new file:</para>
-options INET # needed for _tcp _icmpstat _ipstat
- # _udpstat _tcpstat _udb
-options FFS #Berkeley Fast File System
-options FAT_CURSOR #block cursor in syscons or pccons
-options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device
-options NCONS=2 #1 virtual consoles
-options USERCONFIG #Allow user configuration with -c XXX
+ <screen>&prompt.root; <userinput>mt -f /dev/nsa0 fsf 3</userinput></screen>
-config kernel root on da0 swap on da0 and da1 dumps on da0
+ <para>This utility supports many operations. Refer to
+ &man.mt.1; for details.</para>
-device isa0
-device pci0
+ <para>To write a single file to tape using
+ <command>tar</command>, specify the name of the tape device
+ and the file to backup:</para>
-device fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr
-device fd0 at fdc0 drive 0
+ <screen>&prompt.root; <userinput>tar cvf /dev/sa0 <replaceable>file</replaceable></userinput></screen>
-device ncr0
+ <para>To recover files from a <command>tar</command> archive
+ on tape into the current directory:</para>
-device scbus0
+ <screen>&prompt.root; <userinput>tar xvf /dev/sa0</userinput></screen>
-device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr
-device npx0 at isa? port "IO_NPX" irq 13 vector npxintr
+ <para>To backup a <acronym>UFS</acronym> file system, use
+ <command>dump</command>. This examples backs up
+ <filename>/usr</filename> without rewinding the tape when
+ finished:</para>
-device da0
-device da1
-device da2
+ <screen>&prompt.root; <userinput>dump -0aL -b64 -f /dev/nsa0 /usr</userinput></screen>
-device sa0
+ <para>To interactively restore files from a
+ <command>dump</command> file on tape into the current
+ directory:</para>
-pseudo-device loop # required by INET
-pseudo-device gzip # Exec gzipped a.out's
-EOM
- exit 1
-fi
+ <screen>&prompt.root; <userinput>restore -i -f /dev/nsa0</userinput></screen>
+ </sect2>
-cp -f /sys/compile/MINI/kernel /mnt
+ <sect2 xml:id="backups-programs-amanda">
+ <title>Third-Party Backup Utilities</title>
-gzip -c -best /sbin/init &gt; /mnt/sbin/init
-gzip -c -best /sbin/fsck &gt; /mnt/sbin/fsck
-gzip -c -best /sbin/mount &gt; /mnt/sbin/mount
-gzip -c -best /sbin/halt &gt; /mnt/sbin/halt
-gzip -c -best /sbin/restore &gt; /mnt/sbin/restore
+ <indexterm>
+ <primary>backup software</primary>
+ </indexterm>
-gzip -c -best /bin/sh &gt; /mnt/bin/sh
-gzip -c -best /bin/sync &gt; /mnt/bin/sync
+ <para>The &os; Ports Collection provides many third-party
+ utilities which can be used to schedule the creation of
+ backups, simplify tape backup, and make backups easier and
+ more convenient. Many of these applications are client/server
+ based and can be used to automate the backups of a single
+ system or all of the computers in a network.</para>
+
+ <para>Popular utilities include
+ <application>Amanda</application>,
+ <application>Bacula</application>,
+ <application>rsync</application>, and
+ <application>duplicity</application>.</para>
+ </sect2>
-cp /root/.profile /mnt/root
+ <sect2>
+ <title>Emergency Recovery</title>
-cp -f /dev/MAKEDEV /mnt/dev
-chmod 755 /mnt/dev/MAKEDEV
+ <para>In addition to regular backups, it is recommended to
+ perform the following steps as part of an emergency
+ preparedness plan.</para>
-chmod 500 /mnt/sbin/init
-chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt
-chmod 555 /mnt/bin/sh /mnt/bin/sync
-chmod 6555 /mnt/sbin/restore
+ <indexterm>
+ <primary><command>bsdlabel</command></primary></indexterm>
-#
-# create the devices nodes
-#
-cd /mnt/dev
-./MAKEDEV std
-./MAKEDEV da0
-./MAKEDEV da1
-./MAKEDEV da2
-./MAKEDEV sa0
-./MAKEDEV pty0
-cd /
+ <para>Create a print copy of the output of the following
+ commands:</para>
-#
-# create minimum file system table
-#
-cat &gt; /mnt/etc/fstab &lt;&lt;EOM
-/dev/fd0a / ufs rw 1 1
-EOM
+ <itemizedlist>
+ <listitem>
+ <para><command>gpart show</command></para>
+ </listitem>
-#
-# create minimum passwd file
-#
-cat &gt; /mnt/etc/passwd &lt;&lt;EOM
-root:*:0:0:Charlie &:/root:/bin/sh
-EOM
+ <listitem>
+ <para><command>more /etc/fstab</command></para>
+ </listitem>
-cat &gt; /mnt/etc/master.passwd &lt;&lt;EOM
-root::0:0::0:0:Charlie &:/root:/bin/sh
-EOM
+ <listitem>
+ <para><command>dmesg</command></para>
+ </listitem>
+ </itemizedlist>
-chmod 600 /mnt/etc/master.passwd
-chmod 644 /mnt/etc/passwd
-/usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd
+ <indexterm><primary>livefs
+ <acronym>CD</acronym></primary></indexterm>
-#
-# umount the floppy and inform the user
-#
-/sbin/umount /mnt
-echo "The floppy has been unmounted and is now ready."]]></programlisting>
+ <para>Store this printout and a copy of the installation media
+ in a secure location. Should an emergency restore be
+ needed, boot into the installation media and select
+ <literal>Live CD</literal> to access a rescue shell. This
+ rescue mode can be used to view the current state of the
+ system, and if needed, to reformat disks and restore data
+ from backups.</para>
- </example>
+ <note>
+ <para>The installation media for
+ &os;/&arch.i386;&nbsp;&rel2.current;-RELEASE does not
+ include a rescue shell. For this version, instead
+ download and burn a Livefs <acronym>CD</acronym> image from
+ <uri
+ xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso</uri>.</para>
+ </note>
- </sect3>
+ <para>Next, test the rescue shell and the backups. Make notes
+ of the procedure. Store these notes with the media, the
+ printouts, and the backups. These notes may prevent the
+ inadvertent destruction of the backups while under the stress
+ of performing an emergency recovery.</para>
- <sect3>
- <title>After the Disaster</title>
-
- <para>The key question is: did your hardware survive? You have been
- doing regular backups so there is no need to worry about the
- software.</para>
-
- <para>If the hardware has been damaged, the parts should be replaced
- before attempting to use the computer.</para>
-
- <para>If your hardware is okay, check your floppies. If you are using
- a custom boot floppy, boot single-user (type <literal>-s</literal>
- at the <prompt>boot:</prompt> prompt). Skip the following
- paragraph.</para>
-
- <para>If you are using the <filename>boot.flp</filename> and
- <filename>fixit.flp</filename> floppies, keep reading. Insert the
- <filename>boot.flp</filename> floppy in the first floppy drive and
- boot the computer. The original install menu will be displayed on
- the screen. Select the <literal>Fixit--Repair mode with CDROM or
- floppy.</literal> option. Insert the
- <filename>fixit.flp</filename> when prompted.
- <command>restore</command> and the other programs that you need are
- located in <filename>/mnt2/rescue</filename>
- (<filename>/mnt2/stand</filename> for
- &os; versions older than 5.2).</para>
-
- <para>Recover each file system separately.</para>
-
- <indexterm>
- <primary><command>mount</command></primary>
- </indexterm>
- <indexterm><primary>root partition</primary></indexterm>
- <indexterm>
- <primary><command>bsdlabel</command></primary>
- </indexterm>
- <indexterm>
- <primary><command>newfs</command></primary>
- </indexterm>
- <para>Try to <command>mount</command> (e.g. <command>mount /dev/da0a
- /mnt</command>) the root partition of your first disk. If the
- bsdlabel was damaged, use <command>bsdlabel</command> to re-partition and
- label the disk to match the label that you printed and saved. Use
- <command>newfs</command> to re-create the file systems. Re-mount the root
- partition of the floppy read-write (<command>mount -u -o rw
- /mnt</command>). Use your backup program and backup tapes to
- recover the data for this file system (e.g. <command>restore vrf
- /dev/sa0</command>). Unmount the file system (e.g. <command>umount
- /mnt</command>). Repeat for each file system that was
- damaged.</para>
-
- <para>Once your system is running, backup your data onto new tapes.
- Whatever caused the crash or data loss may strike again. Another
- hour spent now may save you from further distress later.</para>
- </sect3>
+ <para>For an added measure of security, store the latest backup
+ at a remote location which is physically separated from the
+ computers and disk drives by a significant distance.</para>
</sect2>
</sect1>
<sect1 xml:id="disks-virtual">
- <info><title>Network, Memory, and File-Backed File Systems</title>
+ <info>
+ <title>Memory Disks</title>
+
<authorgroup>
- <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Reorganized and enhanced by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ </personname>
+ <contrib>Reorganized and enhanced by </contrib>
+ </author>
</authorgroup>
</info>
-
- <indexterm><primary>virtual disks</primary></indexterm>
- <indexterm>
- <primary>disks</primary>
- <secondary>virtual</secondary>
- </indexterm>
-
- <para>Aside from the disks you physically insert into your computer:
- floppies, CDs, hard drives, and so forth; other forms of disks
- are understood by FreeBSD - the <firstterm>virtual
- disks</firstterm>.</para>
- <indexterm><primary>NFS</primary></indexterm>
- <indexterm><primary>Coda</primary></indexterm>
- <indexterm>
- <primary>disks</primary>
- <secondary>memory</secondary>
- </indexterm>
- <para>These include network file systems such as the <link linkend="network-nfs">Network File System</link> and Coda, memory-based
- file systems and
- file-backed file systems.</para>
+ <para>In addition to physical disks, &os; also supports the
+ creation and use of memory disks. One possible use for a
+ memory disk is to access the contents of an
+ <acronym>ISO</acronym> file system without the overhead of first
+ burning it to a <acronym>CD</acronym> or <acronym>DVD</acronym>,
+ then mounting the <acronym>CD/DVD</acronym> media.</para>
- <para>According to the FreeBSD version you run, you will have to use
- different tools for creation and use of file-backed and
- memory-based file systems.</para>
+ <para>In &os;, the &man.md.4; driver is used to provide support
+ for memory disks. The <filename>GENERIC</filename> kernel
+ includes this driver. When using a custom kernel configuration
+ file, ensure it includes this line:</para>
- <note>
- <para>Use &man.devfs.5; to allocate device nodes transparently for the
- user.</para>
- </note>
+ <programlisting>device md</programlisting>
<sect2 xml:id="disks-mdconfig">
- <title>File-Backed File System</title>
+ <title>Attaching and Detaching Existing Images</title>
+
<indexterm>
- <primary>disks</primary>
- <secondary>file-backed</secondary>
+ <primary>disks</primary>
+ <secondary>memory</secondary>
</indexterm>
- <para>The utility &man.mdconfig.8; is used to configure and enable
- memory disks, &man.md.4;, under FreeBSD. To use
- &man.mdconfig.8;, you have to load &man.md.4; module or to add
- the support in your kernel configuration file:</para>
-
- <programlisting>device md</programlisting>
-
- <para>The &man.mdconfig.8; command supports three kinds of
- memory backed virtual disks: memory disks allocated with
- &man.malloc.9;, memory disks using a file or swap space as
- backing. One possible use is the mounting of floppy
- or CD images kept in files.</para>
-
- <para>To mount an existing file system image:</para>
-
- <example>
- <title>Using <command>mdconfig</command> to Mount an Existing File System
- Image</title>
+ <para>To mount an existing file system image, use
+ <command>mdconfig</command> to specify the name of the
+ <acronym>ISO</acronym> file and a free unit number. Then,
+ refer to that unit number to mount it on an existing mount
+ point. Once mounted, the files in the <acronym>ISO</acronym>
+ will appear in the mount point. This example attaches
+ <replaceable>diskimage.iso</replaceable> to the memory device
+ <filename>/dev/md0</filename> then mounts that memory device
+ on <filename>/mnt</filename>:</para>
+
+ <screen>&prompt.root; <userinput>mdconfig -f <replaceable>diskimage.iso</replaceable> -u <replaceable>0</replaceable></userinput>
+&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+
+ <para>If a unit number is not specified with
+ <option>-u</option>, <command>mdconfig</command> will
+ automatically allocate an unused memory device and output
+ the name of the allocated unit, such as
+ <filename>md4</filename>. Refer to &man.mdconfig.8; for more
+ details about this command and its options.</para>
- <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f diskimage -u 0</userinput>
-&prompt.root; <userinput>mount /dev/md0 /mnt</userinput></screen>
- </example>
-
- <para>To create a new file system image with &man.mdconfig.8;:</para>
-
- <example>
- <title>Creating a New File-Backed Disk with <command>mdconfig</command></title>
-
- <screen>&prompt.root; <userinput>dd if=/dev/zero of=newimage bs=1k count=5k</userinput>
-5120+0 records in
-5120+0 records out
-&prompt.root; <userinput>mdconfig -a -t vnode -f newimage -u 0</userinput>
-&prompt.root; <userinput>bsdlabel -w md0 auto</userinput>
-&prompt.root; <userinput>newfs md0a</userinput>
-/dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048
- using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes.
-super-block backups (for fsck -b #) at:
- 160, 2720, 5280, 7840
-&prompt.root; <userinput>mount /dev/md0a /mnt</userinput>
-&prompt.root; <userinput>df /mnt</userinput>
-Filesystem 1K-blocks Used Avail Capacity Mounted on
-/dev/md0a 4710 4 4330 0% /mnt</screen>
- </example>
+ <indexterm>
+ <primary>disks</primary>
+ <secondary>detaching a memory disk</secondary>
+ </indexterm>
- <para>If you do not specify the unit number with the
- <option>-u</option> option, &man.mdconfig.8; will use the
- &man.md.4; automatic allocation to select an unused device.
- The name of the allocated unit will be output on stdout like
- <filename>md4</filename>. For more details about
- &man.mdconfig.8;, please refer to the manual page.</para>
-
- <para>The utility &man.mdconfig.8; is very useful, however it
- asks many command lines to create a file-backed file system.
- FreeBSD also comes with a tool called &man.mdmfs.8;,
- this program configures a &man.md.4; disk using
- &man.mdconfig.8;, puts a UFS file system on it using
- &man.newfs.8;, and mounts it using &man.mount.8;. For example,
- if you want to create and mount the same file system image as
- above, simply type the following:</para>
+ <para>When a memory disk is no longer in use, its resources
+ should be released back to the system. First, unmount the
+ file system, then use <command>mdconfig</command> to detach
+ the disk from the system and release its resources. To
+ continue this example:</para>
- <example>
- <title>Configure and Mount a File-Backed Disk with <command>mdmfs</command></title>
- <screen>&prompt.root; <userinput>dd if=/dev/zero of=newimage bs=1k count=5k</userinput>
-5120+0 records in
-5120+0 records out
-&prompt.root; <userinput>mdmfs -F newimage -s 5m md0 /mnt</userinput>
-&prompt.root; <userinput>df /mnt</userinput>
-Filesystem 1K-blocks Used Avail Capacity Mounted on
-/dev/md0 4718 4 4338 0% /mnt</screen>
- </example>
-
- <para>If you use the option <option>md</option> without unit
- number, &man.mdmfs.8; will use &man.md.4; auto-unit feature to
- automatically select an unused device. For more details
- about &man.mdmfs.8;, please refer to the manual page.</para>
+ <screen>&prompt.root; <userinput>umount /mnt</userinput>
+&prompt.root; <userinput>mdconfig -d -u <replaceable>0</replaceable></userinput></screen>
+ <para>To determine if any memory disks are still attached to the
+ system, type <command>mdconfig -l</command>.</para>
</sect2>
<sect2 xml:id="disks-md-freebsd5">
- <title>Memory-Based File System</title>
+ <title>Creating a File- or Memory-Backed Memory Disk</title>
+
<indexterm>
- <primary>disks</primary>
- <secondary>memory file system</secondary>
+ <primary>disks</primary>
+ <secondary>memory file system</secondary>
</indexterm>
-
- <para>For a
- memory-based file system the <quote>swap backing</quote>
- should normally be used. Using swap backing does not mean
- that the memory disk will be swapped out to disk by default,
- but merely that the memory disk will be allocated from a
- memory pool which can be swapped out to disk if needed. It is
- also possible to create memory-based disk which are
- &man.malloc.9; backed, but using malloc backed memory disks,
- especially large ones, can result in a system panic if the
- kernel runs out of memory.</para>
-
- <example>
- <title>Creating a New Memory-Based Disk with
- <command>mdconfig</command></title>
-
- <screen>&prompt.root; <userinput>mdconfig -a -t malloc -s 5m -u 1</userinput>
-&prompt.root; <userinput>newfs -U md1</userinput>
+ <para>&os; also supports memory disks where the storage to use
+ is allocated from either a hard disk or an area of memory.
+ The first method is commonly referred to as a file-backed file
+ system and the second method as a memory-backed file system.
+ Both types can be created using
+ <command>mdconfig</command>.</para>
+
+ <para>To create a new memory-backed file system, specify a type
+ of <literal>swap</literal> and the size of the memory disk to
+ create. Then, format the memory disk with a file system and
+ mount as usual. This example creates a 5M memory disk on unit
+ <literal>1</literal>. That memory disk is then formatted with
+ the <acronym>UFS</acronym> file system before it is
+ mounted:</para>
+
+ <screen>&prompt.root; <userinput>mdconfig -a -t swap -s <replaceable>5</replaceable>m -u <replaceable>1</replaceable></userinput>
+&prompt.root; <userinput>newfs -U md<replaceable>1</replaceable></userinput>
/dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048
- using 4 cylinder groups of 1.27MB, 81 blks, 256 inodes.
- with soft updates
+ using 4 cylinder groups of 1.27MB, 81 blks, 192 inodes.
+ with soft updates
super-block backups (for fsck -b #) at:
- 32, 2624, 5216, 7808
-&prompt.root; <userinput>mount /dev/md1 /mnt</userinput>
-&prompt.root; <userinput>df /mnt</userinput>
+ 160, 2752, 5344, 7936
+&prompt.root; <userinput>mount /dev/md<replaceable>1</replaceable> <replaceable>/mnt</replaceable></userinput>
+&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
Filesystem 1K-blocks Used Avail Capacity Mounted on
-/dev/md1 4846 2 4458 0% /mnt</screen>
- </example>
+/dev/md1 4718 4 4338 0% /mnt</screen>
- <example>
- <title>Creating a New Memory-Based Disk with
- <command>mdmfs</command></title>
- <screen>&prompt.root; <userinput>mdmfs -M -s 5m md2 /mnt</userinput>
-&prompt.root; <userinput>df /mnt</userinput>
-Filesystem 1K-blocks Used Avail Capacity Mounted on
-/dev/md2 4846 2 4458 0% /mnt</screen>
- </example>
+ <para>To create a new file-backed memory disk, first allocate an
+ area of disk to use. This example creates an empty 5K file
+ named <filename>newimage</filename>:</para>
- <para>Instead of using a &man.malloc.9; backed file system, it is
- possible to use swap, for that just replace
- <option>malloc</option> with <option>swap</option> in the
- command line of &man.mdconfig.8;. The &man.mdmfs.8; utility
- by default (without <option>-M</option>) creates a swap-based
- disk. For more details, please refer to &man.mdconfig.8;
- and &man.mdmfs.8; manual pages.</para>
- </sect2>
+ <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput>
+5120+0 records in
+5120+0 records out</screen>
- <sect2>
- <title>Detaching a Memory Disk from the System</title>
- <indexterm>
- <primary>disks</primary>
- <secondary>detaching a memory disk</secondary>
- </indexterm>
+ <para>Next, attach that file to a memory disk, label the memory
+ disk and format it with the <acronym>UFS</acronym> file
+ system, mount the memory disk, and verify the size of the
+ file-backed disk:</para>
- <para>When a memory-based or file-based file system
- is not used, you should release all resources to the system.
- The first thing to do is to unmount the file system, then use
- &man.mdconfig.8; to detach the disk from the system and release
- the resources.</para>
+ <screen>&prompt.root; <userinput>mdconfig -f <replaceable>newimage</replaceable> -u <replaceable>0</replaceable></userinput>
+&prompt.root; <userinput>bsdlabel -w md<replaceable>0</replaceable> auto</userinput>
+&prompt.root; <userinput>newfs md<replaceable>0</replaceable>a</userinput>
+/dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048
+ using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes.
+super-block backups (for fsck -b #) at:
+ 160, 2720, 5280, 7840
+&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable>a <replaceable>/mnt</replaceable></userinput>
+&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
+Filesystem 1K-blocks Used Avail Capacity Mounted on
+/dev/md0a 4710 4 4330 0% /mnt</screen>
+
+ <para>It takes several commands to create a file- or
+ memory-backed file system using <command>mdconfig</command>.
+ &os; also comes with <command>mdmfs</command> which
+ automatically configures a memory disk, formats it with the
+ <acronym>UFS</acronym> file system, and mounts it. For
+ example, after creating <replaceable>newimage</replaceable>
+ with <command>dd</command>, this one command is equivalent to
+ running the <command>bsdlabel</command>,
+ <command>newfs</command>, and <command>mount</command>
+ commands shown above:</para>
- <para>For example to detach and free all resources used by
- <filename>/dev/md4</filename>:</para>
+ <screen>&prompt.root; <userinput>mdmfs -F <replaceable>newimage</replaceable> -s <replaceable>5</replaceable>m md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
- <screen>&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen>
+ <para>To instead create a new memory-based memory disk with
+ <command>mdmfs</command>, use this one command:</para>
- <para>It is possible to list information about configured
- &man.md.4; devices in using the command <command>mdconfig
- -l</command>.</para>
+ <screen>&prompt.root; <userinput>mdmfs -s <replaceable>5</replaceable>m md<replaceable>1</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+ <para>If the unit number is not specified,
+ <command>mdmfs</command> will automatically select an unused
+ memory device. For more details about
+ <command>mdmfs</command>, refer to &man.mdmfs.8;.</para>
</sect2>
</sect1>
<sect1 xml:id="snapshots">
- <info><title>File System Snapshots</title>
+ <info>
+ <title>File System Snapshots</title>
+
<authorgroup>
- <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
</authorgroup>
-
</info>
-
-
<indexterm>
<primary>file systems</primary>
<secondary>snapshots</secondary>
</indexterm>
- <para>FreeBSD offers a feature in conjunction with
- <link linkend="soft-updates">Soft Updates</link>: File system snapshots.</para>
-
- <para>Snapshots allow a user to create images of specified file
- systems, and treat them as a file.
- Snapshot files must be created in the file system that the
- action is performed on, and a user may create no more than 20
- snapshots per file system. Active snapshots are recorded
- in the superblock so they are persistent across unmount and
- remount operations along with system reboots. When a snapshot
- is no longer required, it can be removed with the standard &man.rm.1;
- command. Snapshots may be removed in any order,
- however all the used space may not be acquired because another snapshot will
- possibly claim some of the released blocks.</para>
-
- <para>The un-alterable <option>snapshot</option> file flag is set
+ <para>&os; offers a feature in conjunction with
+ <link linkend="soft-updates">Soft Updates</link>: file system
+ snapshots.</para>
+
+ <para>UFS snapshots allow a user to create images of specified
+ file systems, and treat them as a file. Snapshot files must be
+ created in the file system that the action is performed on, and
+ a user may create no more than 20 snapshots per file system.
+ Active snapshots are recorded in the superblock so they are
+ persistent across unmount and remount operations along with
+ system reboots. When a snapshot is no longer required, it can
+ be removed using &man.rm.1;. While snapshots may be removed in
+ any order, all the used space may not be acquired because
+ another snapshot will possibly claim some of the released
+ blocks.</para>
+
+ <para>The un-alterable <option>snapshot</option> file flag is set
by &man.mksnap.ffs.8; after initial creation of a snapshot file.
- The &man.unlink.1; command makes an exception for snapshot files
- since it allows them to be removed.</para>
+ &man.unlink.1; makes an exception for snapshot files since it
+ allows them to be removed.</para>
- <para>Snapshots are created with the &man.mount.8; command. To place
- a snapshot of <filename>/var</filename> in the file
- <filename>/var/snapshot/snap</filename> use the following
- command:</para>
+ <para>Snapshots are created using &man.mount.8;. To place a
+ snapshot of <filename>/var</filename> in the
+ file <filename>/var/snapshot/snap</filename>, use the following
+ command:</para>
-<screen>&prompt.root; <userinput>mount -u -o snapshot /var/snapshot/snap /var</userinput></screen>
+ <screen>&prompt.root; <userinput>mount -u -o snapshot /var/snapshot/snap /var</userinput></screen>
- <para>Alternatively, you can use &man.mksnap.ffs.8; to create
- a snapshot:</para>
-<screen>&prompt.root; <userinput>mksnap_ffs /var /var/snapshot/snap</userinput></screen>
+ <para>Alternatively, use &man.mksnap.ffs.8; to create the
+ snapshot:</para>
- <para>One can find snapshot files on a file system (e.g. <filename>/var</filename>)
- by using the &man.find.1; command:</para>
-<screen>&prompt.root; <userinput>find /var -flags snapshot</userinput></screen>
+ <screen>&prompt.root; <userinput>mksnap_ffs /var /var/snapshot/snap</userinput></screen>
- <para>Once a snapshot has been created, it has several
- uses:</para>
+ <para>One can find snapshot files on a file system, such as
+ <filename>/var</filename>, using
+ &man.find.1;:</para>
- <itemizedlist>
- <listitem>
- <para>Some administrators will use a snapshot file for backup purposes,
- because the snapshot can be transfered to CDs or tape.</para>
- </listitem>
+ <screen>&prompt.root; <userinput>find /var -flags snapshot</userinput></screen>
- <listitem>
- <para>File integrity, &man.fsck.8; may be ran on the snapshot.
- Assuming that the file system was clean when it was mounted, you
- should always get a clean (and unchanging) result.
- This is essentially what the
- background &man.fsck.8; process does.</para>
- </listitem>
+ <para>Once a snapshot has been created, it has several
+ uses:</para>
- <listitem>
- <para>Run the &man.dump.8; utility on the snapshot.
- A dump will be returned that is consistent with the
- file system and the timestamp of the snapshot. &man.dump.8;
- can also take a snapshot, create a dump image and then
- remove the snapshot in one command using the
- <option>-L</option> flag.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Some administrators will use a snapshot file for backup
+ purposes, because the snapshot can be transferred to
+ <acronym>CD</acronym>s or tape.</para>
+ </listitem>
- <listitem>
- <para>&man.mount.8; the snapshot as a frozen image of the file system.
- To &man.mount.8; the snapshot
- <filename>/var/snapshot/snap</filename> run:</para>
+ <listitem>
+ <para>The file system integrity checker, &man.fsck.8;, may be
+ run on the snapshot. Assuming that the file system was
+ clean when it was mounted, this should always provide a
+ clean and unchanging result.</para>
+ </listitem>
-<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /var/snapshot/snap -u 4</userinput>
-&prompt.root; <userinput>mount -r /dev/md4 /mnt</userinput></screen>
+ <listitem>
+ <para>Running &man.dump.8; on the snapshot will produce a dump
+ file that is consistent with the file system and the
+ timestamp of the snapshot. &man.dump.8; can also take a
+ snapshot, create a dump image, and then remove the snapshot
+ in one command by using <option>-L</option>.</para>
+ </listitem>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>The snapshot can be mounted as a frozen image of the
+ file system. To &man.mount.8; the snapshot
+ <filename>/var/snapshot/snap</filename> run:</para>
+
+ <screen>&prompt.root; <userinput>mdconfig -a -t vnode -o readonly -f /var/snapshot/snap -u 4</userinput>
+&prompt.root; <userinput>mount -r /dev/md4 /mnt</userinput></screen>
+ </listitem>
+ </itemizedlist>
- <para>You can now walk the hierarchy of your frozen <filename>/var</filename>
- file system mounted at <filename>/mnt</filename>. Everything will
- initially be in the same state it was during the snapshot creation time.
- The only exception is that any earlier snapshots will appear
- as zero length files. When the use of a snapshot has delimited,
- it can be unmounted with:</para>
+ <para>The frozen <filename>/var</filename> is now available
+ through <filename>/mnt</filename>. Everything will initially be
+ in the same state it was during the snapshot creation time. The
+ only exception is that any earlier snapshots will appear as zero
+ length files. To unmount the snapshot, use:</para>
-<screen>&prompt.root; <userinput>umount /mnt</userinput>
+ <screen>&prompt.root; <userinput>umount /mnt</userinput>
&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen>
- <para>For more information about <option>softupdates</option> and
- file system snapshots, including technical papers, you can visit
- Marshall Kirk McKusick's website at
- <uri xlink:href="http://www.mckusick.com/">http://www.mckusick.com/</uri>.</para>
+ <para>For more information about <option>softupdates</option> and
+ file system snapshots, including technical papers, visit
+ Marshall Kirk McKusick's website at <uri
+ xlink:href="http://www.mckusick.com/">http://www.mckusick.com/</uri>.</para>
</sect1>
<sect1 xml:id="quotas">
@@ -3181,92 +2440,109 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on
</sect2>
</sect1>
-
<sect1 xml:id="disks-encrypting">
- <info><title>Encrypting Disk Partitions</title>
+ <info>
+ <title>Encrypting Disk Partitions</title>
+
<authorgroup>
- <author><personname><firstname>Lucky</firstname><surname>Green</surname></personname><contrib>Contributed by </contrib><affiliation>
- <address><email>shamrock@cypherpunks.to</email></address>
- </affiliation></author>
+ <author>
+ <personname>
+ <firstname>Lucky</firstname>
+ <surname>Green</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ <affiliation>
+ <address>
+ <email>shamrock@cypherpunks.to</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
-
</info>
-
<indexterm>
<primary>disks</primary>
- <secondary>encrypting</secondary></indexterm>
-
- <para>FreeBSD offers excellent online protections against
- unauthorized data access. File permissions and Mandatory
- Access Control (MAC) (see <xref linkend="mac"/>) help prevent
- unauthorized third-parties from accessing data while the operating
- system is active and the computer is powered up. However,
- the permissions enforced by the operating system are irrelevant if an
- attacker has physical access to a computer and can simply move
- the computer's hard drive to another system to copy and analyze
- the sensitive data.</para>
-
- <para>Regardless of how an attacker may have come into possession of
- a hard drive or powered-down computer, both <application>GEOM
- Based Disk Encryption (gbde)</application> and
- <command>geli</command> cryptographic subsystems in &os; are able
- to protect the data on the computer's file systems against even
- highly-motivated attackers with significant resources. Unlike
- cumbersome encryption methods that encrypt only individual files,
- <command>gbde</command> and <command>geli</command> transparently
- encrypt entire file systems. No cleartext ever touches the hard
- drive's platter.</para>
-
- <sect2>
- <title>Disk Encryption with <application>gbde</application></title>
-
- <procedure>
- <step>
- <title>Become <systemitem class="username">root</systemitem></title>
-
- <para>Configuring <application>gbde</application> requires
- super-user privileges.</para>
-
- <screen>&prompt.user; <userinput>su -</userinput>
-Password:</screen>
- </step>
+ <secondary>encrypting</secondary>
+ </indexterm>
- <step>
- <title>Add &man.gbde.4; Support to the Kernel Configuration File</title>
+ <para>&os; offers excellent online protections against
+ unauthorized data access. File permissions and <link
+ linkend="mac">Mandatory Access Control</link> (MAC) help
+ prevent unauthorized users from accessing data while the
+ operating system is active and the computer is powered up.
+ However, the permissions enforced by the operating system are
+ irrelevant if an attacker has physical access to a computer and
+ can move the computer's hard drive to another system to copy and
+ analyze the data.</para>
+
+ <para>Regardless of how an attacker may have come into possession
+ of a hard drive or powered-down computer, the
+ <acronym>GEOM</acronym>-based cryptographic subsystems built
+ into &os; are able to protect the data on the computer's file
+ systems against even highly-motivated attackers with significant
+ resources. Unlike encryption methods that encrypt individual
+ files, the built-in <command>gbde</command> and
+ <command>geli</command> utilities can be used to transparently
+ encrypt entire file systems. No cleartext ever touches the hard
+ drive's platter.</para>
- <para>Add the following line to the kernel configuration
- file:</para>
+ <para>This chapter demonstrates how to create an encrypted file
+ system on &os;. It first demonstrates the process using
+ <command>gbde</command> and then demonstrates the same example
+ using <command>geli</command>.</para>
- <para><literal>options GEOM_BDE</literal></para>
+ <sect2>
+ <title>Disk Encryption with
+ <application>gbde</application></title>
+
+ <para>The objective of the &man.gbde.4; facility is to provide a
+ formidable challenge for an attacker to gain access to the
+ contents of a <emphasis>cold</emphasis> storage device.
+ However, if the computer is compromised while up and running
+ and the storage device is actively attached, or the attacker
+ has access to a valid passphrase, it offers no protection to
+ the contents of the storage device. Thus, it is important to
+ provide physical security while the system is running and to
+ protect the passphrase used by the encryption
+ mechanism.</para>
+
+ <para>This facility provides several barriers to protect the
+ data stored in each disk sector. It encrypts the contents of
+ a disk sector using 128-bit <acronym>AES</acronym> in
+ <acronym>CBC</acronym> mode. Each sector on the disk is
+ encrypted with a different <acronym>AES</acronym> key. For
+ more information on the cryptographic design, including how
+ the sector keys are derived from the user-supplied passphrase,
+ refer to &man.gbde.4;.</para>
+
+ <para>&os; provides a kernel module for
+ <application>gbde</application> which can be loaded with this
+ command:</para>
- <para>Rebuild the kernel as described in <xref linkend="kernelconfig"/>.</para>
+ <screen>&prompt.root; <userinput>kldload geom_bde</userinput></screen>
- <para>Reboot into the new kernel.</para>
- </step>
- </procedure>
+ <para>If using a custom kernel configuration file, ensure it
+ contains this line:</para>
- <sect3>
- <title>Preparing the Encrypted Hard Drive</title>
+ <para><literal>options GEOM_BDE</literal></para>
- <para>The following example assumes that you are adding a new hard
- drive to your system that will hold a single encrypted partition.
- This partition will be mounted as <filename>/private</filename>.
- <application>gbde</application> can also be used to encrypt
- <filename>/home</filename> and <filename>/var/mail</filename>, but
- this requires more complex instructions which exceed the scope of
- this introduction.</para>
+ <para>The following example demonstrates adding a new hard drive
+ to a system that will hold a single encrypted partition that
+ will be mounted as <filename>/private</filename>.</para>
<procedure>
+ <title>Encrypting a Partition with
+ <application>gbde</application></title>
+
<step>
<title>Add the New Hard Drive</title>
- <para>Install the new drive to the system as explained in <xref linkend="disks-adding"/>. For the purposes of this example,
- a new hard drive partition has been added as
- <filename>/dev/ad4s1c</filename>. The
- <filename>/dev/ad0s1*</filename>
- devices represent existing standard FreeBSD partitions on
- the example system.</para>
+ <para>Install the new drive to the system as explained in
+ <xref linkend="disks-adding"/>. For the purposes of this
+ example, a new hard drive partition has been added as
+ <filename>/dev/ad4s1c</filename> and
+ <filename>/dev/ad0s1<replaceable>*</replaceable></filename>
+ represents the existing standard &os; partitions.</para>
<screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1
@@ -3275,81 +2551,78 @@ Password:</screen>
</step>
<step>
- <title>Create a Directory to Hold gbde Lock Files</title>
+ <title>Create a Directory to Hold <command>gbde</command>
+ Lock Files</title>
<screen>&prompt.root; <userinput>mkdir /etc/gbde</userinput></screen>
- <para>The <application>gbde</application> lock file contains
- information that <application>gbde</application> requires to
- access encrypted partitions. Without access to the lock file,
- <application>gbde</application> will not be able to decrypt
- the data contained in the encrypted partition without
- significant manual intervention which is not supported by the
- software. Each encrypted partition uses a separate lock
- file.</para>
+ <para>The <application>gbde</application> lock file
+ contains information that <application>gbde</application>
+ requires to access encrypted partitions. Without access
+ to the lock file, <application>gbde</application> will not
+ be able to decrypt the data contained in the encrypted
+ partition without significant manual intervention which is
+ not supported by the software. Each encrypted partition
+ uses a separate lock file.</para>
</step>
<step>
- <title>Initialize the gbde Partition</title>
+ <title>Initialize the <command>gbde</command>
+ Partition</title>
<para>A <application>gbde</application> partition must be
- initialized before it can be used. This initialization needs to
- be performed only once:</para>
-
- <screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c</userinput></screen>
-
- <para>&man.gbde.8; will open your editor, permitting you to set
- various configuration options in a template. For use with UFS1
- or UFS2, set the sector_size to 2048:</para>
-
- <programlisting>$<!-- This is not the space you are looking
-for-->FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/20 11:16:13 phk Exp $
+ initialized before it can be used. This initialization
+ needs to be performed only once. This command will open
+ the default editor, in order to set various configuration
+ options in a template. For use with the
+ <acronym>UFS</acronym> file system, set the sector_size to
+ 2048:</para>
+
+ <screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c.lock</userinput># &dollar;FreeBSD: src/sbin/gbde/template.txt,v 1.1.36.1 2009/08/03 08:13:06 kensmith Exp $
#
# Sector size is the smallest unit of data which can be read or written.
# Making it too small decreases performance and decreases available space.
# Making it too large may prevent filesystems from working. 512 is the
# minimum and always safe. For UFS, use the fragment size
#
-sector_size = 2048
-[...]
-</programlisting>
-
- <para>&man.gbde.8; will ask you twice to type the passphrase that
- should be used to secure the data. The passphrase must be the
- same both times. <application>gbde</application>'s ability to
- protect your data depends entirely on the quality of the
- passphrase that you choose.
- <footnote>
- <para>For tips on how to select a secure passphrase that is easy
- to remember, see the <link xlink:href="http://world.std.com/~reinhold/diceware.html">Diceware
- Passphrase</link> website.</para></footnote></para>
-
- <para>The <command>gbde init</command> command creates a lock
- file for your <application>gbde</application> partition that in
- this example is stored as
- <filename>/etc/gbde/ad4s1c</filename>.</para>
+sector_size = 2048
+[...]</screen>
+
+ <para>Once the edit is saved, the user will be asked twice
+ to type the passphrase used to secure the data. The
+ passphrase must be the same both times. The ability of
+ <application>gbde</application> to protect data depends
+ entirely on the quality of the passphrase. For tips on
+ how to select a secure passphrase that is easy to
+ remember, see <link
+ xlink:href="http://world.std.com/~reinhold/diceware.html">http://world.std.com/~reinhold/diceware.htm</link>.</para>
+
+ <para>This initialization creates a lock file for the
+ <application>gbde</application> partition. In this
+ example, it is stored as
+ <filename>/etc/gbde/ad4s1c.lock</filename>. Lock files
+ must end in <quote>.lock</quote> in order to be correctly
+ detected by the <filename>/etc/rc.d/gbde</filename> start
+ up script.</para>
<caution>
- <para><application>gbde</application> lock files
- <emphasis>must</emphasis> be backed up together with the
- contents of any encrypted partitions. While deleting a lock
- file alone cannot prevent a determined attacker from
- decrypting a <application>gbde</application> partition,
- without the lock file, the legitimate owner will be unable
- to access the data on the encrypted partition without a
- significant amount of work that is totally unsupported by
- &man.gbde.8; and its designer.</para>
+ <para>Lock files <emphasis>must</emphasis> be backed up
+ together with the contents of any encrypted partitions.
+ Without the lock file, the legitimate owner will be
+ unable to access the data on the encrypted
+ partition.</para>
</caution>
</step>
<step>
- <title>Attach the Encrypted Partition to the Kernel</title>
+ <title>Attach the Encrypted Partition to the
+ Kernel</title>
- <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</userinput></screen>
+ <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen>
- <para> You will be asked to provide the passphrase that you
- selected during the initialization of the encrypted partition.
- The new encrypted device will show up in
+ <para>This command will prompt to input the passphrase that
+ was selected during the initialization of the encrypted
+ partition. The new encrypted device will appear in
<filename>/dev</filename> as
<filename>/dev/device_name.bde</filename>:</para>
@@ -3360,43 +2633,36 @@ sector_size = 2048
</step>
<step>
- <title>Create a File System on the Encrypted Device</title>
-
- <para>Once the encrypted device has been attached to the kernel,
- you can create a file system on the device. To create a file
- system on the encrypted device, use &man.newfs.8;. Since it is
- much faster to initialize a new UFS2 file system than it is to
- initialize the old UFS1 file system, using &man.newfs.8; with
- the <option>-O2</option> option is recommended.</para>
-
- <screen>&prompt.root; <userinput>newfs -U -O2 /dev/ad4s1c.bde</userinput></screen>
-
- <note>
- <para>The &man.newfs.8; command must be performed on an
- attached <application>gbde</application> partition which
- is identified by a
- <filename>*.bde</filename>
- extension to the device name.</para>
- </note>
+ <title>Create a File System on the Encrypted
+ Device</title>
+
+ <para>Once the encrypted device has been attached to the
+ kernel, a file system can be created on the device. This
+ example creates a <acronym>UFS</acronym> file system with
+ soft updates enabled. Be sure to specify the partition
+ which has a
+ <filename><replaceable>*</replaceable>.bde</filename>
+ extension:</para>
+
+ <screen>&prompt.root; <userinput>newfs -U /dev/ad4s1c.bde</userinput></screen>
</step>
<step>
<title>Mount the Encrypted Partition</title>
- <para>Create a mount point for the encrypted file system.</para>
-
- <screen>&prompt.root; <userinput>mkdir /private</userinput></screen>
-
- <para>Mount the encrypted file system.</para>
+ <para>Create a mount point and mount the encrypted file
+ system:</para>
- <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
+ <screen>&prompt.root; <userinput>mkdir /private</userinput>
+&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
</step>
<step>
- <title>Verify That the Encrypted File System is Available</title>
+ <title>Verify That the Encrypted File System is
+ Available</title>
- <para>The encrypted file system should now be visible to
- &man.df.1; and be available for use.</para>
+ <para>The encrypted file system should now be visible and
+ available for use:</para>
<screen>&prompt.user; <userinput>df -H</userinput>
Filesystem Size Used Avail Capacity Mounted on
@@ -3408,251 +2674,195 @@ Filesystem Size Used Avail Capacity Mounted on
/dev/ad4s1c.bde 150G 4.1K 138G 0% /private</screen>
</step>
</procedure>
- </sect3>
-
- <sect3>
- <title>Mounting Existing Encrypted File Systems</title>
<para>After each boot, any encrypted file systems must be
- re-attached to the kernel, checked for errors, and mounted, before
- the file systems can be used. The required commands must be
- executed as user <systemitem class="username">root</systemitem>.</para>
+ manually re-attached to the kernel, checked for errors, and
+ mounted, before the file systems can be used. To configure
+ these steps, add the following lines to
+ <filename>/etc/rc.conf</filename>:</para>
- <procedure>
- <step>
- <title>Attach the gbde Partition to the Kernel</title>
+ <programlisting>gbde_autoattach_all="YES"
+gbde_devices="<replaceable>ad4s1c</replaceable>"
+gbde_lockdir="/etc/gbde"</programlisting>
- <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</userinput></screen>
+ <para>This requires that the passphrase be entered at the
+ console at boot time. After typing the correct passphrase,
+ the encrypted partition will be mounted automatically.
+ Additional <application>gbde</application> boot options are
+ available and listed in &man.rc.conf.5;.</para>
- <para>You will be asked to provide the passphrase that you
- selected during initialization of the encrypted
- <application>gbde</application> partition.</para>
- </step>
-
- <step>
- <title>Check the File System for Errors</title>
-
- <para>Since encrypted file systems cannot yet be listed in
- <filename>/etc/fstab</filename> for automatic mounting, the
- file systems must be checked for errors by running &man.fsck.8;
- manually before mounting.</para>
-
- <screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput></screen>
- </step>
-
- <step>
- <title>Mount the Encrypted File System</title>
-
- <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
-
- <para>The encrypted file system is now available for use.</para>
- </step>
- </procedure>
-
- <sect4>
- <title>Automatically Mounting Encrypted Partitions</title>
-
- <para>It is possible to create a script to automatically attach,
- check, and mount an encrypted partition, but for security reasons
- the script should not contain the &man.gbde.8; password. Instead,
- it is recommended that such scripts be run manually while
- providing the password via the console or &man.ssh.1;.</para>
-
- <para>As of &os; 5.2-RELEASE, there is a new <filename>rc.d</filename> script
- provided. Arguments for this script can be passed via
- &man.rc.conf.5;, for example:</para>
-
- <screen>gbde_autoattach_all="YES"
-gbde_devices="ad4s1c"</screen>
-
- <para>This will require that the <application>gbde</application>
- passphrase be entered at boot time. After typing the correct
- passphrase, the <application>gbde</application> encrypted
- partition will be mounted automatically. This can be very
- useful when using <application>gbde</application> on
- notebooks.</para>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Cryptographic Protections Employed by gbde</title>
-
- <para>&man.gbde.8; encrypts the sector payload using 128-bit AES in
- CBC mode. Each sector on the disk is encrypted with a different
- AES key. For more information on <application>gbde</application>'s
- cryptographic design, including how the sector keys are derived
- from the user-supplied passphrase, see &man.gbde.4;.</para>
- </sect3>
-
- <sect3>
- <title>Compatibility Issues</title>
-
- <para>&man.sysinstall.8; is incompatible with
- <application>gbde</application>-encrypted devices. All
+<!--
+What about bsdinstall?
+-->
+ <note>
+ <para><application>sysinstall</application> is incompatible
+ with <application>gbde</application>-encrypted devices. All
<filename>*.bde</filename> devices must be detached from the
- kernel before starting &man.sysinstall.8; or it will crash during
- its initial probing for devices. To detach the encrypted device
- used in our example, use the following command:</para>
- <screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput></screen>
-
- <para>Also note that, as &man.vinum.4; does not use the
- &man.geom.4; subsystem, you cannot use
- <application>gbde</application> with
- <application>vinum</application> volumes.</para>
- </sect3>
+ kernel before starting <application>sysinstall</application>
+ or it will crash during its initial probing for devices. To
+ detach the encrypted device used in the example, use the
+ following command:</para>
+ <screen>&prompt.root; <userinput>gbde detach /dev/<replaceable>ad4s1c</replaceable></userinput></screen>
+ </note>
</sect2>
- <sect2>
- <info><title>Disk Encryption with <command>geli</command></title>
+ <sect2 xml:id="disks-encrypting-geli">
+ <info>
+ <title>Disk Encryption with <command>geli</command></title>
+
<authorgroup>
- <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Daniel</firstname>
+ <surname>Gerzo</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
</authorgroup>
-
</info>
-
-
- <para>A new cryptographic GEOM class is available as of &os; 6.0 -
- <command>geli</command>. It is currently being developed by
- &a.pjd;. <command>Geli</command> is different to
- <command>gbde</command>; it offers different features and uses
- a different scheme for doing cryptographic work.</para>
-
- <para>The most important features of &man.geli.8; are:</para>
+ <para>An alternative cryptographic <acronym>GEOM</acronym> class
+ is available using <command>geli</command>. This control
+ utility adds some features and uses a different scheme for
+ doing cryptographic work. It provides the following
+ features:</para>
<itemizedlist>
<listitem>
- <para>Utilizes the &man.crypto.9; framework &mdash; when
- cryptographic hardware is available, <command>geli</command>
- will use it automatically.</para>
+ <para>Utilizes the &man.crypto.9; framework and
+ automatically uses cryptographic hardware when it is
+ available.</para>
</listitem>
+
<listitem>
- <para>Supports multiple cryptographic algorithms (currently
- AES, Blowfish, and 3DES).</para>
+ <para>Supports multiple cryptographic algorithms such as
+ <acronym>AES</acronym>, Blowfish, and
+ <acronym>3DES</acronym>.</para>
</listitem>
+
<listitem>
<para>Allows the root partition to be encrypted. The
- passphrase used to access the encrypted root partition will
- be requested during the system boot.</para>
+ passphrase used to access the encrypted root partition
+ will be requested during system boot.</para>
</listitem>
+
<listitem>
- <para>Allows the use of two independent keys (e.g. a
- <quote>key</quote> and a <quote>company key</quote>).</para>
+ <para>Allows the use of two independent keys.</para>
</listitem>
+
<listitem>
- <para><command>geli</command> is fast - performs simple
- sector-to-sector encryption.</para>
+ <para>It is fast as it performs simple sector-to-sector
+ encryption.</para>
</listitem>
+
<listitem>
- <para>Allows backup and restore of Master Keys. When a user
- has to destroy his keys, it will be possible to get access
- to the data again by restoring keys from the backup.</para>
+ <para>Allows backup and restore of master keys. If a user
+ destroys their keys, it is still possible to get access to
+ the data by restoring keys from the backup.</para>
</listitem>
+
<listitem>
- <para>Allows to attach a disk with a random, one-time key
- &mdash; useful for swap partitions and temporary file
+ <para>Allows a disk to attach with a random, one-time key
+ which is useful for swap partitions and temporary file
systems.</para>
</listitem>
</itemizedlist>
- <para>More <command>geli</command> features can be found in the
- &man.geli.8; manual page.</para>
-
- <para>The next steps will describe how to enable support for
- <command>geli</command> in the &os; kernel and will explain how
- to create a new <command>geli</command> encryption provider. At
- the end it will be demonstrated how to create an encrypted swap
- partition using features provided by <command>geli</command>.</para>
+ <para>More features and usage examples can be found in
+ &man.geli.8;.</para>
- <para>In order to use <command>geli</command>, you must be running
- &os; 6.0-RELEASE or later. Super-user privileges will be
- required since modifications to the kernel are necessary.</para>
+ <para>The following example describes how to generate a key file
+ which will be used as part of the master key for the encrypted
+ provider mounted under <filename>/private</filename>. The key
+ file will provide some random data used to encrypt the master
+ key. The master key will also be protected by a passphrase.
+ The provider's sector size will be 4kB. The example describes
+ how to attach to the <command>geli</command> provider, create
+ a file system on it, mount it, work with it, and finally, how
+ to detach it.</para>
<procedure>
+ <title>Encrypting a Partition with
+ <command>geli</command></title>
+
<step>
- <title>Adding <command>geli</command> Support to the Kernel
- Configuration File</title>
+ <title>Load <command>geli</command> Support</title>
- <para>Add the following lines to the kernel configuration
- file:</para>
+ <para>Support for <command>geli</command> is available as a
+ loadable kernel module. To configure the system to
+ automatically load the module at boot time, add the
+ following line to
+ <filename>/boot/loader.conf</filename>:</para>
- <screen>options GEOM_ELI
-device crypto</screen>
+ <programlisting>geom_eli_load="YES"</programlisting>
- <para>Rebuild the kernel as described in <xref linkend="kernelconfig"/>.</para>
+ <para>To load the kernel module now:</para>
- <para>Alternatively, the <command>geli</command> module can
- be loaded at boot time. Add the following line to the
- <filename>/boot/loader.conf</filename>:</para>
+ <screen>&prompt.root; <userinput>kldload geom_eli</userinput></screen>
- <para><literal>geom_eli_load="YES"</literal></para>
+ <para>For a custom kernel, ensure the kernel configuration
+ file contains these lines:</para>
- <para>&man.geli.8; should now be supported by the kernel.</para>
+ <programlisting>options GEOM_ELI
+device crypto</programlisting>
</step>
<step>
- <title>Generating the Master Key</title>
-
- <para>The following example will describe how to generate a
- key file, which will be used as part of the Master Key for
- the encrypted provider mounted under
- <filename>/private</filename>. The key
- file will provide some random data used to encrypt the
- Master Key. The Master Key will be protected by a
- passphrase as well. Provider's sector size will be 4kB big.
- Furthermore, the discussion will describe how to attach the
- <command>geli</command> provider, create a file system on
- it, how to mount it, how to work with it, and finally how to
- detach it.</para>
-
- <para>It is recommended to use a bigger sector size (like 4kB) for
- better performance.</para>
-
- <para>The Master Key will be protected with a passphrase and
- the data source for key file will be
- <filename>/dev/random</filename>. The sector size of
- <filename>/dev/da2.eli</filename>, which we call provider,
- will be 4kB.</para>
+ <title>Generate the Master Key</title>
+
+ <para>The following commands generate a master key
+ (<filename>/root/da2.key</filename>) that is protected
+ with a passphrase. The data source for the key file is
+ <filename>/dev/random</filename> and the sector size of
+ the provider (<filename>/dev/da2.eli</filename>) is 4kB as
+ a bigger sector size provides better performance:</para>
<screen>&prompt.root; <userinput>dd if=/dev/random of=/root/da2.key bs=64 count=1</userinput>
&prompt.root; <userinput>geli init -s 4096 -K /root/da2.key /dev/da2</userinput>
Enter new passphrase:
Reenter new passphrase:</screen>
- <para>It is not mandatory that both a passphrase and a key
- file are used; either method of securing the Master Key can
- be used in isolation.</para>
+ <para>It is not mandatory to use both a passphrase and a key
+ file as either method of securing the master key can be
+ used in isolation.</para>
- <para>If key file is given as <quote>-</quote>, standard
- input will be used. This example shows how more than one
- key file can be used.</para>
+ <para>If the key file is given as <quote>-</quote>, standard
+ input will be used. For example, this command generates
+ three key files:</para>
<screen>&prompt.root; <userinput>cat keyfile1 keyfile2 keyfile3 | geli init -K - /dev/da2</userinput></screen>
</step>
<step>
- <title>Attaching the Provider with the generated Key</title>
+ <title>Attach the Provider with the Generated Key</title>
+
+ <para>To attach the provider, specify the key file, the name
+ of the disk, and the passphrase:</para>
<screen>&prompt.root; <userinput>geli attach -k /root/da2.key /dev/da2</userinput>
Enter passphrase:</screen>
- <para>The new plaintext device will be named
- <filename>/dev/da2.eli</filename>.</para>
+ <para>This creates a new device with an
+ <filename>.eli</filename> extension:</para>
<screen>&prompt.root; <userinput>ls /dev/da2*</userinput>
/dev/da2 /dev/da2.eli</screen>
</step>
<step>
- <title>Creating the new File System</title>
+ <title>Create the New File System</title>
+
+ <para>Next, format the device with the
+ <acronym>UFS</acronym> file system and mount it on an
+ existing mount point:</para>
<screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/da2.eli bs=1m</userinput>
&prompt.root; <userinput>newfs /dev/da2.eli</userinput>
-&prompt.root; <userinput>mount /dev/da2.eli /private</userinput></screen>
+&prompt.root; <userinput>mount /dev/da2.eli <replaceable>/private</replaceable></userinput></screen>
- <para>The encrypted file system should be visible to &man.df.1;
- and be available for use now.</para>
+ <para>The encrypted file system should now be available for
+ use:</para>
<screen>&prompt.root; <userinput>df -H</userinput>
Filesystem Size Used Avail Capacity Mounted on
@@ -3662,188 +2872,767 @@ Filesystem Size Used Avail Capacity Mounted on
/dev/ad0s1d 989M 1.5M 909M 0% /tmp
/dev/ad0s1e 3.9G 1.3G 2.3G 35% /var
/dev/da2.eli 150G 4.1K 138G 0% /private</screen>
-
- </step>
-
- <step>
- <title>Unmounting and Detaching the Provider</title>
-
- <para>Once the work on the encrypted partition is done, and
- the <filename>/private</filename> partition
- is no longer needed, it is prudent to consider unmounting
- and detaching the <command>geli</command> encrypted
- partition from the kernel.</para>
-
- <screen>&prompt.root; <userinput>umount /private</userinput>
-&prompt.root; <userinput>geli detach da2.eli</userinput></screen>
</step>
</procedure>
- <para>More information about the use of &man.geli.8; can be
- found in the manual page.</para>
-
- <sect3>
- <title>Encrypting a Swap Partition</title>
-
- <para>The following example demonstrates how to create a
- <command>geli</command> encrypted swap partition.</para>
+ <para>Once the work on the encrypted partition is done, and the
+ <filename>/private</filename> partition is no longer needed,
+ it is prudent to put the device into cold storage by
+ unmounting and detaching the <command>geli</command> encrypted
+ partition from the kernel:</para>
- <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput>
-&prompt.root; <userinput>geli onetime -d -a 3des ad0s1b</userinput>
-&prompt.root; <userinput>swapon /dev/ad0s1b.eli</userinput></screen>
- </sect3>
+ <screen>&prompt.root; <userinput>umount /private</userinput>
+&prompt.root; <userinput>geli detach da2.eli</userinput></screen>
- <sect3>
- <title>Using the <filename>geli</filename> <filename>rc.d</filename> Script</title>
-
- <para><command>geli</command> comes with a <filename>rc.d</filename> script which
- can be used to simplify the usage of <command>geli</command>.
- An example of configuring <command>geli</command> through
- &man.rc.conf.5; follows:</para>
-
- <screen>geli_devices="da2"
-geli_da2_flags="-p -k /root/da2.key"</screen>
-
- <para>This will configure <filename>/dev/da2</filename> as a
- <command>geli</command> provider of which the Master Key file
- is located in <filename>/root/da2.key</filename>, and
- <command>geli</command> will not use a passphrase when
- attaching the provider (note that this can only be used if -P
- was given during the <command>geli</command> init phase). The
- system will detach the <command>geli</command> provider from
- the kernel before the system shuts down.</para>
-
- <para>More information about configuring <filename>rc.d</filename> is provided in the
- <link linkend="configtuning-rcd">rc.d</link> section of the
- Handbook.</para>
- </sect3>
+ <para>A <filename>rc.d</filename> script is provided to
+ simplify the mounting of <command>geli</command>-encrypted
+ devices at boot time. For this example, add these lines to
+ <filename>/etc/rc.conf</filename>:</para>
+
+ <programlisting>geli_devices="<replaceable>da2</replaceable>"
+geli_da2_flags="-p -k /root/<replaceable>da2.key</replaceable>"</programlisting>
+
+ <para>This configures <filename>/dev/da2</filename> as a
+ <command>geli</command> provider with a master key of
+ <filename>/root/da2.key</filename>. The system will
+ automatically detach the provider from the kernel before the
+ system shuts down. During the startup process, the script
+ will prompt for the passphrase before attaching the provider.
+ Other kernel messages might be shown before and after the
+ password prompt. If the boot process seems to stall, look
+ carefully for the password prompt among the other messages.
+ Once the correct passphrase is entered, the provider is
+ attached. The file system is then mounted, typically by an
+ entry in <filename>/etc/fstab</filename>. Refer to <xref
+ linkend="mount-unmount"/> for instructions on how to
+ configure a file system to mount at boot time.</para>
</sect2>
</sect1>
-
<sect1 xml:id="swap-encrypting">
- <info><title>Encrypting Swap Space</title>
+ <info>
+ <title>Encrypting Swap</title>
+
<authorgroup>
- <author><personname><firstname>Christian</firstname><surname>Br&uuml;ffer</surname></personname><contrib>Written by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Christian</firstname>
+ <surname>Br&uuml;ffer</surname>
+ </personname>
+ <contrib>Written by </contrib>
+ </author>
</authorgroup>
</info>
-
<indexterm>
<primary>swap</primary>
<secondary>encrypting</secondary>
</indexterm>
- <para>Swap encryption in &os; is easy to configure and has been
- available since &os; 5.3-RELEASE. Depending on which version
- of &os; is being used, different options are available
- and configuration can vary slightly. From &os; 6.0-RELEASE onwards,
- the &man.gbde.8; or &man.geli.8; encryption systems can be used
- for swap encryption. With earlier versions, only &man.gbde.8; is
- available. Both systems use the <filename>encswap</filename>
- <link linkend="configtuning-rcd">rc.d</link> script.</para>
+ <para>Like the encryption of disk partitions, encryption of swap
+ space is used to protect sensitive information. Consider an
+ application that deals with passwords. As long as these
+ passwords stay in physical memory, they are not written to disk
+ and will be cleared after a reboot. However, if &os; starts
+ swapping out memory pages to free space, the passwords may be
+ written to the disk unencrypted. Encrypting swap space can be a
+ solution for this scenario.</para>
- <para>The previous section, <link linkend="disks-encrypting">Encrypting
- Disk Partitions</link>, includes a short discussion on the different
- encryption systems.</para>
+ <para>This section demonstrates how to configure an encrypted
+ swap partition using &man.gbde.8; or &man.geli.8; encryption.
+ It assumes a <acronym>UFS</acronym> file system where
+ <filename>/dev/ad0s1b</filename> is the swap partition.</para>
<sect2>
- <title>Why should Swap be Encrypted?</title>
-
- <para>Like the encryption of disk partitions, encryption of swap space
- is done to protect sensitive information. Imagine an application
- that e.g. deals with passwords. As long as these passwords stay in
- physical memory, all is well. However, if the operating system starts
- swapping out memory pages to free space for other applications, the
- passwords may be written to the disk platters unencrypted and easy to
- retrieve for an adversary. Encrypting swap space can be a solution for
- this scenario.</para>
- </sect2>
+ <title>Configuring Encrypted Swap</title>
- <sect2>
- <title>Preparation</title>
+ <para>Swap partitions are not encrypted by default and should be
+ cleared of any sensitive data before continuing. To overwrite
+ the current swap partition with random garbage, execute the
+ following command:</para>
- <note>
- <para>For the remainder of this section, <filename>ad0s1b</filename>
- will be the swap partition.</para>
- </note>
+ <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/<replaceable>ad0s1b</replaceable> bs=1m</userinput></screen>
- <para>Up to this point the swap has been unencrypted. It is possible that
- there are already passwords or other sensitive data on the disk platters
- in cleartext. To rectify this, the data on the swap partition should be
- overwritten with random garbage:</para>
+ <para>To encrypt the swap partition using &man.gbde.8;, add the
+ <literal>.bde</literal> suffix to the swap line in
+ <filename>/etc/fstab</filename>:</para>
- <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen>
+ <programlisting># Device Mountpoint FStype Options Dump Pass#
+/dev/ad0s1b.bde none swap sw 0 0</programlisting>
+
+ <para>To instead encrypt the swap partition using &man.geli.8;,
+ use the
+ <literal>.eli</literal> suffix:</para>
+
+ <programlisting># Device Mountpoint FStype Options Dump Pass#
+/dev/ad0s1b.eli none swap sw 0 0</programlisting>
+
+ <para>By default, &man.geli.8; uses the <acronym>AES</acronym>
+ algorithm with a key length of 128 bit. These defaults can be
+ altered by using <literal>geli_swap_flags</literal> in
+ <filename>/etc/rc.conf</filename>. The following flags
+ configure encryption using the Blowfish algorithm with a key
+ length of 128 bits and a sectorsize of 4 kilobytes, and sets
+ <quote>detach on last close</quote>:</para>
+
+ <programlisting>geli_swap_flags="-e blowfish -l 128 -s 4096 -d"</programlisting>
+
+ <para>Refer to the description of <literal>onetime</literal> in
+ &man.geli.8; for a list of possible options.</para>
</sect2>
<sect2>
- <title>Swap Encryption with &man.gbde.8;</title>
+ <title>Encrypted Swap Verification</title>
+
+ <para>Once the system has rebooted, proper operation of the
+ encrypted swap can be verified using
+ <command>swapinfo</command>.</para>
- <para>If &os; 6.0-RELEASE or newer is being used, the
- <literal>.bde</literal> suffix should be added to the device in the
- respective <filename>/etc/fstab</filename> swap line:</para>
+ <para>If &man.gbde.8; is being used:</para>
- <screen>
-# Device Mountpoint FStype Options Dump Pass#
-/dev/ad0s1b.bde none swap sw 0 0
- </screen>
+ <screen>&prompt.user; <userinput>swapinfo</userinput>
+Device 1K-blocks Used Avail Capacity
+/dev/ad0s1b.bde 542720 0 542720 0%</screen>
- <para>For systems prior to &os; 6.0-RELEASE, the following line
- in <filename>/etc/rc.conf</filename> is also needed:</para>
+ <para>If &man.geli.8; is being used:</para>
- <programlisting>gbde_swap_enable="YES"</programlisting>
+ <screen>&prompt.user; <userinput>swapinfo</userinput>
+Device 1K-blocks Used Avail Capacity
+/dev/ad0s1b.eli 542720 0 542720 0%</screen>
</sect2>
+ </sect1>
- <sect2>
- <title>Swap Encryption with &man.geli.8;</title>
+ <sect1 xml:id="disks-hast">
+ <info>
+ <title>Highly Available Storage
+ (<acronym>HAST</acronym>)</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Daniel</firstname>
+ <surname>Gerzo</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Freddie</firstname>
+ <surname>Cash</surname>
+ </personname>
+ <contrib>With inputs from </contrib>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Pawel Jakub</firstname>
+ <surname>Dawidek</surname>
+ </personname>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Michael W.</firstname>
+ <surname>Lucas</surname>
+ </personname>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Viktor</firstname>
+ <surname>Petersson</surname>
+ </personname>
+ </author>
+ </authorgroup>
+ </info>
+
+ <indexterm>
+ <primary>HAST</primary>
+ <secondary>high availability</secondary>
+ </indexterm>
+
+ <para>High availability is one of the main requirements in
+ serious business applications and highly-available storage is a
+ key component in such environments. In &os;, the Highly
+ Available STorage (<acronym>HAST</acronym>) framework allows
+ transparent storage of the same data across several physically
+ separated machines connected by a <acronym>TCP/IP</acronym>
+ network. <acronym>HAST</acronym> can be understood as a
+ network-based RAID1 (mirror), and is similar to the DRBD&reg;
+ storage system used in the GNU/&linux; platform. In combination
+ with other high-availability features of &os; like
+ <acronym>CARP</acronym>, <acronym>HAST</acronym> makes it
+ possible to build a highly-available storage cluster that is
+ resistant to hardware failures.</para>
+
+ <para>The following are the main features of
+ <acronym>HAST</acronym>:</para>
- <para>Alternatively, the procedure for using &man.geli.8; for swap
- encryption is similar to that of using &man.gbde.8;. The
- <literal>.eli</literal> suffix should be added to the device in the
- respective <filename>/etc/fstab</filename> swap line:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Can be used to mask <acronym>I/O</acronym> errors on
+ local hard drives.</para>
+ </listitem>
- <screen>
-# Device Mountpoint FStype Options Dump Pass#
-/dev/ad0s1b.eli none swap sw 0 0
- </screen>
+ <listitem>
+ <para>File system agnostic as it works with any file system
+ supported by &os;.</para>
+ </listitem>
- <para>&man.geli.8; uses the <acronym>AES</acronym> algorithm with
- a key length of 256 bit by default.</para>
+ <listitem>
+ <para>Efficient and quick resynchronization as only the blocks
+ that were modified during the downtime of a node are
+ synchronized.</para>
+ </listitem>
- <para>Optionally, these defaults can be altered using the
- <literal>geli_swap_flags</literal> option in
- <filename>/etc/rc.conf</filename>. The following line tells the
- <filename>encswap</filename> rc.d script to create &man.geli.8; swap
- partitions using the Blowfish algorithm with a key length of 128 bit,
- a sectorsize of 4 kilobytes and the <quote>detach on last close</quote>
- option set:</para>
+ <!--
+ <listitem>
+ <para>Has several synchronization modes to allow for fast
+ failover.</para>
+ </listitem>
+ -->
- <programlisting>geli_swap_flags="-a blowfish -l 128 -s 4096 -d"</programlisting>
+ <listitem>
+ <para>Can be used in an already deployed environment to add
+ additional redundancy.</para>
+ </listitem>
- <para>Please refer to the description of the <command>onetime</command> command
- in the &man.geli.8; manual page for a list of possible options.</para>
+ <listitem>
+ <para>Together with <acronym>CARP</acronym>,
+ <application>Heartbeat</application>, or other tools, it can
+ be used to build a robust and durable storage system.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>After reading this section, you will know:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>What <acronym>HAST</acronym> is, how it works, and
+ which features it provides.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to set up and use <acronym>HAST</acronym> on
+ &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to integrate <acronym>CARP</acronym> and
+ &man.devd.8; to build a robust storage system.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Before reading this section, you should:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Understand &unix; and &os; basics (<xref
+ linkend="basics"/>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Know how to configure network
+ interfaces and other core &os; subsystems (<xref
+ linkend="config-tuning"/>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Have a good understanding of &os;
+ networking (<xref
+ linkend="network-communication"/>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The <acronym>HAST</acronym> project was sponsored by The
+ &os; Foundation with support from <link
+ xlink:href="http://www.omc.net/">http://www.omc.net/</link>
+ and <link
+ xlink:href="http://www.transip.nl/">http://www.transip.nl/</link>.</para>
+
+ <sect2>
+ <title>HAST Operation</title>
+
+ <para><acronym>HAST</acronym> provides synchronous block-level
+ replication between two physical machines: the
+ <emphasis>primary</emphasis>, also known as the
+ <emphasis>master</emphasis> node, and the
+ <emphasis>secondary</emphasis>, or <emphasis>slave</emphasis>
+ node. These two machines together are referred to as a
+ cluster.</para>
+
+ <para>Since <acronym>HAST</acronym> works in a primary-secondary
+ configuration, it allows only one of the cluster nodes to be
+ active at any given time. The primary node, also called
+ <emphasis>active</emphasis>, is the one which will handle all
+ the <acronym>I/O</acronym> requests to
+ <acronym>HAST</acronym>-managed devices. The secondary node
+ is automatically synchronized from the primary node.</para>
+
+ <para>The physical components of the <acronym>HAST</acronym>
+ system are the local disk on primary node, and the disk on the
+ remote, secondary node.</para>
+
+ <para><acronym>HAST</acronym> operates synchronously on a block
+ level, making it transparent to file systems and applications.
+ <acronym>HAST</acronym> provides regular GEOM providers in
+ <filename>/dev/hast/</filename> for use by other tools or
+ applications. There is no difference between using
+ <acronym>HAST</acronym>-provided devices and raw disks or
+ partitions.</para>
+
+ <para>Each write, delete, or flush operation is sent to both the
+ local disk and to the remote disk over
+ <acronym>TCP/IP</acronym>. Each read operation is served from
+ the local disk, unless the local disk is not up-to-date or an
+ <acronym>I/O</acronym> error occurs. In such cases, the read
+ operation is sent to the secondary node.</para>
+
+ <para><acronym>HAST</acronym> tries to provide fast failure
+ recovery. For this reason, it is important to reduce
+ synchronization time after a node's outage. To provide fast
+ synchronization, <acronym>HAST</acronym> manages an on-disk
+ bitmap of dirty extents and only synchronizes those during a
+ regular synchronization, with an exception of the initial
+ sync.</para>
+
+ <para>There are many ways to handle synchronization.
+ <acronym>HAST</acronym> implements several replication modes
+ to handle different synchronization methods:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>memsync</emphasis>: This mode reports a
+ write operation as completed when the local write
+ operation is finished and when the remote node
+ acknowledges data arrival, but before actually storing the
+ data. The data on the remote node will be stored directly
+ after sending the acknowledgement. This mode is intended
+ to reduce latency, but still provides good
+ reliability.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>fullsync</emphasis>: This mode reports a
+ write operation as completed when both the local write and
+ the remote write complete. This is the safest and the
+ slowest replication mode. This mode is the
+ default.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>async</emphasis>: This mode reports a write
+ operation as completed when the local write completes.
+ This is the fastest and the most dangerous replication
+ mode. It should only be used when replicating to a
+ distant node where latency is too high for other
+ modes.</para>
+ </listitem>
+ </itemizedlist>
</sect2>
<sect2>
- <title>Verifying that it Works</title>
+ <title>HAST Configuration</title>
- <para>Once the system has been rebooted, proper operation of the
- encrypted swap can be verified using the
- <command>swapinfo</command> command.</para>
+ <para>The <acronym>HAST</acronym> framework consists of several
+ components:</para>
- <para>If &man.gbde.8; is being used:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The &man.hastd.8; daemon which provides data
+ synchronization. When this daemon is started, it will
+ automatically load <varname>geom_gate.ko</varname>.</para>
+ </listitem>
- <screen>&prompt.user; <userinput>swapinfo</userinput>
-Device 1K-blocks Used Avail Capacity
-/dev/ad0s1b.bde 542720 0 542720 0%
- </screen>
+ <listitem>
+ <para>The userland management utility,
+ &man.hastctl.8;.</para>
+ </listitem>
- <para>If &man.geli.8; is being used:</para>
+ <listitem>
+ <para>The &man.hast.conf.5; configuration file. This file
+ must exist before starting
+ <application>hastd</application>.</para>
+ </listitem>
+ </itemizedlist>
- <screen>&prompt.user; <userinput>swapinfo</userinput>
-Device 1K-blocks Used Avail Capacity
-/dev/ad0s1b.eli 542720 0 542720 0%
- </screen>
+ <para>Users who prefer to statically build
+ <literal>GEOM_GATE</literal> support into the kernel should
+ add this line to the custom kernel configuration file, then
+ rebuild the kernel using the instructions in <xref
+ linkend="kernelconfig"/>:</para>
+
+ <programlisting>options GEOM_GATE</programlisting>
+
+ <para>The following example describes how to configure two nodes
+ in master-slave/primary-secondary operation using
+ <acronym>HAST</acronym> to replicate the data between the two.
+ The nodes will be called <literal>hasta</literal>, with an
+ <acronym>IP</acronym> address of
+ <literal>172.16.0.1</literal>, and <literal>hastb</literal>,
+ with an <acronym>IP</acronym> address of
+ <literal>172.16.0.2</literal>. Both nodes will have a
+ dedicated hard drive <filename>/dev/ad6</filename> of the same
+ size for <acronym>HAST</acronym> operation. The
+ <acronym>HAST</acronym> pool, sometimes referred to as a
+ resource or the <acronym>GEOM</acronym> provider in <filename
+ class="directory">/dev/hast/</filename>, will be called
+ <literal>test</literal>.</para>
+
+ <para>Configuration of <acronym>HAST</acronym> is done using
+ <filename>/etc/hast.conf</filename>. This file should be
+ identical on both nodes. The simplest configuration
+ is:</para>
+
+ <programlisting>resource <replaceable>test</replaceable> {
+ on <replaceable>hasta</replaceable> {
+ local <replaceable>/dev/ad6</replaceable>
+ remote <replaceable>172.16.0.2</replaceable>
+ }
+ on <replaceable>hastb</replaceable> {
+ local <replaceable>/dev/ad6</replaceable>
+ remote <replaceable>172.16.0.1</replaceable>
+ }
+}</programlisting>
+
+ <para>For more advanced configuration, refer to
+ &man.hast.conf.5;.</para>
+
+ <tip>
+ <para>It is also possible to use host names in the
+ <literal>remote</literal> statements if the hosts are
+ resolvable and defined either in
+ <filename>/etc/hosts</filename> or in the local
+ <acronym>DNS</acronym>.</para>
+ </tip>
+
+ <para>Once the configuration exists on both nodes, the
+ <acronym>HAST</acronym> pool can be created. Run these
+ commands on both nodes to place the initial metadata onto the
+ local disk and to start &man.hastd.8;:</para>
+
+ <screen>&prompt.root; <userinput>hastctl create <replaceable>test</replaceable></userinput>
+&prompt.root; <userinput>service hastd onestart</userinput></screen>
+
+ <note>
+ <para>It is <emphasis>not</emphasis> possible to use
+ <acronym>GEOM</acronym>
+ providers with an existing file system or to convert an
+ existing storage to a <acronym>HAST</acronym>-managed pool.
+ This procedure needs to store some metadata on the provider
+ and there will not be enough required space available on an
+ existing provider.</para>
+ </note>
+
+ <para>A HAST node's <literal>primary</literal> or
+ <literal>secondary</literal> role is selected by an
+ administrator, or software like
+ <application>Heartbeat</application>, using &man.hastctl.8;.
+ On the primary node, <literal>hasta</literal>, issue this
+ command:</para>
+
+ <screen>&prompt.root; <userinput>hastctl role primary <replaceable>test</replaceable></userinput></screen>
+
+ <para>Run this command on the secondary node,
+ <literal>hastb</literal>:</para>
+
+ <screen>&prompt.root; <userinput>hastctl role secondary <replaceable>test</replaceable></userinput></screen>
+
+ <para>Verify the result by running <command>hastctl</command> on
+ each node:</para>
+
+ <screen>&prompt.root; <userinput>hastctl status <replaceable>test</replaceable></userinput></screen>
+
+ <para>Check the <literal>status</literal> line in the output.
+ If it says <literal>degraded</literal>, something is wrong
+ with the configuration file. It should say
+ <literal>complete</literal> on each node, meaning that the
+ synchronization between the nodes has started. The
+ synchronization completes when <command>hastctl
+ status</command> reports 0 bytes of <literal>dirty</literal>
+ extents.</para>
+
+ <para>The next step is to create a file system on the
+ <acronym>GEOM</acronym> provider and mount it. This must be
+ done on the <literal>primary</literal> node. Creating the
+ file system can take a few minutes, depending on the size of
+ the hard drive. This example creates a <acronym>UFS</acronym>
+ file system on <filename>/dev/hast/test</filename>:</para>
+
+ <screen>&prompt.root; <userinput>newfs -U /dev/hast/<replaceable>test</replaceable></userinput>
+&prompt.root; <userinput>mkdir /hast/<replaceable>test</replaceable></userinput>
+&prompt.root; <userinput>mount /dev/hast/<replaceable>test</replaceable> <replaceable>/hast/test</replaceable></userinput></screen>
+
+ <para>Once the <acronym>HAST</acronym> framework is configured
+ properly, the final step is to make sure that
+ <acronym>HAST</acronym> is started automatically during
+ system boot. Add this line to
+ <filename>/etc/rc.conf</filename>:</para>
+
+ <programlisting>hastd_enable="YES"</programlisting>
+
+ <sect3>
+ <title>Failover Configuration</title>
+
+ <para>The goal of this example is to build a robust storage
+ system which is resistant to the failure of any given node.
+ If the primary node fails, the secondary node is there to
+ take over seamlessly, check and mount the file system, and
+ continue to work without missing a single bit of
+ data.</para>
+
+ <para>To accomplish this task, the Common Address Redundancy
+ Protocol (<acronym>CARP</acronym>) is used to provide for
+ automatic failover at the <acronym>IP</acronym> layer.
+ <acronym>CARP</acronym> allows multiple hosts on the same
+ network segment to share an <acronym>IP</acronym> address.
+ Set up <acronym>CARP</acronym> on both nodes of the cluster
+ according to the documentation available in <xref
+ linkend="carp"/>. In this example, each node will have
+ its own management <acronym>IP</acronym> address and a
+ shared <acronym>IP</acronym> address of
+ <replaceable>172.16.0.254</replaceable>. The primary
+ <acronym>HAST</acronym> node of the cluster must be the
+ master <acronym>CARP</acronym> node.</para>
+
+ <para>The <acronym>HAST</acronym> pool created in the previous
+ section is now ready to be exported to the other hosts on
+ the network. This can be accomplished by exporting it
+ through <acronym>NFS</acronym> or
+ <application>Samba</application>, using the shared
+ <acronym>IP</acronym> address
+ <replaceable>172.16.0.254</replaceable>. The only problem
+ which remains unresolved is an automatic failover should the
+ primary node fail.</para>
+
+ <para>In the event of <acronym>CARP</acronym> interfaces going
+ up or down, the &os; operating system generates a
+ &man.devd.8; event, making it possible to watch for state
+ changes on the <acronym>CARP</acronym> interfaces. A state
+ change on the <acronym>CARP</acronym> interface is an
+ indication that one of the nodes failed or came back online.
+ These state change events make it possible to run a script
+ which will automatically handle the HAST failover.</para>
+
+ <para>To catch state changes on the
+ <acronym>CARP</acronym> interfaces, add this configuration
+ to <filename>/etc/devd.conf</filename> on each node:</para>
+
+ <programlisting>notify 30 {
+ match "system" "IFNET";
+ match "subsystem" "carp0";
+ match "type" "LINK_UP";
+ action "/usr/local/sbin/carp-hast-switch master";
+};
+
+notify 30 {
+ match "system" "IFNET";
+ match "subsystem" "carp0";
+ match "type" "LINK_DOWN";
+ action "/usr/local/sbin/carp-hast-switch slave";
+};</programlisting>
+
+ <note>
+ <para>If the systems are running &os;&nbsp;10 or higher,
+ replace <filename>carp0</filename> with the name of the
+ <acronym>CARP</acronym>-configured interface.</para>
+ </note>
+
+ <para>Restart &man.devd.8; on both nodes to put the new
+ configuration into effect:</para>
+
+ <screen>&prompt.root; <userinput>service devd restart</userinput></screen>
+
+ <para>When the specified interface state changes by going up
+ or down , the system generates a notification, allowing the
+ &man.devd.8; subsystem to run the specified automatic
+ failover script,
+ <filename>/usr/local/sbin/carp-hast-switch</filename>.
+ For further clarification about this configuration, refer to
+ &man.devd.conf.5;.</para>
+
+ <para>Here is an example of an automated failover
+ script:</para>
+
+ <programlisting>#!/bin/sh
+
+# Original script by Freddie Cash &lt;fjwcash@gmail.com&gt;
+# Modified by Michael W. Lucas &lt;mwlucas@BlackHelicopters.org&gt;
+# and Viktor Petersson &lt;vpetersson@wireload.net&gt;
+
+# The names of the HAST resources, as listed in /etc/hast.conf
+resources="<replaceable>test</replaceable>"
+
+# delay in mounting HAST resource after becoming master
+# make your best guess
+delay=3
+
+# logging
+log="local0.debug"
+name="carp-hast"
+
+# end of user configurable stuff
+
+case "$1" in
+ master)
+ logger -p $log -t $name "Switching to primary provider for ${resources}."
+ sleep ${delay}
+
+ # Wait for any "hastd secondary" processes to stop
+ for disk in ${resources}; do
+ while $( pgrep -lf "hastd: ${disk} \(secondary\)" &gt; /dev/null 2&gt;&amp;1 ); do
+ sleep 1
+ done
+
+ # Switch role for each disk
+ hastctl role primary ${disk}
+ if [ $? -ne 0 ]; then
+ logger -p $log -t $name "Unable to change role to primary for resource ${disk}."
+ exit 1
+ fi
+ done
+
+ # Wait for the /dev/hast/* devices to appear
+ for disk in ${resources}; do
+ for I in $( jot 60 ); do
+ [ -c "/dev/hast/${disk}" ] &amp;&amp; break
+ sleep 0.5
+ done
+
+ if [ ! -c "/dev/hast/${disk}" ]; then
+ logger -p $log -t $name "GEOM provider /dev/hast/${disk} did not appear."
+ exit 1
+ fi
+ done
+
+ logger -p $log -t $name "Role for HAST resources ${resources} switched to primary."
+
+
+ logger -p $log -t $name "Mounting disks."
+ for disk in ${resources}; do
+ mkdir -p /hast/${disk}
+ fsck -p -y -t ufs /dev/hast/${disk}
+ mount /dev/hast/${disk} /hast/${disk}
+ done
+
+ ;;
+
+ slave)
+ logger -p $log -t $name "Switching to secondary provider for ${resources}."
+
+ # Switch roles for the HAST resources
+ for disk in ${resources}; do
+ if ! mount | grep -q "^/dev/hast/${disk} on "
+ then
+ else
+ umount -f /hast/${disk}
+ fi
+ sleep $delay
+ hastctl role secondary ${disk} 2&gt;&amp;1
+ if [ $? -ne 0 ]; then
+ logger -p $log -t $name "Unable to switch role to secondary for resource ${disk}."
+ exit 1
+ fi
+ logger -p $log -t $name "Role switched to secondary for resource ${disk}."
+ done
+ ;;
+esac</programlisting>
+
+ <para>In a nutshell, the script takes these actions when a
+ node becomes master:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Promotes the <acronym>HAST</acronym> pool to
+ primary on the other node.</para>
+ </listitem>
+
+ <listitem>
+ <para>Checks the file system under the
+ <acronym>HAST</acronym> pool.</para>
+ </listitem>
+
+ <listitem>
+ <para>Mounts the pool.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>When a node becomes secondary:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Unmounts the <acronym>HAST</acronym> pool.</para>
+ </listitem>
+
+ <listitem>
+ <para>Degrades the <acronym>HAST</acronym> pool to
+ secondary.</para>
+ </listitem>
+ </itemizedlist>
+
+ <caution>
+ <para>This is just an example script which serves as a proof
+ of concept. It does not handle all the possible scenarios
+ and can be extended or altered in any way, for example, to
+ start or stop required services.</para>
+ </caution>
+
+ <tip>
+ <para>For this example, a standard <acronym>UFS</acronym>
+ file system was used. To reduce the time needed for
+ recovery, a journal-enabled <acronym>UFS</acronym> or
+ <acronym>ZFS</acronym> file system can be used
+ instead.</para>
+ </tip>
+
+ <para>More detailed information with additional examples can
+ be found at <link
+ xlink:href="http://wiki.FreeBSD.org/HAST">http://wiki.FreeBSD.org/HAST</link>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Troubleshooting</title>
+
+ <para><acronym>HAST</acronym> should generally work without
+ issues. However, as with any other software product, there
+ may be times when it does not work as supposed. The sources
+ of the problems may be different, but the rule of thumb is to
+ ensure that the time is synchronized between the nodes of the
+ cluster.</para>
+
+ <para>When troubleshooting <acronym>HAST</acronym>, the
+ debugging level of &man.hastd.8; should be increased by
+ starting <command>hastd</command> with <literal>-d</literal>.
+ This argument may be specified multiple times to further
+ increase the debugging level. Consider also using
+ <literal>-F</literal>, which starts <command>hastd</command>
+ in the foreground.</para>
+
+ <sect3 xml:id="disks-hast-sb">
+ <title>Recovering from the Split-brain Condition</title>
+
+ <para><firstterm>Split-brain</firstterm> occurs when the nodes
+ of the cluster are unable to communicate with each other,
+ and both are configured as primary. This is a dangerous
+ condition because it allows both nodes to make incompatible
+ changes to the data. This problem must be corrected
+ manually by the system administrator.</para>
+
+ <para>The administrator must decide which node has more
+ important changes or merge them manually. Then, let
+ <acronym>HAST</acronym> perform full synchronization of the
+ node which has the broken data. To do this, issue these
+ commands on the node which needs to be
+ resynchronized:</para>
+
+ <screen>&prompt.root; <userinput>hastctl role init <replaceable>test</replaceable></userinput>
+&prompt.root; <userinput>hastctl create <replaceable>test</replaceable></userinput>
+&prompt.root; <userinput>hastctl role secondary <replaceable>test</replaceable></userinput></screen>
+ </sect3>
</sect2>
</sect1>
</chapter>
diff --git a/zh_TW.UTF-8/books/handbook/dtrace/Makefile b/zh_TW.UTF-8/books/handbook/dtrace/Makefile
new file mode 100644
index 0000000000..f766c4c4df
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/dtrace/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= dtrace/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/zh_TW.UTF-8/books/handbook/dtrace/chapter.xml b/zh_TW.UTF-8/books/handbook/dtrace/chapter.xml
new file mode 100644
index 0000000000..cd9348b538
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/dtrace/chapter.xml
@@ -0,0 +1,359 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Recently I suggested to myself that this should become a profiling
+and debugging chapter, which covers things like ktrace(1) and
+using other debugging (like -x in shell scripts). But then I
+realized that, over time and while DTrace becomes better supported,
+that might make this chapter too large.
+-->
+<!--
+ The FreeBSD Documentation Project
+ $FreeBSD$
+-->
+<!-- XXXTR: Should probably put links and resources here. I'm
+ nervous about this chapter as it may require a partial
+ re-write and large modification once DTrace is complete, but
+ at least we can get everyone started ... -->
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="dtrace">
+ <info>
+ <title>&dtrace;</title>
+
+ <authorgroup>
+ <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written
+ by </contrib></author>
+ </authorgroup>
+ </info>
+
+ <sect1 xml:id="dtrace-synopsis">
+ <title>Synopsis</title>
+
+ <indexterm><primary>&dtrace;</primary></indexterm>
+ <indexterm>
+ <primary>&dtrace; support</primary>
+ <see>&dtrace;</see>
+ </indexterm>
+
+ <para>&dtrace;, also known as Dynamic Tracing, was developed by
+ &sun; as a tool for locating performance bottlenecks in
+ production and pre-production systems. In addition to
+ diagnosing performance problems, &dtrace; can be used to help
+ investigate and debug unexpected behavior in both the &os;
+ kernel and in userland programs.</para>
+
+ <para>&dtrace; is a remarkable profiling tool, with an impressive
+ array of features for diagnosing system issues. It may also be
+ used to run pre-written scripts to take advantage of its
+ capabilities. Users can author their own utilities using the
+ &dtrace; D Language, allowing them to customize their profiling
+ based on specific needs.</para>
+
+ <para>The &os; implementation provides full support for kernel
+ &dtrace; and experimental support for userland &dtrace;.
+ Userland &dtrace; allows users to perform function boundary
+ tracing for userland programs using the <literal>pid</literal>
+ provider, and to insert static probes into userland programs for
+ later tracing. Some ports, such as
+ <package>databases/postgres-server</package> and
+ <package>lang/php5</package> have a &dtrace; option to enable
+ static probes. &os; 10.0-RELEASE has reasonably good userland
+ &dtrace; support, but it is not considered production ready. In
+ particular, it is possible to crash traced programs.</para>
+
+ <para>After reading this chapter, you will know:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>What &dtrace; is and what features it provides.</para>
+ </listitem>
+
+ <listitem>
+ <para>Differences between the &solaris; &dtrace;
+ implementation and the one provided by &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to enable and use &dtrace; on &os;.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Before reading this chapter, you should:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Understand &unix; and &os; basics
+ (<xref linkend="basics"/>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Have some familiarity with security and how it pertains
+ to &os; (<xref linkend="security"/>).</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="dtrace-implementation">
+ <title>Implementation Differences</title>
+
+ <para>While the &dtrace; in &os; is similar to that found in
+ &solaris;, differences do exist. The primary difference is that
+ in &os;, &dtrace; is implemented as a set of kernel modules and
+ &dtrace; can not be used until the modules are loaded. To load
+ all of the necessary modules:</para>
+
+ <screen>&prompt.root; <userinput>kldload dtraceall</userinput></screen>
+
+ <para>Beginning with &os; 10.0-RELEASE, the modules are
+ automatically loaded when <command>dtrace</command> is
+ run.</para>
+
+ <para>&os; uses the <literal>DDB_CTF</literal> kernel option to
+ enable support for loading <acronym>CTF</acronym> data from
+ kernel modules and the kernel itself. <acronym>CTF</acronym> is
+ the &solaris; Compact C Type Format which encapsulates a reduced
+ form of debugging information similar to
+ <acronym>DWARF</acronym> and the venerable stabs.
+ <acronym>CTF</acronym> data is added to binaries by the
+ <command>ctfconvert</command> and <command>ctfmerge</command>
+ build tools. The <command>ctfconvert</command> utility parses
+ <acronym>DWARF</acronym> <acronym>ELF</acronym> debug sections
+ created by the compiler and <command>ctfmerge</command> merges
+ <acronym>CTF</acronym> <acronym>ELF</acronym> sections from
+ objects into either executables or shared libraries.</para>
+
+ <para>Some different providers exist for &os; than for &solaris;.
+ Most notable is the <literal>dtmalloc</literal> provider, which
+ allows tracing <function>malloc()</function> by type in the &os;
+ kernel. Some of the providers found in &solaris;, such as
+ <literal>cpc</literal> and <literal>mib</literal>, are not
+ present in &os;. These may appear in future versions of &os;.
+ Moreover, some of the providers available in both operating
+ systems are not compatible, in the sense that their probes have
+ different argument types. Thus, <acronym>D</acronym> scripts
+ written on &solaris; may or may not work unmodified on &os;, and
+ vice versa.</para>
+
+ <para>Due to security differences, only <systemitem
+ class="username">root</systemitem> may use &dtrace; on &os;.
+ &solaris; has a few low level security checks which do not yet
+ exist in &os;. As such, the
+ <filename>/dev/dtrace/dtrace</filename> is strictly limited to
+ <systemitem class="username">root</systemitem>.</para>
+
+ <para>&dtrace; falls under the Common Development and Distribution
+ License (<acronym>CDDL</acronym>) license. To view this license
+ on &os;, see
+ <filename>/usr/src/cddl/contrib/opensolaris/OPENSOLARIS.LICENSE</filename>
+ or view it online at <uri
+ xlink:href="http://opensource.org/licenses/CDDL-1.0">http://opensource.org/licenses/CDDL-1.0</uri>.
+ While a &os; kernel with &dtrace; support is
+ <acronym>BSD</acronym> licensed, the <acronym>CDDL</acronym> is
+ used when the modules are distributed in binary form or the
+ binaries are loaded.</para>
+ </sect1>
+
+ <sect1 xml:id="dtrace-enable">
+ <title>Enabling &dtrace; Support</title>
+
+ <para>In &os; 9.2 and 10.0, &dtrace; support is built into the
+ <filename>GENERIC</filename> kernel. Users of earlier versions
+ of &os; or who prefer to statically compile in &dtrace; support
+ should add the following lines to a custom kernel configuration
+ file and recompile the kernel using the instructions in <xref
+ linkend="kernelconfig"/>:</para>
+
+ <programlisting>options KDTRACE_HOOKS
+options DDB_CTF
+options DEBUG=-g</programlisting>
+
+ <para>Users of the AMD64 architecture should also add this
+ line:</para>
+
+ <programlisting>options KDTRACE_FRAME</programlisting>
+
+ <para>This option provides support for <acronym>FBT</acronym>.
+ While &dtrace; will work without this option, there will be
+ limited support for function boundary tracing.</para>
+
+ <para>Once the &os; system has rebooted into the new kernel, or
+ the &dtrace; kernel modules have been loaded using
+ <command>kldload dtraceall</command>, the system will need
+ support for the Korn shell as the &dtrace;
+ Toolkit has several utilities written in <command>ksh</command>.
+ Make sure that the <package>shells/ksh93</package> package or
+ port is installed. It is also possible to run these tools under
+ <package>shells/pdksh</package> or
+ <package>shells/mksh</package>.</para>
+
+ <para>Finally, install the current &dtrace; Toolkit,
+ a collection of ready-made scripts
+ for collecting system information. There are scripts to check
+ open files, memory, <acronym>CPU</acronym> usage, and a lot
+ more. &os; 10
+ installs a few of these scripts into
+ <filename>/usr/share/dtrace</filename>. On other &os; versions,
+ or to install the full
+ &dtrace; Toolkit, use the
+ <package>sysutils/DTraceToolkit</package> package or
+ port.</para>
+
+ <note>
+ <para>The scripts found in
+ <filename>/usr/share/dtrace</filename> have been specifically
+ ported to &os;. Not all of the scripts found in the &dtrace;
+ Toolkit will work as-is on &os; and some scripts may require
+ some effort in order for them to work on &os;.</para>
+ </note>
+
+ <para>The &dtrace; Toolkit includes many scripts in the special
+ language of &dtrace;. This language is called the D language
+ and it is very similar to C++. An in depth discussion of the
+ language is beyond the scope of this document. It is
+ extensively discussed at <uri
+ xlink:href="http://wikis.oracle.com/display/DTrace/Documentation">http://wikis.oracle.com/display/DTrace/Documentation</uri>.</para>
+ </sect1>
+
+ <sect1 xml:id="dtrace-using">
+ <title>Using &dtrace;</title>
+
+ <para>&dtrace; scripts consist of a list of one or more
+ <firstterm>probes</firstterm>, or instrumentation points, where
+ each probe is associated with an action. Whenever the condition
+ for a probe is met, the associated action is executed. For
+ example, an action may occur when a file is opened, a process is
+ started, or a line of code is executed. The action might be to
+ log some information or to modify context variables. The
+ reading and writing of context variables allows probes to share
+ information and to cooperatively analyze the correlation of
+ different events.</para>
+
+ <para>To view all probes, the administrator can execute the
+ following command:</para>
+
+ <screen>&prompt.root; <userinput>dtrace -l | more</userinput></screen>
+
+ <para>Each probe has an <literal>ID</literal>, a
+ <literal>PROVIDER</literal> (dtrace or fbt), a
+ <literal>MODULE</literal>, and a
+ <literal>FUNCTION NAME</literal>. Refer to &man.dtrace.1; for
+ more information about this command.</para>
+
+ <para>The examples in this section provide an overview of how to
+ use two of the fully supported scripts from the
+ &dtrace; Toolkit: the
+ <filename>hotkernel</filename> and
+ <filename>procsystime</filename> scripts.</para>
+
+ <para>The <filename>hotkernel</filename> script is designed to
+ identify which function is using the most kernel time. It will
+ produce output similar to the following:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/share/dtrace/toolkit</userinput>
+&prompt.root; <userinput>./hotkernel</userinput>
+Sampling... Hit Ctrl-C to end.</screen>
+
+ <para>As instructed, use the
+ <keycombo action="simul"><keycap>Ctrl</keycap><keycap>C</keycap>
+ </keycombo> key combination to stop the process. Upon
+ termination, the script will display a list of kernel functions
+ and timing information, sorting the output in increasing order
+ of time:</para>
+
+ <screen>kernel`_thread_lock_flags 2 0.0%
+0xc1097063 2 0.0%
+kernel`sched_userret 2 0.0%
+kernel`kern_select 2 0.0%
+kernel`generic_copyin 3 0.0%
+kernel`_mtx_assert 3 0.0%
+kernel`vm_fault 3 0.0%
+kernel`sopoll_generic 3 0.0%
+kernel`fixup_filename 4 0.0%
+kernel`_isitmyx 4 0.0%
+kernel`find_instance 4 0.0%
+kernel`_mtx_unlock_flags 5 0.0%
+kernel`syscall 5 0.0%
+kernel`DELAY 5 0.0%
+0xc108a253 6 0.0%
+kernel`witness_lock 7 0.0%
+kernel`read_aux_data_no_wait 7 0.0%
+kernel`Xint0x80_syscall 7 0.0%
+kernel`witness_checkorder 7 0.0%
+kernel`sse2_pagezero 8 0.0%
+kernel`strncmp 9 0.0%
+kernel`spinlock_exit 10 0.0%
+kernel`_mtx_lock_flags 11 0.0%
+kernel`witness_unlock 15 0.0%
+kernel`sched_idletd 137 0.3%
+0xc10981a5 42139 99.3%</screen>
+
+ <!-- XXXTR: I attempted to use objdump and nm on /boot/kernel/kernel
+ to find 0xc10981a5, but to no avail. It would be nice to know
+ how we should look that up. -->
+
+ <para>This script will also work with kernel modules. To use this
+ feature, run the script with <option>-m</option>:</para>
+
+ <screen>&prompt.root; <userinput>./hotkernel -m</userinput>
+Sampling... Hit Ctrl-C to end.
+^C
+MODULE COUNT PCNT
+0xc107882e 1 0.0%
+0xc10e6aa4 1 0.0%
+0xc1076983 1 0.0%
+0xc109708a 1 0.0%
+0xc1075a5d 1 0.0%
+0xc1077325 1 0.0%
+0xc108a245 1 0.0%
+0xc107730d 1 0.0%
+0xc1097063 2 0.0%
+0xc108a253 73 0.0%
+kernel 874 0.4%
+0xc10981a5 213781 99.6%</screen>
+
+ <!-- XXXTR: I was unable to match these up with output from
+ kldstat and kldstat -v and grep. Maybe I'm missing something
+ seriously obvious. It is 5AM btw. -->
+
+ <para>The <filename>procsystime</filename> script captures and
+ prints the system call time usage for a given process
+ <acronym>ID</acronym> (<acronym>PID</acronym>) or process name.
+ In the following example, a new instance of
+ <filename>/bin/csh</filename> was spawned. Then,
+ <filename>procsystime</filename> was executed and remained
+ waiting while a few commands were typed on the other incarnation
+ of <command>csh</command>. These are the results of this
+ test:</para>
+
+ <screen>&prompt.root; <userinput>./procsystime -n csh</userinput>
+Tracing... Hit Ctrl-C to end...
+^C
+
+Elapsed Times for processes csh,
+
+ SYSCALL TIME (ns)
+ getpid 6131
+ sigreturn 8121
+ close 19127
+ fcntl 19959
+ dup 26955
+ setpgid 28070
+ stat 31899
+ setitimer 40938
+ wait4 62717
+ sigaction 67372
+ sigprocmask 119091
+ gettimeofday 183710
+ write 263242
+ execve 492547
+ ioctl 770073
+ vfork 3258923
+ sigsuspend 6985124
+ read 3988049784</screen>
+
+ <para>As shown, the <function>read()</function> system call used
+ the most time in nanoseconds while the
+ <function>getpid()</function> system call used the least amount
+ of time.</para>
+ </sect1>
+</chapter>
diff --git a/zh_TW.UTF-8/books/handbook/eresources/chapter.xml b/zh_TW.UTF-8/books/handbook/eresources/chapter.xml
index a55dab922b..350b1fea65 100644
--- a/zh_TW.UTF-8/books/handbook/eresources/chapter.xml
+++ b/zh_TW.UTF-8/books/handbook/eresources/chapter.xml
@@ -1,12 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The FreeBSD Documentation Project
+ The FreeBSD Traditional Chinese Project
$FreeBSD$
Take translation from Kang-min Liu <gugod@gugod.org>
- Original revision: 1.175
+ Original revision: r46084
-->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="eresources">
+<appendix xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="eresources">
+
<title>網際網路上的資源</title>
<para>進展飛快的 FreeBSD 使得現有的印刷、平面媒體跟不上它的最新進度!
@@ -112,11 +116,6 @@
</row>
<row>
- <entry>&a.policy.name;</entry>
- <entry>FreeBSD Core team 的 policy 方針討論區。這裡文章不多,且只限 core team 才可發言。</entry>
- </row>
-
- <row>
<entry>&a.questions.name;</entry>
<entry>使用問題及技術支援</entry>
</row>
@@ -194,16 +193,6 @@
</row>
<row>
- <entry>&a.audit.name;</entry>
- <entry>Source code 的稽核(audit)計劃</entry>
- </row>
-
- <row>
- <entry>&a.binup.name;</entry>
- <entry>研發 binary 的升級方式</entry>
- </row>
-
- <row>
<entry>&a.bluetooth.name;</entry>
<entry>在 FreeBSD 中使用藍芽(&bluetooth;)技術</entry>
</row>
@@ -214,11 +203,6 @@
</row>
<row>
- <entry>&a.cvsweb.name;</entry>
- <entry>CVSweb 的維護</entry>
- </row>
-
- <row>
<entry>&a.database.name;</entry>
<entry>討論各式資料庫在 FreeBSD 的研發、運用</entry>
</row>
@@ -314,11 +298,6 @@
</row>
<row>
- <entry>&a.libh.name;</entry>
- <entry>新世代的安裝、打包套件機制</entry>
- </row>
-
- <row>
<entry>&a.mips.name;</entry>
<entry>移植 FreeBSD 到 &mips;</entry>
</row>
@@ -349,12 +328,6 @@
</row>
<row>
- <entry>&a.openoffice.name;</entry>
- <entry>移植 <application>OpenOffice.org</application> 及
- <application>&staroffice;</application> 到 FreeBSD</entry>
- </row>
-
- <row>
<entry>&a.performance.name;</entry>
<entry>在高效能/負荷環境下的效能調校(tuning)議題</entry>
</row>
@@ -727,44 +700,6 @@
</varlistentry>
<varlistentry>
- <term>&a.audit.name;</term>
-
- <listitem>
- <para><emphasis>Source code audit project</emphasis></para>
-
- <para>This is the mailing list for the FreeBSD source code
- audit project. Although this was originally intended for
- security-related changes, its charter has been expanded to
- review any code changes.</para>
-
- <para>This list is very heavy on patches, and is probably of no
- interest to the average FreeBSD user. Security discussions
- not related to a particular code change are held on
- freebsd-security. Conversely, all developers are encouraged
- to send their patches here for review, especially if they
- touch a part of the system where a bug may adversely affect
- the integrity of the system.</para>
-
-<!-- I can't actually find a charter for this, but there's this email: http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=223347+225804+/usr/local/www/db/text/2000/cvs-all/20001210.cvs-all -->
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>&a.binup.name;</term>
-
- <listitem>
- <para><emphasis>FreeBSD Binary Update Project</emphasis></para>
-
- <para>This list exists to provide discussion for the binary
- update system, or <application>binup</application>.
- Design issues, implementation details,
- patches, bug reports, status reports, feature requests, commit
- logs, and all other things related to
- <application>binup</application> are fair game.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term>&a.bluetooth.name;</term>
<listitem>
@@ -854,17 +789,6 @@
</varlistentry>
<varlistentry>
- <term>&a.cvsweb.name;</term>
-
- <listitem>
- <para><emphasis>FreeBSD CVSweb Project</emphasis></para>
-
- <para>Technical discussions about use, development and maintenance
- of FreeBSD-CVSweb.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term>&a.doc.name;</term>
<listitem>
@@ -1129,18 +1053,6 @@
</varlistentry>
<varlistentry>
- <term>&a.openoffice.name;</term>
-
- <listitem>
- <para><emphasis>OpenOffice.org</emphasis></para>
-
- <para>Discussions concerning the porting and maintenance
- of <application>OpenOffice.org</application> and
- <application>&staroffice;</application>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term>&a.performance.name;</term>
<listitem>
@@ -1195,17 +1107,6 @@
</varlistentry>
<varlistentry>
- <term>&a.policy.name;</term>
-
- <listitem>
- <para><emphasis>Core team policy decisions</emphasis></para>
-
- <para>This is a low volume, read-only mailing list for FreeBSD
- Core Team Policy decisions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term>&a.ports.name;</term>
<listitem>
diff --git a/zh_TW.UTF-8/books/handbook/filesystems/Makefile b/zh_TW.UTF-8/books/handbook/filesystems/Makefile
new file mode 100644
index 0000000000..81806c414c
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/filesystems/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= filesystems/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/zh_TW.UTF-8/books/handbook/filesystems/chapter.xml b/zh_TW.UTF-8/books/handbook/filesystems/chapter.xml
new file mode 100644
index 0000000000..3454617e38
--- /dev/null
+++ b/zh_TW.UTF-8/books/handbook/filesystems/chapter.xml
@@ -0,0 +1,219 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ 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="filesystems">
+ <info>
+ <title>Other File Systems</title>
+
+ <authorgroup>
+ <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written
+ by </contrib></author>
+ </authorgroup>
+ </info>
+
+ <sect1 xml:id="filesystems-synopsis">
+ <title>Synopsis</title>
+
+ <indexterm><primary>File Systems</primary></indexterm>
+ <indexterm>
+ <primary>File Systems Support</primary>
+ <see>File Systems</see>
+ </indexterm>
+
+ <para>File systems are an integral part of any operating system.
+ They allow users to upload and store files, provide access to
+ data, and make hard drives useful. Different operating systems
+ differ in their native file system. Traditionally, the native
+ &os; file system has been the Unix File System
+ <acronym>UFS</acronym> which has been modernized as
+ <acronym>UFS2</acronym>. Since &os;&nbsp;7.0, the Z File System
+ (<acronym>ZFS</acronym>) is also available as a native file
+ system. See <xref linkend="zfs"/> for more information.</para>
+
+ <para>In addition to its native file systems, &os; supports a
+ multitude of other file systems so that data from other
+ operating systems can be accessed locally, such as data stored
+ on locally attached <acronym>USB</acronym> storage devices,
+ flash drives, and hard disks. This includes support for the
+ &linux; Extended File System (<acronym>EXT</acronym>) and the
+ Reiser file system.</para>
+
+ <para>There are different levels of &os; support for the various
+ file systems. Some require a kernel module to be loaded and
+ others may require a toolset to be installed. Some non-native
+ file system support is full read-write while others are
+ read-only.</para>
+
+ <para>After reading this chapter, you will know:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The difference between native and supported file
+ systems.</para>
+ </listitem>
+
+ <listitem>
+ <para>Which file systems are supported by &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to enable, configure, access, and make use of
+ non-native file systems.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Before reading this chapter, you should:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Understand &unix; and <link
+ linkend="basics">&os; basics</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Be familiar with the basics of <link
+ linkend="kernelconfig">kernel configuration and
+ compilation</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Feel comfortable <link linkend="ports">installing
+ software</link> in &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>Have some familiarity with <link
+ linkend="disks">disks</link>, storage, and device names in
+ &os;.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="filesystems-linux">
+ <title>&linux; File Systems</title>
+
+ <para>&os; provides built-in support for several &linux; file
+ systems. This section demonstrates how to load support for and
+ how to mount the supported &linux; file systems.</para>
+
+ <sect2>
+ <title><acronym>ext2</acronym></title>
+
+ <para>Kernel support for ext2 file systems has
+ been available since &os;&nbsp;2.2. In &os;&nbsp;8.x and
+ earlier, the code is licensed under the
+ <acronym>GPL</acronym>. Since &os;&nbsp;9.0, the code has
+ been rewritten and is now <acronym>BSD</acronym>
+ licensed.</para>
+
+ <para>The &man.ext2fs.5; driver allows the &os; kernel to both
+ read and write to ext2 file systems.</para>
+
+ <note>
+ <para>
+ This driver can also be used to access ext3 and ext4 file
+ systems. However, ext3 journaling, extended attributes, and
+ inodes greater than 128-bytes are not supported. Support
+ for ext4 is read-only.</para>
+ </note>
+
+ <para>To access an ext file system, first
+ load the kernel loadable module:</para>
+
+ <screen>&prompt.root; <userinput>kldload ext2fs</userinput></screen>
+
+ <para>Then, mount the ext volume by specifying its &os;
+ partition name and an existing mount point. This example
+ mounts <filename>/dev/ad1s1</filename> on
+ <filename>/mnt</filename>:</para>
+
+ <screen>&prompt.root; <userinput>mount -t ext2fs <replaceable>/dev/ad1s1</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+ </sect2>
+
+ <sect2>
+ <title>XFS</title>
+
+ <para>A &os; kernel can be configured to provide read-only
+ support for <acronym>XFS</acronym>
+ file systems.</para>
+
+ <para>To compile in <acronym>XFS</acronym> support, add the
+ following option to a custom kernel configuration file and
+ recompile the kernel using the instructions in <xref
+ linkend="kernelconfig"/>:</para>
+
+ <programlisting>options XFS</programlisting>
+
+ <para>Then, to mount an <acronym>XFS</acronym> volume located on
+ <filename>/dev/ad1s1</filename>:</para>
+
+ <screen>&prompt.root; <userinput>mount -t xfs <replaceable>/dev/ad1s1</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+
+ <para>The <package>sysutils/xfsprogs</package> package or
+ port provides additional
+ utilities, with man pages, for using, analyzing, and repairing
+ <acronym>XFS</acronym> file systems.</para>
+ </sect2>
+
+ <sect2>
+ <title>ReiserFS</title>
+
+ <para>&os; provides read-only support for The Reiser file
+ system, ReiserFS.</para>
+
+ <para>To load the &man.reiserfs.5; driver:</para>
+
+ <screen>&prompt.root; <userinput>kldload reiserfs</userinput></screen>
+
+ <para>Then, to mount a ReiserFS volume located on
+ <filename>/dev/ad1s1</filename>:</para>
+
+ <screen>&prompt.root; <userinput>mount -t reiserfs <replaceable>/dev/ad1s1</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+ </sect2>
+ </sect1>
+
+ <!--
+ <sect1>
+ <title>Device File System</title>
+ </sect1>
+
+ <sect1>
+ <title>DOS and NTFS File Systems</title>
+ <para>This is a good section for those who transfer files, using
+ USB devices, from Windows to FreeBSD and vice-versa. My camera,
+ and many other cameras I have seen default to using FAT16. There
+ is (was?) a kde utility, I think called kamera, that could be used
+ to access camera devices. A section on this would be useful.</para>
+
+ <para>XXXTR: Though! The disks chapter, covers a bit of this and
+ devfs under it's USB devices. It leaves a lot to be desired though,
+ see:
+http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/usb-disks.html
+ It may be better to flesh out that section a bit more. Add the
+ word "camera" to it so that others can easily notice.</para>
+ </sect1>
+
+ <sect1>
+ <title>Linux EXT File System</title>
+
+ <para>Probably NOT as useful as the other two, but it requires
+ knowledge of the existence of the tools. Which are hidden in
+ the ports collection. Most Linux guys would probably only use
+ Linux, BSD guys would be smarter and use NFS.</para>
+ </sect1>
+
+ <sect1>
+ <title>HFS</title>
+
+ <para>I think this is the file system used on Apple OSX. There are
+ tools in the ports collection, and with Apple being a big
+ FreeBSD supporter and user of our technologies, surely there
+ is enough cross over to cover this?</para>
+ </sect1>
+ -->
+
+</chapter>
diff --git a/zh_TW.UTF-8/books/handbook/geom/chapter.xml b/zh_TW.UTF-8/books/handbook/geom/chapter.xml
index b8a44254ca..95c0027994 100644
--- a/zh_TW.UTF-8/books/handbook/geom/chapter.xml
+++ b/zh_TW.UTF-8/books/handbook/geom/chapter.xml
@@ -1,20 +1,31 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The FreeBSD Documentation Project
- $FreeBSD$
- Original revision: 1.21
+ The FreeBSD Traditional Chinese Project
+
+ $FreeBSD$
+ Original revision: r46061
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="GEOM">
- <info><title>GEOM: Modular Disk Transformation Framework</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="geom">
+
+ <info>
+ <title>GEOM: Modular Disk Transformation Framework</title>
+
<authorgroup>
- <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Written by </contrib>
+ </author>
</authorgroup>
</info>
-
-
- <sect1 xml:id="GEOM-synopsis">
+ <sect1 xml:id="geom-synopsis">
<title>概述</title>
<indexterm>
@@ -69,25 +80,27 @@
</itemizedlist>
</sect1>
- <sect1 xml:id="GEOM-intro">
- <title>GEOM 導論</title>
-
- <para>GEOM 透過 privoder(即 <filename>/dev/</filename>
- 下的特殊裝置檔案) 來操控 classes(如 Master Boot Records、
- <acronym>BSD</acronym> labels 等) 。GEOM 支援多種軟體
- <acronym>RAID</acronym> 配置,透過 GEOM 存取時,
- 作業系統和應用程式不會意識到 GEOM 存在。</para>
- </sect1>
-
- <sect1 xml:id="GEOM-striping">
- <info><title>RAID0 - 分散連結(striping)</title>
- <authorgroup>
- <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author>
- <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author>
- </authorgroup>
- </info>
-
-
+ <sect1 xml:id="geom-striping">
+ <info>
+ <title>RAID0 - 分散連結(striping)</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Written by </contrib>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Murray</firstname>
+ <surname>Stokely</surname>
+ </personname>
+ </author>
+ </authorgroup>
+ </info>
<indexterm>
<primary>GEOM</primary>
@@ -189,7 +202,7 @@ XXX: What message? Put it inside the screen output above.
</sect1>
- <sect1 xml:id="GEOM-mirror">
+ <sect1 xml:id="geom-mirror">
<title>RAID1 - 鏡射(Mirroring)</title>
<indexterm>
@@ -353,4 +366,855 @@ OK? <userinput>boot</userinput></screen>
</sect3>
</sect2>
</sect1>
+
+ <sect1 xml:id="geom-raid3">
+ <info>
+
+ <title><acronym>RAID</acronym>3 - Byte-level Striping with
+ Dedicated Parity</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Mark</firstname>
+ <surname>Gladman</surname>
+ </personname>
+ <contrib>Written by </contrib>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Daniel</firstname>
+ <surname>Gerzo</surname>
+ </personname>
+ </author>
+ </authorgroup>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Based on documentation by </contrib>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Murray</firstname>
+ <surname>Stokely</surname>
+ </personname>
+ </author>
+ </authorgroup>
+ </info>
+
+ <indexterm>
+ <primary><acronym>GEOM</acronym></primary>
+ </indexterm>
+ <indexterm>
+ <primary>RAID3</primary>
+ </indexterm>
+
+ <para><acronym>RAID</acronym>3 is a method used to combine several
+ disk drives into a single volume with a dedicated parity disk.
+ In a <acronym>RAID</acronym>3 system, data is split up into a
+ number of bytes that are written across all the drives in the
+ array except for one disk which acts as a dedicated parity disk.
+ This means that disk reads from a <acronym>RAID</acronym>3
+ implementation access all disks in the array. Performance can
+ be enhanced by using multiple disk controllers. The
+ <acronym>RAID</acronym>3 array provides a fault tolerance of 1
+ drive, while providing a capacity of 1 - 1/n times the total
+ capacity of all drives in the array, where n is the number of
+ hard drives in the array. Such a configuration is mostly
+ suitable for storing data of larger sizes such as multimedia
+ files.</para>
+
+ <para>At least 3 physical hard drives are required to build a
+ <acronym>RAID</acronym>3 array. Each disk must be of the same
+ size, since <acronym>I/O</acronym> requests are interleaved to
+ read or write to multiple disks in parallel. Also, due to the
+ nature of <acronym>RAID</acronym>3, the number of drives must be
+ equal to 3, 5, 9, 17, and so on, or 2^n + 1.</para>
+
+ <para>This section demonstrates how to create a software
+ <acronym>RAID</acronym>3 on a &os; system.</para>
+
+ <note>
+ <para>While it is theoretically possible to boot from a
+ <acronym>RAID</acronym>3 array on &os;, that configuration is
+ uncommon and is not advised.</para>
+ </note>
+
+ <sect2>
+ <title>Creating a Dedicated <acronym>RAID</acronym>3
+ Array</title>
+
+ <para>In &os;, support for <acronym>RAID</acronym>3 is
+ implemented by the &man.graid3.8; <acronym>GEOM</acronym>
+ class. Creating a dedicated <acronym>RAID</acronym>3 array on
+ &os; requires the following steps.</para>
+
+ <procedure>
+ <step>
+ <para>First, load the <filename>geom_raid3.ko</filename>
+ kernel module by issuing one of the following
+ commands:</para>
+
+ <screen>&prompt.root; <userinput>graid3 load</userinput></screen>
+
+ <para>or:</para>
+
+ <screen>&prompt.root; <userinput>kldload geom_raid3</userinput></screen>
+ </step>
+
+ <step>
+ <para>Ensure that a suitable mount point exists. This
+ command creates a new directory to use as the mount
+ point:</para>
+
+ <screen>&prompt.root; <userinput>mkdir <replaceable>/multimedia</replaceable></userinput></screen>
+ </step>
+
+ <step>
+ <para>Determine the device names for the disks which will be
+ added to the array, and create the new
+ <acronym>RAID</acronym>3 device. The final device listed
+ will act as the dedicated parity disk. This example uses
+ three unpartitioned <acronym>ATA</acronym> drives:
+ <filename><replaceable>ada1</replaceable></filename> and
+ <filename><replaceable>ada2</replaceable></filename> for
+ data, and
+ <filename><replaceable>ada3</replaceable></filename> for
+ parity.</para>
+
+ <screen>&prompt.root; <userinput>graid3 label -v gr0 /dev/ada1 /dev/ada2 /dev/ada3</userinput>
+Metadata value stored on /dev/ada1.
+Metadata value stored on /dev/ada2.
+Metadata value stored on /dev/ada3.
+Done.</screen>
+ </step>
+
+ <step>
+ <para>Partition the newly created <filename>gr0</filename>
+ device and put a <acronym>UFS</acronym> file system on
+ it:</para>
+
+ <screen>&prompt.root; <userinput>gpart create -s GPT /dev/raid3/gr0</userinput>
+&prompt.root; <userinput>gpart add -t freebsd-ufs /dev/raid3/gr0</userinput>
+&prompt.root; <userinput>newfs -j /dev/raid3/gr0p1</userinput></screen>
+
+ <para>Many numbers will glide across the screen, and after a
+ bit of time, the process will be complete. The volume has
+ been created and is ready to be mounted:</para>
+
+ <screen>&prompt.root; <userinput>mount /dev/raid3/gr0p1 /multimedia/</userinput></screen>
+
+ <para>The <acronym>RAID</acronym>3 array is now ready to
+ use.</para>
+ </step>
+ </procedure>
+
+ <para>Additional configuration is needed to retain this setup
+ across system reboots.</para>
+
+ <procedure>
+ <step>
+ <para>The <filename>geom_raid3.ko</filename> module must be
+ loaded before the array can be mounted. To automatically
+ load the kernel module during system initialization, add
+ the following line to
+ <filename>/boot/loader.conf</filename>:</para>
+
+ <programlisting>geom_raid3_load="YES"</programlisting>
+ </step>
+
+ <step>
+ <para>The following volume information must be added to
+ <filename>/etc/fstab</filename> in order to
+ automatically mount the array's file system during the
+ system boot process:</para>
+
+ <programlisting>/dev/raid3/gr0p1 /multimedia ufs rw 2 2</programlisting>
+ </step>
+ </procedure>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="geom-graid">
+ <info>
+ <title>Software <acronym>RAID</acronym> Devices</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Warren</firstname>
+ <surname>Block</surname>
+ </personname>
+ <contrib>Originally contributed by </contrib>
+ </author>
+ </authorgroup>
+ </info>
+
+ <indexterm>
+ <primary><acronym>GEOM</acronym></primary>
+ </indexterm>
+ <indexterm>
+ <primary>Software RAID Devices</primary>
+ <secondary>Hardware-assisted RAID</secondary>
+ </indexterm>
+
+ <para>Some motherboards and expansion cards add some simple
+ hardware, usually just a <acronym>ROM</acronym>, that allows the
+ computer to boot from a <acronym>RAID</acronym> array. After
+ booting, access to the <acronym>RAID</acronym> array is handled
+ by software running on the computer's main processor. This
+ <quote>hardware-assisted software
+ <acronym>RAID</acronym></quote> gives <acronym>RAID</acronym>
+ arrays that are not dependent on any particular operating
+ system, and which are functional even before an operating system
+ is loaded.</para>
+
+ <para>Several levels of <acronym>RAID</acronym> are supported,
+ depending on the hardware in use. See &man.graid.8; for a
+ complete list.</para>
+
+ <para>&man.graid.8; requires the <filename>geom_raid.ko</filename>
+ kernel module, which is included in the
+ <filename>GENERIC</filename> kernel starting with &os;&nbsp;9.1.
+ If needed, it can be loaded manually with
+ <command>graid load</command>.</para>
+
+ <sect2 xml:id="geom-graid-creating">
+ <title>Creating an Array</title>
+
+ <para>Software <acronym>RAID</acronym> devices often have a menu
+ that can be entered by pressing special keys when the computer
+ is booting. The menu can be used to create and delete
+ <acronym>RAID</acronym> arrays. &man.graid.8; can also create
+ arrays directly from the command line.</para>
+
+ <para><command>graid label</command> is used to create a new
+ array. The motherboard used for this example has an Intel
+ software <acronym>RAID</acronym> chipset, so the Intel
+ metadata format is specified. The new array is given a label
+ of <filename>gm0</filename>, it is a mirror
+ (<acronym>RAID1</acronym>), and uses drives
+ <filename>ada0</filename> and
+ <filename>ada1</filename>.</para>
+
+ <caution>
+ <para>Some space on the drives will be overwritten when they
+ are made into a new array. Back up existing data
+ first!</para>
+ </caution>
+
+ <screen>&prompt.root; <userinput>graid label Intel gm0 RAID1 ada0 ada1</userinput>
+GEOM_RAID: Intel-a29ea104: Array Intel-a29ea104 created.
+GEOM_RAID: Intel-a29ea104: Disk ada0 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:0-ada0 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Disk ada1 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Array started.
+GEOM_RAID: Intel-a29ea104: Volume gm0 state changed from STARTING to OPTIMAL.
+Intel-a29ea104 created
+GEOM_RAID: Intel-a29ea104: Provider raid/r0 for volume gm0 created.</screen>
+
+ <para>A status check shows the new mirror is ready for
+ use:</para>
+
+ <screen>&prompt.root; <userinput>graid status</userinput>
+ Name Status Components
+raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE))
+ ada1 (ACTIVE (ACTIVE))</screen>
+
+ <para>The array device appears in
+ <filename>/dev/raid/</filename>. The first array is called
+ <filename>r0</filename>. Additional arrays, if present, will
+ be <filename>r1</filename>, <filename>r2</filename>, and so
+ on.</para>
+
+ <para>The <acronym>BIOS</acronym> menu on some of these devices
+ can create arrays with special characters in their names. To
+ avoid problems with those special characters, arrays are given
+ simple numbered names like <filename>r0</filename>. To show
+ the actual labels, like <filename>gm0</filename> in the
+ example above, use &man.sysctl.8;:</para>
+
+ <screen>&prompt.root; <userinput>sysctl kern.geom.raid.name_format=1</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-volumes">
+ <title>Multiple Volumes</title>
+
+ <para>Some software <acronym>RAID</acronym> devices support
+ more than one <emphasis>volume</emphasis> on an array.
+ Volumes work like partitions, allowing space on the physical
+ drives to be split and used in different ways. For example,
+ Intel software <acronym>RAID</acronym> devices support two
+ volumes. This example creates a 40&nbsp;G mirror for safely
+ storing the operating system, followed by a 20&nbsp;G
+ <acronym>RAID0</acronym> (stripe) volume for fast temporary
+ storage:</para>
+
+ <screen>&prompt.root; <userinput>graid label -S 40G Intel gm0 RAID1 ada0 ada1</userinput>
+&prompt.root; <userinput>graid add -S 20G gm0 RAID0</userinput></screen>
+
+ <para>Volumes appear as additional
+ <filename>r<replaceable>X</replaceable></filename> entries
+ in <filename>/dev/raid/</filename>. An array with two volumes
+ will show <filename>r0</filename> and
+ <filename>r1</filename>.</para>
+
+ <para>See &man.graid.8; for the number of volumes supported by
+ different software <acronym>RAID</acronym> devices.</para>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-converting">
+ <title>Converting a Single Drive to a Mirror</title>
+
+ <para>Under certain specific conditions, it is possible to
+ convert an existing single drive to a &man.graid.8; array
+ without reformatting. To avoid data loss during the
+ conversion, the existing drive must meet these minimum
+ requirements:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The drive must be partitioned with the
+ <acronym>MBR</acronym> partitioning scheme.
+ <acronym>GPT</acronym> or other partitioning schemes with
+ metadata at the end of the drive will be overwritten and
+ corrupted by the &man.graid.8; metadata.</para>
+ </listitem>
+
+ <listitem>
+ <para>There must be enough unpartitioned and unused space at
+ the end of the drive to hold the &man.graid.8; metadata.
+ This metadata varies in size, but the largest occupies
+ 64&nbsp;M, so at least that much free space is
+ recommended.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If the drive meets these requirements, start by making a
+ full backup. Then create a single-drive mirror with that
+ drive:</para>
+
+ <screen>&prompt.root; <userinput>graid label Intel gm0 RAID1 ada0 NONE</userinput></screen>
+
+ <para>&man.graid.8; metadata was written to the end of the drive
+ in the unused space. A second drive can now be inserted into
+ the mirror:</para>
+
+ <screen>&prompt.root; <userinput>graid insert raid/r0 ada1</userinput></screen>
+
+ <para>Data from the original drive will immediately begin to be
+ copied to the second drive. The mirror will operate in
+ degraded status until the copy is complete.</para>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-inserting">
+ <title>Inserting New Drives into the Array</title>
+
+ <para>Drives can be inserted into an array as replacements for
+ drives that have failed or are missing. If there are no
+ failed or missing drives, the new drive becomes a spare. For
+ example, inserting a new drive into a working two-drive mirror
+ results in a two-drive mirror with one spare drive, not a
+ three-drive mirror.</para>
+
+ <para>In the example mirror array, data immediately begins to be
+ copied to the newly-inserted drive. Any existing information
+ on the new drive will be overwritten.</para>
+
+ <screen>&prompt.root; <userinput>graid insert raid/r0 ada1</userinput>
+GEOM_RAID: Intel-a29ea104: Disk ada1 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NONE to NEW.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NEW to REBUILD.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 rebuild start at 0.</screen>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-removing">
+ <title>Removing Drives from the Array</title>
+
+ <para>Individual drives can be permanently removed from a
+ from an array and their metadata erased:</para>
+
+ <screen>&prompt.root; <userinput>graid remove raid/r0 ada1</userinput>
+GEOM_RAID: Intel-a29ea104: Disk ada1 state changed from ACTIVE to OFFLINE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-[unknown] state changed from ACTIVE to NONE.
+GEOM_RAID: Intel-a29ea104: Volume gm0 state changed from OPTIMAL to DEGRADED.</screen>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-stopping">
+ <title>Stopping the Array</title>
+
+ <para>An array can be stopped without removing metadata from the
+ drives. The array will be restarted when the system is
+ booted.</para>
+
+ <screen>&prompt.root; <userinput>graid stop raid/r0</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-status">
+ <title>Checking Array Status</title>
+
+ <para>Array status can be checked at any time. After a drive
+ was added to the mirror in the example above, data is being
+ copied from the original drive to the new drive:</para>
+
+ <screen>&prompt.root; <userinput>graid status</userinput>
+ Name Status Components
+raid/r0 DEGRADED ada0 (ACTIVE (ACTIVE))
+ ada1 (ACTIVE (REBUILD 28%))</screen>
+
+ <para>Some types of arrays, like <literal>RAID0</literal> or
+ <literal>CONCAT</literal>, may not be shown in the status
+ report if disks have failed. To see these partially-failed
+ arrays, add <option>-ga</option>:</para>
+
+ <screen>&prompt.root; <userinput>graid status -ga</userinput>
+ Name Status Components
+Intel-e2d07d9a BROKEN ada6 (ACTIVE (ACTIVE))</screen>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-deleting">
+ <title>Deleting Arrays</title>
+
+ <para>Arrays are destroyed by deleting all of the volumes from
+ them. When the last volume present is deleted, the array is
+ stopped and metadata is removed from the drives:</para>
+
+ <screen>&prompt.root; <userinput>graid delete raid/r0</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="geom-graid-unexpected">
+ <title>Deleting Unexpected Arrays</title>
+
+ <para>Drives may unexpectedly contain &man.graid.8; metadata,
+ either from previous use or manufacturer testing.
+ &man.graid.8; will detect these drives and create an array,
+ interfering with access to the individual drive. To remove
+ the unwanted metadata:</para>
+
+ <procedure>
+ <step>
+ <para>Boot the system. At the boot menu, select
+ <literal>2</literal> for the loader prompt. Enter:</para>
+
+ <screen>OK <userinput>set kern.geom.raid.enable=0</userinput>
+OK <userinput>boot</userinput></screen>
+
+ <para>The system will boot with &man.graid.8;
+ disabled.</para>
+ </step>
+
+ <step>
+ <para>Back up all data on the affected drive.</para>
+ </step>
+
+ <step>
+ <para>As a workaround, &man.graid.8; array detection
+ can be disabled by adding</para>
+
+ <programlisting>kern.geom.raid.enable=0</programlisting>
+
+ <para>to <filename>/boot/loader.conf</filename>.</para>
+
+ <para>To permanently remove the &man.graid.8; metadata
+ from the affected drive, boot a &os; installation
+ <acronym>CD-ROM</acronym> or memory stick, and select
+ <literal>Shell</literal>. Use <command>status</command>
+ to find the name of the array, typically
+ <literal>raid/r0</literal>:</para>
+
+ <screen>&prompt.root; <userinput>graid status</userinput>
+ Name Status Components
+raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE))
+ ada1 (ACTIVE (ACTIVE))</screen>
+
+ <para>Delete the volume by name:</para>
+
+ <screen>&prompt.root; <userinput>graid delete raid/r0</userinput></screen>
+
+ <para>If there is more than one volume shown, repeat the
+ process for each volume. After the last array has been
+ deleted, the volume will be destroyed.</para>
+
+ <para>Reboot and verify data, restoring from backup if
+ necessary. After the metadata has been removed, the
+ <literal>kern.geom.raid.enable=0</literal> entry in
+ <filename>/boot/loader.conf</filename> can also be
+ removed.</para>
+ </step>
+ </procedure>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="geom-ggate">
+ <title><acronym>GEOM</acronym> Gate Network</title>
+
+ <para><acronym>GEOM</acronym> provides a simple mechanism for
+ providing remote access to devices such as disks,
+ <acronym>CD</acronym>s, and file systems through the use of the
+ <acronym>GEOM</acronym> Gate network daemon,
+ <application>ggated</application>. The system with the device
+ runs the server daemon which handles requests made by clients
+ using <application>ggatec</application>. The devices should not
+ contain any sensitive data as the connection between the client
+ and the server is not encrypted.</para>
+
+ <para>Similar to <acronym>NFS</acronym>, which is discussed in
+ <xref linkend="network-nfs"/>, <application>ggated</application>
+ is configured using an exports file. This file specifies which
+ systems are permitted to access the exported resources and what
+ level of access they are offered. For example, to give the
+ client <systemitem class="ipaddress">192.168.1.5</systemitem>
+ read and write access to the fourth slice on the first
+ <acronym>SCSI</acronym> disk, create
+ <filename>/etc/gg.exports</filename> with this line:</para>
+
+ <programlisting>192.168.1.5 RW /dev/da0s4d</programlisting>
+
+ <para>Before exporting the device, ensure it is not currently
+ mounted. Then, start <application>ggated</application>:</para>
+
+ <screen>&prompt.root; <userinput>ggated</userinput></screen>
+
+ <para>Several options are available for specifying an alternate
+ listening port or changing the default location of the exports
+ file. Refer to &man.ggated.8; for details.</para>
+
+ <para>To access the exported device on the client machine, first
+ use <command>ggatec</command> to specify the
+ <acronym>IP</acronym> address of the server and the device name
+ of the exported device. If successful, this command will
+ display a <literal>ggate</literal> device name to mount. Mount
+ that specified device name on a free mount point. This example
+ connects to the <filename>/dev/da0s4d</filename> partition on
+ <literal>192.168.1.1</literal>, then mounts
+ <filename>/dev/ggate0</filename> on
+ <filename>/mnt</filename>:</para>
+
+ <screen>&prompt.root; <userinput>ggatec create -o rw 192.168.1.1 /dev/da0s4d</userinput>
+ggate0
+&prompt.root; <userinput>mount /dev/ggate0 /mnt</userinput></screen>
+
+ <para>The device on the server may now be accessed through
+ <filename>/mnt</filename> on the client. For more details about
+ <command>ggatec</command> and a few usage examples, refer to
+ &man.ggatec.8;.</para>
+
+ <note>
+ <para>The mount will fail if the device is currently mounted on
+ either the server or any other client on the network. If
+ simultaneous access is needed to network resources, use
+ <acronym>NFS</acronym> instead.</para>
+ </note>
+
+ <para>When the device is no longer needed, unmount it with
+ <command>umount</command> so that the resource is available to
+ other clients.</para>
+ </sect1>
+
+ <sect1 xml:id="geom-glabel">
+ <title>Labeling Disk Devices</title>
+
+ <indexterm>
+ <primary><acronym>GEOM</acronym></primary>
+ </indexterm>
+ <indexterm>
+ <primary>Disk Labels</primary>
+ </indexterm>
+
+ <para>During system initialization, the &os; kernel creates
+ device nodes as devices are found. This method of probing for
+ devices raises some issues. For instance, what if a new disk
+ device is added via <acronym>USB</acronym>? It is likely that
+ a flash device may be handed the device name of
+ <filename>da0</filename> and the original
+ <filename>da0</filename> shifted to
+ <filename>da1</filename>. This will cause issues mounting
+ file systems if they are listed in
+ <filename>/etc/fstab</filename> which may also prevent the
+ system from booting.</para>
+
+ <para>One solution is to chain <acronym>SCSI</acronym> devices
+ in order so a new device added to the <acronym>SCSI</acronym>
+ card will be issued unused device numbers. But what about
+ <acronym>USB</acronym> devices which may replace the primary
+ <acronym>SCSI</acronym> disk? This happens because
+ <acronym>USB</acronym> devices are usually probed before the
+ <acronym>SCSI</acronym> card. One solution is to only insert
+ these devices after the system has been booted. Another method
+ is to use only a single <acronym>ATA</acronym> drive and never
+ list the <acronym>SCSI</acronym> devices in
+ <filename>/etc/fstab</filename>.</para>
+
+ <para>A better solution is to use <command>glabel</command> to
+ label the disk devices and use the labels in
+ <filename>/etc/fstab</filename>. Because
+ <command>glabel</command> stores the label in the last sector of
+ a given provider, the label will remain persistent across
+ reboots. By using this label as a device, the file system may
+ always be mounted regardless of what device node it is accessed
+ through.</para>
+
+ <note>
+ <para><command>glabel</command> can create both transient and
+ permanent labels. Only permanent labels are consistent across
+ reboots. Refer to &man.glabel.8; for more information on the
+ differences between labels.</para>
+ </note>
+
+ <sect2>
+ <title>Label Types and Examples</title>
+
+ <para>Permanent labels can be a generic or a file system label.
+ Permanent file system labels can be created with
+ &man.tunefs.8; or &man.newfs.8;. These types of labels are
+ created in a sub-directory of <filename>/dev</filename>, and
+ will be named according to the file system type. For example,
+ <acronym>UFS</acronym>2 file system labels will be created in
+ <filename>/dev/ufs</filename>. Generic permanent labels can
+ be created with <command>glabel label</command>. These are
+ not file system specific and will be created in
+ <filename>/dev/label</filename>.</para>
+
+ <para>Temporary labels are destroyed at the next reboot. These
+ labels are created in <filename>/dev/label</filename> and are
+ suited to experimentation. A temporary label can be created
+ using <command>glabel create</command>.</para>
+
+<!-- XXXTR: How do you create a file system label without running newfs
+ or when there is no newfs (e.g.: cd9660)? -->
+
+ <para>To create a permanent label for a
+ <acronym>UFS</acronym>2 file system w