#language en

= Client backups =
User data can be backed up by synchronising these data with the user's home directory on `b.fluid.tuwien.ac.at`.

Home directories on `b.fluid` are backed up daily and can be restored for at least one year by the admins.
You can log in via ssh to `b.fluid.tuwien.ac.at`, using the credentials of your TU e-mail account,
to see whether a home directory is already set up for you.
If a home directory does not yet exist on `b.fluid`, please contact the admins (Thomas Loimer or Iris Fula) so they can create a home directory for you.

The synchronisation of the data involves two steps which are presented in detail further below,
 i. setting up a `rsync`-command which synchronises the data on a desktop computer with the data on `b.fluid.tuwien.ac.at`, and
 i. setting up a `cron`-job which invokes the `rsync`-command once an hour.

== Setup instructions ==
=== Windows ===
In order to set up file synchronisation to `b.fluid` on your Windows client, your system needs an rsync client and a customised Windows synchronisation script. For details on how to proceed, please contact Iris Fula.

=== Common part for GNU/Linux, macOS, other Unix-like operating systems ===
On your desktop computer, please …
  * check that the program `rsync` is installed (should be installed by default on most systems)
  * save the script [attachment:sync-to-host sync-to-host] to a directory of our choice, for example `~/bin/`; further below, the path to this script must be set accordingly
  * make the script [attachment:sync-to-host sync-to-host] executable (e.g., `chmod +x ~/bin/sync-to-host`)
  * copy the following lines to a terminal, adjusting `TU_USER` according to your TU username:
{{{
bash	# the commands below must be executed in the bash shell
export TU_USER=YOUR_TU_USERNAME
}}}
  * copy/paste the following lines to a terminal, adjusting ~/bin/sync-to-host to the actual path to the script,
{{{
export TARGET_HOST=b.fluid.tuwien.ac.at
export TARGET_DIR=$(hostname -s)

# run the backup script once (enter your TU password when asked to do so)
~/bin/sync-to-host ${TU_USER} ${TARGET_HOST} ${TARGET_DIR}
}}}
  * Please, edit the file `~/.config/sync-to-host/exclude.txt` and set the patterns of files and directories which should be ignored by the backup. See `man rsync` under `INCLUDE/EXCLUE PATTERN RULES` for the syntax of these patterns.

The top of the file [attachment:sync-to-host sync-to-host] contains some comments on how the script works.

==== Automated backups on GNU/Linux ====
In order to set up a cron job for automated client backups on GNU/Linux  systems, please copy and paste the following lines into the same 
terminal as above. Set `SYNC_CMD` according to the path where you saved the [attachment:sync-to-host sync-to-host] script:
{{{
export SYNC_CMD="${HOME}/bin/sync-to-host ${TU_USER} ${TARGET_HOST} ${TARGET_DIR}"
export SYNC_TIME="$((RANDOM % 60)) * * * *"
export CRON_ENTRY="${SYNC_TIME} ${SYNC_CMD}"
crontab -l 2>/dev/null | { cat; echo "${CRON_ENTRY}"; } | crontab -
}}}

==== Automated backups on macOS ====
In order to set up a launchd job for automated client backups on macOS systems, please copy and paste the following lines into a terminal:

{{{
#!/bin/bash
export BASENAME=at.ac.tuwien.fluid.b_backup-${USER}
export PLIST_PATH=${HOME}/Library/LaunchAgents/${BASENAME}.plist
cat > ${PLIST_PATH} <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>${BASENAME}</string>

  <key>ProgramArguments</key>
  <array>
    <string>${HOME}/bin/sync-to-host</string>
    <string>${TU_USER}</string>
    <string>${TARGET_HOST}</string>
    <string>${TARGET_DIR}</string>
  </array>

  <key>RunAtLoad</key><true/>
  <key>StartInterval</key><integer>3600</integer>
</dict>
</plist>
EOF
launchctl load ${PLIST_PATH}
}}}

= Restoring data =
== Instructions for admins ==
In order to restore data from a backup, backups can be mounted to a user's home directory. Users can then access their data using an SFTP client (e.g. Nautilus on GNU/Linux, Cyberduck on macOS and WinSCP on Windows).

For example, in order to expose backup data from `b.fluid` to the user `oswat`, the following commands might be used:
{{{
export BACKUP_REPO=/mnt/backup/b/home/oswat.borg
export RESTORE_DIR=/home/oswat/restore-$(date -Idate)
mkdir ${RESTORE_DIR}
borg mount -o default_permissions,allow_other ${BACKUP_REPO} ${RESTORE_DIR}
ls ${RESTORE_DIR}
}}}

Note: As soon as users have restored their data, backups should be unmounted again:
{{{
umount ${RESTORE_DIR}
}}}