Borg Backup - UI

What is Borg Backup UI?

Borg Backup UI is an Unraid plugin that provides a web interface for BorgBackup.

It helps manage backup jobs, repositories, restore tests, archive browsing, reports, notifications, and system health checks directly from within Unraid.

Support and Feedback

This thread can be used for:

• Discussion

• Questions

• Feedback

• Feature suggestions

• Bug reports

If you run into problems, notice unclear behavior, or have ideas for improvements, feel free to post them here.

Helpful information includes:

• Screenshots

• Relevant log excerpts

• A short description of what you were trying to do

• What you expected to happen

• What actually happened

GitHub Issues

Bug reports can also be submitted directly on GitHub if you prefer:

https://github.com/borgforge/borg-backup-ui/issues

GitHub issues may be written in either English or German.

Requirement

Borg Backup UI requires the separate Unraid plugin:

Python 3 for UNRAID

Important Note

Please test your backup and restore workflow carefully, especially before using the plugin with important data.

A backup is only useful if restore has been tested as well.

Thank You

Thanks for testing and using Borg Backup UI.

Your feedback helps improve the plugin and make it easier to use for more Unraid users.

Edited August 13Aug 13 by Thorsten

19 hours ago, Thorsten said:

1. Which best practices should every Unraid plugin follow?

2. Are there common pitfalls or mistakes to avoid?

3. How do you handle updates, migrations, and rollbacks?

4. Any recommendations regarding logging, security, or UI integration?

5. What should be avoided to keep a plugin stable long term?

Forgive my bluntness, but this should not be a plugin. Docker containers are the preferred way of adding services to an unRAID server, and plugins should only be considered for things that cannot be containerized because they require direct access to the host os. Docker containers (on the unRAID platform) provide crucial benefits to both end users and developers. For end users they provide a means for controlling file access and resource allocation for services that is not available for bare metal plugins. Additionally they protect the stability of the core NAS functionality of unRAID by insulating services in containers. For the developer they address many of your questions above by allowing your service to run in its preferred environment without relying on the stripped down distro that unRAID runs on or having to handle the many versions of unRAID that are currently still in wide use (being essentially a network appliance many users rarely if ever update their systems). In the specific case of you proposed app, the fact that it runs its own webserver, interacts with borg (which i have long said also belongs in a container), and is python based (which does not belong directly on the host system) it is the perfect example of something which would be better served as a container. If the reason for making this a plugin is the want to directly integrate the ui with the unRAID webgui then something link this https://forums.unraid.net/topic/57109-plugin-custom-tab/ is a better solution.

Edited May 12May 12 by primeval_god

2 hours ago, primeval_god said:

Forgive my bluntness, but this should not be a plugin. Docker containers are the preferred way of adding services to an unRAID server, and plugins should only be considered for things that cannot be containerized because they require direct access to the host os. Docker containers (on the unRAID platform) provide crucial benefits to both end users and developers. For end users they provide a means for controlling file access and resource allocation for services that is not available for bare metal plugins. Additionally they protect the stability of the core NAS functionality of unRAID by insulating services in containers. For the developer they address many of your questions above by allowing your service to run in its preferred environment without relying on the stripped down distro that unRAID runs on or having to handle the many versions of unRAID that are currently still in wide use (being essentially a network appliance many users rarely if ever update their systems). In the specific case of you proposed app, the fact that it runs its own webserver, interacts with borg (which i have long said also belongs in a container), and is python based (which does not belong directly on the host system) it is the perfect example of something which would be better served as a container. If the reason for making this a plugin is the want to directly integrate the ui with the unRAID webgui then something link this https://forums.unraid.net/topic/57109-plugin-custom-tab/ is a better solution.

Thanks, that makes sense.

One reason I initially considered the plugin approach is that there are also existing Unraid plugins such as unBALANCE which run a background service / web UI and interact directly with the array.

My thinking was similar: backup and restore operations are very closely tied to Unraid paths, shares, disks, permissions, locks, logs, and the overall NAS workflow.

