{"id":28262881,"url":"https://github.com/jonasalfredsson/docker-kea","last_synced_at":"2025-06-16T14:31:23.728Z","repository":{"id":50493530,"uuid":"517441469","full_name":"JonasAlfredsson/docker-kea","owner":"JonasAlfredsson","description":"The ISC Kea DHCP server, Control Agent and DDNS running inside individual Docker containers.","archived":false,"fork":false,"pushed_at":"2025-06-05T06:53:08.000Z","size":112,"stargazers_count":98,"open_issues_count":4,"forks_count":16,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-05T07:57:34.663Z","etag":null,"topics":["alpine","amd64","arm64","armv7","ddns","debian","dhcp","docker","hacktoberfest","ipv4","ipv6","isc-dhcp","isc-kea","kea","kea-ctrl-agent","kea-dhcp","kea-dhcp-ddns","kea-dhcp4","kea-dhcp6","kea-dhcpd"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/search?q=jonasal%2Fkea","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JonasAlfredsson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"JonasAlfredsson","patreon":"jonasal","ko_fi":"jonasal","custom":["buymeacoffee.com/jonasal","paypal.me/JonasAlfredsson"]}},"created_at":"2022-07-24T21:32:33.000Z","updated_at":"2025-06-04T07:39:34.000Z","dependencies_parsed_at":"2023-10-10T22:31:41.347Z","dependency_job_id":"f10bbe39-2117-4c64-9265-7dad504a6bde","html_url":"https://github.com/JonasAlfredsson/docker-kea","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JonasAlfredsson/docker-kea","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-kea","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-kea/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-kea/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-kea/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonasAlfredsson","download_url":"https://codeload.github.com/JonasAlfredsson/docker-kea/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-kea/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260175756,"owners_count":22970043,"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":["alpine","amd64","arm64","armv7","ddns","debian","dhcp","docker","hacktoberfest","ipv4","ipv6","isc-dhcp","isc-kea","kea","kea-ctrl-agent","kea-dhcp","kea-dhcp-ddns","kea-dhcp4","kea-dhcp6","kea-dhcpd"],"created_at":"2025-05-20T07:13:09.614Z","updated_at":"2025-06-16T14:31:23.679Z","avatar_url":"https://github.com/JonasAlfredsson.png","language":"Dockerfile","funding_links":["https://github.com/sponsors/JonasAlfredsson","https://patreon.com/jonasal","https://ko-fi.com/jonasal","buymeacoffee.com/jonasal","paypal.me/JonasAlfredsson"],"categories":[],"sub_categories":[],"readme":"# docker-kea\n\nThe ISC (Internet System Consortium) Kea DHCP server running inside a Docker\ncontainer. Separate images for the IPv4 and IPv6 services, as well as an image\nfor the Control Agent which exposes a RESTful API that can be used for\nquerying/controlling the other services.\n\nAvailable as both Debian and Alpine images and for multiple architectures. In\norder to facilitate the last part this repo needs to build Kea from source,\nso it might not be 100% identical to the official ISC package, which is\nunfortunate but it will probably have to remain like this until official\npackages are built for all architectures.\n\n\u003e There is also an [Ansible role][19] using this image, if that is of interest.\n\n---\n\n[Kea][1] is the successor of the old [ISC DHCP][2] server which reached its end\nof life [late 2022][28], so it is recommended to [migrate][29] to Kea now if you\nare still using the old service. Kea is built with the modern web in mind\n([intro presentation][5]), and is more modular with separate [packages][3] for\nthe different services along with a lot of [documentation][4].\n\nTo keep the same modularity in the Docker case this repo produces four\ndifferent images which are tagged with the same version as the Kea service\nrunning inside:\n\n- [`jonasal/kea-dhcp4:\u003cversion\u003e`][12]\n- [`jonasal/kea-dhcp6:\u003cversion\u003e`][13]\n- [`jonasal/kea-dhcp-ddns:\u003cversion\u003e`][25]\n- [`jonasal/kea-ctrl-agent:\u003cversion\u003e`][14]\n- (+ [`jonasal/kea-hooks:\u003cversion\u003e`][16] - read about this in the [Kea Hooks](#kea-hooks) section)\n\n\u003e Just append `-alpine` to the tags above to get the Alpine image.\n\nIt is possible to define how strict you want to lock down the version so `2`,\n`2.2` or `2.2.0` all work and the less specific tags will move to point to the\nlatest of the more specific ones. One thing to be aware of is that **even**\nminor versions (`2.2`) are stable builds while **odd** (`2.3`) are development\nbuilds, therefore the major tagging of all the images built here will only track\nthe stable releases. What this means is that `2 -\u003e 2.2.0` even though `2.3.1` is\navailable.\n\n\u003e There is no [`:latest`][15] tag since Kea updates may break things.\n\n## Usage\n\n### Environment Variables\nThere are a couple of environment variables present in the container that\nallow for some customization, however, some of them should not be touched.\n\n#### Executable Information\n- `KEA_EXECUTABLE`: Should **not** be modified, is used by [`entrypoint.sh`](./entrypoint.sh).\n- `KEA_USER`: Currently does nothing, might be used in the future.\n\n#### Data Directories\nBecause of strict [path limitations][31] these variables need to be defined in\norder to allow us to use the directory structure mentioned\n[below](#useful-directories). These can be changed if desired.\n\n- `KEA_DHCP_DATA_DIR`: Location of the leases \"memfile\" (Default: `/kea/leases`)\n- `KEA_LOG_FILE_DIR`: Output directory of log files (Default: `/kea/logs`)\n- `KEA_LEGAL_LOG_DIR`: Output directory of forensic log files (Default: `/kea/logs`)\n- `KEA_CONTROL_SOCKET_DIR`: Directory for any sockets created (Default: `/kea/sockets`)\n\n### Useful Directories\nThere are a few directories present inside the images that may be utilized if\nyour usecase calls for it.\n\n\u003e This image creates the user `kea` with uid:gid `101:101`/`100:101`\n\u003e (Debian/Alpine) which may be used for non-root execution in the future,\n\u003e however, Kea runs as root right now since it needs high privilege to open\n\u003e raw sockets.\n\n- `/kea/config`: Mount this to the directory with all your configuration files.\n- `/kea/leases`: Good location for the leases \"memfile\" if used.\n- `/kea/logs`: Good location to output any logs to.\n- `/kea/sockets`: Host mount this in order to share sockets between containers.\n- `/entrypoint.d`: Place any custom scripts you want executed at the start of the container here.\n\nAll the folders under `kea/` may be mounted individually or you can just mount\nthe entire `kea/` folder, however, then you need to manually create the\nsubfolders (with `750` permissions) since Kea is not able to do so itself. See\nthe advanced [docker-compose](./examples/advanced/docker-compose.yaml) example\nfor inspiration.\n\n### The DHCP Server\nEach image/service needs its own specific configuration file, so you will need\nto create one for each service you want to run. There is a very simple config\nfor the `dhcp4` service in the [simple/](./examples/simple/dhcp4.json) folder,\nwith more comprehensive ones for all services in the\n[advanced/](./examples/advanced/) folder. You may also look in the [examples][6]\nfolder on the official repo to find stuff like [all available keys][7] for the\nDHCP4 config, or go to the [documentation][20] for the latest info.\n\n\u003e The syntax used is [extended JSON with another couple of addons][21] which\n\u003e allows comments and file inclusion. This is very handy and makes it much\n\u003e easier to write well structured configuration files.\n\nWhen starting the service you need to make sure that you point it to the correct\nconfiguration file. In the simple example we would provide the following command\nto have it find the correct file:\n\n```bash\ndocker run -it --rm \\\n    -v $(pwd)/examples/simple:/kea/config \\\n    jonasal/kea-dhcp4:2 \\\n    -c /kea/config/dhcp4.json\n```\n\nThis container will run inside a Docker network so it should not interfere with\nanything. You can test to see if it responds correctly by calling upon the\n`test4` target from the [Makefile](./Makefile).\n\n```bash\nmake test4\n```\n\nTo start the IPv6 service you just replace all instances of `dhcp4` with `dhcp6`\nin the command above. However, I would suggest you read the\n[next section](#docker-network-mode) about the Docker network mode and how that\naffects these services before trying anything else.\n\n#### Docker Network Mode\nWhen you want to run your DHCP server for real you will need to make sure that\nthe incoming [DHCP packages][22] can reach your service, and this will not\nhappen in case you put the containers on a normal Docker network.\n\nFor basic home use I would recommend just setting the container to use the\n[`host`][24] network, since this will be the absolute easiest way to get around\nmost issues.  However, you *could* [fiddle][9] with a [macvlan][8] or an\n[ipvlan][23] ([example](./examples/multiple-vlans/docker-compose.yml)) setup in\ncase you have more advanced needs, but unless you know you need this I would not\nbother.\n\nAdditionally, [IPv6 support][10] in Docker is a little bit [messy][11] right\nnow so if you want to deploy that your other choices are a bit limited either\nway.\n\nSetting the `host` network is done by adding\n\n```bash\n--network host\n```\n\nto the command above, or look at the\n[docker-compose](./examples/advanced/docker-compose.yaml)\nfile for how it is done there. Then you should be able to serve leases on the\nnetwork the host machine is connected to.\n\n\n### The Control Agent\nThe DHCP services expose an API that may be used if the `control-socket`\nsetting is defined in their configuration file:\n\n```json\n\"control-socket\": {\n    \"socket-type\": \"unix\",\n    \"socket-name\": \"/kea/sockets/dhcp4.socket\"\n},\n```\n\nA unix socket is the only method available, and while you can push commands\ndirectly through this with the help of [`socat`][30] the `ctrl-agent` service\nprovides a RESTful API that may be interfaced with instead. You just need\nto make sure this service can communicate with the `control-socket` of the DHCP\nservice, and an example of how to do this can be found in the\n[advanced/](./examples/advanced/) folder along with the\n[docker-compose.yaml](./examples/advanced/docker-compose.yaml) file.\n\nWhen that is all up and running you should be able to make queries like this:\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n    -d '{ \"command\": \"config-get\", \"service\": [ \"dhcp4\" ] }' \\\n    http://localhost:8000/\n```\n\nMore information about this may be found in the Management API section of the\n[documentation][4].\n\n\n\n### Kea Hooks\nKea has some extended features that are available as \"[hooks][17]\" which may be\nimported in those cases when they are specifically needed. Some are available\nas free open source while others require a premium subscription in order to get\nthem, a table exists [here][18] with more info.\n\nThese hooks enable advanced functionality, like High Availability and BOOTP,\nwhich means most people will probably never use these, and which is why we\nprovide `dhcp4-slim` and `dhcp6-slim` images which don't have any hook libraries\nincluded at all.\n\nHowever, if you want to make your own specialized image we do provide an\nadditional image from where individual hooks may be imported. In the example\nbelow we just import the HA hooks into the `dhcp4-slim` service image.\n\n```Dockerfile\nFROM jonasal/kea-dhcp4-slim:2.2.0\nCOPY --from=jonasal/kea-hooks:2.2.0 /hooks/libdhcp_ha.so /hooks/libdhcp_lease_cmds.so /usr/local/lib/kea/hooks\n```\n\nIt could also be necessary to run the linker after this, so just to be safe I\nwould add one of the following lines afterwards.\n\n```Dockerfile\nRUN ldconfig  # \u003c--- Debian\nor\nRUN ldconfig /usr/local/lib/kea/hooks  # \u003c--- Alpine\n```\n\n\n\n\n\n\n[1]: https://www.isc.org/kea/\n[2]: https://www.isc.org/dhcp/\n[3]: https://kb.isc.org/docs/isc-kea-packages\n[4]: https://kea.readthedocs.io\n[5]: https://academy.apnic.net/wp-content/uploads/2020/03/kea-apnic-webinar.pdf\n[6]: https://github.com/isc-projects/kea/tree/master/doc/examples\n[7]: https://github.com/isc-projects/kea/blob/master/doc/examples/kea4/all-keys.json\n[8]: https://docs.docker.com/network/macvlan/\n[9]: https://gist.github.com/mikejoh/04978da4d52447ead7bdd045e878587d\n[10]: https://docs.docker.com/config/daemon/ipv6/\n[11]: https://github.com/robbertkl/docker-ipv6nat\n[12]: https://hub.docker.com/r/jonasal/kea-dhcp4/tags\n[13]: https://hub.docker.com/r/jonasal/kea-dhcp6/tags\n[14]: https://hub.docker.com/r/jonasal/kea-ctrl-agent/tags\n[15]: https://vsupalov.com/docker-latest-tag/\n[16]: https://hub.docker.com/r/jonasal/kea-hooks/tags\n[17]: https://kea.readthedocs.io/en/latest/arm/hooks.html\n[18]: https://kea.readthedocs.io/en/latest/arm/hooks.html#id1\n[19]: https://github.com/JonasAlfredsson/ansible-role-kea_dhcp\n[20]: https://kea.readthedocs.io/en/latest/arm/config.html\n[21]: https://kea.readthedocs.io/en/latest/arm/config.html#json-syntax\n[22]: https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol#DHCP_message_types\n[23]: https://docs.docker.com/network/ipvlan/\n[24]: https://docs.docker.com/network/host/\n[25]: https://hub.docker.com/r/jonasal/kea-dhcp-ddns/tags\n[28]: https://www.isc.org/blogs/isc-dhcp-eol/\n[29]: https://www.isc.org/dhcp_migration/\n[30]: https://reports.kea.isc.org/dev_guide/d2/d96/ctrlSocket.html#ctrlSocketClient\n[31]: https://github.com/JonasAlfredsson/docker-kea/issues/82\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasalfredsson%2Fdocker-kea","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonasalfredsson%2Fdocker-kea","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasalfredsson%2Fdocker-kea/lists"}