Adguard home

[BrokenOnedroid]

General information on project

This pull request proposes to add a new rock-on for the following project:

• name: AdGuard Home
• website: https://github.com/AdguardTeam/AdGuardHome
• description: Free and open source, powerful network-wide ads & trackers blocking DNS server.
  Fixes New Rockon using AdGuard Home #403

Information on docker image

• docker image: https://hub.docker.com/r/adguard/adguardhome
• is an official docker image available for this project?: yes

Checklist

• Passes JSONlint validation
• Entry added to root.json in alphabetical order (for new rock-on only)
• "description" object lists and links to the docker image used
• "description" object provides information on the image's particularities (advantage over another existing rock-on for the same project, for instance)
• "website" object links to project's main website

[Hooverdan96]

@BrokenOnedroid is this different from what, for example our pi-hole Rockon provides?

[Hooverdan96]

Well, reading the github page for it, it provides a matrix of same/different ...

https://github.com/AdguardTeam/AdGuardHome

Thanks for submitting this. I think it could be a complementary/alternative offering on Rockstor, since there is overlap but also a few key differences.

[BrokenOnedroid]

Using pi-hole didn't work as well for me as Adguard did. As I have already created the rock-on, I can also submit it.

[kanecko]

I don't see why adguard shouldn't be in Rockstor.

[BrokenOnedroid]

I going to update the volumes. I checked them and there empty .
Looking at the official example they have to be set to:
/opt/adguardhome/work & /opt/adguardhome/conf

[phillxnet]

@BrokenOnedroid Thanks for submitting this Rock-on - a nice counterpart to our Pi-hole by the looks of it.
@Hooverdan96 Can we remove the needs review once this is ready.
@kanecko & @FroggyFlox Thanks for the review and advice on this one.

My tendency re our user visible wording is that we should tent to be brief. Working on what I hope will be an example of where I think we should be going on this front. Full agree that we should at least have a high-level (brief) description though of purpose though.

Happy to publish once it has @Hooverdan96's say-so.

[phillxnet]

@BrokenOnedroid One can move a pull request in and out of Draft mode: i.e. if it is a work-in-progress the draft status is good, and you can leave a comment as to remaining issues that you would like comment on etc. And once all looks to be working at your end, move the pull request out of draft status.

I just noticed more changes since my last comment was all. Nice catch on those internal directories. Always good to check that intended persistent data is actually persisted :).

[Hooverdan96]

@BrokenOnedroid I am probably doing something incorrectly, but somehow I can't connect to the web address of the adguard container.

I created the macvlan using your example syntax (my machine also has eth0 as its NIC id) and configured and installed the adguard item. However, upon trying to connect to 192.168.178.58:3000 (from a different machine) it does not reach the container, pinging it also does not produce any results. Am I missing anything in particular? The docker logs show nothing unusual (i.e. no error messages).

[Hooverdan96]

ok, I think I finally understood the macvlan values that might be needed. I ended up using the same network as the host (192.168.0.0/24), specified an address in that space (192.168.0.58/32) and used the gateway that the host is connected to (192.168.0.1). That then finally gave access to the initial configuration page at 192.168.0.58:3000.

Fundamentally, I don't think any ports need to be mapped really, since this is running on the macvlan network and all ports are exposed by the application.

I will test some more.

[Hooverdan96]

docker inspect adguard

