Edition | Supported Versions |
---|---|
pfSense® Community Edition | 2.7.2 |
pfSense® Plus | 23.09.1 |
For existing installations on out-dated pfSense® you must upgrade the OS first and then re-install adam:ONE®, see one-liner below.
Important note on pfSense® Upgrades
Every time pfSense® is upgraded on an existing adam:ONE® (v4) instance, a re-install of adam:ONE® v4 is required.
From the Diagnostics menu, choose Command Prompt and execute the following:
curl -sS https://dl.adamnet.works/pfsense/install4 | sh -s
Note that the adamone-setup configure
script does not need to be run on a re-install.
For a first-time adam:ONE® installation on pfSense®, follow the steps below.
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
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.
-
From Firewall menu choose Virtual IPs. Create a localhost interface alias of
127.0.0.2/8
that will be used to hijack/force DNS for internal endpoints referencing public DNS servers. When completed, it should appear like this:
Install version 4
-
From your ssh session or Diagnostics → Command Prompt menu, run:
curl -sS https://dl.adamnet.works/pfsense/install4 | sh -s
Your output should look similar to this:
-
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
For all other steps, answer accordingly, an example is shown here:
[2.7.2-RELEASE][admin@gateway1.site-a.anycorp.io]/root: adamone-setup configure Available Interfaces: 1 - All (all) 2 - WAN (em0) 3 - *LAN (em1) Enter the interfaces you would like to set as LAN interfaces separated by a comma, press <ENTER> to skip [3]: Select a default LAN interface, press <ENTER> to skip [3]: Set LAN interfaces to: em1 Set Default LAN interface to: em1 Available Interface Addresses: 1 - WAN (192.168.42.108) 2 - *LAN (192.168.1.1) 3 - 127.0.0.2 (for DNS hijacking) (127.0.0.2) 4 - Localhost (127.0.0.1) 5 - Localhost (::1) Select the addresses you would like adam:ONE to listen on separated by a comma, press <ENTER> to skip [2]: 2,3 Set DNS listeners to: 192.168.1.1@53,127.0.0.2@53 Set HTTP listeners to: 192.168.1.1@80,127.0.0.2@80 Set a log level (0-6), press <ENTER> to skip [0]: 4 Set log level to: 4 What hour of the day would you like adam:ONE to be automatically updated? Valid options are 0-23 [14]: 03 Setting adam:ONE auto-update cron job to 3:59 Enable automatic cloud backups [no]: yes Cloud backups enabled Generate recommended firewall rules in each LAN interface [no]: yes Hijack IPv4 DNS to Public Servers [yes]: Configuring firewall for LAN interfaces [lan] adam:ONE Allow DoT - 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 Allow NetBIOS names for device discovery - creating rule [lan] adam:ONE Prevent DNS bypass - creating rule [lan] adam:ONE Allowed Traffic - creating rule [lan] adam:ONE Reject Blocked Traffic - Should be last rule - creating rule ℹ︎ Setting System Tunable zero-copy BPF buffer sessions ############ 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 # Services / DNS Resolver ☑️ No DNS conflict issues detected # Firewall / Rules ⚠️ Rules have been created. Please go review them and Apply Changes. You will want to disable the default allow to any rules. # Firewall / NAT ⚠️ Hijack rules forcing DNS to adam:ONE have been created, please review your NAT port forwards and Apply Changes. ################################# Applying configuration... restarting anmuscle service... done. [2.7.2-RELEASE][admin@gateway1.site-a.anycorp.io]/root:
-
From the Firewall → Rules menu, apply the Rules changes that were generated with the
adamone-setup
script. Rules will be effective once you click on “Apply Changes” -
Once firewall rule changes have been applied, note the Firewall → NAT and confirm your relevant DNS hijacking rules are in place for 127.0.0.2:
-
Address all other NOTICES shown at the end of your script execution above.
-
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.7.2-RELEASE][admin@gateway1.site-a.anycorp.io]/root: sockstat |grep anmuscle root anmuscle 191 20 udp4 192.168.1.1:53 *:* root anmuscle 191 21 tcp4 192.168.1.1:53 *:* root anmuscle 191 22 udp4 127.0.0.2:53 *:* root anmuscle 191 23 tcp4 127.0.0.2:53 *:* root anmuscle 191 25 tcp4 192.168.42.108:55697 34.120.84.240:443 root anmuscle 191 26 tcp4 192.168.1.1:80 *:* root anmuscle 191 27 tcp4 127.0.0.2:80 *:* root anmuscle 191 28 tcp4 192.168.1.1:443 *:* root anmuscle 191 29 tcp4 127.0.0.2:443 *:* root anmuscle 191 30 udp4 192.168.1.1:137 *:* root anmuscle 191 31 tcp4 192.168.42.108:47329 34.120.84.240:1883
-
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 191 20 udp4 192.168.1.1:53 *:* root anmuscle 191 21 tcp4 192.168.1.1:53 *:*
-
Confirm these specific bindings are present for 127.0.0.2 so that non-local DNS usage is hijacked and answered by policy:
root anmuscle 191 22 udp4 127.0.0.2:53 *:* root anmuscle 191 23 tcp4 127.0.0.2:53 *:*
Review your rules
In the above sample screenshot, the original “Default allow LAN” will not be matched any longer since the “adam:ONE Reject Blocked Traffic” rule will block any unmatched traffic above.
In the event you need firewall rules to be processed outside of adam:ONE® they must appear above “adam:ONE Reject Blocked Traffic”.
For a full review of the purpose of each rule, with some historical context, see Understanding pfSense unified firewall rules.
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) -
- 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
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.