Skip to content

Latest commit

 

History

History
412 lines (280 loc) · 14.5 KB

README_release-notes_latest.rst

File metadata and controls

412 lines (280 loc) · 14.5 KB
Raw

Software Version Description for fpnd 0.9.10

Date: 2024-09-20, 03:42 PST8PDT
Author: Stephen L Arnold
tags:system, prototype, version
category:release
slug:engineering_process
summary:Software version/release description and full change history
asset name:fpnd
software version:0.9.10

Table of Contents

1.0 - Identification and Overview

The FreePN network daemon (fpnd) is a P2P implementation of a distributed virtual private network (dVPN) that creates an anonymous "cloud" of peers where each peer is both a client and an exit. Peers are randomly connected on startup and reconnected to new (random) peers as needed.

1.1 - System Design

The FreePN network daemon uses ZeroTier virtual networks to provide enhanced user privacy, anonymity, and security when accessing the Internet. The current prototype design supports these goals in the following ways; planned (future) features include more granular user controls.

  • each peer VPN link is a private ZeroTier network with its own IPv4 address space
  • each network link allows only 2 hosts, and only the routed traffic (currently http/https/dns)
  • peer links are randomly assigned/reassigned by the network controller as user nodes come and go
  • FreePN infrastructure traffic is restricted to only node and network IDs (the minimum required for this stuff to actually work)

1.2 - Required / Optional Software

FreePN packages are available for Gentoo and Ubuntu using the ebuilds in the freepn-overlay or the .deb packages hosted on the Embedded device PPA on Launchpad. The PPA sources can also be used to build Debian packages, however, we don't (yet) support any "official" Debian releases.

In addition to the existing (FOSS) package dependencies, there is one primary package (and related repository on github) for each of the following two components:

The required Linux kernel modules include:

  • xt_MASQUERADE, xt_nat, xt_tcpudp, xt_mark
  • nf_nat, nf_conntrack, nf_defrag_ipv4
  • iptable_filter, iptable_nat, iptable_mangle, bpfilter
  • ip6_tables, ip6table_mangle, ip6table_filter, ip6table_nat

The required outgoing network ports for the FreePN user node daemon include:

  • allow port 9993/udp (both IPv4 and IPv6 for zerotier)
  • allow port 8443/tcp (for fpnd infra messages)
  • allow ports 53/udp and 53/tcp (if not using encrypted dns)
  • allow port 853/tcp (if using encrypted dns)
  • allow ports 80/tcp and 443/tcp

Note

When using encrypted dns and with private_dns_only set to True local dns queries are only allowed to localhost (but peer dns traffic is still routed).

2.0 - Referenced Documents

3.0 - Version Description

Prerequisites:

A supported linux distribution, mainly something that uses .ebuilds (eg, Gentoo or funtoo) or a supported Ubuntu series, currently bionic 18.0.4 LTS, or focal 20.0.4 LTS (see the above`PPA on Launchpad`_). Note you can also use the focal PPA series on the latest kali images, however, the fpnd.service is broken against the latest systemd upgrade to 264 or higher (and there is no fix yet).

Breaking "feature":

As of the 0.9.7 release, the primary FreePN infrastructure node will check the version of fpnd in the announce message and send an UPGRADE message if the user node software is no longer compatible with the minimum required version (currently 0.9.5). This means your node will no longer be able to connect until the required packages are upgraded. See the Post-Install Updates section in the README for more information.

3.1 - Packages and Source Code

Released packages come in three different formats, which are verified in at least one or more places.

For supported Linux distributions:

  • Ubuntu bionic, focal
  • Kali (other ubuntu derivatives with recent Python3 should also work)
  • Gentoo (funtoo, Sabayon)

For other distributions:

3.2 - Install Instructions

Before you can install any Freepn packages, you'll need to add the required package repository or overlay.

For all ubuntu series, make sure you have the gpg and add-apt-repository commands installed and then add the PPA:

$ sudo apt-get install -y software-properties-common
$ sudo add-apt-repository -y -s ppa:nerdboy/embedded

If you get a key error you will also need to manually import the PPA signing key like so:

$ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys <PPA_KEY>

where <PPA_KEY> is the key shown in the launchpad PPA page under "Adding this PPA to your system", eg, 41113ed57774ed19 for the Embedded device PPA.

On kali you will need to edit the file created under /etc/apt/sources.list.d for the PPA and change the series name to focal, then run the above apt-key command, and finally a manual update.

Then install fpnd (for console only) or freepn-gtk3-indicator for the desktop GUI:

$ sudo apt-get install python3-fpnd

Or:

$ sudo apt-get install freepn-gtk3-indicator

For Gentoo or derivatives based on Portage, first install the portage overlay.

Create a repos.conf file for the overlay and place the file in the /etc/portage/repos.conf directory. Run:

$ sudo nano -w /etc/portage/repos.conf/freepn-overlay.conf

and add the following content to the new file:

[freepn-overlay]

# Various python ebuilds for FreePN
# Maintainer: nerdboy ([email protected])

