# OpenMesh ISP

OpenMesh ISP is a community-operated internet service built on a wireless mesh network. Each participating node extends coverage, routes traffic around outages, and helps connect homes, local businesses, and public spaces without relying on a single central access point.

This repository contains the software used to configure mesh routers, register nodes, monitor network health, and provide a local status dashboard.

## Features

- Self-forming, self-healing mesh topology
- Multi-gateway internet uplinks with automatic failover
- Per-node bandwidth limits and traffic shaping
- WPA3 client access with isolated guest networks
- IPv4 and IPv6 support
- Local DNS caching and community service discovery
- Node registration and configuration synchronization
- Prometheus-compatible metrics
- Web dashboard for topology, uptime, and link quality
- Configuration backups and staged updates
- Works on common OpenWrt-compatible routers

## Requirements

- Linux host or supported OpenWrt router
- Python 3.11 or newer
- `batman-adv` kernel module
- `iproute2`, `iw`, and `nftables`
- One wireless interface dedicated to mesh backhaul
- Optional second wireless interface for client access
- Root privileges for network configuration

For production deployments, use wired backhaul where available and connect at least two gateway nodes to independent internet uplinks.

## Installation

Clone the repository:

```sh
git clone https://github.com/example/openmesh-isp.git
cd openmesh-isp
```

Create a virtual environment and install the package:

```sh
python3 -m venv .venv
. .venv/bin/activate
pip install .
```

Install the system service:

```sh
sudo openmesh install-service
sudo systemctl enable --now openmesh
```

Verify that the node is running:

```sh
sudo openmesh status
```

### OpenWrt

Copy the release package to the router and install it with `opkg`:

```sh
scp dist/openmesh_1.0.0_all.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 opkg install /tmp/openmesh_1.0.0_all.ipk
```

Edit `/etc/openmesh/config.yml`, then enable the service:

```sh
/etc/init.d/openmesh enable
/etc/init.d/openmesh restart
```

## Usage

### Register a node

Each router needs a unique name and a registration token issued by the community network administrator:

```sh
sudo openmesh register \
  --name library-roof-01 \
  --token "$OPENMESH_REGISTRATION_TOKEN"
```

Node names should describe a stable location rather than a person or hardware serial number.

### Start the mesh

```sh
sudo openmesh start
```

The node creates the mesh interface, joins nearby peers, applies firewall rules, and downloads its assigned configuration.

### Check node health

```sh
openmesh status
openmesh peers
openmesh routes
```

Example:

```text
Node:       library-roof-01
State:      online
Mesh:       community-mesh
Gateway:    market-fiber-01
Peers:      4
Uptime:     12d 08h 41m
Backhaul:   5 GHz / channel 149
Link score: 0.87
```

### Run the dashboard

```sh
openmesh dashboard --listen 127.0.0.1:8080
```

Open `http://127.0.0.1:8080` in a browser. Do not expose the dashboard directly to the public internet; place it behind an authenticated reverse proxy.

### Apply configuration changes

Validate the configuration before restarting:

```sh
sudo openmesh config check
sudo openmesh reload
```

### Upgrade a node

```sh
sudo openmesh upgrade --channel stable
```

Updates are downloaded, verified, and applied only when the node has an alternate route or is inside its configured maintenance window.

## Configuration

The default configuration file is `/etc/openmesh/config.yml`.

```yaml
node:
  name: library-roof-01
  site: downtown-library
  latitude: 43.6532
  longitude: -79.3832
  contact: noc@example.net

controller:
  url: https://controller.mesh.example.net
  token_file: /etc/openmesh/registration-token
  sync_interval: 300

mesh:
  id: community-mesh
  interface: wlan1
  mode: 802.11s
  frequency_mhz: 5745
  channel_width_mhz: 40
  encryption: sae
  key_file: /etc/openmesh/mesh.key
  routing_protocol: batman-adv

clients:
  interface: wlan0
  ssid: CommunityNet
  country: CA
  isolation: true
  network:
    ipv4_cidr: 10.42.16.1/24
    ipv6_prefix: fd42:16::/64
  dhcp:
    start: 10.42.16.50
    end: 10.42.16.220
    lease_time: 12h

gateway:
  enabled: false
  uplink_interface: eth0
  advertised_bandwidth_mbps:
    download: 100
    upload: 20

traffic:
  per_client_download_mbps: 25
  per_client_upload_mbps: 10
  fair_queueing: true
  block_peer_to_peer_clients: true

dns:
  upstream:
    - 1.1.1.1
    - 9.9.9.9
  local_zone: mesh.local

monitoring:
  metrics_enabled: true
  metrics_listen: 127.0.0.1:9108
  log_level: info
  topology_reporting: true

updates:
  channel: stable
  maintenance_window: "03:00-05:00"
  require_signed_packages: true
```

### Gateway nodes

To advertise an internet uplink, enable gateway mode:

```yaml
gateway:
  enabled: true
  uplink_interface: eth0
  advertised_bandwidth_mbps:
    download: 500
    upload: 100
```

Only enable gateway mode on nodes with permission to share their uplink. Confirm that the connection, firewall policy, and local regulations allow redistribution.

### Secrets

Keep mesh keys and registration tokens outside the main configuration file:

```text
/etc/openmesh/mesh.key
/etc/openmesh/registration-token
```

Restrict access to root:

```sh
sudo chmod 600 /etc/openmesh/mesh.key
sudo chmod 600 /etc/openmesh/registration-token
```

Never commit live credentials, subscriber information, or precise private-site coordinates to the repository.

### Environment overrides

Common settings can be overridden with environment variables:

```sh
export OPENMESH_CONFIG=/etc/openmesh/config.yml
export OPENMESH_LOG_LEVEL=debug
export OPENMESH_CONTROLLER_URL=https://controller.mesh.example.net
```

Configuration values take precedence in this order:

1. Command-line options
2. Environment variables
3. Configuration file
4. Built-in defaults

## Troubleshooting

Inspect service logs:

```sh
sudo journalctl -u openmesh -n 200
```

Confirm that the mesh interface exists:

```sh
iw dev
ip link show mesh0
```

Check nearby mesh peers:

```sh
openmesh peers --verbose
```

If a node has poor connectivity, verify antenna alignment, channel selection, line of sight, cable condition, and power stability before increasing transmit power.

## Community Operations

OpenMesh ISP is intended to be run cooperatively. Deployments should publish clear policies covering:

- Acceptable use
- Privacy and logging
- Network neutrality
- Abuse handling
- Maintenance responsibilities
- Subscription fees and hardship access
- Equipment ownership
- Service expectations and outage communication

Operators should collect only the data required to maintain the network and comply with applicable laws. Avoid retaining browsing histories or other unnecessary subscriber traffic records.

## Contributing

Issues and pull requests are welcome. Before deploying changes to production nodes:

```sh
pip install -e ".[dev]"
pytest
ruff check .
openmesh config check --file examples/node.yml
```

Test radio, firewall, and routing changes in a lab or isolated neighborhood segment first. Include rollback instructions with changes that affect connectivity.

## License

Licensed under the GNU Affero General Public License, version 3 or later. See `LICENSE` for details.