This guide will walk you through the steps necessary to download and run linkerd locally.
In order to run linkerd locally, you must have Java 8 installed. You can check your Java version by running:
$ java -version java version "1.8.0_66"
linkerd works with both Oracle and OpenJDK. If you need to install Java 8, you can download either one.
Downloading & installing
First, download the latest binary release of linkerd.
Once you’ve downloaded the release, extract it:
$ tar -xzf linkerd-1.3.0.tgz $ cd linkerd-1.3.0
The release will contain these files:
config/linkerd.yaml— config file defining routers, servers, protocols, and ports
disco/— file-based service discovery config
linkerd-1.3.0-exec— linkerd executable
logs/— default location where linkerd logs are written
Once you have extracted the release, you can start and stop linkerd by using
To start linkerd, run:
$ ./linkerd-1.3.0-exec config/linkerd.yaml
Making sure it works
You can validate that linkerd works by sending some HTTP traffic through it.
Out of the box, linkerd is configured to listen on port 4140, and to route any
HTTP calls with a
Host header set to “web” to a service listening on port
You can test this by running a simple service on port 9999:
$ echo 'It works!' > index.html $ python -m SimpleHTTPServer 9999
This will be our destination server, and will respond to any HTTP request with a friendly response. We can send traffic to this destination by connecting to linkerd and specifying the appropriate host header:
$ curl -H "Host: web" http://localhost:4140/ It works!
Because we’ve asked linkerd to proxy the “web” host, our request is routed to the server on port 9999, and the response is proxied to the client. It works!
Note that if you don’t provide a Host header that matches the name of one of the routable services, linkerd will fail the request:
$ curl -I -H "Host: foo" http://localhost:4140/ HTTP/1.1 502 Bad Gateway
Of course, there’s a lot more to naming services than this! In the next section, we’ll see where the service information used above is specified.
File-based service discovery
Under the configuration shipped with linkerd, the first place it looks when it
needs to resolve a service endpoints is the
(See the configuration guide for more on how this simple file-based service
discovery system works.)
With this configuration, linkerd looks for files with names corresponding to
the concrete name of a destination, and it expects these files to contain
a newline-delimited list of addresses in
host port form.
The default configuration looks like this:
$ head disco/* ==> disco/thrift-buffered <== 127.0.0.1 9997 ==> disco/thrift-framed <== 127.0.0.1 9998 ==> disco/web <== 127.0.0.1 9999
As you can see, there is a destination called “web” that is backed by a single
127.0.0.1 9999, as well as a thrift framed destination that is backed
127.0.0.1 9998, and a thrift buffered destination that is backed by
127.0.0.1 9997. Note that, just as it does with all service discovery
endpoints, linkerd monitors this directory for changes, so feel free to add,
remove, and edit files at any point—no restarting required.
The routing configuration that is shipped with linkerd is very simple, and
routes directly to the concrete names specified in this directory. In other
words, asking linkerd for the “web” service, as we did above, will result in it
connecting to one of the endpoints in the
This routing configuration is good for demonstrating basic functionality, but linkerd is capable of a lot more, including multiple service discovery endpoints, per-request routing rules, debug proxy injection, service failover, and more. See the Routing page for details on linkerd’s routing capabilities.