That said, I understand that Borg Backup UI is more like a full application than a small helper plugin, especially because it includes its own web server, Python code, and a bundled Borg binary.

So maybe the better long-term architecture could be:

a Docker container for the Borg UI backend/runtime

a small Unraid plugin only for native UI integration, launcher/settings link, and possibly lifecycle management

That would keep the actual service isolated while still offering a native Unraid user experience.

I appreciate the feedback — I think this is exactly the kind of architectural discussion I was hoping for.

7 minutes ago, Thorsten said:

Thanks, that makes sense.

One reason I initially considered the plugin approach is that there are also existing Unraid plugins such as unBALANCE which run a background service / web UI and interact directly with the array.

Dont quote me on this but the original unBalance plugin may actually predate the inclusion of docker in unRAID. That said these days it probably could be done within a container, though it does make use of one of the under-the-hood details of unRAID which might make path configuration confusing for users (that being the need to access both user and disk shares).

12 minutes ago, Thorsten said:

My thinking was similar: backup and restore operations are very closely tied to Unraid paths, shares, disks, permissions, locks, logs, and the overall NAS workflow.

I understand your thinking but i would disagree. I personally handle backup using a containerized version of urBackup. I map the parts of my array that require backup into it via read only mount points (including disk shares). It has dedicated rw mappings for is config, storage, and tmp locations. This ensures during normal operations it only has access to the parts of the system that it needs. The only complication is on restore at which point I have to either change the ro mapping to rw to do an inplace restore, or restore to rw directory and move the files.

22 minutes ago, Thorsten said:

a small Unraid plugin only for native UI integration, launcher/settings link, and possibly lifecycle management

I am not certain there are many if any examples of an architecture like this with a plugin front end and a container backend, however I think it is a great idea. Perhaps you can set the standard for split plugin/docker services.

That is actually one of the reasons why I am still not fully convinced that a pure container-based approach would fit the project well.

The application is not only intended to be a Borg web interface. It is also designed as an Unraid-specific backup orchestration tool that interacts quite deeply with the host system.

For example, when backing up the appdata directory, the application can automatically stop running Docker containers before the backup starts and then restart them afterwards based on their configured startup priority.

The same applies to VMs. The application detects currently running VMs, checks for logged-in users, sends notifications, waits for a configurable grace period, shuts the VMs down cleanly, performs the backup, and then starts the VMs again afterwards.

From my current understanding, implementing this inside a container would require rather extensive host integration, including access to Docker management, libvirt, Unraid-specific commands, notifications, sockets, and potentially privileged access.

At that point, the container would no longer be a simple isolated application container but would effectively become a host orchestration component with broad system-level permissions.

That is why I currently see the project as something slightly different from a typical standalone web application. It is evolving more into an Unraid-native backup orchestration system that coordinates backups together with Docker containers, VMs, shares, and host-level workflows.

I am still evaluating where the best architectural boundary should be, but this is one of the main reasons why I initially chose the plugin approach.

7 hours ago, Thorsten said:

The application is not only intended to be a Borg web interface. It is also designed as an Unraid-specific backup orchestration tool that interacts quite deeply with the host system.

For example, when backing up the appdata directory, the application can automatically stop running Docker containers before the backup starts and then restart them afterwards based on their configured startup priority.

The same applies to VMs. The application detects currently running VMs, checks for logged-in users, sends notifications, waits for a configurable grace period, shuts the VMs down cleanly, performs the backup, and then starts the VMs again afterwards.

Ah see I didnt catch that from your initial post, I read it as just a webui component for borg. That said all of my above points still stand. Putting everything in a plugin will require more maintenance effort long term.

Hi,

It's possible to test it ?

🎉 It’s official!

A huge thank you to everyone for your support and especially for helping with the testing! 🙏

My plugin has now been approved by Unraid and is available through Community Applications (CA) as a Beta. 🚀

