### dest

<h1>Destination Help</h1>

<h2>Backup to Directory</h2>

If this option is used, TwcBackup will store all backups in a (local)
directory.

<h3>Directory</h3>

Absolute path to the directory (example: /BACKUP).

<h2>Backup to External Disk</h2>

If this option is used, TwcBackup will mount an external disk for backup,
store the backups on that external disk, and umount that disk on each
backup run.

<h3>Disk Label</h3>

The external disk must have a filesystem label that corresponds to this
property, otherwise the backup will fail.

<h1>Backup Weekday Configuration</h1>

<h2>Backup Time</h2>

The backup of the work of the day usually occurs after the day is over. Since
TwcBackup needs to figure out which weekday this backup belongs to, the user
needs to specify whether the backup is started on the same day, in the evening
or on the next day, in the morning.
<p>
The first case "same day" will not require extra steps in the backup, but if
"next day" is selected, TwcBackup will subtract one day to make the data
generated on friday also match the "friday" label in the TwcBackup
configuration of the external disk.

### media

<h1>Media Help</h1>

If the destination of the backup is an external disk (and not a local directory),
each disk needs to added to the TwcBackup configuration.

<h2>External Disk Name</h2>

This is a name the external disk has so that end users can identify it.

<h2>External Disk UUID</h2>

This should be the UUID of the external disk (as printed out by blkid). If
backup is started and the UUID of the attached disk is not found among all
disks registered in the configuration, the backup will fail.

<h2>Days of the Week</h2>

TwcBackup will compare the day of the week of the backup to the days of the week
the backup media is allowed to store. If this doesn't match, the backup will fail.
Through this setting, it is possible to ensure that one hard disk is used for
fridays backup, and another hard disk for all other days.

### tar

<h1>Tar Backup Help</h1>

Tar Backup is a full/incremental backup strategy that creates tar files of
the files that are included in the backup. On first run, a full backup is
created. Then only the differences to that full backup are stored each time
a backup is created. After a while, a new full backup is created.
<p>
Tar Backups usually require more diskspace than bfsync backups, so:  <b>if you
can, use bfsync backups instead</b>.

<h2>Name</h2>
The Name property should contain a unique name for this Tar Backup step.
<p>
It may contain letters, numbers and underscores.

<h2>Include Dirs</h2>

This is a list of directories that should be included in the Backup.

<h2>Exclude Dirs (optional)</h2>

This is a list of directories that should not be included in the Backup. Exclude
Dirs should be relative to Include Dirs.
<p>
Example: to backup /home but not /home/stefan, Include Dirs should be set to
/home, and exclude dirs should be set to stefan. (XXX).

<h2>Full Backup every N Days</h2>

The number of days between the full backups.

### rsync

<h1>RSync Help</h1>

RSync Backups will just rsync directories to the backup device. It can neither
be used to access old backups, nor will it delete files that have been deleted
on the source directory. Thus: <b>if you can, use bfsync backups instead</b>.

<h2>Name</h2>
The Name property should contain a unique name for this RSync Backup step.
<p>
It may contain letters, numbers and underscores.

<h2>Include Dirs</h2>

This is a list of directories that should be included in the Backup.

<h2>Exclude Dirs (optional)</h2>

This is a list of directories that should not be included in the Backup.
Exclude Dirs should absolute paths (like Include Dirs). 
<p>
Example: to backup /home but not /home/stefan, Include Dirs should be set to
/home, and Exclude Dirs should be set to /home/stefan.

<h2>Ignore existing Files (optional)</h2>

If this option is set, files that already exist on the backup will not be
updated, even if they were modified in the source directory. It is implemented
using the rsync <tt style="white-space:nowrap;">--ignore-existing</tt> option.

### pg_dump

<h1>Postgres Dump Help</h1>

<h2>Name</h2>
The Name property should contain a unique name for this Postgres Backup step.
<p>
It may contain letters, numbers and underscores.

<h2>Include DBs</h2>

A list of databases that should be included in the backup, in DBNAME:PORT
format (i.e. mydb:3456).
<p>
To backup all databases on the machine, the value can be set to *.

<h2>Exclude Dirs</h2>

Usually this should be set to "data".
<p>
TWC installations usually store the postgres data in a subdirectory data (relative
to the directory in which documents/files/scripts/... are stored). This subdirectory
doesn't need to be included in the backup, since a dump of the postgres database
is made.

### pre_script

<h1>Pre-Script Help</h1>

Pre-Scripts are shell commands that are run before every backup. If one
pre-script fails, the backup is not performed.
<p>
A typical task for pre-scripts is shutting down a database server before
the backup is done.

<h2>Run</h2> 

