# Lantern Mesh Lantern Mesh is a community-operated wireless mesh network that provides affordable, resilient internet access across neighborhoods where traditional broadband is unavailable, unreliable, or too expensive. Each participating site runs a small router that connects to nearby nodes over Wi-Fi. Traffic is forwarded through the mesh to one or more internet gateways, allowing the network to reroute automatically when a node or link goes offline. > **Project status:** Active development. Lantern Mesh is suitable for pilots and community test networks, but operators should evaluate local regulations, security requirements, and upstream-provider terms before offering public service. ## Features - Self-forming, self-healing wireless mesh - Multiple internet gateways with automatic failover - IPv4 and IPv6 support - Per-node bandwidth limits and traffic shaping - Optional member authentication and captive portal - DNS caching and local service discovery - Encrypted management traffic between nodes - Prometheus metrics and health checks - Configuration validation before deployment - Support for common OpenWrt-compatible routers - Local operation during upstream internet outages ## Architecture A typical deployment contains three node roles: - **Relay:** Extends mesh coverage and forwards traffic. - **Access point:** Provides Wi-Fi or Ethernet service to members. - **Gateway:** Connects the mesh to an upstream internet provider. A single device may perform more than one role. For production networks, deploy at least two gateways and avoid placing critical services on only one node. ## Requirements - Linux host for the controller - Python 3.11 or newer - `iproute2`, `nftables`, and `wireguard-tools` - OpenWrt 23.05 or newer on mesh nodes - Root access on each managed node - One or more upstream internet connections For wireless mesh links, use radios and channels permitted by your local regulator. Outdoor installations may require approved enclosures, grounding, and professional mounting. ## Install Clone the repository and create a virtual environment: ```sh git clone https://github.com/lantern-mesh/lantern.git cd lantern python3 -m venv .venv . .venv/bin/activate pip install --upgrade pip pip install . ``` Create the configuration directory: ```sh sudo install -d -m 0750 /etc/lantern sudo cp config/lantern.example.yml /etc/lantern/lantern.yml sudo chmod 0640 /etc/lantern/lantern.yml ``` Initialize the controller: ```sh sudo lantern init --config /etc/lantern/lantern.yml ``` Install and start the service: ```sh sudo lantern service install sudo systemctl enable --now lantern ``` Confirm that the controller is healthy: ```sh lantern status ``` ## Usage ### Add a node Generate an enrollment token: ```sh lantern node enroll --name library-roof --role relay,access-point ``` On the OpenWrt device, install the node package and run the enrollment command printed by the controller: ```sh opkg install lantern-node.ipk lantern-node join --controller https://mesh.example.net --token ENROLLMENT_TOKEN ``` Enrollment tokens expire after 15 minutes and may be used once. ### List nodes ```sh lantern node list ``` Example output: ```text NAME ROLE STATUS NEIGHBORS UPTIME library-roof relay,access-point online 4 18d clinic-gateway gateway,relay online 3 42d market-west access-point degraded 1 6d ``` ### Inspect the mesh ```sh lantern topology lantern link list lantern node show library-roof ``` To export the topology as JSON: ```sh lantern topology --format json > topology.json ``` ### Apply configuration Validate changes before deploying them: ```sh lantern config validate /etc/lantern/lantern.yml ``` Preview the affected nodes: ```sh lantern config plan /etc/lantern/lantern.yml ``` Apply the configuration: ```sh sudo lantern config apply /etc/lantern/lantern.yml ``` Nodes receive updates in batches. If a health check fails, deployment stops before the next batch. ### Remove a node ```sh lantern node revoke library-roof ``` Revocation removes the node's credentials and prevents it from reconnecting. Reset the device separately before reusing it. ## Configuration Lantern uses YAML configuration. Environment variables may be referenced with `${VARIABLE_NAME}`. ```yaml network: name: "Riverside Community Mesh" domain: "mesh.riverside.example" ipv4_cidr: "10.42.0.0/16" ipv6_prefix: "fd42:7269:7665::/48" routing_protocol: "babel" controller: listen: "0.0.0.0:8443" public_url: "https://mesh.riverside.example" database_url: "sqlite:////var/lib/lantern/lantern.db" enrollment_ttl: "15m" mesh: interface: "mesh0" band: "5ghz" channel: 149 channel_width: "40mhz" encryption: "sae" country_code: "CA" access: ssid: "Riverside Community WiFi" client_isolation: true captive_portal: true default_download_mbps: 25 default_upload_mbps: 10 gateways: selection: "latency" health_check_interval: "15s" failover_threshold: 3 dns: upstream: - "1.1.1.1" - "2606:4700:4700::1111" cache_size: 10000 local_zone: "mesh.riverside.example" monitoring: prometheus: enabled: true listen: "127.0.0.1:9108" log_level: "info" retain_metrics: "30d" ``` ### Important settings | Setting | Description | |---|---| | `network.ipv4_cidr` | Private address range assigned to mesh nodes and clients. | | `network.ipv6_prefix` | ULA or delegated IPv6 prefix for the network. | | `mesh.country_code` | Regulatory domain used to restrict channels and transmit power. | | `mesh.channel` | Radio channel shared by mesh links in this profile. | | `access.client_isolation` | Prevents member devices on the same access point from communicating directly. | | `access.default_*_mbps` | Default per-member bandwidth limits. | | `gateways.selection` | Gateway selection strategy: `latency`, `capacity`, or `static`. | | `controller.public_url` | Address nodes use to reach the controller. | Secrets should not be committed to the configuration file. Store them in a root-readable environment file: ```sh sudo install -m 0600 config/lantern.env.example /etc/lantern/lantern.env ``` Then reference them from YAML: ```yaml controller: database_url: "${LANTERN_DATABASE_URL}" ``` ## Operations ### Backups Back up the controller database, configuration, and certificate directory: ```sh sudo lantern backup create --output /var/backups/lantern ``` Test restoration regularly: ```sh sudo lantern backup verify /var/backups/lantern/lantern-backup.tar.zst ``` ### Monitoring Prometheus metrics are available at `/metrics` on the configured monitoring address. Recommended alerts include: - Gateway unavailable - Node offline for more than 10 minutes - Mesh link packet loss above 20% - Channel utilization above 80% - Controller certificate nearing expiration - Address pool nearing capacity ### Troubleshooting Check controller logs: ```sh sudo journalctl -u lantern --since "30 minutes ago" ``` Run diagnostics for a node: ```sh lantern diagnose library-roof ``` Verify routing and gateway reachability: ```sh lantern route list lantern gateway check ``` If a node becomes unreachable after a configuration change, connect locally over Ethernet and run: ```sh lantern-node rollback ``` ## Security - Change default device credentials before installation. - Use unique enrollment credentials for every node. - Restrict controller access with a firewall. - Keep OpenWrt and Lantern packages updated. - Separate management, mesh, and member traffic where hardware permits. - Publish an acceptable-use and privacy policy for members. - Collect only the operational data required to maintain the network. - Establish a process for handling abuse reports and compromised nodes. Report security issues privately to `security@lanternmesh.example`. Do not open public issues for undisclosed vulnerabilities. ## Contributing Contributions from network operators, firmware developers, documentation writers, and community organizers are welcome. Before submitting a change: ```sh pip install -e ".[dev]" ruff check . pytest ``` Open an issue for major protocol, architecture, or configuration changes before starting implementation. ## License Lantern Mesh is licensed under the GNU Affero General Public License v3.0 or later. See `LICENSE` for details.