Scheduling
Job scheduling allows you to setup automatic backups for your Jobs based on a Daily, Weekly and Monthly routine. In order for Tarsnap GUI to be able to achieve this, it has to register itself with the system's scheduler and run as often as needed in order to reliably check whether any of the Jobs need to be executed or not, based on how many days have elapsed since the last execution for each cadence category. For sakes of simplicity, portability and ease of use, the Daily, Weekly and Monthly timestamps are the same for all Jobs. For the same reasons, after enabling automatic Job backups, Tarsnap GUI will backup all scheduled Jobs immediately and then adjust each cadence timestamp accordingly and then promptly quit. Next time when the system scheduler runs Tarsnap GUI, the application will test each scheduled Job against previous timestamps and execute only the necessary ones, update the cadence timestamps and then quit. This way we don't need a daemon, applet or otherwise to be always running in the background and hog on your precious system resources. More on this in the following sections.
Since version 1.0 automatic Job scheduling can be easily enabled on macOS using the Launchd daemon and *Unixes sporting the crond daemon, without any manual tinkering. After you've installed Tarsnap GUI, created a Tarsnap account and added a couple of Jobs (you can use the default ones suggested to you on first run), all you need to do to enable automatic Job scheduling is to head to the Settings page and click on Enable Job scheduling button.
Next time when the automated backup schedule will fire, all of the Jobs that have scheduling enabled will be backed up and a different timestamp will be kept on record for the Daily, Weekly and Monthly routines. From then on your Jobs will be backed up accordingly every-time Tarsnap GUI is invoked by the system scheduler or manually via the --jobs parameter. On MacOS this happens every day at 10am and on crond enabled Unixes every 30 minutes. We recommend enabling Show desktop notifications and Save Console Log options in Settings -> Application so that you'll be notified when Tarsnap is working on your system as well as keep a detailed Console log on record. The Journal log is keeping track of scheduled activity too. For more on this as well as how to manually adjust when scheduled Tarsnap GUI is fired proceed to the following section.
Since Tarsnap GUI aims at being very slim, efficient and non-intrusive, it schedules automated Job backups without the need for a always running daemon or applet on your system. In order to do this, it has to register with some form of task scheduling available on your platform. On macOS this would be the Launchd service and on Linux that would be Cron. In order to achieve this the Tarsnap GUI executable has a command line parameter called –jobs:
Usage: ./Tarsnap [options]
Tarsnap GUI - Online backups for the truly lazy
Options:
-h, --help Displays this help.
-v, --version Displays version information.
-j, --jobs Executes all Jobs sequentially that have the
\'Automatic backup schedule\' option enabled. The
application runs headless and useful information is
printed to standard out and error.
Whenever Tarsnap GUI is executed with the --jobs parameter it will sequentially go through all the Jobs that have scheduling enabled, compare current timestamp with the stored Daily, Weekly and Monthly timestamps respectively and execute backups as needed. This happens silently, unless you enabled desktop notifications in Settings -> Application pane (highly recommended). Now to ensure automatic backups for your scheduled Jobs one has to schedule tarsnap-gui --jobs to execute as often as needed on his system in order to make sure that the minimum cadence of one Day doesn't get skipped for any reason. The application can do that for you on macOS and cron enabled Unixes using the Enable/Disable Job scheduling buttons in Settings -> Backup. Let's take a look at how that is achieved for each platform next.
Launchd on MacOS is the perfect scheduling mechanism. One because it's simple, second because it can be automated and third because it doesn't skip scheduled invocations if your system was powered off, sleeping or hibernating at the time when the timer should have fired.
When you enable Job scheduling via the Settings -> Backup pane, all Tarsnap GUI has to do is place a crafted plist launchd service file in ~/Library/LaunchAgents/com.tarsnap.gui.plist and enable it with launchctl load ../com.tarsnap.gui.plist && launchctl start com.tarsnap.gui. Here's an example launchd service file:
https://gist.github.com/shinnok/6897d2714c32ee4f95f1722139df4581
The default Tarsnap GUI launchd service file tells macOS's Launchd daemon to launch tarsnap-gui --jobs every day at 10AM sharp. If your system was shut down or in hibernation during that time, Launchd is smart enough to invoke tarsnap-gui with the next opportunity. Also missed timers don't accrue and this is perfect for our case. One manual adjustment that I foresee some people will make to this service file is to move the default 10AM scheduling to something more appropriate for your use case. Maybe you're just arriving at work at that time or are usually in running some heavy duty work on your system often at that specific time, so in order to move the backup time to something more appropriate all you need to do is:
- Edit the
StartCalendarIntervalkey in~/Library/LaunchAgents/com.tarsnap.gui.plistto something that suits you best; - Execute:
launchctl load ../com.tarsnap.gui.plist && launchctl start com.tarsnap.gui
Please keep in mind that if you disable/enable automatic Job scheduling from within Tarsnap GUI Settings pane, the default service file will overwrite your modified service file, thus you'll have to go through these steps again. I'll implement the possibility to do this from within the app in a following release.
On Linux and *BSDs we're stuck with CRON for non-superuser scheduling. The biggest caveat with using CRON for scheduling backups is that CRON won't defer missed scheduled invocations if your system was powered off, sleeping or hibernating at the time when the timer should have fired. That also implies that if your system is always powered off when the backups should fire, say 10AM, then your system will never be backed up. In order to get around this issue we have to use a schedule cadence that will fire often and many times during the day. In my testing the best bet is to schedule tarsnap-gui --jobs at every 30 minutes. This is the biggest time increment that ensures backups will fire for 99% of use cases and that is easy to do via a single line CRONTAB.
When you enable Job scheduling via the Settings -> Backup pane on Ubuntu for e.g. the app will add the following block to the current user's crontab:
#BEGIN Tarsnap GUI - DO NOT EDIT THIS BLOCK MANUALLY
# For help, see: https://github.com/Tarsnap/tarsnap-gui/wiki/Scheduling
*/30 * * * * /usr/bin/env DISPLAY=:0 XAUTHORITY=/home/shinnok/.Xauthority /home/shinnok/Work/tarsnap-gui/tarsnap-gui --jobs
#END Tarsnap GUI - DO NOT EDIT THIS BLOCK MANUALLY
The DISPLAY & XAUTHORITY variables are used to enable desktop notifications for tarsnap-gui when running in the background. Their values are copied from the environment when you enable scheduling from Settings and are hardcoded when written to CRONTAB. If any of that is due to change for whatever reason on your system you can update their values with the appropriate ones either manually via crontab -e or by disabling and then reenabling scheduling from within the app.
For the sakes of discussion, the other cross-distribution alternative for scheduling tarsnap-gui, one that would have been more similar to the macOS Launchd service, would have been to place a wrapper shell script in /etc/cron.daily. On most Linux distributions scheduling tasks via that cron.daily would ensure deferred invocation, however that method would require super-user (root) access when enabling automated backups at least. On BSD similar functionality is exposed via the /etc/periodic scheduling system. If you'd prefer having tarsnap-gui to run only once daily, you can easily enable scheduling manually using this method.
If you have trouble with your scheduled backups, the first step towards investigating this is to enable the Save Console Log option in Settings -> Application. On that note, it's also recommended to enable the Show desktop notifications option, so that you'll know when Tarsnap is working on your system and if it the backups fire at the appropriate times.
If your notifications don't show up and if the Console Log is empty, it might be a good time to open the application, verify the Journal Log (click the arrow in the status bar) and then try a manual backup for any of your Jobs and see if that works for you. If that goes well, the third step would be to try out tarsnap-gui --jobs at the command-line. Fire up a terminal, remember where you placed the Tarsnap GUI binary and execute it like so (MacOS example):
$./Tarsnap.app/Contents/MacOS/Tarsnap --jobs
../tarsnap-gui/src/translator.cpp(23): System language is English
../tarsnap-gui/src/taskmanager.cpp(463): Daily: false
../tarsnap-gui/src/taskmanager.cpp(464): Next daily: Wed Jun 28 2017
../tarsnap-gui/src/taskmanager.cpp(466): Weekly: false
../tarsnap-gui/src/taskmanager.cpp(467): Next weekly: Sun Jul 2 2017
../tarsnap-gui/src/taskmanager.cpp(469): Monthly: false
../tarsnap-gui/src/taskmanager.cpp(470): Next monthly: Sat Jul 1 2017
If your backups haven't fired in a while, Tarsnap should proceed with the backups as usual. If they don't, verify the printed timestamps and look for any DEBUG warning or error messages in the output. That might be a good time to get in touch with us, please make sure you include all the platform info, steps to reproduce and Tarsnap output in your report.