Warning, /utilities/kbackup/doc/en/index.docbook is written in an unsupported language. File is not indexed.

 <?xml version="1.0" ?>
 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
 
   <!ENTITY kbackup "<application>KBackup</application>"><!--FIXME remove entitiy when kbackup depends on kdoctools >= 5.42-->
   <!ENTITY % addindex "IGNORE">
   <!ENTITY % English "INCLUDE">
 ]>
 
 <book id="kbackup" lang="&language;">
 
 <bookinfo>
 <title>The &kbackup; Handbook</title>
 
 <authorgroup>
 <author>
 <personname>
 <firstname>Martin</firstname>
 <surname>Koller</surname>
 </personname>
 <email>kollix@aon.at</email>
 </author>
 </authorgroup>
 
 <!-- TRANS:ROLES_OF_TRANSLATORS -->
 
 <copyright>
 <year>2006 - 2017</year>
 <holder>Martin Koller</holder>
 </copyright>
 <legalnotice>&FDLNotice;</legalnotice>
 
 <date>2018-01-05</date>
 <releaseinfo>Applications 18.04</releaseinfo>
 
 <!-- Abstract about this handbook -->
 
 <abstract>
 <para>
 &kbackup; is an application which lets you back up your data in a simple, user friendly way.
 </para>
 </abstract>
 
 <keywordset>
 <keyword>KDE</keyword>
 <keyword>system</keyword>
 <keyword>KBackup</keyword>
 <keyword>backup</keyword>
 <keyword>storage</keyword>
 <keyword>archive</keyword>
 <keyword>zip</keyword>
 <keyword>gzip</keyword>
 <keyword>bzip2</keyword>
 <keyword>xz</keyword>
 </keywordset>
 
 </bookinfo>
 
 <chapter id="introduction">
 <title>Introduction</title>
 
 <para>
 &kbackup; is a program that lets you back up any folders or files,
 whereby it uses an easy to use folder tree to select the things to back up.
 It lets you save your settings in so-called <quote>profile</quote> files, where a profile is a simple
 text file containing definitions for folders and files to be included
 or excluded from the backup process.
 Also, it lets you define where the backup shall be saved to.
 The target can be either a local folder (&eg; a locally mounted device
 like a ZIP drive, USB stick, &etc;) but it can also be any remote &URL;
 (&eg; smb://remote/some_path) to back up your data to some central server, &etc;
 </para>
 
 <para>
 The program can also run an automated backup without using a graphical user interface.
 One can simply create a profile and use these settings to tell &kbackup; what to do
 when running in non-interactive mode, &eg; by starting it from a cron job.
 </para>
 
 <para>
 The program was designed to be very simple in its use so that it can be used
 by non-computer experts.
 </para>
 
 <para>
 The storage format is the well known TAR format, whereby the data can still be stored
 in compressed format (xz, bzip2 or gzip).
 </para>
 
 <para>
 The current implementation features only the backup step. To restore data back into
 your system, you currently have to use, &eg;, &dolphin; to open the TAR backup files
 and drag/drop the files back to your file system.
 This is also an advantage of the usage of the well known and well supported TAR file
 format.
 </para>
 <para>
 If the files are compressed, you can uncompress all files
 from the current folder recursively down with the following command:
 </para>
 <para>
 <programlisting>find . -name \*bz2 -print0 | xargs -0 bunzip2</programlisting>
 </para>
 <para>Alternatively you can use &ark; to extract a full backup or just a few files from a backup.</para>
 </chapter>
 
 <chapter id="using-kbackup">
 <title>Using &kbackup;</title>
 
 <para>
 All you need to do is to select which folders you want to store.
 This is done by selecting all the folders in the tree view on the left side
 of the main window.
 </para>
 
 <para>
 If you select a folder, &kbackup; will automatically store all files and
 subfolders below it.
 If you want to exclude parts of a selected folder, simply deselect that files/folders
 inside the still selected folder.
 </para>
 
 <para>
 In general, this means: A selected folder will store everything in it and below it,
 except the deselected parts in it.
 This also means, whenever you reuse a profile (see below) later on and new files
 have been added to a folder already selected for backup, all the new files will
 also be stored.
 </para>
 
 <para>
 
 <screenshot>
 <screeninfo>Here's a screenshot of &kbackup;</screeninfo>
         <mediaobject>
           <imageobject>
             <imagedata fileref="mainwindow.png" format="PNG"/>
           </imageobject>
           <textobject>
             <phrase>Screenshot of the Main Window</phrase>
           </textobject>
         </mediaobject>
 </screenshot>
 </para>
 
 
 <sect1 id="kbackup-profiles">
 <title>Using profiles</title>
 
 <para>
 To keep a selection for later use, simply save it into a &kbackup; profile file.
 Use the <guimenu>File</guimenu> menu and select <guimenuitem>Save Profile</guimenuitem>.
 </para>
 
 <para>
 To reload a selection into &kbackup;, use the <menuchoice><guimenu>File</guimenu> <guimenuitem>Load Profile...</guimenuitem></menuchoice> menu item.
 </para>
 
 <para>
 &kbackup; saves in a profile the selections for all included folders/files,
 excluded folders/files, the target folder/&URL;, defined archive prefix,
 the defined maximum slice file size, &etc;
 </para>
 
 <para>
 If you want to ease the usage of backing up every day the same set of
 files, simply store your settings into a &kbackup; profile (a <filename class="extension">.kbp</filename> file)
 and pass that file on the command line.
 </para>
 
 <para>
 &eg;:
 </para>
 
 <para>
 <programlisting>kbackup myData.kbp</programlisting>
 </para>
 
 <para>
 Hint: you can also create a shortcut on your desktop to a <filename class="extension">.kbp</filename> file
 as the file type is registered to start &kbackup; on double click.
 </para>
 
 </sect1>
 
 <sect1 id="archive-slices">
 <title>Archive slices</title>
 <para>
 As a medium has normally limited capacity (&eg; 100MB ZIP disc),
 &kbackup; will create several archive slices.
 </para>
 <para>
 Each archive slice will get its own name, which looks like this:
 </para>
 <para>
 backup_2006.08.26-13.04.44_1.tar
 </para>
 <para>
 The name contains the creation date and time (which will be the same for all
 slices of one backup) and a trailing slice sequence number (_1 in this example).
 </para>
 <para>
 In the menu <menuchoice><guimenu>File</guimenu> <guimenuitem>Profile Settings...</guimenuitem></menuchoice>, you can define a different archive prefix than the
 default <quote>backup</quote>.
 </para>
 
 <para>
 In the <guilabel>Profile Settings</guilabel> dialog, you can also define a maximum archive slice size,
 which limits the slice size even if there would be more space left on the target
 device.
 This helps to create archive slices which can then be later burned on a &CD;/&DVD;, &etc;
 If you explicitly limit the size of an archive slice, the available size
 will be marked with (*) in the main window.
 </para>
 <para>
 But even if you define a slice to be of <quote>unlimited</quote> size, there are other constraints
 which limit the size of a slice:
 <itemizedlist>
 <listitem><para>limited by the target folder (when stored directly into a local folder)</para></listitem>
 <listitem><para>limited by the <filename class="directory">/tmp</filename> folder when we create a tmp file for later upload to a remote &URL;</para></listitem>
 </itemizedlist>
 </para>
 
 <para>
 In the <guilabel>Profile Settings</guilabel>, you can also define a maximum number of full backups being kept
 in the target folder, and therefore automatically deleting all older backups there.
 &eg; if you set it to 3, &kbackup; will keep the last 3 backups and delete all older ones.
 </para>
 
 </sect1>
 
 
 <sect1 id="incremental-backup">
 <title>Incremental Backup</title>
 <para>
 With an incremental backup not all files will be saved every time the backup runs, but only
 the files which have changed since the last backup. This has the great advantage that the
 incremental backup will usually include much fewer files than a full backup and therefore
 will be finished in a much shorter time.
 </para>
 <para>
 This works as follows: In the profile, you define an interval (in days) for the full backup.
 &eg; when you define 5 days, then &kbackup; will do a full backup of all files every 5 days.
 Whenever you start &kbackup; before the interval expires with this profile - regardless
 how often you run a backup - only the files which have changed since the last backup will
 be saved. &kbackup; stores the time stamp of the last backup into the profile and knows
 therefore what to do when running the next time.
 </para>
 <para>
 The archive slice files created during an incremental backup will contain the text <quote>_inc</quote>, &eg;:
 </para>
 <para>
 backup_2010.06.14-18.50.26_1_inc.tar
 </para>
 <para>
 Full backup slice files will not include <quote>_inc</quote> in the name, &eg;:
 </para>
 <para>
 backup_2010.06.13-20.58.14_1.tar
 </para>
 <para>
 When one wants to restore files from an incremental backup, it's important to look for
 the most recent version of a file to be restored in all <quote>_inc</quote> files and finally also the last full backup
 slice file.
 This exactly is also the disadvantage of the incremental backup (but no advantage without disadvantage ;-) )
 </para>
 <para>
 If you want to do a full backup earlier than the defined incremental cycle time defined in a profile,
 you can do so by checking the <guilabel>Force Full Backup</guilabel> option in the user interface.
 When &kbackup; is started via the command line, this can be achieved by using the option <option>--forceFull</option>
 </para>
 <para>
 A forced full backup will restart the backup cycle, &ie; &kbackup; counts the days to the next full backup
 from the time of the last full backup.
 </para>
 </sect1>
 
 
 <sect1 id="archive-compression">
 <title>Archive Compression</title>
 <para>
 &kbackup; will compress the files stored if you activate this
 in the profile settings. Depending on
 the availability on your system it chooses <command>xz</command>, <command>bzip2</command> or <command>gzip</command> compression.
 &kbackup; will compress every single file
 and store all files with an added file extension (<filename class="extension">.xz</filename>, <filename class="extension">.bzip2</filename> or <filename class="extension">.gz</filename>) into the
 then not-compressed <filename class="extension">.tar</filename> archive.
 </para>
 
 <para>
 When you have selected to create the backup on some local filesystem
 (&eg; your extra disc, ZIP drive, &etc;) - which means you did not
 enter a remote target &URL; - &kbackup; might split the whole backup into several archive slices
 due to media capacity limitations.
 </para>
 <para>
 &eg;:
 </para>
 <para>
 backup_2006.08.26-13.04.44_1.tar
 </para>
 <para>
 backup_2006.08.26-13.04.44_2.tar
 </para>
 
 </sect1>
 
 <sect1 id="automating">
 <title>Automating Backup</title>
 
 <para>
 If you want to automate the process of the backup, &kbackup; offers different
 command line options to help with this:
 <itemizedlist>
 <listitem><para><option>--auto</option></para>
 <para>
 When you run &kbackup; with this option and a given <filename class="extension">.kbp</filename> profile, it will
 start, load the given profile, run the backup and terminate when done.
 All this is done with a visible &kbackup; user interface.
 </para>
 </listitem>
 
 <listitem><para><option>--autobg</option></para>
 <para>
 When you run &kbackup; with this option and a given <filename class="extension">.kbp</filename> profile, it will
 run the same process as with <option>--auto</option>  but <emphasis>without</emphasis> showing any graphical user interface.
 Therefore the suffix <quote>bg</quote> which stands for <quote>background</quote> - everything is done in the background
 so this is the right option to be used when you do your backups, &eg;, started by a cron job.
 </para>
 <para>
 When using <option>--autobg</option> the output from &kbackup; - showing the progress of the backup - is written
 to stderr. By default, the output includes just a few important messages and a summary at the end.
 If you pass <option>--verbose</option> in addition, then you will also see each file name currently being backed up.
 </para>
 </listitem>
 </itemizedlist>
 </para>
 
 </sect1>
 
 </chapter>
 
 <chapter id="commands">
 <title>Command Reference</title>
 
 <sect1 id="kapp-mainwindow">
 <title>The main &kbackup; window</title>
 
 <para>
 </para>
 
 <sect2>
 <title>The File Menu</title>
 <para>
 <variablelist>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Open Recent</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Shows a submenu with the recently used profiles for easy selection.
 </action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>New Profile</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Clears the selection and the target input field, to be able to define
 a new profile.</action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Load Profile...</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Loads a profile.</action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Save Profile</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Saves all settings into the currently loaded profile.</action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Save Profile As...</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Saves all settings into a profile with a new name.</action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>File</guimenu>
 <guimenuitem>Profile Settings...</guimenuitem>
 </menuchoice></term>
 <listitem><para>In the settings, you can define whether the archive-slice files
 start with the default name <quote>backup</quote> or with an alternative name.
 Also you can limit the archive slice size. See chapter <link linkend="archive-slices">Archive Slices</link>.
 These settings are also stored into the profile.
 </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>Quits</action> &kbackup;.</para></listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 </sect2>
 
 <sect2>
 <title>The Settings Menu</title>
 <para>
 <variablelist>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>Settings</guimenu>
 <guimenuitem>Dock in System Tray</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>
 When this option is activated, an icon is shown in the system tray, which reflects the current
 status of a backup operation. An animation is shown when a backup is in progress, else you see
 a static icon.
 If this option is selected, the closing of the main window will not terminate &kbackup;.
 The application must be explicitly terminated by selecting the <guimenuitem>Quit</guimenuitem> action.
 Via the context menu of the &kbackup; system tray icon you can start and cancel a backup operation -
 which is the same as you can do in the main window.
 The tooltip on this icon also gives progress information (Number of saved files, size of the backup and
 the last saved file).
 </action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>Settings</guimenu>
 <guimenuitem>Enable All Messages</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>
 Activating this entry clears all internally stored <guilabel>Do not ask again</guilabel> flags for
 the dialogs shown in &kbackup;.
 </action></para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><menuchoice>
 <guimenu>Settings</guimenu>
 <guimenuitem>Show Hidden Files</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Enable or disable</action> the display of hidden files (preceded
 by a dot character) in the tree view. Use this option if you want to exclude some
  hidden files from the backup. If you want to exclude all hidden files,
 use a filename filter in the profile settings.
 </para></listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 </sect2>
 
 <sect2 id="help-menu1">
 <title>The Help Menu</title>
 <para>
 &kbackup; has the common &kde; <guimenu>Help</guimenu> menu item, for more information read the section
 about the <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
 </para>
 </sect2>
 
 </sect1>
 </chapter>
 
 <chapter id="developers">
 <title>Developer's Guide to &kbackup;</title>
 
 <para>
 &kbackup; can be extended by using a shell script (or any other executable)
 which will be started at three different points during the backup process.
 The idea behind it is to allow to mount, unmount, eject media in a system
 specific way, or do other things with the produced archive files.
 </para>
 
 <para>
 The script to execute must be given with the <option>--script</option> command line option.
 </para>
 
 <para>Here is a sample script:</para>
 
 <example><title>sliceScript.sh</title>
 <programlisting>
 #!/bin/sh
 
 mode=$1
 archive=$2
 target=$3
 mountPoint=$4
 
 case "$mode" in
  "slice_init" )
     if [ "$mountPoint" != "" ]
     then
       mount /media/zip
       rm -f /media/zip/backup_2*.tar*
     fi
  ;;
 
  "slice_closed" )
  ;;
 
  "slice_finished" )
     if [ "$mountPoint" != "" ]
     then
       umount /media/zip
       eject /media/zip
     fi
  ;;
 esac
 </programlisting>
 </example>
 
 <para>
 The script is always invoked with four command line arguments:
 </para>
 <itemizedlist>
 <listitem><para>invocation mode</para> </listitem>
 <listitem><para>archive (slice) file name</para> </listitem>
 <listitem><para>target directory/&URL;</para> </listitem>
 <listitem><para>mountpoint of the target directory if it's a local directory, else an empty string</para> </listitem>
 </itemizedlist>
 
 <para>
 There are three possible invocation modes:
 </para>
 
 <para>
 <itemizedlist>
 
 <listitem><para>slice_init</para>
 <para>called before a new archive slice is being created on disc</para>
  </listitem>
 
 <listitem><para>slice_closed</para>
 <para>called after an archive slice has been created, but before it has been put into
 the target directory</para>
 <para>
 This can be used if you want to copy the archive slice to some additional place, &eg;
 the archive is sent to the main server (via a target &URL;), but you want to keep the last
 backup also onto the local disc.
 </para>
 </listitem>
 
 <listitem><para>slice_finished</para>
 <para>called after an archive slice has been successfully transferred into the
 target directory</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 </chapter>
 
 <chapter id="credits">
 
 <title>Credits and License</title>
 
 <para>
 &kbackup;
 </para>
 <para>
 Program copyright &copy; 2006 - 2009 Martin Koller <email>kollix@aon.at</email><!--FIXME use entities when kbackup depends on kdoctools >= 5.42-->
 </para>
 
 <para>
 Documentation Copyright &copy; 2006 - 2009 Martin Koller
 </para>
 
 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 
 &underFDL;               <!-- FDL: do not remove -->
 
 &underGPL;               <!-- GPL License -->
 
 </chapter>
 
 &documentation.index;
 </book>
 
 <!--
 Local Variables:
 mode: xml
 sgml-minimize-attributes:nil
 sgml-general-insert-case:lower
 sgml-indent-step:0
 sgml-indent-data:nil
 End:
 
 vim:tabstop=2:shiftwidth=2:expandtab
 kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
 -->