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