User:John/FreedomBox/Network architecture

Some notes about fbx network architecture. The goal is to make sure the user has secure access to their FreedomBox globally (on their LAN and from the Internet) before further network configuration continues (via plinth etc). This is the Out-Of-The-Box (OOTB) user experience that must happen before further access to FreedomBox services is provided.

The rationale for the network architecture offered below is that it solves some particular problems:

• it gets HTTPS security working without the user needing to ignore a security warning
• it enables the user to access their FreedomBox from their LAN and the public Internet using the same URL, being e.g. https://fbx.example.com/

Note: at the present time this documentation is maybe one tenth complete, there's lots more to add.

Examples

In the use cases below the following configuration settings are used. Note that a table like this would be a good thing to ship on a physical card that comes with FreedomBox hardware. The user will need to know the value for some (not all) of these settings so they can configure their network services appropriately.

THINK: could we ship an "app" that helped users figure out some/all of these values?

THINK: which of these settings can we validate before applying?

Setting	Value	User needs to know?
User's internet router LAN IP	192.168.0.1	yes, but we can suggest based on DHCP gateway
User's LAN subnet mask	255.255.255.0	yes, but we can suggest based on network class
User's LAN config web client IP	192.168.0.137	no
User's fbx LAN DHCP IP	192.168.0.123	not if freedombox.local MDNS works
User's fbx LAN static IP	192.168.0.2	yes
User's fbx LAN DNS static IP	192.168.0.53	yes, but we can suggest the .53 address, maybe
User's LAN DHCP range	192.168.0.{100,199}	yes, they need to know so they can pick static IP addresses outside the range
User's domain name	example.com	yes
User's FreedomBox name	fbx.example.com	we recommend 'fbx'
User's public IP address	139.218.130.78	yes, but we can offer to detect
User's internet DNS resolver	1.1.1.1	no, we can choose a default and make override an advanced feature

Use case

User wants LAN features only, no external access

If the user wants to run in LAN only mode that should be supported. Running in LAN only mode means no router NAT/DMZ/DNS config is required. Also no static network configuration (such as IP addresses) is required.

First I think we have to all agree that getting the user to ignore a security warning on order to connect to https://freedombox.local/ is absolutely 100% totally completely unacceptable and we simply cannot do that.

But! What we can do is be our own Certificate Authority. We create our own CA cert pair and use it to sign a browser certificate for DNS "freedombox.local" and IP address "192.168.0.123" and we configure Apache to use the browser cert and delete the CA private key.

So when you get your shiny new fbx you navigate to http://freedombox.local/ (*not* HTTPS) and there are instructions for downloading your own personal certificate authority cert from http://freedombox.local/ca.crt

You download your CA cert, install it in your browser as a trusted CA, and then when you navigate to https://freedombox.local/ you will get no security warning because your freedombox.local cert will be signed by the your very own personal CA which you have trusted.

Just one extra step, not hard to do, and advanced users who simply don't care can just navigate to https://freedombox.local/ and ignore the warning.

In this way we:

• keep configuration complexity low (no router or network config required)
• avoid scaring the user
• avoid teaching the user insecure practices
• avoid ruining our brand by associating with insecure practices

Note: it would be nice if we could validate that the certificate is properly installed and trusted before redirecting the user from http://freedombox.local/ to https://freedombox.local/

Note: after the CA cert is used to sign the browser's cert the private key for the CA cert is to be destroyed and that CA can never sign any other certs again ever.

Note: as the CA can't ever sign any additional certificates we probably want to set the expiry on the browser's cert at 100 years or something high like that...

Note: could output CA fingerprint to tty1 so user can confirm they downloaded the correct file via HTTP

Note: straight port 80 HTTP requests for ca.crt would need to continue working indefinitely so the user can download their CA cert on other computers, other HTTP traffic can redirect to HTTPS.

