Product SiteDocumentation Site

fwbackups 1.43.4

User Guide

Using fwbackups for easy, automated backups

Edition 1

Stewart Adam

Diffingo Solutions Inc.

Legal Notice

Copyright © 2010 Stewart Adam
The text of and illustrations in this document are licensed under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Windows® is a registered trademark of Microsoft Corporation in the United States and other countries.
All other trademarks are the property of their respective owners.
Abstract
This user guide will help you use and configure fwbackups. It provides instructions for creating and configuring backups, as well as documentation for the various configuration options available to you in fwbackups.
Preface
1. We Need Feedback!
1. Getting Started
1.1. Introduction
1.2. Starting fwbackups
2. Using fwbackups
2.1. Backup types
2.2. Creating a backup set
2.2.1. Paths
2.2.2. Destination
2.2.3. Times
2.2.4. Options (Simple)
2.2.5. Options (Advanced)
2.3. Editing an existing set
2.4. Running a backup only once
2.5. Restoring backups
2.6. Importing or exporting sets
2.7. Changing your preferences
3. Technical Information
3.1. Backup formats
3.1.1. Archive/tar backups
3.1.2. Direct Copy/rsync backups
3.1.3. Minimum storage requirements
3.2. Preservation of file ownership and other attributes
3.3. Expected levels of reliability
4. About fwbackups
4.1. About fwbackups
4.2. Reporting a problem
A. Revision History

Preface

1. We Need Feedback!

If you find a typographical mistake in this user guide or if you have an idea to improve this manual, your comments are appreciated! Please contact the author, Stewart Adam, at .
If you are reporting an error, please include the section name that the error is in as well as some surrounding text so that it can be found easily.

Chapter 1. Getting Started

1.1. Introduction
1.2. Starting fwbackups

1.1. Introduction

fwbackups is a feature-rich user backup program that allows you to backup your documents anytime with ease. Its simple, intuitive interface offers the following features:
  • Each user of the system can configure their own backups
  • On-demand or automated backups for files and folders via backup sets
  • A tray icon to monitor the current progress of backups or restore operations
  • Several backup engines including compression and incremental backups
  • Support for backing up to a remote host via SSH/SFTP
  • Support for restoring any of the backups created with fwbackups

1.2. Starting fwbackups

There are two ways to start the fwbackups:
  1. Graphically (recommended for most users):
    Select Applications → System Tools → fwbackups from the menu.
  2. From the command line interface:
    Start a terminal, type fwbackups and then press the Return key.

    Note

    More options are available! Type fwbackups --help to see all the available options and their descriptions.
The Overview page
Figure 1.1. The Overview page

fwbackups starts on the Overview page. To begin using fwbackups, simply click a one of the toolbar buttons to switch pages.
Backup Sets
Create, edit or remove backup sets as well as manually start a set backup.
One-Time Backup
Perform "one-time" backups (backups that will not be scheduled to run at a future date).
Log Viewer
Displays the log file, showing information about fwbackups's activities.

Note

  • All log messages are formatted like this: Month DD HH:MM:SS :: severity : message
  • Messages from previous sessions are displayed as purple text
  • Messages from the current session are displayed as blue text
  • Errors and warnings are displayed as red and yellow text respectively
Restore
Allows you to restore any backup you previously made using fwbackups.

Chapter 2. Using fwbackups

2.1. Backup types
2.2. Creating a backup set
2.2.1. Paths
2.2.2. Destination
2.2.3. Times
2.2.4. Options (Simple)
2.2.5. Options (Advanced)
2.3. Editing an existing set
2.4. Running a backup only once
2.5. Restoring backups
2.6. Importing or exporting sets
2.7. Changing your preferences

2.1. Backup types

fwbackups supports two main types of backups: recurring backups that automatically backup your files on a schedule, and backups that are run once and not scheduled again. These are referred to as as backup sets and one-time backups respectively.
You will be able to configure any number of backup sets, each backing up on a regular schedule at a time of your choice. Each set operates independently, so if you wish you may group files into two or more sets and have them backup at different times or to different destination folders. You may also perform one-time, however in this case the backup will not be scheduled to start again in the future.

When to use set or one-time backups

It is recommended that you create a backup set for your important files in order to ensure that you have a recent backup copy saved at all times. One-time backups are more suitable for making backups of large files, such as a music collection or video that you may not want to include in a backup set that is started daily or weekly.

2.2. Creating a backup set

The Backup Sets page
Figure 2.1. The Backup Sets page

