{"id":13644579,"url":"https://github.com/microsoft/machnet","last_synced_at":"2025-05-16T09:05:06.533Z","repository":{"id":193122561,"uuid":"660349954","full_name":"microsoft/machnet","owner":"microsoft","description":"Machnet provides applications like databases and finance an easy way to access low-latency DPDK-based messaging on public cloud VMs. 750K RPS on Azure at 61 us P99.9.","archived":false,"fork":false,"pushed_at":"2025-01-28T17:36:30.000Z","size":5744,"stargazers_count":108,"open_issues_count":17,"forks_count":21,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-12T04:45:21.266Z","etag":null,"topics":["dpdk","low-latency"],"latest_commit_sha":null,"homepage":"","language":"C++","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/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-29T20:10:27.000Z","updated_at":"2025-05-08T22:55:24.000Z","dependencies_parsed_at":"2023-12-14T01:41:32.584Z","dependency_job_id":"4c0a32c5-0730-40a2-999b-c8f16c9b7ec4","html_url":"https://github.com/microsoft/machnet","commit_stats":{"total_commits":259,"total_committers":17,"mean_commits":"15.235294117647058","dds":0.6640926640926641,"last_synced_commit":"2a1bcd34ca29b6fccf0fdded4deda10c5357a18e"},"previous_names":["microsoft/machnet"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fmachnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fmachnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fmachnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fmachnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/machnet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501557,"owners_count":22081528,"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":["dpdk","low-latency"],"created_at":"2024-08-02T01:02:08.331Z","updated_at":"2025-05-16T09:05:01.512Z","avatar_url":"https://github.com/microsoft.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# Machnet: Easy kernel-bypass messaging between cloud VMs\n\n[![Build](https://github.com/microsoft/machnet/actions/workflows/build.yml/badge.svg?event=push)](https://github.com/microsoft/machnet)\n\nMachnet provides an easy way for applications to reduce their datacenter\nnetworking latency via kernel-bypass (DPDK-based) messaging. Distributed\napplications like databases and finance can use Machnet as the networking\nlibrary to get sub-100 microsecond tail latency at high message rates, e.g.,\n**750,000 1KB request-reply messages per second on Azure F8s_v2 VMs with 61\nmicrosecond P99.9 round-trip latency**. We support a variety of cloud (Azure,\nAWS, GCP) and bare-metal platforms, OSs and NICs, evaluated in\n[docs/PERFORMANCE_REPORT.md](docs/PERFORMANCE_REPORT.md).\n\nWhile there are several other DPDK-based network stacks, Machnet provides the\nfollowing unique benefits:\n\n- Specifically designed for and tested on public cloud VM environments\n- Multiple applications on the same machine can use Machnet\n- No need for DPDK expertise, or compiling the application with DPDK\n\n**Architecture**: Machnet runs as a separate process on all machines where the\napplication is deployed and mediates access to the DPDK NIC. Applications\ninteract with Machnet over shared memory with a sockets-like API. Machnet\nprocesses in the cluster communicate with each other using DPDK.\n\n# Steps to use Machnet\n\n## 1. Set up two machines with two NICs each\n\nMachnet requires a dedicated NIC on each machine that it runs on. This NIC may be\nused by multiple applications that use Machnet.\n\nOn Azure, we recommend the following steps:\n\n  1. Create two VMs with accelerated networking enabled. The VMs will start up with one NIC each, named `eth0`. This NIC is *never* used by Machnet.\n  2. Shut-down the VMs.\n  3. Create two new accelerated NICs from the portal, with no public IPs, and add one to each VM.\n  4. After restarting, each VM should have another NIC named `eth1`, which will be used by Machnet.\n\nThe `examples` directory contains detailed scripts/instructions to launch VMs for Machnet.\n\n## 2. Get the Docker image \n\nPulling our prebuilt Machnet docker image from GHCR requires an auth token:\n\n 1. Generate a Github personal access token for yourself (https://github.com/settings/tokens) with the read:packages scope. and store it in the `GITHUB_PAT` environment variable.\n 2. At `https://github.com/settings/tokens`, follow the steps to \"Configure SSO\" for this token.\n\n```bash\n# Install packages required to try out Machnet\nsudo apt-get update\nsudo apt-get install -y docker.io net-tools driverctl uuid-dev\n\n# Reboot like below to allow non-root users to run Docker\nsudo usermod -aG docker $USER \u0026\u0026 sudo reboot\n\n# We assume that the Github token is stored as GITHUB_PAT\necho ${GITHUB_PAT} | docker login ghcr.io -u \u003cgithub_username\u003e --password-stdin\ndocker pull ghcr.io/microsoft/machnet/machnet:latest\n```\n\n## 3. Start the Machnet process on both VMs\n\nUsing DPDK often requires unbinding the dedicated NIC from the OS. This will\ncause the NIC to disappear from tools like `ifconfig`. **Before this step,\nnote down the IP and MAC address of the NIC, since we will need them\nlater.**\n\nBelow, we assume that the dedicated NIC is named `eth1`.  These steps can be\nautomated using a script like\n[azure_start_machnet.sh](examples/azure_start_machnet.sh) that uses the\ncloud's metadata service to get the NIC's IP and MAC address.\n\n```bash\nMACHNET_IP_ADDR=`ifconfig eth1 | grep -w inet | tr -s \" \" | cut -d' ' -f 3`\nMACHNET_MAC_ADDR=`ifconfig eth1 | grep -w ether | tr -s \" \" | cut -d' ' -f 3`\n\n# If on Azure, use driverctl to unbind the NIC instead of dpdk-devbind.py:\nsudo modprobe uio_hv_generic\nDEV_UUID=$(basename $(readlink /sys/class/net/eth1/device))\nsudo driverctl -b vmbus set-override $DEV_UUID uio_hv_generic\n\n# Otherwise, use dpdk-devbind.py like so\n# sudo \u003cdpdk_dir\u003e/usertools/dpdk-devbind.py --bind=vfio-pci \u003cPCIe address of dedicated NIC\u003e\n\n# Start Machnet\necho \"Machnet IP address: $MACHNET_IP_ADDR, MAC address: $MACHNET_MAC_ADDR\"\ngit clone --recursive https://github.com/microsoft/machnet.git\ncd machnet\n./machnet.sh --mac $MACHNET_MAC_ADDR --ip $MACHNET_IP_ADDR\n\n# Note: If you lose the NIC info, the Azure metadata server has it:\ncurl -s -H Metadata:true --noproxy \"*\" \"http://169.254.169.254/metadata/instance?api-version=2021-02-01\" | jq '.network.interface[1]'\n```\n\n## 4. Run the hello world example\n\nAt this point, the Machnet container/process is running on both VMs. We can now\ntest things end-to-end with a client-server application.\n\n```bash\n# Build the Machnet helper library and hello_world example, on both VMs\n./build_shim.sh\ncd examples\n\n# On VM #1, run the hello_world server\n./hello_world --local \u003ceth1 IP address of VM 1\u003e\n\n# On VM #2, run the hello_world client. This should print the reply from the server.\n./hello_world --local \u003ceth1 IP address of VM 2\u003e --remote \u003ceth1 IP address of VM 1\u003e\n```\n\n## 5. Run the end-to-end benchmark\n\nThe Docker image contains a pre-built benchmark called `msg_gen`.\n```bash\nMSG_GEN=\"docker run -v /var/run/machnet:/var/run/machnet ghcr.io/microsoft/machnet/machnet:latest release_build/src/apps/msg_gen/msg_gen\"\n\n# On VM #1, run the msg_gen server\n${MSG_GEN} --local_ip \u003ceth1 IP address of VM 1\u003e\n\n# On VM #2, run the msg_gen client\n${MSG_GEN} --local_ip \u003ceth1 IP address of VM 2\u003e --remote_ip \u003ceth1 IP address of VM 1\u003e\n```\n\nThe client should print message rate and latency percentile statistics.\n`msg_gen --help` lists all the options available.\n\nWe can also build `msg_gen` from source without DPDK or rdma_core:\n```bash\ncd machnet\nrm -rf build; mkdir build; cd build; cmake -DCMAKE_BUILD_TYPE=Release ..; make -j\nMSG_GEN=\"~/machnet/build/src/apps/msg_gen/msg_gen\"\n```\n\n\n## Machnet API\n\nSee [machnet.h](src/ext/machnet.h) for the full API documentation.  Applications use the following steps to interact with the Machnet service:\n\n- Initialize the Machnet library using `machnet_init()`.\n- In every thread, create a new shared-memory channel to Machnet using `machnet_attach()`.\n- Listen on a port using `machnet_listen()`.\n- Connect to remote processes using `machnet_connect()`.\n- Send and receive messages using `machnet_send()` and `machnet_recv()`.\n\n\n## Developing Machnet\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). for instructions on how to build and test Machnet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fmachnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fmachnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fmachnet/lists"}