One or more commandlines to be run before backup. These will be executed
with the user that runs the backup script (typically root).

### post_script

<h1>Post-Script Help</h1>

Post-Scripts are shell commands that are run after every backup. Even if
the backup fails, or one post-script fails, <b>all post-scripts will always
be executed</b>.
<p>
A typical task for post-scripts is restarting a database server after
the backup is done.

<h2>Run</h2> 

One or more commandlines to be run after backup. These will be executed
with the user that runs the backup script (typically root).

### bfsync_common

<h1>BFSync Common Help</h1>

The options in this section affect all bfsync repositories. If no bfsync repositories
are configured, the options will have no effect.

<h1>Export File Lists to Postgres</h1>

After the backup has finished, twcbackup can export the file lists of the
bfsync repositories to a Postgres Database. This feature is optional, if no
database name, user, ... is configured, nothing will be exported.
<p>
The exported file lists are useful for tools that display the contents of the
bfsync repositories (so it is for instance possible to search for all versions
of a specific file that are contained in a bfsync repository).

<h2>Database Name</h2>

The postgres database name of the database that should contain the file lists.

<h2>User</h2>

The postgres user used when connecting the database.

<h2>Password</h2>

The postgres password used when connecting the database.

<h2>Host</h2>

The host the postgres database server is running on.

<h2>Port</h2>

The tcp port used when connecting the postgres database server.

### bfsync_repo

<h1>BFSync Repository Help</h1>

When bfsync backups are used, one or more bfsync repository needs to be
created. The backups stored inside one bfsync repository will be deduplicated
at file level (but only within each repository). Old versions of all files will
be kept, so that it is possible to restore old backups. There are no full/incremental
backups if bfsync is used, so each backup will appear to be a full backup, but the
contents of each file will only be stored once (SHA1-hashes are used for deduplication).

<h2>Name</h2>

The name of the bfsync repository. Each repository needs to have a different name.
<p>
It may contain letters, numbers and underscores.

<h2>Database Cache Size (Mb)</h2>

The database cache size is the amount of system memory in megabytes that is used
as cache for the bfsync repository. If the database cache size is too small, the
time required to add files to the repostory will become huge. If the database cache
size is too large, the machine that does the backups will slow down or not be able
to perform the backup due to lack of RAM.
<p>
<b>At least 100 MB cache per 1.000.000 files stored should be used</b>, more is
better, if you can afford it.
<p>
Since the cache will be in shared memory, the system wide shared memory limits
need to be large enough for the cache. See SHARED MEMORY CONFIGURATION in the
bfsync manpage for details.
<p>
To avoid excessive RAM usage, <b>all bfsync repository caches combined should
be considerably less than the amount of system memory</b>.

<h2>Deletion of old Backups</h2>

Whenever a backup runs, new data will be added to the bfsync repository. To ensure
that the repository doesn't grow too large, this configuration describes which backups
should be deleted.
<p>
First of all, some of the backups are tagged as <i>"daily backup"</i>. If the backup is
done once a day, every backup will be a daily backup, if the backup runs more than
once a day, either the <b>first or last</b> backup of the day can be used as daily
backup.
<p>
Based on the daily backups, <i>"weekly backups"</i> can be defined by weekday: for instance
<b>Daily Backup on Monday/...</b> can be used as weekly backup. The <i>"monthly and yearly
backups"</i> are also choosen among the daily backups; here the <b>first or last daily backup</b>
of the month/year can be used as monthly or yearly backup.
<p>
The actual deletion rule works by defining which backups are to be kept, and all
other backups will be deleted.
<p>
You can keep the most recent N backups.  This is important mainly if the
backup runs more than once every day, since then there will be backups which
are neither tagged daily nor weekly nor monthly nor yearly.
<p>
In addition to keeping the most recent N backups, there is a parameter for each
tagged backup: that way, you can keep the most recent N daily backups, the most
recent N weekly backups, the most recent N monthly backups and the most recent N
yearly backups.
<p>
All backups that are not on one of the keep lists are automatically deleted.

### bfsync_backup

<h1>BFSync Backup Help</h1>

<h2>Name</h2>

The name of the bfsync backup. Each backup needs to have a different name.
<p>
It may contain letters, numbers and underscores.

<h2>Repo</h2>

The name of the repository to store the backup. The repository must be the name
of one of the repositories created (under BFSync Repository).

<h2>Source Host (optional)</h2>

If this field contains a value, TwcBackup will fetch the data from this host.
Ssh ids should be used to allow TwcBackup to access this host as root without
password.

<h2>Include Dirs</h2>

This is a list of directories that should be included in the Backup.

<h2>Exclude Dirs (optional)</h2>