To create a new set, click Backup Sets on the toolbar to switch pages and then click the New Set on the left.

2.2.1. Paths

The paths tab allows you to select which files and folder are to be included in the backup. To add files, click Add File or Add Folder. If you wish to remove a file or folder from the backup, select one or more paths from the list and click Remove.
Each path in the list will have either a green or red icon next to it. A green icon indicates that fwbackups is able to read path, while a red icon indicates that the file is missing or unable to read the path and it may be excluded from future backups.

Drag 'n' Drop!

Adding files or folders is as easy as dragging them from your favourite file manager and dropping them onto the path list.

2.2.2. Destination

The destination tab controls where your backup will be saved to. You may choose to backup to a local drive, removable storage or a remote computer supporting the SFTP protocol (if your computer runs the OpenSSH server, it most likely supports SFTP).
Configuring backup destinations
Figure 2.2. Configuring backup destinations

Remember to test settings for remote destinations

If you choose to backup to a remote host, be sure to click Test Settings before saving your set! A typo in the password (and other fields) can leave fwbackups unable to connect to to the remote host, resulting in a failed backup.

2.2.3. Times

This tab controls the time and date at which the backup should be started at. Both easy configuration and manual configuration (crontab) methods are supported. Using the easy configuration is recommended for most users.
The easy configuration is uses a series of drop-down boxes, and sliders to determine at which time fwbackups should schedule a backup. A backup of the set is run whenever the date matches the chosen parameters. That being said, be careful when selecting the minute for your backup operation! A common user error is choosing Every minute for the backup time, causing a a new backup to start at every minute of the hour. It is recommended instead to choose a specific minute at which the backup will start at, for example "0" (at the beginning of the hour) or "30" (for half-way through the hour).
Setting a backup schedule for a set
Figure 2.3. Setting a backup schedule for a set

If you wish to further customize the times at which the backup operation starts, you may use the manual configuration method to do so. It uses crontab syntax:

+-------------- minute (0 - 59)
| +------------ hour (0 - 23)
|  | +---------- day of month (1 - 31)
|  |  | +-------- month (1 - 12)
|  |  |  | +------ day of week (0 - 7) (Sunday=0 or 7)
|  |  |  |  |  +-- command to run
|  |  |  |  | |
*  *  *  *  * command

Simply enter the same values you would into a crontab, as outlined above, into the designated entry boxes. Please note that you cannot enter all five fields onto one line; the four fields are divided among four different entry boxes. As well, it is important to note that in manual configuration mode no validation is performed on user input and you must supply valid values for the first five fields. The sixth field, used for the command, is generated automatically by fwbackups.
  • Use a comma (,) to specify a list of values
    Example 2.1. Using a comma
    2,4,5,7,8,9

  • Use a dash (-) to specify a range of values
    Example 2.2. Using a dash
    1-4 is equivalent to 1,2,3,4

  • Use an asterisk (*) to specify all possible values
    Example 2.3. Using an asterisk
    * in the hours field is the same as 0-23 or 1,2,3,[...],23

  • Most variants of cron support the forward slash (/) to designate a skip
    Example 2.4. Using a forward slash
    */2 in the minutes field is equivalent to 0,2,4,6,8,[...],58

  • In the day of the week field, both 0 and 7 are counted as Sunday.
  • If both day of month and day of week are present, the command will be executed when either is true.

2.2.4. Options (Simple)

The Options (Simple) tab allows you to set the parameters for your backup. In addition, the options tabs allow you to you select the backup format and the number of old backups to keep at any given time.
Backup Format
Your backup will be stored differently differently depending on the backup format selected (this option replaces the Backup Engine selection in versions 1.43.2 and earlier).
An Archive backup packs all of the files into a single (often large) "tar" archive file. Archive backups do not support incremental backups; a full snapshot must be created each time. Archive backups support both gzip and bzip2 on-the-fly compression. This backup format was formerly called the "tar" backup engine (".gz" or ".bz2" was appended if gzip or bzip2 compression was enabled, respectively).

Reducing backup size with compression

Enabling compression will utilize more system resources during the backup, but results in smaller file sizes. gzip is a relatively lightweight compression with a good compression ratio. If you would like to further reduce the size of your backups, consider switching to bzip2 compression. Although it is much slower than gzip, bzip2 is able to achieve smaller file sizes.
A Direct copy backup will simply copy your files and folder structure as-is (similar to a drag-and-drop copy in your file browser). Although this backup type does not support compression, incremental backups are available. This backup format was formerly called the "rsync" backup engine.

