diff options
Diffstat (limited to 'doc/kdat/index.docbook')
| -rw-r--r-- | doc/kdat/index.docbook | 833 |
1 files changed, 833 insertions, 0 deletions
diff --git a/doc/kdat/index.docbook b/doc/kdat/index.docbook new file mode 100644 index 0000000..b5fb94e --- /dev/null +++ b/doc/kdat/index.docbook @@ -0,0 +1,833 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kdat;"> + <!ENTITY package "kdeadmin"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>&kdat; Documentation</title> + +<authorgroup> + +<author> +<firstname>Sean</firstname> +<surname>Vyain</surname> +<affiliation><address><email>svyain@mail.tds.net</email></address></affiliation> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year> +<holder>Sean Vyain</holder> +</copyright> + +<date>2000-10-03</date> +<releaseinfo>2.00.00</releaseinfo> + +<abstract><para>This documentation describes &kdat; +2.0</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KDat</keyword> +<keyword>tape</keyword> +<keyword>tape management</keyword> +</keywordset> + +</bookinfo> + +<chapter id="Introduction"> +<title>Introduction</title> + +<para>&kdat; is a tar-based tape archiver. It is designed to work with +multiple archives on a single tape. &kdat; was inspired by two separate +goals. +The first, was to provide a nice, <abbrev>GUI</abbrev> front-end to tar +that +supported the fast selective extraction features of the +<application>dds2tar</application> program. The second goal was to +answer my wife's +question, <quote>How much longer is it going to be backing +up?!?</quote></para> + +<!-- //////// --> +<sect1 id="features"> +<title>Features</title> + +<itemizedlist> +<listitem><para>Simple graphical interface to local filesystem and tape +contents.</para> +</listitem> +<listitem><para>Multiple archives on the same physical tape.</para> +</listitem> +<listitem><para>Complete index of archives and files is stored on local +hard +disk.</para> +</listitem> +<listitem><para>Selective restore of files from an archive.</para> +</listitem> +<listitem><para>Backup profiles for frequently used backups.</para> +</listitem> +</itemizedlist> + +</sect1> +</chapter> + +<chapter id="using-kdat"> +<title>Using &kdat;</title> + +<sect1 id="mount"> +<title>Mounting/unmounting a tape</title> + +<para>Before a tape can be used, it must be mounted by &kdat;. There are + + + + +three +ways to mount a tape:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Mount Tape</guimenuitem> from the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>Click on the <guiicon>tape drive</guiicon> icon on the +toolbar.</para> +</listitem> +<listitem><para>&RMB; click on the tape drive tree node, and select +<guimenuitem>Mount Tape</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>&kdat; will rewind the tape, and read the header information from +the tape. If &kdat; does not recognize the header on the tape, you will +be prompted to <link linkend="formatting">format</link> the tape.</para> + +<para>If &kdat; recognizes the header it will look for the corresponding +tape index on your local disk. If the tape index cannot be found you +will be prompted to <link linkend="indexing">recreate the index from +tape</link>.</para> + +<para>If all goes well, the tape drive icon will change to indicate that +the tape has been mounted, and a message will appear in the status bar. +The contents of the tape can be explored under the tape drive tree +node.</para> + +<para>Before ejecting a tape, you must unmount the tape. There are three +ways to unmount the tape:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Unmount Tape</guimenuitem> from the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>Click on the <guiicon>tape drive</guiicon> icon on the +toolbar.</para> +</listitem> +<listitem><para>&RMB; click on the tape drive tree node, and select +<guimenuitem>Unmount Tape</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>&kdat; will acknowledge that the tape has been unmounted by +changing the +tape drive icon, and displaying a message in the status bar. The tape +may now +be safely ejected.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="formatting"> +<title>Formatting a tape</title> + +<para>Before a tape can be used by &kdat;, it must be formatted by +&kdat;.</para> + +<para>Some types of tapes must be formatted before they can be used to +store data. <emphasis>This is not what &kdat; does when formatting a +tape.</emphasis> If your tape drive requires that the tapes be formatted + + + + +before +using them, then they must be formatted before they can be +<quote>formatted</quote> +by &kdat;. Typically floppy tape drives require that their media be +formatted, but +DAT drives do not.</para> + +<para>There are two ways to format a tape:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Format Tape...</guimenuitem> from +the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>&RMB; click on the tape drive tree node, and select +<guimenuitem>Format Tape...</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>You will be prompted for a name for the tape, and the stated +capacity of the tape. Both of these parameters can be changed +after the tape has been formatted. The tape name is only used +to identify the tape to the user; it is not used to identify the +tape index associated with the tape. Instead, a unique tape +identifier is automatically generated and written to the tape. +The stated capacity of the tape is used by &kdat; to warn the user +if there will not be enough space to complete a backup.</para> + +<para>After entering the tape name and capacity, &kdat; will proceed to +format the tape. <emphasis>ALL DATA ON THE TAPE WILL BE LOST</emphasis>. +Once &kdat; has finished formatting the tape, the tape will be +automatically +mounted and is ready for use.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="backing-up"> +<title>Backing up files to tape</title> + +<para>Before initiating a backup, you must select some files to archive. + + + + +There +are three ways to select files for backup:</para> + +<orderedlist> +<listitem><para>Highlight a file or folder in the local file tree. +Only the +selected file or subfolder will be archived.</para> +</listitem> +<listitem><para>Highlight a <link linkend="profile">backup +profile</link> in the +tree. Only the files in the backup profile will be archived.</para> +</listitem> +<listitem><para>Checkmark selected files in the local file tree. Only +the +checked files and/or subfolders will be archived.</para> +</listitem> +</orderedlist> + +<para>There are four ways to initiate a backup:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Backup...</guimenuitem> from the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>Click on the <guiicon>backup</guiicon> icon in the +toolbar.</para> +</listitem> +<listitem><para>&RMB; click on a file or folder in the local file +tree, and +select <guimenuitem>Backup...</guimenuitem>.</para> +</listitem> +<listitem><para>&RMB; click on a <link linkend="profile">backup +profile</link>, +and select <guimenuitem>Backup...</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>Once the backup has been initiated, the <guilabel>Backup +Options</guilabel> dialog will appear. This dialog gives you a chance to +review the selected files, and change the backup options.</para> + +<para>After accepting the backup options, the +<guilabel>Backup</guilabel> +dialog will appear. This dialog shows the progress of the backup +including +throughput and time remaining.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="verifying"> +<title>Verifying tape files against local files</title> + +<para>Before initiating a verify, you must select some files to +verify.</para> + +<para>There are two ways to select files for verification:</para> + +<orderedlist> +<listitem><para>Highlight a file or folder in one of the archives +under the +tape drive tree node. Only the selected file or subfolder will be +verified.</para> +</listitem> +<listitem><para>Checkmark selected files in one of the archives under +the tape +drive tree node. Only the checked files and/or subfolders will be +verified.</para> +</listitem> +</orderedlist> + +<para>There are three ways to initiate a verify:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Verify...</guimenuitem> from the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>Click on the <guiicon>verify</guiicon> icon in the +toolbar.</para> +</listitem> +<listitem><para>&RMB; click on a file or folder in one of the +archives, and select <guimenuitem>Verify...</guimenuitem>.</para> +</listitem> +</orderedlist> + + +<para>Once the verify has been initiated, the <guilabel>Verify +Options</guilabel> dialog will appear. This dialog gives you a chance to +review the selected files, and change the working folder for the +verification.</para> + +<para>After accepting the verify options, the +<guilabel>Verify</guilabel> +dialog will appear. This dialog shows the progress of the verification +including throughput and time remaining.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="restoring"> +<title>Restoring files from tape</title> + +<para>Before initiating a restore, you must select some files to +restore. There are two ways to select files for restoring:</para> + +<orderedlist> +<listitem><para>Highlight a file or folder in one of the archives +under the +tape drive tree node. Only the selected file or subfolder will be +restored.</para> +</listitem> +<listitem><para>Checkmark selected files in one of the archives under +the tape +drive tree node. Only the checked files and/or subfolders will be +restored.</para> +</listitem> +</orderedlist> + +<para>There are three ways to initiate a restore:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Restore...</guimenuitem> from the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>Click on the <guiicon>restore</guiicon> icon in the +toolbar.</para> +</listitem> +<listitem><para>&RMB; click on a file or folder in one of the +archives, and select +<guimenuitem>Restore...</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>Once the restore has been initiated, the <guilabel>Restore +Options</guilabel> dialog will appear. This dialog gives you a chance to +review the selected files, and change the working folder for the +restore.</para> + +<para>After accepting the restore options, the +<guilabel>Restore</guilabel> +dialog will appear. This dialog shows the progress of the restore +including +throughput and time remaining.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="indexing"> +<title>Recreating an index from tape</title> + +<para>Sometimes it may be necessary to recreate the tape index file from + + + + +the tape +contents. <emphasis>This process will overwrite any existing index +file for the tape</emphasis>. There are two way to recreate an index +from +tape:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Recreate Tape Index</guimenuitem> +from the +<guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>&RMB; click on the tape drive tree node, and select +<guimenuitem>Recreate Tape Index</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>The <guilabel>Index</guilabel> dialog will appear. This dialog +shows +&kdat;'s progress as it creates the index file.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="profile"> +<title>Creating a backup profile</title> + +<para>There are two ways to create a backup profile:</para> + +<orderedlist> +<listitem><para>Select <guimenuitem>Create Backup Profile</guimenuitem> +from +the <guimenu>File</guimenu> menu.</para> +</listitem> +<listitem><para>&RMB; click on the <guilabel>Backup Profiles</guilabel> +tree node, and select <guimenuitem>Create Backup +Profile</guimenuitem>.</para> +</listitem> +</orderedlist> + +<para>This should create a new backup profile using the currently +checked files +and the default backup options. The following options can be set for the + + + + +backup +profile:</para> + +<variablelist> + +<varlistentry> +<term>Archive name</term> +<listitem><para>The symbolic name for the archive. It can be changed +later.</para></listitem> +</varlistentry> +<varlistentry> +<term>Working folder</term> +<listitem><para>The current working folder to perform the backup in. +The +list of files to backup is automatically updated to reflect the selected + + + + +working +folder.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Stay on one filesystem</term> +<listitem><para>For each folder that is listed under +<guilabel>Backup files</guilabel>, only the files under that folder +that are +on the same filesystem as the folder will be archived. Folders on + + + + +different +filesystems can be listed under <guilabel>Backup files</guilabel>, and +each will +be treated independently of the others, by tar.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>GNU listed incremental</term> +<listitem><para>Perform an incremental backup. A snapshot file is used +to +determine which files have changed since the last incremental backup. +Only the +files that have changed will be archived.</para></listitem> +</varlistentry> +<varlistentry> +<term>Snapshot file</term> +<listitem><para>The name of the file that is used to determine which +files have +changed since the last incremental backup.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Remove snapshot file before backup.</term> +<listitem><para>Remove the snapshot file before invoking +<application>tar</application>. This has the effect of backing up all of + + + + +the +files, and creating the snapshot file for use next time.</para> +</listitem> +</varlistentry> + +</variablelist> + +<note><para>The <guibutton>Files >></guibutton> and +<guibutton><< +Files</guibutton> buttons were not fully implemented at the time this +documentation was +written...</para></note> + +<para>You must press the <guibutton>Apply</guibutton> button to commit +any +changes made to the backup profile.</para> + +</sect1> + +<!-- //////// --> +<sect1 id="prefs"> +<title>Configuring user preferences</title> + +<para>User preferences can be configured by selecting +<guimenuitem>Preferences...</guimenuitem> from the +<guimenu>Edit</guimenu> +menu. The following preferences can be configured:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Default tape size</guilabel> +</term> +<listitem><para>This value will be used as the default tape size when +formatting +a tape.</para> </listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Tape block size</guilabel> +</term> +<listitem><para>The hardware block size for the tape drive. For floppy +tape +drives this value should be 10240 bytes.</para> </listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Tape device</guilabel> +</term> +<listitem><para>The full path to your tape device (usually +<filename>/dev/tape</filename>). +This path must point to the <emphasis>non-rewind</emphasis> version of +your tape device. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Tar command</guilabel> +</term> +<listitem><para>The full path to the <command>tar</command> command on +your +system.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Load tape on mount</guilabel> +</term> +<listitem><para>If enabled, before trying to mount a tape &kdat; will +issue an +<userinput><command>mt<option>load</option></command></userinput> +command to the +tape drive. Some drives may require this before reading and writing the +tape.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Lock tape drive on mount</guilabel> +</term> +<listitem><para>If enabled, whenever a tape is mounted by &kdat;, the +tape drive +will be asked to disable the eject button. This option may not work with + + + + +all +tape drives.</para> </listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Eject tape on unmount</guilabel> +</term> +<listitem><para>If enabled, whenever a tape is unmounted by &kdat;, the +tape +will automatically be ejected from the drive. Do not use this option +with floppy tape +drives.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Variable block size</guilabel> +</term> +<listitem><para>If enabled, &kdat; will attempt to change the hardware +block +size used by the tape drive. Not all drives support variable block size. +Whether this feature is enabled or not, you must tell &kdat; the block +size that +your tape drive uses (&ie; 10240 for ftape users).</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<!-- //////// --> +<sect1 id="tapeformat"> +<title>&kdat; tape format</title> + +<para>When &kdat; formats a tape it writes a single file at the +beginning of the +tape. This file should only occupy a single tape block. The contents of +the +file are:</para> + +<itemizedlist> +<listitem><para>(9 bytes) The string literal +<literal>KDatMAGIC</literal></para> +</listitem> +<listitem><para>(4 bytes) The file format version number (currently +1).</para> +</listitem> +<listitem><para>(4 bytes) The length in bytes of the tape ID +string.</para> +</listitem> +<listitem><para>(n bytes) The tape ID string. The format of this string +is +<replaceable>hostname</replaceable>:<replaceable>seconds</replaceable>, +where +<replaceable>hostname</replaceable> is the full name of the machine that + + + + +the tape was +formatted on and <replaceable>seconds</replaceable> is the number of +seconds since +the epoch when the tape was formatted.</para> +</listitem> +</itemizedlist> + +<para>The tape ID is used to locate a file, with the same name, in the +<filename>$<envar>HOME</envar>/.kdat</filename> folder.</para> + +<para>Each of the remaining files on the tape are plain-old +<application>tar</application> archives. You should be able to +manipulate them +directly with <acronym>GNU</acronym> <application>tar</application>. +Even +non-<acronym>GNU</acronym> <application>tar</application> should work +for +non-incremental backups.</para> + +</sect1> +</chapter> + +<!-- +********************************************************************** +--> +<chapter id="menu-reference"> +<title>Menu and Toolbar Reference</title> + +<sect1 id="menus"> +<title>&kdat; menus</title> + +<para>&kdat; has three menus: +<link linkend="menu-file"><guimenu>File</guimenu></link>, +<link linkend="menu-edit"><guimenu>Edit</guimenu></link>, and +<link linkend="menu-help"><guimenu>Help</guimenu></link>.</para> + +<!-- //////// --> +<sect2 id="menu-file"> +<title>The <guimenu>File</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Backup</guimenuitem> +</menuchoice></term> +<listitem><para><action>Begin a backup.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Restore</guimenuitem> +</menuchoice></term> +<listitem><para><action>Restore a backup from +tape.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Verify</guimenuitem> +</menuchoice></term> +<listitem><para><action>Verify a backup.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Mount Tape</guimenuitem> +</menuchoice></term> +<listitem><para><action>Mount a tape.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Recreate Tape Index</guimenuitem> +</menuchoice></term> +<listitem><para><action>Recreate an index on the currently mounted +tape.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Create Backup Profile</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the dialog box that allows you to create a + + + + +Backup +Profile.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Delete Archive</guimenuitem> +</menuchoice></term> +<listitem><para><action>Delete an archive from the +tape.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Delete Index</guimenuitem> +</menuchoice></term> +<listitem><para><action>Delete the &kdat; index from a +tape.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Delete Backup Profile</guimenuitem> +</menuchoice></term> +<listitem><para><action>Delete a Backup +Profile.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Format Tape</guimenuitem> +</menuchoice></term> +<listitem><para><action>Format a tape for use with +&kdat;.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap> +</keycombo></shortcut><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Exit &kdat;.</action></para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- //////// --> +<sect2 id="menu-edit"> +<title>The <guimenu>Edit</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the <guilabel>Preferences</guilabel> dialog, where +you can configure &kdat; for your needs.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- //////// --> +<sect2 id="menu-help"> +<title>The <guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; + +</sect2> + +<!-- //////// --> +<sect2 id="icon-reference"> +<title>The &kdat; toolbar</title> + +<para>The &kdat; toolbar contains 6 icons, as follows:</para> + +<variablelist> + +<varlistentry> +<term><guiicon>Mount/unmount Tape</guiicon> +</term> +<listitem><para>Mount or unmount a tape.</para></listitem> +</varlistentry> +<varlistentry> +<term><guiicon>Backup</guiicon> +</term> +<listitem><para>Begin a backup. This item is unavailable unless a tape +is +mounted.</para></listitem> +</varlistentry> +<varlistentry> +<term><guiicon>Restore</guiicon> +</term> +<listitem><para>Restore a backup from tape. This item is unavailable +unless a +tape is mounted.</para></listitem> +</varlistentry> +<varlistentry> +<term><guiicon>Verify</guiicon> +</term> +<listitem><para>Verify the contents of a backup tape. This item is +unavailable unless +a tape is mounted.</para></listitem> +</varlistentry> +<varlistentry> +<term><guiicon>Help</guiicon> +</term> +<listitem><para>Opens the &kdat; help files (this +document)</para></listitem> +</varlistentry> +<varlistentry> +<term><guiicon>Quit</guiicon> +</term> +<listitem><para>Quits &kdat;</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +</chapter> + +<!-- +*********************************************************************** +--> +<chapter id="Copyright"> +<title>Copyright</title> +<para>&kdat;</para> + +<para>Program and Documentation copyright 1998-2000 Sean +Vyain<email>svyain@mail.tds.net</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> +</book> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> |