flip-linux

A user-space implementation of the FLIP (Fast Local Internet Protocol) network protocol for Linux hosts, enabling communication with daemons running on Amoeba systems over FLIP.

Overview

FLIP is the native network protocol of the Amoeba distributed operating system. This project implements the FLIP protocol stack entirely in user space on Linux, using TAP (layer 2) virtual network interfaces to send and receive raw Ethernet frames carrying FLIP packets (Ethertype 0x8146).

This allows programs on a Linux host to participate in an Amoeba FLIP network — locating remote services, exchanging data with Amoeba daemons, and routing FLIP traffic across network interfaces.

Architecture

┌─────────────────────────────────┐
│         flip_linux (main)       │  Event loop (poll-based), Unix socket server
├──────────┬──────────────────────┤
│  Router  │   RPC Port Manager   │  FLIP routing table & RPC dispatch
├──────────┴──────────────────────┤
│        Network Driver (TAP)     │  TAP interface abstraction
└─────────────────────────────────┘

Component	Description
flip_linux.cpp	Main entry point. Opens one or more TAP devices, runs the poll() event loop, performs fragment reassembly, dispatches incoming Ethernet frames, manages Unix socket clients, and fires a 30-second timer for routing table maintenance.
flip/router.cpp	FLIP routing table and packet routing logic. Learns routes from incoming packets, handles LOCATE/HEREIS/UNIDATA/MULTIDATA/NOTHERE/UNTRUSTED message types, and handles RPC LOCATE/HEREIS/ACK.
flip/protocol.cpp	Supplementary protocol utilities (work in progress).
rpc/port_manager.cpp	RPC port registry. Tracks locally registered ports and pending remote lookups; resolves port-to-FLIP-address mappings.
unix/unix_server.cpp	Unix domain socket server (/tmp/flip.sock). Accepts connections from local Amoeba clients, frames messages, and delivers RPC replies.
driver/tap.cpp	Linux TAP network driver. Opens /dev/net/tun in TAP mode (layer 2, no PI header), reads/writes raw Ethernet frames.
include/flip_proto.hpp	FLIP protocol definitions — packet header, message types (LOCATE, HEREIS, UNIDATA, MULTIDATA, NOTHERE, UNTRUSTED), flags, fragment control header, and RPC header.
include/flip_router.hpp	Routing table entry and router class declarations.
include/netdrv.hpp	Abstract NetDrv base class for network drivers, plus the flip_networks registry that assigns network IDs.
include/rpc_port_manager.hpp	RPC port manager class declaration.
include/unix_server.hpp	Unix socket server class declaration.
include/tap.hpp	TAP driver class declaration.
amoeba.c	Drop-in replacement for src/unix/lib/amoeba.c in the Amoeba source tree.

FLIP Packet Types

Type	Value	Purpose
LOCATE	1	Locate a FLIP address on the network
HEREIS	2	Response to LOCATE — announces presence
UNIDATA	3	Unicast data delivery
MULTIDATA	4	Multicast data delivery
NOTHERE	5	Destination is not (or no longer) reachable
UNTRUSTED	6	Packet traversed an untrusted network

Building

Requires a C++23-capable compiler (GCC 13+ or Clang 17+).

make

This produces the flip_linux binary.

To clean build artifacts:

make clean

Usage

Create one or more TAP interfaces and pass their names as arguments:

# Create a TAP device (requires root or CAP_NET_ADMIN)
sudo ip tuntap add dev tap0 mode tap
sudo ip link set tap0 up

# Run flip_linux (may require root for TAP access)
sudo ./flip_linux tap0

Multiple TAP interfaces can be specified to bridge FLIP traffic across networks:

sudo ./flip_linux tap0 tap1

The daemon will listen on all specified TAP interfaces, route incoming FLIP packets, maintain a routing table, and age out stale routes every 30 seconds. Local Amoeba clients connect via the Unix socket at /tmp/flip.sock.

Amoeba src integration

If you have the amoeba source code, replace src/unix/lib/amoeba.c with the one from this repo. If you are on a 64-bit machine, you will also need to fix the definition of "int32" and "uint32" to be "int" and "unsigned int" respectively, rather than "long" and "unsigned long".

How It Works

1. Startup — Opens each TAP device specified on the command line, registers it as a FLIP network interface, and starts the Unix socket server at /tmp/flip.sock.
2. Event loop — Uses poll() to wait for incoming packets on any TAP interface, messages from local Unix clients, or a periodic 30-second timer.
3. Packet reception — Incoming Ethernet frames are filtered by the FLIP Ethertype (0x8146). The fragment control header is stripped; fragmented messages are reassembled before being passed to the router.
4. Routing — The router learns source routes from incoming packets and makes forwarding decisions based on the FLIP message type:
   • LOCATE — If the destination is local, responds with HEREIS; otherwise broadcasts to all other networks.
   • HEREIS — Updates the routing table; forwards to destination if known.
   • UNIDATA — Delivers locally (including RPC replies to Unix clients) or forwards to the next hop.
   • MULTIDATA — Handles RPC LOCATE requests for locally registered ports; broadcasts to all other networks.
   • NOTHERE — Removes the route for the unreachable destination.
5. Local clients — Programs connect via the Unix socket, are assigned a random FLIP address, and can send RPC requests to Amoeba services. The daemon resolves ports via FLIP RPC LOCATE/HEREIS and routes replies back.
6. Route aging — Every 30 seconds, increment_age() is called for routing table maintenance (full aging logic is not yet implemented).

Status

This project is a work in progress. Currently implemented:

• TAP network driver
• FLIP packet parsing (Ethertype, fragment control, FLIP header)
• Basic routing table with source-route learning
• LOCATE / HEREIS / NOTHERE handling (partial)
• Route aging timer
• UNIDATA forwarding and local delivery
• MULTIDATA support
• RPC layer for Amoeba service communication
• HEREIS response generation
• Full route aging and pruning logic
• Trusted / untrusted network handling

License

See repository for license details.