User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active
 
 

Invocationsyntax and -options

raspiBackup has to be invoked as user root or with sudo. The invocation syntax is

raspiBackup.sh Option1 Option2 Option3 ... backupdirectory 
and starting with Release 0.6.6 you can omit the extension .sh
 

raspiBackup Option1 Option2 Option3 ... backupdirectory

 
There are a lot of options available to customize the backup process. The most important parameters are marked in red. Some options require addition parameters as -k 3 or -m 1.

All default options can be overwritten in a configuration file /usr/local/etc/raspiBackup.conf. A sample configuration file which has the standard options defined can be downloaded here.

All options which turn something on or off can be controlled by a trailing + or -. Example: Option -z and option -z+ turn on the backupcompression. Option -z- turns off the backupcompression and ignores the definition DEFAULT_ZIP_BACKUP in the configuration file. That way it's possible to turn off options in the commandline even they are turned on in the configuration file.

In addition to /usr/local/etc/raspiBackup.conf other config files are read if they exist. The priority of the other config files is listed in following table:

 

OptionPriority Source
1 Invocation options
2 -f <configFile>
3 $(pwd)/.raspiBackup.conf
4 ~/.raspiBackup.conf
5  /usr/local/etc/raspiBackup.conf

 

Options theme sorted

 

Options alphabetical sorted

Parameter Function Default Option can be set in installer Option in configuration file
-a

Commands to start services stopped before the backup. Example "service xbmc start" (Attention: There are leading and trailing double quotes). This option is mandatory together with option -o.

Multiple commands have to be separated by && . As an alternative use a wrapperscript (See below). The commands should have the inverse sequence as the commands used for the  -o parameter.

Example:

-a "service nfs-kernel-server start && service samba start"

If there are no services to stop use a colon ":" as parameter.

See also FAQ#1 and FAQ#18

Note: 

All commands are executed as root. There is no sudo required.

None yes

DEFAULT_STARTSERVICES

-b Blocksize used in the dd command 1MB no

DEFAULT_DD_BLOCKSIZE

-B

Boot partition will be save with tar instead of dd

Note: This option has no function if partition oriented mode is used and option -P is used or DEFAULT_PARTITIONBASED_BACKUP=1 is defined in the configuration file.

No no

DEFAULT_TAR_BOOT_PARTITION_ENABLED

-C The root partition as backup target is rejected because there may not be enough space on the root parition. This option disabled the test and a backup can be created on the root partition. ATTENTION: There is no check whether there is enough space for the  backup. No no DEFAULT_SKIPLOCALCHECK
--coloring  Starting with version 0.6.5 messages can be colorized. Possible parms C for console and/or M for eMail. See also option --eMailColoring if you use the postfix eMailClient. CM no

DEFAULT_COLORING

 -D Addition invocation parameters for dd command (e.G.. "conv=notrunc,noerror,sync")  None no

DEFAULT_DD_PARMS

--dynamic

Mount

Starting with version 0.6.6 the specified mount point or partition will be mounted during startup and umounted at the end. If it's already mounted it's not umounted at the end. The mount point has to be defined in /etc/fstab. The option argument can either be the mount point (e.g. /backup) or the backup partition name (e.g. /dev/sdb1).  None no

DEFAULT_DYNAMIC_MOUNT

 -e

email address which will get a notification eMail

Attention: The notification eMail will be send by the root user. You have to configure your eMail client on your system that following command sends an eMail successfully

echo "eMail-Text" | sudo mail -s "Subject" "Rec
eiver eMail"

With configurationoption DEFAULT_SENDER_EMAIL it's possible to change the default sender addess root@$(hostname) if required.

 None yes

DEFAULT_EMAIL

-E

Optional additional parameters which are passed in the eMail call. For sendEmail use "-f sender.mail@senderdomain -s smtp-server:587 -xu username -xp password".

Attention: The parameters for -E have to have a leading and trailing double quote ". It's  useful to use parameter -F to speed up the test of the email notification function

