{"id":13430297,"url":"https://github.com/facebookincubator/dhcplb","last_synced_at":"2025-05-14T19:04:45.217Z","repository":{"id":45551309,"uuid":"63437106","full_name":"facebookincubator/dhcplb","owner":"facebookincubator","description":"dhcplb is Facebook's implementation of a load balancer for DHCP.","archived":false,"fork":false,"pushed_at":"2025-01-30T13:12:55.000Z","size":247,"stargazers_count":1054,"open_issues_count":4,"forks_count":88,"subscribers_count":54,"default_branch":"main","last_synced_at":"2025-04-06T14:02:13.068Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/facebookincubator.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":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-15T16:48:22.000Z","updated_at":"2025-04-04T02:15:09.000Z","dependencies_parsed_at":"2023-11-17T19:39:04.670Z","dependency_job_id":"fb772bc9-41be-4b0f-b046-a405f30a3f82","html_url":"https://github.com/facebookincubator/dhcplb","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/facebookincubator%2Fdhcplb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2Fdhcplb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2Fdhcplb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2Fdhcplb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebookincubator","download_url":"https://codeload.github.com/facebookincubator/dhcplb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248748647,"owners_count":21155673,"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-07-31T02:00:51.947Z","updated_at":"2025-04-13T16:45:32.385Z","avatar_url":"https://github.com/facebookincubator.png","language":"Go","funding_links":[],"categories":["Go","Misc"],"sub_categories":[],"readme":"# What is dhcplb?\n\n`dhcplb` is Facebook's implementation of:\n  * a DHCP v4/v6 relayer with load balancing capabilities\n  * a DHCP v4/v6 server framework\n\nBoth modes currently only support handling messages sent by a relayer which is\nunicast traffic. It doesn't support broadcast (v4) and multicast (v6) requests.\nFacebook currently uses it in production, and it's deployed at global scale\nacross all of our data centers.\nIt is based on [@insomniacslk](https://github.com/insomniacslk) [dhcp library](https://github.com/insomniacslk/dhcp).\n\n# Why did you do that?\n\nFacebook uses DHCP to provide network configuration to bare-metal machines at\nprovisioning phase and to assign IPs to out-of-band interfaces.\n\n`dhcplb` was created because the previous infrastructure surrounding DHCP led\nto very unbalanced load across the DHCP servers in a region when simply using\nAnycast+ECMP alone (for example 1 server out of 10 would receive \u003e65% of\nrequests).\n\nFacebook's DHCP infrastructure was [presented at SRECon15 Ireland](https://www.usenix.org/conference/srecon15europe/program/presentation/failla).\n\nLater, support for making it responsible for serving dhcp requests (server mode)\nwas added. This was done because having a single threaded application (ISC KEA)\nqueuing up packets while doing backend calls to another services wasn't scaling\nwell for us.\n\n# Why not use an existing load balancer?\n\n* All the relayer implementations available on the internet lack the load\nbalancing functionality.\n* Having control of the code gives you the ability to:\n  * perform A/B testing on new builds of our DHCP server\n  * implement override mechanism\n  * implement anything additional you need\n\n# Why not use an existing server?\n\nWe needed a server implementation which allow us to have both:\n* Multithreaded design, to avoid blocking requests when doing backend calls\n* An interface to be able to call other services for getting the IP assignment,\nboot file url, etc.\n\n# How do you use `dhcplb` at Facebook?\n\nThis picture shows how we have deployed `dhcplb` in our production\ninfrastructure:\n\n![DHCPLB deployed at Facebook](/docs/dhcplb-fb-deployment.jpg)\n\nTORs (Top of Rack switch) at Facebook run DHCP relayers, these relayers are\nresponsible for relaying broadcast DHCP traffic (DISCOVERY and SOLICIT\nmessages) originating within their racks to anycast VIPs, one DHCPv4 and one\nfor DHCPv6.\n\nIn a Cisco switch the configuration would look like this:\n\n```\nip helper-address 10.127.255.67\nipv6 dhcp relay destination 2401:db00:eef0:a67::\n```\n\nWe have a bunch of `dhcplb` [Tupperware](https://blog.docker.com/2014/07/dockercon-video-containerized-deployment-at-facebook/) instances in every region listening on\nthose VIPs.\nThey are responsible for received traffic relayed by TORs agents and load\nbalancing them amongst the actual `dhcplb` servers distributed across clusters\nin that same region.\n\nHaving 2 layers allows us to A/B test changes of the server implementation.\n\nThe configuration for `dhcplb` consists of 3 files:\n\n* json config file: contains the main configuration for the server as explained in the [Getting Started](docs/getting-started.md) section\n* host lists file: contains a list of dhcp servers, one per line, those are the servers `dhcplb` will try to balance on\n* overrides file: a file containing per mac overrides. See the [Getting Started](docs/getting-started.md) section.\n\n# TODOs / future improvements\n\n`dhcplb` does not support relaying/responding broadcasted DHCPv4 DISCOVERY\npackets or DHCPv6 SOLICIT packets sent to `ff02::1:2` multicast address. We\ndon't need this in our production environment but adding that support should be\ntrivial though.\n\nTODOs and improvements are tracked [here](https://github.com/facebookincubator/dhcplb/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)\n\nPRs are welcome!\n\n# How does the packet path looks like?\n\nWhen operating in v4 `dhcplb` will relay relayed messages coming from other\nrelayers (in our production network those are rack switches), the response from\nthe server will be relayed back to the rack switches:\n\n```\ndhcp client \u003c---\u003e rsw relayer ---\u003e dhcplb (relay) ---\u003e dhcplb (server)\n                      ^                                      |\n                      |                                      |\n                      +--------------------------------------+\n```\n\nIn DHCPv6 responses by the dhcp server will traverse the load balancer.\n\n# Installation\n\nTo install `dhcplb` into `$GOPATH/bin/dhcplb`, simply run:\n\n```\n$ go install github.com/facebookincubator/dhcplb@latest\n```\n\n# Cloning\n\nIf you wish to clone the repo you can do the following:\n\n```\n$ mkdir -p $GOPATH/src/github.com/facebookincubator\n$ cd $_\n$ git clone https://github.com/facebookincubator/dhcplb\n$ go install github.com/facebookincubator/dhcplb\n```\n\n# Run unit tests\n\nYou can run tests with:\n\n```\n$ cd $GOPATH/src/github.com/facebookincubator/dhcplb/lib\n$ go test\n```\n\n# Getting Started and extending `dhcplb`\n\n`dhcplb` can be run out of the box after compilation.\n\nTo start immediately, you can run\n`sudo dhcplb -config config.json -version 6`.\nThat will start the relay in v6 mode using the default configuration.\n\nShould you need to integrate `dhcplb` with your infrastructure please\nsee [Extending DHCPLB](docs/extending-dhcplb.md).\n\n# Virtual lab for development and testing\n\nYou can bring up a virtual lab using vagrant. This will replicate our production\nenvironment, you can spawn VMs containing various components like:\n\n* N instances of `ISC dhcpd`\n* An instance of `dhcplb`\n* An instance of `dhcrelay`, simulating a top of rack switch.\n* a VM where you can run `dhclient` or `ISC perfdhcp`\n\nAll of that is managed by `vagrant` and `chef-solo` cookbooks.\nYou can use this lab to test your `dhcplb` changes.\nFor more information have a look at the [vagrant directory](vagrant/README.md).\n\n# Who wrote it?\n\n`dhcplb` started in April 2016 during a 3 days hackathon in the Facebook\nDublin office, the hackathon project proved the feasibility of the tool.\nIn June we were joined by Vinnie Magro (@vmagro) for a 3 months internship in\nwhich he worked with two production engineers on turning the hack into a\nproduction ready system.\n\nOriginal Hackathon project members:\n\n* Angelo Failla ([@pallotron](https://github.com/pallotron)), Production Engineer\n* Roman Gushchin ([@rgushchin](https://github.com/rgushchin)), Production Engineer\n* Mateusz Kaczanowski ([@mkaczanowski](https://github.com/mkaczanowski)), Production Engineer\n* Jake Bunce, Network Engineer\n\nInternship project members:\n\n* Vinnie Magro ([@vmagro](https://github.com/vmagro)), Production Engineer intern\n* Angelo Failla (@pallotron), Intern mentor, Production Engineer\n* Mateusz Kaczanowski (@mkaczanowski), Production Engineer\n\nOther contributors:\n\n* Emre Cantimur, Production Engineer, Facebook, Throttling support\n* Andrea Barberio, Production Engineer, Facebook\n* Pablo Mazzini, Production Engineer, Facebook\n\n# License\n\nBSD License. See the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookincubator%2Fdhcplb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebookincubator%2Fdhcplb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookincubator%2Fdhcplb/lists"}