Increasing backup speed

Enabling the Backups are incremental option will run an incremental backup instead of a full one, copying only the changes since your last backup. Currently, the incremental backups are only available for set backups on Unix-like platforms (such as Linux and OS X) and cannot be used when backing up to a remote host.
Additionally, running an incremental backup will update the backup folder in-place so no old backups will be kept if you choose to enable incremental backups.
Set is enabled
If deselected, the set will be unscheduled for automated backups (not available in one-time backups).
Include subfolders
If selected, subfolders will be included in the backup (recommended). If unchecked, fwbackups will only backup files immediately inside any folders supplied in the Section 2.2.1, “Paths” tab and will not backup any files in subfolders.
Include hidden files
If selected, Unix-style hidden files (files and folders starting with a period character ".") are included in the backup.

Hidden files on the Windows platform are always backed up

Support for detecting Windows-style hidden files will be added in the future. Until then, hidden files and folders on all Windows operating systems will be included in the backup regardless of the state of this checkbutton.
Follow links
If selected, the backup will follow symbolic links and copy their targets rather than copying the link into the backup. Be wary of link recursion!
Print disk geometry information to a file
If selected, disk geometry (including partition layout) will be saved to a file that will be added to the backup.
Print installed packages to a text file
If selected, a list of installed package names and versions will be saved to a text file that will be added to the backup. This option can be used to ease system reinstallation in the unfortunate event of a crash or data loss.
Currently, the RPM, dpkg and pacman package managers are supported.
Handle sparse files efficiently
If selected, sparse files on the disk will be handled more efficiently.

2.2.5. Options (Advanced)

The Options (Advanced) tabs include technical or complex options that you can use to customize how your backup functions.
Command to run before backup
Command(s) entered here will run in the default system shell before fwbackups begins to backup files (not available in one-time backups).
Command to run after backup
Command(s) entered here will run in the default system shell after fwbackups has finished backing up (not available in one-time backups).

Tokens

Both the before and after backup commands support token string replacements. fwbackups will replace tokens you use in your commands with their appropriate values:
[successful]
If the backup was completed successfully without errors, this token will be substituted for 1. In the event of a failure or backup error, a 0 will be substituted.
[destination]
The destination folder (see Section 2.2.2, “Destination”). If a remote host is being used, then this will be token will be the remote folder.
[set]
The set name
[date]
The date string (YYYY-MM-DD_HH-MM) when the backup was started
[backup]
The name of the backup file or folder that will be stored in the backup destination. It is equivalent to Backup-[set]-[date], plus the archive extension if applicable.
[remote_host]
The hostname of the remote machine where the backup will be store
[remote_port]
The port to connect to the remote hostname on
[remote_username]
The username used to connect to the remote host
[remote_password]
The password used to connect to the remote host
Use [destination]/[backup] if you need the absolute path to the new backup folder or file. If you want to escape one of the tokens (for example, to actually use the text [date] in a command), prefix it by a backslash (\[date]).
Nice value of backup process
This controls the priority of the backup (a lower nice value indicates a higher priority). This feature is only available on Unix-like platforms. Only the root user may select negative nice values.
Exclude from backup
Files and folders matching the patterns listed in this text entry will be excluded from the backup. File, folder or patterns for exclusion should be entered one per line. The contents of this text entry will be passed directly to the tar or rsync processes when performing the backup. In the example below, all files in the /home/username/Exclude folder, all files with the png extension, the file /home/username/foobar.jpg and lastly any file named specificname.txt are all excluded from the backup.
Example 2.5. Excluding files