location = /var/db/repos/freepn-overlay
sync-type = git
sync-uri = https://github.com/freepn/freepn-overlay.git
priority = 50
auto-sync = yes

Adjust the path in the location field as needed, then save and exit nano.

Run the following command to sync the repo:

$ sudo emaint sync --repo freepn-overlay

Once the overlay is synced, install the daemon and/or UI package:

$ sudo emerge fpnd

Or:

$ sudo emerge freepn-gtk3-tray

Note

In either case, installing the UI package will pull the daemon package as one of the dependencies, so you do not need to manually install both packages (ie, choose one or the other).

Portage notes:

  • almost nothing in the overlay is keyworded stable yet; use your preferred method to accept ~ packages
  • depending on your license settings, you may need to allow the new zerotier license (BSL-1.1) in your make.conf file
  • freepn-gtk3-tray requires an XDG-compliant desktop with policykit installed, so you'll need to enable the "polkit" USE flag on net-misc/fpnd

3.3 - Build Instructions

For Gentoo and related derivatives, all packages are built from source by design, while .deb packages are built automatically by the PPA tools.

The Gentoo ebuilds generally enable only the package tests (without any extras like code coverage, linting, etc) so you'll need to manually install those if desired. You can find the additional test packages in the package-specific requirements*.txt files (for python packages) and .travis.yml files (and sometimes as comments in the ebuilds). You can start by installing fpnd with test in both FEATURES and USE.

If you're on Ubuntu you can make a local build directory and cd into it, then issue the following commands to get started:

$ sudo apt-get build-dep python3-fpnd
$ sudo apt-get install tox
$ git clone https://github.com/freepn/fpnd

Using the Debian developer/packaging tools is beyond the scope of this document.

3.4 - Data integrity

The canonical source code repositories are maintained on github and verified by both github keys (for pull requests) and developer keys; the latter are used to sign releases (both tags and tar.gz archives). Note this also includes the .ebuild packages in the freepn-overlay.

For the .deb package format:

  • all .deb "source" packages are signed with the developer's PPA key prior to uploading to the PPA builder
  • signatures are verified using the package manager via the ubuntu key server

3.5 - Dependencies

Core dependencies for the FreePN network daemon are shown below. Dependency resolution is handled by the respective package managers and test tools. The run-time requirements also include a recent Linux kernel with bash, iptables (legacy), and iproute2 installed.

3.6 - Known Issues

  • Domain resolution issue on Ubuntu 20.04 in Chromium / Firefox browsers

When you type a "naked" domain into the URL bar in the format: xxx.com, it doesn't resolve / times out while trying to load, however https://xxx.com does resolve (clicking a link to https://xxx.com also resolves immediately). Modern browsers have a built-in "prediction" mechanism for "guessing" what to do in this case; on firefox-81.0.1 it defaults to http with xxx.com but the prediction thing switches to https and adds a trailing slash if it recognizes/remembers the domain. From the browser side, the "fix" is basically using a plugin, eg, https-everywhere (as we don't have a fix yet for the port 80 issue).

  • ip6tables modules not loading automatically on ubuntu

The new setting to filter leaky IPv6 traffic depends on some additional kernel modules for the basic (ip6) iptables setup. On at least some Ubuntu installs, the ip6tables module is not loaded automatically. Earlier versions installed a modules.conf file into the /etc/modules-load.d/ directory but that still allowed module errors without a reboot or manual modprobe on the first start after package install. This is now fixed in the primary service files for Systemd and Openrc (so the modules.conf file is no longer installed by the .deb packages). Issue #95 will be closed accordingly.

  • Erratic service file behavior with systemd >= 246

This essentially breaks correct shutdown and associated cleanup functions (no fixes yet) on ubuntu groovy and kali.

  • avahi-autoipd link-local conflicts with zerotier interfaces
    • avahi-daemon.conf requires interface whitelisting to ignore vpn interfaces

These are both open "watch items" (see issue 39 and issue 67) for Linux hosts running the avahi daemon. Using autoipd is incompatible with both fpnd and ZeroTier (see the first github issue for details) so you must disable the autoipd daemon before running fpnd. The second issue addresses the default avahi config listening on all the interfaces it finds and recommends options to address both issues.

  • missing kernel module(s) cause net script failures

This is also an open "watch item" issue (see issue 30) and is mainly a potential issue with user-configured/custom kernels; currently the standard kernel packages on Ubuntu and Kali have the required modules enabled (on Gentoo this is handled by checking for the required modules when building the package and issuing a warning to the user if necessary).

3.7 - Resolved Issues

See the closed issues list on github for details.

Appendix A - Full Change History

Since there has been no prior Software Version Description published for this software, this section should contain the complete change history (see the git logs for the detailed source code changes). Sadly github does not render included .rst documents.

Note

You can build a (complete) PDF version of this document using the rst2pdf tool. After cloning this repository, cd into the top level directory and run the following command:

$ rst2pdf README_0.9.4-release-notes.rst -o README_0.9.4-release-notes.pdf