# Lantern Mesh

Lantern Mesh is a community-operated wireless mesh-network ISP designed to provide affordable, resilient internet access in neighborhoods underserved by traditional providers.

Each participating site runs a mesh node that connects to nearby nodes over encrypted wireless links. Gateway nodes provide upstream internet access, while local services remain available across the mesh during upstream outages.

## Features

- Self-forming, self-healing wireless mesh
- Multiple internet gateways with automatic failover
- Encrypted node-to-node links
- Per-member bandwidth limits and fair-usage policies
- Local DNS, service discovery, and community-hosted services
- Prometheus metrics and health checks
- Optional captive portal for member onboarding
- IPv4 and IPv6 support
- Configuration managed through version-controlled YAML
- Designed for commodity OpenWrt routers and Linux gateways

## Architecture

A typical deployment includes:

- **Mesh nodes** installed on rooftops, balconies, or community buildings
- **Gateway nodes** connected to one or more upstream internet providers
- **Controller** responsible for configuration, member records, and monitoring
- **Local services** such as DNS, status pages, mirrors, and community applications

Lantern Mesh uses WireGuard for encrypted tunnels and Babel for dynamic route selection. The controller does not forward subscriber traffic and is not required for basic mesh routing.

## Requirements

### Controller

- Linux host or virtual machine
- Docker Engine 24 or later
- Docker Compose v2
- 2 CPU cores
- 2 GB RAM
- 10 GB available storage
- A static LAN address reachable by mesh nodes

### Mesh nodes

- OpenWrt 23.05 or later
- At least 16 MB flash and 128 MB RAM
- One supported 5 GHz radio for mesh backhaul
- Ethernet or a second radio for subscriber access
- Accurate system time through NTP

Outdoor installations should use weather-rated enclosures, grounded Ethernet surge protectors, and properly secured mounting hardware.

## Installation

Clone the repository:

```sh
git clone https://github.com/lantern-mesh/lantern-mesh.git
cd lantern-mesh
```

Create the local environment file:

```sh
cp .env.example .env
```

Generate controller secrets:

```sh
./scripts/generate-secrets.sh
```

Review `config/mesh.yaml`, then start the controller services:

```sh
docker compose up -d
```

Run the initial database migration:

```sh
docker compose exec controller lantern migrate
```

Create an administrator account:

```sh
docker compose exec controller lantern admin create
```

The management interface is available at `https://<controller-address>:8443`.

For production deployments, place the controller behind a reverse proxy with a trusted TLS certificate and restrict administrative access to the management network or VPN.

## Adding a Mesh Node

Register the node with the controller:

```sh
docker compose exec controller lantern node create \
  --name library-roof \
  --site library \
  --model gl-mt6000
```

The command prints a one-time enrollment token. On the OpenWrt node, install the agent package and enroll it:

```sh
opkg update
opkg install lantern-agent
lantern-agent enroll \
  --controller https://mesh-controller.example.net \
  --token <enrollment-token>
```

After enrollment, verify connectivity:

```sh
lantern-agent status
```

A healthy node should report an active WireGuard interface, at least one mesh neighbor, and a recent controller check-in.

## Usage

### Check network status

```sh
docker compose exec controller lantern status
```

### List nodes

```sh
docker compose exec controller lantern node list
```

### Inspect a node

```sh
docker compose exec controller lantern node show library-roof
```

### View mesh routes

```sh
docker compose exec controller lantern route list
```

### Apply configuration changes

Validate the configuration before deployment:

```sh
docker compose exec controller lantern config validate
```

Apply it to all online nodes:

```sh
docker compose exec controller lantern config deploy
```

Deploy to a single node:

```sh
docker compose exec controller lantern config deploy --node library-roof
```

### View logs

```sh
docker compose logs -f controller
```

Node logs are available through OpenWrt:

```sh
logread -e lantern
```

## Configuration

The main configuration file is `config/mesh.yaml`.