Attention: If option -l 1 is used the password will be logged in the log file. Masquerade the password before sending the log to somebody.

None no

DEFAULT_EMAIL_PARMS

--eMail

Coloring

Default is to use the subject header in eMails to control eMail coloring because that's the way used by most of the emailCients. If postfix is used then parameter OPTION has to be used because postfix uses a dedicated option to control email coloring.
SUBJECT no

DEFAULT_EMAIL_COLORING

-f Configuration file which is includes last. See here for all configuration files and their precedence. No no  
-F Fake backup. This option is useful when raspiBackup is initially tested. The time consuming backup is not started but all the parameters are checked and an email is sent. No no  
-g This option enables a progress bar during backup and restore. For a tar backup there is no progress bar available.   no  
-G Define language of messages. Possible messages are DE (German) and EN (English). Volunteers to translate the messages into another languages are welcome.  Please contact me for details.

System language

If the system language is not supported EN (English) is used.

yes

DEFAULT_LANGUAGE

 -h  Help  No no  

--ignore

Additional

Partitions

Starting with version 0.6.5 raspiBackup allows to have more than two partitions on the SD card when tar or rsync backup is used. But only the first two partitions, /boot and / are saved and restored. Attention: All other paritions are not saved. No no

DEFAULT_IGNORE_ADDITIONAL_PARTITIONS

 -k

Number of backups to keep for all backup types if not overridden by following option. If you use the default you keep 3 dd, 3 tar and 3 rsync backups.

Note: This option is ignored when intelligent rotaion strategy is used.

 3 yes

DEFAULT_KEEPBACKUPS

--keep_<type>

Starting with version 0.6.4.3: Number of backups to keep for the specific backup type.

<type> can be any backup type, eg dd, ddz, tar, tgz or rsync

Note: These options are ignored when intelligent rotaion strategy is used.

Parameter for option -k no

DEFAULT_KEEPBACKUPS_{DD|DDZ|TAR|TGZ|RSYNC}

 -l

Log level defines whether a debug log will be created:

- off  -> No debug log

- debug -> Create debug log

Attention:  Logfile may contain sensitive data in some situations (E.g. external static IP addresses, eMailAddresses, passwords for mount commands or eMail server ...). The debug logs are stored in the backup location. In case the backup fails and the backup directory will be cleaned up the debug log is saved in the home directory of the caller first.

 on no

DEFAULT_LOG_LEVEL

-L

Defines the log target for raspiBackup.log

varlog: Target is /var/log/raspiBackup.log

backup: Log will be stored in created backup

current: Use current directory

<Fileprefix>: The debuglog will be created with extension .log and the messagefile with extension .msg.

Example: /home/pi/raspiBackup.

At the end /home/pi/raspiBackup.log and /home/pi/raspiBackup.msg will exist.

The backupdirectory will not get any log files.

backup no

DEFAULT_LOG_OUTPUT

-m

Message details:

- minimal -> Write important messages only

- detailed -> Write a lot of messages to show the progress

minimal yes

DEFAULT_MSG_LEVEL

-M

This option allows to create raspiBackup snapshots which are not included in the backup recycle process. In addition the passed text is appended to the backup directory name. See also this page for details about snapshots.

Note: raspiBackup snapshots are normal backups with special properties but no real snapshots like LVM or btrf snapshots

Note: These backup directories are not included in the backup recycle process and have to be deleted manually.

  no  
-n Notify if there is a newer version of raspiBackup available Yes no

DEFAULT_NOTIFY_UPDATE

-N Activation of plugins to activate custom code. See this page for details which also offers three sample plugins which report the CPU temperature and the memory utilization before and after the backup run. None no

DEFAULT_EXTENSIONS

--notify

Start

Starting with version 0.6.5 it's possible to get an eMail or Telegram notification when raspiBackup starts. Default is to send an eMail or notification only when raspiBackup finishes. No no

