Run app from unprivileged user

[ammnt]

Prerequisites

• I have checked the Wiki and Discussions and found no answer

• I have searched other issues and found no duplicates

• I want to report a bug and not ask a question

Operating system type

Linux, Other (please mention the version in the description)

CPU architecture

AMD64

Installation

GitHub releases or script from README

Setup

On one machine

AdGuard Home version

0.107.23

Description

No LSB modules are available.
Distributor ID: Debian
Description: Debian GNU/Linux 11 (bullseye)
Release: 11
Codename: bullseye
Linux dns.msftcnsi.com 5.10.0-21-amd64 #1 SMP Debian 5.10.162-1 (2023-01-21) x86_64 GNU/Linux

I'm trying to run the app from unprivileged user. What I exactly do:

• added system user (Debian) adguard with system group adguard
• make 'setcap -r 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' ./AdGuardHome' from root user
• chown app directory to adguard user: chown -R adguard:adguard /opt/AdGuardHome
• change user and group fields in the .yaml config file to adguard (also tried UID and GID after that)

Still no success because:
[fatal] listen tcp 0.0.0.0:80: bind: permission denied

The verbose log is attached. Anyone tried it before?

Thank you.
Best regards!

[ammnt]

[ainar-g]

make 'setcap -r 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' ./AdGuardHome' from root user

Perhaps the Debian setcap is different from the Ubuntu one, but doesn't -r remove capabilities? What I do is:

sudo setcap 'cap_net_bind_service+ep cap_net_raw+ep' ./AdGuardHome

[ammnt]

@ainar-g, unfortunately I have the same result with these flags:

[ainar-g]

Sorry, I'm not sure what it could be then. Other than if you run it as a service, systemd might interfere with that somehow (systemctl daemon-reload?).

[ammnt]

@ainar-g, nope. Nothing changed☹️

[ainar-g]

I'll move this to discussions then, if you don't mind, as I don't think that it's an AdGuard Home issue.

[siberianspot]

Currently (version 0.107.42), installing with "-s install" arguments does not work correctly. At least on deb-based (Ubuntu 22.04) and FreeBSD (13/OPNsense). Steps i did to make first one works:
I’ve mitigated stub-dns resolver issue before at cloud-init step, but you could do it now (AdGuard Home wiki -> Docker -> Resolved https://github.com/AdguardTeam/AdGuardHome/wiki/Docker#resolved-daemon ).
Made (actually, copied the one i already have, but yaml and data only) /opt/AdGuardHome dir (instead of /opt you could use any path you want).
wget tarball with the link from releases page and tar -xf it to place executable in AdGuardHome dir.
Made a new user (adguard) and group (adguard) with --system --no-create-home --disabled-password flags. Maybe you should set home at AdGuardHome dir, but i forgot it and leave as it is.
[sudo] chown -R adguard:adguard AdGuardHome dir.
sudo setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' /opt/AdGuardHome/AdGuardHome Edit AdGuardHome.yaml at "os" section with appropriate user and group
Finally, sudo /opt/AdGuardHome/AdGuardHome -c /opt/AdGuardHome/AdGuardHome.yaml -w /opt/AdGuardHome -s install
And sudo systemctl stop AdGuardHome if it hasn’t crashed yet.
echo "/opt/AdGuardHome:${PATH}" > /etc/default/adguardhome, or fill in appropriate paths yourself instead of using the PATH var.
Edit /etc/systemd/system/AdGuardHome.service file:
Remove prestart step, delete redundant quotes from start command, replace your user’s home at WorkingDirectory with /opt/AdGuardHome (if you haven’t given adguard user sudo perm and call -s install within it), and nonexistent path at Environment with /etc/default/adguardhome you’ve created before, add User=adguard and Group=adguard to the Service section.
And i think that’s all for Ubuntu/Debian — just start the service.
FreeBSD needs rcvar to be set in AdGuardHome’s rc.conf (and in case AdGuardHome will gain SIGHUP support — it could make sense to extend service unit exposing functionality with /usr/sbin/daemon workarounds). OPNsense needs one more rc file to be created.

[Cygon]

I'm successfully running AdGuard Home on my Gentoo router.

The -s install step doesn't work on OpenRC (though, curiously, it writes a broken OpenRC init script). Here are the steps I took to set it up on my Gentoo system:

• Downloaded the AdGuardHome archive and extracted it to /opt
• Ran AdGuardHome with -s run as root user once (stderr says the first launch has to be with root privileges)
• chown'ed /opt/AdGuardHome and everything in it to an adguard system user I created via useradd
• chmod'ded /opt/AdGuardHome to 0700 (only user may access). This seems to be optional, but AdGuard Home warns if this isn't the case.
• Gave it both the privileged ports exception and (only needed when using DHCP) the raw sockets exception: setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' /opt/AdGuardHome/AdGuardHome
• I also entered the user and group in /opt/AdGuardHome/AdGuardHome.yaml but I did not verify whether this is needed or has any effect at all

It already worked from there when launched under its own user account, providing both DNS and DHCP to the local network.

To run it as a daemon, I'm using the following OpenRC service init script, but this is entirely Gentoo specific:

#!/sbin/openrc-run
# Copyright 2025 Markus Ewald
# Distributed under the terms of the GNU General Public License v2

description="AdGuard Home: Network-level blocker"

name="AdGuard Home service"

directory=/opt/AdGuardHome

command="/opt/AdGuardHome/AdGuardHome"
command_args="-s run "
command_background="yes"
command_user="adguard"
command_group="users"

output_log="/var/log/AdGuardHome/stdout.txt"
error_log="/var/log/AdGuardHome/stderr.txt"

pidfile=/var/run/AdGuardHome.pid

depend() {
        need localmount
        use net
        after clean-log-files
}

start_pre() {

        # Make sure a separate directory exists for the AdGuard log files
        if [ ! -d "/var/log/AdGuardHome" ]; then
                mkdir "/var/log/AdGuardHome"
                checkpath \
                        --directory \
                        --owner adguard:users \
                        --mode 0775 \
                        "/var/log/AdGuardHome"
        fi

}

One thing I noticed is that if I use command="AdGuardHome" in the service init script, AdGuard Home will segfault. It needs to be command="/opt/AdGuardHome/AdGuardHome" (full path) so the process' argv[0] contains the absolute path to the executable.

Finally, I made a little shell script to reapply the socket exceptions in case I need to update/replace the executable:

#!/bin/sh
setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' /opt/AdGuardHome/AdGuardHome