backintime-config(5)

📦 version 1.6.1, in ubuntu resolute, ubuntu stonking

🎀 backintime-config(5) 🎀

ok bestie, this is the BackInTime config file manual — section 5, USER COMMANDS, the whole thing. sit down, grab a strawberry drink 🍓, we're going in.

🌸 NAME 🌸

config — BackInTime configuration files. yes, that's it. that's the name. iconic brevity 💅

✨ SYNOPSIS ✨

~/.config/backintime/config
/etc/backintime/config

two paths, two vibes. the first one is your personal one, the second one is the system-wide one. pick your fighter 🫶

💖 DESCRIPTION 💖

okay so here's the tea. Back In Time was built as a pure GUI program, which means most of the functions are only usable with backintime-qt. it's giving "pretty windows or nothing" energy, and honestly? fair.

BUT 🦋 — and this is the part where it gets good — it is possible to use Back In Time on, like, a headless server. no screen, no mouse, no problem. the catch is you have to create the configuration file manually:

~/.config/backintime/config

look inside /usr/share/doc/backintime-common/examples/ for examples. they're right there, bestie, go look, they're free ✨

The configuration file has the following format:

keyword=arguments

Arguments don't need to be quoted. All characters are allowed except '='. literally everything else can come to the party, just not that one character. it's banned 🚫

run backintime check-config to verify the configfile, create the snapshot folder and crontab entries. do this. please. it's the vibe check your config deserves. 👑

🔥 POSSIBLE KEYWORDS 🔥

