This folder contains a script for configuring systemd-resolved
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 and Github Issue for more info.
This script has been tested on the following operating systems:
Ubuntu 18.04
Quick start
To setup systemd-resolved, use git to clone this repository at a specific tag (see the releases page
for all available tags) and run the setup-systemd-resolved script:
Note: by default, the setup-systemd-resolved script assumes that a Consul agent is already running locally and connected to
a Consul cluster. After the install completes, restart systemd-resolved (e.g. sudo systemctl restart systemd-resolved.service) and queries
to the .consul domain will be resolved via Consul:
The setup-systemd-resolved 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.
Example:
setup-systemd-resolved
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":"b602d607e34a3cbef8c7f766d18369841efbb89a"}]},{"name":".gitignore","path":".gitignore","sha":"866fba08567d4c22683017421abdb60f985833f2"},{"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":"9f6aed2a3cc04e4ef63c90448b2f0ac07378b270"},{"name":"README.md","path":"README.md","sha":"2f70405c336d19685c495170b103691ed604b300"},{"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":"e575763ccd2158e49f3b5c53aad2b8f197992260"}]},{"name":"_docs","children":[{"name":"amazon-linux-ami-list.md","path":"_docs/amazon-linux-ami-list.md","sha":"fc523855ab81d4958d77179a64e3bb7d10782664"},{"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":"ubuntu16-ami-list.md","path":"_docs/ubuntu16-ami-list.md","sha":"b551779a9941362909d3f5d76fe709e52f02067e"}]},{"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":"2b71fb3d7a4cd4176ece97a50a859e8106ebcd5a"},{"name":"consul.json","path":"examples/consul-ami/consul.json","sha":"0cbaaf8e0ce8509414ba1caee19997980f39faf7"}]},{"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":"fa9beba847bff2270703632a526ffbeb2070974c"}]},{"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":"ed53539e6440f8b9a0b951c78b90270409daf07b"},{"name":"outputs.tf","path":"examples/example-with-custom-asg-role/outputs.tf","sha":"347e121901e654df4aaabe434af02c7ced60c051"},{"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":"a7f5025a21c9252bdb592a852bf485a426bc9347"}]},{"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":"90b3095339a0ac6234c4165412534025ffe5e403"},{"name":"outputs.tf","path":"examples/example-with-encryption/outputs.tf","sha":"347e121901e654df4aaabe434af02c7ced60c051"},{"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":"2a3b298a526ab2bb5abbd91f7ac513a528ff57b8"},{"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":"2f741e848bd95f3d7798f4fd52021ddfdb30d3bd"}]},{"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":"ce92b8206ed5e2be29d5e877235dca412bfdb47a"},{"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":"a90c7a072a8d939094a0171f03520b22986a72d2"},{"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":"ef8e3e819c481fde0ff65c90ae6a3efe99ac30d0"},{"name":"outputs.tf","path":"modules/consul-cluster/outputs.tf","sha":"a980d658e1be410a013a7e7febcc38a49899ffdc"},{"name":"variables.tf","path":"modules/consul-cluster/variables.tf","sha":"f3b4dcad2f1d02a179d25c7cc63e8e5d2c62da11"}]},{"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":"815931541fb65a51755fd053e0e5f264eaf14111"},{"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":"6eb9aa2bbd44923f048f5e582b1d301571be4fbc"},{"name":"variables.tf","path":"modules/consul-security-group-rules/variables.tf","sha":"b9f5fe2bd11994d2d8eeb932db8650b43c47add1"}]},{"name":"install-consul","children":[{"name":"README.md","path":"modules/install-consul/README.md","sha":"1d451e16e08a4f6259cb3ee643e39d6171d5a4d9"},{"name":"install-consul","path":"modules/install-consul/install-consul","sha":"476e0e67cac0bcc3561114dd50d0cc8f383086db"}]},{"name":"install-dnsmasq","children":[{"name":"README.md","path":"modules/install-dnsmasq/README.md","sha":"80f0d44b7c7e916821ec8fd624d624f16eb2cb20"},{"name":"install-dnsmasq","path":"modules/install-dnsmasq/install-dnsmasq","sha":"a2b23000018ed0bb4265f137219cea939c851306"}]},{"name":"run-consul","children":[{"name":"README.md","path":"modules/run-consul/README.md","sha":"0b990a784db0354a8bd0401c8a64033765e01c05"},{"name":"run-consul","path":"modules/run-consul/run-consul","sha":"204fcdff91cbdabb8c4166e213e400bf8140d543"}]},{"name":"setup-systemd-resolved","children":[{"name":"README.md","path":"modules/setup-systemd-resolved/README.md","sha":"92a5fb39c0eabefcfc84f20ebe7a994156774fc0","toggled":true},{"name":"setup-systemd-resolved","path":"modules/setup-systemd-resolved/setup-systemd-resolved","sha":"d81c2bf0966dd1d1a1a97fc24c5862048b05b2cd"}],"toggled":true}],"toggled":true},{"name":"outputs.tf","path":"outputs.tf","sha":"347e121901e654df4aaabe434af02c7ced60c051"},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"874818e6da7a9c0c9338edde0c27fa3f8a3b3d05"},{"name":"aws_helpers.go","path":"test/aws_helpers.go","sha":"867034abaf29d9c6e641daa9c4a51a8286ffb0ed"},{"name":"consul_cluster_test.go","path":"test/consul_cluster_test.go","sha":"179f09e027f87ee8b94debdd0a01a610708cc4b4"},{"name":"consul_cluster_with_custom_asg_role_test.go","path":"test/consul_cluster_with_custom_asg_role_test.go","sha":"96595f03771d0bb27d07ac9739284a9190be3530"},{"name":"consul_cluster_with_encryption_test.go","path":"test/consul_cluster_with_encryption_test.go","sha":"2149dd3a2eb3a0fbab52b17db8d0c18970df5d72"},{"name":"consul_enterprise_test.go","path":"test/consul_enterprise_test.go","sha":"6632f0529b899a314093b489335233108af86d21"},{"name":"consul_helpers.go","path":"test/consul_helpers.go","sha":"da283d181716a2dd127e6b6ebf2bdb3a46f52539"},{"name":"go.mod","path":"test/go.mod","sha":"34184d187f97882ff6ff03b5f22886d2625a7c59"},{"name":"go.sum","path":"test/go.sum","sha":"d0bb4149e83152c6ac5576e0258eb3ef5925bebf"},{"name":"terratest_helpers.go","path":"test/terratest_helpers.go","sha":"cfe73dfea67dc40877e7df715c73dda501e614fd"}]},{"name":"variables.tf","path":"variables.tf","sha":"a2ab5424fac8bd42c8e48a9073ec2e1a403d5db3"}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"systemd-resolved-setup-script\">systemd-resolved Setup Script</h1><div class=\"preview__body--border\"></div><p>This folder contains a script for configuring <a href=\"http://man7.org/linux/man-pages/man8/systemd-resolved.service.8.html\" class=\"preview__body--description--blue\" target=\"_blank\">systemd-resolved</a>\nto 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> and <a href=\"https://github.com/hashicorp/consul/issues/4155\" class=\"preview__body--description--blue\" target=\"_blank\">Github Issue</a> for more info.</p>\n<p>This script has been tested on the following operating systems:</p>\n<ul>\n<li>Ubuntu 18.04</li>\n</ul>\n<h2 class=\"preview__body--subtitle\" id=\"quick-start\">Quick start</h2>\n<p>To setup systemd-resolved, 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>setup-systemd-resolved</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/setup-systemd-resolved/setup-systemd-resolved\n</pre>\n<p>Note: by default, the <code>setup-systemd-resolved</code> script assumes that a Consul agent is already running locally and connected to\na Consul cluster. After the install completes, restart <code>systemd-resolved</code> (e.g. <code>sudo systemctl restart systemd-resolved.service</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>setup-systemd-resolved</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.7.3/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>setup-systemd-resolved</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</ul>\n<p>Example:</p>\n<pre><span class=\"hljs-built_in\">setup</span>-systemd-resolved\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.7.10","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/setup-systemd-resolved","title":"Repo Browser: HashiCorp Consul","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}