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

Knowledge Base
,
#1
Edition Supported Versions
pfSense® Community Edition 2.5.1 - 2.5.2
pfSense® Plus 21.05

Stage 1 of 5 – Learn what’s new in version 4

  • Installation and host configuration administration has moved from the GUI to the CLI (command line). Don’t be afraid if you don’t see adam:ONE® under the pfSense® Services menu.
  • The binary name has changed from anmgr (ADAMnetworks Manager) to anmuscle (ADAMnetworks Muscle) to more accurately describe the hybrid brain (in the cloud) and the muscle (on-premise).
  • IPv4 and IPv6 dual-stacking compatible even with DTTS® functionality
  • Firewall rules now need to be created manually (we’ve learned pfSense® sysadmins like to manage their own rules, so we just show you what’s needed)
  • DNSharmony® support so you can combine upstream DNS threat intel
  • DNS-over-HTTPS (DoH) client support for recursive queries
  • DNS-over-HTTPS server support to answer internal endpoints via DoH
  • DNS-over-TLS (DoT) client support for recursive queries
  • DNS-over-TLS server support to answer internal endpoints via DoT
  • Enablers (DTTS® exemptions) moved to the dashboard.adamnet.works GUI (no longer need to make pfSense allow rules for DNSless traffic to pass)
  • Allow lists (whitelist rules) are available on all policies, including ones based on Blocklists (blacklists)
  • Approximately 20x performance increase on DTTS® engine, which manages the rapid creation and destruction of firewall rules

We’re very excited about version 4 and hope you also enjoy the fruit of our labour. However, we’re far from done as we’re rebuilding our dashboard UI as well with many changes coming soon!

Stage 2 of 5 – Preparation for version 4

Networking architecture always needs to be planned with good preparation in order to avoid unintended consequences. This is a starter list that should be verified with your own IT, networking and cyber security experts, as you may have additional requirements.

  • Make sure a maintenance period is scheduled and permission granted
  • Have a list of all of your network segments ready, along with IP address allocations and corresponding DHCP server details
  • If planning on running DoT or DoH, set aside an available alias IP address for each network segment
  • If the DHCP server has a long TTL such as Microsoft’s default 1 week, change that in advance to 1 hour TTL
  • Note the v3 uninstall script prior to v4 installation: pkg remove -y dnsthingy (note DNSthingy was our development brand and this may be our last remaining v3 artifact)
  • Note all Active Directory (AD) controller IP addresses
  • Note all domains for which AD is authoritative
  • Make sure you have administrative rights to pfSense, including ssh access
  • Take an inventory of any statically-assigned devices
  • Take an inventory as best as possible of any apps, services or devices that have configurations that reach out to the public Internet by IP addresses

Stage 3 of 5 – Installation

Now that you know what’s new and how to prepare, here are the steps to install adam:ONE® version 4 on pfSense®:

  1. From System → Advanced enable SSH and adjust firewall rules, if needed (we also recommend changing SSH to a non-default port such as 20022)
  2. Make an ssh connection to your pfSense® gateway (e.g. from terminal use ssh -p 20022 admin@192.168.1.1)
  3. From the console menu, use option #13 to first upgrade/update pfSense® to the latest version
  4. If version 3 (anmgr) was installed, uninstall it first with pkg remove -y dnsthingy, otherwise skip to the next step
  5. Now we need to take care of several special ports required for the adam:ONE® stack to operate successfully:
    A) TCP port 443 needs to be unused, but since it’s the default webGUI port for TLS access to pfSense, it needs to be moved by going to System menu → Advanced → Change listening port to 20443
    B) TCP port 80 is needed by mytools.management but the redirect binding needs to be removed for it be available. Do this under System → Advanced → Disable WebGUI Redirect
    C) TCP and UDP port 53 are required by adam:ONE®’s DNS legacy services, so unbound needs to be unbound (pun intended) via Services → DNS Resolver, and then disable it there
  6. Install adam:ONE® from your ssh session or from the GUI → Diagnostics → Command Prompt and execute:
curl -sS https://dl.adamnet.works/pfsense/install4 | sh -s test