/home/username/Exclude/*
*.png
/home/username/foobar.jpg
specificname.txt


2.3. Editing an existing set

Switch to the Backup Sets page and select the desired set. Click Edit Set to open the backup configuration dialog. You can configure existing sets in the same way you would configure a new set (see Section 2.2, “Creating a backup set” ).

2.4. Running a backup only once

  1. Switch to the One-Time Backup page
  2. Add the files and/or folders you would like to backup to the list. Similar to the Paths tab in the backup configuration dialog, you may use the Add File(s)/Folder(s) buttons or simply drag-and-drop the files and folders into the list. When finished, click Next.
    Adding paths to a One-Time Backup
    Figure 2.4. Adding paths to a One-Time Backup

  3. Choose your backup options (see Section 2.2.4, “Options (Simple)”). When finished, click Start Backup to begin the operation.

2.5. Restoring backups

fwbackups can restore your files and folders from any set or one-time backup.
  1. To start, click Restore on the toolbar to open the restore dialog.
  2. Enter the folder where you wish to restore your files to into the entry labelled Restore to. To the make selection more convenient, you may use the Browse... button to open a file browser dialog. A green icon indicates that the folder entered is writable and a red icon indicates that the folder is unwritable (another must be chosen or the restore operation will fail).

    Folder structure

    Folder structure is preserved in restore operations, so files will be restored relative to their original location. For example, restoring a backup of of /home/myusername to /tmp will result in your files being restored to /tmp/home/myusername.
    Setting the restore location to the root directory (/ on Linux, Mac OS X and other Unix-based platforms) or the root drive (typically C:\ on the Windows platform) will restore your files to their original locations.
  3. Select where to restore files from. There are several possible options:
    Set backup
    Drop-down menus will be available for you to select the set name and backup date to use for the restore operation.
    Local archive
    Use this option to restore Archive/tar format one-time backups available on local storage (such as hard disks or removable media). Click Browse... to select the location of the archive file to restore.
    Local folder
    Use this option to restore Direct copy/rsync format one-time backups available on local storage (such as hard disks or removable media). Click Browse... to select the backup folder to restore.
    Remote archive (SSH)
    Same as Local archive with the exception that the archive will be retrieved from a remote machine before restoring its contents.
    Remote folder (SSH)
    Same as Local folder with the exception that the folder will be retrieved from a remote machine before restoring its contents.

    This feature is a work in progress

    Restoring from remote folders is a new feature that is supported not speed-optimized yet. This operation may be slow.
    Once you have configured the restore operation, click Start Restore to begin restoring files. Depending on the size of your backup, restoring files may take some time.

2.6. Importing or exporting sets

To import set configuration files (.conf files), select File → Import Sets and then select the .conf file(s) to be imported. All versions of fwbackups configuration files can be imported.
To export a set so that you can import again it later, select File → Export Sets and select the sets you would like to export by selecting the checkbox next to the set name. After choosing a folder, click Export Sets to save the selected sets to the chosen folder.

Note

The location at which set configurations are stored is ~/.fwbackups/Sets on Linux, Mac OS X and other Unix-based platforms and %APPDATA%\fwbackups\Sets on the Windows platform.

2.7. Changing your preferences

Select Edit → Preferences from the menu to open the preferences dialog:
The Preferences dialog
Figure 2.5. The Preferences dialog

Show tray icon
Toggling this checkbox will show or hide the tray icon.
Show notifications in tray area
Select this is you wish to receive notifications like the one below for important events:
Minimize to tray on close
Selecting this checkbox will make fwbackups minimize to the tray icon when closing instead of quitting.

Note

Clicking the tray icon will reopen the main fwbackups window.
Start minimized
Select to have fwbackups to only show the tray icon and to hide the main window when starting.
Always show debug messages
This option enables all debugging messages in the log viewer. Use this if you are trying to troubleshoot a problem.
Start fwbackups (minimized) when I login
Select to have fwbackups start minimized, but only when you login.
Pycron installation folder
When running on the Windows platform, fwbackups will use pycron to schedule tasks and must know where pycron has been installed. The installation folder will be auto-detected in most cases, but in the event that it isn't use the Browse button to select the pycron installation folder.
"Don't show me again" messages
Several messages in fwbackups can be disabled by selecting Don't show me again when they appear. If you would like to enable these messages again, click the button.

Chapter 3. Technical Information

3.1. Backup formats
3.1.1. Archive/tar backups
3.1.2. Direct Copy/rsync backups
3.1.3. Minimum storage requirements
3.2. Preservation of file ownership and other attributes
3.3. Expected levels of reliability

3.1. Backup formats

This section details how fwbackups create backups and each type of backup's storage requirements.

3.1.1. Archive/tar backups

Archive backups use one of two methods to create the backup archive depending on the operating system. On Unix-like operating systems such as Linux, Unix and OS X, the tar executable is called upon directly to create a standard GNU tar archive, optionally with gzip or bzip2 compression. On Windows, Python's tarfile module is used to create a standard GNU compliant tar archive. In either case, backup compression is applied on-the-fly without the need for the tar archive to be created first.
Because the backup is in the format of a standard tar archive, should fwbackups ever fail to restore a backup any utility supporting the tar format such as GNOME's integrated file-roller utility or 7-zip on Windows may be used to extract files from the backup. For those confortable with the command line, a simple tar xfz <backup file> will extract all files from the backup.

3.1.2. Direct Copy/rsync backups

As with Archive backups, Direct copy backups will use one of two methods to copy files depending on the operatng system. On Windows, fwbackups uses a slightly modified version of the Python shutil library to copy files and folders. On Unix-like operating systems (Linux, Unix and OS X) fwbackups determines the appropriate parameters and then makes a call to rsync to copy the files (rsync is faster than shutil and therefore is used when the OS supports it). Thus, in either case the result is a direct copy of the files and folder structure.
Because files have been copied directly, if fwbackups fails to restore your files simply copying them from the backup destination to their desired location via drag-and-drop in your file browser will suffice.

3.1.3. Minimum storage requirements

Depending on your backup format and destination, the minimum storage requirements to complete a backup may change.
For local backups, both the Archive and Direct copy backup engines will copy files from the disk source to the destination without the need for temporary storage, even if compression is enabled. Therefore, you should have no problems backing up a full disk so long as your destination is on another volume such as USB or removable storage.
Backups to remote destinations have different storage requirements. Archive backups with a remote destination create the archive locally and then upload it via SFTP to the remote host. Therefore, you must have free space equal to the size of the files being backed up (unless compression is enabled, in which case slightly less would be required). In a Direct copy backup with a remote destination, files are uploaded directly to the remote machine and therefore it is possible to backup a full drive. However, be warned that a remote direct copy is significantly slower than a archive backup.

3.2. Preservation of file ownership and other attributes

fwbackups uses the internal Python tarfile and shutil modules to restore files (and paramiko for interfacing with remote hosts via SFTP). File permissions, modification time and access time are always preserved, as are symbolic links.
Local backups should preserve ownership on Unix-like operating systems, however OSs commonly do not allow regular users to change the ownership of files and thus the backup would need to be extracted manually as root in order to preserve ownership. Remote backups will not preserve ownership, as any files uploaded over SFTP assume the owner of the user used to connect to the remote machine. Please note that in the case of an archive backup to a remote host, this only applies to the actual archive file. The archive itself may contain file ownership information and once it has been retrieved from the remote host, it can be extracted manually similarly to a local archive backup if the user wishes to preserve file ownership.
Other file attributes, xattrs or ACLs may be stored in the backup (depending on the backup format, the OS the backup was created on and filesystem) however fwbackups will not attempt to restore them.

3.3. Expected levels of reliability

fwbackups is a user backup program and accordingly, should be able to backup your user data without issues. Although it is possible to use fwbackups to backup an entire operating system, this was not its intended purpose and this scenario is as of yet untested. Users should expect fwbackups to successfully backup and restore their data, however (as described above) extra metadata such as file ownership, ACLs and extended attributes that an OS may require to function properly are not guarunteed to be restored along with the actual file data.
Prior to each release of fwbackups, the code is put through a test suite which automates each possible type of backup and restore operation and verifies that each of those operations completed successfully. Nonetheless, unexpected bugs in software do happen and migitate the risk of unintentional data loss, users are recommended to check the fwbackups log regularly to ensure no errors are occuring, as well as periodically verify backups to ensure that no files are missing.

Chapter 4. About fwbackups

4.1. About fwbackups
4.2. Reporting a problem

4.1. About fwbackups

fwbackups is written by Stewart Adam ( ), To find more information about fwbackups, please visit the fwbackups homepage.
This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found in the file COPYING included with the source code of this program.
If you would like to offer feedback, help develop or test upcoming versions of fwbackups, please contact the author at the email address above. Any comments are welcome!

4.2. Reporting a problem

If you think you have found a problem or bug in fwbackups, please contact the author at .
If you can reliably reproduce the issue you are experiencing, enable debug messages in the preferences and try to reproduce the problem again. If you are able to, attach a copy of the fwbackups log and (if applicable) the set configuration in question to the email message.
Any information sent will be kept confidential and will be used strictly for troubleshooting purposes.

Revision History

Revision History
Revision 4Mon Dec 20 2010Stewart Adam
Release 1.43.4
Revision 3Tue Nov 30 2010Stewart Adam
Release 1.43.3
Revision 2Thu Oct 28 2010Stewart Adam
Update documentation for 1.43.3rc6
Revision 1Thu July 1 2010Stewart Adam
Finish updating user guide for version 1.43.3rc5
Revision 0Thu July 1 2010Stewart Adam
Port user guide to publican publishing tool