{"id":22904592,"url":"https://github.com/Chocorean/pibackup","last_synced_at":"2025-08-12T06:31:47.286Z","repository":{"id":93413564,"uuid":"467182081","full_name":"Chocorean/pibackup","owner":"Chocorean","description":"Backup your Raspberry PI with one command","archived":false,"fork":false,"pushed_at":"2024-01-21T15:21:45.000Z","size":173,"stargazers_count":8,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-01-21T15:56:43.563Z","etag":null,"topics":["backup","bash","pi","pishrink","raspberry-pi","rpi","shell-script","tool"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Chocorean.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-03-07T16:55:21.000Z","updated_at":"2023-04-14T21:47:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"c88e991c-a203-47f7-b0b0-8c4a1a393d4c","html_url":"https://github.com/Chocorean/pibackup","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chocorean%2Fpibackup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chocorean%2Fpibackup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chocorean%2Fpibackup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chocorean%2Fpibackup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Chocorean","download_url":"https://codeload.github.com/Chocorean/pibackup/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229639963,"owners_count":18102846,"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","bash","pi","pishrink","raspberry-pi","rpi","shell-script","tool"],"created_at":"2024-12-14T02:46:36.534Z","updated_at":"2024-12-14T02:46:40.887Z","avatar_url":"https://github.com/Chocorean.png","language":"Shell","funding_links":[],"categories":["raspberry-pi"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./logo.png\" alt=\"pibackup logo\" width=\"192px\" /\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003cp\u003e\n    \u003cimg src=\"https://www.codefactor.io/repository/github/chocorean/pibackup/badge/main\" alt=\"codefactor\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/bash-5.0.3-lightgray\" alt=\"bash version\" /\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n# pibackup.sh\n\n`pibackup.sh` is a bash script that automatically dump a PI sdcard as a shrunk image to a [remote] directory, and handles rotation of several files. It is recommended to automate this script using `systemd` timers or `cron`, so the backups are done on a regular basis and without any interaction.\n\nThis is still WIP work, let me know if you have ideas about how to improve.\n\n## Table of content\n\n1. [Background](#background)\n2. [Usage](#usage)\n3. [Prerequisites](#prerequisites)\n   1. [Optional dependencies](#optional-dependencies)\n4. [Installation](#installation)\n5. [Example](#example)\n6. [Restoring](#restoring)\n7. [Automation](#automation)\n   1. [systemd timer](#systemd-timer)\n   2. [cron job](#cron-job)\n8. [Contributing](#contributing)\n\n## Background\n\nOnce during a house move, I unplugged a Raspberry PI and somehow it killed the SD card. All my code was saved already, but I lost hours of my time spent on configuring and pimping my PI. I was so mad at myself for not doing backups that I started to look into automatic backup tools, but I didn't find anything that pleased me enough. So I bought an external drive and started this project.\nHope it will be useful for more people than just myself!\n\n## Usage\n\n**Note:** It will create a `\u003coutput\u003e/\u003ctarget\u003e` directory, so you can use the same output directory for multiple nodes.\n\n```bash\n$ ./pibackup.sh -h\n---\npibackup.sh 0.5\n---\n\nusage: pibackup.sh -o \u003coutput\u003e [options]\n\nRequired parameters:\n  -o, --output-dir [DIRECTORY]  Where backup will be saved and rotated.\n\nOptional parameters:\n  -h, --help                    Display this message.\n  -n, --image-name [NAME]       Rename the backup file as '\u003cTARGET\u003e.img.x'.\n                                  Default: self ($ uname -n)\n  -r, --rotation-count [COUNT]  Quantity of files to be kept. Default: 8\n  -t, --tmp-dir [DIRECTORY]     Temporary directory to use on the remote node. Default: /tmp\n  -T, --target [HOSTNAME]       Name of the host to backup. Default: self ($ uname -n)\n  -q, --quiet                   Silent mode.\n  -z, --gzip                    Compress image using gzip.\n  -Z, --xz                      Compress image using xz.\n```\n\n## Prerequisites\n\n1. **External disk space:** At the moment, you cannot dump your sd card on itself; you need a proper storage. For instance, I have a disk drive plugged to my main Raspberry PI that other nodes will remotely interact with.\n\n2. **Fast local network:** If doing remote backup, you need to make sure your network is efficiently configured. I had speed issues at home, so I had to create a local network for my PIs, which greatly increased the backup upload speed.\n\n3. This project uses [PiShrink](https://github.com/Drewsif/PiShrink) from Drewsif. Make sure to install it before.\n\n```bash\n$ which pishrink.sh\n/usr/local/bin/pishrink.sh\n```\n\n### Optional dependencies\n\n1. If using `cron` you may need `postfix` to deliver local mails:\n\n```bash\nsudo apt install postfix\n```\n\n## Installation\n\nAll you need to do is download `pibackup.sh`, make it executable and put it in your PATH.\n\n```bash\nwget https://raw.githubusercontent.com/Chocorean/pibackup/main/pibackup.sh\nchmod +x pibackup.sh\nsudo mv pibackup.sh /usr/local/bin\n```\n\n## Example\n\nFor a local backup, this is simplest you can use:\n\n```bash\nuser@pi $ pibackup.sh -o /backups -n awesome_pi\n[pibackup.sh] Dumping sdcard ...\n[ ... dd output ... ]\n[pibackup.sh] Setting permissions ...\n[pibackup.sh] Shrinking image ...\n[ ... pishrink.sh output ... ]\n[pibackup.sh] Rotating previous images ...\n[pibackup.sh] Done ...\nuser@pi $ ls /backups/pi\nawesome_pi.img.0\n```\n\nFor a remote node, just specify its hostname or IP address.\n\n```bash\nuser@pi$ pibackup.sh -o /backups -d another_pi\n[pibackup.sh] Dumping sdcard ...\n[ ... dd output ... ]\n[pibackup.sh] Setting permissions ...\n[pibackup.sh] Shrinking image ...\n[ ... pishrink.sh output ... ]\n[pibackup.sh] Rotating previous images ...\n[pibackup.sh] Done ...\nuser@pi $ ls /backups/another_pi\nanother_pi.img.0\n```\n\n## Restoring\n\nDoing backups is a good thing, however you know to know how to restore them. Right now, I haven't looked at the newest feature which allows to boot from the network, but I might add a section about it later.\n\nUse a computer with access to the storage drive. If you compress your images, you will need to decompress them first:\n\n```bash\n# -Z ; xz\ncp /path/to/backup.xz.0 backup.xz\nunxz backup.xz\n\n# -z ; gzip\ncp /path/to/backup.gz.0 backup.gz\ngunzip backup.gz\n```\n\nNow you have a suitable image for flashing an SD card. Plug the SD card you want to overwrite and copy the image:\n\n```bash\nsudo dd if=backup.img of=/dev/mmcblk0 bs=4M conv=noerror,sync status=progress\n```\n\nInsert the SD card in your PI and you recovered all your data!\n\n## Automation\n\nThe recommended way to use `pibackup.sh` is to create a `systemd` timer-service duo, but a `cron` job will work fine. You also need to make sure your nodes have a proper SSH config which allows the main node to connect to them without asking for password (see `~/.ssh/authorized_keys` file).\n\n### systemd timer\n\nYou will first need to create the timer and the associated service. Then, enable and start the timer:\n\n```bash\n# systemctl enable pibackup.timer\n# systemctl start pibackup.timer\n```\n\nCheck [the docs](https://man.archlinux.org/man/systemd.time.7#CALENDAR_EVENTS) for `OnCalendar=` syntax.\n\n\u003cdetails\u003e\n  \u003csummary\u003esystemd timer example\u003c/summary\u003e\n  \u003cp\u003e\n    /etc/systemd/system/pibackup.timer\n    \n    [Unit]\n    Description=Run pibackup.sh every monday at 2am\n    \n    [Timer]\n    Unit=pibackup.service\n    OnCalendar=Mon, 2:00\n\n    [Install]\n    WantedBy=timers.target\n  \u003c/p\u003e\n\u003c/details\u003e\n    \n\u003cdetails\u003e\n  \u003csummary\u003esystemd service example\u003c/summary\u003e\n  \u003cp\u003e\n    /etc/systemd/system/pibackup.service\n    \n    [Unit]\n    Description=Run pibackup\n\n    [Service]\n    Type=oneshot\n    ExecStart=/usr/local/bin/pibackup.sh ...\n    User=pi\n  \u003c/p\u003e\n\u003c/details\u003e\n\nThanks to [Mcdostone](https://github.com/Chocorean/pibackup/issues/8) for the suggestion.\n\n### cron job\n\nI recommend to seperate `cron` logs from `syslog` logs for easier troubleshooting. If not the case already, edit `/etc/rsyslog.conf` and uncomment `cron.*  /var/log/cron.log`.\nAs stated in the [Prerequisites](#prerequisites) section, you may also need to install `postfix` because `cron` sends mails if a job has an output.\n\n**Also**, I had to set `SHELL` and `PATH` variables inside the crontab to make it work, but that might not be necessary for you.\n\nCheck [the docs](https://www.man7.org/linux/man-pages/man5/crontab.5.html) for `crontab` syntax.\n\n\u003cdetails\u003e\n  \u003csummary\u003ecrontab example\u003c/summary\u003e\n  \u003cp\u003e\n    $ crontab -e\n\n    # default shell\n    SHELL=/bin/bash\n    # set PATH variable\n    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin\n\n    # Do a backup once a week on Mondays at 2am\n    0 2 * * MON /usr/local/bin/pibackup.sh ...\n  \u003c/p\u003e\n\u003c/details\u003e\n\n## Contributing\n\nQuoting Drewsif:\n\n\u003e If you find a bug please create an issue for it. If you would like a new feature added, you can create an issue for it but I can't promise that I will get to it.\n\u003e\n\u003e Pull requests for new features and bug fixes are more than welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChocorean%2Fpibackup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChocorean%2Fpibackup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChocorean%2Fpibackup/lists"}