{"id":13645872,"url":"https://github.com/erikh/ldhcpd","last_synced_at":"2025-04-30T10:32:45.510Z","repository":{"id":145967193,"uuid":"254295078","full_name":"erikh/ldhcpd","owner":"erikh","description":"Light DHCPd -- a DHCP server with a small feature set and a remotely programmable control plane","archived":false,"fork":false,"pushed_at":"2020-05-06T01:39:44.000Z","size":150,"stargazers_count":58,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T15:22:06.148Z","etag":null,"topics":["dhcp","golang","grpc","network"],"latest_commit_sha":null,"homepage":"","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/erikh.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}},"created_at":"2020-04-09T06:56:20.000Z","updated_at":"2025-01-19T18:27:26.000Z","dependencies_parsed_at":"2024-01-14T10:07:55.617Z","dependency_job_id":null,"html_url":"https://github.com/erikh/ldhcpd","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fldhcpd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fldhcpd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fldhcpd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikh%2Fldhcpd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erikh","download_url":"https://codeload.github.com/erikh/ldhcpd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251684510,"owners_count":21627143,"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":["dhcp","golang","grpc","network"],"created_at":"2024-08-02T01:02:43.890Z","updated_at":"2025-04-30T10:32:45.488Z","avatar_url":"https://github.com/erikh.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"## Light DHCPd\n\nThis is a DHCP service/daemon with very few features. It provides basic dynamic\nIPv4 pool allocation as well as persistent, static leases. iPXE support does\nnot exist yet, but is planned.\n\nOne thing Light DHCPd offers that is novel, is a remote control plane powered\nover GRPC, authenticated and encrypted by TLS client certificates. This control\nplane can be embedded into your orchestration code or you can use the provided\ncommand-line tool to manipulate it from your shell. There is a golang client,\nand the protobufs are included in the source tree if you wish to generate\nclients for other languages.\n\nThere is a small configuration file for managing dynamic leases and the overall\nnetwork parameters (resolver, gateway).\n\n## Stability\n\nLight DHCPd has been powering my network for over a week!\n\n**(Seriously, you do not want to use this in production yet.)**\n\n## Development Instructions\n\n- `make shell`: This runs a docker shell. You can do a few things in here:\n  - `make test`: This is context-dependent and will run properly in the container\n    or outside of it, running the unit and functional tests in a container.\n  - `make interfaces`: This sets up some dummy interfaces and plumbs them through\n    a bridge; afterwards `veth1` will be available for running a `ldhcpd` on, and\n    `veth3` will be available for running a `dhclient` on.\n  - `make start`: will start the dhcpd.\n  - `make stop`: stops it.\n  - `make get-ip`: issues a ISC `dhclient` launch against the second veth pair\n    to get an IP, allowing you to test interaction with a real client.\n\n**NOTE**: The following instructions install https://github.com/box-builder/box\non first run to build the images, will require `sudo` for that (but nothing\nelse). If you don't want to run `sudo` to install box, install it in your\n`$PATH` somewhere and try again.\n\nAssuming you're not crazy enough to try this on your own network, try this at\nyour shell instead:\n\n```bash\n$ make shell\n# \u003cinside of container\u003e\n$ make interfaces\n$ make install\n$ sudo ldhcpd veth1 example.conf \u0026\n$ sudo dhclient -1 -v -d veth3\n# ^C it to stop it\n$ ip addr\n# veth3 -\u003e 10.0.20.50\n```\n\nIf you want to boot the control plane only, without serving DHCP, try the `-d`\nflag.\n\n## Config File Rundown\n\n```yaml\n#\n# DNS servers\n#\ndns_servers:\n  - 10.0.0.1\n  - 1.1.1.1\n\n#\n# network gateway\n#\ngateway: 10.0.20.1\n\n#\n# Search domains (if not specified, the client will not get a default)\n#\nsearch_domains:\n  - internal\n\n#\n# Dynamic Range of IPs to use in dynamic lease hand-outs, IP inclusive.\n#\ndynamic_range:\n  from: 10.0.20.50\n  to: 10.0.20.100\n\n#\n# Lease parameters:\n#\n# The duration is the duration of the lease; no other allocation can affect the\n# IP you will get back while this lease is obtained.\n#\n# The grace period is the maximum amount of time the IP is available to the mac\n# address; it is added to the duration. If another mac comes in and there are\n# no available IPs, addresses in the grace period may be reclaimed to make\n# room.\n#\nlease:\n  duration: 24h\n  grace_period: 8h\n```\n\n## Making your certificate authority\n\nWe use [mkcert](https://github.com/FiloSottile/mkcert) to generate our certs.\n\nYou can use this script to generate a very basic CA that operates over\n`localhost`. Depending on your circumstances, you may need to run it as `root`.\n\nThis code also installs it into the paths expected by default in the daemon and\nclient; be mindful of permissions and directory names!\n\n```bash\nCAROOT=/etc/ldhcpd mkcert -install # CA file will be /etc/ldhcpd/rootCA.pem\nCAROOT=/etc/ldhcpd mkcert -cert-file /etc/ldhcpd/server.pem -key-file /etc/ldhcpd/server.key localhost 127.0.0.1\nCAROOT=/etc/ldhcpd mkcert -client -cert-file /etc/ldhcpd/client.pem -key-file /etc/ldhcpd/client.key localhost 127.0.0.1\n```\n\n## Other Notes\n\nldhcpd will suss out your subnet block from the interface you tell it to listen\non. **It is very important your interface is configured correctly**. We make\nsome checks, but no guarantees! Most importantly, ensure the **subnet for ip is\nconfigured properly**. Subnetting is a bit beyond this document's scope, but\nthis is typically done by associating the IP with a CIDR address space that is\n_less_ than `32`.\n\nExample:\n\n```\n2: ens18: \u003cBROADCAST,MULTICAST,UP,LOWER_UP\u003e mtu 1500 qdisc fq_codel state UP group default qlen 1000\n    link/ether a6:80:e0:5e:c5:46 brd ff:ff:ff:ff:ff:ff\n    inet 10.0.0.2/24 brd 10.0.0.255 scope global ens18\n       valid_lft forever preferred_lft forever\n    inet6 2001:1::1/64 scope global\n       valid_lft forever preferred_lft forever\n    inet6 fe80::a480:e0ff:fe5e:c546/64 scope link\n       valid_lft forever preferred_lft forever\n```\n\n`10.0.0.2/24` will get selected here to serve. Only **one** address like this\nmay be configured for now. We may eventually address this, but for now if you\nneed to serve two subnets, start two of `ldhcpd` on different interfaces.\n\n## Roadmap\n\nThese are the items planned for the near future of this project:\n\n- [ ] Per-Lease DNS and Gateway parameters\n- [ ] Hostname support:\n  - [ ] Pushing hostnames\n  - [ ] Recording hostnames from clients\n- [ ] Better, easier to use bridge for the GRPC client\n- [ ] PXE booting support\n  - [ ] maybe with TFTP baked-in?\n\n## Dependencies\n\n- github.com/insomniacslk/dhcp and https://github.com/krolaw/dhcp4 for the\n  dhcp4 protocol work, thanks to the authors, This tool would be much less\n  useful without it.\n- https://github.com/jinzhu/gorm and https://github.com/mattn/go-sqlite3 for the database work.\n- https://google.golang.org/grpc for the control plane protocol.\n- https://github.com/box-builder/box which is a mruby-based docker image builder.\n\n## License\n\nMIT License\n\n## Author\n\nErik Hollensbe \u003cerik+git@hollensbe.org\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikh%2Fldhcpd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferikh%2Fldhcpd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikh%2Fldhcpd/lists"}