Development will of course continue, so feedback, suggestions, improvements, and feature requests are always very welcome.

Thanks again to everyone who has supported the project so far! ❤️

Help us improve Borg Backup UI – Short Feedback Survey

Hi everyone,

Borg Backup UI has now been available in Community Apps for a few days, and I would like to collect some feedback from those of you who have already installed or tested it.

The goal is to continuously improve the plugin, especially regarding:

• Installation and initial setup

• Creating your first repository and backup job

• UI clarity and usability

• Problems or errors

• Missing features

• Preferred communication channels for future feedback

The survey is very short and should only take about 2 minutes.

Feedback is also very welcome if everything worked without any problems. Knowing what already works well is just as valuable as knowing what needs improvement.

👉 Survey: https://forms.gle/EqVNi4jNRjDbdV259

Thank you very much for your support, feedback and for helping to improve Borg Backup UI! 🙂

Is there a way to change the dashboard widget language?

Good point — i actually missed that. I’m already working on it and it should be available tomorrow. Thanks for pointing it out!

I have decided to keep the Unraid dashboard widget in English for now.

The reason is that the widget is closer to a technical Unraid integration, similar to log output and plugin status information. To keep this area consistent and easier to maintain, the widget currently uses English labels only.

The main Borg Backup UI application itself remains bilingual and supports both German and English.

This may change in the future if there is enough demand or if a good approach for localized Unraid dashboard widgets becomes clear.

New Version: 2026.08.14.1905

Hey,

I currently have the issue that I'm trying to create multiple jobs for different storage targets, but the UI will always exclusively select the first one and not acknowledge the others. For example I have 3 storage targets right now, but when I click one of the other 2 during Job creations it immediately flips back to the first one. I've tried multiple browsers as well to see if it was maybe an issue with that. So far that's the only issue I've run into.

All 3 of those storage targets use different subusers, so they are neatly divided, but in my case it always force picks the first, aka Immich for me.

Thanks for the detailed report. This definitely sounds like something I need to take a closer look at.

Could you please create a Support Package in Borg Backup UI under Settings → Import / Export and send it to me via PM?

Personal and sensitive information in the support package is automatically masked. The package is created as a ZIP file, so you can also open it and review the contents yourself before sending it to me. I think it's important that you can see exactly what information is being shared.

That should give me the information I need to investigate why the storage target selection keeps jumping back to the first entry.

Thanks for also testing it in multiple browsers — that already helps narrow things down.

And I'm glad to hear that this is the only issue you've run into so far. Thanks a lot for the feedback and testing!

Hello Thorsten,

Although I have never posted before, this time I felt compelled to share my experience.

After a long search for the perfect backup solution (at least for my specific needs), Duplicati had worked well until now, but the goal was to find something even better. Other options like Kopia or Duplicacy didn't fully meet the criteria; while fast, they lacked in ergonomics or missing features, which led to further exploration. That’s when I discovered the magnificent Borg Backup UI.

There is no issue with Borg being a plugin; on the contrary. With Duplicati (running in Docker), during a large restoration, the cache would grow so much that it saturated the Docker SSD (though this might have been due to misconfiguration ;) ).

Backups are now configured to a USB drive, a local NAS via SMB, and a remote NAS via SSH. Even without being an expert, everything was successfully set up. A minor issue occurred with SSH backups to a Synology NAS: the system kept indicating that Borg had to be installed on the Synology, but getting it to work proved difficult. Ultimately, switching to generic SSH resolved the problem without any particular issues.

The “restore test” feature is absolutely brilliant. Verifying backups is essential, something that often gets overlooked, but now it’s fully automated, so there’s no need to think about it anymore. A huge thank you for that!

There is, however, one suggestion, though I’m not sure if it’s technically feasible: in the job section, where the operation state shows “running,” would it be possible to add a progress bar or something similar with maybe the tranfrt speed ? A 6 TB backup has been running for 24 hours now, and being able to check the progress at a glance would be incredibly helpful.

