diff options
Diffstat (limited to 'el_GR.ISO8859-7/books/handbook/disks/chapter.xml')
| -rw-r--r-- | el_GR.ISO8859-7/books/handbook/disks/chapter.xml | 5111 |
1 files changed, 2537 insertions, 2574 deletions
diff --git a/el_GR.ISO8859-7/books/handbook/disks/chapter.xml b/el_GR.ISO8859-7/books/handbook/disks/chapter.xml index 987380c80c..55142fd69b 100644 --- a/el_GR.ISO8859-7/books/handbook/disks/chapter.xml +++ b/el_GR.ISO8859-7/books/handbook/disks/chapter.xml @@ -8,7 +8,7 @@ $FreeBSD$ %SOURCE% en_US.ISO8859-1/books/handbook/disks/chapter.xml - %SRCID% 1.1 + %SRCID% 43449 --> <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="disks"> @@ -52,17 +52,10 @@ στο &os;.</para> </listitem> <listitem> - <para>Τα διάφορα διαθέσιμα μέσα αποθήκευσης για αντίγραφα - ασφαλείας.</para> - </listitem> - <listitem> <para>Πως να χρησιμοποιήσετε προγράμματα λήψης αντιγράφων ασφαλείας στο &os;.</para> </listitem> <listitem> - <para>Πως να πάρετε αντίγραφα ασφαλείας σε δισκέττες.</para> - </listitem> - <listitem> <para>Τι είναι οι εικόνες (snapshots) σε ένα σύστημα αρχείων και πως να τις χρησιμοποιήσετε αποδοτικά.</para> </listitem> @@ -72,19 +65,17 @@ <itemizedlist> <listitem> - <para>Να ξέρετε πως θα ρυθμίσετε και θα εγκαταστήσετε ένα νέο πυρήνα - του &os; (<xref linkend="kernelconfig"/>).</para> + <para>Να ξέρετε πως να <link linkend="kernelconfig">ρυθμίσετε και + να εγκαταστήσετε ένα νέο πυρήνα του &os;</link>.</para> </listitem> </itemizedlist> - </sect1> <sect1 xml:id="disks-naming"> <title>Device Names</title> <para>The following is a list of physical storage devices - supported in FreeBSD, and the device names associated with - them.</para> + supported in &os; and their associated device names.</para> <table xml:id="disk-naming-physical-table" frame="none"> <title>Physical Disk Naming Conventions</title> @@ -96,45 +87,70 @@ <entry>Drive device name</entry> </row> </thead> + <tbody> <row> <entry>IDE hard drives</entry> - <entry><literal>ad</literal></entry> + <entry><literal>ad</literal> or + <literal>ada</literal></entry> </row> + <row> - <entry>IDE CDROM drives</entry> - <entry><literal>acd</literal></entry> + <entry>IDE CD-ROM drives</entry> + <entry><literal>acd</literal> or + <literal>cd</literal></entry> </row> + <row> - <entry>SCSI hard drives and USB Mass storage devices</entry> + <entry>SATA hard drives</entry> + <entry><literal>ad</literal> or + <literal>ada</literal></entry> + </row> + + <row> + <entry>SATA CD-ROM drives</entry> + <entry><literal>acd</literal> or + <literal>cd</literal></entry> + </row> + + <row> + <entry>SCSI hard drives and USB Mass storage + devices</entry> <entry><literal>da</literal></entry> </row> + <row> - <entry>SCSI CDROM drives</entry> + <entry>SCSI CD-ROM drives</entry> <entry><literal>cd</literal></entry> </row> + <row> - <entry>Assorted non-standard CDROM drives</entry> + <entry>Assorted non-standard CD-ROM drives</entry> <entry><literal>mcd</literal> for Mitsumi CD-ROM and - <literal>scd</literal> for Sony CD-ROM devices - </entry> + <literal>scd</literal> for Sony CD-ROM devices</entry> </row> + <row> <entry>Floppy drives</entry> <entry><literal>fd</literal></entry> </row> + <row> <entry>SCSI tape drives</entry> <entry><literal>sa</literal></entry> - </row> + </row> + <row> <entry>IDE tape drives</entry> <entry><literal>ast</literal></entry> </row> + <row> <entry>Flash drives</entry> - <entry><literal>fla</literal> for &diskonchip; Flash device</entry> + <entry><literal>fla</literal> for &diskonchip; Flash + device</entry> </row> + <row> <entry>RAID drives</entry> <entry><literal>aacd</literal> for &adaptec; AdvancedRAID, @@ -150,618 +166,142 @@ </sect1> <sect1 xml:id="disks-adding"> - <info><title>Adding Disks</title> + <info> + <title>Adding Disks</title> + <authorgroup> - <author><personname><firstname>David</firstname><surname>O'Brien</surname></personname><contrib>Originally contributed by </contrib></author> + <author> + <personname> + <firstname>David</firstname> + <surname>O'Brien</surname> + </personname> + <contrib>Originally contributed by </contrib> + </author> </authorgroup> - </info> - - <indexterm> <primary>disks</primary> <secondary>adding</secondary> </indexterm> - <para>Lets say we want to add a new SCSI 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 manufacturer. Due to the - wide variations of procedures to do this, the details are beyond - the scope of this document.</para> + <para>This section describes how to add a new + <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 + <systemitem class="username">root</systemitem>.</para> - <para>Login as user <systemitem class="username">root</systemitem>. After you have installed the - drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new - disk was found. Continuing with our example, the newly added drive will - be <filename>da1</filename> and we want to mount it on - <filename>/1</filename> (if you are adding an IDE drive, the device name - will be <filename>ad1</filename>).</para> + <para>Inspect <filename>/var/run/dmesg.boot</filename> to ensure + the new disk was found. In this example, the newly added + <acronym>SATA</acronym> drive will appear as + <filename>ada1</filename>.</para> <indexterm><primary>partitions</primary></indexterm> - <indexterm><primary>slices</primary></indexterm> <indexterm> - <primary><command>fdisk</command></primary> + <primary><command>gpart</command></primary> </indexterm> - <para>FreeBSD runs on IBM-PC compatible computers, therefore it must - take into account the PC BIOS partitions. These 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 FreeBSD, you can use the - <emphasis>dedicated</emphasis> mode. Otherwise, FreeBSD will - have to live within one of the PC BIOS partitions. FreeBSD - calls the PC BIOS partitions <emphasis>slices</emphasis> so as - not to confuse them with traditional BSD partitions. You may - also use slices on a disk that is dedicated to FreeBSD, 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 - other, non-FreeBSD 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 simply 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.gpt.8; partitions may be - used.</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>You may use <command>sysinstall</command> to - partition and label a new disk using its easy to use menus. - Either login as user <systemitem class="username">root</systemitem> or use the - <command>su</command> command. Run - <command>sysinstall</command> and enter the - <literal>Configure</literal> menu. Within the - <literal>FreeBSD 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>, typing <userinput>A</userinput> will - use the entire disk for FreeBSD. When asked if you want to - <quote>remain cooperative with any future possible operating - systems</quote>, answer <literal>YES</literal>. Write the - changes to the disk using <userinput>W</userinput>. Now exit the - FDISK editor by typing <userinput>q</userinput>. Next you will be - asked about the <quote>Master Boot Record</quote>. Since you are adding a - disk to an already running system, choose - <literal>None</literal>.</para> - </step> - - <step> - <title>Disk Label Editor</title> - <indexterm><primary>BSD partitions</primary></indexterm> - - <para>Next, you need to exit <application>sysinstall</application> - and start it again. Follow the directions above, although this - time choose the <literal>Label</literal> option. This will - enter the <literal>Disk Label Editor</literal>. This - is where you will create the 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>/</filename>). Thus only your system disk (e.g, - the disk you boot from) should have an <literal>a</literal> - partition. The <literal>b</literal> partition is used for - swap partitions, and you may have many disks with swap - partitions. The <literal>c</literal> partition addresses the - entire disk in dedicated mode, or the entire FreeBSD slice in - slice mode. The other partitions are for general use.</para> - - <para><application>sysinstall</application>'s Label editor - favors the <literal>e</literal> - partition for non-root, non-swap partitions. Within the - Label editor, create a single file system by typing - <userinput>C</userinput>. When prompted if this will be a FS - (file system) or swap, choose <literal>FS</literal> and type in a - mount point (e.g, <filename>/mnt</filename>). When adding a - disk in post-install mode, <application>sysinstall</application> - will not create entries - in <filename>/etc/fstab</filename> for you, so the mount point - you specify is not important.</para> - - <para>You are now ready to write the new label to the disk and - create a file system on it. Do this by typing - <userinput>W</userinput>. Ignore any errors from - <application>sysinstall</application> that - it could not mount the new partition. Exit the Label Editor - and <application>sysinstall</application> completely.</para> - </step> - - <step> - <title>Finish</title> - - <para>The last step is to edit <filename>/etc/fstab</filename> - to add an entry for your new disk.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Using Command Line Utilities</title> - - <sect3> - <title>Using Slices</title> - - <para>This setup will allow your disk to work correctly with - other operating systems that might be installed on your - computer and will not confuse other operating systems' - <command>fdisk</command> utilities. It is recommended - to use this method for new disk installs. Only use - <literal>dedicated</literal> mode if you have 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 -r 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>If you have an IDE disk, substitute <filename>ad</filename> - for <filename>da</filename>.</para> - </sect3> - - <sect3> - <title>Dedicated</title> - <indexterm><primary>OS/2</primary></indexterm> - - <para>If you will not be sharing the new drive with another operating - system, you may use the <literal>dedicated</literal> mode. Remember - this mode can confuse Microsoft operating systems; however, no damage - will be done by them. IBM's &os2; however, will - <quote>appropriate</quote> any partition it finds which it does not - understand.</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput> -&prompt.root; <userinput>bsdlabel -Brw da1 auto</userinput> -&prompt.root; <userinput>bsdlabel -e da1</userinput> # create the `e' partition -&prompt.root; <userinput>newfs -d0 /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 -BrR 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> - - </sect3> - </sect2> - </sect1> - - <sect1 xml:id="raid"> - <title>RAID</title> - - <sect2 xml:id="raid-soft"> - <title>Software RAID</title> - - <sect3 xml:id="ccd"> - <info><title>Concatenated Disk Driver (CCD) Configuration</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>When choosing a mass storage solution the most important - factors to consider are speed, reliability, and cost. It is - rare to have all three in balance; normally a fast, reliable mass - storage device is expensive, and to cut back on cost either speed - or reliability must be sacrificed.</para> - - <para>In designing the system described below, cost was chosen - as the most important factor, followed by speed, then reliability. - Data transfer speed for this system is ultimately - constrained by the network. And while reliability is very important, - the CCD drive described below serves online data that is already - fully backed up on CD-R's and can easily be replaced.</para> - - <para>Defining your own requirements is the first step - in choosing a mass storage solution. If your requirements prefer - speed or reliability over cost, your solution will differ from - the system described in this section.</para> - - - <sect4 xml:id="ccd-installhw"> - <title>Installing the Hardware</title> - - <para>In addition to the IDE system disk, three Western - Digital 30GB, 5400 RPM IDE disks form the core - of the CCD disk described below providing approximately - 90GB of online storage. Ideally, - each IDE disk would have its own IDE controller - and cable, but to minimize cost, additional - IDE controllers were not used. Instead the disks were - configured with jumpers so that each IDE controller has - one master, and one slave.</para> - - <para>Upon reboot, the system BIOS was configured to - automatically detect the disks attached. More importantly, - FreeBSD detected them on reboot:</para> - - <programlisting>ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33 -ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33 -ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33 -ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33</programlisting> - - <note><para>If FreeBSD does not detect all the disks, ensure - that you have jumpered them correctly. Most IDE drives - also have a <quote>Cable Select</quote> jumper. This is - <emphasis>not</emphasis> the jumper for the master/slave - relationship. Consult the drive documentation for help in - identifying the correct jumper.</para></note> - - <para>Next, consider how to attach them as part of the file - system. You should research both &man.vinum.8; (<xref linkend="vinum-vinum"/>) and &man.ccd.4;. In this - particular configuration, &man.ccd.4; was chosen.</para> - </sect4> - - <sect4 xml:id="ccd-setup"> - <title>Setting Up the CCD</title> - - <para>The &man.ccd.4; driver allows you to take - several identical disks and concatenate them into one - logical file system. In order to use - &man.ccd.4;, you need a kernel with - &man.ccd.4; support built in. - Add this line to your kernel configuration file, rebuild, and - reinstall the kernel:</para> - - <programlisting>device ccd</programlisting> - - <para>The &man.ccd.4; support can also be - loaded as a kernel loadable module.</para> - - <para>To set up &man.ccd.4;, you must first use - &man.bsdlabel.8; to label the disks:</para> - - <programlisting>bsdlabel -r -w ad1 auto -bsdlabel -r -w ad2 auto -bsdlabel -r -w ad3 auto</programlisting> - - <para>This creates a bsdlabel for <filename>ad1c</filename>, <filename>ad2c</filename> and <filename>ad3c</filename> that - spans the entire disk.</para> - - <para>The next step is to change the disk label type. You - can use &man.bsdlabel.8; to edit the - disks:</para> - - <programlisting>bsdlabel -e ad1 -bsdlabel -e ad2 -bsdlabel -e ad3</programlisting> - - <para>This opens up the current disk label on each disk with - the editor specified by the <envar>EDITOR</envar> - environment variable, typically &man.vi.1;.</para> - - <para>An unmodified disk label will look something like - this:</para> - - <programlisting>8 partitions: -# size offset fstype [fsize bsize bps/cpg] - c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)</programlisting> - - <para>Add a new <literal>e</literal> partition for &man.ccd.4; to use. This - can usually be copied from the <literal>c</literal> partition, - but the <option>fstype</option> <emphasis>must</emphasis> - be <userinput>4.2BSD</userinput>. The disk label should - now look something like this:</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>Building the File System</title> - - <para>Now that you have all the disks labeled, you must - build the &man.ccd.4;. To do that, - use &man.ccdconfig.8;, with options similar to the following:</para> + <para>For this example, a single large partition will be created + on the new disk. The <link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"> + <acronym>GPT</acronym></link> partitioning scheme will be + used in preference to the older and less versatile + <acronym>MBR</acronym> scheme.</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>The use and meaning of each option is shown below:</para> - - <calloutlist> - <callout arearefs="co-ccd-dev"> - <para>The first argument is the device to configure, in this case, - <filename>/dev/ccd0c</filename>. The <filename>/dev/</filename> - portion is optional.</para> - </callout> - - <callout arearefs="co-ccd-interleave"> - - <para>The interleave for the file system. The interleave - defines the size of a stripe in disk blocks, each normally 512 bytes. - So, an interleave of 32 would be 16,384 bytes.</para> - </callout> - - <callout arearefs="co-ccd-flags"> - <para>Flags for &man.ccdconfig.8;. If you want to enable drive - mirroring, you can specify a flag here. This - configuration does not provide mirroring for - &man.ccd.4;, so it is set at 0 (zero).</para> - </callout> - - <callout arearefs="co-ccd-devs"> - <para>The final arguments to &man.ccdconfig.8; - are the devices to place into the array. Use the complete pathname - for each device.</para> - </callout> - </calloutlist> - - - <para>After running &man.ccdconfig.8; the &man.ccd.4; - is configured. A file system can be installed. Refer to &man.newfs.8; - for options, or simply run: </para> - - <programlisting>newfs /dev/ccd0c</programlisting> - - - </sect4> - - <sect4 xml:id="ccd-auto"> - <title>Making it All Automatic</title> - - <para>Generally, you will want to mount the - &man.ccd.4; upon each reboot. To do this, you must - configure it first. Write out your current configuration to - <filename>/etc/ccd.conf</filename> using the following command:</para> - - <programlisting>ccdconfig -g > /etc/ccd.conf</programlisting> - - <para>During reboot, the script <command>/etc/rc</command> - runs <command>ccdconfig -C</command> if <filename>/etc/ccd.conf</filename> - exists. This automatically configures the - &man.ccd.4; so it can be mounted.</para> - - <note><para>If you are booting into single user mode, before you can - &man.mount.8; the &man.ccd.4;, you - need to issue the following command to configure the - array:</para> - - <programlisting>ccdconfig -C</programlisting> - </note> - - <para>To automatically mount the &man.ccd.4;, - place an entry for the &man.ccd.4; in - <filename>/etc/fstab</filename> so it will be mounted at - boot time:</para> - - <programlisting>/dev/ccd0c /media ufs rw 2 2</programlisting> - </sect4> - </sect3> - - <sect3 xml:id="vinum"> - <title>The Vinum Volume Manager</title> - -<indexterm><primary>RAID</primary><secondary>software</secondary></indexterm> -<indexterm> - <primary>RAID</primary> - <secondary>Vinum</secondary> -</indexterm> - - <para>The Vinum Volume Manager is a block device driver which - implements virtual disk drives. It isolates disk hardware - from the block device interface and maps data in ways which - result in an increase in flexibility, performance and - reliability compared to the traditional slice view of disk - storage. &man.vinum.8; implements the RAID-0, RAID-1 and - RAID-5 models, both individually and in combination.</para> - - <para>See <xref linkend="vinum-vinum"/> for more - information about &man.vinum.8;.</para> - </sect3> - </sect2> - - <sect2 xml:id="raid-hard"> - <title>Hardware RAID</title> - - <indexterm> - <primary>RAID</primary> - <secondary>hardware</secondary> - </indexterm> - - <para>FreeBSD also supports a variety of hardware <acronym>RAID</acronym> - controllers. These devices control a <acronym>RAID</acronym> subsystem - without the need for FreeBSD specific software to manage the - array.</para> - - <para>Using an on-card <acronym>BIOS</acronym>, the card controls most of the disk operations - itself. The following is a brief setup description using a Promise <acronym>IDE</acronym> <acronym>RAID</acronym> - controller. When this card is installed and the system is started up, it - displays a prompt requesting information. Follow the instructions - to enter the card's setup screen. From here, you have the ability to - combine all the attached drives. After doing so, the disk(s) will look like - a single drive to FreeBSD. Other <acronym>RAID</acronym> levels can be set up - accordingly. - </para> - </sect2> - - <sect2> - <title>Rebuilding ATA RAID1 Arrays</title> - - <para>FreeBSD allows you to hot-replace a failed disk in an array. This requires - that you catch it before you reboot.</para> - - <para>You will probably see something like the following in <filename>/var/log/messages</filename> or in the &man.dmesg.8; - output:</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>Using &man.atacontrol.8;, check for further information:</para> - - <screen>&prompt.root; <userinput>atacontrol list</userinput> -ATA channel 0: - Master: no device present - Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0 + <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> -ATA channel 1: - Master: no device present - Slave: no device present + <para>The partition scheme is created, and then a single partition + is added:</para> -ATA channel 2: - Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 - Slave: no device present + <screen>&prompt.root; <userinput>gpart create -s GPT ada1</userinput> +&prompt.root; <userinput>gpart add -t freebsd-ufs ada1</userinput></screen> -ATA channel 3: - Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 - Slave: no device present + <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> -&prompt.root; <userinput>atacontrol status ar0</userinput> -ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED</screen> + <para>A file system is created on the new blank disk:</para> - <procedure> - <step> - <para>You will first need to detach the ata channel with the failed - disk so you can safely remove it:</para> + <screen>&prompt.root; <userinput>newfs -U /dev/ada1p1</userinput></screen> - <screen>&prompt.root; <userinput>atacontrol detach ata3</userinput></screen> - </step> + <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> - <step> - <para>Replace the disk.</para> - </step> + <screen>&prompt.root; <userinput>mkdir /newdisk</userinput></screen> - <step> - <para>Reattach the ata channel:</para> + <para>Finally, an entry is added to + <filename>/etc/fstab</filename> so the new disk will be mounted + automatically at startup:</para> - <screen>&prompt.root; <userinput>atacontrol attach ata3</userinput> -Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 -Slave: no device present</screen> - </step> + <programlisting>/dev/ada1p1 /newdisk ufs rw 2 2</programlisting> - <step> - <para>Add the new disk to the array as a spare:</para> - - <screen>&prompt.root; <userinput>atacontrol addspare ar0 ad6</userinput></screen> - </step> - - <step> - <para>Rebuild the array:</para> - - <screen>&prompt.root; <userinput>atacontrol rebuild ar0</userinput></screen> - </step> - - <step> - <para>It is possible to check on the progress by issuing the - following command:</para> + <para>The new disk can be mounted manually, without restarting the + system:</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 - -&prompt.root; <userinput>atacontrol status ar0</userinput> -ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed</screen> - </step> - - <step> - <para>Wait until this operation completes.</para> - </step> - </procedure> - </sect2> + <screen>&prompt.root; <userinput>mount /newdisk</userinput></screen> </sect1> <sect1 xml:id="usb-disks"> - <info><title>USB Storage Devices</title> + <info> + <title>USB Storage Devices</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> - </info> - <indexterm> <primary>USB</primary> <secondary>disks</secondary> </indexterm> - <para>A lot of external storage solutions, nowadays, use the - Universal Serial Bus (USB): hard drives, USB thumbdrives, CD-R - burners, etc. &os; provides support for these devices.</para> + <para>Many external storage solutions, such as hard drives, USB + thumbdrives, and CD/DVD burners, use the Universal Serial Bus + (USB). &os; provides support for these devices.</para> <sect2> <title>Configuration</title> - <para>The USB mass storage devices driver, &man.umass.4;, - provides the support for USB storage devices. If you use the - <filename>GENERIC</filename> kernel, you do not have to change - anything in your configuration. If you use a custom kernel, - be sure that the following lines are present in your kernel - configuration file:</para> + <para>The USB mass storage devices driver, &man.umass.4;, is + built into the <filename>GENERIC</filename> kernel and + provides support for USB storage devices. For a custom + kernel, be sure that the following lines are present in the + kernel configuration file:</para> <programlisting>device scbus device da device pass device uhci device ohci +device ehci device usb device umass</programlisting> - <para>The &man.umass.4; driver uses the SCSI subsystem to access - to the USB storage devices, your USB device will be seen as a - SCSI device by the system. Depending on the USB chipset on - your motherboard, you only need either <literal>device - uhci</literal> or <literal>device ohci</literal>, however - having both in the kernel configuration file is harmless. Do - not forget to compile and install the new kernel if you added - any lines.</para> + <para>Since the &man.umass.4; driver uses the SCSI subsystem to + access the USB storage devices, any USB device will be seen as + a SCSI device by the system. Depending on the USB chipset on + the motherboard, <literal>device uhci</literal> or + <literal>device ohci</literal> is used to provide USB 1.X + support. Support for USB 2.0 controllers is provided by + <literal>device ehci</literal>.</para> <note> - <para>If your USB device is a CD-R or DVD burner, the SCSI CD-ROM - driver, &man.cd.4;, must be added to the kernel via the - line:</para> + <para>If the USB device is a CD or DVD burner, &man.cd.4;, + must be added to the kernel via the line:</para> <programlisting>device cd</programlisting> @@ -769,23 +309,14 @@ device umass</programlisting> &man.atapicam.4; should not be used in the kernel configuration.</para> </note> - - <para>Support for USB 2.0 controllers is provided on - &os;; however, you must add:</para> - - <programlisting>device ehci</programlisting> - - <para>to your configuration file for USB 2.0 support. Note - &man.uhci.4; and &man.ohci.4; drivers are still needed if you - want USB 1.X support.</para> </sect2> <sect2> <title>Testing the Configuration</title> - <para>The configuration is ready to be tested: plug in your USB - device, and in the system message buffer (&man.dmesg.8;), the - drive should appear as something like:</para> + <para>To test the USB configuration, plug in the USB device. In + the system message buffer, &man.dmesg.8;, the drive should + appear as something like:</para> <screen>umass0: USB Solid state disk, rev 1.10/1.00, addr 2 GEOM: create disk da0 dp=0xc2d74850 @@ -794,88 +325,92 @@ da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device da0: 1.000MB/s transfers da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen> - <para>Of course, the brand, the device node - (<filename>da0</filename>) and other details can differ - according to your configuration.</para> + <para>The brand, device node (<filename>da0</filename>), and + other details will differ according to the device.</para> - <para>Since the USB device is seen as a SCSI one, the - <command>camcontrol</command> command can be used to list the - USB storage devices attached to the system:</para> + <para>Since the USB device is seen as a SCSI one, + <command>camcontrol</command> can be used to list the USB + storage devices attached to the system:</para> <screen>&prompt.root; <userinput>camcontrol devlist</userinput> <Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0)</screen> - <para>If the drive comes with a file system, you should be able - to mount it. The <xref linkend="disks-adding"/> will help you - to format and create partitions on the USB drive if - needed.</para> - - <para>To make this device mountable as a normal user, certain - steps have to be taken. First, the devices that are created - when a USB storage device is connected need to be accessible - by the user. A solution is to make all users of these devices - a member of the <systemitem class="groupname">operator</systemitem> group. This - is done with &man.pw.8;. Second, when the devices are - created, the <systemitem class="groupname">operator</systemitem> group should be - able to read and write them. This is accomplished by adding - these lines to + <para>If the drive comes with a file system, it can be mounted. + Refer to <xref linkend="disks-adding"/> for + instructions on how to format and create partitions on the USB + drive.</para> + + <warning> + <para>Allowing untrusted users to mount arbitrary media, by + enabling <varname>vfs.usermount</varname> as + described below, should not be considered safe from a + security point of view. Most file systems in &os; were not + built to safeguard against malicious devices.</para> + </warning> + + <para>To make the device mountable as a normal user, one + solution is to make all users of the device a member of the + <systemitem class="groupname">operator</systemitem> group + using &man.pw.8;. Next, ensure that the + <systemitem class="groupname">operator</systemitem> group is + able to read and write the device by adding these lines to <filename>/etc/devfs.rules</filename>:</para> - <programlisting>[localrules=1] + <programlisting>[localrules=5] add path 'da*' mode 0660 group operator</programlisting> <note> - <para>If there already are SCSI disks in the system, it must - be done a bit different. E.g., if the system already - contains disks <filename>da0</filename> through - <filename>da2</filename> attached to the system, change + <para>If SCSI disks are installed in the system, change the second line as follows:</para> <programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting> - <para>This will exclude the already existing disks from - belonging to the <systemitem class="groupname">operator</systemitem> + <para>This will exclude the first three SCSI disks + (<filename>da0</filename> to + <filename>da2</filename>)from belonging to the + <systemitem class="groupname">operator</systemitem> group.</para> </note> - <para>You also have to enable your &man.devfs.rules.5; ruleset - in your <filename>/etc/rc.conf</filename> file:</para> + <para>Next, enable the &man.devfs.rules.5; ruleset in + <filename>/etc/rc.conf</filename>:</para> <programlisting>devfs_system_ruleset="localrules"</programlisting> - <para>Next, the kernel has to be configured to allow regular - users to mount file systems. The easiest way is to add the + <para>Next, instruct the running kernel to allow regular users + to mount file systems. The easiest way is to add the following line to <filename>/etc/sysctl.conf</filename>:</para> <programlisting>vfs.usermount=1</programlisting> - <para>Note that this only takes effect after the next reboot. - Alternatively, one can also use &man.sysctl.8; to set this - variable.</para> + <para>Since this only takes effect after the next reboot use + &man.sysctl.8; to set this variable now.</para> <para>The final step is to create a directory where the file system is to be mounted. This directory needs to be owned by the user that is to mount the file system. One way to do that - is for <systemitem class="username">root</systemitem> to create a subdirectory - owned by that user as - <filename>/mnt/$USER</filename> - (replace <replaceable>$USER</replaceable> by the login name of - the actual user):</para> + is for <systemitem class="username">root</systemitem> to + create a subdirectory owned by that user as + <filename>/mnt/username</filename>. In the following example, + replace <replaceable>username</replaceable> with the login + name of the user and <replaceable>usergroup</replaceable> with + the user's primary group:</para> - <screen>&prompt.root; <userinput>mkdir /mnt/$USER</userinput> -&prompt.root; <userinput>chown $USER:$USER /mnt/$USER</userinput></screen> + <screen>&prompt.root; <userinput>mkdir /mnt/username</userinput> +&prompt.root; <userinput>chown username:usergroup /mnt/username</userinput></screen> <para>Suppose a USB thumbdrive is plugged in, and a device - <filename>/dev/da0s1</filename> appears. Since these devices - usually come preformatted with a FAT file system, one can - mount them like this:</para> + <filename>/dev/da0s1</filename> appears. If the device is + preformatted with a FAT file system, it can be mounted + using:</para> - <screen>&prompt.user; <userinput>mount_msdosfs -m 644 -M 755 /dev/da0s1 /mnt/$USER</userinput></screen> + <screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/username</userinput></screen> - <para>If you unplug the device (the disk must be unmounted - before), you should see, in the system message buffer, - something like the following:</para> + <para>Before the device can be unplugged, it + <emphasis>must</emphasis> be unmounted first. After device + removal, the system message buffer will show messages similar + to the following:</para> <screen>umass0: at uhub0 port 1 (addr 2) disconnected (da0:umass-sim0:0:0:0): lost device @@ -888,214 +423,232 @@ umass0: detached</screen> <title>Further Reading</title> <para>Beside the <link linkend="disks-adding">Adding - Disks</link> and <link linkend="mount-unmount">Mounting and + Disks</link> and <link linkend="mount-unmount">Mounting and Unmounting File Systems</link> sections, reading various - manual pages may be also useful: &man.umass.4;, - &man.camcontrol.8;, and &man.usbdevs.8;.</para> + manual pages may also be useful: &man.umass.4;, + &man.camcontrol.8;, and &man.usbconfig.8; under &os; 8.X + or &man.usbdevs.8; under earlier versions of &os;.</para> </sect2> </sect1> <sect1 xml:id="creating-cds"> - <info><title>Creating and Using Optical Media (CDs)</title> + <info> + <title>Creating and Using CD 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>CD-ROMs</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>CD media provide 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.</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> + <para>CD media do have tracks, but this refers to a section of + data to be read continuously and not a physical property of + the disk. For example, to produce a CD on &os;, 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> + <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> + differences. To overcome the original file system limits, 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> <indexterm> - <primary><package>sysutils/cdrtools</package></primary> + <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> + port includes &man.mkisofs.8;, a program that can be used 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>CD burner</primary> - <secondary>ATAPI</secondary> + <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. - It is also possible to use <command>cdrecord</command> and other tools - for SCSI drives on ATAPI hardware with the <link linkend="atapicam">ATAPI/CAM module</link>.</para> - - <para>If you want CD burning software with a graphical user - interface, you may wish to take a look at either - <application>X-CD-Roast</application> or + + <para>Which tool to use to burn the CD depends on whether the + CD burner is ATAPI or something else. ATAPI CD burners use + <command>burncd</command> which is part of the base system. + SCSI and USB CD burners should use <command>cdrecord</command> + from the <package>sysutils/cdrtools</package> port. It is + also possible to use <command>cdrecord</command> and other + tools for SCSI drives on ATAPI hardware with the + <link linkend="atapicam">ATAPI/CAM module</link>.</para> + + <para>For CD burning software with a graphical user + interface, consider <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. + 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 + <application>K3b</application> require the + <link linkend="atapicam">ATAPI/CAM module</link> with ATAPI hardware.</para> </sect2> <sect2 xml:id="mkisofs"> - <title>mkisofs</title> + <title><application>mkisofs</application></title> - <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> + <para>The <package>sysutils/cdrtools</package> + port also installs &man.mkisofs.8;, which 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> <screen>&prompt.root; <userinput>mkisofs -o imagefile.iso /path/to/tree</userinput></screen> <indexterm> - <primary>file systems</primary> - <secondary>ISO 9660</secondary> + <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> + + <para>This command creates 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 + maps 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> <indexterm> - <primary>file systems</primary> - <secondary>HFS</secondary> + <primary>file systems</primary> + <secondary>HFS</secondary> </indexterm> <indexterm> - <primary>file systems</primary> - <secondary>Joliet</secondary> + <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, + <para>A number of options are available to overcome these + 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 &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 FreeBSD tree you started - from, though it may violate the ISO 9660 standard in a number of - ways.</para> + restrictions. When used with <option>-R</option>, it produces + a file system image that is identical to the specified &os; + tree, though it may violate the ISO 9660 standard in a number + of ways.</para> <indexterm> - <primary>CDROMs</primary> - <secondary>creating bootable</secondary> + <primary>CD-ROMs</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 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 + <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 + <quote>floppy disk emulation</quote> mode, and thus expects + the boot image to be exactly 1200, 1440 or 2880 KB in + size. Some boot loaders, like the one used by the &os; + distribution disks, 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>, you could produce the - image of an ISO 9660 file system in - <filename>/tmp/bootable.iso</filename> like so:</para> + <filename>/tmp/myboot/boot/cdboot</filename>, this command + would produce the image of an ISO 9660 file system as + <filename>/tmp/bootable.iso</filename>:</para> <screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen> - <para>Having done that, if you have <filename>md</filename> - configured in your kernel, you can mount the file system with:</para> + <para>If <filename>md</filename> is configured in the + kernel, the file system can be mounted as a memory disk + with:</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> - <para>At which point you can verify that <filename>/mnt</filename> - and <filename>/tmp/myboot</filename> are identical.</para> + <para>One can then verify that <filename>/mnt</filename> and + <filename>/tmp/myboot</filename> are identical.</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> + <para>There are many other options available for + &man.mkisofs.8; to fine-tune its behavior. Refer to + &man.mkisofs.8; for details.</para> </sect2> <sect2 xml:id="burncd"> - <title>burncd</title> + <title><application>burncd</application></title> + <indexterm> - <primary>CDROMs</primary> - <secondary>burning</secondary> + <primary>CD-ROMs</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> + <para>For an ATAPI CD burner, <command>burncd</command> can be + used 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> + <para>This command 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> <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> + <title><application>cdrecord</application></title> + + <para>For systems without an ATAPI CD burner, + <command>cdrecord</command> can be used to burn CDs. + <command>cdrecord</command> is not part of the base system and + must be installed from either the + <package>sysutils/cdrtools</package> package or port. Changes + to the base system can cause binary versions of this program + to fail, possibly resulting in a <quote>coaster</quote>. It + is recommended to either upgrade the port when the system is + upgraded, or for users + <link linkend="stable">tracking -STABLE</link>, to upgrade the + port when a new version becomes available.</para> + + <para>While <command>cdrecord</command> has many options, basic + usage is simple. 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> + <para>The tricky part of using <command>cdrecord</command> is + finding the <option>dev</option> to use. To find the proper + setting, use <option>-scanbus</option> which might produce + results like this:</para> + <indexterm> - <primary>CDROMs</primary> - <secondary>burning</secondary> + <primary>CD-ROMs</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örg Schilling @@ -1119,55 +672,65 @@ 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> + <para>This lists the appropriate <option>dev</option> value for + the devices on the list. Locate the 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 is <option>dev=1,5,0</option>. + Refer to &man.cdrecord.1; for easier ways to specify this + value and for information on writing audio tracks and + controlling the write speed.</para> </sect2> <sect2 xml:id="duplicating-audiocds"> <title>Duplicating Audio CDs</title> - <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 + <para>To duplicate an audio CD, extract the audio data from the + CD to a series of files, then write these files to a blank CD. + The process is slightly different for ATAPI and SCSI drives.</para> <procedure> <title>SCSI Drives</title> <step> - <para>Use <command>cdda2wav</command> to extract the audio.</para> + <para>Use <command>cdda2wav</command> to extract the + audio:</para> - <screen>&prompt.user; <userinput>cdda2wav -v255 -D2,0 -B -Owav</userinput></screen> + <screen>&prompt.user; <userinput>cdda2wav -vall -D2,0 -B -Owav</userinput></screen> </step> <step> <para>Use <command>cdrecord</command> to write the - <filename>.wav</filename> files.</para> + <filename>.wav</filename> files:</para> <screen>&prompt.user; <userinput>cdrecord -v dev=2,0 -dao -useinfo *.wav</userinput></screen> <para>Make sure that <replaceable>2,0</replaceable> is set - appropriately, as described in <xref linkend="cdrecord"/>.</para> + appropriately, as described in + <xref linkend="cdrecord"/>.</para> </step> </procedure> <procedure> <title>ATAPI Drives</title> + <note> + <para>With the help of the + <link linkend="atapicam">ATAPI/CAM module</link>, + <command>cdda2wav</command> can also be used on ATAPI + drives. This tool is usually a better choice for most of + users, as it supports jitter correction and endianness, + than the method proposed below.</para> + </note> + <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 + 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> @@ -1180,20 +743,19 @@ scsibus1: </step> <step> - <para>Extract each track using &man.dd.1;. You must also use a - specific block size when extracting the files.</para> + <para>Extract each track using &man.dd.1;, making sure to + specify a block size when extracting the files:</para> <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> +...</screen> </step> <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> + <command>burncd</command>. Specify that these are audio + files, and that <command>burncd</command> should fixate + the disk when finished:</para> <screen>&prompt.root; <userinput>burncd -f /dev/acd0 audio track1.cdr track2.cdr ... fixate</userinput></screen> </step> @@ -1203,164 +765,167 @@ scsibus1: <sect2 xml:id="imaging-cd"> <title>Duplicating Data CDs</title> - <para>You can copy a data CD to a image file that is + <para>It is possible to copy a data CD to an 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> + &man.mkisofs.8;, and then use it to duplicate any data CD. + The example given here assumes that the CD-ROM device is + <filename>acd0</filename>. Substitute the correct CD-ROM + device.</para> <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=file.iso bs=2048</userinput></screen> - <para>Now that you have an image, you can burn it to CD as + <para>Now that there is an image, it can be burned to CD as described above.</para> </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> + <para>It is possible to mount and read the data on a standard + data CD. By default, &man.mount.8; assumes that a file system + is of type <literal>ufs</literal>. Running this + command:</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, but the &os; CD9660 driver is able to convert - Unicode characters on the fly. If some non-English characters - show up as question marks you will need to specify the local - charset you use with the <option>-C</option> option. For more - information, consult the &man.mount.cd9660.8; manual - page.</para> + <para>will generate an error about <errorname>Incorrect super + block</errorname>, and will fail to mount the CD. The CD + does not use the <literal>UFS</literal> file system, so + attempts to mount it as such will fail. Instead, tell + &man.mount.8; that the file system is of type + <literal>ISO9660</literal> by specifying + <option>-t cd9660</option> to &man.mount.8;. For example, + to mount the CD-ROM device, <filename>/dev/cd0</filename>, + under <filename>/mnt</filename>, + use:</para> + + <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen> + + <para>Replace <filename>/dev/cd0</filename> with the device + name for the CD device. Also, <option>-t cd9660</option> + executes &man.mount.cd9660.8;, meaning the above command is + equivalent to:</para> + + <screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0 /mnt</userinput></screen> + + <para>While data CD-ROMs from any vendor can be mounted this + way, disks with certain ISO 9660 extensions might behave + oddly. For example, Joliet disks store all filenames in + two-byte Unicode characters. The &os; kernel does not speak + Unicode, but the &os; CD9660 driver is able to convert Unicode + characters on the fly. 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> <note> - <para>To be able to do this character conversion with the help - of the <option>-C</option> option, the kernel will require - the <filename>cd9660_iconv.ko</filename> module to be - loaded. This can be done either by adding this line to + <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> <programlisting>cd9660_iconv_load="YES"</programlisting> - <para>and then rebooting the machine, or by directly loading the - module with &man.kldload.8;.</para> + <para>and then rebooting the machine, or by directly loading + the module with &man.kldload.8;.</para> </note> - <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 + <para>Occasionally, <errorname>Device not configured</errorname> + will be displayed when trying to mount a CD-ROM. This + usually means that the CD-ROM 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> + It can take a couple of seconds for a CD-ROM drive to realize + that a media is present, 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> + <para>Sometimes, a SCSI CD-ROM may be missed because it did not + have enough time to answer the bus reset. To resolve this, + add the following option to the kernel configuration and + <link linkend="kernelconfig-building">rebuild the + kernel</link>.</para> <programlisting>options SCSI_DELAY=15000</programlisting> - <para>This tells your SCSI bus to pause 15 seconds during boot, - to give your CDROM drive every possible chance to answer the + <para>This tells the SCSI bus to pause 15 seconds during boot, + to give the CD-ROM 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 + <para>It is possible 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> + backup purposes. This command 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> + <para>In order to retrieve the data burned to such a CD, the + data must be read from the raw device node:</para> <screen>&prompt.root; <userinput>tar xzvf /dev/acd1</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> + <para>This type of disk can not be mounted as a normal CD-ROM + and the data cannot be read under any operating system except + &os;. In order to mount the CD, or to share the data with + another operating system, &man.mkisofs.8; must be used as + described above.</para> </sect2> <sect2 xml:id="atapicam"> - <info><title>Using the ATAPI/CAM Driver</title> + <info> + <title>Using the ATAPI/CAM Driver</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> </info> - - <indexterm> <primary>CD burner</primary> <secondary>ATAPI/CAM driver</secondary> </indexterm> - <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 + <para>This driver allows ATAPI devices, such as CD/DVD drives, + to be accessed through the SCSI subsystem, and so allows the + use of applications like <package>sysutils/cdrdao</package> or &man.cdrecord.1;.</para> - <para>To use this driver, you will need to add the following - line to the <filename>/boot/loader.conf</filename> - file:</para> + <para>To use this driver, add the following line to + <filename>/boot/loader.conf</filename>:</para> <programlisting>atapicam_load="YES"</programlisting> - <para>then, reboot your machine.</para> + <para>then, reboot the system.</para> <note> - <para>If you prefer to statically compile the &man.atapicam.4; - support in your kernel, you will have to add this line to - your kernel configuration file:</para> + <para>Users who prefer to statically compile &man.atapicam.4; + support into the kernel, should add this line to the + kernel configuration file:</para> - <programlisting>device atapicam</programlisting> + <programlisting>device atapicam</programlisting> - <para>You also need the following lines in your kernel - configuration file:</para> + <para>Ensure the following lines are still in the kernel + configuration file:</para> - <programlisting>device ata + <programlisting>device ata device scbus device cd device pass</programlisting> - <para>which should already be present. Then rebuild, install - your new kernel, and reboot your machine.</para> + <para>Then rebuild, install the new kernel, and reboot the + machine.</para> </note> - <para>During the boot process, your burner should show up, - like so:</para> + <para>During the boot process, the burner should show up, like + so:</para> <screen>acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4 cd0 at ata1 bus 0 target 0 lun 0 @@ -1368,40 +933,53 @@ cd0: <MATSHITA CDRW/DVD UJDA740 1.00> 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>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>The drive can now be accessed via the + <filename>/dev/cd0</filename> device name. For example, to + mount a CD-ROM on <filename>/mnt</filename>, + type the following:</para> <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen> - <para>As <systemitem class="username">root</systemitem>, you can run the following - command to get the SCSI address of the burner:</para> + <para>As <systemitem class="username">root</systemitem>, run the + following command to get the SCSI address of the + burner:</para> <screen>&prompt.root; <userinput>camcontrol devlist</userinput> <MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0)</screen> - <para>So <literal>1,0,0</literal> will be the SCSI address to - use with &man.cdrecord.1; and other SCSI application.</para> + <para>In this example, <literal>1,0,0</literal> is the SCSI + address to use with &man.cdrecord.1; and other SCSI + applications.</para> <para>For more information about ATAPI/CAM and SCSI system, - refer to the &man.atapicam.4; and &man.cam.4; manual - pages.</para> + refer to &man.atapicam.4; and &man.cam.4;.</para> </sect2> </sect1> <sect1 xml:id="creating-dvds"> - <info><title>Creating and Using Optical Media (DVDs)</title> + <info> + <title>Creating and Using DVD 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> <secondary>burning</secondary> @@ -1412,33 +990,32 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <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> + than any CD 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 DVD:</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> + 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> <listitem> - <para>DVD-RW: This is the rewritable version of - the DVD-R standard. A DVD-RW can be rewritten about 1000 + <para>DVD-RW: This is the rewritable version of the + DVD-R standard. A DVD-RW can be rewritten about 1000 times.</para> </listitem> <listitem> - <para>DVD-RAM: This is also a rewritable 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. Read - the <xref linkend="creating-dvd-ram"/> for more information - on DVD-RAM use.</para> + <para>DVD-RAM: This is a rewritable format which can be seen + as a removable hard drive. However, this media is not + compatible with most DVD-ROM drives and DVD-Video players + as only a few DVD writers support the DVD-RAM format. + Refer to <xref linkend="creating-dvd-ram"/> for more + information on DVD-RAM use.</para> </listitem> <listitem> @@ -1456,50 +1033,49 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>A single layer recordable DVD can hold up to 4,700,000,000 bytes which is actually 4.38 GB or - 4485 MB (1 kilobyte is 1024 bytes).</para> + 4485 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 + <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> + physical media such as DVD-R, DVD+R, or DVD-RW. 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> <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 DVD recording, use &man.growisofs.1;. This + command is part of the + <package>sysutils/dvd+rw-tools</package> utilities which + support all DVD 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 SCSI 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 USB interface. + Refer to <xref linkend="usb-disks"/> for more details + on USB 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 ATAPI 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 other + <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> @@ -1507,41 +1083,72 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <sect2> <title>Burning Data DVDs</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 DVD. 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> - <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 DVD + 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 DVD-ROM 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> <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 filesystem 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 filesystem 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 imagefile.iso /path/to/data</userinput></screen> + + <para>To burn files directly to a disk:</para> + + <screen>&prompt.root; <userinput>growisofs -dvd-compat -udf -iso-level 3 -Z /dev/cd0 -J -R /path/to/data</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> @@ -1552,26 +1159,24 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <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>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 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 + <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 DVD 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 /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><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> @@ -1583,49 +1188,46 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </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> + 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 DVD+RW:</para> <screen>&prompt.root; <userinput>dvd+rw-format /dev/cd0</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 DVD+RW medias need to be formatted. Once + formatted, the DVD+RW 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 DVD+RW, 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> - <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 DVD+RW 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 DVD+RW, use the + following:</para> <screen>&prompt.root; <userinput>growisofs -M /dev/cd0 -J -R /path/to/nextdata</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 DVD-ROM drives. When using DVD+RW, 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> </sect2> @@ -1638,36 +1240,36 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <secondary>DVD-RW</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 DVD-RW accepts two disc formats: incremental sequential + and restricted overwrite. By default, DVD-RW 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 DVD-RW can be directly written without being + formatted. However, a non-virgin DVD-RW 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 DVD-RW in sequential mode:</para> <screen>&prompt.root; <userinput>dvd+rw-format -blank=full /dev/cd0</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> + <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 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>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>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>One should instead use restricted overwrite mode with + any DVD-RW 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 @@ -1675,59 +1277,56 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -J -R /path/to/data</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 + <para>To append some data to a previous recording, use + <option>-M</option> with &man.growisofs.1;. However, if data + is appended 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>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>To put a DVD-RW in the restricted overwrite format, the + 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 + DVD.</para> + + <para>To put a DVD-RW in restricted overwrite format, the following command must be used:</para> <screen>&prompt.root; <userinput>dvd+rw-format /dev/cd0</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> </sect2> <sect2> - <title>Multisession</title> + <title>Multi-Session</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 - restricted overwrite formats.</para> + <para>Few DVD-ROM drives support multi-session DVDs and most of + the time 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 restricted overwrite formats.</para> - <para>Using the following command after an initial (non-closed) + <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> <screen>&prompt.root; <userinput>growisofs -M /dev/cd0 -J -R /path/to/nextdata</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 DVD+RW or a DVD-RW 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> @@ -1735,27 +1334,29 @@ 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 + <para>To obtain more information about a DVD, use <command>dvd+rw-mediainfo - /dev/cd0</command> command can be - ran with the disc in the drive.</para> + /dev/cd0</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> <sect2 xml:id="creating-dvd-ram"> <title>Using a DVD-RAM</title> + <indexterm> <primary>DVD</primary> <secondary>DVD-RAM</secondary> @@ -1764,24 +1365,23 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <sect3> <title>Configuration</title> - <para>DVD-RAM writers come with either SCSI or ATAPI - interface. DMA access for ATAPI devices has to be enabled, - this can be done by adding the following line to the - <filename>/boot/loader.conf</filename> file:</para> + <para>DVD-RAM writers can use either a SCSI or ATAPI + interface. For ATAPI devices, DMA access has to be + enabled by adding the following line to + <filename>/boot/loader.conf</filename>:</para> <programlisting>hw.ata.atapi_dma="1"</programlisting> </sect3> <sect3> - <title>Preparing the Medium</title> + <title>Preparing the Media</title> - <para>As previously mentioned in the chapter introduction, a - DVD-RAM can be seen as a removable hard drive. As any other - hard drive the DVD-RAM must be <quote>prepared</quote> - before the first use. In the example, the whole - disk space will be used with a standard UFS2 file system:</para> + <para>A DVD-RAM can be seen as a removable hard drive. Like + any other hard drive, the DVD-RAM 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> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/acd0 count=2</userinput> + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/acd0 bs=2k count=1</userinput> &prompt.root; <userinput>bsdlabel -Bw acd0</userinput> &prompt.root; <userinput>newfs /dev/acd0</userinput></screen> @@ -1790,41 +1390,52 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect3> <sect3> - <title>Using the Medium</title> + <title>Using the Media</title> - <para>Once the previous operations have been performed on the - DVD-RAM, it can be mounted as a normal hard drive:</para> + <para>Once the DVD-RAM has been formatted, it can be mounted + as a normal hard drive:</para> <screen>&prompt.root; <userinput>mount /dev/acd0 /mnt</userinput></screen> - <para>After this the DVD-RAM will be both readable and writeable.</para> + <para>Once mounted, the DVD-RAM will be both readable and + writeable.</para> </sect3> </sect2> </sect1> <sect1 xml:id="floppies"> - <info><title>Creating and Using Floppy Disks</title> + <info> + <title>Creating and Using Floppy Disks</title> + <authorgroup> - <author><personname><firstname>Julio</firstname><surname>Merino</surname></personname><contrib>Original work by </contrib></author> + <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> + <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> + <para>This section explains how to use floppy disks in &os;. It + covers formatting and usage of 3.5inch DOS floppies, but the + concepts are similar for other floppy disk formats.</para> <sect2> <title>Formatting Floppies</title> @@ -1833,37 +1444,34 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <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</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 + <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. Although - it is possible to force larger (or smaller) disk sizes, - 1440kB is what most floppy disks are designed for.</para> + it is possible to force other 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>To low-level format the floppy disk, 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> + <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> + <para>To format the floppy, insert a new 3.5inch floppy + disk into the first floppy drive and issue:</para> <screen>&prompt.root; <userinput>/usr/sbin/fdformat -f 1440 /dev/fd0</userinput></screen> - </sect4> </sect3> </sect2> @@ -1871,33 +1479,32 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <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>After low-level formatting the disk, a disk label needs to + placed 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.</para> - <para>The new disk label will take over the whole disk, and will + <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> + <para>To write the disk label, use &man.bsdlabel.8;:</para> + <screen>&prompt.root; <userinput>/sbin/bsdlabel -B -w /dev/fd0 fd1440</userinput></screen> </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 is now ready to be high-level formatted. This + will place a new file system on it so that &os; can read and + write to the disk. Since creating the new file system + destroys the disk label, the disk label needs to be recreated + whenever the disk is reformatted.</para> <para>The floppy's file system can be either UFS or FAT. - FAT is generally a better choice for floppies.</para> + FAT is generally a better choice for floppies.</para> <para>To put a new file system on the floppy, issue:</para> @@ -1906,13 +1513,13 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <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.msdosfs.8;. One can also use - <package>emulators/mtools</package> from the ports - collection.</para> + <para>To use the floppy, mount it with &man.mount.msdosfs.8;. + One can also use + <package>emulators/mtools</package> from the + Ports Collection.</para> </sect2> </sect1> @@ -1920,543 +1527,344 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <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> + <para>Tape technology has continued to evolve but is less likely + to be used in a modern system. Modern backup systems tend to + use off site combined with local removable disk drive + technologies. Still, &os; will support any tape drive that + uses SCSI, such as LTO and older devices such as DAT. There is + limited support for SATA and USB tape drives.</para> - <indexterm> - <primary>tape media</primary> - <secondary>DDS (4mm) tapes</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 kB/s, peaking at ~500 kB/s. - Data capacity starts at 1.3 GB and ends at 2.0 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 GB.</para> - - <para>The DDS-3 standard now supports tape capacities up to 12 GB (or - 24 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="tapes-sa0"> + <title>Serial Access with &man.sa.4;</title> - <sect2 xml:id="backups-tapebackups-8mm"> - <title>8mm (Exabyte)</title> <indexterm> - <primary>tape media</primary> - <secondary>Exabyte (8mm) tapes</secondary> + <primary>tape drives</primary> </indexterm> - <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 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 kB/s to ~500 kB/s. Data sizes start - at 300 MB and go up to 7 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+ GB.</para> - - <para>The Exabyte <quote>Mammoth</quote> model supports 12 GB on one tape - (24 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> + <para>&os; uses the &man.sa.4; driver, providing + <filename>/dev/sa0</filename>, + <filename>/dev/nsa0</filename>, and + <filename>/dev/esa0</filename>. In normal use, only + <filename>/dev/sa0</filename> is needed. + <filename>/dev/nsa0</filename> is the same physical drive + as <filename>/dev/sa0</filename> but does not rewind the + tape after writing a file. This allows writing more than one + file to a tape. Using <filename>/dev/esa0</filename> + ejects the tape after the device is closed, if + applicable.</para> </sect2> - <sect2 xml:id="backups-tapebackups-qic"> - <title>QIC</title> - <indexterm> - <primary>tape media</primary> - <secondary>QIC-150</secondary> - </indexterm> - - <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 kB/s to ~500 kB/s. Data capacity - ranges from 40 MB to 15 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> + <sect2> + <title xml:id="tapes-mt">Controlling the Tape Drive with + &man.mt.1;</title> - <sect2 xml:id="backups-tapebackups-dlt"> - <title>DLT</title> <indexterm> - <primary>tape media</primary> - <secondary>DLT</secondary> + <primary>tape media</primary> + <secondary>mt</secondary> </indexterm> - <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 MB/s, three times the throughput of - 4mm, 8mm, or QIC tape drives. Data capacities range from 10 GB to 20 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 GB to 9 TB of - storage.</para> - - <para>With compression, DLT Type IV format supports up to 70 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>&man.mt.1; is the &os; utility for controlling other + operations of the tape drive, such as seeking through files on + a tape or writing tape control marks to the tape.</para> - <sect2> - <title xml:id="backups-tapebackups-ait">AIT</title> - <indexterm> - <primary>tape media</primary> - <secondary>AIT</secondary> - </indexterm> + <para>For example, the first three files on a tape can be + preserved by skipping past them before writing a new + file:</para> - <para>AIT is a new format from Sony, and can hold up to 50 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> + <screen>&prompt.root; <userinput>mt -f /dev/nsa0 fsf 3</userinput></screen> </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> + <title xml:id="tapes-tar">Using &man.tar.1; to Read and + Write Tape Backups</title> - <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> - - </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> + <para>An example of writing a single file to tape using + &man.tar.1;:</para> - <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> + <screen>&prompt.root; <userinput>tar cvf /dev/sa0 file</userinput></screen> - <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>Recovering files from a &man.tar.1; archive on tape into + the current directory:</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> + <screen>&prompt.root; <userinput>tar xvf /dev/sa0</userinput></screen> </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> - - <para>To backup all the files in the current directory and sub-directory - use this (as <systemitem class="username">root</systemitem>):</para> + <sect2> + <title xml:id="tapes-dumprestore">Using &man.dump.8; and + &man.restore.8; to Create and Restore Backups</title> - <screen>&prompt.root; <userinput>tar Mcvf /dev/fd0 *</userinput></screen> + <para>A simple backup of <filename>/usr</filename> with + &man.dump.8;:</para> - <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> + <screen>&prompt.root; <userinput>dump -0aL -b64 -f /dev/nsa0 /usr</userinput></screen> - <screen>Prepare volume #2 for /dev/fd0 and hit return:</screen> + <para>Interactively restoring files from a &man.dump.8; file on + tape into the current directory:</para> - <para>This is repeated (with the volume number incrementing) until all - the specified files have been archived.</para> + <screen>&prompt.root; <userinput>restore -i -f /dev/nsa0</userinput></screen> </sect2> - <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> - - <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> - - <sect2 xml:id="floppies-restoring"> - <title>How Do I Restore My Backups?</title> - - <para>To restore the entire archive use:</para> - - <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0</userinput></screen> - - <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> - - <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0 filename</userinput></screen> - - <para>The utility &man.tar.1; will prompt you to insert subsequent floppies until it - finds the required file.</para> - - <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> + <title xml:id="tapes-othersofware">Other Tape Software</title> + + <para>Higher-level programs are available to simplify tape + backup. The most popular are + <application>Amanda</application> and + <application>Bacula</application>. These programs aim to make + backups easier and more convenient, or to automate complex + backups of multiple machines. The Ports Collection contains + both these and other tape utility applications.</para> </sect2> </sect1> <sect1 xml:id="backup-strategies"> - <info><title>Backup Strategies</title> + <info> + <title>Backup Strategies</title> + <authorgroup> - <author><personname><firstname>Lowell</firstname><surname>Gilbert</surname></personname><contrib>Original work by </contrib></author> + <author> + <personname> + <firstname>Lowell</firstname> + <surname>Gilbert</surname> + </personname> + <contrib>Original work by </contrib> + </author> </authorgroup> - </info> - - - <para>The first requirement in devising a backup plan is to make sure that - all of the following problems are covered:</para> + <para>The first requirement in devising a backup plan is to make + sure that all of the following problems are covered:</para> <itemizedlist> <listitem> - <para>Disk failure</para> + <para>Disk failure.</para> </listitem> + <listitem> - <para>Accidental file deletion</para> + <para>Accidental file deletion.</para> </listitem> + <listitem> - <para>Random file corruption</para> + <para>Random file corruption.</para> </listitem> + <listitem> - <para>Complete machine destruction (e.g. fire), including destruction - of any on-site backups.</para> + <para>Complete machine destruction, say by fire, including + destruction of any on-site backups.</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>Some systems will be best served by having each of these + problems covered by a completely different technique. Except + for strictly personal systems with low-value data, it is + unlikely that one technique will cover all of them.</para> - <para>Some of the techniques in the toolbox are:</para> + <para>Some possible techniques include:</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> + <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. Copies of the backups can be stored on site + 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> + <para>Filesystem snapshots, which are really only helpful in + the accidental file deletion scenario, but can be + <emphasis>very</emphasis> helpful in that case, as well as + quick and easy to deal with.</para> </listitem> <listitem> - <para>Copies of whole filesystems and/or disks (e.g. periodic &man.rsync.1; 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> + <para>Copies of whole file systems or disks which can be + created with a periodic <package>net/rsync</package> of the + whole machine. This is generally most useful in networks + with unique requirements. For general protection against + disk failure, this is usually inferior to + <acronym>RAID</acronym>. For restoring accidentally deleted + files, it can be comparable to <acronym>UFS</acronym> + snapshots.</para> </listitem> <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> + <para><acronym>RAID</acronym>, which minimizes or avoids + downtime when a disk fails at the expense of having to deal + with disk failures more often, because there are more disks, + albeit at a much lower urgency.</para> </listitem> <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> + <para>Checking fingerprints of files using &man.mtree.8;. + Although this is not a backup, this technique indicates + when one needs to resort to backups. This is particularly + important for offline backups, and should be checked + periodically.</para> </listitem> </itemizedlist> - <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> + <para>It is quite easy to come up with more techniques, many + of them variations on the ones listed above. Specialized + requirements 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 which dangers should be protected + against, and how each will be handled.</para> </sect1> <sect1 xml:id="backup-basics"> <title>Backup Basics</title> - <para>The three major backup programs are - &man.dump.8;, - &man.tar.1;, - and - &man.cpio.1;.</para> + <para>The major backup programs built into &os; are + &man.dump.8;, &man.tar.1;, &man.cpio.1;, and + &man.pax.1;.</para> <sect2> <title>Dump and Restore</title> + <indexterm> - <primary>backup software</primary> + <primary>backup software</primary> <secondary>dump / restore</secondary> </indexterm> - <indexterm><primary><command>dump</command></primary></indexterm> - <indexterm><primary><command>restore</command></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&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> + abstractions of files, links and directories that are created + by the file systems. Unlike other backup software, + <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, + but rather writes the raw data blocks that comprise files and + directories. When used to extract 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> + + <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> + + <para><command>dump</command> has quirks that remain from its + early days in Version 6 of AT&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> + 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 <filename>.rhosts</filename> on + the remote computer. The arguments to + <command>rdump</command> and <command>rrestore</command> must + be suitable to use on the remote computer. For example, to + <command>rdump</command> from a &os; computer to an Exabyte + tape drive connected to a host called + <systemitem>komodo</systemitem>, use:</para> <screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1</userinput></screen> - <para>Beware: there are security implications to - allowing <filename>.rhosts</filename> authentication. Evaluate your - situation carefully.</para> + <para>There are security implications to allowing + <filename>.rhosts</filename> authentication, so use + with caution.</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> + <command>restore</command> in a more secure fashion over + <command>ssh</command>.</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>Or, use the built-in <envar>RSH</envar>:</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> + <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&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 + <para>&man.tar.1; also dates back to Version 6 of AT&T + &unix;, circa 1975. <command>tar</command> operates in + cooperation with the file system and 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> <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> - - <screen>&prompt.root; <userinput>/usr/bin/gtar cf komodo:/dev/nsa8 . 2>&1</userinput></screen> + <para>To <command>tar</command> to an Exabyte tape drive + connected to a host called + <systemitem>komodo</systemitem>:</para> - <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 cf - . | rsh hostname dd of=tape-device obs=20b</userinput></screen> + <screen>&prompt.root; <userinput>tar cf - . | rsh komodo dd of=tape-device obs=20b</userinput></screen> - <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> + <para>When backing up over an insecure network, instead use + <command>ssh</command>.</para> </sect2> <sect2> <title><command>cpio</command></title> + <indexterm> - <primary>backup software</primary> - <secondary><command>cpio</command></secondary> + <primary>backup software</primary> + <secondary><command>cpio</command></secondary> </indexterm> <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 + program for magnetic media. <command>cpio</command> includes + options 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> + <indexterm> + <primary><command>cpio</command></primary> + </indexterm> + + <para>Since <command>cpio</command> does not support backups + across the network, use a pipeline and <command>ssh</command> to send the data to a remote tape drive.</para> <screen>&prompt.root; <userinput>for f in directory_list; do</userinput> @@ -2464,109 +1872,127 @@ sa0(ncr1:4:0): Logical unit is in process of becoming ready</screen> <userinput>done</userinput> &prompt.root; <userinput>cpio -v -o --format=newc < backup.list | ssh user@host "cat > 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> + <para>Where <replaceable>directory_list</replaceable> is the + list of directories 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, such as + <filename>/dev/nsa0</filename>).</para> </sect2> <sect2> <title><command>pax</command></title> + <indexterm> - <primary>backup software</primary> - <secondary><command>pax</command></secondary> + <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.pax.1; is IEEE/&posix;'s answer to + <para>&man.pax.1; is the IEEE/&posix; 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 + <command>cpio</command> have become 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> + 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> <sect2 xml:id="backups-programs-amanda"> <title><application>Amanda</application></title> + + <indexterm> + <primary>backup software</primary> + <secondary><application>Amanda</application></secondary> + </indexterm> <indexterm> - <primary>backup software</primary> - <secondary><application>Amanda</application></secondary> + <primary><application>Amanda</application></primary> </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> + 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 by using + 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 grained 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 not installed by + but is available as either a port or package.</para> + </sect2> <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><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>If your time and data is worth little to nothing, then + <quote>Do nothing</quote> is the most suitable backup program + for the computer. But beware, &os; is a useful tool and + over time it can be used to create a valuable collection of + files.</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> + <filename>/usr/obj</filename> and other + directory trees that can be exactly recreated by the computer. + An example is the files that comprise the HTML or &postscript; + version of this Handbook. These document formats have been + created from XML input files. Creating backups of the HTML or + &postscript; files is not necessary if the XML files are + backed up regularly.</para> </sect2> <sect2> <title>Which Backup Program Is Best?</title> + <indexterm> - <primary>LISA</primary> + <primary>LISA</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 + <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://www.coredumps.de/doc/dump/zwicky/testdump.doc.html">torture-testing Backup and Archive Programs</link>.</para> </sect2> @@ -2576,291 +2002,136 @@ sa0(ncr1:4:0): Logical unit is in process of becoming ready</screen> <sect3> <title>Before the Disaster</title> - <para>There are only four steps that you need to perform in + <para>There are four steps which should be performed 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 - -fdformat -q fd0 -if [ $? -ne 0 ] -then - echo "Bad floppy, please use a new one" - exit 1 -fi - -# place boot blocks on the floppy -# -bsdlabel -w -B /dev/fd0c fd1440 - -# -# newfs the one and only partition -# -newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/fd0a - -# -# mount the new floppy -# -mount /dev/fd0a /mnt - -# -# 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 - -# -# populate the directories -# -if [ ! -x /sys/compile/MINI/kernel ] -then - cat << 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 - -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 - -config kernel root on da0 swap on da0 and da1 dumps on da0 - -device isa0 -device pci0 - -device fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr -device fd0 at fdc0 drive 0 - -device ncr0 - -device scbus0 - -device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr -device npx0 at isa? port "IO_NPX" irq 13 vector npxintr - -device da0 -device da1 -device da2 - -device sa0 - -pseudo-device loop # required by INET -pseudo-device gzip # Exec gzipped a.out's -EOM - exit 1 -fi - -cp -f /sys/compile/MINI/kernel /mnt - -gzip -c -best /sbin/init > /mnt/sbin/init -gzip -c -best /sbin/fsck > /mnt/sbin/fsck -gzip -c -best /sbin/mount > /mnt/sbin/mount -gzip -c -best /sbin/halt > /mnt/sbin/halt -gzip -c -best /sbin/restore > /mnt/sbin/restore - -gzip -c -best /bin/sh > /mnt/bin/sh -gzip -c -best /bin/sync > /mnt/bin/sync - -cp /root/.profile /mnt/root - -cp -f /dev/MAKEDEV /mnt/dev -chmod 755 /mnt/dev/MAKEDEV - -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 - -# -# create the devices nodes -# -cd /mnt/dev -./MAKEDEV std -./MAKEDEV da0 -./MAKEDEV da1 -./MAKEDEV da2 -./MAKEDEV sa0 -./MAKEDEV pty0 -cd / - -# -# create minimum file system table -# -cat > /mnt/etc/fstab <<EOM -/dev/fd0a / ufs rw 1 1 -EOM - -# -# create minimum passwd file -# -cat > /mnt/etc/passwd <<EOM -root:*:0:0:Charlie &:/root:/bin/sh -EOM - -cat > /mnt/etc/master.passwd <<EOM -root::0:0::0:0:Charlie &:/root:/bin/sh -EOM - -chmod 600 /mnt/etc/master.passwd -chmod 644 /mnt/etc/passwd -/usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd - -# -# umount the floppy and inform the user -# -/sbin/umount /mnt -echo "The floppy has been unmounted and is now ready."]]></programlisting> - - </example> - + <primary><command>bsdlabel</command></primary> + </indexterm> + + <para>First, print the bsdlabel of each disk using a command + such as <command>bsdlabel da0 | lpr</command>. Also print a + copy of <filename>/etc/fstab</filename> and all boot + messages.</para> + + <indexterm><primary>livefs CD</primary></indexterm> + <para>Second, burn a <quote>livefs</quote> CD. This CD + contains support for booting into a &os; + <quote>livefs</quote> rescue mode, allowing the user to + perform many tasks like running &man.dump.8;, + &man.restore.8;, &man.fdisk.8;, &man.bsdlabel.8;, + &man.newfs.8;, &man.mount.8;, and more. The livefs CD image + for &os;/&arch.i386; &rel2.current;-RELEASE is + available 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> + <para>Livefs CD images are not available for + &os; &rel.current;-RELEASE and later. In addition to + the CD-ROM installation images, flash drive installation + images may be used to recover a system. The + <quote>memstick</quote> image for + &os;/&arch.i386; &rel.current;-RELEASE is available + from <uri + xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img</uri>.</para> + </note> + + <para>Third, create backup tapes regularly. Any changes that + made after the last backup may be irretrievably lost. + Write-protect the backup media.</para> + + <para>Fourth, test the <quote>livefs</quote> CD and the + backups. Make notes of the procedure. Store these notes + with the CD, 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> + + <para>For an added measure of security, store an extra + <quote>livefs</quote> CD and the latest backup at a + remote location, where a remote location is + <emphasis>not</emphasis> the basement of the same building. + A remote location should be physically separated from the + computers and disk drives by a significant distance.</para> </sect3> <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>First, determine if the hardware survived. Thanks + to regular, off-site backups, 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 the hardware is okay, insert the + <quote>livefs</quote> CD and boot the computer. The + original install menu will be displayed on the screen. + Select the correct country, then choose + <guimenuitem>Fixit -- Repair mode with CD-ROM/DVD/floppy or + start a shell.</guimenuitem> then select + <guimenuitem>CD-ROM/DVD -- Use the live filesystem + CD-ROM/DVD</guimenuitem>. + <command>restore</command> and the other needed programs + are located in <filename>/mnt2/rescue</filename>.</para> <para>Recover each file system separately.</para> <indexterm> - <primary><command>mount</command></primary> - </indexterm> + <primary><command>mount</command></primary> + </indexterm> <indexterm><primary>root partition</primary></indexterm> <indexterm> - <primary><command>bsdlabel</command></primary> - </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> + <primary><command>newfs</command></primary> + </indexterm> + + <para>Try to <command>mount</command> the root partition + of the first disk using <command>mount /dev/da0a + /mnt</command>. If the bsdlabel was damaged, use + <command>bsdlabel</command> to re-partition and label the + disk to match the label that was printed and saved. Use + <command>newfs</command> to re-create the file systems. + Re-mount the root partition of the disk read-write using + <command>mount -u -o rw /mnt</command>. Use the backups + to recover the data for this file system. Unmount the file + system with <command>umount /mnt</command>. Repeat for each + file system that was damaged.</para> + + <para>Once the system is running, backup the data onto new + media as whatever caused the crash or data loss may strike + again. Another hour spent now may save further distress + later.</para> </sect3> </sect2> </sect1> <sect1 xml:id="disks-virtual"> - <info><title>Network, Memory, and File-Backed File Systems</title> + <info> + <title>Network, Memory, and File-Backed File Systems</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> + <para>In addition to physical disks such as floppies, CDs, and + hard drives, &os; also supports + <firstterm>virtual disks</firstterm>.</para> <indexterm><primary>NFS</primary></indexterm> <indexterm><primary>Coda</primary></indexterm> @@ -2868,53 +2139,55 @@ echo "The floppy has been unmounted and is now ready."]]></programlisting> <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>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>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>According to the &os; version, the tools used for the + creation and use of file-backed and memory-based file systems + differ.</para> <note> - <para>Use &man.devfs.5; to allocate device nodes transparently for the - user.</para> + <para>Use &man.devfs.5; to allocate device nodes transparently + for the user.</para> </note> <sect2 xml:id="disks-mdconfig"> <title>File-Backed File System</title> + <indexterm> - <primary>disks</primary> - <secondary>file-backed</secondary> + <primary>disks</primary> + <secondary>file-backed</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> + <para>&man.mdconfig.8; is used to configure and enable memory + disks, &man.md.4;, under &os;. To use &man.mdconfig.8;, + &man.md.4; must be first loaded. When using a custom kernel + configuration file, ensure it includes this line:</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>&man.mdconfig.8; supports several types of memory backed + virtual disks: memory disks allocated with &man.malloc.9; and + memory disks using a file or swap space as backing. One + possible use is the mounting of CD images.</para> <para>To mount an existing file system image:</para> <example> - <title>Using <command>mdconfig</command> to Mount an Existing File System - Image</title> + <title>Using <command>mdconfig</command> to Mount an Existing + File System Image</title> <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> + <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> + <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 @@ -2932,24 +2205,25 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0a 4710 4 4330 0% /mnt</screen> </example> - <para>If you do not specify the unit number with the - <option>-u</option> option, &man.mdconfig.8; will use the + <para>If unit number is not specified with + <option>-u</option>, &man.mdconfig.8; uses 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> + The name of the allocated unit will be output to stdout, such + as <filename>md4</filename>. Refer to &man.mdconfig.8; + for more details about.</para> + + <para>While &man.mdconfig.8; is useful, it takes several + command lines to create a file-backed file system. &os; also + comes with &man.mdmfs.8; which automatically 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, to create and mount the same file system image as + above, type the following:</para> <example> - <title>Configure and Mount a File-Backed Disk with <command>mdmfs</command></title> + <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 @@ -2959,30 +2233,29 @@ 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 + <para>When <option>md</option> is used without a unit number, + &man.mdmfs.8; uses the &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> - + about &man.mdmfs.8;, refer to its manual page.</para> </sect2> <sect2 xml:id="disks-md-freebsd5"> <title>Memory-Based File System</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 + <para>For a memory-based file system, <quote>swap + backing</quote> should normally be used. This 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 + but rather 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> + also possible to create memory-based disks which are + &man.malloc.9; backed, but using large malloc backed memory + disks can result in a system panic if the kernel runs out of + memory.</para> <example> <title>Creating a New Memory-Based Disk with @@ -3004,6 +2277,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <example> <title>Creating a New Memory-Based Disk with <command>mdmfs</command></title> + <screen>&prompt.root; <userinput>mdmfs -s 5m md2 /mnt</userinput> &prompt.root; <userinput>df /mnt</userinput> Filesystem 1K-blocks Used Avail Capacity Mounted on @@ -3013,133 +2287,141 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <sect2> <title>Detaching a Memory Disk from the System</title> + <indexterm> - <primary>disks</primary> - <secondary>detaching a memory disk</secondary> + <primary>disks</primary> + <secondary>detaching a memory disk</secondary> </indexterm> - <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> + <para>When a memory-based or file-based file system is no + longer in use, its resources should be released back to + the system. First, unmount the file system, then use + &man.mdconfig.8; to detach the disk from the system and + release the resources.</para> - <para>For example to detach and free all resources used by + <para>For example, to detach and free all resources used by <filename>/dev/md4</filename>:</para> <screen>&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen> <para>It is possible to list information about configured - &man.md.4; devices in using the command <command>mdconfig - -l</command>.</para> + &man.md.4; devices by running + <command>mdconfig -l</command>.</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>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, 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 CDs 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> - <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> + <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> + </itemizedlist> -<screen>&prompt.root; <userinput>umount /mnt</userinput> + <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> &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"> <title>File System Quotas</title> + <indexterm> <primary>accounting</primary> <secondary>disk space</secondary> @@ -3147,145 +2429,139 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <indexterm><primary>disk quotas</primary></indexterm> <para>Quotas are an optional feature of the operating system that - allow you to limit the amount of disk space and/or the number of + can be used to limit the amount of disk space or the number of files a user or members of a group may allocate on a per-file - system basis. This is used most often on timesharing systems where - it is desirable to limit the amount of resources any one user or - group of users may allocate. This will prevent one user or group - of users from consuming all of the available disk space.</para> + system basis. This is used most often on timesharing systems + where it is desirable to limit the amount of resources any one + user or group of users may allocate. This prevents one user or + group of users from consuming all of the available disk + space.</para> <sect2> - <title>Configuring Your System to Enable Disk Quotas</title> + <title>Configuring the System to Enable Disk Quotas</title> - <para>Before attempting to use disk quotas, it is necessary to make - sure that quotas are configured in your kernel. This is done by - adding the following line to your kernel configuration - file:</para> + <para>Before using disk quotas, quota support must be added to + the kernel by adding the following line to the kernel + configuration file:</para> <programlisting>options QUOTA</programlisting> - <para>The stock <filename>GENERIC</filename> kernel does not have - this enabled by default, so you will have to configure, build and - install a custom kernel in order to use disk quotas. Please refer - to <xref linkend="kernelconfig"/> for more information on kernel - configuration.</para> + <para>Before &os; 9.2, the <filename>GENERIC</filename> + kernel usually did not include this option. + <command>sysctl kern.features.ufs_quota</command> can be used + to test whether the current kernel supports quotas. If the + option is not present, a custom kernel must be compiled. + Refer to <xref linkend="kernelconfig"/> for more information + on kernel configuration.</para> - <para>Next you will need to enable disk quotas in - <filename>/etc/rc.conf</filename>. This is done by adding the - line:</para> + <para>Next, enable disk quotas in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>quota_enable="YES"</programlisting> - <programlisting>enable_quotas="YES"</programlisting> <indexterm> - <primary>disk quotas</primary> - <secondary>checking</secondary> + <primary>disk quotas</primary> + <secondary>checking</secondary> </indexterm> - <para>For finer control over your quota startup, there is an - additional configuration variable available. Normally on bootup, - the quota integrity of each file system is checked by the - &man.quotacheck.8; program. The - &man.quotacheck.8; facility insures that the data in - the quota database properly reflects the data on the file system. - This is a very time consuming process that will significantly - affect the time your system takes to boot. If you would like to - skip this step, a variable in <filename>/etc/rc.conf</filename> - is made available for the purpose:</para> + <para>For finer control over quota startup, an additional + configuration variable is available. Normally on bootup, the + quota integrity of each file system is checked by + &man.quotacheck.8;. This program insures that the data in the + quota database properly reflects the data on the file system. + This is a time consuming process that will significantly + affect the time the system takes to boot. To skip this step, + add this variable to <filename>/etc/rc.conf</filename>:</para> <programlisting>check_quotas="NO"</programlisting> - <para>Finally you will need to edit <filename>/etc/fstab</filename> - to enable disk quotas on a per-file system basis. This is where - you can either enable user or group quotas or both for all of your - file systems.</para> + <para>Finally, edit <filename>/etc/fstab</filename> to enable + disk quotas on a per-file system basis. This is when user or + group quotas can be enabled on the file systems.</para> - <para>To enable per-user quotas on a file system, add the - <option>userquota</option> option to the options field in the - <filename>/etc/fstab</filename> entry for the file system you want - to enable quotas on. For example:</para> + <para>To enable per-user quotas on a file system, add + <option>userquota</option> to the options field in the + <filename>/etc/fstab</filename> entry for the file system to + enable quotas on. For example:</para> <programlisting>/dev/da1s2g /home ufs rw,userquota 1 2</programlisting> - <para>Similarly, to enable group quotas, use the - <option>groupquota</option> option instead of - <option>userquota</option>. To enable both user and - group quotas, change the entry as follows:</para> + <para>To enable group quotas, instead use + <option>groupquota</option>. To enable both user and group + quotas, change the entry as follows:</para> <programlisting>/dev/da1s2g /home ufs rw,userquota,groupquota 1 2</programlisting> - <para>By default, the quota files are stored in the root directory of - the file system with the names <filename>quota.user</filename> and - <filename>quota.group</filename> for user and group quotas - respectively. See &man.fstab.5; for more - information. Even though the &man.fstab.5; manual page says that - you can specify - an alternate location for the quota files, this is not recommended - because the various quota utilities do not seem to handle this + <para>By default, the quota files are stored in the root + directory of the file system as + <filename>quota.user</filename> and + <filename>quota.group</filename>. Refer to &man.fstab.5; for + more information. Even though an alternate location for the + quota files can be specified, this is not recommended because + the various quota utilities do not seem to handle this properly.</para> - <para>At this point you should reboot your system with your new - kernel. <filename>/etc/rc</filename> will automatically run the - appropriate commands to create the initial quota files for all of - the quotas you enabled in <filename>/etc/fstab</filename>, so - there is no need to manually create any zero length quota - files.</para> - - <para>In the normal course of operations you should not be required - to run the &man.quotacheck.8;, - &man.quotaon.8;, or &man.quotaoff.8; - commands manually. However, you may want to read their manual pages - just to be familiar with their operation.</para> + <para>Once the configuration is complete, reboot the system + with the new kernel. <filename>/etc/rc</filename> will + automatically run the appropriate commands to create the + initial quota files for all of the quotas enabled in + <filename>/etc/fstab</filename>. There is no need to + manually create any zero length quota files.</para> + + <para>In the normal course of operations, there should be no + need to manually run &man.quotacheck.8;, &man.quotaon.8;, or + &man.quotaoff.8;. However, one should read their manual pages + to be familiar with their operation.</para> </sect2> <sect2> <title>Setting Quota Limits</title> + <indexterm> - <primary>disk quotas</primary> - <secondary>limits</secondary> + <primary>disk quotas</primary> + <secondary>limits</secondary> </indexterm> - <para>Once you have configured your system to enable quotas, verify - that they really are enabled. An easy way to do this is to - run:</para> + <para>Once the system has been configured to enable quotas, + verify they really are enabled by running:</para> <screen>&prompt.root; <userinput>quota -v</userinput></screen> - <para>You should see a one line summary of disk usage and current - quota limits for each file system that quotas are enabled - on.</para> + <para>There should be a one line summary of disk usage and + current quota limits for each file system that quotas are + enabled on.</para> - <para>You are now ready to start assigning quota limits with the - &man.edquota.8; command.</para> + <para>The system is now ready to be assigned quota limits with + &man.edquota.8;.</para> - <para>You have several options on how to enforce limits on the - amount of disk space a user or group may allocate, and how many - files they may create. You may limit allocations based on disk - space (block quotas) or number of files (inode quotas) or a - combination of both. Each of these limits are further broken down + <para>Several options are available to enforce limits on the + amount of disk space a user or group may allocate, and how + many files they may create. Allocations can be limited based + on disk space (block quotas), number of files (inode quotas), + or a combination of both. Each limits is further broken down into two categories: hard and soft limits.</para> <indexterm><primary>hard limit</primary></indexterm> - <para>A hard limit may not be exceeded. Once a user reaches his - hard limit he may not make any further allocations on the file - system in question. For example, if the user has a hard limit of - 500 kbytes on a file system and is currently using 490 kbytes, the - user can only allocate an additional 10 kbytes. Attempting to - allocate an additional 11 kbytes will fail.</para> + <para>A hard limit may not be exceeded. Once a user reaches a + hard limit, no further allocations can be made on that file + system by that user. For example, if the user has a hard + limit of 500 kbytes on a file system and is currently using + 490 kbytes, the user can only allocate an additional 10 + kbytes. Attempting to allocate an additional 11 kbytes will + fail.</para> <indexterm><primary>soft limit</primary></indexterm> - <para>Soft limits, on the other hand, can be exceeded for a limited - amount of time. This period of time is known as the grace period, - which is one week by default. If a user stays over his or her - soft limit longer than the grace period, the soft limit will - turn into a hard limit and no further allocations will be allowed. - When the user drops back below the soft limit, the grace period - will be reset.</para> - - <para>The following is an example of what you might see when you run - the &man.edquota.8; command. When the - &man.edquota.8; command is invoked, you are placed into - the editor specified by the <envar>EDITOR</envar> environment - variable, or in the <application>vi</application> editor if the - <envar>EDITOR</envar> variable is not set, to allow you to edit - the quota limits.</para> + <para>Soft limits can be exceeded for a limited amount of time, + known as the grace period, which is one week by default. If a + user stays over their limit longer than the grace period, the + soft limit turns into a hard limit and no further allocations + are allowed. When the user drops back below the soft limit, + the grace period is reset.</para> + + <para>The following is an example output from &man.edquota.8;. + When &man.edquota.8; is invoked, the editor specified by + <envar>EDITOR</envar> is opened in order to edit the quota + limits. The default editor is set to + <application>vi</application>.</para> <screen>&prompt.root; <userinput>edquota -u test</userinput></screen> @@ -3295,12 +2571,13 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on /usr/var: kbytes in use: 0, limits (soft = 50, hard = 75) inodes in use: 0, limits (soft = 50, hard = 60)</programlisting> - <para>You will normally see two lines for each file system that has - quotas enabled. One line for the block limits, and one line for - inode limits. Simply change the value you want updated to modify - the quota limit. For example, to raise this user's block limit - from a soft limit of 50 and a hard limit of 75 to a soft limit of - 500 and a hard limit of 600, change:</para> + <para>There are normally two lines for each file system that + has quotas enabled. One line represents the block limits and + the other represents the inode limits. Change the value to + modify the quota limit. For example, to raise this + user's block limit from a soft limit of 50 and a hard limit of + 75 to a soft limit of 500 and a hard limit of 600, + change:</para> <programlisting>/usr: kbytes in use: 65, limits (soft = 50, hard = 75)</programlisting> @@ -3308,44 +2585,43 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <programlisting>/usr: kbytes in use: 65, limits (soft = 500, hard = 600)</programlisting> - <para>The new quota limits will be in place when you exit the + <para>The new quota limits take affect upon exiting the editor.</para> - <para>Sometimes it is desirable to set quota limits on a range of - UIDs. This can be done by use of the <option>-p</option> option - on the &man.edquota.8; command. First, assign the - desired quota limit to a user, and then run + <para>Sometimes it is desirable to set quota limits on a range + of UIDs. This can be done by passing <option>-p</option> to + &man.edquota.8;. First, assign the desired quota limit to a + user, then run <command>edquota -p protouser startuid-enduid</command>. For - example, if user <systemitem class="username">test</systemitem> has the desired quota - limits, the following command can be used to duplicate those quota - limits for UIDs 10,000 through 19,999:</para> + example, if <systemitem class="username">test</systemitem> has + the desired quota limits, the following command will duplicate + those quota limits for UIDs 10,000 through 19,999:</para> <screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen> - <para>For more information see &man.edquota.8; manual page.</para> + <para>For more information, refer to &man.edquota.8;.</para> </sect2> <sect2> <title>Checking Quota Limits and Disk Usage</title> + <indexterm> - <primary>disk quotas</primary> - <secondary>checking</secondary> + <primary>disk quotas</primary> + <secondary>checking</secondary> </indexterm> - <para>You can use either the &man.quota.1; or the - &man.repquota.8; commands to check quota limits and - disk usage. The &man.quota.1; command can be used to - check individual user or group quotas and disk usage. A user - may only examine his own quota, and the quota of a group he - is a member of. Only the super-user may view all user and group - quotas. The - &man.repquota.8; command can be used to get a summary - of all quotas and disk usage for file systems with quotas - enabled.</para> - - <para>The following is some sample output from the - <command>quota -v</command> command for a user that has quota - limits on two file systems.</para> + <para>Either &man.quota.1; or &man.repquota.8; can be used to + check quota limits and disk usage. To check individual user + or group quotas and disk usage, use &man.quota.1;. A user + may only examine their own quota and the quota of a group they + are a member of. Only the superuser may view all user and + group quotas. To get a summary of all quotas and disk usage + for file systems with quotas enabled, use + &man.repquota.8;.</para> + + <para>The following is sample output from + <command>quota -v</command> for a user that has quota limits + on two file systems.</para> <programlisting>Disk quotas for user test (uid 1002): Filesystem usage quota limit grace files quota limit grace @@ -3353,29 +2629,31 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on /usr/var 0 50 75 0 50 60</programlisting> <indexterm><primary>grace period</primary></indexterm> - <para>On the <filename>/usr</filename> file system in the above - example, this user is currently 15 kbytes over the soft limit of - 50 kbytes and has 5 days of the grace period left. Note the - asterisk <literal>*</literal> which indicates that the user is - currently over his quota limit.</para> - - <para>Normally file systems that the user is not using any disk - space on will not show up in the output from the - &man.quota.1; command, even if he has a quota limit - assigned for that file system. The <option>-v</option> option - will display those file systems, such as the - <filename>/usr/var</filename> file system in the above + + <para>In this example, the user is currently 15 kbytes over the + soft limit of 50 kbytes on <filename>/usr</filename> and has 5 + days of grace period left. The asterisk <literal>*</literal> + indicates that the user is currently over the quota + limit.</para> + + <para>Normally, file systems that the user is not using any disk + space on will not show in the output of &man.quota.1;, even if + the user has a quota limit assigned for that file system. Use + <option>-v</option> to display those file systems, such as + <filename>/usr/var</filename> in the above example.</para> </sect2> <sect2> <title>Quotas over NFS</title> + <indexterm><primary>NFS</primary></indexterm> - <para>Quotas are enforced by the quota subsystem on the NFS server. - The &man.rpc.rquotad.8; daemon makes quota information available - to the &man.quota.1; command on NFS clients, allowing users on - those machines to see their quota statistics.</para> + <para>Quotas are enforced by the quota subsystem on the NFS + server. The &man.rpc.rquotad.8; daemon makes quota + information available to &man.quota.1; on NFS clients, + allowing users on those machines to see their quota + statistics.</para> <para>Enable <command>rpc.rquotad</command> in <filename>/etc/inetd.conf</filename> like so:</para> @@ -3384,235 +2662,248 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <para>Now restart <command>inetd</command>:</para> - <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen> + <screen>&prompt.root; <userinput>service inetd restart</userinput></screen> </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> + <secondary>encrypting</secondary> + </indexterm> + + <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, both the GEOM Based + Disk Encryption (<command>gbde</command>) 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> + <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> + superuser privileges.</para> <screen>&prompt.user; <userinput>su -</userinput> Password:</screen> </step> <step> - <title>Add &man.gbde.4; Support to the Kernel Configuration File</title> - - <para>Add the following line to the kernel configuration - file:</para> + <para>If using a custom kernel configuration file, ensure it + contains this line:</para> <para><literal>options GEOM_BDE</literal></para> - <para>Rebuild the kernel as described in <xref linkend="kernelconfig"/>.</para> + <para>If the kernel already contains this support, use + <command>kldload</command> to load &man.gbde.4;:</para> - <para>Reboot into the new kernel.</para> + <screen>&prompt.root; <userinput>kldload geom_bde</userinput></screen> </step> - - <step> - <para>An alternative to recompiling the kernel is to use - <command>kldload</command> to load &man.gbde.4;:</para> - - <screen>&prompt.root; <userinput>kldload geom_bde</userinput></screen> - </step> </procedure> - <sect3> - <title>Preparing the Encrypted Hard Drive</title> - - <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> - - <procedure> - <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> - - <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> + <sect3> + <title>Preparing the Encrypted Hard Drive</title> + + <para>The following example demonstrates adding a new hard + drive to a 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> + + <procedure> + <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> and + <filename>/dev/ad0s1*</filename> + represents the existing standard &os; partitions.</para> + + <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c /dev/ad0s1a /dev/ad0s1d /dev/ad4</screen> - </step> + </step> - <step> - <title>Create a Directory to Hold gbde 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> - </step> + <step> + <title>Create a Directory to Hold <command>gbde</command> + Lock Files</title> - <step> - <title>Initialize the gbde Partition</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> + </step> + + <step> + <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> + <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> + <screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c.lock</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> + <para>&man.gbde.8; will open the default editor, in order + 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 $ + <programlisting># $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> - - <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> - </caution> - </step> - - <step> - <title>Attach the Encrypted Partition to the Kernel</title> - - <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</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 - <filename>/dev</filename> as - <filename>/dev/device_name.bde</filename>:</para> - - <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> +sector_size = 2048 +[...]</programlisting> + + <para>&man.gbde.8; will ask the user 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 the <link + xlink:href="http://world.std.com/~reinhold/diceware.html">Diceware + Passphrase</link> website.</para> + + <para><command>gbde init</command>creates a lock file for + the <application>gbde</application> partition. In this + example, it is stored as + <filename>/etc/gbde/ad4s1c.lock</filename>. + <application>gbde</application> 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;.</para> + </caution> + </step> + + <step> + <title>Attach the Encrypted Partition to the + Kernel</title> + + <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen> + + <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> + + <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c /dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde</screen> - </step> + </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> - </step> + <step> + <title>Create a File System on the Encrypted + Device</title> - <step> - <title>Mount the Encrypted Partition</title> + <para>Once the encrypted device has been attached to the + kernel, a file system can be created on the device using + &man.newfs.8;. This example creates a UFS2 file + system with soft updates enabled.</para> - <para>Create a mount point for the encrypted file system.</para> + <screen>&prompt.root; <userinput>newfs -U /dev/ad4s1c.bde</userinput></screen> - <screen>&prompt.root; <userinput>mkdir /private</userinput></screen> + <note> + <para>&man.newfs.8; 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> + </step> - <para>Mount the encrypted file system.</para> + <step> + <title>Mount the Encrypted Partition</title> - <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen> - </step> + <para>Create a mount point for the encrypted file + system:</para> - <step> - <title>Verify That the Encrypted File System is Available</title> + <screen>&prompt.root; <userinput>mkdir /private</userinput></screen> - <para>The encrypted file system should now be visible to - &man.df.1; and be available for use.</para> + <para>Mount the encrypted file system:</para> + + <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen> + </step> - <screen>&prompt.user; <userinput>df -H</userinput> + <step> + <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> + + <screen>&prompt.user; <userinput>df -H</userinput> Filesystem Size Used Avail Capacity Mounted on /dev/ad0s1a 1037M 72M 883M 8% / /devfs 1.0K 1.0K 0B 100% /dev @@ -3620,233 +2911,245 @@ Filesystem Size Used Avail Capacity Mounted on /dev/ad0s1e 1037M 1.1M 953M 0% /tmp /dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr /dev/ad4s1c.bde 150G 4.1K 138G 0% /private</screen> - </step> - </procedure> - </sect3> + </step> + </procedure> + </sect3> - <sect3> - <title>Mounting Existing Encrypted File Systems</title> + <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> + <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 + <systemitem class="username">root</systemitem>.</para> - <procedure> - <step> - <title>Attach the gbde Partition to the Kernel</title> + <procedure> + <step> + <title>Attach the <command>gbde</command> 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 initialization of the encrypted - <application>gbde</application> partition.</para> - </step> + <para>This command will prompt for the passphrase that was + selected during initialization of the encrypted + <application>gbde</application> partition.</para> + </step> - <step> - <title>Check the File System for Errors</title> + <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> + <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> + <screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput></screen> + </step> - <step> - <title>Mount the Encrypted File System</title> + <step> + <title>Mount the Encrypted File System</title> - <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen> + <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen> - <para>The encrypted file system is now available for use.</para> - </step> - </procedure> + <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 an alternative, an <filename>rc.d</filename> script is - 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> + <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 an alternative, an <filename>rc.d</filename> script + is provided. Arguments for this script can be passed via + &man.rc.conf.5;:</para> + + <programlisting>gbde_autoattach_all="YES" +gbde_devices="ad4s1c" +gbde_lockdir="/etc/gbde"</programlisting> + + <para>This requires 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 useful when using + <application>gbde</application> on laptops.</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> + <title>Cryptographic Protections Employed by + <command>gbde</command></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 the + cryptographic design, including how the sector keys are + derived from the user-supplied passphrase, refer to + &man.gbde.4;.</para> </sect3> <sect3> <title>Compatibility Issues</title> <para>&man.sysinstall.8; 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> + <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 + the 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> - </sect2> <sect2> - <info><title>Disk Encryption with <command>geli</command></title> + <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 + <para>An alternative cryptographic GEOM class is available + through &man.geli.8;. <command>geli</command> differs from + <command>gbde</command>; 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>&man.geli.8; provides the following features:</para> <itemizedlist> <listitem> - <para>Utilizes the &man.crypto.9; framework — when - cryptographic hardware is available, <command>geli</command> - will use it automatically.</para> + <para>Utilizes the &man.crypto.9; framework and, when + cryptographic hardware is available, + <command>geli</command> uses it automatically.</para> </listitem> + <listitem> - <para>Supports multiple cryptographic algorithms (currently - AES, Blowfish, and 3DES).</para> + <para>Supports multiple cryptographic algorithms such as + AES, Blowfish, and 3DES.</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 such as a + <quote>key</quote> and a + <quote>company key</quote>.</para> </listitem> + <listitem> - <para><command>geli</command> is fast - performs simple + <para><command>geli</command> 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 - — 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>More <command>geli</command> features can be found in + &man.geli.8;.</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>This section describes how to enable support for + <command>geli</command> in the &os; kernel and explains how + to create and use a <command>geli</command> encryption + provider.</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>Superuser privileges are required since modifications + to the kernel are necessary.</para> <procedure> <step> - <title>Adding <command>geli</command> Support to the Kernel - Configuration File</title> + <title>Adding <command>geli</command> Support to the + Kernel</title> - <para>Add the following lines to the kernel configuration - file:</para> + <para>For a custom kernel, ensure the kernel configuration + file contains these lines:</para> - <screen>options GEOM_ELI -device crypto</screen> - - <para>Rebuild the kernel as described in <xref linkend="kernelconfig"/>.</para> + <programlisting>options GEOM_ELI +device crypto</programlisting> <para>Alternatively, the <command>geli</command> module can - be loaded at boot time. Add the following line to the + be loaded at boot time by adding the following line to <filename>/boot/loader.conf</filename>:</para> - <para><literal>geom_eli_load="YES"</literal></para> + <programlisting>geom_eli_load="YES"</programlisting> - <para>&man.geli.8; should now be supported by the kernel.</para> + <para>&man.geli.8; should now be supported by the + kernel.</para> </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 + <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 be protected by a - passphrase as well. Provider's sector size will be 4kB big. - Furthermore, the discussion will describe how to attach the + master key. The master key will also be protected by a + passphrase. The provider's sector size will be 4kB. + The example will describe how to attach to 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> + it, mount it, 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>It is recommended to use a bigger sector size, such as + 4kB, for better performance.</para> - <para>The Master Key will be protected with a passphrase and - the data source for key file will be + <para>The master key will be protected with a passphrase and + the data source for the 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> + the provider <filename>/dev/da2.eli</filename> will be + 4kB.</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 + <para>If the 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> + key file can be used:</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>Attaching the Provider with the Generated Key</title> <screen>&prompt.root; <userinput>geli attach -k /root/da2.key /dev/da2</userinput> Enter passphrase:</screen> @@ -3859,14 +3162,14 @@ Enter passphrase:</screen> </step> <step> - <title>Creating the new File System</title> + <title>Creating the New File System</title> <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> - <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 visible to + &man.df.1; and be available for use:</para> <screen>&prompt.root; <userinput>df -H</userinput> Filesystem Size Used Avail Capacity Mounted on @@ -3876,17 +3179,16 @@ 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> + 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> @@ -3894,159 +3196,820 @@ Filesystem Size Used Avail Capacity Mounted on </procedure> <para>More information about the use of &man.geli.8; can be - found in the manual page.</para> + found in its manual page.</para> <sect3> - <title>Using the <filename>geli</filename> <filename>rc.d</filename> Script</title> + <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 + <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> + <programlisting>geli_devices="da2" +geli_da2_flags="-p -k /root/da2.key"</programlisting> - <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 + <para>This configures <filename>/dev/da2</filename> as a + <command>geli</command> provider of which the master key + file is located in <filename>/root/da2.key</filename>. <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 + attaching to the provider if + <option>-P</option> was given during the + <literal>geli init</literal> 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> </sect2> </sect1> - <sect1 xml:id="swap-encrypting"> - <info><title>Encrypting Swap Space</title> + <info> + <title>Encrypting Swap Space</title> + <authorgroup> - <author><personname><firstname>Christian</firstname><surname>Brüffer</surname></personname><contrib>Written by </contrib></author> + <author> + <personname> + <firstname>Christian</firstname> + <surname>Brü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> + <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, these passwords will not be + written to disk and be cleared after a reboot. If &os; starts + swapping out memory pages to free space for other applications, + the passwords may be written to the disk platters unencrypted. + Encrypting swap space can be a solution for this + scenario.</para> + + <para>The &man.gbde.8; or &man.geli.8; encryption systems may be + used for swap encryption. Both systems use the + <filename>encswap</filename> <link linkend="configtuning-rcd">rc.d</link> script.</para> - <para>The previous section, <link linkend="disks-encrypting">Encrypting - Disk Partitions</link>, includes a short discussion on the different - encryption systems.</para> + <note> + <para>For the remainder of this section, + <filename>ad0s1b</filename> will be the swap + partition.</para> + </note> + + <para>Swap partitions are not encrypted by default and should + be cleared of any sensitive data before continuing. To + overwrite the current swap parition with random garbage, + execute the following command:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen> <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> + <title>Swap Encryption with &man.gbde.8;</title> + + <para>The <literal>.bde</literal> suffix should be added to the + device in the respective <filename>/etc/fstab</filename> swap + line:</para> + + <programlisting># Device Mountpoint FStype Options Dump Pass# +/dev/ad0s1b.bde none swap sw 0 0</programlisting> </sect2> <sect2> - <title>Preparation</title> + <title>Swap Encryption with &man.geli.8;</title> - <note> - <para>For the remainder of this section, <filename>ad0s1b</filename> - will be the swap partition.</para> - </note> + <para>The procedure for instead 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> - <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> + <programlisting># Device Mountpoint FStype Options Dump Pass# +/dev/ad0s1b.eli none swap sw 0 0</programlisting> - <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen> + <para>&man.geli.8; uses the <acronym>AES</acronym> algorithm + with a key length of 128 bit by default. These defaults can + be altered by using <literal>geli_swap_flags</literal> 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 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 + <command>onetime</command> 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>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>Once the system has rebooted, proper operation of the + encrypted swap can be verified using + <command>swapinfo</command>.</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> + + <sect1 xml:id="disks-hast"> + <info> + <title>Highly Available Storage (HAST)</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> <sect2> - <title>Swap Encryption with &man.geli.8;</title> + <title>Synopsis</title> + + <para>High availability is one of the main requirements in + serious business applications and highly-available storage is + a key component in such environments. Highly Available + STorage, or <acronym>HAST<remark role="acronym">Highly + Available STorage</remark></acronym>, was developed by + &a.pjd.email; as a framework which allows transparent storage + of the same data across several physically separated machines + connected by a TCP/IP network. <acronym>HAST</acronym> can be + understood as a network-based RAID1 (mirror), and is similar + to the DRBD® storage system known from 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>After reading this section, you will know:</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>What <acronym>HAST</acronym> is, how it works and + which features it provides.</para> + </listitem> - <screen> -# Device Mountpoint FStype Options Dump Pass# -/dev/ad0s1b.eli none swap sw 0 0 - </screen> + <listitem> + <para>How to set up and use <acronym>HAST</acronym> on + &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>How to integrate <acronym>CARP</acronym> and + &man.devd.8; to build a robust storage system.</para> + </listitem> + </itemizedlist> - <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> + <para>Before reading this section, you should:</para> - <programlisting>geli_swap_flags="-a blowfish -l 128 -s 4096 -d"</programlisting> + <itemizedlist> + <listitem> + <para>Understand &unix; and + <link linkend="basics">&os; basics</link>.</para> + </listitem> + + <listitem> + <para>Know how to + <link linkend="config-tuning">configure</link> network + interfaces and other core &os; subsystems.</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>Have a good understanding of + <link linkend="network-communication">&os; + networking</link>.</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/">OMCnet Internet Service + GmbH</link> and <link + xlink:href="http://www.transip.nl/">TransIP + BV</link>.</para> </sect2> <sect2> - <title>Verifying that it Works</title> + <title>HAST Features</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 main features of the <acronym>HAST</acronym> system + are:</para> - <para>If &man.gbde.8; is being used:</para> + <itemizedlist> + <listitem> + <para>Can be used to mask I/O errors on local hard + drives.</para> + </listitem> - <screen>&prompt.user; <userinput>swapinfo</userinput> -Device 1K-blocks Used Avail Capacity -/dev/ad0s1b.bde 542720 0 542720 0% - </screen> + <listitem> + <para>File system agnostic as it works with any file + system supported by &os;.</para> + </listitem> - <para>If &man.geli.8; is being used:</para> + <listitem> + <para>Efficient and quick resynchronization, synchronizing + only blocks that were modified during the downtime of a + node.</para> + </listitem> - <screen>&prompt.user; <userinput>swapinfo</userinput> -Device 1K-blocks Used Avail Capacity -/dev/ad0s1b.eli 542720 0 542720 0% - </screen> + <!-- + <listitem> + <para>Has several synchronization modes to allow for fast + failover.</para> + </listitem> + --> + + <listitem> + <para>Can be used in an already deployed environment to add + additional redundancy.</para> + </listitem> + + <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> + </sect2> + + <sect2> + <title>HAST Operation</title> + + <para>As <acronym>HAST</acronym> provides a synchronous + block-level replication of any storage media to several + machines, it requires at least two physical machines: + the <literal>primary</literal>, also known as the + <literal>master</literal> node, and the + <literal>secondary</literal> or <literal>slave</literal> + node. These two machines together are referred to as a + cluster.</para> + + <note> + <para>HAST is currently limited to two cluster nodes in + total.</para> + </note> + + <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 + <literal>primary</literal> node, also called + <literal>active</literal>, is the one which will handle all + the I/O requests to <acronym>HAST</acronym>-managed + devices. The <literal>secondary</literal> node is + automatically synchronized from the <literal>primary</literal> + node.</para> + + <para>The physical components of the <acronym>HAST</acronym> + system are:</para> + + <itemizedlist> + <listitem> + <para>local disk on primary node, and</para> + </listitem> + + <listitem> + <para>disk on remote, secondary node.</para> + </listitem> + </itemizedlist> + + <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, thus 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 the + local disk and to the remote disk over TCP/IP. Each read + operation is served from the local disk, unless the local disk + is not up-to-date or an I/O error occurs. In such case, the + read operation is sent to the secondary node.</para> + + <sect3> + <title>Synchronization and Replication Modes</title> + + <para><acronym>HAST</acronym> tries to provide fast failure + recovery. For this reason, it is very 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>: report 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 very good + reliability.</para> + </listitem> + + <listitem> + <para><emphasis>fullsync</emphasis>: report write + operation as completed when local write completes and + when remote write completes. This is the safest and the + slowest replication mode. This mode is the + default.</para> + </listitem> + + <listitem> + <para><emphasis>async</emphasis>: report write operation + as completed when local write completes. This is the + fastest and the most dangerous replication mode. It + should be used when replicating to a distant node where + latency is too high for other modes.</para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + + <sect2> + <title>HAST Configuration</title> + + <para><acronym>HAST</acronym> requires + <literal>GEOM_GATE</literal> support which is not present in + the default <literal>GENERIC</literal> kernel. However, the + <varname>geom_gate.ko</varname> loadable module is available + in the default &os; installation. Alternatively, to build + <literal>GEOM_GATE</literal> support into the kernel + statically, add this line to the custom kernel configuration + file:</para> + + <programlisting>options GEOM_GATE</programlisting> + + <para>The <acronym>HAST</acronym> framework consists of several + parts from the operating system's point of view:</para> + + <itemizedlist> + <listitem> + <para>the &man.hastd.8; daemon responsible for data + synchronization,</para> + </listitem> + + <listitem> + <para>the &man.hastctl.8; userland management + utility,</para> + </listitem> + + <listitem> + <para>and the &man.hast.conf.5; configuration file.</para> + </listitem> + </itemizedlist> + + <para>The following example describes how to configure two nodes + in <literal>master</literal>-<literal>slave</literal> / + <literal>primary</literal>-<literal>secondary</literal> + operation using <acronym>HAST</acronym> to replicate the data + between the two. The nodes will be called + <literal>hasta</literal> with an IP address of + <replaceable>172.16.0.1</replaceable> and + <literal>hastb</literal> with an IP of address + <replaceable>172.16.0.2</replaceable>. 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 also referred to as a + resource or the GEOM provider in + <filename>/dev/hast/</filename>, will be called + <filename>test</filename>.</para> + + <para>Configuration of <acronym>HAST</acronym> is done using + <filename>/etc/hast.conf</filename>. This file should be the + same on both nodes. The simplest configuration possible + is:</para> + + <programlisting>resource test { + on hasta { + local /dev/ad6 + remote 172.16.0.2 + } + on hastb { + local /dev/ad6 + remote 172.16.0.1 + } +}</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. In such a case, make + sure that these hosts are resolvable and are defined in + <filename>/etc/hosts</filename> or in the local + <acronym>DNS</acronym>.</para> + </tip> + + <para>Now that 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 test</userinput> +&prompt.root; <userinput>service hastd onestart</userinput></screen> + + <note> + <para>It is <emphasis>not</emphasis> possible to use GEOM + 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 test</userinput></screen> + + <para>Similarly, run this command on the secondary node, + <literal>hastb</literal>:</para> + + <screen>&prompt.root; <userinput>hastctl role secondary test</userinput></screen> + + <caution> + <para>When the nodes are unable to communicate with each + other, and both are configured as primary nodes, the + condition is called <literal>split-brain</literal>. To + troubleshoot this situation, follow the steps described in + <xref linkend="disks-hast-sb"/>.</para> + </caution> + + <para>Verify the result by running &man.hastctl.8; on each + node:</para> + + <screen>&prompt.root; <userinput>hastctl status test</userinput></screen> + + <para>The important text is the <literal>status</literal> line, + which should say <literal>complete</literal> + on each of the nodes. If it says <literal>degraded</literal>, + something went wrong. At this point, the synchronization + between the nodes has already 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 filesystem on the + <filename>/dev/hast/test</filename> + GEOM provider and mount it. This must be done on the + <literal>primary</literal> node, as + <filename>/dev/hast/test</filename> + appears only on the <literal>primary</literal> node. Creating + the filesystem can take a few minutes, depending on the size + of the hard drive:</para> + + <screen>&prompt.root; <userinput>newfs -U /dev/hast/test</userinput> +&prompt.root; <userinput>mkdir /hast/test</userinput> +&prompt.root; <userinput>mount /dev/hast/test /hast/test</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. + The scenario is that a <literal>primary</literal> node of + the cluster fails. If this happens, the + <literal>secondary</literal> 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, another &os; feature, + <acronym>CARP</acronym>, provides for automatic failover on + the IP layer. <acronym>CARP</acronym> (Common + Address Redundancy Protocol) allows multiple hosts on the + same network segment to share an IP address. Set up + <acronym>CARP</acronym> on both nodes of the cluster + according to the documentation available in + <xref linkend="carp"/>. After setup, each node will + have its own <filename>carp0</filename> interface with a + shared IP 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 IP + 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 be able 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> + + <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 <filename>carp0</filename> interface state + changes by going up or down , the system generates a + notification, allowing the &man.devd.8; subsystem to run an + arbitrary script, in this case + <filename>/usr/local/sbin/carp-hast-switch</filename>. This + script handles the automatic failover. For further + clarification about the above &man.devd.8; configuration, + refer to &man.devd.conf.5;.</para> + + <para>An example of such a script could be:</para> + + <programlisting>#!/bin/sh + +# Original script by Freddie Cash <fjwcash@gmail.com> +# Modified by Michael W. Lucas <mwlucas@BlackHelicopters.org> +# and Viktor Petersson <vpetersson@wireload.net> + +# The names of the HAST resources, as listed in /etc/hast.conf +resources="test" + +# 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\)" > /dev/null 2>&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}" ] && 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>&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 <literal>master</literal> / + <literal>primary</literal>:</para> + + <itemizedlist> + <listitem> + <para>Promotes the <acronym>HAST</acronym> pools to + primary on a given node.</para> + </listitem> + + <listitem> + <para>Checks the file system under the + <acronym>HAST</acronym> pool.</para> + </listitem> + + <listitem> + <para>Mounts the pools at an appropriate place.</para> + </listitem> + </itemizedlist> + + <para>When a node becomes <literal>backup</literal> / + <literal>secondary</literal>:</para> + + <itemizedlist> + <listitem> + <para>Unmounts the <acronym>HAST</acronym> pools.</para> + </listitem> + + <listitem> + <para>Degrades the <acronym>HAST</acronym> pools to + secondary.</para> + </listitem> + </itemizedlist> + + <caution> + <para>Keep in mind that 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/stop required services.</para> + </caution> + + <tip> + <para>For this example, a standard UFS file system was used. + To reduce the time needed for recovery, a journal-enabled + UFS or ZFS file system can be used instead.</para> + </tip> + + <para>More detailed information with additional examples can + be found in the <link + xlink:href="http://wiki.FreeBSD.org/HAST">HAST Wiki</link> + page.</para> + </sect3> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <sect3> + <title>General Troubleshooting Tips</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 all nodes of + the cluster.</para> + + <para>When troubleshooting <acronym>HAST</acronym> problems, + the debugging level of &man.hastd.8; should be increased by + starting &man.hastd.8; with <literal>-d</literal>. This + argument may be specified multiple times to further increase + the debugging level. A lot of useful information may be + obtained this way. Consider also using + <literal>-F</literal>, which starts &man.hastd.8; in the + foreground.</para> + </sect3> + + <sect3 xml:id="disks-hast-sb"> + <title>Recovering from the Split-brain Condition</title> + + <para><literal>Split-brain</literal> is 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) and 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 <resource></userinput> +&prompt.root; <userinput>hastctl create <resource></userinput> +&prompt.root; <userinput>hastctl role secondary <resource></userinput></screen> + </sect3> </sect2> </sect1> </chapter> |