FAQ: Technical Deep Dive

A FrogNet is a Class B TCP/IP Network Controller.  It can theoretically route traffic for up to 255 * 255 * 255 = 16,581,475 addresses, in the range 10.0.0.1 to 10.254.254.254, inclusive.

From a physical point of view, an individual FrogNet is the combination of a computer, a router, and at least one antenna (may be built into the computer).  We have tested with a wide range of routers and computers, and all have worked as expected.

The computer must be running some version of the Linux operating system and have the FrogNet dependencies installed.  Those dependencies, along with their associated configuration files are installed by the FrogNet installation script, 

The FrogNet software falls into two categories: PHP and Bash.  PHP files are found in /var/www/html and are triggered by a POST request.  Some methods, like AddHost, alter the routing and hosts tables on the current machine, while others provide information about the FrogNet to a caller.  These methods are:

• frognet_echo.php -- Returns the name of the FrogNet and its IP address, as well as the IP addresses of the eth0, wlan0, and wlan1 interfaces. 
• getHosts.php -- Returns the complete /etc/hosts, with additional data, in JSON form.

The second category, Bash, is the actual network controller.  These files, most of which can be found in /usr/local/bin, automatically synchronize host and routing information across the FrogNet network.  There are only about 7,000 lines of code, but they convert almost any old computer into a stand-alone FrogNet capable of participating in a FrogNet Network, with DNS and DHCP and everything.

The key insights are:

• Individual FrogNets are Class C network controllers where:
  • The physical routers are in Access Point mode
  • The computer attached to the router (the FrogNet Host) is statically assigned the .1 address of the network CIDR that the router is projecting
  • The computer attached to the router is running Linux and the FrogNet software
  • The computer attached to the router is using dnsmasq to provide DHCP and DNS to the devices attached to the router
• Each FrogNet Host has an Apache web server installed.  The web server has two purposes:
  • To announce changes in the local network to the greater FrogNet
  • To answer specific queries about the FrogNet it is hosting
    • The identification of the attached FrogNet
    • A list of devices, including other FrogNets, that are attached to the router
• Any network adapter connected to a network *not* in the 10,xxx.xxx.xxx domain is deemed an "upstream" adapter and the IP address becomes the default route
• The "domain" of a FrogNet is unique within the FrogNet Network
• The IP CIDR of the FrogNet is unique within the FrogNet network
   

The core algorithms for synchronizing the host and routing tables between FrogNets are initiated by executing mergeHostsAndResolve.bash.

The algorithms may be triggered in any of three ways:

1. When a connection is made to the router on a machine, the dnsmasq process executes the script
2. When there is a connection change (connected, disconnected, etc.) to either wlan0 or wlan1 (if present), the NetworkManager process executes the script
3. When a network change announcement is received from an external server, the Apache web server executes the script

In each of the above cases, a small amount of pathway-specific code is executed, followed by a call to mergeHostsAndResolv.bash.  This script runs the synchronization process between this computer and all of our upstream and downstream connections.

Synchronization is the process of obtaining and verifying host and route information for all known FrogNet hosts.  Triggered by one of the events above, the synchronization process starts with the wlan0 connection, then moves to wlan1, and finally eth0.  For wlan0 and wlan1, a request for a frognet_echo is issued to the server attached to the interface.  As hosts are returned, routes are established.  When hunting for a route, we first try wlan0, then wlan1, if present, and finally eth0.

Eth0 is the name of the router on our Ethernet port.  The physical route attached to the port has been placed in Access Point (passive) mode and is getting its DHCP and DNS from the host computer -- specifically through the NetworkManager and dnsmasq services.

When we need to check the devices attached to the router, we use the DHCP leases file found at /var/lib/misc/dnsmasq.leases.  That file contains, in a packed form, the MAC address, simple name, and IP address of every device that has a DHCP lease, which is to say every device attached to the system.

Synchronizing downstream FrogNets is the process of opening the leases file and reading the data there.  For every entry where the simple name is either a '*' or "FrogNetHost", we use curl to request the frognet_echo.php information.  If the curl call returns, we know that we have a FrogNet host, that the host is alive, and if the host is connected to any external networks.

For both the of the wlan interfaces, and any attached to eth0, once we have the frognet_echo return, the steps are the same:

• For each real or suspected FrogNet Host, request frognet_echo
• If frognet_echo returns data, make sure that our local host and routing tables are right
• Use curl to call getHosts on the candidate FrogNet.  This will return the Host JSON
• Scan the Host JSON.  For each host, perform a frognet_echo and make sure we have the entries in our local host and routing tables.
• For each first-level host that answers the frognet_echo query, we will request getHosts.  This merges us two levels along every interface.
• Any host that is added is automatically propagated upstream and downstream through the Apache web server

A simple, stand-alone FrogNet is a reasonably easy thing to do.  We put the router into passive mode and let the computer handle the DHCP and DNS for our little network, and we're good to go.  We have 254 addresses available.  If our WiFi antenna is connected to the Internet, then everyone on our network has Internet access.

To make your home secure and protect your private information, you create two FrogNets -- one for your computers and one for your smart devices.  You give the smart devices network permission to route to the Internet, but not to other networks on the FrogNet Network.   Connections may be made from the FrogNet Network into the smart devices FrogNet, and users on the FrogNet network can query and control the smart devices, by name, but the smart network cannot initiate a connection to any other FrogNet network member.

Your home is safe because the smart network cannot covertly communicate with anything but the greater Internet.

Next, let's join two FrogNets.  Doing this is as simple as connecting the WiFi antenna for one FrogNet to the router of the other.  Seriously, that's all you have to do.

The connection triggers a merge event on both computers.  On the computer using the WiFi antenna to connect to the upstream router, the event comes from the NetworkManager in the form of a "99-ifup" event.  Our configuration is such that when this event is received, we synchronize hosts and routes.

The computer joining the router is given an IP address in the range of the host FrogNet.  We know that on every FrogNet the .1 address is the listening Apache web server, so we issue a request to the .1 address of our IP range.  This tells us who we are connected to (both name and IP address),  Using that, we enter the name and route in our /etc/hosts, /etc/dnsmasq.d/opts_only.conf, and /etc/resolv.conf, then use curl to propagate the information to our upstream and downstream networks.

The computer that was joined received a notification from dnsmasq.  In a manner similar to that described above, the computer hosting the router queries the downstream connection for its frognet_echo, and uses that information to add the name and route to the local files.  The information is also propagated to upstream and downstream FrogNets.

This happens to the second level for each interface, as follows:

• Ask for the frognet_echo of an address
• Add the echo'd  machine to our hosts and routes
• Propagate
• Issue getHosts query
• For each host, run frognet_echo, add the host, request its getHosts, and repeat.

This process can take a little time to complete, as it may require multiple synchronization runs to completely merge a large network.  When it is finished, every FrogNet should know about every other FrogNet on the FrogNet Network -- their name and how to get to them.

Our algorithms define the root of our network to be 10.0.0.1, and everything attached to the FrogNet Network will have an address that starts with 10.

A "foreign" network is defined as any network that does not begin with 10.  If a foreign network is located, it is defined as the default route, and routes to it are established throughout the FrogNet.

Seems to.