{"id":17319567,"url":"https://github.com/ziman/meshub","last_synced_at":"2025-04-14T16:14:20.232Z","repository":{"id":137833054,"uuid":"92882764","full_name":"ziman/meshub","owner":"ziman","description":"A lightweight mesh VPN","archived":false,"fork":false,"pushed_at":"2024-08-22T10:47:38.000Z","size":89,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T16:14:09.049Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ziman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-30T22:48:46.000Z","updated_at":"2025-02-02T16:56:21.000Z","dependencies_parsed_at":"2024-08-22T00:13:14.419Z","dependency_job_id":"cf855436-9021-4d90-bd61-cd709b7d8853","html_url":"https://github.com/ziman/meshub","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziman%2Fmeshub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziman%2Fmeshub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziman%2Fmeshub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziman%2Fmeshub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ziman","download_url":"https://codeload.github.com/ziman/meshub/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248914115,"owners_count":21182359,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T13:25:48.139Z","updated_at":"2025-04-14T16:14:20.192Z","avatar_url":"https://github.com/ziman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# meshub\n\nA lightweight full-mesh VPN\n\n## Features / Design\n\n* mesh connectivity with O(n²) direct client-to-client NAT-traversal edges\n* IPv6 *inside* the VPN\n\t* IPv6 in WAN has a very low priority\n* untrusted and unstable central hub with a public IPv4 address\n\t* assumed to be in the cloud, on someone else's computer, etc.\n\t* complete exposure should not affect confidentiality of other nodes' communications\n\t* if it goes down, the network must keep working (but new clients may not be able to join)\n* no packet forwarding through hub or nodes\n\t* there are only direct peer-to-peer connections\n\t* of course, OS-level routing always works\n* client-to-client edges encrypted symmetrically using a PSK\n\t* clients are trusted and can impersonate each other\n    * it would be nice to have an assymetric system with a CA that would fix this\n* Linux \u0026 OS X support\n\t* OSX needs [the tuntap driver](http://tuntaposx.sourceforge.net/)\n* a network can be either TUN or TAP\n* local host discovery using LAN broadcast\n\n## Synopsis\n\n### Hub\n\n```bash\n$ ./hub.py [-a address=0.0.0.0] [-p port=3731]\n```\n\n* No special privileges needed.\n* Almost no functionality.\n* Not part of the network -- it just mediates NAT traversal.\n* Never relays data traffic.\n* Needs a public IP address.\n\n### Client\n\n```bash\n$ sudo ./client.py client.cfg\n```\n\n* Requires root to create the TUN interface and set up routing.\n* Advertises itself to all other clients via the hub.\n* Creates direct mesh edges to all other clients.\n* Encrypts traffic using the provided PSK.\n\n### Generate a PSK\n\n```bash\n$ ./generate_fernet_key.py\n--your-key-in-urlsafe-base64--\n```\n\nPut the key into the variable named `psk` in config section `encryption`.\n\n## Related projects\n\nOther mesh VPNs worth checking out:\n* [peervpn](https://peervpn.net/)\n\t* my choice until recently, very easy to configure and get running\n\t* requires PSK to be present in cleartext on the hub node\n* [tinc](https://tinc-vpn.org/)\n\t* assymetric crypto\n\t* won't work when the central node goes down (v1.0 at least)\n\t* there's v1.1 but I haven't tried it\n* [freelan](https://freelan.org/)\n\t* PSK or CA\n\t* does not seem to create everyone-to-everyone mesh automatically\n* [tailscale](https://tailscale.com/)\n    * If I understand correctly, the security of a Tailscale network\n      depends on the central coordinating node.\n      In contrast, the meshub hub is just a dumb repeater\n      and can run on any old untrusted machine.\n      It's up to the clients to use PSK-based encryption.\n      (Beware that the unencrypted port hack makes things vulnerable.)\n\n## Troubleshooting\n\n* Computers won't connect. (Or only some of them do.)\n\t* Some networks require frequent pings to keep STUN up.\n\t  Try using the value `5` (seconds) for the following configuration options:\n\t  `select_interval_sec`, `advert_interval_sec`, `maintenance_interval_sec`,\n\t  `ping_interval_sec`.\n\n\t  More details: As long as all client-to-client connections are working,\n\t  the client-to-hub connections are unused (they are used only to establish\n\t  client-to-client connections). If client-to-hub breaks because\n\t  long ping intervals broke STUN, you won't notice until eventually a\n\t  client-to-client connection breaks and cannot be reestablished anymore\n\t  due to defunct client-to-hub communication.\n\n## Dependencies\n\n* Python 3\n* [cryptography](https://pypi.python.org/pypi/cryptography)\n\n## License\n\n[MIT](https://github.com/ziman/meshub/blob/master/LICENSE).\n\n## Wishlist/TODO\n\n* MTU discovery / propagation of the corresponding ICMP messages into the tunnel\n* assymetric crypto\n* replay resilience\n* a status command that would print all edges and their detailed diagnostics\n    * generally a RPC\n* ICMP inside VPN\n    * for unroutable hosts etc.\n* log level config option\n* make hub listen on multiple addresses (and send responses to all of them)\n* drop privileges after opening sockets \u0026 ifaces\n* a performant (but secure) symmetric encryption\n    * currently using `Fernet` from `cryptography` which should be foolproof but it's not very fast\n* possible workaround:\n\t1. an extra VPN subnet range for unencrypted data packets\n\t\t* performance-hungry scenarios are usually SFTP-related, anyway (ssh, scp, rsync, sshfs, git+ssh, ...)\n\t2. per-port exemptions (e.g. TCP(v6)/22) `\u003c-- currently used hack`\n\t\t* or other packet marking\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fziman%2Fmeshub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fziman%2Fmeshub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fziman%2Fmeshub/lists"}