# The &kbackup; Handbook

## Introduction

&kbackup; is a program that lets you back up any directories or files, whereby it uses an easy to use directory tree to select the things to back up. It lets you save your settings in so called "profile" files, where a profile is a simple textfile containing definitions for directories 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 directory (e.g. a local mounted device like a ZIP drive, USB stick, etc.) but it can also be any remote URL (e.g. smb://remote/some_path) to back up your data to some central server, etc.

The program was designed to be very simple in its use so that it can be used by non-computer experts.

The storage format is the well known TAR format, whereby the data is still stored in compressed format (bzip2 or gzip).

The current implementation features only the backup step. To restore data back into your system, you currently have to use e.g. konqueror 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.

## Using &kbackup;

All you need to do is to select which directories you want to store. This is done by selecting all the directories in the treeview on the left side of the main window.

If you select a directory, &kbackup; will automatically store all files and subdirectories below it. If you want to exclude parts of a selected directory, simply deselect that files/directories inside the still selected directory.

In general this means: A selected directory 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 directory already selected for backup, all the new files will also be stored.

Here's a screenshot of &kbackup; Screenshot of Main Window

### Using profiles

To keep a selection for later use, simply save it into a &kbackup; Profile file. Use the File Menu and select "Save profile".

To reload a selection into &kbackup;, use the File Menu "Load Profile".

&kbackup; saves in a profile the selections for all included directories/files, excluded directories/files, the target directory/URL, the defined archive prefix and the defined maximum slice file size.

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 .kbp file) and pass that file on the commandline.

E.g.:

kbackup myData.kbp

Hint: you can also create a shortcut on your desktop to a .kbp file as the file type is registered to start &kbackup; on double click

### Archive slices

As a medium has normally limited capacity (e.g. 100MB ZIP disc), &kbackup; will create several archive slices.

Each archive slice will get its own name, which looks like this:

backup_2006.08.26-13.04.44_1.tar

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).

In the menu File/Profile Settings you can define a different archive prefix than the default "backup".

In the Profile Settings 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 explicitely limit the size of an archive slice, the available size will be marked with (*) in the mainwindow.

### Archive Compression

&kbackup; will always compress the files stored (except you explicitely deactivate this in the profile settings). Depending on the availability on your system it chooses bzip2 or gzip compression.

When you have selected to create the backup on some local filesystem (e.g. your extra disc, ZIP drive, etc.) - which means you did not enter a target URL - &kbackup; might split the whole backup into several archive slices due to media capacity limitations. &kbackup; will compress every single file and store all files with an added file extension (.bzip2 or .gz) into the then not-compressed .tar archive.

e.g.: backup_2006.08.26-13.04.44_1.tar

When you have selected a target URL, which is displayed as unlimited medium size, &kbackup; will create only one archive, which includes the non-compressed files, but it will compress the whole .tar archive as the last step.

This always results in an archive file with the file extension .tar.bzip2 or .tar.gz

e.g.: backup_2006.08.26-13.04.44_1.tar.bzip2

## Command Reference

### The main &kbackup; window

#### The File Menu

File New Profile

- Clears the selection and the target input field, to be able to define a new profile.

File Load Profile

- Loads a profile

File Save Profile

- Saves all settings into a profile

File Profile Settings

- In the settings, you can define whether the archive-slice files start with the default name "backup" or with an alternative name. Also you can limit the archive slice size. See chapter "Archive Slices". This setting is also stored into the profile.

&Ctrl;Q File Quit

- Quits &kbackup;

#### The Settings Menu

Settings Dock in System Tray

- 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 mainwindow will not terminate &kbackup;. The application must be explicitely terminated by selecting the "Quit" 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 mainwindow. The tooltip on this icon also gives progress information (Number of saved files, size of the backup and the last saved file).

#### The Help Menu

&help.menu.documentation;

## Developer's Guide to &kbackup;

&kbackup; can be extended by using a shellscript (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.

The script to execute must be given with the --script commandline option.

Here is a sample script

### sliceScript.sh

    #!/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

The script is always invoked with four commandline argument:

- invocation mode

- archive (slice) file name

- target directory/URL

- mountpoint of the target directory if it's a local dir, else an empty string

There are three possible invocation modes:

- slice_init

  called before a new archive slice is being created on disc

- slice_closed

  called after an archive slice has been created, but before it has been put into the target directory

  This can be used if you want to copy the archive slice to some additional place, e.g. 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.

- slice_finished

  called after an archive slice has been successfully transferred into the target directory

Another example shows how you can limit the number of archive files in the target:

### rotateScript.sh

    #!/bin/sh
    # kbackup script to do a rotating backup (keep only a defined number of backups)

    NUM_BACKUPS=20

    mode=$1
    archive=$2
    target=$3
    mountPoint=$4

    case "$mode" in
     "slice_init" )
     ;;

     "slice_closed" )
     ;;

     "slice_finished" )
       count=`ls -A1 $target | wc -l`
       if [ $count -ge $NUM_BACKUPS ]
       then
         removeCount=`expr $count - $NUM_BACKUPS`
         oldest=`ls -A1 ${target}/* | sort | head -n $removeCount`
         rm -f ${oldest}
       fi
     ;;
    esac

## Questions and Answers

&reporting.bugs; &updating.documentation;

## Credits and License

&kbackup;

Program copyright © 2006, 2007 Martin Koller m.koller@surfeu.at

Documentation Copyright © 2006, 2007 Martin Koller

&underFDL; &underGPL;

## Installation

### How to obtain &kbackup;

You can download &kbackup; from www.kde-apps.org

### Compilation and Installation

&install.compile.documentation;
&documentation.index;