# Technical Information

## Backup formats

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

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

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

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

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

## 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 guaranteed 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.

## Application data & logging

fwbackups stores all of its logs and configuration in the `~/.fwbackups` folder on Linux, or `%APPDATA%\fwbackups` on Windows. The GUI adminsitrator's application preferences are written to a file named `fwbackups-prefs.conf`.

The fwbackups log file is written to `fwbackups-userlog.txt` in the application data folder; it is not rotated automatically. Whenever the backup administrator is run or a backup/restore operation is started, the fwbackups log file will be appended to.

Backup sets are .ini-style files stored in the `Sets` subfolder of the application data, and must have a `.conf` extension in order to be read by fwbackups. The files are portable between different machines and platforms, and will be automatically upgraded on first read if they are from a prior fwbackups version.

## Command-line interface

fwbackups offers limited command-line tooling to run one-time backups or start a backup of an existing backup set. `fwbackups-run SetName` will execute an immediate backup using the settings configured for the named backup set. `fwbackups-runonce SrcPath DstPath` will run a one-time backup of the specified paths to the specified destination. Execute either command with the `--help` parameter for full options and usage details.