```yaml
mesh:
  name: lantern
  domain: mesh.example.net

  ipv4:
    network: 10.72.0.0/16

  ipv6:
    prefix: fd42:72::/48

  routing:
    protocol: babel
    hello_interval_seconds: 4
    route_expiry_seconds: 60

wireless:
  country: CA
  backhaul:
    band: 5ghz
    channel: 149
    width: 40
    tx_power_dbm: 20
  access:
    ssid: Lantern Community Internet
    security: wpa2-wpa3

gateways:
  selection: lowest-cost
  health_check:
    targets:
      - 1.1.1.1
      - 9.9.9.9
    interval_seconds: 15
    failure_threshold: 3

members:
  default_plan: community
  plans:
    community:
      download_mbps: 50
      upload_mbps: 15
      monthly_transfer_gb: 500
    sponsor:
      download_mbps: 150
      upload_mbps: 50
      monthly_transfer_gb: 2000

dns:
  upstream:
    - tls://1.1.1.1
    - tls://9.9.9.9
  local_zone: lan.mesh.example.net

monitoring:
  prometheus:
    enabled: true
    listen: 0.0.0.0:9090
  retention_days: 30
```

### Environment Variables

Controller-specific settings are stored in `.env`.

| Variable | Description | Default |
| --- | --- | --- |
| `LANTERN_LOG_LEVEL` | Logging level | `info` |
| `LANTERN_HTTP_ADDR` | Controller API listen address | `0.0.0.0:8080` |
| `LANTERN_HTTPS_ADDR` | Management interface address | `0.0.0.0:8443` |
| `LANTERN_DATABASE_URL` | PostgreSQL connection string | Set by Compose |
| `LANTERN_CONFIG_PATH` | Path to the mesh configuration | `/etc/lantern/mesh.yaml` |
| `LANTERN_PUBLIC_URL` | Public controller URL used by nodes | Required |
| `LANTERN_SESSION_SECRET` | Administrative session signing key | Required |
| `LANTERN_ENROLLMENT_TTL` | Enrollment token lifetime | `30m` |

Do not commit `.env`, enrollment tokens, private keys, database backups, or exported member records.

## Network Planning

Assign each node a stable name based on its site, such as `library-roof` or `oak-st-142`. Before installation:

1. Confirm line of sight to at least two existing nodes.
2. Record the site owner’s permission and emergency contact.
3. Photograph the mounting location and cable route.
4. Measure signal strength after alignment.
5. Label the router, power supply, and Ethernet cable.
6. Update the network map and maintenance notes.

For reliable service, target a signal level above `-65 dBm` and avoid building a topology where an entire area depends on one relay.

## Backups

Create a controller backup:

```sh
./scripts/backup.sh
```

Backups include the database, controller configuration, and public node metadata. Private node keys remain on their respective devices.

Restore a backup into a stopped deployment:

```sh
docker compose down
./scripts/restore.sh backups/lantern-2026-07-17.tar.zst
docker compose up -d
```

Test restores regularly and store encrypted copies in at least two physical locations.

## Troubleshooting

### Node has no neighbors

- Verify the configured country, channel, and channel width.
- Confirm that both nodes use the same backhaul settings.
- Check antenna alignment and line of sight.
- Run `iw dev mesh0 station dump` to inspect link quality.
- Confirm that local regulations permit the configured transmit power.

### Node has mesh access but no internet

- Check gateway health with `lantern route list`.
- Verify DNS resolution from the node.
- Confirm that the member account is active.
- Inspect firewall and NAT rules on the selected gateway.
- Test another gateway before rebooting equipment.

### Node is offline in the controller

- Confirm that routing still works locally.
- Check system time and TLS certificate validity.
- Verify the controller URL in `/etc/config/lantern`.
- Inspect logs with `logread -e lantern`.
- Re-enroll only if the node identity has been intentionally revoked.

## Security

Report suspected vulnerabilities privately to `security@mesh.example.net`. Do not include member information, private keys, or active enrollment tokens in public issues.

Administrators should:

- Require multi-factor authentication
- Rotate gateway and controller credentials regularly
- Keep OpenWrt and container images updated
- Restrict management interfaces to trusted networks
- Review administrative actions and enrollment events
- Collect only the subscriber data required to operate the network
- Publish clear retention, acceptable-use, and incident-response policies

## Contributing

Community members can contribute code, documentation, installation help, site access, or equipment.

Before opening a pull request:

```sh
make lint
make test
```

Keep changes focused and include tests for routing, configuration, or billing behavior. Operational changes should include a rollback plan.

## Community Operations

Lantern Mesh is infrastructure shared by its members. Technical decisions, fees, privacy practices, and acceptable-use rules should be documented and approved through the community’s governance process.

Before operating a public network, consult qualified local experts regarding spectrum rules, permits, privacy obligations, taxation, emergency access, and ISP regulations.

## License

Lantern Mesh is licensed under the GNU Affero General Public License v3.0. See `LICENSE` for details.