Skip to content

How to setup?

Jump to bottom Edit New page
rugk edited this page Jul 28, 2019 · 24 revisions

1. Download

  1. Download the latest release of the scripts.
  2. It is suggested to verify them with my public key and/or look through the scripts, so you know what they do and that they do not do anything malicious. To do so just run gpg --verify download.zip.asc.
  3. Make sure that all scripts are not writable by the backup user, if it is different than root.

2. Enter the backup parameters

In the config directory you will find an example configuration file. Set the variables according to your already initialized borg backup. Each backup has its own configuration file. Copy the template file if you want to setup more backups.

3. Setup statistics (optional)

To use the logging and reporting functionality, you have to create some dirs. These have to be writable by the user running the scripts.

  1. For logging: Create /var/log/borg with appropriate permissions.
  2. Create a subdirectry called /var/log/borg/last (configurable as LAST_BACKUP_DIR). There the .time files will be written to containing the tiome of the last backup execution.
  3. Include/add the tools/checklastbackup.sh script to your ~/.bashrc, ~/.zshrc or similar, depending on your shell). It will read the .time files to display the time of the last execution of your backups, when you login into your shell. You may also adjust the time period (CRITICAL_TIME) in order to get a notification, if no successful backup has been made within that time.

4. Setup local lock (optional)

By default RUN_PID_DIR, where the PID files are saved, is set to /var/run. It is configurable in RUN_PID_DIR in borgcron.sh. Note that for the system to work, the RUN_PID_DIR must exist and be writable. This is usually done by init scripts or systemd, because /var/run is often mounted as a tempfs, so all data is deleted at shutdown and you have to recreate the dirs at the (next) startup. So either:

  • change the configuration to use a dir writable by the user, or
  • create a init.d script or systemd service file, which creates the dir in /var/run

In order to do the second, we provide some scripts:

  • If you use systemd, copy the tmpfile configuration file to /usr/lib/tmpfiles.d (suggested name: borg.conf) and adjust the username/group in the script to match the user, you are running the backup.
  • If you use init.d, copy the init script to /etc/init.d (suggested name: borg), make it executable (chmod +x) if necessary and enable it (update-rc.d borg defaults).

The script also tries to create the dirs by itself, but this may only be the last fallback and certainly only works for the default configuration when it is running as root.

If the configured dir does not exist, the backup will not run for security reasons. To disable this feature, set RUN_PID_DIR to an empty string (""). This will disable the local locking system and use borg's default locking mechanism. This is useful when you run borg v1.1.0 or higher.

Attention: This system assumes, that you access your borg repo in a "single-user" (one client, one server) environment. As the locking is managed locally, you should ensure, that only one client is allowed to access the borg repository. Otherwise data loss may occur, as this script automatically breaks the remote lock in the borg repository, if it is not locked locally.

5. Setup MySQL dump (optional)

The databasedump.sh script can be used to dump your database(s) into a dir before executing the backup. You can do this either directly before running the backup by including databasedump.sh in your config file, or you can setup a new cron job using another user, who is allowed to dump the databases into a dir. The cron job should, of course, be executed before executing the actual backup.

6. Setup notifications (optional)

By default, borgcron tries to show notifications via zenity, if it is installed. By default it only does so for the currently logged in user that is running the borgcron backup and if a display is "connected"/used (the DISPLAY variable is there).

If you use a desktop system (Xorg or Wayland) and want to get notifications of your service, you may need some configuration. First, if you run borg-cron-helper as the same user as you want to see the notifications, you do not need to change anything, it should work out of the box. However, if you execute borg under, let's say, root, you may need some setup your system:

  1. First, allow the user to communicate via DBUS. To do so, add this to your /etc/dbus-1/session-local.conf (if the file is not there, create it):

    <busconfig>
	<policy context="default">
		<allow user="root"/>
	</policy>
</busconfig>

    This used root as the user, where borg is executed. Also mind to adjust the permissions of the config file to match the one of the existing /etc/dbus-1/session.conf file, e.g. (chmod --reference= is handy here.) If you do mistakes in the dbus configuration here, your system may not properly boot when you restart it!

  2. In the borg script you need to enable the line to include the zenityProxy.sh:

    . "$( dirname "$0" )/tools/zenityProxy.sh"

    The scripts tries to find the currently logged in and active user in a graphical user session and sends the notification to them. Additionally, you can set FALLBACK_NOTIFICATION_USER to a username to use as a fallback, if that does not work.

    Note that the script requires you to either be able to su or (if installed) sudo to the user, where to show the notification.

    If you do not want to use the included zenityProxy.sh, here you can find the old instructions on how to do it manually, here.

  3. Finally, the easiest step: If you want to see the borg icon in your notification, enable GUI_OVERWRITE_ICON in the config and adjust its path to the absolute (i.e. full) path to the borg.png. Note that the file must be readable by the user, where the notification should be shown.

If it still does not work, maybe your backup user does not have any DISPLAY variable set. In such a case, consider overwriting the function guiCanShowNotifications, so it always returns "true". (i.e. guiCanShowNotifications() {return 0})

7. Setup cron/anacron/systemd timers

Finally test the backup process. Then add the cron entry for the script (use the crontab -e command to edit the files):

# daily backup at midnight
RANDOM_DELAY=120
00 00 * * * /path/to/borgcron_starter.sh >> /var/log/borg/allbackups.log 2>&1

Or anacron creating the following file in /etc/cron.daily, /etc/cron.weekly or similar:

#!/bin/sh
/path/to/borgcron_starter.sh >> /var/log/borg/allbackups.log 2>&1

Do not forget to make the anacron file executable (chmod +x).

Alternatively you can also use systemd:

  1. Copy the borg.service and borg.timer scripts to /etc/systemd/system.
  2. Adjust the files, especially the User and Group in the service file.
  3. Enable the timer: systemctl enable borg.timer
  4. Start the timer: systemctl start borg.timer

If systemd is used, the borg service only starts if/after the network is online. By default the service won't start on a device that is offline.

You can test the execution with systemctl start borg.

8. Setup logrotate

If you use a logfile to save the output, you may also use logrotate to remove old logs. Just put the logrotate into /etc/logrotate.d.

Add a custom footer
Add a custom sidebar
Clone this wiki locally