Edition | Supported Versions |
---|---|
pfSense® Community Edition | 2.5.2 - 2.6.0 |
pfSense® Plus | 21.05 - 22.01 |
Preparation
-
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
-
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:
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
-
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
andudp4
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 Descriptionadam: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.