# Norg A simple, portable, orchestration tool for the [borg backup](https://www.borgbackup.org) and [restic](https://restic.net) utilities written in Nim. Full documentation on the [Norg Backup Website](https://norgbackup.net/) Inspired by [Borgmatic](https://torsion.org/borgmatic) ## Usage Norg uses a `toml` based config file for configuration. An example configuration would look like this: ```toml source_directories = [ "/home/me/Music", "/home/me/Pictures" ] [[repositories]] label = "MyBorgRepo" path = "/my/backup/location" [[repositories]] label = "Another Respository at BorgBase" path = "ssh://1234abcd@1234abcd.repo.borgbase.com/./repo" [encryption] encryption_passphrase = "MyReallySecurePassword" [actions] before_actions = ["echo before actions"] after_actions = ["echo after actions", "echo actions completed"] before_backup = ["echo before backup", "date"] after_backup = ["echo after backup","echo backup completed"] [uptimekuma] base_url = "https://uptime.kuma.url/api/push/1234abcd" states = ["Success","Failure", "Running"] ``` You can then run the equivalent `borg` or `restic` command to init, create, list, mount and extract your backups. **Using BorgBackup** ```sh # Init your repository norg -c myconfig.toml init # Backup your data norg -c myconfig.toml create # List Archives norg -c myconfig.toml list # Mount an Archive norg -c myconfig.toml mount -r MyBorgRepo -a pcname-2024-08-18T15:20:17773204 /home/me/mnt # Unmount an Archive norg -c myconfig.toml umount -r MyBorgRepo /home/me/mnt # Extract an Archive # You must be in an empty folder for this to work norg -c myconfig.toml extract -r MyBorgRepo -a pcname-2024-08-18T15:20:17773204 # Or You must set the destination to an empty folder norg -c myconfig.toml extract -r MyBorgRepo -a pcname-2024-08-18T15:20:17773204 --destination /tmp/my_extracted_archive # Prune all repos norg -c myconfig.toml prune # Or specify a particula repo norg -c myconfig.toml prune -r MyBorgRepo # Delete an Archive norg -c myconfig.toml delete -r MyBorgRepo -a pcname-2024-08-18T15:20:17773204 ``` **Using Restic** _New in v0.1.6_ Add a repository with a `tool = "restic"` option. ```toml [[repositories]] label = "MyResticRepo" path = "/my/restic/backup/location" tool = "restic" ``` Then run the appropriate commands ```sh # Init your repository norg -c myconfig.toml init # Backup your data norg -c myconfig.toml backup # List Snapshots norg -c myconfig.toml snapshots # Mount a Repo norg -c myconfig.toml mount -r MyResticRepo /home/me/mnt # Restore an Archive (restore destination must be empty) norg -c myconfig.toml restore -a latest --destination /my/restore/location # Prune a repo norg -c myconfig.toml prune # Forget a Snapshot norg -c myconfig.toml forget -r MyBorgRepo -a a1b2c3d4 ``` ### Command line parameters * `-c`, `--config`: The configuration file to use * `-r`, `--repository`: The repository to work on * `-a`, `--archive`: The Archive to operate on (snapshots for restic) * `-d`, `--destination`: When extracting/restoring, the destination for the extracted files ## Build from Source Download and build from source ```sh git clone https://codeberg.org/pswilde/norgbackup cd norgbackup nimble install ``` or just install directly with `nimble` ```sh nimble install https://codeberg.org/pswilde/norgbackup ``` ## System Support Norg should work on any system that can compile `nim` code with `nimble`. Tested on: * Arch Linux * Debian Linux * AlmaLinux * FreeBSD But in general all Linux distributions and BSDs should work if borg and/or restic is installed. Windows support (Restic only until Borg support in Windows is available) is planned with the only real issue being finding the restic executable. Should be an easy fix. ## Naming. Why "Norg"? Well, I don't know. I'm a Star Trek fan so obviously I wanted to keep something in line with the [Borg pseudo-species](https://memory-alpha.fandom.com/wiki/Borg) as the borg backup utility does. Also, sometimes I feel my code has elements of inexperience but loads of potential... which reminded me of [Nog](https://memory-alpha.fandom.com/wiki/Nog). So, simply put, `Norg` is an portmanteau of "Borg" and "Nog". ## Borg and Restic Notes I love both Borg and Restic tools, they are both great and both have their pros and cons. As [BorgBase](https://borgbase.com) has repos for both, I felt it only sensible to provide a tool that can use both. Providing implementation for both means you could have duplicate backups using different tools which should provide a certain amount of protection over failures in a particular tool. Caution should be taken when using additional flags when you have repositories of both types in the same configuration file. I have tried to cater for some common flags that will be converted to the correct type for a particular tool, but this may not always be the case. If in any doubt, it is advised to use the `--repository` flag for any borg/restic specific flags so as not to cause one the other tool to fail. Some different yet similar commands should be converted to the correct type. A table below shows some of these: | Borg Command | Restic Command | Result | | --- | --- | --- | | create | backup | creates a backup | | list | snapshots | lists archives/snapshots | | extract | restore | restores/extracts a backup | | delete | forget | removes a archive/snapshot | | prune | forget (with --prune flag) | removes snapshots as per `--keep-*` config | You may specify either command and it will work with both except the `forget` command. This will only forget a single snapshot in restic. ## Why create this when Borgmatic exists? `Borgmatic` is absolutely fantastic, and I love it dearly. I even implemented the `Uptime Kuma` hook that is in it. However, I got a little impatient waiting for the version that included the Uptime Kuma hook to arrive in various distributions package repositories so ended up building borgmatic from source on all computers. This was a lengthy process, and borgmatic isn't very portable; it requires installation of numerous python packages (and the entire rust language in FreeBSD). I wanted to make something that had to features I needed, in a single binary I could move around to whatever computer I needed it on. Norg was the outcome of this. ## Work in Progress Norg is still very much a work in progress, so there will be bugs. Please raise and issue, or create a pull request for any issues and resolutions you may have. ## Contact For any issues, please raise an issue here. Otherwise, I can be contacted via the fediverse at [@paul@notnull.space](https://notnull.space/@paul).