Skip to content

Commit

Permalink
Move setup instructions into wiki
Browse files Browse the repository at this point in the history
  • Loading branch information
rugk committed Sep 3, 2017
1 parent ff9a723 commit 94fb99a
Showing 1 changed file with 1 addition and 67 deletions.
68 changes: 1 addition & 67 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,70 +63,4 @@ Also, you can of course not use some features outlined here. That's why the whol

## How to setup?

### 1. Download

1. Download the [latest release](https://github.com/rugk/borg-cron-helper/releases) of the scripts.
2. It is suggested to verify them with my [public key](https://github.com/rugk/otherfiles/blob/master/RugkGitSoftwareSignKey.txt) 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 script are not writable by the backup user, if it is different than root.

### 2. Enter the backup parameters

In the [config directory](config/) 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 appropiate permissions.
2. Create a subdirectry called `/var/log/borg/last` (configurable as [`LAST_BACKUP_DIR`](borgcron.sh#L9)). There the `.time` files will be written to containing the tiome of the last backup execution.
3. Include/add the [`tools/checklastbackup.sh`](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`](tools/checklastbackup.sh#L8)) in order to get a notification, if no successful backup has been made within that time.

### 4. Setup local log (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`](borgcron.sh#L10). Note that for the system to work, the `RUN_PID_DIR` must **exist and be writable**. This is [usually done](https://askubuntu.com/questions/303120/how-folders-created-in-var-run-on-each-reboot) 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`](system/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`](system/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`](borgcron.sh#L10) 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`](tools/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`](tools/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 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`](system/borg.service) and [`borg.timer`](system/borg.timer) scripts to `/usr/lib/systemd/system`.
2. Adjust the files, especially the `User` and `Group` in the service file.
3. Enable the timer: `systemctl enable borg.timer`

You can test the execution with `systemctl start borg`.

### 7. Setup logrotate
If you use a logfile to save the output, you may also use logrotate to remove old logs. Just put the [`logrotate`](system/logrotate) into `/etc/logrotate.d`.
Setup instructions can be found [in the wiki](https://github.com/rugk/borg-cron-helper/wiki/How-to-setup%3F).

0 comments on commit 94fb99a

Please sign in to comment.