Norg

A simple, portable, orchestration tool for the borg backup and restic utilities written in Nim.

Full documentation on the Norg Backup Website

Inspired by Borgmatic

Usage

Norg uses a toml based config file for configuration. An example configuration would look like this:

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

# 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.

[[repositories]]
label = "MyResticRepo"
path = "/my/restic/backup/location"
tool = "restic"

Then run the appropriate commands

# 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

git clone https://codeberg.org/pswilde/norgbackup
cd norgbackup
nimble install

or just install directly with nimble

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 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.
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 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.