docs/164920: [PATCH] changes to swap section of config chapter

[Niclas Zeising]

>Number:         164920
>Category:       docs
>Synopsis:       [PATCH] changes to swap section of config chapter
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu Feb 09 00:10:07 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator:     Niclas Zeising
>Release:        FreeBSD 9.0-BETA2 amd64
>Organization:
>Environment:
System: FreeBSD vincent.daemonic.se 9.0-BETA2 FreeBSD 9.0-BETA2 #0 r225368: Sat Sep 3 22:13:26 CEST 2011 root at vincent.daemonic.se:/usr/obj/usr/src/sys/VINCENT amd64


	
>Description:
	The section about adding swap space on a new harddrive in the configuation and tuning chapter of the handbook is rather inadequate, and the language used is perhaps not entirely suitable for the handbook.
>How-To-Repeat:
	
>Fix:

	Attached patch rewrites this section of the handbook to add a more throughout and clear explanation on how to add more swap space using an existing or new harddrive.
	Prodded by: A friend who at first couldn't figure out how to add more swap space to a machine.

--- handbook.config.chapter.sgml.diff begins here ---
Index: en_US.ISO8859-1/books/handbook/config/chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v
retrieving revision 1.250
diff -u -d -r1.250 chapter.sgml
--- en_US.ISO8859-1/books/handbook/config/chapter.sgml	31 Jan 2012 14:14:59 -0000	1.250
+++ en_US.ISO8859-1/books/handbook/config/chapter.sgml	8 Feb 2012 23:14:35 -0000
@@ -2390,15 +2390,37 @@
       <xref linkend="swap-encrypting"> of the Handbook.</para>
 
     <sect2 id="new-drive-swap">
-      <title>Swap on a New Hard Drive</title>
+      <title>Swap on a New or Existing Hard Drive</title>
 
-      <para>The best way to add swap, of course, is to use this as an
-	excuse to add another hard drive.  You can always use another
-	hard drive, after all.  If you can do this, go reread the
-	discussion of swap space
-	in <xref linkend="configtuning-initial">
-	of the Handbook for some suggestions on how to best
-	arrange your swap.</para>
+      <para>The best way, and the way that gives most performance, is to add
+	a new swap partition on an existing or new hard drive.  How to set up
+	partitions and harddrives is explaned in <xref linkend="disks-adding">
+	and <xref linkend="configtuning-initial"> contains a discussion on
+	partition layouts and swap partition size considerations.</para>
+      <para>When a partition is prepared and selected, &man.swapon.8; is used
+	to add the partition to the system.  If the partition is
+	<filename>/dev/ada1s1p2</filename>, this will look like:</para>
+
+      <screen>&prompt.root; <userinput>swapon
+	<replaceable>/dev/ada1s1p2</replaceable></userinput></screen>
+
+      <warning>
+	<para>It is posible to use any partition not currently mounted, even
+	  if it contains a file system.  If the partition contains a file
+	  system and is mounted as swap space, the filesystem will be
+	  destroyed.  Therefore, make sure that the partition to be added as
+	  swap partition is really the intended partition, before running
+	  <command>swapon</command>.</para>
+      </warning>
+
+      <para>To make this new swap partition automatically added on boot,
+	change <filename>/etc/fstab</filename> to include an entry for the
+	partition.  This entry can look something like:</para>
+
+      <programlistning>/dev/ada1s1p1	none	swap	sw	0	0</programlistning>
+
+      <para>For an explanation of entries in <filename>/etc/fstab</filename>,
+	refer to &man.fstab.5;.</para>
     </sect2>
 
     <sect2 id="nfs-swap">
--- handbook.config.chapter.sgml.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: