YRBA - Your Remote Backup Assistant

GitHub Release Date GitHub branch check runs GitHub Sponsors GitHub License

Crates.io Total Downloads GitHub Downloads (all assets, all releases) Docker Pulls AUR Votes

YRBA makes backing up your systems easy, by automating incremental backups of defined folders, and uploading them to a server of your choice or copying them to a different location like an external hard drive.

Documentation: https://yrba.roth.systems/

Features

Archives your backups as .tar.gz
Incremental backups automatically keeps the last N backups
Automatic uploads with SFTP, SMB or local copy to a target location like external drives
Can back up directories on any OS
- GNU/Linux
- macOS
- Windows

Installation

Detailed installation instructions can be found on the official documentation over at: https://yrba.roth.systems/

Usage

Usage: yrba [OPTIONS]

Options:
  -v, --verbose...                 Increase logging verbosity
  -q, --quiet...                   Decrease logging verbosity
  -c, --config <CONFIG_FILE_PATH>  
  -h, --help                       Print help
  -V, --version                    Print version

Contributing

Any kind of support is appreciated.

This can range from suggesting new features, to finding bugs, to coding on the project itself.

To suggest new features or report bugs, please leave a GitHub issue on this project.

For detailed guides on how to contribute, and how to build the project check out the official documentation.

AI-generated contributions disclaimer

This project does not accept low-effort or wholesale AI-generated contributions. Examples include, but are not limited to:

Any code including configuration files generated by tools like GitHub Copilot, ChatGPT, or similar.
AI-created assets e.g. application icons.
Auto-generated documentation, issue reports or pull request descriptions.

License

GPL-3.0

Installation

There are three main ways to install YRBA.

Native Installation
Docker Container
Arch Linux AUR

The native installation will be directly installed in your system via Cargo, Nix, or your Linux packages.

Meanwhile, the docker container allows a simple solution without a lot of setup, and is perfect for servers that are already utilizing Docker.

After this continue to Configuration to set up your YRBA instance.

Native Installation

There are multiple ways to YRBA natively on your system.

System Packages (Linux)
Download executables (Linux, macOS, Windows)
Nix
Rust Cargo

1. System Packages (Linux)

You can find packages for your Linux distribution either on the release page, in the package repositories of your distribution.

Currently, we offer packages for the following linux distributions. If yours is not one of the following distributions, please create an issue on the GitHub page, and it will likely get added very soon.

Arch Linux AUR

An easy to install Arch Linux AUR package can be installed using any AUR helper of your choice. Check out AUR Instructions for further information.

2. Download Binaries

Ready to run executables can be downloaded from the GitHub releases page, and are always up to date with the latest release of YRBA.

You can find the download of the latest release here.

3. Nix

If you have Nix installed on your system be it Linux, macOS or Windows, you can easily install & run YRBA with a single command.

nix run github:lilith-roth/yrba

In case you need to add parameters while calling the application, you have to append a -- at the end of the command, before the parameters.

Example:

nix run github:lilith-roth/yrba -- --config ./config.toml

4. Rust Cargo

If you have Rust’s Cargo installed on your system, you can easily compile and run the latest version easily on your machine, with this simple command.

NOTE: Due to an issue with the upstream library tar-rs if the cargo installation method is used, and socket files are encountered during the archiving process, it will error, and stop archiving at that point!

In other installation methods this is solved by using our own fork of tar-rs, though that does not work with cargo installations, as they always use the library on crates.io for building the application.

Install YRBA:

cargo install yrba

Afterwards, you can call YRBA just by calling yrba in your terminal.

yrba

Now that we installed YRBA we can continue to configuring YRBA.

Docker Setup

There are two different, easy to set up, ways to use YRBA with Docker.

Single-run Container
Automatic cron setup

Both setups are configured almost exactly the same way. Scroll down to see the installation instructions.

Single-run Container

The single run container runs the application as usual in a docker container once, and exits after the backup process is finished.

Automatic cron setup

The automatic cron setup will periodically run YRBA on a defined schedule. This is useful if you want easy to set up automatic recurring backups.

Installation

Docker Compose (recommended)

The setup with docker compose is recommended as it is completely preconfigured, and ready to use.

Clone the GitHub repository to your system git clone https://github.com/lilith-roth/yrba
Copy config.example.toml to config.toml
Adjust config.toml as described in Configuration
(Optional) If using the cron schedule based setup, adjust your automatic backup schedule by adjusting the CRON_SCHEDULE line in docker/docker-compose-cron.yml
Adjust docker/docker-compose.yml or docker/docker-compose-cron.yml with correct mount paths for your backup folder, and your authentication keys if SFTP private keys are used
Start the docker container with docker compose -f docker/docker-compose.yml up or docker compose -f docker/docker-compose-cron.yml up if the cron container is used

Manual container setup

To set up YRBA with docker, but without using docker compose follow the steps below.

Get the YRBA configuration file template from GitHub
Run the YRBA docker container with the following command

docker run \
  --rm \
  --name yrba \
  -v ./config.toml:/app/config.toml \
  -v ./folder-to-backup:/backup \
  -v ~/.ssh/:/auth \
  dcpacky/yrba-official:latest \
  /app/release/yrba -c /app/config.toml

Adjust the command with your mount paths for the configuration file, the folder to back up, and your authentication keys if private key authentication is desired.

Building the docker image locally

You can easily build the docker image on your local machine either by using the just command, or by using the full docker build command.

Note: Make sure you’re running these commands from the root folder of the repository.

just build-docker

docker build . -f docker/Dockerfile -t dcpacky/yrba-official:latest

Arch Linux AUR Setup

YRBA provides an AUR package for Arch Linux to easily get started with YRBA on your system, and features a systemd service and timers to have automatic updates with almost no setup required.

The AUR package is called yrba-git, and can be installed using an AUR helper of your choice.

https://aur.archlinux.org/packages/yrba-git

Installation example using `paru`

If paru is the AUR helper of your choice, installing YRBA is as simple as running the following command.

paru -Syu yrba-git

This will automatically install the systemd service & timers as well. To set those up, please check out the systemd instructions: systemd configuration.

Configuration

The configuration of YRBA is rather simple, and requires just a few adjustments to get going.

The default location the configuration is read from is ~/.config/yrba/config.toml, and /etc/yrba.toml if run as the root user, and can be changed by starting the executable with the --config /path/to/config/file or -c /path/to/config/file flag.

If the application has been started without the -c flag, and the default location does not contain a configuration file, it will automatically create an example file.

An example configuration file looks somewhat like this:

# Remote address for uploading backups
# SFTP: 'sftp://root@127.0.0.1/path/to/my/backup/storage/directory'
# SMB: 'smb://user@127.0.0.1/share-name/path/to/my/backup/storage/directory'
# FILE: 'file:///path/to/my/local/backup/storage/directory'
remote = 'sftp://root@127.0.0.1/path/to/my/backup/storage/directory'

# The amount of backups to keep
# Set to 0 to never delete old backups
amount_of_backups_to_keep = 5

# SFTP Settings (only used if remote string above is set to sftp protocol)
# if both public key path & password is defined, first the private key authentication is tried,
# and if that fails the password is tried next.
sftp_public_key_path = '/auth/id_ed25519.pub'
sftp_private_key_path = '/auth/id_ed25519'
sftp_private_key_password = 'my-super-secure-password'
sftp_password = 'my-super-secure-password'

# SMB Settings (only used if remote string above is set to smb protocol)
# SMB user password
smb_password = 'my-super-secure-password'

# Path to folders to back up, supports relative paths
folders_to_backup = [
    '/backup'
]

# Optional: Temporary folder to store archive before upload
# Default: '~/.cache/yrba'
# temporary_folder = '/tmp/yrba'

Tip: Use ' instead of " for the path strings in the file configuration. ' refers to a raw string in .toml files, which makes it allows the use of certain special characters without escaping them. Especially useful when the application runs on Windows due to the nature of Windows directory paths often containing \ characters that would otherwise need to be escaped with another backslash like \\.

The example file can be found in the root directory of the GitHub repository. https://github.com/lilith-roth/yrba/blob/main/config.example.toml

Explanation

`remote`

This configures the target to upload your backups to incl. path on the target system to which your backups will be uploaded.

It is intended to be written in a URL format.

Example: remote = 'sftp://user@127.0.0.1/path/to/my/backup/storage/directory'

Note: The password can be omitted if a private key is used for authentication

`amount_of_backups_to_keep`

This defines the amount of backups that will be kept on the remote server, older ones will be deleted.

Set this to 0 to never remove old backups.

Example: amount_of_backups_to_keep = 5

SFTP Options

`sftp_public_key_path`

If SFTP private key authentication is used set this to the path of your public key.

sftp_pubkey_path = '~/.ssh/id_ed25519.pub'

`sftp_private_key_path`

If SFTP private key authentication is used set this to the path of your private key.

sftp_public_key_path = '~/.ssh/id_ed25519'

`sftp_private_key_password`

If SFTP private key authentication is used, and your private key is protected with a password, set the password for your key here.

sftp_public_key_path = '~/.ssh/id_ed25519'

`sftp_password`

If SFTP password authentication is used, enter the password of your user here.

sftp_password = 'my-super-secure-password'

SMB Options

`smb_password`

User of the smb user connecting to the remote storage system.

smb_password = 'my-super-secure-password'

`folders_to_backup`

Configure the folders you want to back up here.

If a docker setup is used, set this to the folders that are mounted into your container.

Example:

folders_to_backup = [
    '/backup',
    '~/all-my-data'
]

Optional: `temporary_folder`

Default: ~/.cache/yrba If you would like to change the temporary folder YRBA will use to archive your backups to, define them here.

Example: temporary_folder = '/tmp/yrba'

systemd Configuration

YRBA provides a systemd service & timers for automated frequent backups.

If YRBA is installed using the AUR it will automatically install the necessary files, otherwise it is possible to set those up yourself, but this is only recommended if you know what you’re doing.

The systemd files for setting this up by yourself can be found here, but for the sake of simplicity, this guide won’t cover on how to set these up with your systemd manually. GitHub systemd files

Enabling automatic backups using systemd

YRBA provides 3 timers that can be enabled with a single line for daily, weekly and monthly backups respectively.

To enable daily backups use:

systemctl enable --now yrba.daily.timer

To enable weekly backups use:

systemctl enable --now yrba.weekly.timer

To enable monthly backups use:

systemctl enable --now yrba.monthly.timer

To verify if they’ve been enabled correctly type:

systemctl status yrba.daily.timer # Replace `daily` with the corresponding activated timer

In case log messages for the application are desired, they can be viewed using:

journalctl -xefu yrba.service

File Servers

YRBA enables easy automatic uploads of your backups to different systems, and automatically deletes backups using a configured amount of backups to keep.

The following backup storage options are available.

SFTP
SMB
File copy

SFTP

Configuration

To use YRBA with SFTP uploads configure the protocol in your config.toml to SFTP, and set up the username to log in with.

NOTE: The remote system has to be a unix like system like Linux or macOS due to the required cli commands on the remote machine!

Example:

remote = 'sftp://root@127.0.0.1/path/to/my/backup/storage/directory'

Afterwards, configure the following settings as well in the config.toml:

# SFTP Settings (only used if remote string above is set to sftp protocol)
# if both public key path & password is defined, first the private key authentication is tried,
# and if that fails the password is tried next.
sftp_public_key_path = '~/.ssh/id_ed25519.pub'
sftp_private_key_path = '~/.ssh/id_ed25519'
sftp_private_key_password = 'my-super-secure-password'
sftp_password = 'my-super-secure-password'

Note: Password and private key authentication can both be configured to try logging in with password, in case private key authentication fails.

For a more in-depth explanation of the configuration parameters, check out Configuration

Note

Make sure the system you’re uploading your backups to has the following shell commands available:

tail
ls
grep
xargs
cd

Full configuration example

A complete file copy backup configuration could look like this.

# Remote address for uploading backups
# SFTP: 'sftp://root@127.0.0.1/path/to/my/backup/storage/directory'
remote = 'sftp://root@127.0.0.1/path/to/my/backup/storage/directory'

# SFTP Settings (only used if remote string above is set to sftp protocol)
# if both public key path & password is defined, first the private key authentication is tried,
# and if that fails the password is tried next.
sftp_public_key_path = '~/.ssh/id_ed25519.pub'
sftp_private_key_path = '~/.ssh/id_ed25519'
sftp_private_key_password = 'my-super-secure-password'
sftp_password = 'my-super-secure-password'

# The amount of backups to keep
# Set to 0 to never delete old backups
amount_of_backups_to_keep = 5

# Path to folders to back up, supports relative paths
folders_to_backup = [
    "/backup"
]

SMB

Configuration

To use YRBA with SMB uploads configure the protocol in your config.toml to SMB, and set up the username to log in with.

Example:

remote = 'smb://user@127.0.0.1/share-name/path/to/my/backup/storage/directory'

Afterwards, configure the following settings as well in the config.toml:

# SMB Settings
# SMB user password
smb_password = 'my-super-secure-password'

For a more in-depth explanation of the configuration parameters, check out Configuration

Guest authentication

To authenticate as a guest user against the smb server set the username to guest, and don’t set a password field, or set smb_password = ''.

Full configuration example

A complete file copy backup configuration could look like this.

# Remote address for uploading backups
# SMB: 'smb://user@127.0.0.1/share-name/path/to/my/backup/storage/directory'
remote = 'smb://user@127.0.0.1/share-name/path/to/my/backup/storage/directory'

# SMB Settings
# SMB user password
smb_password = 'my-super-secure-password'

# The amount of backups to keep
# Set to 0 to never delete old backups
amount_of_backups_to_keep = 5

# Path to folders to back up, supports relative paths
folders_to_backup = [
    "/backup"
]

File copy backup

Configuration

If you want your backup to be stored by copying to a different directory, for example to store backups on an external drive, you can use the file protocol as your remote string in the YRBA configuration.

Example:

remote = "file:///path/to/my/backup/storage/directory"

For a more in-depth explanation of the configuration parameters, check out Configuration

Full configuration example

A complete file copy backup configuration could look like this.

# Remote address for uploading backups
# File copy: "file:///path/to/my/backup/storage/directory"
remote = "file:///path/to/my/backup/storage/directory"

# The amount of backups to keep
# Set to 0 to never delete old backups
amount_of_backups_to_keep = 5

# Path to folders to back up, supports relative paths
folders_to_backup = [
    "/backup"
]

Contribute

All kinds of contributions are welcome, be it bug reports, documentation updates, or improvements to the application or its tests, or even financial contributions.

All development is done directly on GitHub.

To find ways to contribute check out the Issues page as it contains all known bugs, planned features, and more.

Development

This guide will contain information to help you compiling YRBA, and general development informations.

How to build

To build YRBA on your local systems, first make sure you have the Rust compiler & cargo installed on your local machine.

For further instructions regarding the installation of Rust check out: https://rust-lang.org/learn/get-started/

The next step is to clone to git repository to your local machine.

git clone https://github.com/lilith-roth/yrba/

Now navigate a terminal to the YRBA project on your local machine, and compile the project using cargo.

cargo build

A release optimized build can be built using the --release flag.

cargo build --release

Code formatting

A formatting and lint check is automatically run on every pull request. To check this locally, and reformat your code use:

cargo clippy --verbose # Runs the clippy linter on your code
cargo fmt # Automatically reformats your code files

Troubleshooting

Compilation fails with `openssl not found`

In some cases, especially when doing cross-compilation, the build process may fail with an error message something like: Could not find openssl via pkg-config.

The easiest solution to this issue is to compile YRBA with the vendored-openssl flag. This will build openssl from source during the compilation of YRBA.

Note: This may increase the compilation time substantially. The alternative to using the feature flag is to install & configure the openssl development libraries on your system so that the Rust compiler can find them.

This is out of scope for this guide though if you run into any issues, please create a GitHub issue, and we can find a solution together.

Keyboard shortcuts

YRBA Documentation