======= INSTALL ======= These are instructions on how to set up "Backup Monitor" so that it helps you in regularly making a backup of your valuable data. Topics covered are: FOREWORD REQUIREMENTS INSTALLATION CUSTOMIZATION FOREWORD ======== Backup Monitor has been designed to make a backup of a user's most important directories. The default behaviour is to use the directories pointed at by xdg-utils, which -- for an english desktop -- would be: $HOME/ Documents/ Videos/ Pictures/ Music/ Thanks to xdg-utils, Backup Monitor is able to adapt to the specifics of the current desktop (typically when the directories have their names translated in the user's language). So the following point must be clearly understood: BY DEFAULT THE DATA THAT IS NOT IN A DIRECTORY CALLED Documents, Videos, Pictures, Music WON'T BE BACKED UP. FOR NON-ENGLISH DESKTOP THIS ADAPT AUTOMATICALLY TO THE EQUIVALENT (TRANSLATED) DIRECTORIES. If you want to change this behaviour or add more stuff to be backed up, please read the CUSTOMIZATION section. REQUIREMENTS ============ Strong dependices on (packages without which this has no chance to work): - python>=2.5 - pygtk - rsync Recommended dependencies (packages with which it will work at its best): - xdg-utils (more info about xdg-utils: http://portland.freedesktop.org/wiki/) .. NOTE:: if xdg-utils is not available, it is still possible to use backup-monitor, but you'll have to manually disable all defaut backup (see CUSTOMIZATION section). INSTALLATION ============ 1/ Decompress the archive (if you're reading this you've probably already done it already) 2/ Run the script of installation: $ ./install.sh .. NOTE:: This will install all the needed files in the xdg-standard place: $HOME/.local/ .. WARNING:: If you get the following message when running the install script, please read the subsection about "Automatic launch":: No autostart folder: you'll have to modify the session startup yourself 4/ Connect the device (e.g. external hard disk) that will be used to store a the backup copy of your data. 5/ Let's assume it's detected with the name MyDrive, then you should: a. Create a specific backup directory (e.g. called "MyBackupFolder") on this drive (optional but surely good practice) b. Create a symolic link named backup_destination in you home folder. Here is the command needed to do so in a terminal: $ cd $HOME; ln -s /media/MyDrive/MyBackupFolder backup_destination Now "Backup Monitor" should start automatically at your next desktop session. However if you're impatient to do your first backup, you may already launch it on the command line like this: $ backup-monitor.py Automatic launch ---------------- When installed on modern Linux desktop that implement xdg specifications, Backup Monitor will automatically register itself among application to be started at the begining of each new sessions. IF NOT, you can do the following: 1/ Make sure the folder containing backup-monitor.py (typically $HOME/.local/bin) is in your PATH. 2/ Add "Backup Monitor" to the list of application to be launched every time you log in on your desktop. .. HINT:: To do so on a GNOME desktop go in Preferences->Sessions and add the backup-monitor.py script (installed by default in $HOME/.local/bin) to the startup list. CUSTOMIZATION ============= What's done during a backup can be tweaked in many ways: disabling some default actions, registering new folder to the backup list, launching custom scripts. All customisation starts by creating or modifying a preferences.cfg file in "$HOME/.config/backup-monitor/". An exemple of such a file is provided in share/backup-monitor/examples/preferences.cfg Changing the defaults --------------------- To modify the default behaviour you should create or adapt the "ChangeDefaults" section of the preference file. Possible changes include: - changing the backup destination by defining a "DestinationFolder" variable. To define this variable, you can use the "~" abbreviation for your home directory. - disabling backup for some directories, by defining a "SkipList" variable as a comma separated list. Values in the list must be among the following: Documents,Videos,Pictures,Music. If your desktop is configured for another language than english, you should still use these values (they will be automatically translated according to xdg's definitions.). For instance, the related part of preferences.cfg could look like:: # Modify the default behaviour [ChangeDefaults] # Change the folder in which data will be copied DestinationFolder: ~/myBackupFolder # A comma separated list of folders among {Documents, Video, Music, Pictures} SkipList: Videos,Documents Backup non-default folders -------------------------- You can ask for some more folders to be backed up. To do so you should create, for each new folder, a new section with an explicit name (a single word that should *not* be "ChangeDefaults"). In this section, define the "Type" variable as equal to "folder", and the "FolderPath" variable as the path to the folder to be backed up. For instance, the related part of preferences.cfg could look like:: # Add a new folder to be backed up [MyNewFolder] # This section defined a "standard" backup for a folder Type: folder # Path to the folder that will be backed up FolderPath: ~/MyNewFolder Running custom scripts ---------------------- You can ask for specific scripts to be launched during the backup procedure. To do so you should create, for each custom script, a new section with an explicit name (a single word that should *not* be "ChangeDefaults"). In this section, define the "Type" variable as equal to "script", and the "ScriptName" variable as the name to the script. Your custom script should be stored in "$HOME/.config/backup-monitor/user-scripts/". It can also be stored in a subdirectory, but you should then indicate the hierarchy (relative to "user-scripts") in the "ScriptName" variable. For instance, the related part of preferences.cfg could look like:: # Also register a script to backup firefox's data [Firefox] # This section defines a "scripted" backup Type: script # Name of the script (provided as an example in examples/user-scripts) ScriptName: bkp_firefox.sh .. HINT:: Some working scripts samples are provided in the share/backup-monitor/examples/user-scripts folder. YOu are free to re-use and modify them, just make sure to copy them in $HOME/.config/backup-monitor/user-scripts/ and to make them executable (for instance with "chmod u+x myscript.sh"). .. NOTE:: In order to ease the construction of new scripts, the following environment variables are made available when the script is run: - ``BACKUP_MONITOR_RSYNC_SCRIPT`` gives the path to the rsync script used for all other backup operation (default and additional folders). This script must be called with two arguments in the right order: the folder to back up and the backup destination. - ``BACKUP_MONITOR_DESTINATION_FOLDER`` gives the folder defined as the backup destination. This is the same folder that can be changed by the "DestinationFolder" variable (see the "Changing the defaults" section).