(the test parameter installs the rapid release version, omit it for a little less adventure)

  1. Make a note of the BoxID and register it at https://dashboard.adamnet.works (please note that the BoxID may not be the same as what you had in version 3, if that was previously installed)
  2. On the dashboard → Advanced enabled DTTS® (if using the business plan)
  3. In your ssh session, run adamone-setup configure to make sure the defaults are all acceptable, or change them if needed
  4. We recommend you change your log-level to 4 (optionally change to level 6 for debugging)
  5. From the ssh sessions, run service anmuscle.sh restart
  6. Make sure you check that each interface has TCP53, UDP53, TCP80 bindings with this command: sockstat |grep anmuscle

Congratulations, if each interface you selected is now offering DNS and a micro web server for mytools.management.

The main adam:ONE® config file is at /usr/local/etc/adamone/anmuscle.conf so that’s where you make edits manually, if required.

Next, make sure you make these firewall rules in the pfSense® GUI:

  1. Disable the default LAN to any rules (skip this steps if you’re not planning on running DTTS®)
  2. Create a LAN allow rule for TCP/UDP port 53 (DNS) to This firewall
  3. Create a LAN allow rule for TCP port 80 (HTTP) to This firewall
  4. Create a LAN allow rule for any destination, but only if tagged as adamone_pass
  5. Create a LAN REJECT rule for all remaining traffic attempts and enable logging. This rule will only be hit when no match above is found.

Note the order of the above rules is essential.

Next, in System → General, make sure localhost is never used. This is so that its upstream name server resolutions don’t create a loop via localhost. You also don’t want the gateway itself having its upstream DNS filtered by itself.

It’s also important to note that when adam:ONE® devices use an allow/whitelisting policy, the upstream resolutions forward here by default. Therefore, it’s an additional layer of security to have allow-listed queries forward to an upstream DNS-based filtering service like Cloudflare’s 1.1.1.3 and 1.0.0.3.

To make sure that the right installation assumptions were made, you can run this script:

adamone-setup configure

We recommend log-level=4 as it will auto-rotate logs when they reach 10MB in size. This log level gives you a local temporary entry for each DNS query and answer, which is helpful as a source of passive DNS records for troubleshooting, maintenance and support.

When your configuration is complete, make sure it takes effect by running this command:

service anmuscle.sh restart

To be certain that the installation completed and is running, run this command:

sockstat |grep anmuscle

This will list all listening sockets and we’re looking for a minimum of 3 of them, bound to:

  • TCP port 53
  • UDP port 53
  • TCP port 80

Those would apply to each interface. If any are missing, review steps above and remove potential port conflicts and make sure interface assignments are correct. There may also be clues in /var/log/anmuscle.log.

If you’re running High Availability (HA) take these additional steps:

  • Each HA instance must run its own license with its own unique BoxID and one-time configuration setup
  • Submit a support request with your additional BoxID(s) and the network where it belongs
  • Test HA (you may need to run service anmuscle.sh restart the first time a slave node becomes master so it can bind the CARP address to anmuscle services

To make sure that adam:ONE® upgrades itself automatically, install a pfSense package called cron from its own package manager.

Once installed, you can then create a cronjob for as often as you like, to check for upgrades.

/usr/local/bin/adamone-upgrade test

We recommend a weekly check during non-working hours. If you append test to the command, it will grab the latest version from the rapid release channel.

From a client-side, the one important addition to any Chrome or Chromium-based browser is to add the blockpage assistant which can be retrieved from adamnet.io/ext

Finally we want to conduct a few basic tests to ensure that everything works. Here’s our QualityControl process to confirm.

  1. Check and see if we can ping the gateway
  2. Check and see if we can resolve a non-blocked destination, say google.com
  3. Check and see if a blocked destination resolves to the block page
  4. Check and see if a blocked destination by https redirects to the block page
  5. Check and see if pinging to the internet by IP is blocked (216.239.38.120)
  6. Check and see if pinging to the internet by allowed hostname is allowed
  7. Finally, check and make sure that http://mytools.management/whoami shows the same mac address as your actual endpoint device - as long as they match, you know you don’t have any layer 2 interference between adam:ONE® and the endpoint

When all of these tests pass, you’ve got a basically functional adam:ONE® environment with DTTS® running. Check out other content coming soon below for DNSharmony® and Enablers.

Stage 4 of 5 – DNSharmony®

Coming soon.

Stage 5 of 5 – Enablers

Other pfSense allow rules will continue to function as always. However, you may now use the dashboard.adamnet.works interface to create them and enable them on a per-policy basis.

Uninstalling adam:ONE®

To uninstall, simply run:

adamone-setup uninstall

More details coming soon.

2 Likes