Thank you again for this indispensable tool.

Hi,

thank you very much for taking the time to write such detailed feedback — I really appreciate it.

It’s great to hear that Borg Backup UI fits your setup well and that you were able to configure backups to USB, SMB and SSH successfully.

I’m especially happy that you like the restore test feature. Automated verification was one of the features I considered very important, because a backup is only really useful if you know it can actually be restored.

Thank you also for the information regarding Synology SSH. I’ll take a closer look at that and check whether the current handling or guidance for Synology targets can be improved. It is good to know that Generic SSH worked successfully as an alternative.

Regarding the running backup progress: that is definitely a useful feature request, especially for very large backups like your 6 TB job. I first need to take a closer look at what progress information Borg provides reliably while a backup is running and how this could best be represented in the UI. Ideally, information such as transferred data, transfer speed and possibly an ETA could make long-running jobs much easier to monitor.

The initial backup can take quite a long time, especially with several terabytes of data. Subsequent backups should normally be considerably faster, as Borg can make use of its cache and only needs to process the changes since the previous backup rather than handling the entire dataset in the same way again.

I’m currently on vacation, but development will continue at the end of next week. More features and improvements are already planned.

Thanks again for the feedback and for using Borg Backup UI!

Hi,

thank you for this awesome plugin. I was desperately searching for a "one-stop-shop-solution" replacing my different backup programs (Appdata-Backup, VM-Backup, Duplicati). This plugin seems to be what I am looking for.

That being said, I am testing your plugin for my different needs. One of them is my docker containers (about 20). When doing a first test-run, I saw the logs saying something about "priorities" when re-starting the containers. What is that about? I haven't found any priority-settings in your Borg-UI, nor in the Unraid Docker section. According to the log, all my containers are "priority level 3". As I do have some DB containers who should start first, I'd like to use this priority feature. How can I achieve this?

Hi @JayDee73 ,

thank you for the feedback — and yes, the restart priority feature is already implemented.

The priority is configured directly on the individual Docker container in Unraid.

Open the container settings, switch to Advanced View, and add the following under Extra Parameters:

--label backup.start.priority=1

You can assign different priority levels to different containers. Containers with a lower priority value are started first, so for example your database containers could use priority 1, dependent application containers priority 2, and everything else priority 3.

If no custom priority is configured, the container falls back to the default priority level, which is why you currently see priority level 3 in the logs.

Your feedback is very useful here, because this feature is currently not obvious enough in the UI or documentation. I’ll improve the explanation so users can actually discover and use it without having to infer it from the logs.

Thanks again for pointing this out!

Edited August 23Aug 23 by Thorsten

Great, thank you! This helps.

On to the next one. ;-)

When backing up VMs, it seems that it is "enough" to just back up the domains folder, which means the .img file of every VM. Is the file really everything one needs to get this VM going again? Let's say you backup this img file to an external backup environment and your primary Unraid system literally "burns down". Can I set up a new Unraid system, install your plugin and do a restore job (=restore the img file)? Or do I need more? For example, the well known Appdata Backup plugin offers the possibility to backup "VM meta data", which seems to be the /etc/libvirt/qemu folder.

35 minutes ago, JayDee73 said:

Great, thank you! This helps.

On to the next one. ;-)

When backing up VMs, it seems that it is "enough" to just back up the domains folder, which means the .img file of every VM. Is the file really everything one needs to get this VM going again? Let's say you backup this img file to an external backup environment and your primary Unraid system literally "burns down". Can I set up a new Unraid system, install your plugin and do a restore job (=restore the img file)? Or do I need more? For example, the well known Appdata Backup plugin offers the possibility to backup "VM meta data", which seems to be the /etc/libvirt/qemu folder.

Hi,

you are right that backing up only the VM disk image from the domains share is not necessarily enough if the goal is a complete disaster recovery of the VM.

For my own VM backups I also include the Libvirt configuration.

The important parts are:

• The VM disk images, usually stored below /mnt/user/domains

• /etc/libvirt — especially /etc/libvirt/qemu, which contains the VM XML definitions, NVRAM-related data and snapshot metadata

• /mnt/user/system/libvirt/libvirt.img

libvirt.img is the persistent Libvirt image used by Unraid and is mounted as /etc/libvirt. It contains the VM definitions and other Libvirt configuration data.

So for a full disaster-recovery scenario — for example if the Unraid server is completely lost and has to be rebuilt — I would recommend backing up both the VM disk images and the Libvirt configuration.

Technically, /etc/libvirt/qemu contains most of the VM-specific information you would need to recreate the VMs, but backing up the complete libvirt.img as well gives you a more complete copy of the original Libvirt environment.

I’m still on vacation at the Baltic Sea (Germany) until the end of next week. After that, development will continue and more features will follow.

If you have any questions, feel free to reach out. I’m still happy to help even while I’m on vacation — only fixes and development work are a bit difficult for me at the moment. 🙂

Edited August 23Aug 23 by Thorsten

Good morning,

thanks again. So I will add this to my VM backup job.

Another one:

I have created several jobs, ran all of them (all were successfull according to the UI) and also did a restore test for every job, which also went successfully. As I was curious, I observed the live log with every task (most of the time...). With nearly every task, I encountered an "error icon" within in the live log on the upper right at one time during the task (not permanently!). But after a refresh, the icon was gone. And, as I said, the tasks themselves have finished with no errors at all.

Two examples:

Do I have to be concerned that I now have corrupted backups? As mentioned, the restore tests (Level 2) were all fine. And the backups are also listed with status success in the History tab.

PS: As you might see, I am also from Germany. ;-) But I'll stick with English here, as maybe other users around the world can also benefit from my findings.

Hi @JayDee73

thanks for reporting this.

I’ve noticed this behavior as well. As far as I can tell, this is a UI status issue in the live log streaming and not an actual Borg backup error.

While the job is still running, the live log can temporarily show "Error (Exit ?)" because the final exit code is not yet available. After the job has finished and the status is refreshed, the correct result is displayed.

You can also verify this directly in the log file. Search for the "borg create" command and check the return code when it finishes. If you see "rc 0", Borg completed the backup successfully.

So in your case, especially since:

- the jobs are shown as successful in History,

- the Borg processes completed successfully, and

- all Level 2 restore tests passed,

there is no indication that your backups are corrupted.

I already have this live-log UI issue on my list and will fix the status handling so that an unknown exit code while a process is still running is not temporarily displayed as an error.

If you’d like, you can also create a GitHub issue here so we can track it properly:

https://github.com/borgforge/borg-backup-ui/issues

Edited August 24Aug 24 by Thorsten

Is it intentional, that during a VM backup process, a warning regarding the shutdown will be thrown in Unraid notifications?

I know, a shutdown of a VM could be a scary thing 🤣, but in this case it is more of a "expected behaviour", right? So maybe this could be categorized as a informational notification (therefore a green check mark, no yellow exclamation mark)? What do you think?

Yes, I agree with you.

The VM shutdown itself is expected behavior when a VM backup is configured to stop the VM before the backup starts, so showing it as a warning is a bit misleading.

I’ll change this notification to an informational message instead.

A warning should really only be shown if something unexpected happens, for example if the VM cannot be shut down cleanly, a timeout occurs, or the VM cannot be restarted after the backup.

Thanks for pointing this out — this is a good UI/UX improvement.

Another question (and I hope I won't receive a trophy for "most annoying user" :-) ):

When backing up containers, one has to choose the appdata folder to be backed up. So far, so good. But what about the individual container configuration stored in the xml files on the flash storage? Will they also be backed up "automagically" in the background within the appdata-job? Yes, when I do have another job for the flash, the xml files will be backed up with this job. But it would be more fitting if they will be stored together with the appdata itself, won't it? What is your opinion about that?