[BUG] better documentation needed for rootless (possibly needs behavior change also)

[invario]

The bug

Firstly, thank you for UpSnap and all the work you've put in.

So while attempting to run UpSnap with a non-root user today on TrueNAS Scale 25.10.1 (Debian 12.11), I kept encountering the following error:
2026-01-10 21:52:27.002035+00:00[ERROR] 2026/01/10 16:52:27 cronjobs.go:64: socket: permission denied
...which resulted in the UI never being updated properly. Everything runs fine as root.

Further investigation led me to the UPSNAP_PING_PRIVILEGED environment variable noted in the docker-compose.yml so I first set that to false with no success. Then I set it to true and it worked, which seems wrong based on the documentation and counterintuitive:

UpSnap/backend/networking/ping.go

Lines 39 to 47 in 02b4f20

	privileged := isRoot()
	privilegedEnv := os.Getenv("UPSNAP_PING_PRIVILEGED")
	if privilegedEnv != "" {
	privileged, err = strconv.ParseBool(privilegedEnv)
	if err != nil {
	privileged = false
	}
	}
	pinger.SetPrivileged(privileged)

It seems that without the UPSNAP_PING_PRIVILEGED=false, it will still check for root and use an unprivileged ping. So setting UPSNAP_PING_PRIVILEGED=false isn't 100% necessary. But the reason why I had to set it to true instead is as follows:
https://pkg.go.dev/github.com/asmpro/go-ping#readme-note-on-linux-support

Note on Linux Support:
This library attempts to send an "unprivileged" ping via UDP. On linux, this must be enabled by setting

sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
If you do not wish to do this, you can set pinger.SetPrivileged(true) and use setcap to allow your binary using go-ping to bind to raw sockets (or just run as super-user):

setcap cap_net_raw=+ep /bin/go-ping

I quickly verified that NET_RAW capability was already granted to the container (it was) and that the issue was net.ipv4.ping_group_range was not set to 0 2147483647 (it was set to 1 0).

I don't know if anyone else has run into this problem yet, but this threw me for a loop and I think some better/corrected documentation in the docker-compose.yml and Wiki needs to be made. I'll submit proposed changes shortly for that.

However, my question is this: is a behavior modification for UpSnap a good idea?

If a container is running rootless, but it has the proper NET_RAW capability, then UpSnap shouldn't be attempting to use an unprivileged UDP ping which may or may not require additional user action (either I have to sudo sysctl -w net.ipv4.ping_group_range="0 2147483647" on the host, or else I have to counterintuitively set UPSNAP_PING_PRIVILEGED=TRUE)

It seems there should be a better way to do this.

The OS that UpSnap is running on

TrueNAS Scale 25.10.1 (Debian 12.11)

Version of UpSnap

5.2.7

Your docker-compose.yml content

services:
  upsnap:
    environment:
      TZ: America/New_York
      UPSNAP_PING_PRIVILEGED: 'TRUE'
    group_add:
      - 568
    hostname: upsnap
    image: seriousm4x/upsnap:5.2.7
    network_mode: host
    platform: linux/amd64
    privileged: False
    pull_policy: missing
    restart: unless-stopped
    stdin_open: False
    tty: False
    user: '568:568'
    volumes:
      - bind:
          create_host_path: False
          propagation: rprivate
        read_only: False
        source: /mnt/MyPool/upsnap
        target: /app/pb_data
        type: bind
volumes: {}

The above docker-compose.yml is the working one on my host.

Reproduction steps

1.Run image as rootless
2.Note above described behavior

Additional information

No response

[seriousm4x]

Thanks for the detailed explaination. I never ran into this so far but also I'm not using the feature myself.

Your explaination makes sense and I think an improved logic is needed here. I'm open for PRs since I don't know when I find the time to do it myself.

I have merged your comment in the docker-compose.

[invario]

Thanks for the merge. I'll work on something and testing it before I push a PR. 👍

[invario]

Just notes for my own sanity and anyone else interested while I think if there is a better way to do this: the following applies to hosts based on Linux only. For Windows, Pinger.SetPrivileged must be set for true per GO docs.

Privileged Ping (ICMP) (UPSNAP_PING_PRIVILEGED='TRUE')

• Capabilities required: NET_RAW / CAP_NET_RAW
• User: root, works, no further action needed
• User: non-root, works only if security_opts: no-new-privileges=true is NOT set

Unprivileged Ping (UDP) (UPSNAP_PING_PRIVILEGED='FALSE')

• Capabilities required: none for unprivileged ping itself, but due to Dockerfile having setcap 'cap_net_raw=+ep' ./upsnap, the executable will not be able to run on startup if NET_RAW capability is dropped via cap_drop. You will get:
  sh: ./upsnap: Operation not permitted
  Therefore, NET_RAW is required.
• Unprivileged ping, regardless of user, on Linux, requires sudo sysctl -w net.ipv4.ping_group_range="0 2147483647" on the host and from my understanding, a lot of hosts are set to 1 0 which will result in a socket permission denied error during the ping cronjob.

Based on the above, I'm considering the following:

1. Do nothing, make documentation in Docker-compose clear that NET_RAW is always, always required, even if using the unprivileged ping (due to setcap on the executable). Also, explicitly add a line regarding no-new-privileges to describe behavior.
2. OR have an upsnap-rootless copy of the executable that doesn't have the cap_net_raw capability tied to it. Make an entrypoint.sh check for UPSNAP_PING_PRIVILEGED variable, and if false, run the upsnap-rootless binary instead.
3. Something else (still thinking.)