Note: our browser cert could include an IP address, but if it's DHCP (it probably is) the IP might change. Maybe we could issue our cert for a full subnet/range of IP addresses? to enable e.g. https://192.168.0.123/ for if MDNS isn't working...

THINK: can we disable swap while our CA private key exists on a RAM disk (/dev/shm)..? We don't want to risk our private key being written to swap file/partition.

User wants to register their fbx on their existing domain name on their static home IP address

Note: these notes are just a bit of a brain dump at the moment. I will tidy them up to try and keep things manageable for the user.

Prerequisites:

• user has a domain name registered (example.com)
• user has DNS hosting and nameservers configured
• user has access to do web based configuration of their DNS settings
  • note: in future we might be able to do for them via API from DNS hosting services
    • we could enumerate a list of supported providers (possibility for paid placement)

Out of scope:

• no IPv6 configuration yet (we can add later)

Process:

1. tell user to access http://freedombox.local/ (*not* https://freedombox.local/) after pluging in power and network then booting
   • if not accessible via MDNS and freedombox.local go through nmap discovery or DHCP server status to find IP host such as http://192.168.0.123 or http://10.1.1.123 etc
   • note that there is no HTTP redirection from either http://freedombox.local/ or e.g. http://192.168.0.123/ those URLs will answer with the web-based configuration services directly regardless of which form is used
     • actually redirecting from http://freedombox.local/ to e.g. http://192.168.0.123/ would be possible and unproblematic (the other way around would be a problem if MDNS were unreliable)
2. get the user to pick an IP address, subnet mask, and gateway for their fbx on their LAN
   • they will currently have a DHCP allocated address but as we can't ensure that IP will be constant/reserved (it's probably not) we want a static IP instead
3. reconfigure fbx with nominated static IP address (192.168.0.2), netmask (255.255.255.0) and gateway (192.168.0.1)
   • don't release the DHCP address (192.168.0.123), the server will have two IP addresses during this process
4. when static IP address settings are valid/successful (we could do a HTTP redirect dance to confirm):
   1. add firewall rule to block port 8080 access from all addresses other than current client IP address (192.168.0.137)
      • the rest of the configuration will need to be completed from the same client
      • this could be relaxed to blocking only gateway/router
   2. HTTP redirect over to the static IP address on port 8080 at e.g. http://192.168.0.2:8080/
5. get the user to pick a DNS resolver service:
   • 1.1.1.1 and 1.0.0.1
   • 8.8.8.8 also an option
   • we could have a database of ISPs and their DNS servers
   • DNS resolver is another possibility for paid placement
   • could enter manually (and find in router config)
6. ask the user to tell us thier domain name, e.g. 'example.com'
7. ask user to pick a hostname at their domain, we recommend 'fbx'.
   • note that what we want is one single global unambiguous well-branded hostname for this fbx and something in the form 'fbx.example.com' is ideal
   • note that support for other domain aliases such as 'www.example.com' or 'blog.example.com' etc can be added later at the user's option
8. tell the user to add an A record for 'fbx' for their public IP address at the DNS hosting provider
   • we could offer to auto-detect public IP address
9. configure our local Bind9 service:
   1. with DNS resolver nominated above (1.1.1.1)
   2. with a zone for 'fbx.example.com' and default A record of 192.168.0.2
      • a zone for the whole example.com could potentially be added later on, for now we just need fbx.example.com