...
        "Config": {
            "Hostname": "c331b7a7cddc",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "ExposedPorts": {
                "3000/tcp": {},
                "3000/udp": {},
                "443/tcp": {},
                "443/udp": {},
                "53/tcp": {},
                "53/udp": {},
                "5443/tcp": {},
                "5443/udp": {},
                "6060/tcp": {},
                "67/udp": {},
                "68/udp": {},
                "784/tcp": {},
                "784/udp": {},
                "80/tcp": {},
                "853/tcp": {},
                "853/udp": {}
...

meaning, it behaves like net=host, i.e. no port mappings are required for the Rockon definition. Since for adguard home there essentially three UI related ports in play between which the user needs to choose, it probably makes no sense to designate any of the three as UI port for the Rockon UI button:

3000 needs to be used once only for the initial setup/configuration of Adguard
80 or 443 are the difference between http vs https for regular access after the configuration. By default it reroutes to port 80 after the initial install.
So, if anything port 80 could be exposed in Rockon UI. Anybody using SSL etc, has to perform some additional config anyway. But I did notice that (probably because of the macvlan) the link to port 80 is not correctly set up (after I removed the other ports and only kept port 80) ... so likely no ports should be/need to be defined but referenced to the documentation for the relevant ones.

New test instance: creating macvlan network:

docker network create -d macvlan --subnet=172.16.0.0/24 --ip-range=172.16.0.254/32 --gateway=172.16.0.1 -o parent=eth0 adguard-home

Test after install going to: http://172.16.0.254:3000

picking eth0 as the WebUI access as well as the DNS server address

set up administrative user, choosing admin and password for testing:

additional instructions screen:

Final screen, pressing Uebersicht oeffnen

automatically rerouted to: http://172.16.0.54

Login and overview page:

Confirming that configuration file in mapped share was created:

-rw------- 1 root  root 3755 Dec 10 17:04 AdGuardHome.yaml

Pinging address from external machine is successful.

However, macvlan is not allowing the host machine to connect to the address (isolation) directly. But setting AdGuard as the DNS server on the home router will prevent from this being a problem? @BrokenOnedroid any clarifications/suggestions, since you've been using it? I can't test this with my network setup without lots of effort at this time.

as an aside on macvlans. Found this, but hopefully not necessary:
Found this here, where a second macvlan interface is required for the communication between host and container:
https://blog.oddbit.com/post/2018-03-12-using-docker-macvlan-networks/

[BrokenOnedroid]

@Hooverdan96 I am not using a second macvlan.
I have no problem using Adguard as a DNS server. My router is the DHCP server in my network, which sets my Adguard installation as DNS-Server network-wide.
I just checked my query log again:

• Plain DNS works
• i can force encryption and at least DNS-over-HTTPS and DNS-over-TLS works

My guess is that unless you can add an IP or domain to the UI-Button setting, the Button won't work because the container does not use the same IP as the host (since it's using the macvlan) Is it possible to disable the UI-button for an container?
Using: "ui": false?

[Hooverdan96]

Ok, that's good to know then, and I take that as proof that it will work as you described.

Yes, you can actually just remove the ui tag (or set it to false for now), then the UI button will not be created/visible. I think it will then be good to add yet another piece of text to the description to indicate how to access the WebUI for the first time (using your example of the macvlan you described).

If/when you or someone else can submit a write-up for this Rockon for the documentation, we can then pare back the description substantially and just reference to the documentation for details and examples. This would bring us then closer @phillxnet's intent on having less of the descriptions on the Rockon page itself.

[Hooverdan96]

Thanks for pushing the update @BrokenOnedroid. I tried it and it looks good.

I'm thinking, since we now don't have any Rockstor WebUI relevant ports anymore, and the net= option is activate (using the macvlan), that the port specifications are not really needed at all anymore (and as described above one can see that none of the ports are really mapped into the docker container when inspecting it).

So I am proposing to remove the port section from the Rockon entirely (leaving the share mapping only). The initial port for access (3000) you've added to the description and the other ones can be found in the documentation (after some looking around).

Does that make sense?

[BrokenOnedroid]

@Hooverdan96 I removed the port defintion in my private installation and reinstalled the rockon. Seems to be working fine.
So I'm going to remove the port section.

[Hooverdan96]

This works nicely. Retested it with this PR, I get the same screen sequence and setup path as before.

[Hooverdan96]

@phillxnet, functionalitywise it's working with substantially less input fields. In turn, the description has become somewhat bigger, but as mentioned before, if/when there is a writeup it could be linked to that and the details be removed.

[phillxnet]

Tested via instructions provided in Rock-on Description only:

docker network create -d macvlan --subnet=192.168.178.0/24 --ip-range=192.168.178.58/32 --gateway=192.168.178.1 -o parent=eth0 adguard-home

Confirmed via:

rleap15-6:~ # docker network list | grep adguard-home
0ac1640ffa03   adguard-home            macvlan   local

Install with default rights on clean shares gives a failed install:

Dec 17 18:14:37 rleap15-6 dockerd[16236]: time="2024-12-17T18:14:37.623361592Z" level=warning msg="macvlan driver does not support port exposures"
Dec 17 18:14:37 rleap15-6 dockerd[16236]: time="2024-12-17T18:14:37.736953252Z" level=error msg="Handler for POST /v1.44/containers/191e7b65ecfff54a27738b53f8811d2fabd8f62e3e78752cf6bbd4802f14d10a/start returned error: failed to create the macvlan port: operation not supported"

Test machine was a Leap 15.6 KVM instance with Rockstor 5.0.15-0 rpm install.

Any ideas on this one. Again, reluctant to publish as-is given there is only a failed install from a fresh install at my end.

@Hooverdan96 The tested state of this Rock-on also exhibited for me: rockstor/rockstor-core#2913 which is expected given no envs.

[BrokenOnedroid]

@phillxnet
i remove the macvlan and recreated it without problems:

The logs for adguard are from a fresh install on newly created shares for config and data.

Settings:

interface is reachable:

And after a fast config:

System is running Rockstor version: 5.0.15-0

The only problem i ran into was removing and recreating the macvlan and then trying to start the existing rockon without deinstallation:

[Hooverdan96]

The only problem i ran into was removing and recreating the macvlan and then trying to start the existing rockon without deinstallation

which makes sense, since the UUID of the network is "tied" into the docker configuration.

@phillxnet, what I found is, since I use a different gateway/IP address range, and my test instance was in yet another address space, I couldn't get it to come up. Once I sacrificed my "official" machine, and aligned the macvlan to my physical network, I had the same experience as @BrokenOnedroid showed above. So, not sure whether your test gateway was corresponding to the instruction example and hence caused some issues?

the port message you listed above, I don't remember seeing that, and with the latest "look ma, no ports!" version I am surprised that this would even come up. But, then again I have not really used macvlans very much.

[Hooverdan96]

So, and sorry to you @BrokenOnedroid for yet another change, may be in the description we should point out that:

The subnet and gateway for your Macvlan network should match those of your Docker host. You can modify these values to suit your environment.

While that is probably self-evident for a regular user of macvlans and someone that logically thinks about networking 😄, it wasn't to me until I read a bit more on that.

@phillxnet what do you think?

[BrokenOnedroid]

@Hooverdan96 I guess it would be easier to move the instructions into a write-up. The quantity of Text is bit to much. I think.
The the Rockon description can link to the write-up. Or how to expect to the user to find the instructions?
So I changing the PR to draft.

And I'm going to take a look a creating a write-up.
I don't expect to have any time for that before January.

[Hooverdan96]

@BrokenOnedroid, thank you! Have some restful holidays.

Just for reference, here's the usual location where write-ups for a number of Rockons has been placed:
https://github.com/rockstor/rockstor-doc/tree/master/interface/docker-based-rock-ons

[Hooverdan96]

Now that the corresponding documentation has been merged by @phillxnet here #517 this Rockon should be ready as well.

@phillxnet, @BrokenOnedroid put the link to the Rockons with write-ups section. Should it point directly to the actual write-up here: https://rockstor.com/docs/interface/docker-based-rock-ons/adguard-home.html or is the section a better choice, in case the documentation is restructured in the future. Probably doesn't make much of a difference, though, especially since AdGuard currently is the first one in the list ...

[phillxnet]

@Hooverdan96 Re:

Should it point directly to the actual write-up here: https://rockstor.com/docs/interface/docker-based-rock-ons/adguard-home.html ...

I think ideally so yes. That way we avoid folks then wondering what they are looking at: i.e. a list of stuff they know-not. So better if we link to the specific doc really. As to broken links post restructuring: we generally guard against this whenever we do a restructure via our redirect directive added by @FroggyFlox some time ago in "Reorganize Table Of Content ..., i.e. the following file:

• https://github.com/rockstor/rockstor-doc/blob/master/redirects.txt

as the config for sphinxext-rediraffe extension.

Like you did when we restructured/renamed our old v3 to v4 migration doc here:

• "refactor centos to opensuse migration ...": refactor centos to opensuse migration (#485) rockstor-doc#508

[Hooverdan96]

@BrokenOnedroid I put a suggestion above with the direct link to your write-up. If agreed, commit suggestion and then @phillxnet can do a final review and hopefully merge this nice Rockon.

[phillxnet]

Just re-tested according to the new doc, i.e. creating the vlan before install, and change only the rights on the data share.

I get a failed install with the following result:

[25/Jan/2025 15:30:18] INFO [storageadmin.views.rockon:504] Rock-on definitions retrieved in: 0.11 seconds.
[25/Jan/2025 15:32:41] INFO [storageadmin.tasks:55] Now executing Huey task [install], id: ae7284d4-19db-4ead-ba23-e99bb1a225e0.
[25/Jan/2025 15:32:41] ERROR [system.osi:287] non-zero code(1) returned by command: ['/usr/bin/docker', 'stop', 'adguard']. output: [''] error: ['Error response from daemon: No such container: adguard', '']
[25/Jan/2025 15:32:41] ERROR [system.osi:287] non-zero code(1) returned by command: ['/usr/bin/docker', 'rm', 'adguard']. output: [''] error: ['Error response from daemon: No such container: adguard', '']
[25/Jan/2025 15:32:49] ERROR [system.osi:287] non-zero code(125) returned by command: ['/usr/bin/docker', 'run', '-d', '--restart=unless-stopped', '--name', 'adguard', '-v', '/mnt2/adguard_config:/opt/adguardhome/conf', '-v', '/mnt2/adguard_data:/opt/adguardhome/work', '-v', '/etc/localtime:/etc/localtime:ro', '--net=adguard-home', 'adguard/adguardhome:latest']. output: ['f74e0275c44118435690f20a11d6b00581ebaf72ce9e3acf9d132edff4e1ca39', ''] error: ['docker: Error response from daemon: failed to create the macvlan port: operation not supported.', '']
[25/Jan/2025 15:32:49] ERROR [storageadmin.views.rockon_helpers:206] Error running a command. cmd = /usr/bin/docker run -d --restart=unless-stopped --name adguard -v /mnt2/adguard_config:/opt/adguardhome/conf -v /mnt2/adguard_data:/opt/adguardhome/work -v /etc/localtime:/etc/localtime:ro --net=adguard-home adguard/adguardhome:latest. rc = 125. stdout = ['f74e0275c44118435690f20a11d6b00581ebaf72ce9e3acf9d132edff4e1ca39', '']. stderr = ['docker: Error response from daemon: failed to create the macvlan port: operation not supported.', '']
Traceback (most recent call last):
  File "/opt/rockstor/src/rockstor/storageadmin/views/rockon_helpers.py", line 203, in install
    globals().get("{}_install".format(rockon.name.lower()), generic_install)(rockon)
  File "/opt/rockstor/src/rockstor/storageadmin/views/rockon_helpers.py", line 389, in generic_install
    run_command(cmd, log=True)
  File "/opt/rockstor/src/rockstor/system/osi.py", line 289, in run_command
    raise CommandException(cmd, out, err, rc)
system.exceptions.CommandException: Error running a command. cmd = /usr/bin/docker run -d --restart=unless-stopped --name adguard -v /mnt2/adguard_config:/opt/adguardhome/conf -v /mnt2/adguard_data:/opt/adguardhome/work -v /etc/localtime:/etc/localtime:ro --net=adguard-home adguard/adguardhome:latest. rc = 125. stdout = ['f74e0275c44118435690f20a11d6b00581ebaf72ce9e3acf9d132edff4e1ca39', '']. stderr = ['docker: Error response from daemon: failed to create the macvlan port: operation not supported.', '']
[25/Jan/2025 15:32:49] INFO [storageadmin.tasks:63] Task [install], id: ae7284d4-19db-4ead-ba23-e99bb1a225e0 completed OK

So can't merge yet as can't install as per docs. What am I doing wrong here? And is this a doc or Rock-on issue?

The IP definitions I used now matches my local network according to the new doc:
i.e. local network as 192.168.2.0/24 so used:

pre-creation of vlan as per docs:

rleap15-6:~ # sudo docker network create -d macvlan --subnet=192.168.2.0/24 --ip-range=192.168.2.99/32 --gateway=192.168.2.1 -o parent=eth0 adguard-home
48fa51952b72063e1a157c4984475c268a66b90bc55013ae371055c3f0343583

Where 192.168.2.99 lies outside the DHCP range employed, and is not otherwise assigned/used, as the docs suggest.

Rockstor log:

[25/Jan/2025 15:30:18] INFO [storageadmin.views.rockon:504] Rock-on definitions retrieved in: 0.11 seconds.
[25/Jan/2025 15:32:41] INFO [storageadmin.tasks:55] Now executing Huey task [install], id: ae7284d4-19db-4ead-ba23-e99bb1a225e0.
[25/Jan/2025 15:32:41] ERROR [system.osi:287] non-zero code(1) returned by command: ['/usr/bin/docker', 'stop', 'adguard']. output: [''] error: ['Error response from daemon: No such container: adguard', '']
[25/Jan/2025 15:32:41] ERROR [system.osi:287] non-zero code(1) returned by command: ['/usr/bin/docker', 'rm', 'adguard']. output: [''] error: ['Error response from daemon: No such container: adguard', '']
[25/Jan/2025 15:32:49] ERROR [system.osi:287] non-zero code(125) returned by command: ['/usr/bin/docker', 'run', '-d', '--restart=unless-stopped', '--name', 'adguard', '-v', '/mnt2/adguard_config:/opt/adguardhome/conf', '-v', '/mnt2/adguard_data:/opt/adguardhome/work', '-v', '/etc/localtime:/etc/localtime:ro', '--net=adguard-home', 'adguard/adguardhome:latest']. output: ['f74e0275c44118435690f20a11d6b00581ebaf72ce9e3acf9d132edff4e1ca39', ''] error: ['docker: Error response from daemon: failed to create the macvlan port: operation not supported.', '']
[25/Jan/2025 15:32:49] ERROR [storageadmin.views.rockon_helpers:206] Error running a command. cmd = /usr/bin/docker run -d --restart=unless-stopped --name adguard -v /mnt2/adguard_config:/opt/adguardhome/conf -v /mnt2/adguard_data:/opt/adguardhome/work -v /etc/localtime:/etc/localtime:ro --net=adguard-home adguard/adguardhome:latest. rc = 125. stdout = ['f74e0275c44118435690f20a11d6b00581ebaf72ce9e3acf9d132edff4e1ca39', '']. stderr = ['docker: Error response from daemon: failed to create the macvlan port: operation not supported.', '']
Traceback (most recent call last):
  File "/opt/rockstor/src/rockstor/storageadmin/views/rockon_helpers.py", line 203, in install
    globals().get("{}_install".format(rockon.name.lower()), generic_install)(rockon)
  File "/opt/rockstor/src/rockstor/storageadmin/views/rockon_helpers.py", line 389, in generic_install
    run_command(cmd, log=True)
  File "/opt/rockstor/src/rockstor/system/osi.py", line 289, in run_command
    raise CommandException(cmd, out, err, rc)
system.exceptions.CommandException: Error running a command. cmd = /usr/bin/docker run -d --restart=unless-stopped --name adguard -v /mnt2/adguard_config:/opt/adguardhome/conf -v /mnt2/adguard_data:/opt/adguardhome/work -v /etc/localtime:/etc/localtime:ro --net=adguard-home adguard/adguardhome:latest. rc = 125. stdout = ['f74e0275c44118435690f20a11d6b00581ebaf72ce9e3acf9d132edff4e1ca39', '']. stderr = ['docker: Error response from daemon: failed to create the macvlan port: operation not supported.', '']
[25/Jan/2025 15:32:49] INFO [storageadmin.tasks:63] Task [install], id: ae7284d4-19db-4ead-ba23-e99bb1a225e0 completed OK

All shares, including rockon-root were created prior to the install test.

My apologies if I've missed something obvious here.

[phillxnet]

@Hooverdan96 & @BrokenOnedroid On my review and experience to date here:

"failed to create the macvlan port: operation not supported."

Could this be an artifact of my particular KVM setup. The test system in this case is running in a KVM instance which itself has an eth0 that is bridged to the local network. Maybe this is exercising a limitation of the particular approach taken by this docker arrangement? Given you have both apparently proven function here.

@Hooverdan96 if you review and find all is dandy, I'm happy to merge and publish based on that, as we can at least then get this out for broader testing/experimentation/feedback.

[Hooverdan96]

I'll take a look shortly. I've been running my tests using Virtualbox that contains a bridged adapter. But that might not be the same as your bridged eth0 setup.

[Hooverdan96]

In this case the eth2 is the bridged adapter on VirtualBox. Rockstor IP: 192.168.56.103

Creating macvlan network:

docker network create -d macvlan --subnet=192.168..0/24 --ip-range=192.168.178.58/32 --gateway=192.168.178.1 -o parent=eth2 adguard-home

results in:

3fd32cf3137599009c70332722af6d1a08a4d9012cafd81635a3cb24e42e6e0a

checking on the docker networks:

rockwurst:~ # docker network ls
NETWORK ID     NAME           DRIVER    SCOPE
3fd32cf31375   adguard-home   macvlan   local
c1503f4b4460   bridge         bridge    local
b04cf05bea65   host           host      local
a5e84db75f44   none           null      local

[Hooverdan96]

I continue to run into issue accessing the macvlan in the virtual machine, though, despite that the network shows as available, because, if I understand correctly, without introducing some workaround I can't get to it from the host due to the shared network adapter.

In any case, I went ahead (again, like I did further up during the first tests) and did the testing on a designated Rockstor testing machine, creating the macvlan, install the Rockon and I end up at the installation page and am able to configure everything as before.

So, I think, for now this can be merged. If there's a simple enough workaround on how to run this on a VM and access it/manage it, then this could be added to the documentation subsequently.

[Hooverdan96]

Well, here's the workaround for VirtualBox at least. The bridged adapter defined for the VM needs to be set to promiscuous mode in the Settings before the Linux guest is started.
Once started, the same network adapter within the guest also needs to be set to promiscious:

Find the relevant adapter (altname), e.g.:
ip addr show, e.g. enp0s8
then
ip link set enp0s8 promisc on

then set up the macvlan network considering the host's associated gateway, subnet and a specific IP address like in the instructions.
Then install the adguard Rockon. Go to the macvlan's network address and port (if you can't remember offhand, just use docker logs adguard to find it after startup).

That should now allow for "outside" system to access the starting page/admin page after setup.

This is good for testing. To make this behavior permanent, from what I found one could likely use one of the two methods described here:

https://askubuntu.com/questions/1355974/how-to-enable-promiscuous-mode-permanently-on-a-nic-managed-by-networkmanager

I tried method 2 (creating a service unit) and that seems to work.

I created the service unit as:

/etc/systemd/system/bridge-promisc.service

and put this in there (assuming that the connection name was enp0s8)

[Unit]
Description=Makes interface(s) run in promiscuous mode at boot
After=network-online.target

[Service]
Type=oneshot
ExecStart=ip link set enp0s8 promisc on
TimeoutStartSec=0
RemainAfterExit=yes

[Install]
WantedBy=default.target

but maybe there's a better option.