<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
<!ENTITY kdar "KDar">
<!ENTITY kappname "&kdar;">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>
<book lang="&language;">
<bookinfo>
<title>The &kdar; Handbook</title>
<authorgroup>
<author>
<firstname>Johnathan</firstname>
<othername>K.</othername>
<surname>Burchill</surname>
<affiliation><address><email>jkerrb@shaw.ca</email></address></affiliation>
</author>
</authorgroup>
<date>15 November 2004</date>
<releaseinfo>1.3.0</releaseinfo>
<abstract>
<para>The &kde; Disk archiver (&kdar;) is a backup and archiving utility. Use &kdar; to make full and incremental backups of your data. </para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>kdar</keyword>
<keyword>backup</keyword>
<keyword>archive</keyword>
<keyword>slice</keyword>
<keyword>disk</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<sect1 id="overview">
<title>Overview</title>
<para>&kdar; is the <quote>KDE Disk archiver</quote>, a
disk-based archiving and backup utility. </para>
<para>&kdar; is built around the <quote>disk archive library</quote>
by Denis Corbin, and is similar in function to his <quote>DAR</quote> program.
DAR is somewhat analogous to the <quote>tape archiver</quote>
shell command <quote>tar</quote>, but is better suited for backups onto
disk-based media, such as CD-R's, DVD's, Jazz, Zip, other
hard-drives, etc. </para>
<para>&kdar; can perform differential backups,
which means that it can quickly store the differences between a recent
full backup and the current state of your data.</para>
<para>A sophisticated file filtering mechanism allows you to select which
files and directories to backup or restore, and which files to compress.</para>
<para>Furthermore, a small catalog can be extracted from the archive,
which means you don't need your archive CD's to do a differential
backup of the entire filesystem. You just need to store the much smaller
catalog file on your filesystem.
</para>
<para>The next section describes &kdar;'s features in more detail.</para>
</sect1>
<sect1 id="features">
<title>Features</title>
<para></para>
<para>&kdar; uses the Disk ARchive library, libdar. This means that
&kdar; can have all of the features of DAR, but not all are
currently implemented. Here is a list of features that are
implemented in version 1.2.0: </para>
<itemizedlist>
<listitem id="feature-filters"><para><link linkend="desc-filters">Filters</link></para></listitem>
<listitem id="feature-diff-backup"><para><link linkend="desc-diff-backup">Differential backup</link></para></listitem>
<listitem id="feature-slices"><para><link linkend="desc-slices">Slices</link></para></listitem>
<listitem id="feature-compression"><para><link linkend="desc-compression">Compression</link></para></listitem>
<listitem id="feature-selective-compression"><para><link linkend="desc-selective-compression">Selective compression</link></para></listitem>
<listitem id="feature-direct-access"><para><link linkend="desc-direct-access">Direct access</link></para></listitem>
<listitem id="feature-hard-links"><para><link linkend="desc-hard-links">Hard links saved</link></para></listitem>
<listitem id="feature-ea"><para><link linkend="desc-ea">Extended attributes</link></para></listitem>
<listitem id="feature-testing"><para><link linkend="desc-testing">Archive testing</link></para></listitem>
<listitem id="feature-isolation"><para><link linkend="desc-isolation">Isolation</link></para></listitem>
<listitem id="feature-config"><para><link linkend="desc-config">Configuration stored</link></para></listitem>
<listitem id="feature-restore-individual"><para><link linkend="desc-restore-individual">Restore individual files</link></para></listitem>
<listitem id="feature-flat"><para><link linkend="desc-flat">Flat restoration</link></para></listitem>
<listitem id="feature-nodump"><para><link linkend="desc-nodump">Nodump flag</link></para></listitem>
<listitem id="feature-commands"><para><link linkend="desc-commands">User commands between slices</link></para></listitem>
<listitem id="substitution"><para><link linkend="desc-substitution">String substitution</link></para></listitem>
<listitem id="dar-commands"><para><link linkend="desc-dar-commands">Equivalent DAR commands</link></para></listitem>
</itemizedlist>
<para>These descriptions are mostly copied from Denis Corbin's FEATURES document from the libdar source.</para>
<variablelist>
<varlistentry id="desc-filters">
<term>Filter</term><listitem>
<para>&kdar; is able to backup everything from a single file to an entire filesystem. Additionally a mechanism of filters permits, based on the filename, to exclude or include some files while backing up or restoring a directory tree. Similarly, a secondary filter mechanism permits to exclude some branches of a directory tree, or to only include some branches. <link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-diff-backup"><term>Differential backup</term><listitem>
<para>When making a backup with &kdar;, you have the possibility to make a full backup or a differential backup. A full backup, as expected makes backup of all files as specified on the command line (with or without filters). Instead, a differential backup, (over filter mechanism), saves only files that have changed since a given reference backup. Additionally, files that existed in the reference backup and which do no more exist at the time of the differential backup are recorded in the backup. At recovery time, (unless you deactivate it), restoring a differential backup will update changed files and new files, but also remove files that have been recorded as deleted. Note that the reference backup can be a full backup or another differential backup. This way you can make a first full backup, then many differential backup, each taking as reference the last backup made.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-slices"><term>Slices</term><listitem>
<para>&kdar; can split an archive over several removable media whatever their number is and whatever their size is. Thus &kdar; is able to save over old floppy disk, CD-R, DVD-R, CD-RW, DVD-RW, Zip, Jazz, etc... &kdar; is not concerned by un/mounting a removable medium, instead it is independent of hardware. Given the size, it will split the archive in several files (called SLICES), eventually pausing before creating the next one, allowing this way, the user to (un)mount a medium, burn the file on CD-R, send it by email. &kdar; can also backup data to one slice whatever its size is. Additionally, the size of the first slice can be specified separately, if for example you want first to fulfill a partially filled disk before starting using empty ones. Last, at restoration time, &kdar; will just pause and prompt the user asking a slice only if it is missing.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-compression"><term>Compression</term><listitem>
<para>&kdar; can use compression. Actually only the gzip and bzip2 algorithms are implemented, but some room has been made for any other compression algorithm. Note that, compression is made before slices are created, which means that using compression with slices will not make slices smaller, but will probably make less slices in the backup.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-selective-compression"><term>Selective compression</term><listitem>
<para>&kdar; can be given a special filter that determines which files will be compressed or not. This way you can speed up the backup operation by not trying to compress *.mp3, *.mpg, *.zip, *.gz and other already compressed files. Moreover another mechanism allows you to say that files under a given size (whatever their name is), will not be compressed.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-direct-access"><term>Direct access</term><listitem>
<para>Even using compression &kdar; does not have to read the entire backup to extract one file. This way if you just want to restore one file from a huge backup, the process will be much faster than using <application>tar</application>.
&kdar; first reads the catalogue (i.e. the contents of the backup),
then it goes directly to the location of the saved file(s) you want to
restore and proceed to restoration. In particular using slices &kdar; will ask only for the slice(s) containing the file(s) to restore.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-hard-links"><term>Hard links</term><listitem>
<para>Hard links are properly saved. They are properly restored if possible. If for example restoring across a mounted file system, hard linking will fail, but dar will then duplicate the inode and file content, issuing a warning.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-ea"><term>Extended attributes</term><listitem>
<para>Support for extended attributes have to be activated at libdar
compilation time. &kdar; is able to save and restore EA, all or just those of a given namespace (system or user). If no EA have been saved and restoration occurs over a file that has EA, they will be preserved. But if they have been saved empty for a given file, any existing EA for that file will be removed at restoration time, unless &kdar; is configured to <quote>ignore user Extended Attributes</quote> and <quote>ignore system Extended Attributes</quote>.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-testing"><term>Archive testing</term><listitem>
<para>thanks to CRC (cyclic redundancy checks), &kdar; is able to detect data corruption in the archive. Only the file where data corruption occurred will not be possible to restore, but &kdar; will restore the others even when compression is used.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-isolation"><term>Isolation</term><listitem>
<para>The catalogue (i.e.: the contents of an archive), can be extracted (this operation is called isolation) to a small file. This catalog can in turn be used as reference for making a differential archive. There is no more need to provide an archive to be able to create a differential backup over it. Just its catalogue is necessary.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-config"><term>Configuration stored</term><listitem>
<para>&kdar; settings are automatically stored between sessions.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-restore-individual"><term>Restore individual files</term><listitem>
<para>You can restore any combination of individual files and directories.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-flat"><term>Flat restoration</term><listitem>
<para>It is possible to restore any file without restoring the directories and subdirectories it was in at the time of the backup. If this option is enabled, all files will be restored in the root directory whatever their real position is.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-nodump"><term>Nodump flag</term><listitem>
<para>The &Linux; ext2/3 filesystem provides for each inodes a set of flags,
among which is the <quote>nodump</quote> flag, which in substance says
<quote>don't save this file</quote>. This is used by the so-called dump backup program. &kdar; can take care not to save files that have this flag set.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-commands"><term>User commands between slices</term>
<listitem><para> &kdar; can call a given command once a slice has
been written or before reading a slice. Several macros allow the user command or script to know the slice number, path and archive basename. Use this feature to automate the CD writing process between slices, for example.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-substitution"><term>String substitution</term>
<listitem><para> &kdar; can substitute convenient codes provided by the user for new archive names,
as well as for the user commands.
<link linkend="features">back to top</link></para></listitem></varlistentry>
<varlistentry id="desc-dar-commands"><term>Equivalent DAR commands</term>
<listitem><para> &kdar; can export the equivalent dar commands for its archiving operations. The commands are also written to a log file.
<link linkend="dar-commands">back to top</link></para></listitem></varlistentry>
</variablelist>
</sect1>
<sect1 id="parts">
<title>The parts of KDar</title>
<para>Here is a brief overview of the parts of the KDar main window.</para>
<screenshot>
<screeninfo>Main &kdar; window</screeninfo>
<mediaobject><imageobject><imagedata format="PNG" fileref="KDar-1.2.0-main-small-annotated.png"/>
</imageobject>
<textobject>
<phrase>Here's a screenshot of &kdar;.</phrase>
</textobject>
<caption><para>
The main &kdar; user interface window.
</para></caption>
</mediaobject>
</screenshot>
<para> Below the titlebar are &kdar;'s <interface>Menubar</interface> and <interface>Toolbar</interface>. The <interface>Menubar</interface> allows you to open and create archives, operate on them, and get information about &kdar;. The <interface>Toolbar</interface> gives you one-click access to many of &kdar;'s features, and you can configure it to your liking by right-clicking on it.
</para>
<para>Next, the <interface>Archive browser</interface> allows you
to view the contents of the current archive by descending through
the file tree. By high-lighting and right-clicking one or more files or directories, you can restore individual or groups of files onto your filesystem.
</para>
<para>At the bottom of the &kdar; window a <interface>Message window</interface> provides you with feedback about the outcome of archive operations (e.g. testing, creating, restoring, etc.). Error messages are displayed here. The contents of
this window can be printed, and you can clear it at any time.
</para>
<para>Below the <interface>Messages</interface> panel is the &kdar; status bar. This provides you with basic feedback about the status of the various archive operations. For example, the current archive slice and its size in MB are displayed while an archive is being created. If you have "verbose" messages enabled, the progress of archive creation and the current file being added to the archive are shown here.</para>
</sect1>
</chapter>
<chapter id="using-kdar">
<title>Using &kdar;</title>
<sect1 id="basic-usage">
<title>Basic usage</title>
<para>When you first start &kdar;, you are asked to provide the name of a directory where archives will be stored by default. Click on the <interface>directory icon</interface> to browse your filesystem and select a suitable storage directory. If necessary, use the toolbar at the top of the dialog to create a new directory.
I recommend "/opt/backups/dar-backups", or something like that. This indicates that the archives are accessible by the command-line "dar", as well as by &kdar;.</para>
<para>A short <interface>splash screen</interface> is shown while &kdar; starts up. It can be disabled from the <interface>settings</interface> dialog.</para>
<para>The menu is set up as <interface>File | Archive | Messages | Settings | Help</interface>.</para>
<para>To Quit, type <interface>Ctrl-Q</interface> or <interface>File->Quit</interface>. &kdar; will wait for any running
operation to finish before closing the window. Currently, you cannot cancel archive operations from within &kdar;. If you want to cancel the operation, "kdekillall kdar" from the commandline should do it.</para>
<para>&kdar; uses and creates "disk archives", which are files that end with ".dar".
One of the key features of &kdar; is that its archives can be created in parts, called "slices". The size of each slice can be set from a list of common media types such as "DVD", "CD-R", "Zip", or it can be customized to be any size. Each archive slice is denoted by a period and a number before the ".dar" extension, such as ".1.dar", ".2.dar", etc. Each archive has a different name, called the "basename", that briefly describes what the archive contains. So a full archive slice name consists of a "basename" followed by the slice number and the extension ".dar".</para>
<para>For example, a full backup of your filesystem might have archive slices that look like "localhost-20040808-full.1.dar", "localhost-20040808-full.2.dar", and so-on, up to the number of slices in the archive.</para>
<para>You can also ask &kdar; not to split the archive into individual slices. The resulting archive still follows the naming convention described above: its slice number is "1".</para>
<para>Many actions in &kdar; need an archive loaded to work. To load, or "open", a disk archive, select <interface>File->Open archive</interface>.</para>
<para>If you selected an archive with .*.dar on the end of the filename (i.e. test-archive.1.dar), &kdar; will automatically remove it for you. You can also type in the archive name without the slice number and extension. Recently-opened archives can be accessed quickly from <interface>File->Open Recent</interface>.</para>
<para>&kdar; can load an archive from the command-line. Just type the archive path and name as an argument.</para>
<para>If you do not yet have any archives, you can easily create one now, as described in the next section.</para>
</sect1>
<sect1 id="creating-archives">
<title>Creating archives</title>
<para>
To create an archive, select "Archive->Create" (at bottom of menu). The
<quote>Create archive</quote> wizard will appear.
<screenshot>
<screeninfo>Wizard for creating archives</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-create-wizard-restore-profile-small.png"/>
</imageobject>
<textobject>
<phrase>The <interface>Archive->Create</interface> wizard.</phrase>
</textobject>
<caption><para>The <interface>Archive->Create</interface> wizard.</para></caption>
</mediaobject>
</screenshot>
Let the wizard take you step-by-step through the archiving process. Use the <interface>Next ></interface> and <interface>< Back</interface> buttons at the bottom of the wizard to navigate the pages. The rest of this section describes this procedure in detail, and you can skip it if you just want to create a basic archive.
</para>
<sect2 id="creation-profiles">
<title>Profiles</title>
<para>The first page of the create wizard gives you an opportunity to restore a <quote>profile</quote>. Profiles store all of the information needed to perform one of &kdar;'s operations. You save them to your filesystem as regular files, with any name you like, but I suggest you append <quote>.kdar</quote> onto it to distinguish the file as a kdar profile. Currently &kdar; supports <quote>creation</quote> and <quote>restoration</quote> profiles.</para>
<para>To load a creation profile, click the <interface>Restore profile</interface> button and select the profile. You probably haven't saved a profile yet, so just click the <interface>Next ></interface> button.</para>
</sect2>
<sect2 id="archive-name">
<title>Archive Name</title>
<para>Choose an appropriate name for your archive.</para>
<screenshot>
<screeninfo>Choose archive name</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-create-wizard-archivename-empty-small.png"/>
</imageobject>
<textobject>
<phrase>Choose a name for your archive.</phrase>
</textobject>
<caption><para>Choose a name for your archive.</para></caption>
</mediaobject>
</screenshot>
<para>You cannot continue to the next page until you have done this. I usually put a descriptive name, and the date (e.g. "040208"). You only need a basename here, not the entire archive name (e.g. "test-archive-040208", not "test-archive-040208.1.dar"), so if you are overwriting an existing archive, remove any of the ".*.dar" trailing stuff.</para>
<para>The archive will be stored in the default storage directory. If you want to store the archive in a different location, just prefix the name with the full path to the new location, including the leading "/". You can also choose a new location and name by clicking the <interface>directory</interface> icon to browse your filesytem.</para>
<sect3 id="archive-name-substitution">
<title>Archive Name Macros</title>
<para>&kdar; understands the following macros which you can type into the archive name. &kdar; automatically substitutes these macros into the name before creating the archive.</para>
<itemizedlist>
<listitem><para><symbol>%hostname</symbol>: Replaced by the computer's hostname, i.e. "igloo", or "localhost" if the hostname can't be found.</para></listitem>
<listitem><para><symbol>%date</symbol>: Replaced by today's date, as "YYYYMMDD".</para></listitem>
<listitem><para><symbol>%time</symbol>: Replaced by the current time, as "hh:mm:ss".</para></listitem>
<listitem><para><symbol>%year</symbol>: Replaced by the current year, as "YYYY".</para></listitem>
<listitem><para><symbol>%month</symbol>: Replaced by the current month, as "MM".</para></listitem>
<listitem><para><symbol>%day</symbol>: Replaced by the current day of the month, as "DD".</para></listitem>
<listitem><para><symbol>%hour</symbol>: Replaced by the current hour, as "hh".</para></listitem>
<listitem><para><symbol>%minute</symbol>: Replaced by the current minute, as "mm".</para></listitem>
<listitem><para><symbol>%second</symbol>: Replaced by the current second, as "ss".</para></listitem>
<listitem><para><symbol>%full</symbol>: Replaced by "full". Used to indicate that this is a full backup.</para></listitem>
<listitem><para><symbol>%diff</symbol>: Replaced by "diff". Used to indicate that this is a differential, or incremental, backup.</para></listitem>
<listitem><para><symbol>%refname</symbol>: If making a differential backup, this is replaced by the basename of the reference archive, excluding path and extension. If not making a differential backup, this is replaced by "NO-REF-ARCHIVE".</para></listitem>
</itemizedlist>
<informalexample>
<para>For example, if you are making a full backup you might use "%hostname-%full-%date" for the new archive name. On a computer called "igloo", this would create archive slices named "igloo-full-20040729.1.dar", "igloo-full-20040729.2.dar", etc.</para>
<para>A few days later, if you are making a differential backup with
"/data/backups/igloo-full-20040729" as the reference archive, you might
use "%refname-%diff-%date" as the new archive name. This would create
archive slices called "igloo-full-20040729-diff-20040805.1.dar", etc.</para>
</informalexample>
<para>Continue to the next wizard page to choose the top-level directory that you want to archive.</para>
</sect3>
</sect2>
<sect2 id="root-directory">
<title>Root directory</title>
<para>The <quote>root directory</quote> is the filesystem's top-level directory that you want to archive. &kdar; will consider all directories and files below this directory for inclusion in the archive, but no files above or beside this directory.</para>
<screenshot>
<screeninfo>Choose root directory</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-create-wizard-rootdirectory-empty-small.png"/>
</imageobject>
<textobject>
<phrase>Choose the archive's root directory.</phrase>
</textobject>
<caption><para>Choose the archive's root directory.</para></caption>
</mediaobject>
</screenshot>
<para>You can browse your filesystem to choose the top-level directory by clicking the <interface>directory</interface> icon to the right of the text box.</para>
</sect2>
<sect2 id="reference-archive">
<title>Differential archives</title>
<para>Creating full system backups can take several hours on modern filesystems. &kdar; can optionally store the difference between the current state of the filesystem and the state of the filesystem when you last created a full backup. The new archive is called a "differential" archive. Doing a differential backup can take considerably less time than doing a full backup, and the resulting archive usually takes up much less space on your filesystem or storage media.</para>
<screenshot>
<screeninfo>Choose reference archive</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-create-wizard-referencearchive-disabled-small.png"/>
</imageobject>
<textobject>
<phrase>Choose the differential archive's reference archive.</phrase>
</textobject>
<caption><para>Choose the differential archive's reference archive.</para></caption>
</mediaobject>
</screenshot>
<para>If you want to make a differential backup, enable the <interface>differential backup</interface> checkbox, and select the reference archive. The reference archive can be from a previous full backup, a previous differential backup, or an archive catalog. Archive catalogs contain only the basic archive information, such as the contents, but are equivalent to regular archives as far as differential creation is concerned. You create a catalog by "isolating" it from its archive, and this is described later.</para>
<para>Leave the checkbox unchecked if you're making a new archive (e.g., a full backup).</para>
</sect2>
<sect2 id="configure-creation-settings">
<title>Advanced creation settings</title>
<para>&kdar; has many advanced creation features which you can configure by clicking the <interface>Configure creation options</interface> button. This brings up a configuration dialog which allows you to customize the creation process to suit your needs. For example, &kdar; has powerful directory and file filtering mechanisms which allow you to fine-tune which directories and files to include in the archive. You can also choose whether to compress the archive contents, and you can specify which types of file to exclude from the compression process.</para>
<screenshot>
<screeninfo>Configure settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-create-wizard-configure-small.png"/>
</imageobject>
<textobject>
<phrase>Configure the advanced creation settings.</phrase>
</textobject>
<caption><para>Configure the advanced creation settings.</para></caption>
</mediaobject>
</screenshot>
<para>Click next to use the default settings. The default settings can be configured from the main menu under <interface>Settings->Configure &kdar;...</interface>.</para>
<para>These configuration options are described <link linkend="configuration-options">later</link> in this manual.</para>
</sect2>
<sect2 id="save-profile-and-finish">
<title>Save profile and start the creation process</title>
<para>Now you can save your settings as a profile.</para>
<screenshot>
<screeninfo>Save profile</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.3.0-create-wizard-create-profile-and-finish-small.png"/>
</imageobject>
<textobject>
<phrase>Save the profile and start the creation process.</phrase>
</textobject>
<caption><para>Save the profile and start the creation process.</para></caption>
</mediaobject>
</screenshot>
<para>Click the <interface>Save profile</interface> button and choose a descriptive name. I recommend something with the words "kdar-creation-profile" in the name. You will be able to restore this profile later when creating a new backup. Profiles are also useful for finding out which settings were used for creating an old backup. You can store the creation profile on your storage media along with the archive slices.</para>
<para>You can export the equivalent dar command by clicking on the <interface>Export dar command</interface> button.</para>
<para>When you're satisfied that everything is okay, click <interface>Finish</interface>. Your archive should be created. The progress is updated in the status bar in the main window.</para>
<para>
Advanced users can disable the Wizard and create archives using a compact dialog. From the <interface>Settings->Configure &kdar;...</interface> menu, unselect the <interface>Use Wizard for creating archives</interface> checkbox.
</para>
</sect2>
</sect1>
<sect1 id="configuration-options">
<title>Configuration options</title>
<para>To configure &kdar;'s options, select <interface>Settings->Configure &kdar;...</interface> from the main menu.</para>
<screenshot>
<screeninfo>General settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-general-small.png"/>
</imageobject>
<textobject>
<phrase>General settings.</phrase>
</textobject>
<caption><para>General settings.</para></caption>
</mediaobject>
</screenshot>
<para>The settings dialog consists of several modules which can be chosen from the column on the left.</para>
<sect2 id="general-settings">
<title>General</title>
<para>Here you can configure several settings of a general nature.</para>
<itemizedlist>
<listitem><para>"verbose output": determines whether to display status and error messages from &kdar;. If you disable this option, the creation progress bar will be disabled.</para></listitem>
<listitem><para>"Use Wizard for creating archives": unselect this to create archives using a single, compact dialog. You can enter settings faster with this than using the Wizard once you're used to it.</para></listitem>
<listitem><para>"Show splash screen on startup": unselect this to not show the &kdar; splash screen. This will reduce the startup time by a couple of seconds.</para></listitem>
<listitem><para>"Archive storage directory": the default archive storage directory.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="fonts-settings">
<title>Fonts</title>
<para>Select the fonts that you want to use for the various displays.</para>
<screenshot>
<screeninfo>Font settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-fonts-small.png"/>
</imageobject>
<textobject>
<phrase>Font settings.</phrase>
</textobject>
<caption><para>Font settings.</para></caption>
</mediaobject>
</screenshot>
</sect2>
<sect2 id="slicing-settings">
<title>Slicing</title>
<para>Settings associated with creating archive slices.</para>
<screenshot>
<screeninfo>Slicing settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-slicing-small.png"/>
</imageobject>
<textobject>
<phrase>Slicing settings.</phrase>
</textobject>
<caption><para>Slicing settings.</para></caption>
</mediaobject>
</screenshot>
<itemizedlist>
<listitem><para>"Split archive": check this to create archives as slices of a given size.</para></listitem>
<listitem><para>"Media type": the type of storage media each slice should fit on. Choose from the drop-down list. Selecting "Custom" will allow you to specify an arbitrary size for your slices.</para></listitem>
<listitem><para>"Slice size": the size of each slice. This is calculated from the media type, or you can type a number here and the media will be updated automatically to "Custom".</para></listitem>
<listitem><para>"First slice size": the size of the first archive slice. You can make this size smaller than the remaining slices. This is useful for saving space on the first storage medium to put DAR documentation, the statically-linked command-line dar binaries, and even your &kdar; creation profile.</para></listitem>
<listitem><para>"Pause between slices": after each slice has been written, &kdar; will pause, prompting you whether to continue writing the next slice. This gives you an opportunity to burn the slice to a DVD or CD-R, for example. It is useful for when you have enough disk space for only one archive at a time.</para></listitem>
<listitem><para>"Command to execute after completion of each slice": &kdar; can optionally run arbitrary shell commands after each slice has been written. Use this to run your DUC (Dar User Command) files, a CD burning program (k3b), or an secure-shell file transfer to a remote server. Include the full path to the script or binary file if it is not in your $PATH environment variable. Leave this command empty if you do not want to run any external programs.</para>
<para>&kdar; can substitute the following DAR macros here:</para>
<itemizedlist>
<listitem><para>%%: replaced by "%"</para></listitem>
<listitem><para>%p: the path to the archive slice</para></listitem>
<listitem><para>%b: the basename of the archive slice</para></listitem>
<listitem><para>%n: the number of the archive slice</para></listitem>
<listitem><para>%e: the extension of the archive slice (always "dar")</para></listitem>
<listitem><para>%c: the context in which the slice has been written or read</para></listitem>
</itemizedlist>
<para>For example, to start "k3b" with the archive slice loaded and ready to burn onto a CD, put the following in the command box:</para>
<para><userinput><command>k3b</command> --datacd %p/%b.%n.%e</userinput></para>
<para>See the DAR manpage (man dar) for details on string substitution.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="compression-settings">
<title>Compression</title>
<para>Compression can be switched on or off in general, or for individual file types, based on filename filters.</para>
<screenshot>
<screeninfo>Compression settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-compression-small.png"/>
</imageobject>
<textobject>
<phrase>Compression settings.</phrase>
</textobject>
<caption><para>Comression settings.</para></caption>
</mediaobject>
</screenshot>
<sect3 id="compression-type">
<title>Compression type</title>
<itemizedlist>
<listitem><para>"bzip2": compress using the bzip2 block-sorting file compressor algorithm.</para></listitem>
<listitem><para>"gzip": compress using the gzip Lempel-Ziv coding algorithm. You can specify a compression level here, with 1 being the least compression (fastest) and 9 being the most compression (slowest).</para></listitem>
<listitem><para>"none": do not compress any files.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="compression-filters">
<title>Compression filters</title>
<para>You can choose to exclude or include specific types of files to be compressed. Click the <interface>New</interface> button to create a new compression filter. This will bring up a dialog with a drop-list of standard file types which do not compress well. You can also choose to have "all of the above" file types to be excluded from compression. You can add your own file type, as the filter value is editable.</para>
<para>Any compression filters that you add will be saved in &kdar;'s configuration file and will reappear when you start a new session of &kdar;.</para>
<para>"minimum size for compression": &kdar; will not compress any file whose size is less than the amount specified (default 150 bytes). Compression algorithms do not compress small files well because of the fixed overhead involved in the compression process. You can change this value depending on your experience with the compression process.</para>
</sect3>
</sect2>
<sect2 id="directory-settings">
<title>Directories</title>
<para>Directory filters allow you to fine-tune which directories &kdar; should include or exclude from the archive.</para>
<screenshot>
<screeninfo>Directory settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-directories-small.png"/>
</imageobject>
<textobject>
<phrase>Add directories to the filter.</phrase>
</textobject>
<caption><para>Directory filters.</para></caption>
</mediaobject>
</screenshot>
<para>Click "new" to add a filter if you want to backup specific directories, or exclude specific directories. Notice that &kdar; automatically excludes the backup directory from your archive. Filters that are automatically controlled by &kdar; have type "auto" and are disabled from editing. In a full backup you also should exclude "/dev/pts" and "/proc", so add them from the dropdown list.</para>
<para>Note, you might want to "Include a directory". In that case, only those directories that are included will be a part of the new archive. You can then exclude directories below those included directories.</para>
<para>Directories can be filtered using wildcards (known as "globbing"), i.e. "*", "?", "[", and "]". For example, to exclude all CVS directories from your archive enter "*/CVS/*" for the directory filter.</para>
<para>Along the same lines, you can include or exclude a specific filename by specifying its full path in the <interface>new directory</interface> dialog. If necessary, browse your filesystem for specific files by clicking the <interface>directory</interface> icon to the right of the input box.</para>
<para>Only subdirectories of the archive directory (the <quote>root</quote>) are suitable for filters. If you select a directory that is not a subdirectory of the root, then when you try to create the archive &kdar; will display a message asking you to remove that directory from filter list.</para>
</sect2>
<sect2 id="file-filters">
<title>Files</title>
<para>File filters allow you to include or exclude files using wildcard matching.</para>
<screenshot>
<screeninfo>File filters</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-files-small.png"/>
</imageobject>
<textobject>
<phrase>File filters.</phrase>
</textobject>
<caption><para>File filters.</para></caption>
</mediaobject>
</screenshot>
<para>For example, to exclude all files named "core", just add a new file filter named "core". Unlike directory filtering, all files of the given name will be filtered, now just a single particular one.</para>
<para>The new file filter dialog has several common file filters that you can select from a drop-list. You might want to exclude any files which end in "~", because these are generally backups of files. Add ".*~" to exclude hidden backups.</para>
</sect2>
<sect2 id="filesystem-settings">
<title>Filesystem</title>
<para>Here you can configure several settings related to the underlying filesystem.</para>
<screenshot>
<screeninfo>Filesystem settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-filesystem-small.png"/>
</imageobject>
<textobject>
<phrase>Filesystem settings.</phrase>
</textobject>
<caption><para>Filesystem settings.</para></caption>
</mediaobject>
</screenshot>
<itemizedlist>
<listitem><para>"disable user Extended Attributes": if you have "Extended Attributes" compiled into libdar and &kdar;, they can be disabled for users by selecting this option.</para></listitem>
<listitem><para>"disable system Extended Attributes": system EA can be disabled for by selecting this option.</para></listitem>
<listitem><para>"ignore user/group ID's": select this option to ignore user and group ID's during backup and restoration. This is useful for restoring archives from other filesystems, which may have user and group ID's that are not the same as the ones on your system.</para></listitem>
<listitem><para>"ignore ext2 dump flag": &kdar; will not store files on an ext2 filesystem that have the "no dump" flag set, unless this option is selected.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="comparison-settings">
<title>Comparison</title>
<screenshot>
<screeninfo>Comparing file dates</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-comparison-small.png"/>
</imageobject>
<textobject>
<phrase>Comparing file modification dates.</phrase>
</textobject>
<caption><para>Comparing file modification dates.</para></caption>
</mediaobject>
</screenshot>
<para>The hourshift value is used during restorations and differential creations. Apparently some filesystems, like Samba, change the dates of files during a transition to or from daylight savings time. This option is a workaround that considers two dates equal if they differ by the specified number of hours, or less. Set this to "1" if you have such a filesystem.</para>
</sect2>
<sect2 id="restore-settings">
<title>Restore</title>
<para>The following options affect the behaviour of archive restoration.</para>
<screenshot>
<screeninfo>Restoration settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-configure-restore-small.png"/>
</imageobject>
<textobject>
<phrase>Restoration settings.</phrase>
</textobject>
<caption><para>Restoration settings.</para></caption>
</mediaobject>
</screenshot>
<itemizedlist>
<listitem><para>"do not delete files on disk": this option refers to differential archive restorations. The filesystem will be restored to the state it had at each reference backup, even if that means deleting files on the disk. Selecting this option prevents those files from being deleted during restoration.</para></listitem>
<listitem><para>"only restore most recent or non-existing files": with this option enabled, files that currently reside on your filesystem will not be overwritten by older files that have the same path and filename."</para></listitem>
<listitem><para>"allow overwrite": select this option to allow files that currently reside on your filesytem to be overwritten by files in the archive.</para></listitem>
<listitem><para>"Flat": all files in all subdirectories of the archive will be restored to the same root directory. The restored filesystem will contain no directories.</para></listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="viewing-archives">
<title>Browsing archives</title>
<para>Open an archive, and click on the "+" in front of its name in the <interface>Archive browser</interface> to examine the contents of the archive.</para>
<screenshot>
<screeninfo>File browser</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-main-listing-small.png"/>
</imageobject>
<textobject>
<phrase>Examine the archive contents using the browser.</phrase>
</textobject>
<caption><para>Examine the archive contents using the browser.</para></caption>
</mediaobject>
</screenshot>
<para>Clicking on a "+" will show that directory's contents, while clicking on a "-" will hide those contents. Empty directories show "<empty>".</para>
<para>The archive browser displays the following information about each item in the archive in a series of columns across the display:</para>
<itemizedlist>
<listitem><para>Filename: the item's filename. This may be a directory, a regular file, named pipe, character device, and so on.</para></listitem>
<listitem><para>Permissions: unix file permissions, in "ls -l" format.</para></listitem>
<listitem><para>User ID: tries to show the owner's name, but will fall back on the user ID number.</para></listitem>
<listitem><para>Group ID: tries to show the group's name, but will fall back on the group ID number.</para></listitem>
<listitem><para>Size: the file's size in bytes.</para></listitem>
<listitem><para>Date: the file's last modification date.</para></listitem>
<listitem><para>Status: status of the file in the archive. This indicates whether the file is in the archive ( [SAVED] ), is in a reference archive ( [InRef], which means this archive is an isolated catalog ), or is not in the archive ( [ ], which means that the archive is a differential one, and there was no change in the file since the previous backup ).</para></listitem>
</itemizedlist>
<para>Right-clicking on an archive item pops up a <interface>context menu</interface> which allows you to restore, diff or test that item and its children (subdirectories and files).</para>
<para>Each column can be sorted by clicking on its header at the top. The default sort is by the "permissions" column, which puts directories first in alphabetical order, then files in alphabetical order. Dates can be sorted chronologically, and sizes can be sorted by value.</para>
<para>The order in which the columns appear can be customized. Left-click the header of a column and drag it to the right or to the left to reposition it with respect to its neighbors. &kdar; will remember this configuration.</para>
<para>A movable splitter separates the <interface>Archive browser</interface> from the <interface>Message window</interface>. You can change the relative size of the two windows by moving the splitter (left-click and drag up or down), even hiding one of the panels this way.</para>
</sect1>
<sect1 id="restoring-archives">
<title>Restoring archives</title>
<para>Select "Archive->Restore", then choose a directory to extract your archive into.</para>
<screenshot>
<screeninfo>Restoring files</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="KDar-1.2.0-restore-empty-small.png"/>
</imageobject>
<textobject>
<phrase>Restore files from the archive onto your filesystem.</phrase>
</textobject>
<caption><para>Restore files from the archive onto your filesystem.</para></caption>
</mediaobject>
</screenshot>
<para>Individual files can be restored from the archive by right-clicking with the mouse on a file in the archive browser, and selecting <interface>Restore</interface>. You can select multiple files for restoration this way by holding down the <CTRL> key while left-clicking with the mouse.</para>
<para>You can select various restore options by clicking the configure button.</para>
<para>"Dry run": check this to perform a dummy restore, i.e. &kdar; will go through all the actions, but not actually restore any files. </para>
</sect1>
<sect1 id="isolating-archives">
<title>Isolating archive contents</title>
<para></para>
</sect1>
<sect1 id="diffing-archives">
<title>Comparing archives against a filesystem</title>
<para></para>
</sect1>
<sect1 id="testing-archives">
<title>Testing archive integrity</title>
<para></para>
</sect1>
</chapter>
<chapter id="questionsanswersandtips">
<title>Questions, Answers, and Tips</title>
<qandaset id="faq">
<title>Frequently asked questions</title>
<qandaentry>
<question>
<para>How do I exclude a specific file from being added to a new archive? The file filters exclude all files that have the same name, but I want to exclude only a specific one.</para>
</question>
<answer>
<para>Use a directory filter to exclude a specific file from the archive. Type the filename, including the full path to the file, when adding a new directory filter.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I get a "spacer undeclared" error while trying to compile the sourcecode:</para>
<screen>kdarConfigureDlg.cpp: In constructor `
kdarConfigureDlg::kdarConfigureDlg(QWidget*, const char*, bool, unsigned
int)':
kdarConfigureDlg.cpp:81: error: `spacer11' undeclared (first use this function)
kdarConfigureDlg.cpp:81: error: (Each undeclared identifier is reported only
once for each function it appears in.)</screen>
</question>
<answer>
<para>From the toplevel source directory do this:</para>
<screen>
<userinput><prompt>%</prompt> <command>make</command> -f admin/Makefile.common</userinput>
<userinput><prompt>%</prompt> <command>configure</command> (--options)</userinput>
<userinput><prompt>%</prompt> <command>make</command> clean</userinput>
<userinput><prompt>%</prompt> <command>make</command></userinput>
</screen>
</answer>
</qandaentry>
</qandaset>
</chapter>
<appendix id="installation">
<title>Installation</title>
<sect1 id="how-to-obtain-kdar">
<title>How to obtain kdar</title>
<para>You can download &kdar; from sourceforge
<ulink url="http://sourceforge.net/projects/kdar">here</ulink>.
</para>
</sect1>
<sect1 id="requirements">
<title>Requirements</title>
<para>KDar requires the following libraries:</para>
<itemizedlist>
<listitem><para>KDE version > 3.2.x</para></listitem>
<listitem><para>QT version > 3.2.x</para></listitem>
<listitem><para>libdar API version > 2.1.0</para></listitem>
<listitem><para>libz version > 1.1.4</para></listitem>
<listitem><para>libbz2 version > 1.0.2</para></listitem>
</itemizedlist>
<para> In order to compile KDar, you'll need a c++ compiler. g++ > 2.96 should work. In fact, you need to use the same compiler that your QT and KDE libraries were built with.
</para>
<para>Redhat-9 users: You'll need several RPM's installed to compile &kdar;. Basically, if you can compile DAR, you can compile &kdar; if you have the correct QT and KDE libraries installed. See the file INSTALL in the top-level source directory for details.
</para>
</sect1>
<sect1 id="compilation-and-installation">
<title>Compilation and Installation</title>
<para>Compiling kdar is very easy. The following should do
it: <screen>
<prompt>$</prompt> <userinput><command>./configure</command> --disable-debug</userinput>
<prompt>$</prompt> <userinput><command>make</command></userinput>
<prompt>$</prompt> <userinput><command>make</command> install</userinput></screen>
</para>
<para>That should do it! Remove the <userinput>--disable-debug</userinput> switch if you need to have debugging messages turned on.
</para>
<para>
<command>configure</command> should be able to detect the necessary settings for your system. If not, you can specify options to <command>configure</command> to force particular features to be enabled or disabled. To see what options libdar is compiled with, run
<screen><prompt>$</prompt> <userinput><command>dar</command> -V</userinput>
</screen>
and look for the following in the output:
<screen>
Using libdar 2.1 built with compilation time options:
Extended Attributes support: NO
Large files support (> 2GB): YES
ext2fs NODUMP flag support : YES
Special allocation scheme : YES
Integer size used : 64 bits
</screen>
To enable or disable largefile support (support for files larger than 2GB), pass the corresponding <userinput>--enable-largefile</userinput>
or <userinput>--disable-largefile</userinput> switch to
<command>configure</command>.
</para>
<para>Note that if you are running one of the
32-bit or 64-bit versions of libdar, you need to pass the corresponding
option to configure. e.g. to use the 64-bit version of
libdar (libdar64), run <screen>
<prompt>%</prompt> <userinput><command>./configure --enable-mode=64</command>
</userinput></screen>
</para>
<para></para>
<para> Should you run into any problems, first do your homework and check</para>
<itemizedlist>
<listitem><para>the INSTALL file in the top-level
&kdar; source directory,</para></listitem>
<listitem><para>and then the
<ulink url="http://sourceforge.net/mailarchive/forum.php?forum_id=37250">&kdar;-users mailing list archives</ulink>.</para>
</listitem>
<listitem><para>A <ulink url="http://www.google.com">google</ulink>
search might turn up something helpful.</para></listitem>
</itemizedlist>
<para>If you're still stuck, please report the problem to the <ulink url="mailto:kdar-users@lists.sourceforge.net">kdar-users@lists.sourceforge.net</ulink></para>
</sect1>
</appendix>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
sgml-general-insert-case: lower
End:
-->
