{"id":20218030,"url":"https://github.com/matrix-org/meshsim","last_synced_at":"2025-04-10T15:45:41.123Z","repository":{"id":53659027,"uuid":"175012349","full_name":"matrix-org/meshsim","owner":"matrix-org","description":"Matrix mesh simulator","archived":false,"fork":false,"pushed_at":"2023-02-02T06:35:13.000Z","size":1375,"stargazers_count":97,"open_issues_count":3,"forks_count":8,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-24T13:36:18.664Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.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}},"created_at":"2019-03-11T14:01:56.000Z","updated_at":"2025-02-04T14:20:48.000Z","dependencies_parsed_at":"2023-02-17T15:30:51.303Z","dependency_job_id":null,"html_url":"https://github.com/matrix-org/meshsim","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/matrix-org%2Fmeshsim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmeshsim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmeshsim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmeshsim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/meshsim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248243511,"owners_count":21071055,"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-11-14T06:36:53.764Z","updated_at":"2025-04-10T15:45:41.090Z","avatar_url":"https://github.com/matrix-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Simulates a mesh of homeservers with Docker.\n\n![meshsim](meshsim.gif)\n\nMeshsim lets you define and manage an arbitrary network of Matrix homeservers\nin docker containers via a web interface.  Servers are instantiated by clicking\non the canvas, and the network topology and latency may be adjusted by dragging\nservers around.  Servers connect to the nearest 5 nodes within the given latency\nthreshold.\n\nThe bandwidth and latency of individual network links can be overridden by clicking\non the link (which will turn red) and adjusting the specific values.\n\nTraffic on the network is visualised in realtime by having servers\nemit telemetry to the simulator via websocket, showing which events are emitted\nand received from which server via which network link.  Events are shown as\nanimated circles which follow the network links between servers.  When a server\nprocesses an inbound event, it shows an animation of the event expanding and popping\nlike a bubble.\n\nThe default docker image that meshsim launches is https://github.com/matrix-org/meshsim-docker\nwhich provides both a Synapse and a [coap-proxy](https://github.com/matrix-org/coap-proxy)\nfor low-bandwidth Matrix transport experimentation.\n\nFurther details can be found in our FOSDEM 2019 talk about meshsim and coap-proxy at:\nhttps://matrix.org/blog/2019/03/12/breaking-the-100bps-barrier-with-matrix-meshsim-coap-proxy/\n\n#### Notes\n\n * Requires a HS with a Dockerfile which lets it be run in a Debianish container to support KSM.\n * Uses KSM to share memory between the server containers.\n * Uses a local postgres shared across all the servers as their DB for simplicity.\n * Uses Flask and NetworkX to model the network topology in python.\n   * It puppets the dockerized HSes via `docker run` and talking HTTP to a `topologiser` daemon that runs on the container.\n   * We deliberately use this rather than docker-compose or docker stack/swarm given the meshsim itself is acting as an orchestrator.\n * Uses D3 to visualise and control the network topology in browser.\n * Manually puppets the routing tables of the servers based on running dijkstra on the network topo\n * Manually puppets TC on the servers to cripple bandwidth, latency \u0026 jitter as desired.\n   * Rather than forcing docker to spin up multiple interfaces per host (which would require gutwrenching the docker's network namespaces), we instead cripple bandwidth on egress traffic per upstream router (as identified by its MAC).\n\nNow usable in general, but may be a bit fiddly to get up and running.\n\n#### Installation\n\n * Supported on macOS (with Docker-for-mac 18.06, not 2.0) \u0026 Linux\n\n * Meshsim requires an up-to-date python installation of at least python 3.6\n   * Check with `python --version` and/or `python3 --version`\n   * Install python dependencies with `pip install -r requirements.txt` or `pip3 install -r requirements.txt`\n\n * Install Docker from docker.com (needs API 1.38; API 1.2x is known not to work.).\n   * Check the API with `docker version`.\n   * Your OS packages will probably be too old.\n\n * create a docker network: `docker network create --driver bridge mesh`. Later\n   we will need to know the gateway IP (so that the images can talk to postgres,\n   meshsim, etc on the host). On MacOS `host.docker.internal` will work,\n   otherwise run `docker network inspect mesh` and find the Gateway IP.\n\n * Install postgres\n   * `createuser -P synapse` # password synapseftw\n   * edit postgresql.conf to ensure postgres is listening on an IP that docker\n     containers will be able to hit. Set `listen_addresses = '\u003cbridge ip\u003e,localhost'`,\n     although that will only work after step \"create a docker network\".\n     If you can't find the config file, have a look in `/var/lib/pgsql/data/`.\n   * edit pg_hba.conf to ensure connections from docker container IPs will be\n     allowed (e.g. by enabling `trust` for user `synapse`). Example:\n\n```\n# Add the following to the end of the file\nlocal   all             synapse                                 trust\nhost    all             all             YOUR_DOCKER_HOST_IP/16  trust\n```\n\n   * Recommended: It's worth making the user you plan to run meshsim a superuser\n   in postgres, such that commands do not need to be prefixed with `sudo -u postgres`.\n   You can do so with the following:\n\n   ```\n   sudo -u postgres createuser --superuser --no-password user\n   ```\n\n * Optional: Enable KSM on your host so your synapses can deduplicate RAM\n   as much as possible\n\n ```sh\nscreen ~/Library/Containers/com.docker.docker/Data/vms/0/tty  # on Docker-for-Mac\necho 1 \u003e /sys/kernel/mm/ksm/run\necho 10000 \u003e /sys/kernel/mm/ksm/pages_to_scan # 40MB of pages at a time\n\n# check to see if it's working (will only kick in once you start running something which requests KSM, like our KSMified synapse)\ngrep -H '' /sys/kernel/mm/ksm/run/*\n```\n\n * create a empty directory, e.g. `matrix-low-bandwidth`\n\n * check out meshsim\n```\nmatrix-low-bandwidth$ git clone https://github.com/matrix-org/meshsim.git\n```\n\n * Build the (KSM-capable) docker image:\n   * Clone `synapse` repo and checkout the `babolivier/low-bandwidth` branch (inside the `matrix-low-bandwidth` directory)\n```\nmatrix-low-bandwidth$ git clone https://github.com/matrix-org/synapse.git\nmatrix-low-bandwidth$ cd synapse\nsynapse$ git checkout babolivier/low-bandwidth\n```\n\n   * Clone the `meshsim-docker` repo (inside the `matrix-low-bandwidth` directory)\n```\nmatrix-low-bandwidth$ git clone https://github.com/matrix-org/meshsim-docker.git\n```\n\n   * Clone the `coap-proxy` repo (inside the `matrix-low-bandwidth` directory)\n```\nmatrix-low-bandwidth$ git clone https://github.com/matrix-org/coap-proxy.git\n```\n\n   * Run `docker build -t synapse -f meshsim-docker/Dockerfile .` from the top of the\n     `matrix-low-bandwidth` directory (***not*** inside the `synapse` repo)\n\n * Optionally edit `start_hs.sh` to add bind mount to a local working copy of\n   synapse. This allows doing synapse dev without having to rebuild images. See\n   `start_hs.sh` for details. An example of the `docker run` command in `start_hs.sh` is below:\n\n```\ndocker run -d --name synapse$HSID \\\n\t--privileged \\\n\t--network mesh \\\n\t--hostname synapse$HSID \\\n\t-e SYNAPSE_SERVER_NAME=synapse${HSID} \\\n\t-e SYNAPSE_REPORT_STATS=no \\\n\t-e SYNAPSE_ENABLE_REGISTRATION=yes \\\n\t-e SYNAPSE_LOG_LEVEL=INFO \\\n\t-e POSTGRES_DB=synapse$HSID \\\n\t-e POSTGRES_PASSWORD=synapseftw \\\n\t-p $((18000 + HSID)):8008 \\\n\t-p $((19000 + HSID)):3000 \\\n\t-p $((20000 + HSID)):5683/udp \\\n\t-e POSTGRES_HOST=$HOST_IP \\\n\t-e SYNAPSE_LOG_HOST=$HOST_IP \\\n\t-e SYNAPSE_USE_PROXY=1 \\\n\t-e PROXY_DUMP_PAYLOADS=1 \\\n\t--mount type=bind,source=/home/user/matrix-low-bandwidth/coap-proxy,destination=/proxy \\\n\t--mount type=bind,source=/home/user/matrix-low-bandwidth/synapse/synapse,destination=/usr/local/lib/python3.7/site-packages/synapse \\\n\tsynapse\n```\n\n * check you can start a synapse via `./start_hs.sh 1 $DOCKER_IP` with DOCEKR_IP being the docker network gateway IP.\n    * If the template import fails with something about `en_GB`, make sure you have that locale generated. Replacing `en_GB` with `en_US` or whatever your locale is in `synapse_template.sql` is also sufficient.\n * check if it's running with `docker stats`\n * check the supervisor logs with `docker logs -f synapse1` and that it can talk to your postgres ok\n * log into the container to poke around with `docker exec -it synapse1 /bin/bash`\n    * Actual synapse logs are located at `/var/log/supervisor/synapse*`\n\n * Check you can connect to its synapse at http://localhost:18001 (ports are 18000 + hsid).\n   * Requires a Riot running on http on localhost or similar to support CORS to non-https\n   * Initial user sign up may time out due to trying to connect to Riot-bot. Simply refresh the page and you should get in fine.\n   * The KSM'd dockerfile autoprovisions an account on the HS called l/p matthew/secret for testing purposes.\n * Check that the topologiser is listening at http://localhost:19001 (ports are 19000 + hsid)\n    * Don't expect to navigate to this URL and see anything more than a 404. As long as *something* is listening at this port, things are set up correctly.\n\n * shut it down nicely `./stop_clean_all.sh`\n\n * run meshsim:  `./meshsim.py \u003cHOST_IP\u003e` where `\u003cHOST_IP\u003e` is the docker\n   network IP for the host (c.f. \"create a docker network\" step). Run\n   `./meshsim.py -h` for more options.\n * connect to meshsim http://localhost:3000\n * click to create HSes\n * drag to move them around\n * =\u003e profit\n\nYou can log into the individual synapse containers as `docker exec -it synapse$N /bin/bash` to traceroute, ping\nand generally see what see what's going on.\n\n#### Using the CoAP proxy\n\n* Build the proxy (see instruction in the [proxy's README](https://github.com/matrix-org/coap-proxy/blob/master/README.md))\n* Run it by telling it to talk to the HS's proxy:\n\n```bash\n./bin/coap-proxy --coap-target localhost:20001 # Ports are 20000 + hsid\n```\n\n* Make clients talk to http://localhost:8888\n* =\u003e profit\n\n#### Limitations\n\nClient-Server traffic shaping is only currently supported on macOS, as client-\u003eserver traffic shaping\nis currently implemented on the host (client) side.\n\n#### License\n\nCopyright 2019 New Vector Ltd\n\nThis file is part of meshsim.\n\nmeshsim is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nmeshsim is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with meshsim.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmeshsim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmeshsim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmeshsim/lists"}