10. configure our Bind9 resolver on the router:
    1. tell user to configure router DNS proxy to point to 192.168.0.2
    2. tell user to configure broadband router DHCP server with DNS server 192.168.0.1 (that's probably current default)
    3. tell user to configure non-DHCP hosts with DNS server 192.169.0.1 (that's probably current default)
    4. tell user to add /etc/hosts (or equiv) for 192.168.0.2 fbx.example.com for any LAN hosts not using our Bind9 resolver (ideally there are no such hosts)
       • if hosts file is being used instead of DNS this might affect alias configurations if those are added later on, ideal the LAN DNS will be used in preference to hosts files
11. tell user to configure router to point port 80 and port 443 at 192.168.0.2
    • ideally use "DMZ" configuration and just point all ports to 192.168.0.2
12. THINK: do we want to offer to do port 80 probe to check router configuration?
13. get a domain validated certificate from Let's Encrypt
    • public DNS should point to our home IP address
    • home IP address should NAT port 80 to our fbx
    • thus Let's Encrypt domain verification can complete
14. configure Apache to use newly generated Let's Encrypt certificate
15. HTTP redirect user to https://fbx.example.com/ and do the rest of the system configuration in plinth
    • we have successfully configured the FreedomBox to be accessible at https://fbx.example.com/ from both the user's LAN and from the public Internet
16. now that we have secure comms between client browser and fbx server we can ask the user for the username/password for their account
    • might want to enforce this account config comes from the client browser (192.168.0.137)

Config

Email

We might use the default RDNS name as the hostname of our mail server and the hostname for our MX records.

fail2ban

If web services are behind a reverse proxy blocking IP addresses will be problematic, so maybe just don't do that? Needs some thought.

Amalgamation

There should be support for operating multiple fbx on the same network. For web services (port 443) there is one "front facing" fbx which receives all web traffic. It can then be configured to reverse proxy web facilities to other fbx on the LAN. This should all be discoverable and configurable via plinth. The front-facing fbx will need to have SSL certificates for all DNS names in use, e.g. fbx.example.com, fbx2.example.com, etc.

Note: we always want to have one single global name for each fbx, such as fbx.example.com, but those fbx can operate multiple additional DNS names such as www.exmaple.com, ftp.example.com, etc.

Processes

nmap discovery

Help user discover their fbx IPv4 address using an nmap command such as:

nmap -p 80 --open -sV 192.168.0.0/24

DHCP server status

Help user discover their fbx IPv4 address by reviewing the status of their DHCP server (often in the commodity internet router) and looking for 'freedombox' in the hostname or otherwise just trying allocated IP addresses to "see if they work".

HTTP redirect dance

Note: don't do this until you're reasonably certain your static IP address settings are valid. So that means check if an IP address is in use before configuring it as the static IP address.

• GET http://192.168.0.123/check
• 307 http://192.168.0.2/valid
• 307 http://192.168.0.123/valid # if we reach here our static IP is working and we can disable port 80 and/or release our DHCP address etc
• 307 http://192.168.0.2:8080/

Challenges

Picking a DNS resolver

Note: I need to think harder about this. Particularly around what the fbx firewall rules will be for traffic coming from the router (which might be NATed port 53 from public internet, we do *not* want to run a public DNS resolver).

Note: we might want to run bind9 on a different additional LAN IP address (so that the router doesn't NAT/DMZ to port 53)

So we could go one of two ways when configuring our DNS resolvers:

• fbx -> router -> internet
• router -> fbx -> internet

The 'internet' resolvers could be one of:

• user's ISP DNS servers
• 1.1.1.1 and 1.0.0.1
• 8.8.8.8
• something else

Then we could either:

1. make our fbx the DNS server on the LAN, which will defer to the router.
2. make our router the DNS server on the LAN, which will defer to the fbx.

If we make the fbx the DNS server then we need to update the DHCP settings on the router to point the DNS server to our fbx.

If we make the router then DNS server then we need to update the DNS server settings on the router to point to our fbx.

Since it's six one way and half a dozen the other the way we will recommend is having the router be the primary LAN DNS server and the fbx as the DNS proxy to the internet. So that's router -> fbx -> internet. That means that we need to configure the DNS server on the router to be our fbx IP address (192.168.0.2 in our example). Because our fbx will defer to the actual DNS server we can offer choices (potentially paid placement) such as those listed as 'internet' DNS servers above (1.1.1.1).