consul/website/pages/intro/getting-started/connect.mdx

---
layout: intro
page_title: Consul Connect
sidebar_current: gettingstarted-connect
description: >-
  Connect is a feature of Consul that provides service-to-service connection
  authorization and encryption using mutual TLS. This ensures that all service
  communication in your datacenter is encrypted and that the rules of what
  services can communicate is centrally managed with Consul.
---

# Connect

We've now registered our first service with Consul and we've shown how you
can use the HTTP API or DNS interface to query the address and directly connect
to that service. Consul also provides a feature called **Connect** for
automatically connecting via an encrypted TLS connection and authorizing
which services are allowed to connect to each other.

Applications do not need to be modified at all to use Connect.
[Sidecar proxies](/docs/connect/proxies.html) can be used
to automatically establish TLS connections for inbound and outbound connections
without being aware of Connect at all. Applications may also
[natively integrate with Connect](/docs/connect/native.html)
for optimal performance and security.

-> **Security note:** The getting started guide will show Connect features and
focus on ease of use with a dev-mode agent. We will _not setup_ Connect in a
production-recommended secure way. Please read the [Connect production
guide](/docs/guides/connect-production.html) to understand the tradeoffs.

## Starting a Connect-unaware Service

Let's begin by starting a service that is unaware of Connect. To keep it simple,
let's just use `socat` to start a basic echo service. This service will accept
TCP connections and echo back any data sent to it. If `socat` isn't installed on
your machine, it should be easily available via a package manager.

```shell
$ socat -v tcp-l:8181,fork exec:"/bin/cat"
```

You can verify it is working by using `nc` to connect directly to it. Once
connected, type some text and press enter. The text you typed should be
echoed back:

```
$ nc 127.0.0.1 8181
hello
hello
echo
echo
```

`socat` is a decades-old Unix utility and our process is configured to
only accept a basic TCP connection. It has no concept of encryption, the
TLS protocol, etc. This can be representative of an existing service in
your datacenter such as a database, backend web service, etc.

## Registering the Service with Consul and Connect

Next, let's register the service with Consul. We'll do this by writing
a new service definition. This is the same as the previous step in the
getting started guide, except this time we'll also configure Connect.

```shell
$ cat <<EOF | sudo tee /etc/consul.d/socat.json
{
  "service": {
    "name": "socat",
    "port": 8181,
    "connect": { "sidecar_service": {} }
  }
}
EOF
```

After saving this, run `consul reload` or send a `SIGHUP` signal to Consul
so it reads the new configuration.

Notice the only difference is the line starting with `"connect"`. The existence
of this empty configuration notifies Consul to register a sidecar proxy for this
process. The proxy process represents that specific service. It accepts inbound
connections on a dynamically allocated port, verifies and authorizes the TLS
connection, and proxies back a standard TCP connection to the process.

The sidecar service registration here is just telling Consul that a proxy should
be running, Consul won't actually run a proxy process for you.

We need to start the proxy process in another terminal:

```shell
$ consul connect proxy -sidecar-for socat
==> Consul Connect proxy starting...
    Configuration mode: Agent API
        Sidecar for ID: socat
              Proxy ID: socat-sidecar-proxy

...
```

## Connecting to the Service

Next, let's connect to the service. We'll first do this by using the `consul connect proxy` command again directly. This time we use the command to configure
and run a local proxy that can represent a service. This is a useful tool for
development since it'll let you masquerade as any service (that you have
permissions for) and establish connections to other services via Connect.

The command below starts a proxy representing a service "web". We request
an upstream dependency of "socat" (the service we previously registered)
on port 9191. With this configuration, all TCP connections to 9191 will
perform service discovery for a Connect-capable "socat" endpoint and establish
a mutual TLS connection identifying as the service "web".

```shell
$ consul connect proxy -service web -upstream socat:9191
==> Consul Connect proxy starting...
    Configuration mode: Flags
               Service: web
              Upstream: socat => :9191
       Public listener: Disabled

...
```

With that running, we can verify it works by establishing a connection:

```
$ nc 127.0.0.1 9191
hello
hello
```

**The connection between proxies is now encrypted and authorized.**
We're now communicating to the "socat" service via a TLS connection.
The local connections to/from the proxy are unencrypted, but in production
these will be loopback-only connections. Any traffic in and out of the
machine is always encrypted.

## Registering a Dependent Service

We previously established a connection by directly running `consul connect proxy` in developer mode. Realistically, services need to establish connections
to dependencies over Connect. Let's register a service "web" that registers
"socat" as an upstream dependency in it's sidecar registration:

```shell
$ cat <<EOF | sudo tee /etc/consul.d/web.json
{
  "service": {
    "name": "web",
    "port": 8080,
    "connect": {
      "sidecar_service": {
        "proxy": {
          "upstreams": [{
             "destination_name": "socat",
             "local_bind_port": 9191
          }]
        }
      }
    }
  }
}
EOF
```

This registers a sidecar proxy for the service "web" that
should listen on port 9191 to establish connections to "socat" as "web". The
"web" service should then use that local port to talk to socat rather than
directly attempting to connect.

With that file in place, use `consul reload` or SIGHUP to reload Consul. If the
proxy command from the previous section (with the inline upstream listener) is
still running, stop it with `Ctrl-C`. Now we can start the web proxy using the
configuration from the sidecar registration as we did for socat.

```shell
$ consul connect proxy -sidecar-for web
==> Consul Connect proxy starting...
    Configuration mode: Agent API
        Sidecar for ID: web
              Proxy ID: web-sidecar-proxy

==> Log data will now stream in as it occurs:

    2018/10/09 12:34:20 [INFO] 127.0.0.1:9191->service:default/socat starting on 127.0.0.1:9191
    2018/10/09 12:34:20 [INFO] Proxy loaded config and ready to serve
    2018/10/09 12:34:20 [INFO] TLS Identity: spiffe://df34ef6b-5971-ee61-0790-ca8622c3c287.consul/ns/default/dc/dc1/svc/web
    2018/10/09 12:34:20 [INFO] TLS Roots   : [Consul CA 7]
```

Note in the first log line that the proxy discovered its configuration from the
local agent and setup a local listener on port 9191 that will proxy to the socat
service just as we configured in the sidecar registration.

You can also see the identity URL from the certificate it loaded from the agent
identifying it as the "web" service and the set of trusted root CAs it knows
about.

-> **Security note:** The Connect security model requires trusting
loopback connections when proxies are in use. To further secure this,
tools like network namespacing may be used.

We can verify it works by establishing a new connection:

```
$ nc 127.0.0.1 9191
hello
hello
```

## Controlling Access with Intentions

Intentions are used to define which services may communicate. Our connections
above succeeded because in a development mode agent, the ACL system is "allow
all" by default.

Let's insert a rule to deny access from web to socat:

```shell
$ consul intention create -deny web socat
Created: web => socat (deny)
```

With the proxy processes running that we setup previously, connection
attempts now fail:

```shell
$ nc 127.0.0.1 9191
$
```

Try deleting the intention and attempt the connection again.

```shell
$ consul intention delete web socat
Intention deleted.
$ nc 127.0.0.1 9191
hello
hello
```

Intentions allow services to be segmented via a centralized control plane
(Consul). To learn more, read the reference documentation on
[intentions](/docs/connect/intentions.html).

Note that in the current release of Consul, changing intentions will not
affect existing connections. Therefore, you must establish a new connection
to see the effects of a changed intention. This will be addressed in the near
term in a future version of Consul.

## Discover More Connect

This quick guide has given a taste of what Connect can do but there is much
more. Take a look at [getting started with
Connect](/docs/connect/index.html#getting-started-with-connect) for more guides
on setting up Connect with Envoy proxy, with Docker and in Kubernetes.

## Next Steps

We've now configured a service on a single agent and used Connect for
automatic connection authorization and encryption. This is a great feature
highlight but let's explore the full value of Consul by [setting up our
first cluster](/intro/getting-started/join.html)!