{"id":27442388,"url":"https://github.com/drpsychick/docker-dnsmasq","last_synced_at":"2025-04-15T00:27:16.086Z","repository":{"id":43114847,"uuid":"116316285","full_name":"DrPsychick/docker-dnsmasq","owner":"DrPsychick","description":"dnsmasq docker image, fully configurable through ENV","archived":false,"fork":false,"pushed_at":"2025-03-17T22:08:45.000Z","size":80,"stargazers_count":31,"open_issues_count":4,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T23:21:56.448Z","etag":null,"topics":["12-factor","dhcp-server","dns-server","dnsmasq","docker"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DrPsychick.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-04T23:05:57.000Z","updated_at":"2025-03-17T22:08:48.000Z","dependencies_parsed_at":"2024-01-21T21:28:31.340Z","dependency_job_id":"0b6d82e3-b2ab-42b3-b68c-85c960b3f52e","html_url":"https://github.com/DrPsychick/docker-dnsmasq","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrPsychick%2Fdocker-dnsmasq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrPsychick%2Fdocker-dnsmasq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrPsychick%2Fdocker-dnsmasq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrPsychick%2Fdocker-dnsmasq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DrPsychick","download_url":"https://codeload.github.com/DrPsychick/docker-dnsmasq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248982949,"owners_count":21193489,"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":["12-factor","dhcp-server","dns-server","dnsmasq","docker"],"created_at":"2025-04-15T00:27:15.389Z","updated_at":"2025-04-15T00:27:16.048Z","avatar_url":"https://github.com/DrPsychick.png","language":"Shell","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=FTXDN7LCDWUEA\u0026source=url","https://github.com/sponsors/DrPsychick"],"categories":[],"sub_categories":[],"readme":"# [Docker image: dnsmasq](https://hub.docker.com/r/drpsychick/dnsmasq/)\nMulti arch docker image, configurable through ENV, based on alpine - serving as local DHCP and/or DNS server\n\n[![Docker image](https://img.shields.io/docker/image-size/drpsychick/dnsmasq?sort=date)](https://hub.docker.com/r/drpsychick/dnsmasq/tags)\n[![CircleCI](https://img.shields.io/circleci/build/github/DrPsychick/docker-dnsmasq)](https://app.circleci.com/pipelines/github/DrPsychick/docker-dnsmasq)\n[![license](https://img.shields.io/github/license/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq/blob/master/LICENSE) [![DockerHub pulls](https://img.shields.io/docker/pulls/drpsychick/dnsmasq.svg)](https://hub.docker.com/r/drpsychick/dnsmasq/) [![DockerHub stars](https://img.shields.io/docker/stars/drpsychick/dnsmasq.svg)](https://hub.docker.com/r/drpsychick/dnsmasq/) [![GitHub stars](https://img.shields.io/github/stars/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq) [![Contributors](https://img.shields.io/github/contributors/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq/graphs/contributors)\n\n[![GitHub issues](https://img.shields.io/github/issues/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq/issues) [![GitHub closed issues](https://img.shields.io/github/issues-closed/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq/issues?q=is%3Aissue+is%3Aclosed) [![GitHub pull requests](https://img.shields.io/github/issues-pr/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq/pulls) [![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/drpsychick/docker-dnsmasq.svg)](https://github.com/drpsychick/docker-dnsmasq/pulls?q=is%3Apr+is%3Aclosed)\n[![Paypal](https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=FTXDN7LCDWUEA\u0026source=url)\n[![GitHub Sponsor](https://img.shields.io/badge/github-sponsor-blue?logo=github)](https://github.com/sponsors/DrPsychick)\n\nNO LONGER based on andyshinn/dnsmasq docker image, as his images are outdated :(\n\nPurpose:\n* make it fully configurable through environment variables\n* use one image to run them all\n* run stateless, environment configured containers (see https://12factor.net/)\n* use primarily to setup DNS/DHCP for simple/home environments\n* **new**: support for VIP with `keepalived` (see below)\n\n## Usage\n\nTry it in 3 steps\n\n### 1 create your own dnsmasq.env\n```\ndocker run --rm -it drpsychick/dnsmasq:latest --test\ndocker run --rm -it drpsychick/dnsmasq:latest --export \u003e dnsmasq.env\n```\n\n### 2 run it\nRun in a separate teminal\n```\ndocker run --rm -it --cap-add NET_ADMIN --env-file dnsmasq.env --name dnsmasq-1 drpsychick/dnsmasq:latest -k -q --log-facility=-\n```\n\n### 3 test it\n```\n# test DNS and DHCP\ncontainer_ip=$(docker inspect dnsmasq-1 -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')\ndocker_interface=$(docker network inspect bridge -f '{{index .Options \"com.docker.network.bridge.name\"}}')\nnslookup google.com $container_ip\n\nsudo ip link add test0 link docker0 type macvlan mode bridge\nsudo dhclient -1 -d -s $container_ip test0\nsudo ip link del test0 link docker0 type macvlan mode bridge\n```\n\n\nIf that ruins your routing because of a new default gateway (check `route -n`):\n```\nsudo route del -net 172.17.10.0/24 gw 172.10.10.1 dev $docker_interface\n```\n\n## Use case: run in local network\nSome additional work is needed in order to run the docker container with an IP from your local subnet and to serve requests for your subnet.\nIf you don't need DHCP, you can skip most part of it. \n\nFurther reading:\n\nhttp://blog.oddbit.com/2014/08/11/four-ways-to-connect-a-docker/\nhttps://docs.docker.com/engine/userguide/networking/get-started-macvlan/#macvlan-bridge-mode-example-usage\nhttps://blog.docker.com/2016/12/understanding-docker-networking-drivers-use-cases/\n\n**Important**:\n\nDHCP will only work if the DHCP range is on the interface it runs on\nIn other words: running DHCP on the ip of the docker container will not work, it needs to have an IP on the subnet it will serve DHCP requests on\n\n### Example: \n* 192.168.1.253 IP of the DNS/DHCP server\n* 192.168.1.1   IP of the gateway\n* 192.168.1.110-120 is an unused range of IPs\n* eth1 is the network device on the local subnet\n\n#### dnsmasq.env:\n\n```\nDMQ_DNS_HOST1=gateway,gateway.local,192.168.1.1\nDMQ_DHCP_GATEWAY=dhcp-option=3,192.168.1.1\nDMQ_DHCP_RANGES=dhcp-range=192.168.1.110,192.168.1.120,24h\nDMQ_DHCP_DNS=dhcp-option=6,192.168.1.253,8.8.8.8,8.8.4.4\n```\n\ntest configuration:\n`docker run --rm -it --env-file dnsmasq.env drpsychick/dnsmasq:latest --test`\n\n#### Network\nTo run the container with an IP from the local subnet, we need the \"macvlan\" driver. \nAnd in order to be able to interact with the container even from the host, we need to create a virtual interface.\n\n```\n# create linked interface mac0 and use this instead of the parent eth1\nsudo ip link add mac0 link eth1 type macvlan mode bridge\nsudo ip addr flush dev eth1\nsudo dhclient mac0\n\n# create macvlan network with our subnet\ndocker network create --driver macvlan --subnet 192.168.1.0/24 --gateway 192.168.1.1 -o parent=mac0 local-net\n```\n\n#### Run in a separate shell:\n```\ndocker run --rm -it --net local-net --ip 192.168.1.253 --cap-add NET_ADMIN --env-file dnsmasq.env --publish 53:53 --publish 53:53/udp --publish 67:67/udp --name dnsmasq-1 drpsychick/dnsmasq:latest -k -q --log-facility=-\n```\n\n#### Test it\n```\nnslookup google.de 192.168.1.253\n\nsudo ip link add mac1 link eth1 type macvlan mode bridge\nsudo dhclient -1 -d -s 192.168.1.253 mac1\nsudo ip link del mac1\n```\n\n#### All good, now lets see it in production:\n```\n# run it\n# Same \"run\" command as above, but with \"-d\" and \"--restart always\" instead of \"--rm -it\" (run as daemon)\ndocker run -d --net local-net --ip 192.168.1.253 --cap-add NET_ADMIN --env-file dnsmasq.env --restart always --publish 53:53 --publish 53:53/udp --publish 67:67/udp --name dnsmasq-1 drpsychick/dnsmasq:latest -k -q --log-facility=-\n\n# watch it\ndocker attach --sig-proxy=false dnsmasq-1\n```\n\n## The simple way\nFor services other than DHCP you still have to some manual tweaking, but its much easier to do\n\nTry this:\n```\nsudo ip addr add 192.168.1.253/32 dev eth1\ndocker run ... --publish 192.168.1.253:53:53 ... (for every port)\n```\n\n## Failover with `keepalived`\n\nSetup two containers (on different hosts), each with an individual IP. Configure an additional VIP for `keepalived` and define which container\nis the master and which one is the backup. When the master fails, or you run docker updates etc, the backup will kick in\nand bring up the VIP and announce it in the network. Once the master is back up, it will take over again as it has a higher\npriority.\n\nMake sure to use the VIP (`192.168.1.250` in this example) as DNS and DHCP listen address for `dnsmasq`.\n\n```shell\n# make sure to set the DNS and DHCP listen address to the VIP (DMQ_DHCP_DNS, DMQ_GLOBAL_LISTEN)\necho \"DMQ_GLOBAL_BIND=bind-dynamic\" \u003e\u003e dnsmasq.env\necho \"DMQ_GLOBAL_LISTEN=listen-address=127.0.0.1,192.168.1.250\" \u003e\u003e dnsmasq.env\necho \"DMQ_DHCP_DNS=dhcp-option=6,192.168.1.250,8.8.8.8,8.8.4.4\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_STATE=MASTER\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_PRIO=100\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_ID=21\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_PASS=S3cr3t99\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_VIP=192.168.1.250\" \u003e\u003e dnsmasq.env \n\ndocker run ... # see above\n\n# for the backup, similarly with lower priority:\necho \"DMQ_GLOBAL_BIND=bind-dynamic\" \u003e\u003e dnsmasq.env\necho \"DMQ_GLOBAL_LISTEN=listen-address=127.0.0.1,192.168.1.250\" \u003e\u003e dnsmasq.env\necho \"DMQ_DHCP_DNS=dhcp-option=6,192.168.1.250,8.8.8.8,8.8.4.4\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_STATE=BACKUP\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_PRIO=99\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_ID=21\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_PASS=S3cr3t99\" \u003e\u003e dnsmasq.env\necho \"KEEPALIVE_VIP=192.168.1.250\" \u003e\u003e dnsmasq.env\n\ndocker run ... # see above\n```\n\nKeepalived User Guide: https://readthedocs.org/projects/keepalived-pqa/downloads/pdf/latest/\n\n### supported `keepalived` environment variables\n|name|description|comment|required/optional|potential values|default|\n|---|---|---|---|---|---|\n|`KEEPALIVE_ID`|virtual router id|keep the same for all members of the keepalived group|optional|numeric|`21`|\n|`KEEPALIVE_INTERFACE`|network interface|the name of the nic keepalived should listen on|optional|string|`eth0`|\n|`KEEPALIVE_PASS`|password|keep the same for all the members of the keepalived group|optional|string|`S3cr3t99`|\n|`KEEPALIVE_PRIO`|priority|this characterises which member of the group should be active, if the `MASTER` member is unavailable|optional|numeric|`100`|\n|`KEEPALIVE_STATE`|state|this characterises the member as either `MASTER` or `BACKUP`.|**required**|`MASTER`\\|`BACKUP`|_none_|\n|`KEEPALIVE_VIP`|virtual ip address|the ip address to be shared for all members of the keepalived group|**required**|ip address|_none_|\n\n\n# Credits\nAutomated build inspired by\n* https://medium.com/vaidikkapoor/managing-open-source-docker-images-on-docker-hub-using-travis-7fd33bc96d65\n* https://medium.com/mobileforgood/coding-tips-patterns-for-continuous-integration-with-docker-on-travis-ci-9cedb8348a62\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrpsychick%2Fdocker-dnsmasq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrpsychick%2Fdocker-dnsmasq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrpsychick%2Fdocker-dnsmasq/lists"}