POC: SnapRAID API ?

[firsttris]

Hey,

I’ve been using SnapRAID for almost 10 years now on my home server. To this day, it’s still my preferred solution.
It saved me many times.

For a long time, I thought it would be great to have a Web UI for controlling and monitoring SnapRAID, but I never had the time to explore the idea properly.

Also, from time to time I see people on Reddit requesting such a feature:
https://www.reddit.com/r/Snapraid/comments/1h32mdn/any_good_gui_for_snapraid/

https://www.reddit.com/r/Snapraid/comments/1ha3468/snapraid_ui/

https://www.reddit.com/r/DataHoarder/comments/2s0zg8/management_and_monitoring_for_snapraid/

There is a native Windows application called Elucidate, but since I'm a Linux user and want something that runs directly on the server, that wasn’t really an option.

Also, OpenMediaVault has (or had) a WebUI plugin for SnapRAID, but I manily use Arch and Fedora.

Because I have a strong background in TypeScript, and since there’s still no good solution in 2025, I thought it would be a fun project to build a SnapRAID Web UI with Docker/Podman support myself:
https://github.com/firsttris/snapraid-ui

Since SnapRAID doesn’t have many commands, I assumed it wouldn’t be too difficult.

However, because SnapRAID is strictly a command-line tool, it doesn’t provide an API. Parsing plain stdout to understand what happened is cumbersome, brittle, and likely to break over time.

So I started wondering whether SnapRAID could expose some form of API.

Implementing a socket-based API would probably be a much larger task.
But adding a simple --json command-line option to output structured data (or JSON streaming for commands like sync and scrub) seems far more realistic to implement.

To understand what would be required to add such a --json option to the SnapRAID CLI, I explored the codebase. Please consider this more of a proof-of-concept to demonstrate the idea rather than a finished solution. I mainly wanted to prototype it and see what it would take.

I think it’s not entirely easy, because JSON output needs to be implemented individually for each command.

I have no experience with the C programming language,
but I still managed to get JSON output working for some commands.

Even if my Web UI project ends up not being great, such feature would make it much easier for others to build their own UIs, dashboards, or integrations for SnapRAID.

I also want to highlight that I’m completely open to better ideas or alternative approaches. If this is not the right direction, that’s totally fine — no hard feelings at all.

I’m happy to collaborate or support any effort that moves in that direction.

Examples:

tristan@AMD-B6507800X3D ~/P/snapraid-git (json-support)> ./snapraid status -c snapraid.conf --json
{"sync_event": {"type": "loading_state", "file": "/home/tristan/Downloads/SnapRAID.content"}}
{"status": {
  "header": "SnapRAID status report",
  "columns": ["Files", "Fragmented", "Excess", "Wasted", "Used", "Free", "Use", "Name"],
  "disks": [
    {"name":"test1", "files":22, "fragmented":1, "excess":1, "wasted":499.7, "used":0, "free":209, "use":0},
    {"name":"test2", "files":0, "fragmented":0, "excess":0, "wasted":-209.5, "used":0, "free":0, "use":0}
  ],
  "summary": {"files":22, "fragmented":1, "excess":1, "wasted":499.7, "used":0, "free":209, "use":0},
  "scrub": {"oldest_days": 2, "median_days": 2, "newest_days": 0},
  "graph": {"max": 259, "scrubbed": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], "new": [259,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,9,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,185,1]},
  "sync_in_progress": false,
  "scrubbed_percentage": 0,
  "zero_subsecond_files": 0,
  "rehash_in_progress": false,
  "errors": 0,
  "messages": [
    "No sync is in progress.",
    "100% of the array is not scrubbed.",
    "No file has a zero sub-second timestamp.",
    "No rehash is in progress or needed.",
    "No error detected."
  ]
}}