This is a list of directories that should not be included in the Backup. Exclude
Dirs should absolute paths (like Include Dirs).
<p>
Example: to backup /home but not /home/stefan, Include Dirs should be set to
/home, and Exclude Dirs should be set to /home/stefan.

<h2>One Filesystem (optional)</h2>

If this option is activated, only those files are backuped that reside on the
same filesystem that Include Dirs are on.

<h2>Remote Shell</h2>

For local backups (Source Host is empty), this option is ignored. For remote
backups, it can be used to configure the remote shell that is used to transfer
the data. Usually, ssh is a good choice, but since ssh encrypts all traffic,
it slows down the backup on very fast local networks.
<p>
Rsh on the other hand doesn't slow down the backup, but it should only be used
if the network is completely trusted, since neither the transfer nor the
authentication are secure.

### bfsync_windows_backup

<h1>BFSync Windows Backup Help</h1>

<h2>Name</h2>

The name of the bfsync windows backup. Each backup needs to have a different name.
<p>
It may contain letters, numbers and underscores.

<h2>Repo</h2>

The name of the repository to store the backup. The repository must be the name
of one of the repositories created (under BFSync Repository).

<h2>SMB Share</h2>

Samba share that contains the data to be included in the backup. Usually this
will be a name like \\HOST\SHARE .

<h2>User</h2>

Username to use for connecting to the samba share.

<h2>Password</h2>

Password to use for connecting to the samba share.

<h2>Include Dirs</h2>

This is a list of directories that should be included in the backup. This should
be in Unix path format, like /foo/bar.

<h2>Exclude Dirs (optional)</h2>

This is a list of directories that should not be included in the Backup. Exclude
Dirs should be relative to Include Dirs.
<p>
Example: to backup /foo but not /foo/bar, Include Dirs should be set to
/foo, and Exclude Dirs should be set to /foo/bar.

### bfsync_clone

<h1>BFSync Replication Help</h1>

Replication can be used to clone the contents of a local or remote bfsync repository
so that all changes that are done to the source repository are also done to the
destination repository.

<h2>Name</h2>

The name of the bfsync replication. Each replication needs to have a different name.
<p>
It may contain letters, numbers and underscores.

<h2>Pull History from Master Repo</h2>

The name of the master repository that contains the history that should be
replicated.  This master repository will be cloned with bfsync clone the first
time the replication is run, and updated each time with new history entries
using bfsync pull.
<p>
The repository can be local (then it would be a local path like /home/stefan/files.bfsync)
or remote (then it would be something like stefan@space.twc.de:files.bfsync).

<h2>Get Files from Repo</h2>

Since the master repository contains only the history, but no file contents, this
second repository needs to be specified. It must be a clone of the master
repository that is replicated, and should contain the file contents of (ideally)
all files that the history contains.
<p>
Each time the replication is run this repository is used as a source of files
(so bfsync get will be used).
<p>
The repository can be local (then it would be a local path like /home/stefan/files.bfsync)
or remote (then it would be something like stefan@space.twc.de:files.bfsync).

<h2>User (optional)</h2>

If this setting is omitted, the repository will be replicated as root. If a user is
specified, the repository will be replicated as this user (all files will belong to
that user).

<h2>Database Cache Size (Mb)</h2>

The database cache size is the amount of system memory in megabytes that is used
as cache for the bfsync repository. If the database cache size is too small, the
time required to add files to the repostory will become huge. If the database cache
size is too large, the machine that does the replication will slow down or not be able
to perform the replication due to lack of RAM.
<p>
<b>At least 100 MB cache per 1.000.000 files stored should be used</b>, more is
better, if you can afford it.
<p>
Since the cache will be in shared memory, the system wide shared memory limits
need to be large enough for the cache. See SHARED MEMORY CONFIGURATION in the
bfsync manpage for details.
<p>
To avoid excessive RAM usage, <b>all bfsync repository caches combined should
be considerably less than the amount of system memory</b>.

<h2>Remote Shell</h2>

This setting can be used to configure the remote shell that is used to transfer
the data. Usually, ssh is a good choice, but since ssh encrypts all traffic,
it slows down the replication on very fast local networks.
<p>
Rsh on the other hand doesn't slow down the replication, but it should only be
used if the network is completely trusted, since neither the transfer nor the
authentication are secure.

### report

<h1>Report Help</h1>

After each run, TwcBackup will send a report via email, either with a
confirmation that the backup was performed, or with an error message.

<h2>Report Title</h2>

A title for the backup report. Usually (if you have more than one machine),
it should be set to something that can be used to identify the machine.

<h2>EMail Address</h2>

A list of email addresses the report should be mailed to.