Install adam:ONE® (v4+) on pfSense®

David · June 21, 2021, 11:37am

Edition	Supported Versions
pfSense® Community Edition	2.5.2 - 2.6.0
pfSense® Plus	21.05 - 22.01

Preparation

Read What’s new in adam:ONE® version 4
Store a current system backup (Diagnostics → Backup & Restore → Download Configuration as XML)
Communicate a maintenance window to affected users
Be able to make an ssh connection to your pfSense gateway
From Services → DNS Resolver, change it to listen only on localhost, and outgoing set only to WAN(s), then Save, Apply Changes

unbound1888×630 75.9 KB
Disable WebGUI redirect and set your pfSense webConfigurator TCP port to a port other than 443. Set to 20443, for example, at System → Advanced → Admin Access like this:

tcpport-disableredirect2330×1242 241 KB

Save changes, and access the webConfigurator at the newly-assigned port.

Requirements

Operate a version 4-supported pfSense® (see above)
Previous version of adam:ONE® version 3 uninstalled via ssh or at the Diagnostics → Command Prompt window with:

pkg remove -y dnsthingy

Install version 4

From your ssh session or Diagnostics → Command Prompt menu, run:

curl -sS https://dl.adamnet.works/pfsense/install4 | sh -s

ao4installed1942×1460 282 KB
Note your BoxID on the output (if you had installed version 3 previously, the BoxID will likely be the same, but in some cases is different)
Register BoxID at dashboard.adamnet.works (may not be required if previously running version 3 on the same gateway and BoxID remained the same)
The following step is also required and cannot be run from the Diagnostics → Command prompt, it must be done via ssh:

adamone-setup configure

If installing version 4 for the first time, make sure this question is answered yes:
Generate recommended firewall rules in each LAN interface [no]: yes