DEFAULT_NOTIFY_START

-o

Commands to stop services before the backup. Example "service smb stop" (Attention: There are leading and trailing double quotes). This option is mandatory together with option -a.

Multiple commands have to be separated by && . As an alternative use a wrapperscript (See below). The commands should have the inverse sequences as the commands used for the  -a parameter

Example:

-o "service samba stop && service nfs-kernel-server stop"

If there are no services to stop use a colon ":" as parameter.

See also FAQ#1 and FAQ#18 

Note: 

All commands are executed as root. There is no sudo required.

None yes

DEFAULT_STOPSERVICES

-P Enable partitionoriented mode which allows to save more than the first two partitions which are saved in the normal mode. Use parameter -T to define which partitions should be saved. off yes

DEFAULT_PARTITIONBASED_BACKUP

--reboot

System

Starting with release 0.6.7 this option initiates a reboot when the backup run finished. This way all services are restarted again. Arguments passed with option -a will be ignored because of this.

Note: If option -F is used no reboot will be executed.

off no

DEFAULT_REBOOT_SYSTEM

-s

email program to use to sent the notification eMail  {mail|sendEmail|ssmtp|msmtp}. Use mail also for postfix and nullmailer and install mailtools. For sendEmail use also parameter -E to pass mandatory parameters (See parameter -E description for details)

Other eMailClients can be used via an eMailPlugin Then mailext has to passed as the parameter. See this page for details about the eMailPlugin.

mail no

DEFAULT_MAIL_PROGRAM

-S An update with option -U is executed even the versions are identical. A local betaversion and a local normal version will be replaced with the latest code level. It's primarily used to update a local beta version to the latest code level. off no  

--smart

Recycle

Starting with version 0.6.5 this option enables the intelligent rotationstrategy. For details see here. This also disables all --keep options and they don't have to be disabled by setting them to 0. off yes

DEFAULT_SMART_RECYCLE

--smart

Recycle

Dryrun

Starting with version 0.6.5 this option enables or disables the test mode of the intelligent rotationstrategy on. For details see here.

yes no

DEFAULT_SMART_RECYCLE_DRYRUN

--smart

Recycle

Options

Starting with version 0.6.5 this option defines the intelligent rotationstrategy parameters. For details see here. "7 4 12 1" yes

DEFAULT_SMART_RECYCLE_OPTIONS

--system

status

A list of running services and open files is reported in the debug logfile.   no  
-t

Backup type which can be dd, tar or rsync. rsync uses hardlinks if the backupfilesystem is an ext3/ext4 partition 

Attention:  rsync should not be used with NTFS formatted Backuppartitions because cannot store the access rights of an ext3/4 filesystem correctly. Therefore the access rights cannot be restored correctly on an ext3/4 filesystem and the restored image is unusable. In addition hardlinks are supported only on ext3/4 filesystems in order to minimze disk space usage.

See details of the backuptypes. An external root filesystem will be saved if tar or rsync backup is used and option -P is not selected. Parameter -z can be used in addition to zip the backups to reduce the backup size.

Note: dd backup can be controlled by configuration parameter DEFAULT_DD_BACKUP_SAVE_USED_PARTITIONS_ONLY which saves backuptime and -space. For details of the parameter see bottom of table.

dd yes

DEFAULT_BACKUPTYPE

-T

If the partitionoriented backupmode is selected with option -P this parameter can be used to define which partitions should be saved. Example: -T "1 2 5" saves the first two partitions and the fifth partition. * saves all partitions. 

* until release 0.6.5.1

"1 2" starting with release 0.6.6

yes

DEFAULT_PARTITIONS_TO_BACKUP 

--telegram

Token

--telegram

ChatID

--telegram

Notifications

Starting with version 0.6.5 Telegram notifications are supported. You have to configure the token and chatid. Notifications option can be S for success and/or F for failure. With "M" raspiBackup messages are attached in a file.. With "m" raspiBackup messages are sent too. Any of these options can be combined. Example: "SFM" or "Sm". Options "M" and "m" cannot be used together.