this is the big one. every keyword, every type, every allowed value, every default. no skipping, no summarizing, we're eating the whole plate 🍽️

  • global.hash_collision
    • Type: int — Allowed Values: 0-99999
    • Internal value used to prevent hash collisions on mountpoints. Do not change this. it's internal, it's doing its job, leave it alone 🙈
    • Default: 0
  • global.language
    • Type: str — Allowed Values: text
    • Language code (ISO 639) used to translate the user interface. If empty the operating systems current local is used. If 'en' the translation is not active and the original English source strings are used. It is the same if the value is unknown.
    • Default: ''
  • global.use_flock
    • Type: bool — Allowed Values: true|false
    • Prevent multiple snapshots (from different profiles or users) to be run at the same time
    • Default: false
  • profile<N>.name
    • Type: str — Allowed Values: text
    • Name of this profile.
    • Default: Main profile
  • profile<N>.schedule.custom_time
    • Type: str — Allowed Values: comma separated int (8,12,18,23) or */3
    • Custom hours for cronjob. Only valid for profile<N>.schedule.mode = 19
    • Default: 8,12,18,23
  • profile<N>.schedule.day
    • Type: int — Allowed Values: 1-28
    • Which day of month the cronjob should run? Only valid for profile<N>.schedule.mode >= 40
    • Default: 1
  • profile<N>.schedule.debug
    • Type: bool — Allowed Values: true|false
    • Enable debug output to system log for schedule mode.
    • Default: false
  • profile<N>.schedule.mode
    • Type: int — Allowed Values: 0|1|2|4|7|10|12|14|16|18|19|20|25|27|30|40|80
    • Which schedule used for crontab. The crontab entry will be generated with backintime check-config.
    • 0 = Disabled
    • 1 = at every boot
    • 2 = every 5 minute
    • 4 = every 10 minute
    • 7 = every 30 minute
    • 10 = every hour
    • 12 = every 2 hours
    • 14 = every 4 hours
    • 16 = every 6 hours
    • 18 = every 12 hours
    • 19 = custom defined hours
    • 20 = every day
    • 25 = daily anacron
    • 27 = when drive get connected
    • 30 = every week
    • 40 = every month
    • 80 = every year
    • Default: 0
  • profile<N>.schedule.repeatedly.period
    • Type: int — Allowed Values: 0-99999
    • How many units to wait between new snapshots with anacron? Only valid for profile<N>.schedule.mode = 25|27
    • Default: 1
  • profile<N>.schedule.repeatedly.unit
    • Type: int — Allowed Values: 10|20|30|40
    • Units to wait between new snapshots with anacron.
    • 10 = hours
    • 20 = days
    • 30 = weeks
    • 40 = months
    • Only valid for profile<N>.schedule.mode = 25|27
    • Default: 20
  • profile<N>.schedule.time
    • Type: int — Allowed Values: 0-2400
    • Position-coded number with the format "hhmm" to specify the hour and minute the cronjob should start (eg. 2015 means a quarter past 8pm). Leading zeros can be omitted (eg. 30 = 0030). Only valid for profile<N>.schedule.mode = 20 (daily), 30 (weekly), 40 (monthly) and 80 (yearly)
    • Default: 0
  • profile<N>.schedule.weekday
    • Type: int — Allowed Values: 1 = monday - 7 = sunday
    • Which day of week the cronjob should run? Only valid for profile<N>.schedule.mode = 30
    • Default: 7
  • profile<N>.snapshots.backup_on_restore.enabled
    • Type: bool — Allowed Values: true|false
    • Rename existing files before restore into FILE.backup.YYYYMMDD
    • Default: true
  • profile<N>.snapshots.bwlimit.enabled
    • Type: bool — Allowed Values: true|false
    • Limit rsync bandwidth usage over network. Use this with mode SSH. For mode Local you should rather use ionice.
    • Default: false
  • profile<N>.snapshots.bwlimit.value
    • Type: int — Allowed Values: 0-99999
    • Bandwidth limit in KB/sec.
    • Default: 3000
  • profile<N>.snapshots.continue_on_errors
    • Type: bool — Allowed Values: true|false
    • Continue on errors. This will keep incomplete snapshots rather than deleting and start over again.
    • Default: true
  • profile<N>.snapshots.copy_links
    • Type: bool — Allowed Values: true|false
    • When symlinks are encountered, the item that they point to (the reference) is copied, rather than the symlink.
    • Default: false
  • profile<N>.snapshots.copy_unsafe_links
    • Type: bool — Allowed Values: true|false
    • This tells rsync to copy the referent of symbolic links that point outside the copied tree. Absolute symlinks are also treated like ordinary files.
    • Default: false
  • profile<N>.snapshots.cron.ionice
    • Type: bool — Allowed Values: true|false
    • Run cronjobs with ionice -c2 -n7. This will give BackInTime the lowest IO bandwidth priority to not interrupt any other working process.
    • Default: true
  • profile<N>.snapshots.cron.nice
    • Type: bool — Allowed Values: true|false
    • Run cronjobs with nice -n19. This will give BackInTime the lowest CPU priority to not interrupt any other working process.
    • Default: true
  • profile<N>.snapshots.cron.redirect_stderr
    • Type: bool — Allowed Values: true|false
    • redirect stderr to /dev/null in cronjobs
    • Default: False
  • profile<N>.snapshots.cron.redirect_stdout
    • Type: bool — Allowed Values: true|false
    • redirect stdout to /dev/null in cronjobs
    • Default: true
  • profile<N>.snapshots.dont_remove_named_snapshots
    • Type: bool — Allowed Values: true|false
    • Keep snapshots with names during smart_remove.
    • Default: true
  • profile<N>.snapshots.exclude.bysize.enabled
    • Type: bool — Allowed Values: true|false
    • Enable exclude files by size.
    • Default: false
  • profile<N>.snapshots.exclude.bysize.value
    • Type: int — Allowed Values: 0-99999
    • Exclude files bigger than value in MiB. With 'Full rsync mode' disabled this will only affect new files because for rsync this is a transfer option, not an exclude option. So big files that has been backed up before will remain in snapshots even if they had changed.
    • Default: 500
  • profile<N>.snapshots.exclude.<I>.value
    • Type: str — Allowed Values: file, folder or pattern (relative or absolute)
    • Exclude this file or folder. <I> must be a counter starting with 1
    • Default: ''
  • profile<N>.snapshots.exclude.size
    • Type: int — Allowed Values: 0-99999
    • Quantity of profile<N>.snapshots.exclude.<I> entries.
    • Default: -1
  • profile<N>.snapshots.include.<I>.type
    • Type: int — Allowed Values: 0|1
    • Specify if profile<N>.snapshots.include.<I>.value is a folder (0) or a file (1).
    • Default: 0
  • profile<N>.snapshots.include.<I>.value
    • Type: str — Allowed Values: absolute path
    • Include this file or folder. <I> must be a counter starting with 1
    • Default: ''
  • profile<N>.snapshots.include.size
    • Type: int — Allowed Values: 0-99999
    • Quantity of profile<N>.snapshots.include.<I> entries.
    • Default: -1
  • profile<N>.snapshots.keep_only_one_snapshot.enabled
    • Type: bool — Allowed Values: true|false
    • NOT YET IMPLEMENTED. Remove all snapshots but one.
    • Default: false
