{"id":13435659,"url":"https://github.com/digint/btrbk","last_synced_at":"2025-05-15T12:02:08.330Z","repository":{"id":27128011,"uuid":"30596420","full_name":"digint/btrbk","owner":"digint","description":"Tool for creating snapshots and remote backups of btrfs subvolumes","archived":false,"fork":false,"pushed_at":"2023-12-03T15:31:49.000Z","size":2511,"stargazers_count":1818,"open_issues_count":239,"forks_count":127,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-14T19:59:17.560Z","etag":null,"topics":["backup","btrfs","encrypted-backups","incremental-backups","snapshot"],"latest_commit_sha":null,"homepage":"https://digint.ch/btrbk/","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digint.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":".github/FUNDING.yml","license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"custom":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=WFQSSCD9GNM4S","https://btc.com/19DYtoEepxBmn9ZPspJGZrhCtySKCxPcP1"]}},"created_at":"2015-02-10T14:41:47.000Z","updated_at":"2025-04-12T01:16:50.000Z","dependencies_parsed_at":"2024-01-13T22:53:29.710Z","dependency_job_id":"b3024716-d9f5-4763-bf38-f13a0d4f72ab","html_url":"https://github.com/digint/btrbk","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digint%2Fbtrbk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digint%2Fbtrbk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digint%2Fbtrbk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digint%2Fbtrbk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digint","download_url":"https://codeload.github.com/digint/btrbk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","btrfs","encrypted-backups","incremental-backups","snapshot"],"created_at":"2024-07-31T03:00:37.835Z","updated_at":"2025-05-15T12:02:08.259Z","avatar_url":"https://github.com/digint.png","language":"Perl","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=WFQSSCD9GNM4S","https://btc.com/19DYtoEepxBmn9ZPspJGZrhCtySKCxPcP1"],"categories":["HarmonyOS","Install from Source","Perl","A list of FOSS backup software","others","Backups \u0026 Snapshots"],"sub_categories":["Windows Manager","Snapshots Management/System Recovery","[btrbk](https://digint.ch/btrbk/)"],"readme":"Introduction\n============\n\nBtrbk is a backup tool for btrfs subvolumes, taking advantage of btrfs\nspecific capabilities to create atomic snapshots and transfer them\nincrementally to your backup locations.\n\nThe source and target locations are specified in a config file, which\nallows to easily configure simple scenarios like \"laptop with locally\nattached backup disks\", as well as more complex ones, e.g. \"server\nreceiving backups from several hosts via ssh, with different retention\npolicies\".\n\nKey Features:\n\n  * Atomic snapshots\n  * Incremental backups\n  * Flexible retention policy\n  * Backups to multiple destinations\n  * Transfer via ssh\n  * Robust recovery from interrupted backups (for removable and mobile\n    devices)\n  * Archive to offline storage\n  * Encrypted backups to non-btrfs storage\n  * Wildcard subvolumes (useful for docker and lxc containers)\n  * Transaction log\n  * Comprehensive list and statistics output\n  * Resolve and trace btrfs parent-child and received-from relationships\n  * List file changes between backups\n  * Calculate accurate disk space usage based on block regions\n\nBtrbk is designed to run as a cron job for triggering periodic\nsnapshots and backups, as well as from the command line (e.g. for\ninstantly creating additional snapshots).\n\n\nInstallation\n============\n\nBtrbk is a single perl script, and does not require any special\ninstallation procedures or libraries. Download the latest [btrbk\nsource tarball], or try latest master:\n\n    wget https://raw.githubusercontent.com/digint/btrbk/master/btrbk\n    chmod +x btrbk\n    sudo ./btrbk ls /\n\nFor more information, read the [installation documentation].\n\n  [btrbk source tarball]: https://digint.ch/download/btrbk/releases/\n  [installation documentation]: doc/install.md\n\n\n### Prerequisites\n\n  * [btrfs-progs]: Btrfs filesystem utilities \u003e= v4.12\n  * [Perl interpreter]: Probably already installed on your system\n  * [OpenSSH]: If you want to transfer backups from/to remote locations\n  * [mbuffer]: If you want rate limiting and progress bars\n\n  [btrfs-progs]: https://www.kernel.org/pub/linux/kernel/people/kdave/btrfs-progs/\n  [Perl interpreter]: https://www.perl.org\n  [OpenSSH]: https://www.openssh.com\n  [mbuffer]: https://www.maier-komor.de/mbuffer.html\n\n\nSynopsis\n========\n\nPlease consult the [btrbk(1)] man-page provided with this package for\na full description of the command line options.\n\n  [btrbk(1)]: https://digint.ch/btrbk/doc/btrbk.1.html\n\n\nConfiguration\n=============\n\nBefore running `btrbk`, you will need to create a configuration\nfile. You might want to take a look at `btrbk.conf.example` provided\nwith this package. For a detailed description, please consult the\n[btrbk.conf(5)] man-page.\n\nAfter a configuration change, it is highly recommended to check it by\nrunning btrbk with the `-n,--dry-run` option:\n\n    # btrbk -c /path/to/myconfig -v -n run\n\nThis will read all btrfs information on the source/target filesystems\nand show what actions would be performed (without writing anything to\nthe disks).\n\nThe examples below assume that the btrfs subvolume containing `home`\nand `rootfs` is mounted at `/mnt/btr_pool`. This is usually the btrfs\nroot subvolume, which always has `subvolid=5`.\n\nMounting `subvolid=5` is *recommended* (mandatory for btrbk \u003c v0.32.0)\nif you want to backup your root filesystem `/`.\n\n/etc/fstab:\n\n    /dev/sda1  /mnt/btr_pool  btrfs  subvolid=5,noatime  0 0\n\nNote that some default btrfs installations (e.g. Ubuntu) use subvolume\nnames `@` for rootfs (mounted at `/`) and `@home` for `/home`, as a\nnaming convention. If this is the case on your file system, replace\nthe `subvolume` declarations in the examples accordingly.\n\n  [btrbk.conf(5)]: https://digint.ch/btrbk/doc/btrbk.conf.5.html\n\n\nExample: Local Regular Snapshots (time-machine)\n-----------------------------------------------\n\nThe simplest use case is to only create snapshots of your data. This\nwill obviously not protect it against hardware failure, but can be\nuseful for:\n\n  * protection against inadvertent changes or deletions\n  * keeping past states of copies from rsync or similar tools\n\nLet's assume you need regular snapshots of your home directory, which\nis located in the subvolume `home` of the volume `/mnt/btr_pool`. The\nsnapshots are to be stored in `btrbk_snapshots` (on the same volume).\n\n/etc/btrbk/btrbk.conf:\n\n    timestamp_format        long\n    snapshot_preserve_min   18h\n    snapshot_preserve       48h\n\n    volume /mnt/btr_pool\n      snapshot_dir btrbk_snapshots\n      subvolume home\n\nNotice that the `target` option is not provided, and btrbk will only\nmanage snapshots located on the same volume in `snapshot_dir`. Btrbk\ndoes not create subdirs by default, the snapshot directory must first\nbe created manually:\n\n    # mkdir /mnt/btr_pool/btrbk_snapshots\n\nThe \"volume\" section is merely used as a specifier for a base\ndirectory, and can be skipped if you prefer to configure everything\nusing absolute paths. The above configuration can also be written as:\n\n    snapshot_dir /mnt/btr_pool/btrbk_snapshots\n    subvolume    /mnt/btr_pool/home\n\nIf you don't want to mount the btrfs root filesystem to\n`/mnt/btr_pool`, you might as well configure it like this:\n\n    snapshot_dir /btrbk_snapshots\n    subvolume    /home\n\nStart a dry run (-n, --dry-run):\n\n    # btrbk run -n\n\nCreate the first snapshot:\n\n    # btrbk run\n\nPrint schedule (-S, --print-schedule):\n\n    # btrbk run -n -S\n\nIf it works as expected, configure a cron job to run btrbk hourly:\n\n/etc/cron.hourly/btrbk:\n\n    #!/bin/sh\n    exec /usr/bin/btrbk -q run\n\nSnapshots will now be created every hour. All snapshots are preserved for at\nleast 18 hours (`snapshot_preserve_min`), whether they are created by the cron\njob or manually by calling `sudo btrbk run` on the command line. Additionally,\n48 hourly snapshots are preserved (`snapshot_preserve`).\n\n\nExample: Backups to USB Disk\n----------------------------\n\nIn this example, we assume you have a laptop with:\n\n  * a disk having a btrfs root subvolume (subvolid=5) mounted on\n    `/mnt/btr_pool`, containing a subvolume `rootfs` for the root\n    filesystem (i.e. mounted on `/`) and a subvolume `home` for the\n    user data,\n  * a directory or subvolume `/mnt/btr_pool/btrbk_snapshots` which\n    will hold the btrbk snapshots,\n  * a backup disk having a btrfs volume mounted as `/mnt/btr_backup`,\n    containing a subvolume or directory `mylaptop` for the incremental\n    backups.\n\nRetention policy:\n\n  * keep all snapshots for 2 days, no matter how frequently you (or\n    your cron job) run btrbk\n  * keep daily snapshots for 14 days (very handy if you are on\n    the road and the backup disk is not attached)\n  * keep monthly backups forever\n  * keep weekly backups for 10 weeks\n  * keep daily backups for 20 days\n\n/etc/btrbk/btrbk-mylaptop.conf:\n\n    snapshot_preserve_min   2d\n    snapshot_preserve      14d\n\n    # Create snapshots only if the backup disk is attached\n    #snapshot_create ondemand\n\n    target_preserve_min    no\n    target_preserve        20d 10w *m\n\n    snapshot_dir           btrbk_snapshots\n\n    volume /mnt/btr_pool\n      target /mnt/btr_backup/mylaptop\n      subvolume rootfs\n      subvolume home\n      [...]\n\n\n/etc/cron.daily/btrbk:\n\n    #!/bin/sh\n    exec /usr/bin/btrbk -q -c /etc/btrbk/btrbk-mylaptop.conf run\n\n\n  * This will create snapshots on a daily basis:\n    * `/mnt/btr_pool/btrbk_snapshots/rootfs.YYYYMMDD`\n    * `/mnt/btr_pool/btrbk_snapshots/home.YYYYMMDD`\n  * And create incremental backups in:\n    * `/mnt/btr_backup/mylaptop/rootfs.YYYYMMDD`\n    * `/mnt/btr_backup/mylaptop/home.YYYYMMDD`\n\nIf you prefer triggering the backups manually, change the cron command\nto run the `snapshot` action instead of `run`. Start the backups\nmanually by running:\n\n    # btrbk resume\n\nFor a quick additional snapshot of your home, run:\n\n    # btrbk snapshot home\n\n\nExample: Host-initiated Backup on Fileserver\n--------------------------------------------\n\nLet's say you have a fileserver at \"myserver.example.org\" where you\nwant to create backups of your laptop disk. The config could look like\nthis:\n\n    ssh_identity /etc/btrbk/ssh/id_rsa\n\n    volume /mnt/btr_pool\n      subvolume rootfs\n        target /mnt/btr_backup/mylaptop\n        target ssh://myserver.example.org/mnt/btr_backup/mylaptop\n\nIn addition to the backups on your local usb-disk mounted at\n`/mnt/btr_backup/mylaptop`, incremental backups would also be pushed\nto `myserver.example.org`.\n\n\nExample: Fileserver-initiated Backups from Several Hosts\n--------------------------------------------------------\n\nIf you're a sysadmin and want to trigger backups directly from your\nfileserver, the config would be something like:\n\n    ssh_identity /etc/btrbk/ssh/id_rsa\n\n    volume ssh://alpha.example.org/mnt/btr_pool\n      target /mnt/btr_backup/alpha\n      subvolume rootfs\n      subvolume home\n\n    volume ssh://beta.example.org/mnt/btr_pool\n      target /mnt/btr_backup/beta\n      subvolume rootfs\n      subvolume dbdata\n\nThis will pull backups from alpha/beta.example.org and locally\ncreate:\n\n  * `/mnt/btr_backup/alpha/rootfs.YYYYMMDD`\n  * `/mnt/btr_backup/alpha/home.YYYYMMDD`\n  * `/mnt/btr_backup/beta/rootfs.YYYYMMDD`\n  * `/mnt/btr_backup/beta/dbdata.YYYYMMDD`\n\n\nExample: Multiple Btrbk Instances\n---------------------------------\n\nLet's say we have a host (at 192.168.0.42) running btrbk with the\nsetup of the time-machine example above, and we need a backup server\nto only fetch the snapshots.\n\n/etc/btrbk/btrbk.conf (on backup server):\n\n    target_preserve_min        no\n    target_preserve            0d 10w *m\n\n    volume ssh://192.168.0.42/mnt/btr_pool\n      target /mnt/btr_backup/my-laptop\n      subvolume home\n        snapshot_dir           btrbk_snapshots\n        snapshot_preserve_min  all\n        snapshot_create        no\n\nIf the server runs btrbk with this config, 10 weeklies and all\nmonthlies are received from 192.168.0.42. The source filesystem is\nnever altered because of `snapshot_preserve_min all`.\n\n\nExample: Virtual Machine Setup\n------------------------------\n\nCommon virtual machine setups have multiple volume sections with same\nhost, but distinct port numbers for each machine.\n\n/etc/btrbk/btrbk.conf:\n\n    # This propagates to all subvolume sections:\n    target /mnt/btr_backup/\n\n    volume ssh://localhost:2201/mnt/btr_pool\n      group vm vm01\n      subvolume home\n        snapshot_name vm01-home\n      subvolume data\n        snapshot_name vm01-data\n\n    volume ssh://localhost:2202/mnt/btr_pool\n      group vm vm02\n      subvolume home\n        snapshot_name vm02-home\n\n    volume ssh://localhost:2203/mnt/btr_pool\n      [...]\n\nThis will create `/mnt/btr_backup/vm[NN]-home`, `vm[NN]-data`, ...\n\nNote that btrbk holds a single reference to every btrfs filesystem\ntree, regarding UUID's as \"globally unique\". If the configured\nsubvolumes point to the same filesystem on different machines (ports),\nyou will see log lines like this when running `btrbk -v`:\n\n```\nAssuming same filesystem: \"ssh://localhost:2201/dev/sda1\", \"ssh://localhost:2202/dev/sda1\"\n```\n\n\nExample: Backup from non-btrfs Source\n-------------------------------------\n\nIf you want to make backups from a filesystem other than btrfs\n(e.g. ext4 or reiserfs), you need to create a *synchronization\nsubvolume* on the backup disk:\n\n    # btrfs subvolume create /mnt/btr_backup/myhost_sync\n\nConfigure btrbk to use `myhost_sync` as source subvolume:\n\n    volume /mnt/btr_backup\n      subvolume myhost_sync\n        snapshot_name           myhost\n\n        snapshot_preserve_min   latest\n        snapshot_preserve       14d 20w *m\n\nThe btrbk package provides the \"btrbk-mail\" script, which automates\nthe synchronization using rsync, and can be run as cron job or systemd\ntimer unit. For configuration details, see the config section in\n\"/contrib/cron/btrbk-mail\".\n\nAlternatively, you can run any synchronization software prior to\nrunning btrbk. Something like:\n\n    #!/bin/sh\n    rsync -az --delete \\\n          --inplace --numeric-ids --acls --xattrs \\\n          -e 'ssh -i /etc/btrbk/ssh/id_rsa' \\\n          myhost.example.org:/data/ \\\n          /mnt/btr_backup/myhost_sync/\n\n    exec /usr/bin/btrbk -q run\n\nThis will produce snapshots `/mnt/btr_backup/myhost.20150101`, with\nretention as defined with the snapshot_preserve option.\n\n\nExample: Encrypted Backup to non-btrfs Target\n---------------------------------------------\n\nIf your backup server does not support btrfs, you can send your\nsubvolumes to a raw file.\n\nThis is an _experimental_ feature: btrbk supports \"raw\" targets,\nmeaning that similar to the \"send-receive\" target the btrfs subvolume\nis being sent using `btrfs send` (mirroring filesystem level data),\nbut instead of instantly being received (`btrfs receive`) by the\ntarget filesystem, it is being redirected to a file, optionally\ncompressed and piped through GnuPG.\n\n/etc/btrbk/btrbk.conf:\n\n    raw_target_compress   xz\n    raw_target_encrypt    gpg\n    gpg_keyring           /etc/btrbk/gpg/pubring.gpg\n    gpg_recipient         btrbk@example.org\n\n    volume /mnt/btr_pool\n      subvolume home\n        target raw ssh://cloud.example.com/backup\n          ssh_user  btrbk\n          # incremental  no\n\nThis will create a GnuPG encrypted, compressed files on the target\nhost. For each backup, two files are created:\n\n  * `/backup/home.YYYYMMDD.btrfs.xz.gpg`: main data file containing\n    the btrfs send-stream,\n  * `/backup/home.YYYYMMDD.btrfs.xz.gpg.info`: sidecar file containing\n    metadata used by btrbk.\n\nIf you are using raw _incremental_ backups, please make sure you\nunderstand the implications (see [btrbk.conf(5)], TARGET TYPES).\n\n\nSetting up SSH\n==============\n\nSince btrbk needs root access, it is *very advisable* to take all the\nsecurity precautions you can. In most cases backups are generated\nperiodically without user interaction, so it is not possible to\nprotect your ssh key with a password. The steps below will give you\nhints on how to secure your ssh server for a backup scenario. Note\nthat the btrbk package is not required on the remote side, but you\nwill need the `btrfs` executable from the [btrfs-progs] package.\n\n\n### Create SSH Key Pair\n\nOn the client side, create a ssh key dedicated to btrbk, without\npassword protection:\n\n    # ssh-keygen -t rsa -b 4096 -f /etc/btrbk/ssh/id_rsa -C btrbk@example.org -N \"\"\n\nThe content of the public key (/etc/btrbk/ssh/id_rsa.pub) is used for\nauthentication in \"authorized_keys\" on the server side (see [sshd(8)]\nfor details).\n\n\n### Allow Root Login\n\nThe most straight forward setup is to allow root login on the remote\nhost. If this is not an option for you, refer to the more complex\n\"Dedicated Btrbk User Login\" section below.\n\n/etc/ssh/sshd_config:\n\n    PermitRootLogin prohibit-password\n\nAdd your btrbk public key to \"/root/.ssh/authorized_keys\" on the\nserver, and you are good to go.\n\n\n### Restrict Access\n\nRestrict ssh access to a static IP address within your network. On the\nremote host, either add a \"Match\" block in:\n\n/etc/ssh/sshd_config:\n\n    Match Address 192.168.0.42\n\nOr restrict in authorized_keys:\n\n    from=\"192.168.0.42\" \u003cpubkey\u003e...\n\nConsult the [sshd_config(5)] man-page for a detailed explanation and\nmore options.\n\n\nDedicated Btrbk User Login (optional)\n-------------------------------------\n\nIf allowing root login is not an option for you, there are several\nways to restrict SSH access to a regular user.\n\n\n### Option 1: Use sudo\n\nOn the client side, configure btrbk use the sudo backend. This changes\nthe ssh calls to btrfs commands to `sudo btrfs \u003csubcommand\u003e\n\u003coptions\u003e`.\n\n/etc/btrbk/btrbk.conf:\n\n    backend_remote btrfs-progs-sudo\n\nOn the remote host, grant root permissions for the \"btrfs\" command\ngroups (subcommands) in \"/etc/sudoers\". If you are using\n[ssh_filter_btrbk(1)], also add the `ssh_filter_btrbk.sh --sudo`\noption in \"authorized_keys\" (see below).\n\n\n### Option 2: Use btrfs-progs-btrbk\n\nInstead of using the all-inclusive `btrfs` command,\n\"btrfs-progs-btrbk\" allows you to restrict privileges to its\nsubcommands using linux capabilities(7) or setuid.\n\nNote that the \"btrfs-progs-btrbk\" package is not available on all\nlinux distributions, you might need to build and install it on your\nown (refer to [btrfs-progs-btrbk] on GitHub for more details).\n\n/etc/btrbk/btrbk.conf:\n\n    backend_remote btrfs-progs-btrbk\n\nMake sure that only the required binaries with elevated privileges can\nbe called by the btrbk user. For example, on a server acting as \"btrbk\nsource\", allow only the following binaries for the \"btrbk\" group:\n\n    # getcap /usr/bin/btrfs-*\n    /usr/bin/btrfs-send cap_dac_read_search,cap_fowner,cap_sys_admin=ep\n    /usr/bin/btrfs-subvolume-delete cap_dac_override,cap_sys_admin=ep\n    /usr/bin/btrfs-subvolume-list cap_dac_read_search,cap_fowner,cap_sys_admin=ep\n    /usr/bin/btrfs-subvolume-show cap_dac_read_search,cap_fowner,cap_sys_admin=ep\n    /usr/bin/btrfs-subvolume-snapshot cap_dac_override,cap_dac_read_search,cap_fowner,cap_sys_admin=ep\n    \n    # ls -l /usr/bin/btrfs-*\n    -rwx--x--- 1 root btrbk  /usr/bin/btrfs-send\n    -rwx--x--- 1 root btrbk  /usr/bin/btrfs-subvolume-delete\n    -rwx--x--- 1 root btrbk  /usr/bin/btrfs-subvolume-list\n    -rwx--x--- 1 root btrbk  /usr/bin/btrfs-subvolume-show\n    -rwx--x--- 1 root btrbk  /usr/bin/btrfs-subvolume-snapshot\n\n\nRestrict Commands with \"ssh_filter_btrbk.sh\" (optional)\n-------------------------------------------------------\n\nBtrbk comes with a shell script \"ssh_filter_btrbk.sh\", which restricts\nssh access to sane calls to the \"btrfs\" command needed for snapshot\ncreation and send/receive operations (see [ssh_filter_btrbk(1)]).\n\nCopy \"ssh_filter_btrbk.sh\" to \"/backup/scripts/\", and configure sshd\nto run it whenever the key is used for authentication. Example\n\"/root/.ssh/authorized_keys\":\n\n    # example backup source (also allowing deletion of old snapshots)\n    command=\"/backup/scripts/ssh_filter_btrbk.sh -l --source --delete\",restrict \u003cpubkey\u003e...\n\n    # example backup target (also allowing deletion of old snapshots)\n    command=\"/backup/scripts/ssh_filter_btrbk.sh -l --target --delete\",restrict \u003cpubkey\u003e...\n\n    # example fetch-only backup source (snapshot_preserve_min=all, snapshot_create=no),\n    # restricted to subvolumes within /home or /data\n    command=\"/backup/scripts/ssh_filter_btrbk.sh -l --send -p /home -p /data\",restrict \u003cpubkey\u003e...\n\n\n  [ssh_filter_btrbk(1)]: https://digint.ch/btrbk/doc/ssh_filter_btrbk.1.html\n  [sshd(8)]: https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8\n  [sshd_config(5)]: https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man5/sshd_config\n  [btrfs-progs-btrbk]: https://github.com/digint/btrfs-progs-btrbk\n\n\nRestoring Backups\n=================\n\nBtrbk does not provide any mechanism to restore your backups, this has\nto be done manually. In the instructions below, we assume that you\nhave a btrfs volume mounted at `/mnt/btr_pool`, and the subvolume you\nwant to restore is at `/mnt/btr_pool/data`.\n\n**Important**: don't use `btrfs property set` to make a subvolume\nread-write after restoring. This is a low-level command, and leaves\n\"Received UUID\" in a false state which causes btrbk to fail on\nsubsequent incremental backups. Instead, use `btrfs subvolume\nsnapshot` (without `-r` flag) as described below.\n\n\n### Step 0: Identify Subvolume\n\n    # list snapshots managed by btrbk\n    btrbk list snapshots\n\n    # alternative: list all subvolumes\n    btrbk ls /\n    btrbk ls -L /\n\nFrom the list, identify the snapshot you want to restore. Let's say it's\n`/mnt/btr_pool/_btrbk_snap/data.20150101`.\n\n\n### Step 1: Restore Backup\n(skip this step if you restore from a snapshot)\n\n    # locally mounted backup disk\n    btrfs send /mnt/btr_backup/data.20150101 | btrfs receive /mnt/btr_pool/\n\n    # from / to remote host\n    ssh root@remote btrfs send /mnt/btr_backup/data.20150101 | btrfs receive /mnt/btr_pool/\n    btrfs send /mnt/btr_backup/data.20150101 | ssh root@remote btrfs receive /mnt/btr_pool/\n\n**Hint**: Try to send-receive backups incrementally if possible. In\ncase you still have common snapshot / backup pairs (i.e. both\n\"snapshot_subvol\" and \"target_subvol\" are listed above), use `btrfs\nsend -p \u003cparent\u003e`.\n\nFrom this point on, `data.20150101` on both disks can be used as\nparents for subsequent send-receive operations, and a *received_uuid*\nrelationship is established (see below).\n\n\n### Step 2: Create read-write Subvolume\n\n    # if still present, move broken subvolume away\n    mv /mnt/btr_pool/data /mnt/btr_pool/data.BROKEN\n\n    # create read-write subvolume\n    btrfs subvolume snapshot /mnt/btr_pool/data.20150101 /mnt/btr_pool/data\n\nYour `data` subvolume is restored, you can carry on with incremental\nbackups to `/mnt/btr_backup`.\n\n\n### Step 3: Cleanup\n\n    # if everything went fine, delete the broken subvolume\n    btrfs subvolume delete /mnt/btr_pool/data.BROKEN\n\nMake sure to keep `data.20150101` subvolumes on both disks at least\nuntil you created a new backup using btrbk, in order to keep the\nincremental chain alive.\n\n\nBtrfs Relationship (technical note)\n-----------------------------------\n\n    btrbk origin -t /mnt/btr_backup/data.20150101\n    btrbk ls -L /mnt/btr_pool /mnt/btr_backup\n\n  * **received_uuid** relationship: *correlated*, *identical*\n    read-only subvolumes, cross-filesystem.\n\n        a.received_uuid = b.received_uuid\n        a.received_uuid = b.uuid\n\n    * Required for subvolumes used as parent (or clone-src) of\n      send-receive operations.\n    * Present on subvolumes created by `btrfs send | btrfs receive`.\n    * `/mnt/btr_pool/data.20150101 === /mnt/btr_backup/data.20150101`\n\n  * **parent_uuid** relationship: \"is-snapshot-of\"\n\n        a.parent_uuid = b.uuid\n\n    * Present on subvolumes created by `btrfs subvolume snapshot` or\n      `btrfs send -p | btrfs receive`.\n    * Used by btrbk to determine best parent.\n    * `/mnt/btr_pool/data.20150101 \u003c-- /mnt/btr_pool/data`\n\n\nFAQ\n===\n\nMake sure to also read the [btrbk FAQ page](doc/FAQ.md).\nHelp improve it by asking!\n\n\nDonate\n======\n\nSo btrbk saved your day?\n\nI will definitively continue to develop btrbk for free. If you want to\nsupport my hard work with a donation, you are welcome to do so!\n\n[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=WFQSSCD9GNM4S)\n\n\nDevelopment\n===========\n\nSource Code Repository\n----------------------\n\nThe source code for btrbk is managed using Git.\n\nOfficial repository:\n\n    git clone https://dev.tty0.ch/btrbk.git\n\nMirror on GitHub:\n\n    git clone https://github.com/digint/btrbk.git\n\n\nHow to Contribute\n-----------------\n\nYour contributions are welcome!\n\nIf you would like to contribute or have found bugs:\n\n  * Visit the [btrbk project page on GitHub] and use the\n    [issues tracker] there.\n  * Talk to us on [Libera.Chat] in `#btrbk`.\n  * Contact the author via email (the email address can be found in\n    the sources).\n\nAny feedback is appreciated!\n\n  [btrbk project page on GitHub]: https://github.com/digint/btrbk\n  [issues tracker]: https://github.com/digint/btrbk/issues\n  [Libera.Chat]: https://libera.chat\n\n\nLicense\n=======\n\nbtrbk is free software, available under the [GNU General Public\nLicense, Version 3 or later][GPL-3.0-or-later].\n\n  [GPL-3.0-or-later]: https://www.gnu.org/licenses/gpl.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigint%2Fbtrbk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigint%2Fbtrbk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigint%2Fbtrbk/lists"}