From 1a2c31f6226911b12cc3d3d96613a93eac031f78 Mon Sep 17 00:00:00 2001 From: Gofannon <17145502+Gofannon@users.noreply.github.com> Date: Mon, 14 Jan 2019 00:07:04 +0100 Subject: [PATCH 1/4] [enh] linter 'markdown' Can cause issue with titles size on the final documentation "From the webadmin" will move from

to

and will be shwoned bigger --- backup.md | 92 +++++++++++++++++++++++++++---------------------------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/backup.md b/backup.md index 312cc99c..73f8f1b3 100644 --- a/backup.md +++ b/backup.md @@ -1,10 +1,8 @@ -Backing up your server and apps -=============================== +# Backing up your server and apps -Backing up your server, apps and data is an important concern when administrating a server. This protects you from unexpected events that could happen (server lost in a fire, database corruption, loss of access, server compromised, ...). The backup policy you will put in place depends of the importance of the services and data hosted. For instance you won't care too much about having backup on a test server, but you will care about having a backup of critical data of your association or company, and having this backup *in a different physical place*. +Backing up your server, apps and data is an important concern when administrating a server. This protects you from unexpected events that could happen (server lost in a fire, database corruption, loss of access, server compromised, ...). The backup policy you will put in place depends of the importance of the services and data hosted. For instance you won't care too much about having backup on a test server, but you will care about having a backup of critical data of your association or company, and having this backup *in a different physical place*. -Backups in the context of YunoHost ----------------------------------- +## Backups in the context of YunoHost YunoHost comes with a backup system, that allows to backup (and restore) system configurations and data (e.g. mails) and apps if they support it. @@ -12,58 +10,61 @@ You can manage backups either from the command line (`yunohost backup --help`) o The current default method consists in creating a `.tar.gz` archive containing all relevant files. In the future, YunoHost plans to support [Borg](https://www.borgbackup.org/) which is a more flexible, efficient and powerful solution. -Creating backups ----------------- +## Creating backups -#### From the webadmin +### From the webadmin You can easily create backup archives from the webadmin by going in Backups > Local storage and clicking on "New backup". You will then be asked to select which configuration, data and apps you want to backup. -![](/images/backup.png) +![picture of Yunohost's backup pannel](/images/backup.png) -#### From the command line +### From the command line -You can create a new backup archive with the command line. Here are a few simple example of commands and their corresponding behavior : +You can create a new backup archive with the command line. Here are a few simple example of commands and their corresponding behavior : -- Backing up everything (all system parts and apps) : -```bash -yunohost backup create -``` +- Backing up everything (all system parts and apps) : + + ```bash + yunohost backup create + ``` - Backing up only apps -```bash -yunohost backup create --apps -``` + + ```bash + yunohost backup create --apps + ``` - Backing up only two apps (wordpress and shaarli) -```bash -yunohost backup create --apps wordpress shaarli -``` + + ```bash + yunohost backup create --apps wordpress shaarli + ``` - Backing up only mails -```bash -yunohost backup create --system data_mail -``` + + ```bash + yunohost backup create --system data_mail + ``` - Backing up mails and wordpress -```bash -yunohost backup create --system data_mail --apps wordpress -``` + + ```bash + yunohost backup create --system data_mail --apps wordpress + ``` For more informations and options about backup creation, consult `yunohost backup create --help`. You can also list system parts that can be backuped with `yunohost hook list backup`. -#### Apps-specific configuration +### Apps-specific configuration Some apps such as Nextcloud may be related to a large quantity of data which are not backuped by default. This practice is referred to "backing up only the core" (of the app). However it's possible to enable the backup of all data of this app with `yunohost app setting nextcloud backup_core_only -v 0`. Be careful though that your archive might get huge if there's too much data to be backuped... -Downloading and uploading backups ---------------------------------- +## Downloading and uploading backups After creating backup archives, it is possible to list and inspect them via the corresponding views in the webadmin, or via `yunohost backup list` and `yunohost backup info ` from the command line. By default, backups are stored in `/home/yunohost.backup/archives/`. There is currently no straightfoward way to download or upload a backup archive. -One solution consists in using `scp` (a program based on [`ssh`](/ssh)) to copy files between two machines via the command line. Hence, from a machine running Linux, you should be able to run the following to download a specific backup: +One solution consists in using `scp` (a program based on [`ssh`](/ssh)) to copy files between two machines via the command line. Hence, from a machine running Linux, you should be able to run the following to download a specific backup: ```bash scp admin@your.domain.tld:/home/yunohost.backup/archives/.tar.gz ./ @@ -80,23 +81,23 @@ Alternatively, a solution can be to install Nextcloud or a similar app and confi Restoring backups ----------------- -#### From the webadmin +### From the webadmin Go in Backup > Local storage and select your archive. You can then select which items you want to restore, then click on 'Restore'. -![](/images/restore.png) +![picture of Yunohost's restore pannel](/images/restore.png) -#### From the command line +### From the command line From the command line, you can run `yunohost backup restore ` (without the `.tar.gz`) to restore an archive. As for `yunohost backup create`, this will restore everything in the archive by default. If you want to restore only specific items, you can use for instance `yunohost backup restore --apps wordpress` which will restore only the wordpress app. -#### Constraints +### Constraints To restore an app, the domain on which it was installed should already be configured (or you need to restore the corresponding system configuration). You also cannot restore an app which is already installed ... which means that to restore an old version of an app, you must first uninstall it. -#### Restoring during the postinstall +### Restoring during the postinstall -One specific feature is the ability to restore a full archive *instead* of the postinstall step. This makes it useful when you want to reinstall a system entirely from an existing backup. To be able to do this, you will need to upload the archive on the server and place it in `/home/yunohost.backup/archives`. Then, instead of `yunohost tools postinstall` you can run: +One specific feature is the ability to restore a full archive *instead* of the postinstall step. This makes it useful when you want to reinstall a system entirely from an existing backup. To be able to do this, you will need to upload the archive on the server and place it in `/home/yunohost.backup/archives`. Then, instead of `yunohost tools postinstall` you can run: ```bash yunohost backup restore @@ -105,10 +106,9 @@ yunohost backup restore Note: Don't start the postinstall step. Decline invite when doing installation via `bash`/`wget`. -To go futher ------------- +## To go futher -#### Storing backups on a different drive +### Storing backups on a different drive If you want, you can connect and mount an external drive to store backup archives on it (among other things). For this, we first move the existing archives then add a symbolic link. @@ -118,16 +118,16 @@ mv /home/yunohost.backup/archives $PATH_TO_DRIVE/yunohost_backup_archives ln -s $PATH_TO_DRIVE/yunohost_backup_archives /home/yunohost.backup/archives ``` -#### Automatic backups +### Automatic backups -You can add a simple cron job to trigger automatic backups regularly. For instance, to backup your wordpress weekly, create a file `/etc/cron.weekly/backup-wordpress` with the following content : +You can add a simple cron job to trigger automatic backups regularly. For instance, to backup your wordpress weekly, create a file `/etc/cron.weekly/backup-wordpress` with the following content : ```bash #!/bin/bash yunohost backup create --apps wordpress ``` -then make it executable : +then make it executable : ```bash chown +x /etc/cron.weekly/backup-wordpress @@ -137,13 +137,13 @@ Be careful what you backup exactly and when : you don't want to end up with your #### Backing your server on a remote server -You can follow this tutorial on the forum to setup Borg between two servers : https://forum.yunohost.org/t/how-to-backup-your-yunohost-server-on-another-server/3153 +You can follow this tutorial on the forum to setup Borg between two servers : -Alternatively, the app Archivist allows to setup a similar system : https://forum.yunohost.org/t/new-app-archivist/3747 +Alternatively, the app Archivist allows to setup a similar system : #### Full backup with `dd` -If you are using an ARM board, another method for doing a full backup can be to create an image of the SD card. For this, poweroff your ARM board, get the SD card in your computer then create a full image with something like : +If you are using an ARM board, another method for doing a full backup can be to create an image of the SD card. For this, poweroff your ARM board, get the SD card in your computer then create a full image with something like : ```bash dd if=/dev/mmcblk0 of=./backup.img From 1f085dc43192a59cb4ae1a77ecd658e6473eacfb Mon Sep 17 00:00:00 2001 From: Gofannon <17145502+Gofannon@users.noreply.github.com> Date: Mon, 14 Jan 2019 00:10:23 +0100 Subject: [PATCH 2/4] [fix] add workaround to manage backup Needed while waiting for a solution. See https://github.com/YunoHost/issues/issues/1266 --- backup.md | 11 +++- backup_workaround.md | 140 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 2 deletions(-) create mode 100644 backup_workaround.md diff --git a/backup.md b/backup.md index 73f8f1b3..ab72d3b9 100644 --- a/backup.md +++ b/backup.md @@ -78,8 +78,15 @@ scp /path/to/your/.tar.gz admin@your.domain.tld:/home/yunohost.back Alternatively, a solution can be to install Nextcloud or a similar app and configure it to be able to access files in `/home/yunohost.backup/archives/` from a web browser. -Restoring backups ------------------ +### Workaround to retrieve the backups + +
+ Since Yunohost version 3.3 and the choice to connect as the `admin` user, there is a [limitation](https://github.com/YunoHost/issues/issues/1266) that prevents straight access to the backups folder `/home/yunohost.backup/archives/` +
+ +Until the issue is solved, you will need to follow [a workaround](/backup_workaround) to manage the backup files. + +## Restoring backups ### From the webadmin diff --git a/backup_workaround.md b/backup_workaround.md new file mode 100644 index 00000000..b5784f4d --- /dev/null +++ b/backup_workaround.md @@ -0,0 +1,140 @@ +# Workaround to retrieve the backups + +As said on the [backup](/backup), there is a limitation to manage backups files with `admin` user + +## What is the problem + +Why you cannot access to `/home/yunohost.backup/archives/` folder + +```bash +root@example:~# tree /home/yunohost.backup/ +/home/yunohost.backup/ +├── archives ## <== Only `root` can access +│   ├── 20180611-192934.info.json +│   ├── 20180611-192934.tar.gz +│   ├── 20180915-212428.info.json +│   ├── 20180915-212428.tar.gz +│   ├── wallabag2-pre-upgrade1.info.json +│   └── wallabag2-pre-upgrade1.tar.gz +└── tmp ## <== `admin` can write here + ├── 20180915-212428.info.json + └── 20180915-212428.tar.gz + +2 directories, 8 files +root@example:~# +``` + +Until it is sorted, you have to work with `/home/yunohost.backup/tmp` and then copy/move to `home/yunohost.backup/archives` so Yunohost backup system can do it's work. + +## Download backups + +You will need to connect by `SSH` to copy the backups to a location that can be acceded by the `admin` user + +### SSH connection + +1. Connect by following [SSH instructions](/ssh#after-installing-yunohost) + + ```bash + ssh admin@192.168.1.68 + admin@192.168.1.68's password: + + The programs included with the Debian GNU/Linux system are free software; + the exact distribution terms for each program are described in the + individual files in /usr/share/doc/*/copyright. + + Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent + permitted by applicable law. + Last login: Sun Jan 6 19:30:47 2019 from 192.168.1.51 + ``` + +2. Verify if `admin` can access backups + + ```bash + admin@example:~$ ls -l /home/yunohost.backup/archives/ + ls: cannot open directory /home/yunohost.backup/archives/: Permission denied + ``` + +3. Run the same command again with `sudo` to list backups + + ```bash + admin@example:~$ sudo ls -l /home/yunohost.backup/archives/ + total 1168888 + -rw------- 1 admin 1007 3427 Jun 17 2018 20180611-192934.info.json + -rw------- 1 admin 1007 592976408 Jun 17 2018 20180611-192934.tar.gz + -rw-r--r-- 1 root root 1436 Sep 15 21:25 20180915-212428.info.json + -rw-r--r-- 1 root root 164731292 Sep 15 21:25 20180915-212428.tar.gz + -rw-r--r-- 1 root root 331 Dec 31 12:10 dokuwiki--2-pre-upgrade1.info.json + -rw-r--r-- 1 root root 23800 Dec 31 12:10 dokuwiki--2-pre-upgrade1.tar.gz + -rw-r--r-- 1 root root 348 Dec 31 12:10 dokuwiki--3-pre-upgrade2.info.json + -rw-r--r-- 1 root root 3710604 Dec 31 12:10 dokuwiki--3-pre-upgrade2.tar.gz + -rw-r--r-- 1 root root 344 Dec 31 12:08 dokuwiki-pre-upgrade2.info.json + -rw-r--r-- 1 root root 163209554 Dec 31 12:08 dokuwiki-pre-upgrade2.tar.gz + admin@example:~$ + ``` + + The most recent backup in this example is from `20180915-212428`. It is going to be copied to the right location + +4. Login as superuser `root` + + ```bash + admin@example:~$ sudo -i + ``` + +5. Copy the previous backups files to `/home/yunohost.backup/tmp` + + ```bash + root@example:~# cd /home/yunohost.backup + root@example:~# sudo cp -a archives/* tmp + ``` + +6. Verify that you have two files ``.info.json and ``.tar.gz in `/home/yunohost.backup/tmp` + + ```bash + root@example:~# ls /home/yunohost.backup/tmp + 20180915-212428.info.json 20180915-212428.tar.gz + ``` + +7. Quit SSH connection + + ```bash + root@example:~# exit + admin@example:~$ exit + ``` + +## Upload backups + +If you want to restore backup, the steps are quite similar to above. + +1. Connect by following [SSH instructions](/ssh#after-installing-yunohost) + +2. Login as superuser `root` + + ```bash + admin@example:~$ sudo -i + ``` + +3. Move your backup `` to `/home/yunohost.backup/archives` + + ```bash + root@example:~# cd /home/yunohost.backup + root@example:~# mv tmp/`*` archives/ + ``` + Yunohost backup mechanism can work do its work. + +4. Verify that you have two files ``.info.json and ``.tar.gz in `/home/yunohost.backup/archives` + + ```bash + root@example:~# ls /home/yunohost.backup/archives + 20180915-212428.info.json 20180915-212428.tar.gz + ``` + +5. Quit SSH connection + + ```bash + root@example:~# exit + admin@example:~$ exit + ``` + +## Back to work + +Now that the files are in the correct folders, you can continue your work with the [backups](backup). \ No newline at end of file From 811b1252be1dfcc803bfcb701e28477b42c1fd90 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Sat, 23 Mar 2019 18:38:51 +0100 Subject: [PATCH 3/4] This has been fixed so no workaround needed anymore... --- backup.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/backup.md b/backup.md index 6e4cbc34..e17327c0 100644 --- a/backup.md +++ b/backup.md @@ -83,14 +83,6 @@ Similarly, you can upload a backup from a machine to your server with: scp /path/to/your/.tar.gz admin@your.domain.tld:/home/yunohost.backup/archives/ ``` -### Workaround to retrieve the backups - -
- Since Yunohost version 3.3 and the choice to connect as the `admin` user, there is a [limitation](https://github.com/YunoHost/issues/issues/1266) that prevents straight access to the backups folder `/home/yunohost.backup/archives/` -
- -Until the issue is solved, you will need to follow [a workaround](/backup_workaround) to manage the backup files. - ## Restoring backups ### From the webadmin From 17f6737d0f6b8b270cc4db557968b9cf51792c13 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Sat, 23 Mar 2019 18:39:04 +0100 Subject: [PATCH 4/4] This has been fixed so no workaround needed anymore... --- backup_workaround.md | 140 ------------------------------------------- 1 file changed, 140 deletions(-) delete mode 100644 backup_workaround.md diff --git a/backup_workaround.md b/backup_workaround.md deleted file mode 100644 index b5784f4d..00000000 --- a/backup_workaround.md +++ /dev/null @@ -1,140 +0,0 @@ -# Workaround to retrieve the backups - -As said on the [backup](/backup), there is a limitation to manage backups files with `admin` user - -## What is the problem - -Why you cannot access to `/home/yunohost.backup/archives/` folder - -```bash -root@example:~# tree /home/yunohost.backup/ -/home/yunohost.backup/ -├── archives ## <== Only `root` can access -│   ├── 20180611-192934.info.json -│   ├── 20180611-192934.tar.gz -│   ├── 20180915-212428.info.json -│   ├── 20180915-212428.tar.gz -│   ├── wallabag2-pre-upgrade1.info.json -│   └── wallabag2-pre-upgrade1.tar.gz -└── tmp ## <== `admin` can write here - ├── 20180915-212428.info.json - └── 20180915-212428.tar.gz - -2 directories, 8 files -root@example:~# -``` - -Until it is sorted, you have to work with `/home/yunohost.backup/tmp` and then copy/move to `home/yunohost.backup/archives` so Yunohost backup system can do it's work. - -## Download backups - -You will need to connect by `SSH` to copy the backups to a location that can be acceded by the `admin` user - -### SSH connection - -1. Connect by following [SSH instructions](/ssh#after-installing-yunohost) - - ```bash - ssh admin@192.168.1.68 - admin@192.168.1.68's password: - - The programs included with the Debian GNU/Linux system are free software; - the exact distribution terms for each program are described in the - individual files in /usr/share/doc/*/copyright. - - Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent - permitted by applicable law. - Last login: Sun Jan 6 19:30:47 2019 from 192.168.1.51 - ``` - -2. Verify if `admin` can access backups - - ```bash - admin@example:~$ ls -l /home/yunohost.backup/archives/ - ls: cannot open directory /home/yunohost.backup/archives/: Permission denied - ``` - -3. Run the same command again with `sudo` to list backups - - ```bash - admin@example:~$ sudo ls -l /home/yunohost.backup/archives/ - total 1168888 - -rw------- 1 admin 1007 3427 Jun 17 2018 20180611-192934.info.json - -rw------- 1 admin 1007 592976408 Jun 17 2018 20180611-192934.tar.gz - -rw-r--r-- 1 root root 1436 Sep 15 21:25 20180915-212428.info.json - -rw-r--r-- 1 root root 164731292 Sep 15 21:25 20180915-212428.tar.gz - -rw-r--r-- 1 root root 331 Dec 31 12:10 dokuwiki--2-pre-upgrade1.info.json - -rw-r--r-- 1 root root 23800 Dec 31 12:10 dokuwiki--2-pre-upgrade1.tar.gz - -rw-r--r-- 1 root root 348 Dec 31 12:10 dokuwiki--3-pre-upgrade2.info.json - -rw-r--r-- 1 root root 3710604 Dec 31 12:10 dokuwiki--3-pre-upgrade2.tar.gz - -rw-r--r-- 1 root root 344 Dec 31 12:08 dokuwiki-pre-upgrade2.info.json - -rw-r--r-- 1 root root 163209554 Dec 31 12:08 dokuwiki-pre-upgrade2.tar.gz - admin@example:~$ - ``` - - The most recent backup in this example is from `20180915-212428`. It is going to be copied to the right location - -4. Login as superuser `root` - - ```bash - admin@example:~$ sudo -i - ``` - -5. Copy the previous backups files to `/home/yunohost.backup/tmp` - - ```bash - root@example:~# cd /home/yunohost.backup - root@example:~# sudo cp -a archives/* tmp - ``` - -6. Verify that you have two files ``.info.json and ``.tar.gz in `/home/yunohost.backup/tmp` - - ```bash - root@example:~# ls /home/yunohost.backup/tmp - 20180915-212428.info.json 20180915-212428.tar.gz - ``` - -7. Quit SSH connection - - ```bash - root@example:~# exit - admin@example:~$ exit - ``` - -## Upload backups - -If you want to restore backup, the steps are quite similar to above. - -1. Connect by following [SSH instructions](/ssh#after-installing-yunohost) - -2. Login as superuser `root` - - ```bash - admin@example:~$ sudo -i - ``` - -3. Move your backup `` to `/home/yunohost.backup/archives` - - ```bash - root@example:~# cd /home/yunohost.backup - root@example:~# mv tmp/`*` archives/ - ``` - Yunohost backup mechanism can work do its work. - -4. Verify that you have two files ``.info.json and ``.tar.gz in `/home/yunohost.backup/archives` - - ```bash - root@example:~# ls /home/yunohost.backup/archives - 20180915-212428.info.json 20180915-212428.tar.gz - ``` - -5. Quit SSH connection - - ```bash - root@example:~# exit - admin@example:~$ exit - ``` - -## Back to work - -Now that the files are in the correct folders, you can continue your work with the [backups](backup). \ No newline at end of file