# OpenMesh ISP OpenMesh ISP is an open-source toolkit for operating a community-owned wireless mesh network. It helps local organizations provision routers, coordinate gateways, monitor link health, and provide resilient neighborhood internet access using affordable hardware. > **Project status:** Early production. Suitable for pilots and small community networks. Test upgrades in a staging environment before deploying them network-wide. ## Overview Each participating router forms encrypted links with nearby nodes and automatically discovers the best path to an internet gateway. If a node or connection fails, traffic is rerouted through the remaining mesh. OpenMesh ISP includes: - A controller API for node enrollment, configuration, and telemetry - A lightweight router agent for OpenWrt-compatible devices - A web dashboard for operators and community support teams - Prometheus metrics and structured audit logs - Optional captive-portal and subscriber-account integrations The project manages the mesh control plane. It does not replace upstream internet service, radio planning, billing, or local regulatory compliance. ## Features - Automatic peer discovery and route convergence - Multiple gateways with configurable priorities - Per-node and per-zone bandwidth policies - Secure enrollment using short-lived tokens - Remote configuration with staged rollouts - Link-quality, latency, traffic, and uptime monitoring - Offline-tolerant router operation - IPv4 NAT and native IPv6 support - Role-based operator access - Configuration backups and audit history ## Requirements For a small deployment, the controller requires: - Linux host or virtual machine - Docker Engine 24 or later - Docker Compose v2 - 2 CPU cores and 4 GB RAM - PostgreSQL 15 or later - A DNS name with TLS - UDP connectivity between mesh nodes Router nodes require supported OpenWrt hardware with at least 16 MB of flash and 128 MB of RAM. Two radios are recommended so client access and mesh backhaul can use separate channels. ## Install Clone the repository and create a local configuration file: ```sh git clone https://github.com/example/openmesh-isp.git cd openmesh-isp cp .env.example .env ``` Generate application secrets: ```sh openssl rand -hex 32 openssl rand -base64 32 ``` Add the generated values to `.env`, then start the controller: ```sh docker compose pull docker compose up -d docker compose exec controller openmesh migrate docker compose exec controller openmesh admin create ``` Verify that the services are healthy: ```sh docker compose ps curl -fsS https://mesh.example.org/health ``` Open `https://mesh.example.org` and sign in with the administrator account created during installation. ### Install a router node Build or download the OpenWrt package that matches the router architecture, copy it to the device, and install it: ```sh scp dist/openmesh-agent_*.ipk root@192.168.1.1:/tmp/ ssh root@192.168.1.1 opkg install /tmp/openmesh-agent_*.ipk ``` Create a single-use enrollment token in the dashboard under **Nodes → Enroll node**, then run: ```sh openmesh-agent enroll \ --controller https://mesh.example.org \ --token ENROLLMENT_TOKEN ``` Enrollment may replace the router's network configuration. Use a wired maintenance connection and export an OpenWrt backup before enrolling remote devices. ## Usage ### Add a gateway A gateway provides upstream internet access to the mesh: ```sh openmesh gateway create community-hall \ --node hall-router-01 \ --interface wan \ --priority 100 ``` Confirm that the gateway is reachable: ```sh openmesh gateway list openmesh node inspect hall-router-01 ``` ### Create a network zone Zones group nodes that share radio and traffic policies: ```sh openmesh zone create north-block \ --channel 149 \ --bandwidth 40MHz \ --client-limit 100mbit ``` Assign nodes to the zone: ```sh openmesh node update roof-01 --zone north-block openmesh node update roof-02 --zone north-block ``` ### Roll out configuration Validate pending changes before applying them: ```sh openmesh config validate openmesh config diff ``` Deploy to a small group first: ```sh openmesh config deploy --zone north-block --limit 2 ``` After confirming connectivity and link quality, complete the rollout: ```sh openmesh config deploy --zone north-block ``` ### Check network health ```sh openmesh status openmesh node list --unhealthy openmesh link list --sort signal openmesh events tail ``` ## Configuration Controller settings are read from environment variables. Router and network policies are stored by the controller and delivered to enrolled nodes. ### Controller environment A minimal `.env` file looks like this: ```dotenv OPENMESH_PUBLIC_URL=https://mesh.example.org OPENMESH_LISTEN_ADDR=0.0.0.0:8080 OPENMESH_DATABASE_URL=postgres://openmesh:change-me@postgres/openmesh OPENMESH_SESSION_SECRET=replace-with-a-random-value OPENMESH_ENROLLMENT_SECRET=replace-with-a-different-random-value OPENMESH_METRICS_ENABLED=true OPENMESH_LOG_LEVEL=info OPENMESH_TELEMETRY_RETENTION_DAYS=30 ``` Do not commit `.env` or enrollment tokens. In production, store secrets in a dedicated secret manager and restrict access to controller backups. ### Network policy Global mesh defaults are defined in `config/network.yaml`: ```yaml network: name: neighbourhood-mesh domain: mesh.internal ipv4_pool: 10.42.0.0/16 ipv6_prefix: fd42:6d65:7368::/48 mtu: 1420 routing: protocol: batman-adv gateway_mode: client gateway_failover_seconds: 15 wireless: country: CA backhaul_band: 5ghz channel: 149 channel_width: 40 tx_power_dbm: 20 minimum_signal_dbm: -78 clients: isolation: true default_download_mbit: 50 default_upload_mbit: 20 dns: servers: - 1.1.1.1 - 9.9.9.9 ``` Set `wireless.country`, channels, frequencies, and transmit power according to local law and the capabilities of deployed hardware. ### Node overrides Use node overrides sparingly for installation-specific values: ```yaml nodes: roof-01: wireless: tx_power_dbm: 17 library-gateway: routing: gateway_mode: server interfaces: wan: eth0 ``` Validate configuration after editing: ```sh openmesh config validate ``` ## Operations Back up the database and controller secrets regularly: ```sh docker compose exec postgres pg_dump -U openmesh openmesh > openmesh-backup.sql ``` Before upgrading: 1. Review the release notes. 2. Back up the database and configuration. 3. Upgrade a staging controller and one test node. 4. Confirm routing, DNS, and gateway failover. 5. Roll out to production in batches. ## Security Treat the controller, gateway nodes, signing keys, and enrollment tokens as sensitive infrastructure. Restrict management access, enable multi-factor authentication, use short-lived enrollment tokens, and promptly revoke lost or decommissioned devices. To report a vulnerability, email `security@example.org`. Do not open a public issue for undisclosed security problems. ## Contributing Contributions are welcome from network operators, community organizers, documentation writers, and developers. Open an issue before beginning a large change, and include tests for changes to routing, provisioning, or configuration validation. By participating, you agree to follow the project's code of conduct. ## License OpenMesh ISP is licensed under the GNU Affero General Public License v3.0. See `LICENSE` for details.