fptn

Core Features of FPTN

FPTN is a VPN technology engineered from the ground up to provide secure, robust, and censorship-resistant connections capable of bypassing network filtering and deep packet inspection (DPI).

Project website: https://storage.googleapis.com/fptn.org/index.html

Key Technical Features:

1. L3 Tunnel (Network Layer)

• IP Packet Tunneling: Encapsulates and transmits raw IP packets (IPv4/IPv6) over a secure tunnel to the VPN server.
• Split Tunneling: Provides granular control over routing policies. Users can define rules (based on domains or IP networks) to specify which traffic is routed through the VPN tunnel; all other traffic uses the direct internet connection.
• Server-side NAT: Implements Network Address Translation (NAT) on the server. Future roadmap includes support for user grouping into virtual LANs (VLANs) for peer-to-peer communication within the VPN.

1. Traffic Obfuscation and Blocking Evasion

• Resistance to active Deep Packet Inspection (DPI): The server can identify FPTN clients during the TLS handshake by analyzing the session_id (which the FPTN client can set using a special time-based method). If the client is not recognized as an FPTN client, the server acts as a transparent proxy and returns legitimate content for the requested domain.
• The VPN connection is masqueraded as regular HTTPS traffic (a mode for short-lived HTTPS connections is also under development).
• Three implemented methods for bypassing blocks:
  • SNI Spoofing: A fake domain name is set in the TLS ClientHello packet that initiates the connection. Traffic analysis systems observe a legitimate TLS connection, while the traffic is actually routed to the VPN server.
  • Obfuscation: The traffic is disguised as an already established TLS session, hiding the initial TLS handshake and preventing detection by DPI systems.
  • Reality Mode with SNI Spoofing: The client initiates a connection to the VPN server using a spoofed Server Name Indication (SNI), receives a genuine TLS handshake response from the actual (spoofed) website, and then continues data exchange with the VPN server within the same connection.
• The desktop client includes an integrated SNI scanner utility.

1. Transport Protocol

• Uses a proprietary transport protocol based on Protocol Buffers (Protobuf) for data exchange between the client and server.
• Protocol-level padding: Data packets are padded with random data to randomize traffic patterns and complicate analysis.
• The server provides a REST API for client authentication and retrieving specific configuration settings.

1. Advanced Functionality

• Built-in filtering of unwanted traffic (e.g., the BitTorrent protocol).
• Per-user bandwidth and traffic control: The server employs a traffic shaper based on the Leaky Bucket algorithm, allowing for granular bandwidth policy configuration.
• Support for a multi-server architecture with a single master server that stores all user data and configuration.
• System monitoring via Prometheus and visualization dashboards in Grafana.
• Ability for users to connect and manage their service via a Telegram bot.

1. Cross-Platform Clients

• A cross-platform core library, libfptn, has been developed for use across various operating systems. It implements the FPTN network protocol, connection management, and data transmission mechanisms for the VPN tunnel.
• Desktop Clients: Windows, macOS, Linux — a minimalist client focused on ease of use.
• Mobile Clients: Android, iOS (under development).

1. Simple Token-Based Configuration

• A Token is a specially generated configuration file containing all necessary settings for the system.
• Enables connection to the VPN without manual configuration: the user simply imports the token into the client application to begin using the service.

Demonstration

Download the FPTN client from the website or GitHub. After downloading, install and launch the client.

The client is a compact application whose icon resides in the system tray.

Simply click the icon to open the context menu.

Navigate to the "Settings" menu, where you need to add an access token. Obtain a token by contacting our Telegram bot,

Copy the token, click the "Add Token" button, paste it into the form, and save.

After this, available servers will appear in the list.

Ease of use:

You can also easily turn your Raspberry Pi or Orange Pi into a WiFi access point and install the FPTN client on it. In this case, all devices connected to this WiFi network will be able to access the internet, bypassing any restrictions. Read more here

Installation, Building, and Configuration

Installing and Configuring the FPTN Server

Setting up and running your own FPTN server is done via Docker. This ensures easy deployment, convenient updates, and environment isolation. Instructions are available on DockerHub.

You can also deploy your own management and monitoring tools:

• Telegram bot – issuing tokens to users sysadmin-tools/telegram-bot/README.md.

• Grafana + Prometheus – monitoring server and user status sysadmin-tools/grafana/README.md

  Installing FPTN on an OpenWrt router

