CatBack User Guide

This page is a modified version of the CatBack User Guide made available on this site for anyone interested in getting more information about CatBack without or prior to downloading the application.

Introduction

CatBack is a light-weight file backup program. CatBack attempts to differentiate itself from other available backup software in the following ways:

It is simple and easy to use. Complex features simply aren't worth the trouble.
Backup files are stored in a simple and easy to navigate directory structure. Restoring files is not dependent on the backup software.
It is easy to install. No complicated install process, no databases, no hassle.
It works on multiple platforms.
It is small in size.

CatBack keeps track of what files you want to back up by storing this information in a Backup Profile. Backup Profiles operate much like editing documents in that you can load them, save them, and create new ones.

When you start CatBack for the first time, you will want to create a new Backup Profile by selecting New from the File menu. Once this is done, you will be taken to a series of panels to enter your backup information. Follow through each panel by clicking the navigation buttons at the bottom or by selecting the panels from the panel list on the left side of the screen. The panels you will navigate through include:

Summary - provides an overview of your backup, and contains a button to execute the backup.
Name & Location - allows you to name your backup and select a location to backup to.
Backup Settings - includes settings to change the behavior of the backup process and how incremental backups are handled.
Included Files - provides a directory tree to select what directories and files will be backed up.
Excluded Files - provides a directory tree to select what subset of directories and files in the included set should be ignored.

When selecting your backup location, it is advised that you create and/or select an empty directory on another hard drive or network share. Before you exit CatBack, you will need to save your Backup Profile (if you try to exit without saving your Backup Profile, you will be prompted to do so).

As a convenience, CatBack will always reload the last Backup Profile on program startup.

Running CatBack

There are three ways to run cat back:

Run the jar: To do this, you need the catback jar file along with the jars of all CatBack dependencies in the same folder. You also need to specify the VM argument for the log4j2 configuration file. The required dependencies include log4j-api-2.19.0, log4j-core-2.19.0, markdownj-core-0.4, catswing-1.0.5, zenput-1.0.1, and, for non Mac systems, applestub-1.0.0.

javaw -Dlog4j.configurationFile=file:\\\C:\CatBack\log4j2.xml -jar catback-1.5.0.jar

Run the "fat jar": A "fat jar" has all dependencies packaged within a single jar. You no longer need to worry about other dependencies with this approach, but you will still need to specify the VM argument if you want logging to work.

javaw -Dlog4j.configurationFile=file:\\\C:\CatBack\log4j2.xml -jar catback-1.5.0-jar-with-dependencies.jar

Run the executable: The CatBack build uses Launch4J to build an executable version of CatBack that can be used on Windows systems. You no longer have to specify the VM argument for the log configuration file, but you still need Java 1.8 or later installed on your system. The exe is essentially a wrapper around the CatBack fat jar and is the easiest way to run CatBack, but because the exe file is not signed with a certificate issued by a common certificate authority, it should be noted that some virus scanning software may flag it as suspicious or as a threat.

catback.exe

Managing a Backup Profile

With your Backup Profile open, you can include or exclude files or directories to and from your backup set by checking or unchecking the checkboxes next to the files or directories on the included and excluded tabs. Checkboxes in CatBack have three states to be aware of:

An unchecked checkbox indicates that the file or directory will NOT be backed up (or NOT excluded, if on the Excluded tab).

A checked checkbox indicates that the file or directory WILL be backed up (or WILL be excluded, if on the Excluded tab).

A partially checked checkbox (horizontal line through checkbox) only occurs on directories, and it indicates that only some (but not all) files or directories beneath it will be backed up or excluded.

In addition, the file names will have one of four different appearances:

bold blue text - for files to be included in the backup.
bold red text - for files to be excluded from the backup.
bold black text - for directories where one or more files beneath it are either included or excluded.
plain gray text - for all other files and directories.

Excluded files and directories take precedence over included files and directories. The purpose of being able to mark files and directories as excluded (and the difference from simply unchecking those files and directories from the Included tree), is so that you can exclude those files while keeping the parent directories in the checked state on the Included tree (rather than a paritially checked state).

Note that you do not have to use the checkboxes in the excluded tree window; you can also just exclude files while in the included tree window by using the right-click context menu on files or directories within the tree.

Pay attention to any selected files or directories that have icons with a warning or missing indicator.

When you see the warning indicator (yellow triangle with exclamation point) on top of a directory icon, it indicates that one or more files beneath it are missing.
When you see the missing indicator (red circle with slash) on top of a file or directory icon, it indicates that the file or directory is missing.

When you see warning or missing indicators on checked files or directories, it means the selected files or directories were previously added to your backup set but are no longer found at their previous locations. Such files have generally either been deleted, renamed, or moved. If the files are renamed or moved, you will need to manually uncheck them and then recheck them at their new locations; you may also want to manually update the directory structure at the backup location if you do not want the backup process to recopy such files.

Performing Backup of Files

Start your backup by clicking on the Begin Backup button on the Summary panel or from the File menu (you can also run a backup by using the "-b" command-line switch described later). A backup consists of up to 6 steps. For each step a progress bar may appear if the step will take a significant amount of time. However, it is not uncommon for a step to be very quick and even skipped completely, in which case you will not see a progress bar for that step. Once the backup is complete, a prompt will appear with a summary of the backup process.

The backup steps are as follows:

Inspecting Files: A list of files you wish to backup is compiled. This generally takes very little time.
Inspecting Last Backup: A list of files from the last backup is compiled. This can take some time if you have a large backup set and the connection to the backup location is slow. This step can be skipped most of the time by by turning off the "Perform full scan of last backup" option in the preferences.
Comparing Files: The two compiled lists of files are compared. During this step, CatBack determines which files have changed and which files need to be backed up (any files that have not changed can be skipped). This can take some time if you have a large backup set and the connection to the backup location is slow.
Removing Expired Incremental Backups: Depending on your incremental backup settings, old incremental backup directories may be removed.
Moving Old Files: Any changed or deleted files since the last backup are moved into another directory in the backup location. (this provides an incremental backup; if no files have been deleted or moved, this step will be skipped and no incremental backup directory will be created.)
Copying New/Changed Files: New and changed files are copied from your source drive(s) to the backup location. This step opens an additional window which is initially minimized. Pay attention if this window still exists after the backup is complete, as this means there was one or more problems copying files during the backup. Switch to this window to see what the problems were and to decide what to do about those problems. However, under normal circumstances, there will be no copy problems and this window will automatically close after the copy step is complete.

When using the "-b" command line backup switch, a backup is immediately performed for the specified Backup Profile; if the backup completes normally, CatBack then exits. This type of backup execution is intended to allow a user to schedule periodic backups using a task scheduler. CatBack does not include a built-in scheduler, but most systems have their own task schedulers that can be used. For example, if you have a Backup Profile with filename c:\myfiles.catback, you could have a task scheduler periodically run CatBack using a command like follows:

catback.exe -b myfiles.catback

Restoring Files

CatBack stores files in a simple directory structure that mimics the structure on the source drive(s) you backed up. The backed up files are not compressed or changed in any way from their original versions. This is done for simplicity. Restoring files is as simple as navigating to the backup directory using your preferred file browser and copying the files back to your source drive.

The directory structure of the backup location includes a directory named latest that stores the most recent backup, and zero or more incremental backup directories with dates for names. When you perform a backup, all of the latest files go into the latest directory. Any files have have been changed or deleted since the last backup are moved into the incremental backup directory with the current date as a directory name. The incremental backup directories allow you to view and recover files from older backups if necessary. In addition to the latest and incremental backup directories, there should also be a statistics file named ".catback_stats" in the backup directory; this file contains your backup history. There will also be a file named ".catback_filelist" in the backup directory; this file stores information about the latest backup and allows CatBack to skip a full scan of the last backup on the next backup; this file is not critical but allows the backup speed to be accelerated so long as "Perform full scan of previous backup" is not checked in your Backup Settings.

As an example, assume you have a backup directory of D:/backup. Assume you have performed two backups since the Backup Profile was created, and the second backup was performed on March 3, 2009, where one or more files had been changed or deleted. In this case, you would have the following directory structure:

D:/

'-- backup/ (your chosen backup directory)

|-- .catback_filelist (file with metadata on last backup)

|-- .catback_stats (backup history file)

|-- latest/ (directory where latest backup is stored)

'-- 20090303/ (incrememtal directory where old and/or deleted files were moved to)

You can configure how long to keep incremental backup directories for in your backup settings. Or you can manage them yourself, simply by deleting incremental backup directories you no longer wish to keep. If more than one backup is performed on the same day, subsequent incremental backup directories on that day will have an additional number appended to the directory name (i.e., if a second backup was performed on March 3, 2009, it might create the directory 20090303-1).

Dry Runs

CatBack can be put into a "Dry Run" mode with the following command-line switch:

"-dryrun"

In Dry Run mode, you can see what CatBack would do when launching a backup without having it actually perform the backup. In effect, it will simulate any backup you run without actually copying, moving, or deleting any files to or from the backup location. However, changes to the backup settings will be applied like normal; only the execution of the backup is simulated.

The simulated speed of copying each file can be changed with additional command-line argument:

"-speed <speed-factor>"

The simulated time to copy a file will be equal to, in milliseconds, the size of the file in bytes / speed-factor. However, there is also a set maximum simulated copy time of 6 seconds for each file. The default speed-factor value is 10000.

Logging

Logging is configured via a log4j2.xml logging configuration file. Normally, this file would reside in the application startup directory. If you start CatBack without this file present, it will automatically be created, but will not take effect until the next time CatBack is started.

The default log4j2.xml configuration file will send log messages to the file "catback.log" located in the application startup directory. You can reroute logging in CatBack by adding one of the following command-line switches when starting the program:

"-l off" - turns off logging

"-l console" - sends logging messages to the console (note: you normally will not see console output if launching CatBack from a desktop shortcut or start menu)

"-l window" - sends logging messages to a dialog window within the application. When this is active, the dialog is launched from the Application Log menu item in the Window menu.

"-l file:<log-file-path>", where log-file-path is the file path and name of the log file. Leave off the colon and log-file-path to reset to the default log file.

When using the -l flag, the log4j2.xml file is re-written to provide the desired logging configuration. To pick up the changes, the application must be restarted. If you are familiar with log4j2 configuration files, you can also manually modify the configuration to your own liking.

Version History

Detailed version history information is available through the Cat Back main menu (Help --> About). The first version of CatBack was released in 2009.

Requirements and Credits

CatBack is a Java application and requires Java 1.8 or later to operate.

Testing on CatBack has only been performed under various versions of Windows and Mac OS X. Linux platforms have been tested as backup locations only. CatBack has been designed to work with large backups, and has been successfully tested with backups as large as 100,000 files and totaling over 500 GB.

Credits:

Author: Scott Arnold
Contributor: Cari Arnold
Logging Engine: log4j 2.19
Icons: Glaze icons by Marco Martin
Textures: Genetica Textures by Spiral Graphics
Bitwise File Compare Code: Joe Orost
Java Version: 8 (1.8)

Page updated

Google Sites

Report abuse