bestie do NOT count on this one. it says NOT YET IMPLEMENTED and it means it. it's giving vaporware, it's giving "coming soon" on a website from 2009 💀
  • profile<N>.snapshots.local.nocache
    • Type: bool — Allowed Values: true|false
    • Run rsync on local machine with 'nocache'. This will prevent files from being cached in memory.
    • Default: false
  • profile<N>.snapshots.local_encfs.path
    • Type: str — Allowed Values: absolute path
    • Where to save snapshots in mode 'local_encfs'.
    • Default: ''
  • profile<N>.snapshots.log_level
    • Type: int — Allowed Values: 1-3
    • Log level used during takeSnapshot.
    • 1 = Error
    • 2 = Changes
    • 3 = Info
    • Default: 3
  • profile<N>.snapshots.min_free_inodes.enabled
    • Type: bool — Allowed Values: true|false
    • Remove snapshots until profile<N>.snapshots.min_free_inodes.value free inodes in % is reached.
    • Default: false
  • profile<N>.snapshots.min_free_inodes.value
    • Type: int — Allowed Values: 1-15
    • Keep at least value % free inodes.
    • Default: 2
  • profile<N>.snapshots.min_free_space.enabled
    • Type: bool — Allowed Values: true|false
    • Remove snapshots until profile<N>.snapshots.min_free_space.value free space is reached.
    • Default: false
  • profile<N>.snapshots.min_free_space.unit
    • Type: int — Allowed Values: 10|20
    • 10 = MB
    • 20 = GB
    • Default: 20
  • profile<N>.snapshots.min_free_space.value
    • Type: int — Allowed Values: 1-99999
    • Keep at least value + unit free space.
    • Default: 1
  • profile<N>.snapshots.mode
    • Type: str — Allowed Values: local|local_encfs|ssh|ssh_encfs
    • Use mode (or backend) for this snapshot. Look at man backintime section 'Modes'.
    • Default: local
  • profile<N>.snapshots.<MODE>.password.save
    • Type: bool — Allowed Values: true|false
    • Save password to system keyring (gnome-keyring or kwallet). <MODE> must be the same as profile<N>.snapshots.mode
    • Default: false
  • profile<N>.snapshots.<MODE>.password.use_cache
    • Type: bool — Allowed Values: true|false
    • Cache password in RAM so it can be read by cronjobs. Security issue: root might be able to read that password, too. <MODE> must be the same as profile<N>.snapshots.mode
    • Default: true if home is not encrypted
⚠️ ok so real talk on that last one: caching the password in RAM means cronjobs can read it, which is convenient, but root might be able to read that password, too. that's not me being dramatic, that's in the manual. security issue, bestie. know it before you set it. 🫶

and that's part 1, stay tuned for part 2 because there is more 👑✨

  • profile<N>.snapshots.no_on_battery — Type: bool · Allowed Values: true|false Unplugged laptop? No snapshot for you. If the computer is running on battery, this skips taking snapshots entirely. Default: false
  • profile<N>.snapshots.notify.enabled — Type: bool · Allowed Values: true|false Wanna get pinged? This pops up notifications (errors, warnings) through libnotify. 👑 Default: true
  • profile<N>.snapshots.one_file_system — Type: bool · Allowed Values: true|false Hands rsync its --one-file-system flag so it does NOT cross filesystem boundaries while recursing. Boundaries stay boundaries. Default: false
  • profile<N>.snapshots.path — Type: str · Allowed Values: absolute path Where snapshots get saved in mode 'local'. Heads up bestie, this path MUST contain a folder structure like 'backintime/<HOST>/<USER>/<PROFILE_ID>' or it's not gonna vibe. Default: ''
  • profile<N>.snapshots.path.host — Type: str · Allowed Values: text Sets the Host for the snapshot path. Default: local hostname
  • profile<N>.snapshots.path.profile — Type: str · Allowed Values: 1-99999 Sets the Profile-ID for the snapshot path. Default: current Profile-ID
  • profile<N>.snapshots.path.user — Type: str · Allowed Values: text Sets the User for the snapshot path. Default: local username
  • profile<N>.snapshots.path.uuid — Type: str · Allowed Values: text The device's uuid — it's what gets used to automatically set up a udev rule if the drive isn't connected. Default: ''
  • profile<N>.snapshots.preserve_acl — Type: bool · Allowed Values: true|false Preserve ACL.
