svn commit: r41895 - head/en_US.ISO8859-1/books/handbook/disks

Warren Block wblock at
Mon Jun 10 16:57:31 UTC 2013

Author: wblock
Date: Mon Jun 10 16:57:30 2013
New Revision: 41895

  Update the Adding Disks section in the Storage chapter.  Use a SATA
  disk device instead of SCSI, use GPT instead of MBR, use gpart instead
  of fdisk/bsdlabel, remove sysinstall example, remove dedicated mode
  example.  The PR below was submitted after an RFC regarding this change
  was posted to the freebsd-doc mailing list, but was entirely relevant.
  PR:		docs/179378
  Submitted by:	Paul Hoffman <phoffman at>
  Reviewed by:	freebsd-doc RFC (no responses after a week)


Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml
--- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml	Mon Jun 10 12:55:29 2013	(r41894)
+++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml	Mon Jun 10 16:57:30 2013	(r41895)
@@ -180,206 +180,66 @@
     <para>This section describes how to add a new
-      <acronym>SCSI</acronym> disk to a machine that currently only
+      <acronym>SATA</acronym> disk to a machine that currently only
       has a single drive.  First, turn off the computer and install
       the drive in the computer following the instructions of the
       computer, controller, and drive manufacturers.  Reboot
       the system and become <username>root</username>.</para>
     <para>Inspect <filename>/var/run/dmesg.boot</filename> to ensure
