183 lines
6.8 KiB
Markdown
183 lines
6.8 KiB
Markdown
# 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/)
|
|
|
|
<!--more-->
|
|
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).
|
|
|
|
|