From 81c2a43128cd10522f636b02d0ea4d899e4cff83 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Mon, 8 Apr 2024 12:52:51 +0200 Subject: [PATCH 1/8] add specification --- Specification.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 Specification.md diff --git a/Specification.md b/Specification.md new file mode 100644 index 0000000..4a017f7 --- /dev/null +++ b/Specification.md @@ -0,0 +1,118 @@ +# Specification + +## Summary + +Creating automated backups of docker swarm services is an often needed task. This specification describes how backups can be configured via [service labels](https://docs.docker.com/compose/compose-file/compose-file-v3/#labels-1) in a standardised way. + +## Requirements + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119]. + +When backing up a docker stack you MUST first check if the `backupbot.backup`. It MUST be set to true, for the backup to happen. + +## Backup + +To enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service. +A `backupbot.backup.pre-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before backup up files. +By default all volumes MUST be backed up. A volume MAY be excluded from backing up when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume. +By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get seperated by a comma. +A `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service after backing up all files. +A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. + +## Restore + +A `backupbot.restore.pre-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before restoring backup files. +By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. +A `backupbot.restore.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service after restoring backup files. + +## Labels + +### `backupbot.backup` + +**Type:** boolean +**Default:** false +**Description:** +Enables backupbot for this compose stack. The labe should be added to the main service of the compose stack. + +**Example:** + +``` +backupbot.backup: true +``` + +### `backupbot.backup.volumes.{volume_name}` + +**Type:** boolean +**Default:** true +**Description:** When set to false the volume is excluded from backups. + +**Example:** + +``` +backupbot.backup.volumes.{volume_name}: false +``` + +### `backupbot.backup.volumes.{volume_name}.path` + +**Type:** string +**Default:** "" +**Description:** +A comma seperated list of paths. When one or more paths are set, it only backups up those on the given volume instead of the whole volume. + +**Example:** + +``` +backupbot.backup.volumes.{volume_name}.path: '/var/lib/mariadb/dump.sql.gz' +``` + +### `backupbot.backup.pre-hook` + +**Type:** string +**Default:** "" +**Description:** +A command, that gets executed before the files are backed up. + +**Example:** + +``` +backupbot.backup.pre-hook: 'mysqldump -u root -p"$(cat /run/secrets/db_root_password)" -f /volume_path/dump.db' +``` + +### `backupbot.backup.post-hook` + +**Type:** string +**Default:** "" +**Description:** +A command, that gets executed after the files are backuped. + +**Example:** + +``` +backupbot.backup.post-hook: "rm -rf /volume_path/dump.db" +``` + +### `backupbot.restore.pre-hook` + +**Type:** string +**Default:** "" +**Description:** +A command, that gets executed before the files are restored. + +**Example:** + +``` +backupbot.restore.pre-hook: "lock db" +``` + +### `backupbot.restore.post-hook` + +**Type:** string +**Default:** "" +**Description:** +A command, that gets executed after the files are restored. + +**Example:** + +``` +backupbot.restore.post-hook: "sqldump dump.sql && unlock db && rm dump.sql" +``` -- 2.47.2 From a2ecb767aabbf56d8dc32240ba2ed222e3a13cd2 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Mon, 8 Apr 2024 13:23:50 +0200 Subject: [PATCH 2/8] more words --- Specification.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/Specification.md b/Specification.md index 4a017f7..d3f7a7d 100644 --- a/Specification.md +++ b/Specification.md @@ -13,17 +13,30 @@ When backing up a docker stack you MUST first check if the `backupbot.backup`. I ## Backup To enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service. -A `backupbot.backup.pre-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before backup up files. -By default all volumes MUST be backed up. A volume MAY be excluded from backing up when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume. + +### Volumes and paths + +By default all volumes MUST be backed up. A volume MAY be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume. By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get seperated by a comma. -A `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service after backing up all files. -A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. + +### Pre/Post Hooks + +A `backupbot.backup.pre-hook` and `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after backing up files. +The command MUST have access to all environment variables inside the container. +There is no guaranteed order in which different hooks MUST be executed. + +### Output + +A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{volume_name}`, where `{volume_name}` is the name of each volume that got backed up. ## Restore -A `backupbot.restore.pre-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before restoring backup files. -By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. -A `backupbot.restore.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service after restoring backup files. +By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. When restoring a backup from a `.tar.gz` it expects the directory layout as described int the [backup output](#output) section. + +### Pre/Post Hooks + +A `backupbot.restore.pre-hook` and `backupbot.restore.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after restoring the files. +There is no guaranteed order in which different hooks MUST be executed. ## Labels @@ -97,6 +110,7 @@ backupbot.backup.post-hook: "rm -rf /volume_path/dump.db" **Default:** "" **Description:** A command, that gets executed before the files are restored. +Note, that there is no guaranteed order in which multiple hooks get executed. **Example:** -- 2.47.2 From e95dd23504d11915480213362e2dcb01ca032a52 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Mon, 8 Apr 2024 17:20:03 +0200 Subject: [PATCH 3/8] add maintainers docs --- Maintainers.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++ Specification.md | 1 - 2 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 Maintainers.md diff --git a/Maintainers.md b/Maintainers.md new file mode 100644 index 0000000..042157a --- /dev/null +++ b/Maintainers.md @@ -0,0 +1,154 @@ +# For Maintainers + +From the perspective of the recipe maintainer, backup/restore is just more +`deploy: ...` labels. Tools can read these labels and then perform the +backup/restore logic. + +## Tools + +Two of the current "blessed" options are, which both implement the [backupbot specification](link to spec) +- [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) +- [`abra`](https://git.coopcloud.tech/coop-cloud/abra) + +### `backup-bot-two` + +`backup-bot-two` is a recipe which gets deployed on the server, it can perform automatic backups. +Please see the [`README.md`](https://git.coopcloud.tech/coop-cloud/backup-bot-two#backupbot-ii) for the full docs. + +### `abra` + +`abra` will read labels and store backups in `~/.abra/backups/...` . +It also provides an integration for `backup-bot-two`. + +## Backup + +### How to Configure backups + +Unless otherwise stated all labels should be added to the main service (which should be named `app`). + +1. Enable backups for the recipe: +You need to enable backups for the recipe by adding the following label: +``` +backupbot.backup=true +``` + +2. Decide wich volumes should be backed up: +By default all volumes will be backed up. To disable a certain volume you can add the following label: +``` +backupbot.backup.volumes.{volume_name}=false +``` + +3. Decide which path should be backed up on each volume +By default all files get backed up for a volume. To only include certain paths you can add the following label: +``` +backupbot.backup.volumes.{volume_name}.path=/mypath1/foo,/mypath2/bar +``` + +Note: You can include multiple paths by providing a comma seperated list +Note: All paths are specified relativ to the volume root + +4. Run commands before the backup +For certain services like a database it is not reccomend to just backup files, because the backup might end up in a corrupted state. Instead it is reccomended to make a database dump. You can run arbitrary commands in any container before the files are backed up. +To do this add the following label to the service on which you want the command being run: +``` +backupbot.backup.pre-hook=mysqldump -u root -pghost ghost --tab /var/lib/foo +``` + +5. Run commands after the backup +Sometimes you want to clean up after the backup. You can run arbitrary commands in any container after the files were backed up. +To do this add the following label to the service on which you want the command being run: +``` +backupbot.backup.post-hook=rm -rf /var/lib/mysql-files/* +``` + +### Testing the backup + +To test that your backup is configured correctly you can deploy the recipe you are working on in a test app either [locally](link to local server deployment) or on a test server. + +After the deployment is succesfull run the backup and inspect its content + +``` +abra app backup myrecipe.example.com +tar -tf ~/.abra/backups/mybackup +``` + +## Restore + +When restoring an app, it takes the files from a backup and copies them to their correct location. +In the case of restoring database tables, you can use the `pre-hook` & `post-hook` commands to run the insertion logic. + +## Pre and Post hooks + +To back up some services correctly it involves more than just copying a few files from one location to another. Some services already have specific backup tools that allow taking a coherent snapshot of its data like `mysqldump`. +The pre and post hooks can be used to prepare the files which should get backed up and clean up afterwards. + +Here are some examples: + +### Example 1: Execute simple command +``` +backupbot.backup.pre-hook: "echo 'foo' > /path/to/volume/bar.txt +``` + +### Example 2: Access environment variable +``` +backupbot.backup.pre-hook: "cat $${POSTGRES_PASSWORD_FILE}" +``` + +### Example 3: Access secret +``` +backupbot.backup.pre-hook: "cat /var/run/secrets/mysupersecret" +``` + +``` +backupbot.backup.pre-hook: 'mysqldump -p"$$(cat /run/secrets/mysupersecret)" mydatabase' +``` + +### Example 4: Complex script +Sometimes the logic to backup up a service can get quite complex. In that case it might be easier to add a script (via mount or config) inside the container and call that from the pre and post hook: +``` +backupbot.backup.pre-hook: "/scripts/my-pre-backup-scripts" +backupbot.backup.post-hook: "/scripts/my-post-backup-scripts" +``` + +## Configuration Examples + +### Mariadb + +``` +services: + db: + image: mariadb + volumes: + - "mariadb:/var/lib/mysql" + deploy: + labels: + backupbot.backup: "true" + backupbot.backup.pre-hook: "sh -c 'mariadb-dump --single-transaction -u root -p\"$$(cat /run/secrets/db_root_password)\" wordpress | gzip > /var/lib/mysql/dump.sql.gz'" + backupbot.backup.volume.mariadb.path: "dump.sql.gz" + backupbot.backup.post-hook: "rm -f /var/lib/mysql/dump.sql.gz" + backupbot.restore: "true" + backupbot.restore.post-hook: "sh -c 'gzip -d /var/lib/mysql/dump.sql.gz && mariadb -u root -p\"$$(cat /run/secrets/db_root_password)\" wordpress < /var/lib/mysql/dump.sql && rm -f /var/lib/mysql/dump.sql'" +``` + +### Postgres + +``` +version: '3.8' + +services: + db: + image: "postgres" + volumes: + - "postgres:/var/lib/postgresql/data" + secrets: + - db_password + deploy: + labels: + backupbot.backup: "true" + backupbot.backup.pre-hook: "PGPASSWORD=$$(cat $${POSTGRES_PASSWORD_FILE}) pg_dump -U $${POSTGRES_USER} $${POSTGRES_DB} > /var/lib/postgresql/data/backup.sql" + backupbot.backup.post-hook: "rm -rf /var/lib/postgresql/data/backup.sql" + backupbot.backup.volume.postgres.path: "backup.sql" + +volumes: + postgres: +``` diff --git a/Specification.md b/Specification.md index d3f7a7d..1975854 100644 --- a/Specification.md +++ b/Specification.md @@ -22,7 +22,6 @@ By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{v ### Pre/Post Hooks A `backupbot.backup.pre-hook` and `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after backing up files. -The command MUST have access to all environment variables inside the container. There is no guaranteed order in which different hooks MUST be executed. ### Output -- 2.47.2 From 15545b10ec2b40e868dd750afa8adfc9271dd716 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Sun, 14 Apr 2024 12:29:47 +0200 Subject: [PATCH 4/8] review --- Specification.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Specification.md b/Specification.md index 1975854..7888df4 100644 --- a/Specification.md +++ b/Specification.md @@ -6,9 +6,7 @@ Creating automated backups of docker swarm services is an often needed task. Thi ## Requirements -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119]. - -When backing up a docker stack you MUST first check if the `backupbot.backup`. It MUST be set to true, for the backup to happen. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119). ## Backup @@ -16,8 +14,8 @@ To enable backups for a docker stack, the `backupbot.backup=true` label MUST be ### Volumes and paths -By default all volumes MUST be backed up. A volume MAY be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume. -By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get seperated by a comma. +By default all volumes MUST be backed up. A volume MUST be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume. +By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get separated by a comma. ### Pre/Post Hooks @@ -44,7 +42,7 @@ There is no guaranteed order in which different hooks MUST be executed. **Type:** boolean **Default:** false **Description:** -Enables backupbot for this compose stack. The labe should be added to the main service of the compose stack. +Enables backups for this compose stack. The label should be added to the main service of the compose stack. **Example:** @@ -69,7 +67,7 @@ backupbot.backup.volumes.{volume_name}: false **Type:** string **Default:** "" **Description:** -A comma seperated list of paths. When one or more paths are set, it only backups up those on the given volume instead of the whole volume. +A comma seperated list of paths. When one or more paths are set, it only backs up those on the given volume instead of the whole volume. **Example:** @@ -95,7 +93,7 @@ backupbot.backup.pre-hook: 'mysqldump -u root -p"$(cat /run/secrets/db_root_pass **Type:** string **Default:** "" **Description:** -A command, that gets executed after the files are backuped. +A command, that gets executed after the files are backed up. **Example:** -- 2.47.2 From 9b90b76fd05c6e03875cb71b7feda0123fc993b0 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Wed, 17 Apr 2024 14:42:23 +0200 Subject: [PATCH 5/8] maintainers guide --- Maintainers.md | 1 - 1 file changed, 1 deletion(-) diff --git a/Maintainers.md b/Maintainers.md index 042157a..a90655e 100644 --- a/Maintainers.md +++ b/Maintainers.md @@ -126,7 +126,6 @@ services: backupbot.backup.pre-hook: "sh -c 'mariadb-dump --single-transaction -u root -p\"$$(cat /run/secrets/db_root_password)\" wordpress | gzip > /var/lib/mysql/dump.sql.gz'" backupbot.backup.volume.mariadb.path: "dump.sql.gz" backupbot.backup.post-hook: "rm -f /var/lib/mysql/dump.sql.gz" - backupbot.restore: "true" backupbot.restore.post-hook: "sh -c 'gzip -d /var/lib/mysql/dump.sql.gz && mariadb -u root -p\"$$(cat /run/secrets/db_root_password)\" wordpress < /var/lib/mysql/dump.sql && rm -f /var/lib/mysql/dump.sql'" ``` -- 2.47.2 From e7f979c6fad64669086a86b3b811b4f6aef1c5bc Mon Sep 17 00:00:00 2001 From: p4u1 Date: Wed, 17 Apr 2024 14:49:12 +0200 Subject: [PATCH 6/8] update --- Maintainers.md | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/Maintainers.md b/Maintainers.md index a90655e..e1e151e 100644 --- a/Maintainers.md +++ b/Maintainers.md @@ -7,12 +7,13 @@ backup/restore logic. ## Tools Two of the current "blessed" options are, which both implement the [backupbot specification](link to spec) + - [`backup-bot-two`](https://git.coopcloud.tech/coop-cloud/backup-bot-two) - [`abra`](https://git.coopcloud.tech/coop-cloud/abra) ### `backup-bot-two` -`backup-bot-two` is a recipe which gets deployed on the server, it can perform automatic backups. +`backup-bot-two` is a recipe which gets deployed on the server, it can perform automatic backups and uses restic. Please see the [`README.md`](https://git.coopcloud.tech/coop-cloud/backup-bot-two#backupbot-ii) for the full docs. ### `abra` @@ -27,19 +28,22 @@ It also provides an integration for `backup-bot-two`. Unless otherwise stated all labels should be added to the main service (which should be named `app`). 1. Enable backups for the recipe: -You need to enable backups for the recipe by adding the following label: + You need to enable backups for the recipe by adding the following deploy label: + ``` backupbot.backup=true ``` 2. Decide wich volumes should be backed up: -By default all volumes will be backed up. To disable a certain volume you can add the following label: + By default all volumes will be backed up. To disable a certain volume you can add the following deploy label: + ``` backupbot.backup.volumes.{volume_name}=false ``` 3. Decide which path should be backed up on each volume -By default all files get backed up for a volume. To only include certain paths you can add the following label: + By default all files get backed up for a volume. To only include certain paths you can add the following deploy label: + ``` backupbot.backup.volumes.{volume_name}.path=/mypath1/foo,/mypath2/bar ``` @@ -48,15 +52,17 @@ Note: You can include multiple paths by providing a comma seperated list Note: All paths are specified relativ to the volume root 4. Run commands before the backup -For certain services like a database it is not reccomend to just backup files, because the backup might end up in a corrupted state. Instead it is reccomended to make a database dump. You can run arbitrary commands in any container before the files are backed up. -To do this add the following label to the service on which you want the command being run: + For certain services like a database it is not reccomend to just backup files, because the backup might end up in a corrupted state. Instead it is reccomended to make a database dump. You can run arbitrary commands in any container before the files are backed up. + To do this add the following deploy label to the service on which you want the command being run: + ``` backupbot.backup.pre-hook=mysqldump -u root -pghost ghost --tab /var/lib/foo ``` 5. Run commands after the backup -Sometimes you want to clean up after the backup. You can run arbitrary commands in any container after the files were backed up. -To do this add the following label to the service on which you want the command being run: + Sometimes you want to clean up after the backup. You can run arbitrary commands in any container after the files were backed up. + To do this add the following deploy label to the service on which you want the command being run: + ``` backupbot.backup.post-hook=rm -rf /var/lib/mysql-files/* ``` @@ -72,6 +78,8 @@ abra app backup myrecipe.example.com tar -tf ~/.abra/backups/mybackup ``` +TODO: this is not complete yet + ## Restore When restoring an app, it takes the files from a backup and copies them to their correct location. @@ -85,16 +93,19 @@ The pre and post hooks can be used to prepare the files which should get backed Here are some examples: ### Example 1: Execute simple command + ``` backupbot.backup.pre-hook: "echo 'foo' > /path/to/volume/bar.txt ``` ### Example 2: Access environment variable + ``` backupbot.backup.pre-hook: "cat $${POSTGRES_PASSWORD_FILE}" ``` ### Example 3: Access secret + ``` backupbot.backup.pre-hook: "cat /var/run/secrets/mysupersecret" ``` @@ -104,7 +115,9 @@ backupbot.backup.pre-hook: 'mysqldump -p"$$(cat /run/secrets/mysupersecret)" myd ``` ### Example 4: Complex script + Sometimes the logic to backup up a service can get quite complex. In that case it might be easier to add a script (via mount or config) inside the container and call that from the pre and post hook: + ``` backupbot.backup.pre-hook: "/scripts/my-pre-backup-scripts" backupbot.backup.post-hook: "/scripts/my-post-backup-scripts" -- 2.47.2 From 1d054aa2e812e0ccf1679377134859cbb434e1e5 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Wed, 17 Apr 2024 14:59:24 +0200 Subject: [PATCH 7/8] . --- Specification.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/Specification.md b/Specification.md index 7888df4..1be0160 100644 --- a/Specification.md +++ b/Specification.md @@ -10,7 +10,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## Backup -To enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service. +To enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service. The label MUST be only set once. When the label is set multiple times, the implementation SHOULD show an error. ### Volumes and paths @@ -22,6 +22,8 @@ By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{v A `backupbot.backup.pre-hook` and `backupbot.backup.post-hook` MAY be set on a service. When set the command MUST be executed inside the running container of the service before/after backing up files. There is no guaranteed order in which different hooks MUST be executed. +TODO: escaping + ### Output A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{volume_name}`, where `{volume_name}` is the name of each volume that got backed up. @@ -69,12 +71,17 @@ backupbot.backup.volumes.{volume_name}: false **Description:** A comma seperated list of paths. When one or more paths are set, it only backs up those on the given volume instead of the whole volume. -**Example:** +**Example 1:** ``` backupbot.backup.volumes.{volume_name}.path: '/var/lib/mariadb/dump.sql.gz' ``` +**Example 2:** +``` +backupbot.backup.volumes.{volume_name}.path: '/var/lib/myapp/foo,/var/lib/myapp/bar' +``` + ### `backupbot.backup.pre-hook` **Type:** string -- 2.47.2 From 40db4e79f7c58638d7b3033b0ede9f1403c99266 Mon Sep 17 00:00:00 2001 From: p4u1 Date: Fri, 26 Apr 2024 16:46:26 +0200 Subject: [PATCH 8/8] . --- Specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Specification.md b/Specification.md index 1be0160..37547df 100644 --- a/Specification.md +++ b/Specification.md @@ -10,12 +10,12 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## Backup -To enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service. The label MUST be only set once. When the label is set multiple times, the implementation SHOULD show an error. +To enable backups for a docker stack, the `backupbot.backup=true` label MUST be set on one of its services. The label MUST NOT be set multiple times for a docker stack. Otherwise the implementation MUST show an error. The label SHOULD be declared on the main service. ### Volumes and paths By default all volumes MUST be backed up. A volume MUST be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume. -By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get separated by a comma. +By default all files MUST be backed up on a volume. `backupbot.backup.volumes.{volume_name}.path` MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get separated by a comma. When the label is set only the given paths MUST be backed up. ### Pre/Post Hooks @@ -26,11 +26,11 @@ TODO: escaping ### Output -A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{volume_name}`, where `{volume_name}` is the name of each volume that got backed up. +A backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{stack_name}_{volume_name}`, where `{stack_name}` is the name of the docker stack and `{volume_name}` is the name of each volume that got backed up. ## Restore -By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. When restoring a backup from a `.tar.gz` it expects the directory layout as described int the [backup output](#output) section. +By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. When restoring a backup from a `.tar.gz` it expects the directory layout as described in the [backup output](#output) section. ### Pre/Post Hooks -- 2.47.2