Question (Mac LaunchDaemons instruction)

[mrtargaryen]

| Version of AdGuard Home server: v0.91 macOS 10.14.2

I'm a bit new to this, I've downloaded the macOS zip files and unpacked it. I'm just wondering where do I place the executable file so I can then run "sudo ./AdGuardHome" in Terminal?

Also, in my Router is the DHCP>DNS setting, I believe I have to insert the AdGuard Home Server Address there, is the server address just the localhost:53?

Thank you for any help you can give.

[tomiams]

Hi @mrtargaryen You can place the executable anywhere you want but for best practices with minimum troubles, please follow the following steps.

1. Go to /Users/YOURUSERNAME/
2. Make a new folder with the name AdguardHome
3. Move the executable to it

Since you are going to change your whole network's DNS server to adguard home, there are going to be more steps to ensure a smooth experience.

Firstly, you want the server to start on its own with system startup, even if you did not log in, so that in case of a power failure the mac would restart and run the server without you being there so your home network isn't disrupted.

4. Go to System Preferences > Energy Saver

5. Enable the following: Wake for network access, Start up automatically after a power failure

6. Go to System Preferences > Network

7. Select the active connection you are connected to the internet with. Copy the IP Address that shows there.

8. Go to your router and add a Static IP Address (google it, steps vary according to your router model) to your mac using the IP Address you just copied. This step ensures that upon every reconnection, your mac will always use the same IP Address. This is necessary to add as the DNS server later on in the guide.

Now, to make the server start up with the mac power up.

9. Open Terminal
10. Type the following command and change YOURUSERNAME to your username. sudo chown root:wheel /Users/YOURUSERNAME/AdguardHome/AdGuardHome Type your password when prompted. This essentially makes the system own the file.
11. Open TextEdit app and create a new note
12. In the Format menu choose Make Plain Text
13. Copy and paste the following (change YOURUSERNAME with your username):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>KeepAlive</key>
    <true/>
    <key>Label</key>
    <string>com.adguardhome.script</string>
    <key>ProcessType</key>
    <string>Background</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOURUSERNAME/AdguardHome/AdGuardHome</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