⚠️ For this to actually work, the source and destination systems need compatible ACL entries. No matching entries, no preserved ACLs. That's the deal.

Default: false

  • profile<N>.snapshots.preserve_xattr — Type: bool · Allowed Values: true|false Preserve extended attributes (xattr). Keep all that extra metadata, she's thorough. 💅 Default: false
  • profile<N>.snapshots.remove_old_snapshots.enabled — Type: bool · Allowed Values: true|false Removes ALL snapshots older than value + unit. Spring cleaning but make it automated. Default: true
  • profile<N>.snapshots.remove_old_snapshots.unit — Type: int · Allowed Values: 20|30|80 The unit we're counting in. Decoder ring:
    • 20 = days
    • 30 = weeks
    • 80 = years Default: 80
  • profile<N>.snapshots.remove_old_snapshots.value — Type: int · Allowed Values: 0-99999 Snapshots older than this many units get removed. Bye babes ✨ Default: 10
  • profile<N>.snapshots.rsync_options.enabled — Type: bool · Allowed Values: true|false Passes additional options to rsync. (Yes, the original says "Past". We love her anyway. 🫶) Default: false
  • profile<N>.snapshots.rsync_options.value — Type: str · Allowed Values: text The actual rsync options. They MUST be quoted, like --exclude-from="/path/to/my exclude file". Default: ''
  • profile<N>.snapshots.smart_remove — Type: bool · Allowed Values: true|false Runs smart_remove to clean up old snapshots right after a new snapshot was created. Fresh snapshot, tidy archive. Default: false
  • profile<N>.snapshots.smart_remove.keep_all — Type: int · Allowed Values: 0-99999 Keeps ALL snapshots for X days. Hoard era. Default: 2
  • profile<N>.snapshots.smart_remove.keep_one_per_day — Type: int · Allowed Values: 0-99999 Keeps one snapshot per day for X days. Default: 7
  • profile<N>.snapshots.smart_remove.keep_one_per_month — Type: int · Allowed Values: 0-99999 Keeps one snapshot per month for X month. (Singular "month" in the original, iconic behavior, keeping it 💀) Default: 24
  • profile<N>.snapshots.smart_remove.keep_one_per_week — Type: int · Allowed Values: 0-99999 Keeps one snapshot per week for X weeks. Default: 4
  • profile<N>.snapshots.smart_remove.run_remote_in_background — Type: bool · Allowed Values: true|false If you're in mode SSH or SSH-encrypted, this runs smart_remove in the background on the remote machine. Default: false
  • profile<N>.snapshots.ssh.check_commands — Type: bool · Allowed Values: true|false Checks that all the commands used during takeSnapshot actually work like expected on the remote host. Vibe check, but for commands. Default: true
  • profile<N>.snapshots.ssh.check_ping — Type: bool · Allowed Values: true|false Checks whether the remote host is even reachable before trying to mount. No point knocking if nobody's home. Default: true
  • profile<N>.snapshots.ssh.cipher — Type: str · Allowed Values: default | aes192-cbc | aes256-cbc | aes128-ctr | aes192-ctr | aes256-ctr | arcfour | arcfour256 | arcfour128 | aes128-cbc | 3des-cbc | blowfish-cbc | cast128-cbc The cipher used to encrypt the SSH tunnel. Depending on your environment (network bandwidth, cpu and hdd performance) a different cipher might be faster. Default: default
  • profile<N>.snapshots.ssh.host — Type: str · Allowed Values: IP or domain address The remote host, used for mode 'ssh' and 'ssh_encfs'. Default: ''
  • profile<N>.snapshots.ssh.ionice — Type: bool · Allowed Values: true|false Runs rsync and other commands on the remote host with ionice -c2 -n7. Default: false
  • profile<N>.snapshots.ssh.max_arg_length — Type: int · Allowed Values: 0, >700 Max command length of the commands run on the remote host.
