YunoHost-Apps/borg_ynh
1
0
Fork 0
mirror of https://github.com/YunoHost-Apps/borg_ynh.git synced 2024-09-03 18:16:05 +02:00
Code Issues Activity Actions

Rework ADMIN.md, misc wording etc

Browse source
This commit is contained in:
Alexandre Aubin 2024-05-03 15:43:33 +02:00
parent ea3f6e3492
commit c3e5353d39
5 changed files with 50 additions and 144 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
config_panel.toml
View file

@ -3,14 +3,14 @@ version = "1.0"
[main]
services = []
[main.settings]
[main.state]
name = ""
visible = "false"
[main.settings.state]
[main.state.state]
type = "string"
[main.settings.last_run]
[main.state.last_run]
type = "string"
[main.general]
@ -25,7 +25,7 @@ services = []
[main.general.repository]
ask.en = "Repository"
type = "string"
help = "Specify a local repository like /mount/my_external_harddrive/backups or a remote repository using this format: ssh://USER@DOMAIN.TLD:PORT/~/backup . If you plan to use borgserver_ynh app : 'USER' is *not* meant to be an existing user on the guest server, instead, it will be created *on the host server* during the installation of the Borg Server App. With borgserver_ynh apps you can't specify another repo path than ~/backup."
help = "Specify a local repository (`/mount/my_external_harddrive/backups`) or a remote repository (`ssh://USER@DOMAIN.TLD:PORT/~/backup`). If you plan to use a remote borgserver_ynh app : `USER` is *not* meant to be an existing user on the guest server, instead, it will be created *on the host server* during the installation of the Borg Server App. With borgserver_ynh apps you can't specify another repo path than `~/backup`."
[main.general.ssh_public_key]
ask.en = "Public key: {ssh_public_key}"
@ -33,9 +33,10 @@ services = []
bind = "/root/.ssh/id___APP___ed25519.pub"
[main.general.on_calendar]
ask.en = "Frequency"
ask.en = "When at at which frequency should the backups be performed?"
ask.fr = "Quand et à quelle fréquence les sauvegardes doivent-elles être effectuées ?"
type = "string"
help = "With which regular time schedule should the backups be performed? (see systemd OnCalendar format)"
help = "For example: `Monthly`, `Weekly`, `Daily` (=every day at midnight), `Hourly`, `Sat *-*-1..7 18:00:00` (=the first saturday of every month at 18:00), `4:00` (=every day at 4 AM), `5,17:00` (=every day at 5 AM and 5 PM). See the [systemd OnCalendar format for full syntax doc](https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer)"
bind = "OnCalendar:/etc/systemd/system/__APP__.timer"
[main.general.mailalert]
@ -47,7 +48,7 @@ services = []
help = "Alerts are sent to the first user of this server"
[main.content]
name = "What should be backuped ?"
name = "What should be backuped?"
optional = false
[main.content.conf]
@ -67,11 +68,11 @@ services = []
type = "tags"
help = "App list separated by comma. You can write 'all' to select all apps, even those installed after this borg app. You can also select all apps but some apps by writing 'exclude:' following by an app list separated by comma."
[advanced]
name = "Advanced"
[list]
name = "Last backups list"
services = []
[advanced.list]
name = "Last backups list"
[advanced.list.last_backups]
[list.list]
name = ""
[list.list.last_backups]
ask.en = ""
type = "markdown"

127
doc/ADMIN.md
View file