If you’re running DTTS and installing for the first time on this gateway, make sure this is also set to yes:
Are you using DTTS (Don't Talk to Strangers) [yes]: yes

For all other steps, answer accordingly, an example is shown here:

[2.5.2-RELEASE][admin@pfSense.home.arpa]/root: adamone-setup configure

Available Interfaces:

1 - All (all)
2 - WAN (hn0)
3 - *LAN (hn1)

Enter the interfaces you would like to set as LAN interfaces separated by a comma, press <ENTER> to skip [3]: 3

Select a default LAN interface, press <ENTER> to skip [3]: 3
Set LAN interfaces to: hn1
Set Default LAN interface to: hn1

Available Interface Addresses:

1 - WAN (10.180.42.114)
2 - *LAN (192.168.1.1)
3 - Localhost (127.0.0.1)
4 - Localhost (::1)

Select the addresses you would like adam:ONE to listen on separated by a comma, press <ENTER> to skip [2]: 2
Set DNS listeners to: 192.168.1.1@53
Set HTTP listeners to: 192.168.1.1@80

Set a log level (0-6), press <ENTER> to skip [0]: 4
Set log level to: 4

Enable automatic updates for adam:ONE [yes]: yes
Enabling automatic updates

Enable automatic cloud backups [no]: yes
Cloud backups enabled

Generate recommended firewall rules in each LAN interface [no]: yes
Are you using DTTS (Don't Talk to Strangers) [yes]: yes
Configuring firewall with DTTTS for LAN interfaces
[lan] adam:ONE Reject Blocked HTTPS - Must be at the top - creating rule
[lan] adam:ONE Allow DNS - creating rule
[lan] adam:ONE Allow ICMP to gateway - creating rule
[lan] adam:ONE Allow block page and adam1.tools - creating rule
[lan] adam:ONE Allow mDNS for device discovery IP4 - creating rule
[lan] adam:ONE Allow mDNS for device discovery IP6 - creating rule
[lan] adam:ONE Prevent DNS bypass - creating rule
[lan] adam:ONE Allowed by DTTS - creating rule
[lan] adam:ONE Reject all traffic not allowed by DTTS - Should be last rule - creating rule

  !!! Rules have been created !!!
      Go to Firewall / Rules to verify and Apply Changes.
      If using DTTS, you will also want to disable any "Default allow" rules.
  !!!



############ NOTICES ############
# Services / DHCP Server
ℹ︎ Remember to update the DNS server option in your DHCP service to your adam:ONE router IP
  - LAN [Not set]

# System / Advanced -> WebGUI redirect
☑️ Disable webConfigurator redirect rule

# System / Advanced -> TCP port
☑️ TCP port is set to a non-default port
#################################

Applying configuration... restarting anmuscle service... done.
[2.5.2-RELEASE][admin@pfSense.home.arpa]/root:

From your ssh session or Diagnostics → Command Prompt, review your bindings and make sure you have a tcp4 and udp4 binding for each interface on which you offer adam:ONE® service:

sockstat |grep anmuscle

The output should be similar to this:

[2.5.2-RELEASE][admin@pfSense.home.arpa]/root: sockstat |grep anmuscle
root     anmuscle   54033 12 udp4   192.168.1.1:53        *:*
root     anmuscle   54033 13 tcp4   192.168.1.1:53        *:*
root     anmuscle   54033 19 tcp4   10.180.42.114:61506   34.120.84.240:443
root     anmuscle   54033 20 tcp4   10.180.42.114:64895   104.196.219.250:44353
root     anmuscle   54033 22 tcp4   192.168.1.1:80        *:*
root     anmuscle   54033 23 udp6   *:5353                *:*
root     anmuscle   54033 24 udp4   *:5353                *:*
root     anmuscle   54033 26 udp4   192.168.1.1:137       *:*

Confirm these specific bindings are present for each LAN and CARP interface. If they’re missing, DNS Resolver might still be bound to the LAN interface(s):

root anmuscle 54033 12 udp4 192.168.1.1:53 *:*
root anmuscle 54033 13 tcp4 192.168.1.1:53 *:*
From the Firewall → Rules menu, apply the Rules changes that were generated with the adamone-setup script

Review the rule order (minimum set of rules required shown below)

Make sure the adam:ONE Reject Blocked HTTPS rule is at the top
If running DTTS, make sure the default rules are disabled (or deleted entirely)
If selected to run DTTS during the adamone-setup configure script, the last two rules were created, and the one with Description adam:ONE Reject all traffic not allowed by DTTS - Should be last rule needs to be the last one in the list as a block rule will not allow any rules below it to be matched

Recommended additional steps:

Learn about Enablers: The complete guide to enabling DTTS® on your adam:ONE® gateway
Learn about and use DNSharmony as a way to aggregate publicly-available threat intelligence
Follow DNS best practices when combining with unbound (DNS Resolver) - this is especially important if you have leftover version 3 DNS hijack rules in place that NAT to 127.0.0.1 (if the original v3 DNS NAT rules are left unchanged, any endpoint using a public DNS Resolver effectively will bypass adam:ONE®)
We also recommend strongly to follow our NTP best practices

Common problems and solutions

No Internet access, dashboard shows offline

Check your device status at dashboard.adamnet.works
Service checks/start/restart:
- service anmuscle.sh status (to see status)
- service anmuscle.sh stop (to stop the service)
- service anmuscle.sh start (to start the service)
- service anmuscle.sh restart (to restart the service)
Eliminate port 53 binding conflicts if another service owns port 53
If intending to run DTTS, ensure that the dashboard → Advanced → Enable DTTS is active
Run adamone-setup boxid to confirm your BoxID is the same as registered on the dashboard

Step-by-step video of the above

Uninstall

To remove adam:ONE® v4, you can run this command in an ssh session:

adamone-uninstall

Note, however, that the uninstall process will not remove any firewall rules created during the adamone-setup configure script.

David · March 16, 2022, 5:49pm