14. Save it in the following location (don't press save yet) /Library/LaunchDaemons/

15. Ensure Plain Text Encoding says Unicode (UTF-8)

16. Untick If no extension is provided, use ".txt"

17. In the save as field, copy and paste this name: com.adguardhome.script.plist

18. Press Save

19. Open Terminal and type: sudo chown root:wheel /Library/LaunchDaemons/com.adguardhome.script.plist

So far, the server will start with every boot and restart itself if it failed at anytime during runtime. For the first run, there are some things to set up so you have to do the first run manually:

20. Open Terminal and type: sudo /Users/YOURUSERNAME/AdguardHome/AdGuardHome

21. Follow the instructions to set up a username and password for the server portal (where you can change adblocking settings)

22. Once everything is set, you need to test that it is running. Open a browser and type: 127.0.0.1:3000

23. Use the username and password that you just set up in Terminal If everything goes well, you will see the Adguard Home portal. We'll get back to it later.

24. Go to your router and set the DNS servers to the IP Address that you got from step 7 and made static in step 8.

25. Go to System Preferences > Network > Advanced > DNS > Delete any values you see there and put the following one in their place: 127.0.0.1

26. Restart your mac

27. Ensure that the server runs itself by going to the portal on 127.0.0.1:3000

28. Start adjusting the settings of the server to what suits you

29. Enjoy a clean web & report back on your results

[mrtargaryen]

Wow, that's a detailed reply. All I can say is thank you very much! I'll get this done, just as is written, and report back. Again thank you. I hope this post is found by others seeking the same information.

[furunos]

I think it would be better to add WorkingDirectory key for log file.

@@ -12,6 +12,8 @@
    <array>
        <string>/Users/YOURUSERNAME/AdguardHome/AdGuardHome</string>
    </array>
+   <key>WorkingDirectory</key>
+   <string>/Users/YOURUSERNAME/AdGuardHome</string>
    <key>RunAtLoad</key>
    <true/>
 </dict>

[mrtargaryen]

@furunos I'm a bit affected by strong pain killers at present so, I'm going to tackle this tomorrow, However, if you could possibly point to where what you've written would be of greater benefit that would be most helpful. And thank you for your reply, much appreciated.

[tomiams]

@mrtargaryen It's good practice to set a Working Directory for such executables with system-level permissions. You are basically 'placing' the process somewhere, like the folder in which the executable exists, as @furunos properly advises.

The edit he made is referring to the com.adguardhome.script.plist that was created in step 13 of my guide. The '+' signs that @furunos put is the change he recommends in the script. So in English he is saying: Look for these lines in the script:

    <array>
        <string>/Users/YOURUSERNAME/AdguardHome/AdGuardHome</string>
    </array>

Then add the following lines immediately after them:

    <key>WorkingDirectory</key>
    <string>/Users/YOURUSERNAME/AdGuardHome</string>

Remember that when you manually modify a system-owned file, you need to make the system re-own it again by running the command mentioned in step 19.

Disclaimer: It is important to note that, unless they explicitly mention so, Adguard Team did not review or endorse my mini guide. This is simply my own advise that can only serve as a temporary solution since multiple steps are missing to make it viable and secure for long term implementation (for example, signing the script to avoid manipulation, and so on) The reason Adguard themselves did not make a more accurate guide is probably due to the fact that this product is still in beta and, once rolled out to normal users, will not require such technical expertise to properly install. Since we are already at version 0.91, the more user-friendly versions should be expected very soon.

[ameshkov]

@tomiams thank you so much, this is an awesome instruction!

[mrtargaryen]

@tomiams Got it, nevertheless Im enjoy the challenge.

One question Im stuck on, the IP address here is the LAN IP. Is this correct, or do I require the External IP? as it is not to be found in the Preferences Panel under Network.

8. Go to your router and add a Static IP Address (google it, steps vary according to your router model) to your mac using the IP Address you just copied. This step ensures that upon every reconnection, your mac will always use the same IP Address. This is necessary to add as the DNS server later on in the guide.

[furunos]

My example is as follows...

Before: Mac IP: 192.168.0.10 Mac Preferences Panel > dns: 192.168.0.2 Router IP: 192.168.0.1

After: (AdGuardHome on mac) Mac IP: 192.168.0.10 Mac Preferences Panel > dns: 127.0.0.1 AdGuardHome > settings > Upstream DNS servers: tcp://192.168.0.2 Router IP: 192.168.0.1

[mrtargaryen]

@tomiams forgive me for this, I've gotten up to step 20

/Users/AdguardHome/AdGuardHome/

The script stored in /Library/LaunchDaemon/

Step 20: "Command Not Found"

I've double checked everything, also I deleted everything and re-redid everything and I got the same result. Obviously I'm doing something wrong.

Can you see where I'm going wrong at all? Thanks again!

[furunos]

Try the following command...

$ sudo launchctl load /Library/LaunchDaemons/com.adguardhome.script.plist

[mrtargaryen]

@furunos the service loaded but there was no setup process nor can I access the UI from 127.0.0.1:3000

[furunos]

Is the path of a program different ?

-       <string>/Users/r2d2/AdGuardHome/AdGuardHome</string>
+       <string>/Users/r2d2/AdGuardHome/AdGuardHome/AdGuardHome</string>

[mrtargaryen]

@tomiams @furunos Does this look correct (thanks for you time)

Something isn't correct ...

[furunos]

How about below ?

    <key>WorkingDirectory</key>
-   <string>/Users/r2d2/AdGuardHome</string>
+   <string>/Users/r2d2/AdGuardHome/AdGuardHome</string>

[mrtargaryen]

@furunos & @tomiams

I have no idea what I've done wrong but here are the amendments I've made, with the same result:

[tomiams]

@mrtargaryen Alright, this doesn't seem complicated as it has nothing to do with the com.adguardhome.script.plist

Please return it to its original form.

You are facing 2 problems here. The fact that in step 3 instead of copying the executable you copied the entire downloaded AdGuardHome folder into the AdGuardHome folder you made in step 2. Please simply take the executable (the black icon Unix executable) outside the folder it is currently in. So You would have /Users/r2d2/AdGuardHome/AdGuardHome The first AdGuardHome in that path is the folder. The second is the unix executable. No more folders.

That is not the main problem though.

[tomiams]

The AdGuardHome executable is fully functional on its own and so manually starting it from terminal using sudo permissions should work regardless of any plist.

And so what you did here was unluckily avoid it throughout all these commands.

The closest you were to actually running it was in this step, where you pointed to the (second) folder instead of the executable and so the terminal told you that it is not a command:

Step 20: "Command Not Found"

When you fix the directory issue as I mentioned in my last comment, however, running this same command again will let you finally manually run the executable for the first time, where you will get to set some settings.

[furunos]

I imagine as follows:

• dir /Users/r2d2/AdGuardHome/AdGuardHome
• file /Users/r2d2/AdGuardHome/AdGuardHome/AdGuardHome

Therefore, the direct execution command is as follows:

$ sudo /Users/r2d2/AdGuardHome/AdGuardHome/AdGuardHome

[tomiams]

Now that the first run is over and we got the server up and running, to make it run itself on startup, please delete the current com.adguardhome.script.plist residing in /Library/LaunchDaemons/ and empty the trash. Then redo the steps of creating it one by one in order to set the proper permissions.

Of course since the old version is already loaded on the current system boot, you will need to restart in order to properly load the new version in its place.

Finally, regarding the IP addresses issues, I should have mentioned that I was only referring to the local IP addresses that are used in your network to communicate with each other through the router. So the ip address of your mac is the ip address you will use on the other devices that you want to filter through AdGuard Home. If you change the router DNS to point to your mac, then all the devices connected to that router will also use your mac as the DNS server unless they manually change their own DNS servers. Please continue reading as this will clear up many confusions.

The trip of a request on a device on your finalized network would go something like this: iPad asks for google.com from the router > router asks for google.com from your mac > your mac asks for google.com from itself (the 127.0.0.1 ip which we used on your mac in step 25 means return the request to myself) > this is when adguardhome finally gets to take a look at google.com and sees whether it has any rule set up to block it, if so, that is the end of the trip, if Adguardhome cleared it, it will still need to ask a real DNS server for what google.com stands for and so it uses the Upstream DNS server that you can manually change, but shouldn't if you don't need to. AdGuard Home's default "real" also known as Upstream DNS server is the blazing fast 1.1.1.1 through a secure tls encryption. This is the only step in this entire process that you connected to something outside your network (the real DNS server).

But since the website you asked for got encrypted at adguardhome level, your ISP will not know that you asked for google.com

[mrtargaryen]

@tomiams My goodness, how I stuffed that up I'll never know. I'll just put it down to the pain medications Im on.

Ok, the Good: Its working, and working well (Yes I thought it would be the IP of the iMac)

The bad: Its not auto starting on boot which means I couldn't even open a website without manually starting AdGuard. Also, it did not ask me to set a Username or Password at setup.

I will re-do the steps as suggested. Also, I have Little Snitch and had to make a permanent acceptation for AdGuard ("Terminal Via AdGuardHome").

However, this is what I see right now (before I re-do everything)

Terminal is stuck at this point

Everything is correct here.

[mrtargaryen]

(Edited) Also, I've noticed AdGuard Home doesn't work nicely with VPNs (OpenVPN Clients) on routers. I have a router with custom Firmware on it. I've been using another Ad & Tracker Blocker which is an application within the router, unfortunately I have a DNS leak issue when using it. I wanted to try AdGuard Home as a way of being able to use policy routing. With the ad and tracker blocker I have been using on my router I can only use the setting ALL (traffic routed) through the VPN tunnel. I'm unable to route different clients through to the WAN and others through the VPN tunnel without my DNS leaking (ie 1.1.1.1 DNS is showing on ipleak.net & NOT the VPN Provider's DNS). When using AdGuard Home it appears that I'll have the same sort of issue.

[tomiams]

@mrtargaryen Good to hear you got it up and running!

Terminal is stuck at this point

No, it's not stuck at all. Thing is when you manually start it using the method mentioned, the terminal window will act like the working log of AdGuardHome and if you quit it you will stop AdguardHome. It is good for debugging purposes, though. So in your example, it is telling you it fetched the filter x from the the website y in order to update it but found that you already have the latest rule from that filter. So, yeah, all good.

When you get the launchdaemon plist working properly you will not be seeing the terminal window at all.

[tomiams]

And something I just tested and realised is not a good thing, it doesn't work with ProtonVPN. I have a ASUS RT-AC86U with WRT-Merlin on it. I've been using Diversion (not sure if you are aware of it). I wanted to try AdGuard as a way of being able to use policy routing. With the ad and tracker blocker Diversion I can only use ALL for the VPN tunnel. I'm unable to route different clients through the WAN and VPN without the DNS leaking. This looks like it'll be the same sort of issue.

This needs some serious ordered expansion before I can fully understand what you meant. But here are a few things to keep in mind: AdGuard Home's main job is purely local and has nothing to do with WAN except for updating its filters (can be routed through a proxy), checking for updates for itself (can be routed through a proxy), and resolving the filtered domains by sending them to an upstream DNS (can be any DNS you like). If you are happy with the DNS on your router setup, you can easily point the Adguard Home Upstream DNS there and let the router handle what happens in the WAN.

You can let your LAN devices point to your Mac directly to use Adguard Home to avoid being resolved by the router itself.

If all else fails and for some reason your setup could not work any other way, put a router that will handle the LAN behind your current router that would then be tasked with handling only the WAN. I would say, though, that this is the easy way out and there are more efficient ways to build a controlled network, albeit with some expertise needed.

All in all, that is beyond the scope of this repo and, unless Adguard Home is the direct culprit, I would say it's more suitable to bring up this routing issue with the Merlin team.

[mrtargaryen]

@tomiams Forgive me, I wasn't too clear in that last paragraph. It appears that when using OpenVPN clients on any router I use (that have OpenVPN clients) the DNS leaks when using AdGuard Home. So, I still see the VPN's IP Address, but not their DNS Address.

As my skills and knowledge are limited in this area I am unaware of how to overcome this issue with AdGuard Home. However, if what you have listed above is capable of overcoming this issue I would be more than willing to try.

[mrtargaryen]

@tomiams By the way, I just want to thank you for all this detailed information. It is greatly appreciated. I have AdGuard Home working perfectly well. Like I mentioned above the only downside is the VPN (Client not server) leaking DNS. Nevertheless, AdGuard Home is a brilliant tool for home Networks.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.