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

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

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

  • 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 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)

  1. Make sure the adam:ONE Reject Blocked HTTPS rule is at the top
  2. If running DTTS, make sure the default rules are disabled (or deleted entirely)
  3. 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:

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.

2 Likes