This folder contains a script for installing Dnsmasq and configuring
it to forward requests for a specific domain to Consul. This way, you can easily use Consul as your DNS server for
domain names such as foo.service.consul, where foo is a service registered with Consul (see the Registering
Services docs for instructions on registering your services
with Consul). All other domain names will continue to be resolved via the default resolver on your OS. See the Consul
DNS Forwarding Guide for more info, including trade-offs between using this module and systemd-resolved for DNS forwarding.
This script has been tested on the following operating systems:
Ubuntu 16.04
Amazon Linux 2
There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.
Quick start
To install Dnsmasq, use git to clone this repository at a specific tag (see the releases page
for all available tags) and run the install-dnsmasq script:
Note: by default, the install-dnsmasq script assumes that a Consul agent is already running locally and connected to
a Consul cluster. After the install completes, restart dnsmasq (e.g. sudo /etc/init.d/dnsmasq restart) and queries
to the .consul domain will be resolved via Consul:
The install-dnsmasq script accepts the following arguments:
consul-domain DOMAIN: The domain name to point to Consul. Optional. Default: consul.
consul-ip IP: The IP address to use for Consul. Optional. Default: 127.0.0.1. This assumes a Consul agent is
running locally and connected to a Consul cluster.
consul-dns-port PORT: The port Consul uses for DNS requests. Optional. Default: 8600.
dnsmasq-listen-address IP: The IP address for dnsmasq to listen on. Optional. Defaults to the value of consul-ip.
Make sure that the network interface you provide for the IP has already been configured before you pass it to dnsmasq.
Example:
install-dnsmasq
Troubleshooting
Add the +trace argument to dig commands to more clearly see what's going on:
digvault.service.consul +trace
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"06f140f324996ecec28b18d6e52142789006ab89"}]},{"name":".gitignore","path":".gitignore","sha":"c749affedc4dee4e84093bef93f6ba0ebdaaf306"},{"name":".pre-commit-config.yaml","path":".pre-commit-config.yaml","sha":"81355c81b991ffeeb1224a07bfb86f0fa592b6cd"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"4be01a6334d39aa5bf6abe6baae701f5e2a8c5ac"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","sha":"bdfb309d7ff6bb05ffc1ea9453604805c022d13b"},{"name":"LICENSE","path":"LICENSE","sha":"7a4a3ea2424c09fbe48d455aed1eaa94d9124835"},{"name":"NOTICE","path":"NOTICE","sha":"2655cb5943994ab8de6faec5e5afc28ce4ec10c7"},{"name":"README.md","path":"README.md","sha":"d2cbf5451f176c46b432261675b3afc5b03ee8a7"},{"name":"_ci","children":[{"name":"publish-amis-in-new-account.md","path":"_ci/publish-amis-in-new-account.md","sha":"5b5daa55c3e36c1c4739471be92ccb53995f9783"},{"name":"publish-amis.sh","path":"_ci/publish-amis.sh","sha":"a2554844ab0693d24edd3f0439073458070350fc"}]},{"name":"_docs","children":[{"name":"architecture.png","path":"_docs/architecture.png","sha":"539fece6e8a9fd7a56245e2b63e6640a1e0591ef"},{"name":"consul-ui-screenshot.png","path":"_docs/consul-ui-screenshot.png","sha":"622c7e70d3ab805b1bb8e27e474ff8243d4bc994"},{"name":"package-managers.md","path":"_docs/package-managers.md","sha":"f382b6997245e03adba61c02346519a70ee016d4"}]},{"name":"examples","children":[{"name":"README.md","path":"examples/README.md","sha":"8eca7399ca356c90a307206147362bc35588179c"},{"name":"consul-ami","children":[{"name":"README.md","path":"examples/consul-ami/README.md","sha":"da69b57110946044c33581e84436940e31e5d159"},{"name":"consul.json","path":"examples/consul-ami/consul.json","sha":"88c2af9e8e4c313f512af2f72a184871250021d0"}]},{"name":"consul-examples-helper","children":[{"name":"README.md","path":"examples/consul-examples-helper/README.md","sha":"296f6878fd49edb27d6a6b62fa4119b6a407ba26"},{"name":"consul-examples-helper.sh","path":"examples/consul-examples-helper/consul-examples-helper.sh","sha":"cb356cf348574378bbecbf49b3d6bf0339606cbe"}]},{"name":"example-with-custom-asg-role","children":[{"name":"README.md","path":"examples/example-with-custom-asg-role/README.md","sha":"fa1fbb9d7416fa96f13afb6b82664bbe1638ea3f"},{"name":"main.tf","path":"examples/example-with-custom-asg-role/main.tf","sha":"c0fcf7631ff6b439363f80c3709691bf9c9d4383"},{"name":"outputs.tf","path":"examples/example-with-custom-asg-role/outputs.tf","sha":"493b36c2b62ad81a4d1d4eb62e268442206eeded"},{"name":"user-data-client.sh","path":"examples/example-with-custom-asg-role/user-data-client.sh","sha":"fd0158b0287de6bf2a6956718c7aa802076fe489"},{"name":"user-data-server.sh","path":"examples/example-with-custom-asg-role/user-data-server.sh","sha":"c78ebc05584513fa04f44d44ef2b9d17c98e2ea6"},{"name":"variables.tf","path":"examples/example-with-custom-asg-role/variables.tf","sha":"387fac5d0223a2466e0f671d055f8255058b3050"}]},{"name":"example-with-encryption","children":[{"name":"README.md","path":"examples/example-with-encryption/README.md","sha":"0f2de7374cf63ee0b18cae4b960b85ec88403866"},{"name":"main.tf","path":"examples/example-with-encryption/main.tf","sha":"bfc7f675ab5ba84c20001d715dec5ab224826e9f"},{"name":"outputs.tf","path":"examples/example-with-encryption/outputs.tf","sha":"493b36c2b62ad81a4d1d4eb62e268442206eeded"},{"name":"packer","children":[{"name":"README.md","path":"examples/example-with-encryption/packer/README.md","sha":"b7b8ca11120c5f69565dab81eeeed659223538e9"},{"name":"ca.crt.pem","path":"examples/example-with-encryption/packer/ca.crt.pem","sha":"c41779f19be6d742d10be51d80c29aa5d41a660c"},{"name":"consul-with-certs.json","path":"examples/example-with-encryption/packer/consul-with-certs.json","sha":"9942398f7b76dc1589394efb1348d9a727389a7a"},{"name":"consul.crt.pem","path":"examples/example-with-encryption/packer/consul.crt.pem","sha":"4a4ea11b89006f41fe2cb8b707d62463bb739184"},{"name":"consul.key.pem","path":"examples/example-with-encryption/packer/consul.key.pem","sha":"b7de428c63382b087007a236602797cc0a0a45f5"}]},{"name":"user-data-client.sh","path":"examples/example-with-encryption/user-data-client.sh","sha":"2ab3735d96777ce9324bc55f7be29c338ef0c1bb"},{"name":"user-data-server.sh","path":"examples/example-with-encryption/user-data-server.sh","sha":"5e97fc02da696b348ee26a2c1803bf7e3e018c79"},{"name":"variables.tf","path":"examples/example-with-encryption/variables.tf","sha":"9187e8892ddb952fd8adf217071d310d1c644967"}]},{"name":"root-example","children":[{"name":"README.md","path":"examples/root-example/README.md","sha":"6c562cb22c28cc5e35b5a21a94b66d6af9101081"},{"name":"user-data-client.sh","path":"examples/root-example/user-data-client.sh","sha":"fd0158b0287de6bf2a6956718c7aa802076fe489"},{"name":"user-data-server.sh","path":"examples/root-example/user-data-server.sh","sha":"c78ebc05584513fa04f44d44ef2b9d17c98e2ea6"}]}]},{"name":"main.tf","path":"main.tf","sha":"19daa7655b66775c23378dcb4382e92f05f86a34"},{"name":"modules","children":[{"name":"README.md","path":"modules/README.md","sha":"8eca7399ca356c90a307206147362bc35588179c"},{"name":"consul-client-security-group-rules","children":[{"name":"README.md","path":"modules/consul-client-security-group-rules/README.md","sha":"777b679a73df3d5c96fb584176e91449c3a72615"},{"name":"main.tf","path":"modules/consul-client-security-group-rules/main.tf","sha":"6ae3118188ae5c7806cc2ac88cc5a1ac3e50edd1"},{"name":"variables.tf","path":"modules/consul-client-security-group-rules/variables.tf","sha":"c9c25d00fdc683748570ba5e2ee718c9af8e6697"}]},{"name":"consul-cluster","children":[{"name":"README.md","path":"modules/consul-cluster/README.md","sha":"b9a3c55973ef27b0022f5eda05840f7cc65cea03"},{"name":"main.tf","path":"modules/consul-cluster/main.tf","sha":"721f6fc0c5bf9efed37d582c767b772893424a7f"},{"name":"outputs.tf","path":"modules/consul-cluster/outputs.tf","sha":"a980d658e1be410a013a7e7febcc38a49899ffdc"},{"name":"variables.tf","path":"modules/consul-cluster/variables.tf","sha":"6830617eb65853e5c8e9a6ce27f6bb49a546aa34"}]},{"name":"consul-iam-policies","children":[{"name":"README.md","path":"modules/consul-iam-policies/README.md","sha":"7725295fbdbf3d2fe881796e63074e3215854f5f"},{"name":"main.tf","path":"modules/consul-iam-policies/main.tf","sha":"803883bcb9ce412710c9e7d59873bf734c2067c2"},{"name":"variables.tf","path":"modules/consul-iam-policies/variables.tf","sha":"1bda7959f19ea4ab20108ec9fb8802036bfd22fd"}]},{"name":"consul-security-group-rules","children":[{"name":"README.md","path":"modules/consul-security-group-rules/README.md","sha":"315155181f5b42ff0fc6f16b86eaa930811366fe"},{"name":"main.tf","path":"modules/consul-security-group-rules/main.tf","sha":"c9081bfa75ebc080a68346fd104dcea22f0a89be"},{"name":"variables.tf","path":"modules/consul-security-group-rules/variables.tf","sha":"90e1bec3a64824c9416088e46cae9d7ffcc45638"}]},{"name":"install-consul","children":[{"name":"README.md","path":"modules/install-consul/README.md","sha":"26c636fc061fc894c41c792d28428f0266056e86"},{"name":"install-consul","path":"modules/install-consul/install-consul","sha":"f33c659cbb0dc5ab7d5846e7ece811481d42792e"}]},{"name":"install-dnsmasq","children":[{"name":"README.md","path":"modules/install-dnsmasq/README.md","sha":"dbfcd308061679992e9afc3c11264b8140cfe04c","toggled":true},{"name":"install-dnsmasq","path":"modules/install-dnsmasq/install-dnsmasq","sha":"6ff5256cf38477fe3693c93056a37b96fcb37b16"}],"toggled":true},{"name":"run-consul","children":[{"name":"README.md","path":"modules/run-consul/README.md","sha":"b5e8ec01a3de18d23095cfdf943e4243a74a32d3"},{"name":"run-consul","path":"modules/run-consul/run-consul","sha":"ffb5dece503f333949b73553e27039cc7caa1f99"}]},{"name":"setup-systemd-resolved","children":[{"name":"README.md","path":"modules/setup-systemd-resolved/README.md","sha":"c71225757127230251fa0774fe608eac9102ea09"},{"name":"setup-systemd-resolved","path":"modules/setup-systemd-resolved/setup-systemd-resolved","sha":"28670839d4c362281407b394303b6ab6162d7ebf"}]}],"toggled":true},{"name":"outputs.tf","path":"outputs.tf","sha":"493b36c2b62ad81a4d1d4eb62e268442206eeded"},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"874818e6da7a9c0c9338edde0c27fa3f8a3b3d05"},{"name":"aws_helpers.go","path":"test/aws_helpers.go","sha":"a340f3a3779fb5efd7c9410f3e72734f9ad4a324"},{"name":"consul_cluster_test.go","path":"test/consul_cluster_test.go","sha":"b44bd7d665b26d7d672f3c557b5eaa3a8fd59df2"},{"name":"consul_cluster_with_custom_asg_role_test.go","path":"test/consul_cluster_with_custom_asg_role_test.go","sha":"9ae0ef139943ab35a8d419e6dac36a3a63a3851e"},{"name":"consul_cluster_with_encryption_test.go","path":"test/consul_cluster_with_encryption_test.go","sha":"7d5b18e14addba8ea16423bcf7efae7019bad66b"},{"name":"consul_enterprise_test.go","path":"test/consul_enterprise_test.go","sha":"8ef7e432973510e89f3dc5207856e1211c208b1f"},{"name":"consul_helpers.go","path":"test/consul_helpers.go","sha":"153811288dee25b13c3e15b73d740e18dadfe8db"},{"name":"go.mod","path":"test/go.mod","sha":"6a500c12e474d5afd9a4a6a958895cca0ba80281"},{"name":"go.sum","path":"test/go.sum","sha":"061b1735dfb194fc921bb33058c4ae93af1c3fe8"},{"name":"terratest_helpers.go","path":"test/terratest_helpers.go","sha":"7376d9065d4958533286b82c0a00f86c4f173fce"}]},{"name":"variables.tf","path":"variables.tf","sha":"6e69029d26449d2d967bf43875c681cbcb901200"}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"dnsmasq-install-script\">Dnsmasq Install Script</h1><div class=\"preview__body--border\"></div><p>This folder contains a script for installing <a href=\"http://www.thekelleys.org.uk/dnsmasq/doc.html\" class=\"preview__body--description--blue\" target=\"_blank\">Dnsmasq</a> and configuring\nit to forward requests for a specific domain to Consul. This way, you can easily use Consul as your DNS server for\ndomain names such as <code>foo.service.consul</code>, where <code>foo</code> is a service registered with Consul (see the <a href=\"https://www.consul.io/intro/getting-started/services.html\" class=\"preview__body--description--blue\" target=\"_blank\">Registering\nServices docs</a> for instructions on registering your services\nwith Consul). All other domain names will continue to be resolved via the default resolver on your OS. See the <a href=\"https://www.consul.io/docs/guides/forwarding.html\" class=\"preview__body--description--blue\" target=\"_blank\">Consul\nDNS Forwarding Guide</a> for more info, including trade-offs between using this module and <a href=\"/repos/v0.8.1/terraform-aws-consul/modules/setup-systemd-resolved\" class=\"preview__body--description--blue\">systemd-resolved</a> for DNS forwarding.</p>\n<p>This script has been tested on the following operating systems:</p>\n<ul>\n<li>Ubuntu 16.04</li>\n<li>Amazon Linux 2</li>\n</ul>\n<p>There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.</p>\n<h2 class=\"preview__body--subtitle\" id=\"quick-start\">Quick start</h2>\n<p>To install Dnsmasq, use <code>git</code> to clone this repository at a specific tag (see the <a href=\"/repos/releases\" class=\"preview__body--description--blue\">releases page</a>\nfor all available tags) and run the <code>install-dnsmasq</code> script:</p>\n<pre>git clone --branch <VERSION> https://github.com/hashicorp/<span class=\"hljs-keyword\">terraform</span>-aws-consul.git\n<span class=\"hljs-keyword\">terraform</span>-aws-consul/modules/install-dnsmasq/install-dnsmasq\n</pre>\n<p>Note: by default, the <code>install-dnsmasq</code> script assumes that a Consul agent is already running locally and connected to\na Consul cluster. After the install completes, restart <code>dnsmasq</code> (e.g. <code>sudo /etc/init.d/dnsmasq restart</code>) and queries\nto the <code>.consul</code> domain will be resolved via Consul:</p>\n<pre><span class=\"hljs-selector-tag\">dig</span> <span class=\"hljs-selector-tag\">foo</span><span class=\"hljs-selector-class\">.service</span><span class=\"hljs-selector-class\">.consul</span>\n</pre>\n<p>We recommend running the <code>install-dnsmasq</code> script as part of a <a href=\"https://www.packer.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Packer</a> template to create an\n<a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html\" class=\"preview__body--description--blue\" target=\"_blank\">Amazon Machine Image (AMI)</a> (see the\n<a href=\"/repos/v0.8.1/terraform-aws-consul/examples/consul-ami\" class=\"preview__body--description--blue\">consul-ami example</a> for sample code).</p>\n<h2 class=\"preview__body--subtitle\" id=\"command-line-arguments\">Command line Arguments</h2>\n<p>The <code>install-dnsmasq</code> script accepts the following arguments:</p>\n<ul>\n<li><code>consul-domain DOMAIN</code>: The domain name to point to Consul. Optional. Default: <code>consul</code>.</li>\n<li><code>consul-ip IP</code>: The IP address to use for Consul. Optional. Default: <code>127.0.0.1</code>. This assumes a Consul agent is\nrunning locally and connected to a Consul cluster.</li>\n<li><code>consul-dns-port PORT</code>: The port Consul uses for DNS requests. Optional. Default: <code>8600</code>.</li>\n<li><code>dnsmasq-listen-address IP</code>: The IP address for dnsmasq to listen on. Optional. Defaults to the value of <code>consul-ip</code>.\nMake sure that the network interface you provide for the IP has already been configured before you pass it to dnsmasq.</li>\n</ul>\n<p>Example:</p>\n<pre><span class=\"hljs-keyword\">install</span>-dnsmasq\n</pre>\n<h2 class=\"preview__body--subtitle\" id=\"troubleshooting\">Troubleshooting</h2>\n<p>Add the <code>+trace</code> argument to <code>dig</code> commands to more clearly see what's going on:</p>\n<pre><span class=\"hljs-selector-tag\">dig</span> <span class=\"hljs-selector-tag\">vault</span><span class=\"hljs-selector-class\">.service</span><span class=\"hljs-selector-class\">.consul</span> +<span class=\"hljs-selector-tag\">trace</span>\n</pre>\n","repoName":"terraform-aws-consul","repoRef":"v0.11.0","serviceDescriptor":{"serviceName":"HashiCorp Consul","serviceRepoName":"terraform-aws-consul","serviceRepoOrg":"hashicorp","cloudProviders":["aws"],"description":"Deploy a Consul cluster. Supports automatic bootstrapping, DNS, Consul UI, and auto healing.","imageUrl":"consul.png","licenseType":"open-source","technologies":["Terraform","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"Service Mesh","fileName":"README.md","filePath":"/modules/install-dnsmasq","title":"Repo Browser: HashiCorp Consul","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}