tristan@AMD-B6507800X3D ~/P/snapraid-git (json-support)> ./snapraid sync -c snapraid.conf --json
{"sync_event": {"type": "loading_state", "file": "/home/tristan/Downloads/SnapRAID.content"}}
{"sync_event": {"type": "scanning"}}
{"sync_event": {"type": "initializing"}}
{"sync_event": {"type": "resizing"}}
{"sync_event": {"type": "saving_state", "file": "/home/tristan/Downloads/SnapRAID.content"}}
{"sync_event": {"type": "saving_state", "file": "/mnt/4TB-NVME/TestSnap/SnapRAID.content"}}
{"sync_event": {"type": "verifying"}}
{"sync_event": {"type": "selecting"}}
{"sync_event": {"type": "syncing"}}
{"sync_progress": {"event": "begin", "blockstart": 0, "blockmax": 455, "countmax": 0}}
{"sync_progress": {"event": "end", "percentage": 100}}


tristan@AMD-B6507800X3D ~/P/snapraid-git (json-support)> ./snapraid list -c snapraid.conf --json
{"sync_event": {"type": "loading_state", "file": "/home/tristan/Downloads/SnapRAID.content"}}
{"files":[{"type":"file","path":"3001549034_Teufel_Tristan_RZ_2025-11_136,00.xlsx","size":76849,"mtime":"2025/12/01 07:54"},{"type":"file","path":"3001549034_Teufel_Tristan_RZ_2025-11_13600.pdf","size":253462,"mtime":"2025/12/04 15:46"},{"type":"file","path":"7D75v1P5.zip","size":13899516,"mtime":"2025/12/01 10:30"},{"type":"file","path":"Bescheiddaten_Einkommensteuer_2024_2836021614624.pdf","size":31496,"mtime":"2025/12/04 07:03"},{"type":"file","path":"Einkommensteuerbescheid.pdf","size":146841,"mtime":"2025/12/04 07:02"},{"type":"file","path":"Rechnung_RE0318.pdf","size":77995,"mtime":"2025/12/01 11:03"},{"type":"file","path":"Rechnung_RE0319.pdf","size":78490,"mtime":"2025/12/04 15:48"},{"type":"file","path":"Vergleich_Bescheiddaten_Einkommensteuer_2024_2836021614624222222225.pdf","size":7910,"mtime":"2025/12/04 07:03"},{"type":"file","path":"Vergleich_Bescheiddaten_Einkommensteuer_2024_2836021614624222225.pdf","size":7910,"mtime":"2025/12/04 07:03"},{"type":"file","path":"ccu3-webui-2025-12-01.sbk","size":48445440,"mtime":"2025/12/01 13:56"},{"type":"file","path":"ccu3-webui-2025-12-011.sbk","size":48445440,"mtime":"2025/12/01 13:56"},{"type":"file","path":"docker/.dockerignore","size":270,"mtime":"2025/12/07 07:40"},{"type":"file","path":"docker/Dockerfile","size":1565,"mtime":"2025/12/07 17:32"},{"type":"file","path":"docker/README.md","size":4537,"mtime":"2025/12/07 08:04"},{"type":"file","path":"docker/docker-compose.yml","size":1055,"mtime":"2025/12/07 17:32"},{"type":"file","path":"docker/entrypoint.sh","size":118,"mtime":"2025/12/07 17:32"},{"type":"file","path":"docker/nginx.conf","size":1705,"mtime":"2025/12/07 17:32"},{"type":"file","path":"docker/snapraid-app.container","size":1785,"mtime":"2025/12/07 07:55"},{"type":"file","path":"docker/snapraid-net.network","size":285,"mtime":"2025/12/07 07:40"},{"type":"file","path":"docker/supervisord.conf","size":903,"mtime":"2025/12/07 17:32"},{"type":"file","path":"snapraid.conf","size":381,"mtime":"2025/12/06 12:44"},{"type":"file","path":"test/Pflegetagebuch.png","size":3152471,"mtime":"2025/12/04 13:52"}],"list_summary":{"files":22,"size_gb":0,"links":0}}



tristan@AMD-B6507800X3D ~/P/snapraid-git (json-support)> ./snapraid diff -c snapraid.conf --json
{"sync_event": {"type": "loading_state", "file": "/home/tristan/Downloads/SnapRAID.content"}}
{"sync_event": {"type": "comparing"}}
{"diff_summary": {"equal":22,"added":0,"removed":0,"updated":0,"moved":0,"copied":0,"restored":0}}


