This script has been tested on the following operating systems:
Ubuntu 16.04
Ubuntu 18.04
Ubuntu 20.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 Consul, use git to clone this repository at a specific tag (see the releases page
for all available tags) and run the install-consul script:
The install-consul script will install Consul, its dependencies, and the run-consul script.
The run-consul script is also run when the server is booting to start Consul and configure it to automatically
join other nodes to form a cluster.
Creates an OS user named consul. Creates the following folders, all owned by user consul:
/opt/consul: base directory for Consul data (configurable via the --path argument).
/opt/consul/bin: directory for Consul binaries.
/opt/consul/data: directory where the Consul agent can store state.
/opt/consul/config: directory where the Consul agent looks up configuration.
/opt/consul/log: directory where Consul will store log output.
/opt/consul/tls: directory where an optional server certificate and private key are copied if provided.
/opt/consul/tls/ca: directory where an optional CA certificate is copied if provided.
Installs Consul binaries and scripts
Installs the following:
consul: Either downloads the Consul zip file from the downloads page (the version
number is configurable via the --version argument), or a package hosted on a precise url configurable with --dowload-url
(useful for installing Consul Enterprise, for example) and extracts the consul binary into /opt/consul/bin. Adds a
symlink to the consul binary in /usr/local/bin.
Copies the certificates/key provided by the --ca-file-path, cert-file-path and key-file-path to the Consul
configuration directory. If provided, the CA file is copied to /opt/consul/tls/ca and the server certificate/key
are copied to /opt/consul/tls (assuming the default config path of /opt/consul). The script also sets the
required permissions and file ownership.
Follow-up tasks
After the install-consul script finishes running, you may wish to do the following:
If you have custom Consul config (.json) files, you may want to copy them into the config directory (default:
/opt/consul/config).
If /usr/local/bin isn't already part of PATH, you should add it so you can run the consul command without
specifying the full path.
Dependencies
The install script assumes that systemd is already installed. We use it as a cross-platform supervisor to ensure Consul is started
whenever the system boots and restarted if the Consul process crashes. Additionally, it is used to store all logs which can be accessed
using journalctl.
Why use Git to install this code?
We needed an easy way to install these scripts that satisfied a number of requirements, including working on a variety
of operating systems and supported versioning. Our current solution is to use git, but this may change in the future.
See Package Managers for a full discussion of the requirements, trade-offs, and why we
picked git.
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","toggled":true},{"name":"install-consul","path":"modules/install-consul/install-consul","sha":"f33c659cbb0dc5ab7d5846e7ece811481d42792e"}],"toggled":true},{"name":"install-dnsmasq","children":[{"name":"README.md","path":"modules/install-dnsmasq/README.md","sha":"dbfcd308061679992e9afc3c11264b8140cfe04c"},{"name":"install-dnsmasq","path":"modules/install-dnsmasq/install-dnsmasq","sha":"6ff5256cf38477fe3693c93056a37b96fcb37b16"}]},{"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=\"consul-install-script\">Consul Install Script</h1><div class=\"preview__body--border\"></div><p>This folder contains a script for installing Consul and its dependencies. Use this script along with the\n<a href=\"/repos/v0.11.0/terraform-aws-consul/modules/run-consul\" class=\"preview__body--description--blue\">run-consul script</a> to create a Consul <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html\" class=\"preview__body--description--blue\" target=\"_blank\">Amazon Machine Image\n(AMI)</a> that can be deployed in\n<a href=\"https://aws.amazon.com/\" class=\"preview__body--description--blue\" target=\"_blank\">AWS</a> across an Auto Scaling Group using the <a href=\"/repos/v0.11.0/terraform-aws-consul/modules/consul-cluster\" class=\"preview__body--description--blue\">consul-cluster module</a>.</p>\n<p>This script has been tested on the following operating systems:</p>\n<ul>\n<li>Ubuntu 16.04</li>\n<li>Ubuntu 18.04</li>\n<li>Ubuntu 20.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></p>\n<p>To install Consul, 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-consul</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-consul/install-consul --version <span class=\"hljs-number\">0.8</span>.<span class=\"hljs-number\">0</span>\n</pre>\n<p>The <code>install-consul</code> script will install Consul, its dependencies, and the <a href=\"/repos/v0.11.0/terraform-aws-consul/modules/run-consul\" class=\"preview__body--description--blue\">run-consul script</a>.\nThe <code>run-consul</code> script is also run when the server is booting to start Consul and configure it to automatically\njoin other nodes to form a cluster.</p>\n<p>We recommend running the <code>install-consul</code> script as part of a <a href=\"https://www.packer.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Packer</a> template to create a\nConsul <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.11.0/terraform-aws-consul/examples/consul-ami\" class=\"preview__body--description--blue\">consul-ami example</a> for a fully-working sample code). You can then deploy the AMI across an Auto\nScaling Group using the <a href=\"/repos/v0.11.0/terraform-aws-consul/modules/consul-cluster\" class=\"preview__body--description--blue\">consul-cluster module</a> (see the <a href=\"/repos/v0.11.0/terraform-aws-consul/examples/root-example\" class=\"preview__body--description--blue\">consul-cluster\nexample</a> for fully-working sample code).</p>\n<h2 class=\"preview__body--subtitle\" id=\"command-line-arguments\">Command line Arguments</h2>\n<p>The <code>install-consul</code> script accepts the following arguments:</p>\n<ul>\n<li><code>version VERSION</code>: Install Consul version VERSION. Optional if download-url is provided.</li>\n<li><code>download-url URL</code>: Install the Consul package hosted in this url. Optional if version is provided.</li>\n<li><code>path DIR</code>: Install Consul into folder DIR. Optional.</li>\n<li><code>user USER</code>: The install dirs will be owned by user USER. Optional.</li>\n<li><code>ca-file-path PATH</code>: Path to a PEM-encoded certificate authority used to encrypt and verify authenticity of client and server connections. Optional.</li>\n<li><code>cert-file-path PATH</code>: Path to a PEM-encoded certificate, which will be provided to clients or servers to verify the agent's authenticity. Optional.</li>\n<li><code>key-file-path PATH</code>: Path to a PEM-encoded private key, used with the certificate to verify the agent's authenticity. Optional.</li>\n</ul>\n<p>Example:</p>\n<pre>install-consul --version <span class=\"hljs-number\">1.2</span><span class=\"hljs-number\">.2</span>\n</pre>\n<h2 class=\"preview__body--subtitle\" id=\"how-it-works\">How it works</h2>\n<p>The <code>install-consul</code> script does the following:</p>\n<ol>\n<li><a href=\"#create-a-user-and-folders-for-consul\" class=\"preview__body--description--blue\">Creates a user and folders for Consul</a></li>\n<li><a href=\"#install-consul-binaries-and-scripts\" class=\"preview__body--description--blue\">Installs Consul binaries and scripts</a></li>\n<li><a href=\"#install-tls-certificates\" class=\"preview__body--description--blue\">Installs provided TLS certificates</a></li>\n<li><a href=\"#follow-up-tasks\" class=\"preview__body--description--blue\">Follow-up tasks</a></li>\n</ol>\n<h3 class=\"preview__body--subtitle\" id=\"creates-a-user-and-folders-for-consul\">Creates a user and folders for Consul</h3>\n<p>Creates an OS user named <code>consul</code>. Creates the following folders, all owned by user <code>consul</code>:</p>\n<ul>\n<li><code>/opt/consul</code>: base directory for Consul data (configurable via the <code>--path</code> argument).</li>\n<li><code>/opt/consul/bin</code>: directory for Consul binaries.</li>\n<li><code>/opt/consul/data</code>: directory where the Consul agent can store state.</li>\n<li><code>/opt/consul/config</code>: directory where the Consul agent looks up configuration.</li>\n<li><code>/opt/consul/log</code>: directory where Consul will store log output.</li>\n<li><code>/opt/consul/tls</code>: directory where an optional server certificate and private key are copied if provided.</li>\n<li><code>/opt/consul/tls/ca</code>: directory where an optional CA certificate is copied if provided.</li>\n</ul>\n<h3 class=\"preview__body--subtitle\" id=\"installs-consul-binaries-and-scripts\">Installs Consul binaries and scripts</h3>\n<p>Installs the following:</p>\n<ul>\n<li><code>consul</code>: Either downloads the Consul zip file from the <a href=\"https://www.consul.io/downloads.html\" class=\"preview__body--description--blue\" target=\"_blank\">downloads page</a> (the version\nnumber is configurable via the <code>--version</code> argument), or a package hosted on a precise url configurable with <code>--dowload-url</code>\n(useful for installing Consul Enterprise, for example) and extracts the <code>consul</code> binary into <code>/opt/consul/bin</code>. Adds a\nsymlink to the <code>consul</code> binary in <code>/usr/local/bin</code>.</li>\n<li><code>run-consul</code>: Copies the <a href=\"/repos/v0.11.0/terraform-aws-consul/modules/run-consul\" class=\"preview__body--description--blue\">run-consul script</a> into <code>/opt/consul/bin</code>.</li>\n</ul>\n<h3 class=\"preview__body--subtitle\" id=\"installs-tls-certificates\">Installs TLS certificates</h3>\n<p>Copies the certificates/key provided by the <code>--ca-file-path</code>, <code>cert-file-path</code> and <code>key-file-path</code> to the Consul\nconfiguration directory. If provided, the CA file is copied to <code>/opt/consul/tls/ca</code> and the server certificate/key\nare copied to <code>/opt/consul/tls</code> (assuming the default config path of <code>/opt/consul</code>). The script also sets the\nrequired permissions and file ownership.</p>\n<h3 class=\"preview__body--subtitle\" id=\"follow-up-tasks\">Follow-up tasks</h3>\n<p>After the <code>install-consul</code> script finishes running, you may wish to do the following:</p>\n<ol>\n<li>If you have custom Consul config (<code>.json</code>) files, you may want to copy them into the config directory (default:\n<code>/opt/consul/config</code>).</li>\n<li>If <code>/usr/local/bin</code> isn't already part of <code>PATH</code>, you should add it so you can run the <code>consul</code> command without\nspecifying the full path.</li>\n</ol>\n<h2 class=\"preview__body--subtitle\" id=\"dependencies\">Dependencies</h2>\n<p>The install script assumes that <code>systemd</code> is already installed. We use it as a cross-platform supervisor to ensure Consul is started\nwhenever the system boots and restarted if the Consul process crashes. Additionally, it is used to store all logs which can be accessed\nusing <code>journalctl</code>.</p>\n<h2 class=\"preview__body--subtitle\" id=\"why-use-git-to-install-this-code\">Why use Git to install this code?</h2>\n<p>We needed an easy way to install these scripts that satisfied a number of requirements, including working on a variety\nof operating systems and supported versioning. Our current solution is to use <code>git</code>, but this may change in the future.\nSee <a href=\"/repos/v0.11.0/terraform-aws-consul/_docs/package-managers.md\" class=\"preview__body--description--blue\">Package Managers</a> for a full discussion of the requirements, trade-offs, and why we\npicked <code>git</code>.</p>\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-consul","title":"Repo Browser: HashiCorp Consul","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
install-consul