The router package carries the client, a service that starts it at boot, and a page in the router web interface. Everything on the network goes through the VPN, and nothing has to be installed on the phones and laptops themselves.

Two OpenWrt branches are supported. They differ in package manager, so the file differs too:

What matters is the package architecture, not the exact model — one package serves every device sharing it:

Ask the router what it needs:

apk --print-arch

On 24.10:

opkg print-architecture

It prints several lines; the package architecture is the one with the largest number, for example arch aarch64_cortex-a53 10.

aarch64_generic, aarch64_cortex-a53 and aarch64_cortex-a72 are different package architectures even though all of them are 64-bit ARM. The package manager refuses a package built for another one — opkg reports incompatible with the architectures configured — so the name has to match exactly.

Both the branch and the architecture are in the file name, so take the matching one from Releases — for example fptn-client-0.4.4-openwrt-25.12.x-aarch64_generic.apk. Building it yourself is described in Building for OpenWrt.

Copy the package to the router and install it. On 25.12:

scp fptn-client-*.apk [email protected]:/tmp/

apk update && apk add --allow-untrusted /tmp/fptn-client-*.apk

On 24.10:

scp fptn-client-*.ipk [email protected]:/tmp/

opkg update && opkg install /tmp/fptn-client-*.ipk

The router needs working internet during installation: kmod-tun and ip-full are pulled from the OpenWrt repository.

Installing sets up everything else on its own: it creates the firewall zone that masquerades LAN traffic into the tunnel, enables the service for boot, and reloads rpcd so the web page appears.

Open VPN → FPTN in the router web interface, paste the access token from @fptn_bot, tick Enabled and press Save & Apply — the service starts right there. The same from the shell:

uci set fptn.config.access_token=''; uci set fptn.config.enabled='1'; uci commit fptn; /etc/init.d/fptn restart

If you administer the router remotely, add your own public address to Routing → Exclude tunnel networks (for example 203.0.113.45/32) before connecting. Otherwise the tunnel takes over the default route, replies to your session leave through it, and you lose access to the router.

The Diagnostics button on the FPTN page checks the tunnel, routes, firewall zone and DNS, and reports what is broken. The full picture is in the system log:

logread -e fptn -f

Removing the package stops the client and disables autostart:

apk del fptn-client

On 24.10 the same is done with opkg remove fptn-client.

Building for Linux, Windows and macOS

1. Install required dependencies

• For Windows
• For Ubuntu
• For macOS

1. Install Conan (version 2.24.0):

pip install conan

1. Detect and configure the Conan profile:

conan profile detect --force

1. Install dependencies, build, and install:

(For debugging and development purposes, use Debug instead of Release.)

• Linux:

conan install . --output-folder=build --build=missing -s compiler.cppstd=17 -o with_gui_client=True --settings build_type=Debug -c "tools.build:defines=['QT_NO_INT128']"

cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Debug
cmake --build . --config Debug
ctest

• macOS:

conan install . --output-folder=build --build=missing -s compiler.cppstd=17 -o with_gui_client=True --settings build_type=Debug

cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Debug
cmake --build . --config Debug
ctest

• Windows:

conan install . --output-folder=build --build=missing -s compiler.cppstd=17 -o with_gui_client=True --settings build_type=Debug

cd build
cmake .. -G "Visual Studio 17 2022" -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_BUILD_TYPE=Debug
cmake --build . --config Debug
ctest

1. Building the Installer

(For debugging and development purposes, use Debug instead of Release.)

• Windows

  bash复制

  cmake --build . --config Release --target build-installer

• Ubuntu

  bash复制

  cmake --build . --config Release --target build-deb-gui

• macOS

  bash复制

  cmake --build . --target build-pkg

  Building for OpenWrt

The router client is cross-compiled inside Docker: the image ships the OpenWrt SDK, builds the CLI client and packs it, the procd service and the LuCI page into a single package. Nothing has to be installed on the host except Docker itself. Installing and using the result is described in Installing FPTN on an OpenWrt router.

Dockerfiles are laid out as deploy/openwrt/target-/. The 25.12.5 directories produce an .apk, the 24.10.7 ones an .ipk:

Run the block matching your device and your OpenWrt branch — it builds the image and copies the package into the current directory.

OpenWrt 25.12.x, .apk

aarch64_generic:

docker build -t openwrt-armv8-25.12.5 -f ./deploy/openwrt/target-armsr-armv8/25.12.5/Dockerfile .
docker run --rm -v "$PWD