@ -1,95 +1,14 @@
## :warning: NB. : This doc is partially obsolete and should be reworked! :warning:
## How to backup your server with this app?
You want to backup a critical "guest" Server A onto a remote "host" Server B, you need:
* Domain name of server B: `host.serverb`
* Name of the server B SSH user (to be created by `borgserver`) for connection from Server A: `borgservera`
* **Strong passphrase** to encrypt your backups on host Server B. And to **restore your backups**!!
* IDs of YunoHost apps you want to backup
* Regular time schedule for your backups, see below
* Install Borg Backup App (`borg`) on guest Server A
* Install Borg Server App (`borgserver`) on host Server B
* Save the passphrase in another place than your server. Without the passphrase, you won't be able to restore data.
You should received an email after the first backup succeeded.
### Set up Borg Backup App on guest Server A
Firstly, set up the Borg Backup App (`borg`) on the guest Server A you want to backup:
```bash
$ yunohost app install borg
In which borg repository location do you want to backup your files ?: user@host.serverb:/remote/repository
Provide a strong passphrase to encrypt your backups. No blank space:
Should Borg backup your YunoHost configuration? [yes | no] (default: yes):
Should Borg backup emails and user home directory? [yes | no] (default: yes):
Which apps should Borg backup ? (default: all):
With which regular time schedule should the backups be performed? (see systemd OnCalendar format) (default: Daily):
Do you want admin to receive mail notifications on backups ? [always | errors_only | never]: never
```
#### Syntax to define a backup time schedule
You can schedule regular backups at specific time. Only one regular time schedule is possible for one `borg` instance, see below for workaround. Some examples:
* Monthly :
* Weekly :
* Daily : Daily at midnight
* Hourly : Hourly o Clock
* Sat *-*-1..7 18:00:00 : The first saturday of every month at 18:00
* 4:00 : Every day at 4 AM
* 5,17:00 : Every day at 5 AM and at 5 PM
See here for more info : <https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer>
#### Information generated by Borg Backup
At the end of the installation, the Borg Backup App (``borg``) displays the SSH public key and the SSH user to give to the person who has access to the host Server B and will set up Borg Server App.
```text
You should now install the "Borg Server" app on host.serverb and fill questions like this:
User: servera
Public key: ssh-ed25519 AAAA[...] root@guest.servera
```
This information is also sent by email to the admin of guest Server A.
If you don't find the email and you don't see the message in the log bar you can find the SSH public key with this command:
```bash
$ cat /root/.ssh/id_borg_ed25519.pub
ssh-ed25519 AAAA[...] root@guest.servera
```
### Set up Borg Server App on host Server B
Secondly, set up the Borg Server App (``borgserver``) on the host Server B that will store your backups:
```bash
$ yunohost app install borgserver
Indicate the ssh user to create: servera
Indicate the public key given by Borg Backup app (borg) setup: ssh-ed25519 AAAA[...] root@guest.servera
Indicate the storage quota: 5G
```
### Test the Borg Apps setup
## Testing that backup work as expected
At this step your backup should run at the scheduled time. Note that the first backup can take very long, as much data has to be copied through ssh. Following backups are incremental: only newly generated data since last backup will be copied.
If you want to test correct Borg Apps setup before scheduled time, you can start a backup manually on guest Server A:
If you want to test correct Borg Apps setup before scheduled time, you can start a backup manually from the command line:
```bash
systemctl start borg
```
Next you can check presence of your backup repository on host Server B:
```bash
BORG_RSH="ssh -i /root/.ssh/id_borg_ed25519 -oStrictHostKeyChecking=yes " borg list servera@host.serverb:~/backup
```
You will need the passphrase to run ``borg`` commands on the backup repository created on the host Server B.
Once the backup completes, you can check that a backup is listed in the webadmin > Applications > Borg > 'Last backups list'.
## Check regularly your backup
@ -108,6 +27,9 @@ borg list ./::ARCHIVE_NAME | grep dump.sql
* Be sure to have your passphrase available even if your server is completely broken
## How to restore a complete system
*For infos on restoring process, check [this yunohost forum thread](https://forum.yunohost.org/t/restoring-whole-yunohost-from-borg-backups/12705/3) and [that one](https://forum.yunohost.org/t/how-to-properly-backup-and-restore/12583/3), also [using Borg with sshkeys](https://thisiscasperslife.wordpress.com/2017/11/28/using-borg-backup-across-ssh-with-sshkeys/), the [`borg extract` documentation](https://borgbackup.readthedocs.io/en/stable/usage/extract.html), and this [general tutorial on Borg Backup](https://practical-admin.com/blog/backups-using-borg/).*
@ -122,11 +44,11 @@ In the following explanations:
### Overview
The idea here, if you need to restore a whole yunohost system is:
If you need to restore a whole yunohost system:
1. Install a new Debian VM
2. Install YunoHost in it the usual way
3. Go through YunoHost postinstall (parameters you will supply are not crucial, as they will be replaced by the restore)
1. Setup a new Debian system
2. Install YunoHost the usual way
3. Go through YunoHost's postinstall (parameters you will supply are not crucial, as they will be replaced by the restore)
4. Install Borg
5. Setup `rem` to accept ssh connections from `yuno`
6. Use Borg to import backups from `rem` to `yuno`
@ -216,32 +138,3 @@ For that, remove the "dummy" Borg you installed to do the restoration, and resto
sudo yunohost app remove borg
sudo yunohost backup restore auto_borg_XX_XX_XX_XX:XX --apps
```
## Tips
### Edit the list of YunoHost apps to backup
`yunohost app setting borg apps -v "nextcloud,wordpress"`
### Other usefull borg commands
[Get the storage space used by the backup repository on the host server](https://borgbackup.readthedocs.io/en/stable/usage/info.html)
`borg info /home/servera/backup`
### Backup YunoHost apps with different criticallity levels
If you want to backup your guest server:
* with different YunoHost apps
* at different regular time schedule
* on different host servers
Then you can set up multiple instances of the Borg Apps on same servers.
For instance:
* Borg Backup instance ``borg``: backup nextcloud daily on host Server B
* Borg Backup instance ``borg__2``: backup all other YunoHost apps weekly on host Server C
### Settings location
Settings of apps are in /etc/yunohost/apps/*/settings.yml, so are the settings for borg_ynh as well. Be careful though to not savagely manually edit them if you don't know what you're doing.

17
doc/DESCRIPTION.md
View file

@ -1,3 +1,16 @@
A [Borg](https://borgbackup.readthedocs.io/en/stable/index.html#what-is-borgbackup) implementation to backup a YunoHost server.
A [Borg](https://borgbackup.readthedocs.io/en/stable/index.html#what-is-borgbackup) integration to backup your YunoHost server to another remote server (e.g. one of your friends).
This is the Borg Backup App to be installed on a server to backup. It works together with a [Borg Server App](https://github.com/YunoHost-Apps/borgserver_ynh) installed on a host server.
It works This is the Borg Backup App to be installed on a server to backup. It works in combination with the [Borg Server App](https://apps.yunohost.org/app/borgserver) installed on a host server.
### Features
- Backup on a remote machine, in comination with the [borg server app](https://apps.yunohost.org/app/borgserver)
- ... or on a [commercial borg service](https://www.borgbackup.org/support/commercial.html)
- Backups are encrypted (the remote server can't read the content) and deduplicated (optimize space)
- Backups are ran automatically, you can choose when and at which frequency
- You can choose what apps are backuped
- Receive email alerts if the backup fails (the [borg server app](https://apps.yunohost.org/app/borgserver) also checks that new content arrives and send an email to your friend otherwise)
### Install procedure
Maybe counter-intuitively, you should *first* install this app (`borg_ynh`) and *then* (`borgserver_ynh`) on the other machine. In fact, after the install of `borg_ynh`, a message should be displayed with the info, in particular the SSH public key, to be used to setup `borgserver_ynh` on the other machine.

2
doc/POST_INSTALL.md
View file

@ -9,4 +9,4 @@ Or if you want to use command-line:
`yunohost app install https://github.com/YunoHost-Apps/borgserver_ynh -a "ssh_user=__SSH_USER__&public_key=__PUBLIC_KEY__"`
If you facing an issue or want to improve this app, please open a new issue in this project: <https://github.com/YunoHost-Apps/borg_ynh>
NB: the SSH user is not meant to pre-exist on the server on which borgserver is installed!

23
manifest.toml
View file

@ -31,15 +31,15 @@ ram.runtime = "50M"
[install.repository]
ask.en = "In which borg repository location do you want to backup your files ?"
ask.fr = "Dans quel repo borg souhaitez-vous sauvegarder vos fichiers ?"
help.en = "Specify a local repository like /mount/my_external_harddrive/backups or a remote repository using this format: ssh://USER@DOMAIN.TLD:PORT/~/backup . If you plan to use borgserver_ynh app : 'USER' is *not* meant to be an existing user on the guest server, instead, it will be created *on the host server* during the installation of the Borg Server App. With borgserver_ynh apps you can't specify another repo path than ~/backup."
help.en = "Specify a local repository (`/mount/my_external_harddrive/backups`) or a remote repository (`ssh://USER@DOMAIN.TLD:PORT/~/backup`). If you plan to use a remote borgserver_ynh app : `USER` is *not* meant to be an existing user on the guest server, instead, it will be created *on the host server* during the installation of the Borg Server App. With borgserver_ynh apps you can't specify another repo path than `~/backup`."
type = "string"
example = "ssh://john@serverb.tld:22/~/backup"
[install.passphrase]
ask.en = "Provide a strong passphrase to encrypt your backups. No blank space"
ask.fr = "Indiquez une phrase de passe forte pour chiffrer vos sauvegardes. Sans espaces"
help.en = "Keep it safe! ...if you want to be able to restore. Do not communicate it to host Server holder or anyone else."
help.fr = "Gardez-la précieusement! ...si vous voulez pouvoir restaurer. Ne donnez pas la clé au possesseur du Serveur distant, ni personne."
help.en = "Keep it safe! There will be **no way** to restore your backup if you lose it. Do not communicate it to the remote host server holder, or anyone else."
help.fr = "Gardez-la précieusement ! Il sera impossible de restaurer vos sauvegardes sans celle-ci. Ne donnez pas cette clé à la personne qui gère le serveur distant - où à n'importe qui d'ailleurs."
type = "password"
[install.conf]
@ -49,8 +49,8 @@ ram.runtime = "50M"
default = true
[install.data]
ask.en = "Should Borg backup emails and user home directory?"
ask.fr = "Borg doit-il sauvegarder les mails et les répertoires des utilisateurs ?"
ask.en = "Should Borg backup emails and user home directories?"
ask.fr = "Borg doit-il sauvegarder les mails et les répertoires (home) des utilisateurs ?"
type = "boolean"
default = true
@ -63,10 +63,10 @@ ram.runtime = "50M"
default = "all"
[install.on_calendar]
ask.en = "With which regular time schedule should the backups be performed? (see systemd OnCalendar format)"
ask.fr = "À quelle fréquence les sauvegardes doivent-elles être effectuées ? (voir le format OnCalendar de systemd)"
ask.en = "When at at which frequency should the backups be performed?"
ask.fr = "Quand et à quelle fréquence les sauvegardes doivent-elles être effectuées ?"
type = "string"
example = "Monthly or Weekly or Daily or Hourly or 4:00 or 5,17:00 or Sat --1..7 18:00:00"
help = "For example: `Monthly`, `Weekly`, `Daily` (=every day at midnight), `Hourly`, `Sat *-*-1..7 18:00:00` (=the first saturday of every month at 18:00), `4:00` (=every day at 4 AM), `5,17:00` (=every day at 5 AM and 5 PM). See the [systemd OnCalendar format for full syntax doc](https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer)"
default = "Daily"
[install.mailalert]
@ -85,13 +85,12 @@ ram.runtime = "50M"
packages = [
"python3-pip",
"python3-dev",
"libacl1-dev",
"libssl-dev",
"liblz4-dev",
"python3-jinja2",
"python3-setuptools",
"python3-venv",
"virtualenv",
"libacl1-dev",
"libssl-dev",
"liblz4-dev",
"libfuse3-dev",
"pkg-config",
]