{"id":24196534,"url":"https://github.com/dedis/simnet","last_synced_at":"2025-09-21T21:31:56.490Z","repository":{"id":36595104,"uuid":"224449081","full_name":"dedis/simnet","owner":"dedis","description":"SimNet is a tool to simulate decentralized applications in the cloud","archived":false,"fork":false,"pushed_at":"2022-08-26T11:10:30.000Z","size":494,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-24T00:41:30.903Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dedis.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-11-27T14:28:34.000Z","updated_at":"2024-03-26T21:11:15.000Z","dependencies_parsed_at":"2022-08-08T16:01:03.357Z","dependency_job_id":null,"html_url":"https://github.com/dedis/simnet","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fsimnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fsimnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fsimnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fsimnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dedis","download_url":"https://codeload.github.com/dedis/simnet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233798289,"owners_count":18731954,"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":"2025-01-13T19:35:45.624Z","updated_at":"2025-09-21T21:31:51.109Z","avatar_url":"https://github.com/dedis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simnet\n\n[![Build Status](https://travis-ci.org/dedis/simnet.svg?branch=master)](https://travis-ci.org/dedis/simnet)\n[![Coverage Status](https://coveralls.io/repos/github/dedis/simnet/badge.svg?branch=master)](https://coveralls.io/github/dedis/simnet?branch=master)\n![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/dedis/simnet?label=version)\n\nSimNet is a tool to simulate a decentralized application using the cloud to\nhost the simulation nodes. It provides multiple configurations to affect the\ntopology so that specific link between two nodes can have a delay or a loss\nof packets for instance.\n\nThe tool is designed to work with three phases:\n - Deployment: everything the simulation needs is deployed to the cloud.\n - Execution: the actual simulation is performed and statistics are written\n to a JSON file.\n - Cleaning: it wipes everything in scope to the simulation.\n\nThoses phases are designed to be independant so that they can be run separatly\nwhich means that simulations can be executed multiple times without deploying.\n\n## Strategies\n\nThe environment the simulation is running on depends on the chosen strategy. Two\nare currently available: Kubernetes and Docker.\n\nIt is completly interchangeable so that you can test your simulation locally with\nDocker and a small number of nodes. Then the simulation can be deployed on\nKubernetes with a bigger amount of nodes.\n\n### Kubernetes\n\nWhen a simulation is deployed to a Kubernetes cluster, each instance of the\napplication uses a POD that will contain the application Docker container\nalongside with a monitor container that will gather data for the statistics.\n\nOne POD will also be used to deploy a router that will simply run OpenVPN so\nthat the simulation can open a tunnel to the cluster network, on the `simnet-router`\npod and thus make requests to the simnet nodes. Simnet uses a NodePort to\ncommunicate with the Kubernetes node running the `simnet-router` Pod. If you\nare using a public cloud provider, please ensure the NodeIP is publically\naccessible and UDP traffic is allowed on the cluster.\n\n### Docker\n\nSimulations with the Docker strategy will interact with the local Docker setup\nto create one container per Node. Each of those containers will need another\ntemporary container to configure the network emulation (latencies, etc...) but\nthey will terminate before the simulation begins and they are booted one after\nthe other.\n\n## Daemons\n\nSome strategies like Kubernetes might need additionnal containers to work. These\nare built independently using the automated build of DockerHub.\n\n| Router | Router Init | Monitor |\n| ------ | ----------- | ------- |\n| [![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/dedis/simnet-router?style=flat-square)](https://hub.docker.com/repository/docker/dedis/simnet-router/timeline) | [![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/dedis/simnet-router-init?style=flat-square)](https://hub.docker.com/repository/docker/dedis/simnet-router-init/timeline) | [![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/dedis/simnet-monitor?style=flat-square)](https://hub.docker.com/repository/docker/dedis/simnet-monitor/timeline) |\n\nDocker images for the daemons have their own version that will trigger a build\nfor each new version. The master branch will also build its own tag for each\nnew commit.\n\nDockerhub is configured to automatically create the following tags:\n- `latest` for the master branch\n- `x.y.z` for each `daemon-vx.y.z` tag on the repository\n\n# Getting started\n\n## Setup\n\nTo run simulations with Kubernetees, **OpenVPN** needs to be installed.\n\nBy default, simnet looks for OpenVPN in `/usr/local/opt/openvpn/sbin/openvpn` (that should be the case for example if you used Homebrew on MacOS to install OpenVPN), but you can specify a different path with the `-vpn` CLI option.\n\nFor **MacOS** users, OpenVPN is also required to run Docker simulation (this is due to MacOS runing docker via a VM).\n\n## Writing the simulation\n\nA basic template with the Docker strategy is shown below:\n\n```go\ntype simRound struct {}\n\nfunc (s simRound) Execute(ctx context.Context) error {\n    return nil\n}\n\nfunc main() {\n    engine, err := docker.NewStrategy(options...)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tsim := simnet.NewSimulation(simRound{}, engine)\n\n\terr = sim.Run(os.Args)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n}\n```\n\nA few number of options is necessary to run an application.\n\n```go\noptions := []sim.Option{\n    sim.WithTopology(\n        net.NewSimpleTopology(3, 25),\n    ),\n    sim.WithImage(\n        \"nginx\", // DockerHub image\n        nil, // CMD if needed\n        nil, // ARGS if needed\n        sim.NewTCP(8080),\n    ),\n}\n```\n\nFinally, the simulation tool provides a bunch of command-line arguments so that\nit is easier to run the different phases. Assuming a `main.go`, use the\nfollowing:\n\n```bash\n# Runs the simulation from A to Z.\ngo run main.go\n\n# ... or do it step by step\ngo run main.go -do-deploy\n\n# This can be done multiple times but be aware that statistics will be\n# overwritten.\ngo run main.go -do-execute\n\n# Important to reduce the cost\ngo run main.go -do-clean\n```\n\n### Plots\n\nFirst you need to install the plot tool\n```bash\ngo get -u go.dedis.ch/simnet/metrics/simplot\n```\n\nThen to draw a plot\n```bash\nsimplot graph -output plot-tx.png tx\nsimplot graph -output plot-rx.png rx\nsimplot graph -output plot-cpu.png cpu\nsimplot graph -output plot-mem.png mem\n```\n\nYou can always use the `-h` option (for example `simplot -h`, or `simplot graph -h`) to see the full list of options and commands available, such as computing the max or average.\n\n## Context\n\nThe context passed to the round execution contains some pieces of information\nthat can be useful when running a simulation.\n\n### NodeInfo\n```go\nnodes := ctx.Value(sim.NodeInfoKey{}).([]sim.NodeInfo)\naddr := nodes[0].Address\n```\n\n### Files\nA file mapper can be specifiec in the strategy options. This file will be read\non each application node and stored in the execution context.\n\n```go\nfiles := ctx.Value(sim.FilesKey(\"my.conf\")).(sim.Files)\nfor ident, file := range files {\n    ...\n}\n```\n\nSee the skipchain example for more details.\n\n# How to\n\n## How to simulate with Kubernetes locally ?\n\nThis section describes a setup using Minikube to run a local Kubernetes cluster\nwhere the simulation can be deployed.\n\nCaveat: Minikube VM does not have the _sch_netem_ module which means Chaos\ntesting does not work out of the box and requires a few steps more.\n\n### Install Minikube\n\nFollow the instructions [here](https://minikube.sigs.k8s.io/docs/start/) then\n\n```bash\n# Start the cluster.\nminikube start --docker-opt bip=172.18.0.1/16\n\n# In case of error, you can first try to delete the previous cluster.\nminikube delete\n\n# After the cluster has started, you can monitor with the dashboard.\nminikube dashboard\n```\n\n### Build the docker images\n\nA local change to the daemon images can be used by building the images inside\nminikube and forcing it to use the local ones. You will need to add \"Never\" for\nthe image pull policy in the kubernetes deployments.\n\n```bash\n# Set the docker environment variables for this session.\neval $(minikube docker-env)\n\ncd $SIMNET_DIR\nmake build_monitor\nmake build_router\n```\n\nMininet will now have the required images in its local images store. The\nsimulation image still need to be deployed on DockerHub.\n\n### Run the simulation\n\nThe simulation is now ready to be run.\n\n```bash\ncd $SIMNET_DIR\nmake EXAMPLE=\"skipchain\" run # be patient, time for a coffee !\n# or make run to run the default simulation.\n\n# In case the simulation fails and cannot clean the cluster correctly, you\n# can force the deletion.\nmake clean\n```\n\n### Chaos testing in Minikube\n\nThis section describes the steps to get a local cluster that supports Chaos\nby enabling the right kernel module in the Minikube ISO.\n\n```bash\ncd $HOME/workspace # ... or a different folder\ngit clone git@github.com:kubernetes/minikube.git\n\ncd minikube\nmake buildroot-image\nmake out/minikube.iso\nmake linux-menuconfig\n\n# Inside the Kconfig menu, you will to navigate to\n#   --\u003e Networking support\n#   --\u003e Networking options\n#   --\u003e QoS and/or fair queuing\n#   --\u003e Network Emulator (NETEM) + HTB\n# Press space until you have \u003c*\u003e for NETEM\n# Finally, save and close the menu\n\nmake out/minikube.iso\n./out/minikube delete\n./out/minikube start --iso-url=file://$(pwd)/out/minikube.iso\n```\n\nYou can check that you are good to go by checking that the Minikube VM has\nthe module enabled.\n\n```bash\n./out/minikube ssh\n$ modprobe sch_netem # should not display an error\n```\n\n---\n\n\u003cimg width=\"200px\" src=\"unicore_logo.png\"/\u003e\n\nThis project has received funding from the European Union's Horizon 2020 \nresearch and innovation programme under grant agreement No 825377.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedis%2Fsimnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdedis%2Fsimnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedis%2Fsimnet/lists"}