-      the new disk was found.  In this example, the newly added SCSI
-      drive should appear as <devicename>da1</devicename>.</para>
+      the new disk was found.  In this example, the newly added
+      <acronym>SATA</acronym> drive will appear as
+      <devicename>ada1</devicename>.</para>
-    <indexterm><primary>slices</primary></indexterm>
-      <primary><command>fdisk</command></primary>
+      <primary><command>gpart</command></primary>
-    <para>&os; runs on IBM-PC compatible computers, therefore it
-      must take into account the PC BIOS partitions which are
-      different from the traditional BSD partitions.  A PC disk has up
-      to four BIOS partition entries.  If the disk is going to be
-      truly dedicated to &os;, use <emphasis>dedicated</emphasis>
-      mode.  Otherwise, &os; will have to live within one of the PC
-      BIOS partitions.  &os; calls the PC BIOS partitions
-      <emphasis>slices</emphasis> so as not to confuse them with
-      traditional BSD partitions.  Slices may also be used on a disk
-      that is dedicated to &os;, but used in a computer that also has
-      another operating system installed.  This is a good way to avoid
-      confusing the <command>fdisk</command> utility of non-&os;
-      operating systems.</para>
-    <para>In the slice case, the drive will be added as
-      <filename>/dev/da1s1e</filename>.  This is read as: SCSI disk,
-      unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1),
-      and <filename>e</filename> BSD partition.  In the dedicated
-      case, the drive will be added as
-      <filename>/dev/da1e</filename>.</para>
-    <para>Due to the use of 32-bit integers to store the number of
-      sectors, &man.bsdlabel.8; is limited to 2^32-1 sectors per disk,
-      or 2TB in most cases.  The &man.fdisk.8; format allows a
-      starting sector of no more than 2^32-1 and a length of no more
-      than 2^32-1, limiting partitions to 2TB and disks to 4TB, in
-      most cases.  The &man.sunlabel.8; format is limited to 2^32-1
-      sectors per partition and 8 partitions for a total of 16TB.  For
-      larger disks, &man.gpart.8; may be used to create
-      <acronym>GPT</acronym> partitions.  <acronym>GPT</acronym> has
-      the added benefit of not being limited to 4 slices.</para>
+    <para>For this example, a single large partition will be created
+      on the new disk.  The <ulink
+	url="">
+	<acronym>GPT</acronym></ulink> partitioning scheme will be
+      used in preference to the older and less versatile
+      <acronym>MBR</acronym> scheme.</para>
-    <sect2>
-      <title>Using &man.sysinstall.8;</title>
-      <indexterm>
-	<primary><application>sysinstall</application></primary>
-	<secondary>adding disks</secondary>
-      </indexterm>
-      <indexterm>
-	<primary>su</primary>
-      </indexterm>
-      <procedure>
-	<step>
-	  <title>Navigating
-	    <application>sysinstall</application></title>
-	  <para><command>sysinstall</command> can be used to partition
-	    and label a new disk using its easy-to-use menus.  As
-	    <username>root</username>, run
-	    <command>sysinstall</command> and enter the
-	    <literal>Configure</literal> menu.  Within the
-	    <literal>&os; Configuration Menu</literal>, scroll down
-	    and select the <literal>Fdisk</literal> option.</para>
-	</step>
-	<step>
-	  <title><application>fdisk</application> Partition
-	    Editor</title>
-	  <para>Once inside <application>fdisk</application>, pressing
-	    <keycap>A</keycap> will use the entire disk for &os;.
-	    When asked whether to <quote>remain cooperative with
-	      any future possible operating systems</quote>, answer
-	    <literal>YES</literal>.  Write the changes to the disk
-	    using <keycap>W</keycap>.  Exit the fdisk editor by
-	    pressing <keycap>Q</keycap> which will prompt about
-	    the <quote>Master Boot Record</quote>.  Since the disk is
-	    being added to an already running system, choose
-	    <literal>None</literal>.</para>
-	</step>
-	<step>
-	  <title>Disk Label Editor</title>
-	  <indexterm><primary>BSD partitions</primary></indexterm>
+    <note>
+      <para>If the disk to be added is not blank, old partition
+	information can be removed with
+	<command>gpart delete</command>.  See &man.gpart.8; for
+	details.</para>
+    </note>
-	  <para>Next, exit <application>sysinstall</application> and
-	    start it again.  Follow the directions above, except this
-	    time choose the <literal>Label</literal> option.  This
-	    will enter the <literal>Disk Label Editor</literal>.  This
-	    editor is used to create traditional BSD partitions.  A
-	    disk can have up to eight partitions, labeled
-	    <literal>a-h</literal>.  A few of the partition labels
-	    have special uses.  The <literal>a</literal> partition is
-	    used for the root partition (<filename
-	      class="directory">/</filename>).  Only the disk the
-	    system boots from should have an <literal>a</literal>
-	    partition.  The <literal>b</literal> partition is used for
-	    swap partitions, and there can be many disks with swap
-	    partitions.  The <literal>c</literal> partition addresses
-	    the entire disk in dedicated mode, or the entire &os;
-	    slice in slice mode.  The other partitions are for general
-	    use.</para>
-	  <para>The label editor in
-	    <application>sysinstall</application> favors the
-	    <literal>e</literal> partition for non-root, non-swap
-	    partitions.  Within the label editor, create a single file
-	    system by pressing <keycap>C</keycap>.  When prompted if
-	    this will be a FS (file system) or swap, choose
-	    <literal>FS</literal> and type in a mount point such as
-	    <filename class="directory">/mnt</filename>).  When adding
-	    a disk in post-install mode,
-	    <application>sysinstall</application> will not create
-	    entries in <filename>/etc/fstab</filename>, so the mount
-	    point you specify is not important.</para>
-	  <para>Press <keycap>W</keycap> to write the new label to the
-	    disk and create a file system on it.  Ignore any errors
-	    from <application>sysinstall</application> indicating that
-	    it could not mount the new partition.  Exit the label
-	    editor then <application>sysinstall</application>
-	    completely.</para>
-	</step>
+    <para>The partition scheme is created, and then a single partition
+      is added:</para>
-	<step>
-	  <title>Finish</title>
+    <screen>&prompt.root; <userinput>gpart create -s GPT ada1</userinput>
+&prompt.root; <userinput>gpart add -t freebsd-ufs ada1</userinput></screen>
-	  <para>The last step is to edit
-	    <filename>/etc/fstab</filename> to add an entry for your
-	    new disk.</para>
-	</step>
-      </procedure>
-    </sect2>
+    <para>Depending on use, several smaller partitions may be desired.
+      See &man.gpart.8; for options to create partitions smaller than
+      a whole disk.</para>
-    <sect2>
-      <title>Using Command Line Utilities</title>
+    <para>A file system is created on the new blank disk:</para>
-      <sect3>
-	<title>Using Slices</title>
+    <screen>&prompt.root; <userinput>newfs -U /dev/ada1</userinput></screen>
-	<para>The setup in the following example allows the new disk
-	  to work correctly with other operating systems that might be
-	  installed on the computer without confusing other operating
-	  systems' <command>fdisk</command> utilities.  This method is
-	  recommended for new disk installs.  Only use
-	  <literal>dedicated</literal> mode if there is a good reason
-	  to do so!</para>
-	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
-&prompt.root; <userinput>fdisk -BI da1</userinput> #Initialize your new disk
-&prompt.root; <userinput>bsdlabel -B -w da1s1 auto</userinput> #Label it.
-&prompt.root; <userinput>bsdlabel -e da1s1</userinput> # Edit the bsdlabel just created and add any partitions.
-&prompt.root; <userinput>mkdir -p /1</userinput>
-&prompt.root; <userinput>newfs /dev/da1s1e</userinput> # Repeat this for every partition you created.
-&prompt.root; <userinput>mount /dev/da1s1e /1</userinput> # Mount the partition(s)
-&prompt.root; <userinput>vi /etc/fstab</userinput> # Add the appropriate entry/entries to your <filename>/etc/fstab</filename>.</screen>
+    <para>An empty directory is created as a
+      <emphasis>mountpoint</emphasis>, a location for mounting the new
+      disk in the original disk's file system:</para>
-	<para>For an IDE disk, substitute
-	  <filename>ad</filename> for <filename>da</filename>.</para>
-      </sect3>
+    <screen>&prompt.root; <userinput>mkdir /newdisk</userinput></screen>
-      <sect3>
-	<title>Dedicated</title>
+    <para>Finally, an entry is added to
+      <filename>/etc/fstab</filename> so the new disk will be mounted
+      automatically at startup:</para>
-	<indexterm><primary>OS/2</primary></indexterm>
+    <programlisting>/dev/ada1	/newdisk	ufs	rw	2	2</programlisting>
-	<para>If the new drive will not be shared with another
-	  operating system, <literal>dedicated</literal> mode can be
-	  used.  This mode can confuse Microsoft operating systems;
-	  however, no damage will be done by them.  To configure a
-	  disk in dedicated mode:</para>
-	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
-&prompt.root; <userinput>bsdlabel -Bw da1 auto</userinput>
-&prompt.root; <userinput>bsdlabel -e da1</userinput>				# create the `e' partition
-&prompt.root; <userinput>newfs /dev/da1e</userinput>
-&prompt.root; <userinput>mkdir -p /1</userinput>
-&prompt.root; <userinput>vi /etc/fstab</userinput>				# add an entry for /dev/da1e
-&prompt.root; <userinput>mount /1</userinput></screen>
-	<para>An alternate method is:</para>
-	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 count=2</userinput>
-&prompt.root; <userinput>bsdlabel /dev/da1 | bsdlabel -BR da1 /dev/stdin</userinput>
-&prompt.root; <userinput>newfs /dev/da1e</userinput>
-&prompt.root; <userinput>mkdir -p /1</userinput>
-&prompt.root; <userinput>vi /etc/fstab</userinput>					# add an entry for /dev/da1e
-&prompt.root; <userinput>mount /1</userinput></screen>
+    <para>The new disk can be mounted manually, without restarting the
+      system:</para>
-      </sect3>
-    </sect2>
+    <screen>&prompt.root; <userinput>mount /newdisk</userinput></screen>
   <sect1 id="raid">

More information about the svn-doc-all mailing list