You can test this for all ssh profiles in your config with python3 /usr/share/backintime/common/sshMaxArg.py LENGTH.

And 0 = unlimited. Default: 0

  • profile<N>.snapshots.ssh.nice — Type: bool · Allowed Values: true|false Runs rsync and other commands on the remote host with nice -n19. Default: false
  • profile<N>.snapshots.ssh.nocache — Type: bool · Allowed Values: true|false Runs rsync on the remote host with nocache. This stops files from being cached in memory. Default: false
  • profile<N>.snapshots.ssh.path — Type: str · Allowed Values: absolute or relative path The snapshot path on the remote host. If the path is relative (no leading /) it starts from the remote user's homedir. An empty path gets replaced with './'. Default: ''
  • profile<N>.snapshots.ssh.port — Type: int · Allowed Values: 0-65535 The SSH Port on the remote host. Default: 22
  • profile<N>.snapshots.ssh.prefix.enabled — Type: bool · Allowed Values: true|false Adds a prefix to every single command that runs through SSH on the remote host. Default: false
  • profile<N>.snapshots.ssh.prefix.value — Type: str · Allowed Values: text The prefix to run before every command on the remote host. Variables need to be escaped with \$FOO.
Heads up: this does NOT touch rsync. So if you want a prefix for rsync, use profile<N>.snapshots.rsync_options.value with --rsync-path="FOO=bar:\$FOO /usr/bin/rsync".

Default: 'PATH=/opt/bin:/opt/sbin:\$PATH'

  • profile<N>.snapshots.ssh.private_key_file — Type: str · Allowed Values: absolute path to private key file The private key file used for password-less authentication on the remote host. 🗝️ Default: ~/.ssh/id_dsa
  • profile<N>.snapshots.ssh.proxy_host — Type: str · Allowed Values: text The proxy host used to connect to the remote host. Default: IP or domain address
  • profile<N>.snapshots.ssh.proxy_host_port — Type: int · Allowed Values: 0-65535 The proxy host port used to connect to the remote host. Default: 22
  • profile<N>.snapshots.ssh.proxy_user — Type: str · Allowed Values: text Remote SSH user. Default: the local users name
  • profile<N>.snapshots.ssh.user — Type: str · Allowed Values: text Remote SSH user. Default: local users name
  • profile<N>.snapshots.take_snapshot_regardless_of_changes — Type: bool · Allowed Values: true|false Creates a new snapshot no matter what — changes or no changes, she's taking one. Default: false
  • profile<N>.snapshots.use_checksum — Type: bool · Allowed Values: true|false Uses checksum to detect changes instead of size + time. More thorough, more work. Default: false
  • profile<N>.snapshots.user_backup.ionice — Type: bool · Allowed Values: true|false Runs BackInTime with ionice -c2 -n7 when taking a manual snapshot. This gives BackInTime the lowest IO bandwidth priority so it doesn't interrupt any other working process. Polite queen. 🎀 Default: false
  • profile<N>.user_callback.no_logging — Type: bool · Allowed Values: true|false Does NOT catch std{out|err} from the user-callback script — the script will only write to the current TTY. The default behavior is to catch std{out|err} and write it to syslog and the TTY again. Default: false
  • profiles — Type: str · Allowed Values: int separated by colon (e.g. 1:3:4) All active Profiles (that's the <N> in profile<N>.snapshots...). Default: 1
  • profiles.version — Type: int · Allowed Values: 1 Internal version of the profiles config. Default: 1

🌈 SEE ALSO 🌈

  • backintime
  • backintime-qt

Back In Time also has a website: https://github.com/bit-team/backintime 🦋

✨ AUTHOR ✨

This manual page was written by BIT Team (<bit-dev@python.org>).

And that's the whole config, bestie — you made it to the end 🫶 This is version 1.6.0-dev, dated November 2024, and you've officially been reading backintime-config(5). Slay, periodt 💅✨

📦 where this page comes from