Page last updated:

Gorouter routes traffic coming into Cloud Foundry to the appropriate component, whether the request comes from an operator addressing the Cloud Controller or from an application user accessing an app running on a Diego Cell. Handling both platform and app requests with the same process centralizes routing logic and simplifies support for WebSocket and other types of traffic (for example, through HTTP CONNECT).

See the following instructions for help getting started with Gorouter in a standalone environment.


$ git clone https://github.com/cloudfoundry/gorouter.git
$ cd gorouter
$ git submodule update --init
$ ./bin/go install gorouter/gorouter
$ gem install nats


# Start NATS server in daemon mode
$ nats-server -d

# Start gorouter
$ ./bin/gorouter


Gorouter receives route updates through NATS. By default, routes that have not been updated in two minutes are pruned. Therefore, to maintain an active route, you must ensure that the route is updated at least every two minutes. The format of these route updates is as follows:

  "host": "",
  "port": 4567,
  "uris": [
  "tags": {
    "another_key": "another_value",
    "some_key": "some_value"

Such a message can be sent to both the gorouter.register subject to register URIs, and to the gorouter.unregister subject to deregister URIs, respectively.

$ nohup ruby -rsinatra -e 'get("/") { "Hello!" }' &
$ nats-pub 'gorouter.register' '{"host":"","port":4567,
Published [gorouter.register] : '{"host":"","port":4567,
$ curl my_first_url.vcap.me:8080


Gorouter provides /varz and /healthz http endpoints for monitoring.

The /routes endpoint returns the entire routing table as JSON. Each route has an associated array of host:port entries.

All of the endpoints require http basic authentication, credentials for which you can acquire through NATS. You can explicitly set the port, user and password (pass is the config attribute) in the gorouter.yml config file status section.

  port: 8080
  user: some_user
  pass: some_password

Example interaction with curl:

$ curl -vvv "http://someuser:somepass@"
* About to connect() to port 8080 (#0)
*   Trying
* Connected
* Connected to ( port 8080 (#0)
* Server auth using Basic with user 'someuser'
> GET /routes HTTP/1.1
> Authorization: Basic c29tZXVzZXI6c29tZXBhc3M=
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host:
> Accept: */*
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Mon, 25 Mar 2013 20:31:27 GMT
< Transfer-Encoding: chunked


This section provides details about Gorouter logging.


The following table describes the log levels supported by Gorouter. The log level is set to debug and is not configurable.

Message Description Examples
fatal Gorouter is unable to handle any requests due to a fatal error. Gorouter cannot bind to its TCP port, a CF component has published invalid data to Gorouter.
error An unexpected error has occurred. Gorouter failed to fetch token from UAA service.
info An expected event has occurred. Gorouter started or exited, Gorouter has begun to prune routes for stale droplets.
debug A lower-level event has occurred. Route registration, route unregistration.

Message Contents

This section section provides a sample Gorouter log entry and explanation of the contents.

[2017-02-01 22:54:08+0000] {"log_level":0,"timestamp":1485989648.0895808,"message":"endpoint-registered","source":"vcap.Gorouter.registry","data":{"uri":"0-*.login.bosh-lite.com","backend":"","modification_tag":{"guid":"","index":0}}}

Property Description
log_level Logging level of the message
timestamp Epoch time of the log
message Content of the log entry
source Gorouter function that initiated the log entry
data Additional information that varies based on the message

About Access Logs

Access logs provide information for the following fields when receiving a request:

<Request Host> - [<Start Date>] "<Request Method> <Request URL> <Request Protocol>" <Status Code> <Bytes Received> <Bytes Sent> "<Referer>" "<User-Agent>" <Remote Address> <Backend Address> x_forwarded_for:"<X-Forwarded-For>" x_forwarded_proto:"<X-Forwarded-Proto>" vcap_request_id:<X-Vcap-Request-ID> response_time:<Response Time> gorouter_time:<GoRouter Time> app_id:<Application ID> app_index:<Application Index> <Extra Headers>

  • The following are optional fields: Status Code, Response Time, Application ID, Application Index, and Extra Headers.

  • If the access log lacks a Status Code, Response Time, Application ID, or Application Index, the corresponding field shows -.

  • Response Time is the total time it takes for the request to go through the Gorouter to the app and for the response to travel back through the Gorouter. This includes the time the request spends traversing the network to the app and back again to the Gorouter. It also includes the time the app spends forming a response.

  • GoRouter Time is the total time it takes for the request to go through the Gorouter initially plus the time it takes for the response to travel back through the Gorouter. This does not include the time the request spends traversing the network to the app. This also does not include the time the app spends forming a response.

Note: Access logs are also redirected to syslog.