tristan@AMD-B6507800X3D ~/P/snapraid-git (json-support)> ./snapraid check -c snapraid.conf --json
{"sync_event": {"type": "loading_state", "file": "/home/tristan/Downloads/SnapRAID.content"}}
{"sync_progress": {"event": "begin", "blockstart": 0, "blockmax": 455, "countmax": 455}}
{"sync_progress": {"event": "progress", "blockpos": 0, "countpos": 1, "countsize": 262144, "percentage": 0, "elapsed_seconds": 0}}
{"sync_progress": {"event": "end", "percentage": 100, "size_MB": 115, "elapsed_seconds": 0}}
{"check_summary": "ok"}
tristan@AMD-B6507800X3D ~/P/snapraid-git (json-support)> 

[auanasgheps]

Wow, this UI looks fantastic! Nice job!

The JSON output would be a god sense for me. I am the maintainer of the SnapRAID AIO Script and parsing the ouput as it is right now is... painful, especially tables.

Having a predictable output would be a dream!

[bobafetthotmail]

I wrote some scripts to integrate and automate snapraid functionality and I like this proposal.
Some CLI tools have a "script-friendly" option for command output and they are a lot less annoying to integrate.

off the top of my head, lsblk has the -P option to write the results in "key=value" format
lsblk -P
NAME="sda" MAJ:MIN="8:0" RM="0" SIZE="476.9G" RO="0" TYPE="disk" MOUNTPOINTS=""
NAME="sda1" MAJ:MIN="8:1" RM="0" SIZE="488M" RO="0" TYPE="part" MOUNTPOINTS=""
NAME="md127" MAJ:MIN="9:127" RM="0" SIZE="487.9M" RO="0" TYPE="raid1" MOUNTPOINTS="/boot/efi"
NAME="sda2" MAJ:MIN="8:2" RM="0" SIZE="1.9G" RO="0" TYPE="part" MOUNTPOINTS="/boot"

There are also "jsonifier" middleware projects that wrangle the stdout output of (some) CLI software and provide a json for ingest in ther programs. But these are just moving the annoyance and fragility of stdout parsing to the middleware, having a native option from the CLI software itself is probably best.
https://github.com/kellyjonbrazil/jc?tab=readme-ov-file

[amadvance]

Hi @firsttris

Thanks for the proposal. Your work on a Web UI and the prototype for JSON output is impressive, especially considering you're new to the C codebase. It clearly highlights a gap in SnapRAID's current machine-readable output.

What you suggest is similar to the existing log_tag() statements, which are designed to output structured and stable information for tools and scripts. I would like to continue to use this system, but I can use your proposal as a direct hint of what specific information is missing and what should be added.

We cannot change the existing log_tag() statements because we need to maintain backward compatibility with all the existing tools and scripts that rely on their stable format. However, we can add as many new log_tag() statements as needed to provide the data you require.

Essentially, log_tag() outputs information in the format NAME:VALUE0:VALUE1:... in the log file specified with -log. You can also force this output to stdout or stderr using the special arguments >&1 or >&2.

For example: snapraid status -l ">&2"

This keeps the structured data separate and stable, which is crucial for external monitoring tools.

Could you identify the specific information your Web UI requires that is currently difficult to parse from the standard output? We can then work together to define new, stable log_tag() entries for that data. This approach will satisfy your need for a stable API while maintaining backward compatibility for the SnapRAID project.

[firsttris]

Currently, my Web UI parses the regular stdout, not the JSON proposal. I was just experimenting to see if there might be a better approach — and it turns out there’s already a solution I hadn’t considered.

While I was using the --log option to write logs to a file, it didn’t occur to me that I could simply use -l ">&2". That actually solves it nicely.

Thanks for your help!

[MasterCATZ]

snapraid status -l ">&2"

wish I knew this sooner ...

[auanasgheps]

I wish i knew this sooner too.. it's a great thing to consider for my script. Thanks!

[amadvance]

I prepared a prerelease version of SnapRAID that includes a few new log tags and their full documentation in snapraid_log.txt. You can download it from Git or from http://ftp.snapraid.it/
Let me know if you think any useful tags are still missing or if other improvements are desired.