No

 

no

DEFAULT_TELEGRAM_TOKEN

DEFAULT_TELEGRAM_CHATID
DEFAULT_TELEGRAM_NOTIFICATIONS

--timestamps This option can be used to prefix all messages with a timestamp. No no

DEFAULT_TIMESTAMPS

-u
Extension of the excludelist for a backup to exlude special files and directories.
 

Attention: Parameters have to follow the syntax of the backuptool used. Otherwise the backup will fail. Example for rsync or tar:

"--exclude=/backup/* --exclude=/rsnapshot/* --exclude=/www-data*/*" 

Note the enclosing double quotes!

Additional information about the syntax is available on the man pages of the backup tools used.

Following directories are not saved:
Backuppath used in invocation, /proc/* , /lost+found/* , /sys/* , /dev/* , /tmp/*, /boot/*, /run/* , /proc/* , /lost+found/* , /sys/* , /dev/* , /tmp/* , /boot/* , /run/*
In addition all mounted directories from external devices which are not mounted on / are not saved. It's only the boot parition /dev/mmcblk0p1 and the root partition /dev/mmcblk0p2 or the external root filesystem on /dev/sda1 which is saved.
 
Note for partitionoriented backup mode:
 
If option -P is used the directories mentioned above are exluded in all partition backups.
 
rsync:
   */directory/* - Excludes directory on all partitions
   mmcblk0p2/verzeichnis/* - Excludes directory on partition mmcblk0p2
 
tar:
   directory/* - Excludes directory on all partitions
 
None no

DEFAULT_EXCLUDE_LIST

--unsupported

Environment

Starting with release 0.6.7  this option allows to start raspiBackup also on unsupported environments. For details read this article. off no  
-U

Upgrades the current raspiBackup version with the latest available version. The previous one will be saved as raspiBackup.sh.n.m where n and m are the versionnumbers of raspiBackup.

Attention: Read this page and understand which changes and new functions will become available before upgrading.

See also option -S which forces an update with the latest version even the versions are identical.

No no  
--updateUUIDs Starting with release 0.6.4.4: A restore will create partitions with the same UUIDs and PARTUUIDs of the original system. This option will create new UUIDs and PARTUUIDs on the restored partitions. No no

DEFAULT_UPDATE_UUIDS

-v Verbose mode of the backup tools tar and rsync. This option is useful during initial manual backup tests in order to see the backup progress. No no

DEFAULT_VERBOSE

-V Presents a list of existing previous version and allows to select one of the version to restore. The actual version will be saved and can be restored later on. See also parameter -U. (Available with Release 0.6) No no  
--version

Display the version information of raspiBackup in following format:

Version: 0.6.3.2 CommitSHA: 8fbcd1a CommitDate: 2018-02-19 CommitTime: 19:18:31

That way it's possible to query the current version information in a programmatic way.

No no  
-y This option starts the deployment of the actual script to hosts which are defined in the configuration file. Access has to be possible without password and requires the keys to be copied into authorized_keys . That way you can quickly deploy a new script version on multiple hosts. No no

DEFAULT_DEPLOYMENT_HOSTS

-z Use gzip with dd or tar backup to reduce the backup size No yes

DEFAULT_ZIP_BACKUP

 

An eMail will be sent only in case of backup failure Note: If raspiBackup crashes because of unexpected reasons it may happen there is no eMail send even the backup failed.

You use this option on your own risk.

No no

DEFAULT_MAIL_ON_ERROR_ONLY

 

Backupoptions used by rsync backup.

You use this option on your own risk.

--delete -aHAx no

DEFAULT_RSYNC_BACKUP_OPTIONS

  Backupoptions used by tarbackup. You use this option on your own risk. -cpi no

DEFAULT_TAR_BACKUP_OPTIONS

 

Additional backupoptions used by rsync backup.

You use this option on your own risk.

  no

DEFAULT_RSYNC_BACKUP_ADDITIONAL_OPTIONS

 

Additional backupoptions used by rsync backup.

You use this option on your own risk.

  no

DEFAULT_TAR_BACKUP_ADDITIONAL_OPTIONS

  Bootpartition backups use hardlinks to minimze the backupspace because bootpartitions don't change often. Note: Ssupport of hardlinks on the backupspace required (ext3/ext4 filesystem) No no

DEFAULT_LINK_

BOOTPARTITIONFILES

 

dd backup only saves the space used by defined partitions. That way a backup of a 32 GB SD card with a 8GB partition only needs 8GB. The root partition in general uses the the whole SD card and has to be resized with gparted or resize2fs first appropriately.

See also FAQ#16

No no

DEFAULT_DD_BACKUP_SAVE_USED_PARTITIONS_ONLY

  This option is used to append the log to the eMail -a no

DEFAULT_APPEND_LOG_OPTION

  Define the sender eMail for ssmtp and msmtp. root@$(hostname) no

DEFAULT_SENDER_EMAIL

 

Backup restore test reminder Intervall (Unit: Months)

6 no

DEFAULT_RESTORE_REMINDER_INTERVAL

  Number of reminders to execute a backup restore test 3 no

DEFAULT_RESTORE_REMINDER_REPEAT

  Starting with version 0.6.4.3: Defined commands are executes before and after backup creation and before stopping and after starting system services (options -a and -o) No no

DEFAULT_BEFORE_STOPSERVICES

DEFAULT_AFTER_STARTSERVICES

  Starting with version 0.6.7 you can define a pre and post exit which is executed when a backup is restored. The syntax is identical to the extsion format for backups. Empty no

DEFAULT_RESTORE_EXTENSIONS

   Starting with version 0.6.7 you can redefine the color codes used for emails and console. The first pair defines the colors for warnings and the second pair the colors for errors. The first element of the pair is the HTML color code The second element defined the VT100 color code. ("#FF8000 33" "#FF0000 31")
 
 no

 DEFAULT_RESTORE_EXTENSIONS

 

Starting with version 0.6.8 you can sent notifications to pushover.

You have to register on https://pushover.net/ first and have to create an application.

PUSHOVER_USER is the Pushover User Key.

PUSHOVER_TOKEN is the API Token Key for you application.

Notifications option can be S for success and/or F for failure. With "M" raspiBackup messages are attached in a file.. With "m" raspiBackup messages are sent too. Any of these options can be combined. Example: "SFM" or "S"F.

Priorities are the Pushover priorities.

Sounds are the Pushover sounds.

  no

DEFAULT_PUSHOVER_TOKEN

DEFAULT_PUSHOVER_USER

DEFAULT_PUSHOVER_NOTIFICATIONS

DEFAULT_PUSHOVER_SOUND_SUCCESS

DEFAULT_PUSHOVER_SOUND_FAILURE

DEFAULT_PUSHOVER_PRIORITY_SUCCESS

DEFAULT_PUSHOVER_PRIORITY_FAILURE

 

Starting with version 0.6.8 you can sent notifications to slack.

Notifications option can be S for success and/or F for failure. With "M" raspiBackup messages are attached in a file.. With "m" raspiBackup messages are sent too. Any of these options can be combined. Example: "SFM" or "S"F.

  no DEFAULT_SLACK_WEBHOOK_URL
DEFAULT_SLACK_NOTIFICATIONS
 
Note: Options in the config file which are set to yes or no have to be set as 0 for no and 1 for yes.
 
All options for the restore of a backup are described here.
 
Add comment

*** Note ***

Comments are welcome. But in order to reject spam posts please consider following rules:
  1. Comments with string http are rejected with message You have no rights to use this tag
  2. All comments are reviewed by hand and thus it usually takes one day until a comment will be published.