How to create a custom backup plan for Debian with backupninja

Last updated on June 21, 2020 by Gabriel Cánepa

Backupninja is a powerful and highly-configurable backup tool for Debian based distributions. In the previous tutorial, we explored how to install backupninja and how to set up two backup actions for the program to perform. However, we should note that those examples were only "the tip of the iceberg," so to speak. In this post we will discuss how to leverage custom handlers and helpers that allow this program to be customized in order to accomplish almost any backup need that you can think of.

And believe me - that is not an overstatement, so let's begin.

A Quick Review of Backupninja

One of backupninja's distinguishing features is the fact that you can just drop plain text configuration or action files in /etc/backup.d, and the program will take care of the rest. In addition, we can write custom scripts (aka "handlers") and place them in /usr/share/backupninja to handle each type of backup action. Furthermore, we can have these scripts be executed via ninjahelper's ncurses-based interactive menus (aka "helpers") to guide us to create the configuration files we mentioned earlier, minimizing the chances of human error.

Creating a Custom Handler and Helper

Our goal in this case is to create a script to handle the backup of chosen home directories into a tarball with either gzip or bzip2 compression, excluding music and video files. We will simply name this script home, and place it under /usr/backup/ninja.

Although you could achieve the same objective with the default tar handler (refer to /usr/share/backupninja/tar and /usr/share/backupninja/tar.helper), we will use this approach to show how to create a useful handler script and ncurses-based helper from scratch. You can then decide how to apply the same principles depending on your specific needs.

Note that since handlers are sourced from the main script, there is no need to start with #!/bin/bash at the top.

Our proposed handler (/usr/share/backupninja/home) is as follows. It is heavily commented for clarification. The getconf function is used to read the backup action's configuration file. If you specify a value for a variable here, it will override the corresponding value present in the configuration file:

# home handler script for backupninja

# Every backup file will identify the host by its FQDN
getconf backupname

# Directory to store backups
getconf backupdir

# Default compression
getconf compress

# Include /home directory
getconf includes

# Exclude files with *.mp3 and *.mp4 extensions
getconf excludes

# Default extension for the packaged backup file

# Absolute path to date binary
getconf  TAR `which tar`

# Absolute path to date binary
getconf    DATE    `which date`

# Chosen date format

# If backupdir does not exist, exit with fatal error
if [ ! -d "$backupdir" ]
   mkdir -p "$backupdir" || fatal "Can not make directory $backupdir"

# If backupdir is not writeable, exit with fatal error as well
if [ ! -w "$backupdir" ]
   fatal "Directory $backupdir is not writable"

# Set the right tar option as per the chosen compression format
case $compress in
     warning "Unknown compress filter ($tar_compress)"

# Exclude the following file types / directories
for i in $excludes
   exclude_options="$exclude_options --exclude $i"

# Debugging messages, performing backup
debug "Running backup: " $TAR -c -p -v $compress_option $exclude_options 
   -f "$backupdir/$backupname-"`$DATE "+$DATEFORMAT"`".$EXTENSION" 

# Redirect standard output to a file with .list extension
# and standard error to a file with .err extension
$TAR -c -p -v $compress_option $exclude_options 
   -f "$backupdir/$backupname-"`$DATE "+$DATEFORMAT"`".$EXTENSION" 
   > "$backupdir/$backupname-"`$DATE "+$DATEFORMAT"`.list 
   2> "$backupdir/$backupname-"`$DATE "+$DATEFORMAT"`.err

[ $? -ne 0 ] && fatal "Tar backup failed"

Next, we will create our helper file (/usr/share/backupninja/home.helper) so that our handlers shows up as a menu in ninjahelper:

# Backup action's description. Separate words with underscores.
HELPERS="$HELPERS home:backup_of_home_directories"

home_wizard() {
   home_title="Home action wizard"

   backupname=`hostname --fqdn`

# Specify default value for the time when this backup actions is supposed to run
   inputBox "$home_title" "When to run this action?" "everyday at 01"
   [ $? = 1 ] && return
   home_when_run="when = $REPLY"

# Specify default value for backup file name
   inputBox "$home_title" ""Name" of backups" "$backupname"
   [ $? = 1 ] && return
   home_backupname="backupname = $REPLY"

# Specify default directory to store the backups
   inputBox "$home_title" "Directory where to store the backups" "/var/backups/home"
   [ $? = 1 ] && return
   home_backupdir="backupdir = $REPLY"

# Specify default values for the radiobox
   radioBox "$home_title" "Compression" 
     "none"    "No compression" off 
       "gzip"    "Compress with gzip" on 
    "bzip"    "Compress with bzip" off
   [ $? = 1 ] && return;
   home_compress="compress = $REPLY "

   while [ -z "$REPLY" ]; do
    formBegin "$home_title: Includes"
         formItem "Include:" /home/gacanepa
     [ $? = 0 ] || return 1
      home_includes="includes = "
   for i in $REPLY; do
         [ -n "$i" ] && home_includes="$home_includes $i"

   while [ -z "$REPLY" ]; do
      formBegin "$home_title: Excludes"
         formItem "Exclude:" *.mp3
         formItem "Exclude:" *.mp4
         # Add as many “Exclude” text boxes as needed to specify other exclude options
formItem "Exclude:"
      formItem "Exclude:"
     [ $? = 0 ] || return 1
      home_excludes="excludes = "
   for i in $REPLY; do
         [ -n "$i" ] && home_excludes="$home_excludes $i"

# Save the config
   get_next_filename $configdirectory/10.home
   cat > $next_filename <<EOF

# tar binary - have to be GNU tar
TAR    `which tar`
DATE    `which date`
DATEFORMAT     "%Y-%m-%d"

# Backupninja requires that configuration files be chmoded to 600
   chmod 600 $next_filename

Running Ninjahelper

Once we have created our handler script named home and the corresponding helper named home.helper, let's run ninjahelper command to create a new backup action:

# ninjahelper

And choose create a new backup action.

We will now be presented with the available action types. Let's select "backup of home directories":

The next screens will display the default values as set in the helper (only 3 of them are shown here). Feel free to edit the values in the text box. Particularly, refer to the scheduling section of the documentation for the right syntax for the when variable.

When you are done creating the backup action, it will show in ninjahelper's initial menu:

Then you can press ENTER to show the options available for this action. Feel free to experiment with them, as their description is quite straightforward.

Particularly, "run this action now" will execute the backup action in debug mode immediately regardless of the scheduled time:

Should the backup action fail for some reason, the debug will display an informative message to help you locate the error and correct it. Consider, for example, the following error messages that were displayed after running a backup action with bugs that have not been corrected yet:

The image above tells you that the connection needed to complete the backup action could not be completed because the remote host seems to be down. In addition, the destination directory specified in the helper file does not exist. Once you correct the problems, re-run the backup action.

A few things to remember:


In this post we have discussed how to create our own backup actions from scratch and how to add a related menu in ninjahelper to facilitate the creation of configuration files. With the previous backupninja article and the present one I hope I've given you enough good reasons to go ahead and at least try it.

Happy backuping!

Support Xmodulo

This website is made possible by minimal ads and your gracious donation via PayPal or credit card

Please note that this article is published by under a Creative Commons Attribution-ShareAlike 3.0 Unported License. If you would like to use the whole or any part of this article, you need to cite this web page at as the original source.

Xmodulo © 2021 ‒ AboutWrite for UsFeed ‒ Powered by DigitalOcean