Router

The Stackato Router role manages HTTP and HTTPS traffic between web clients and application instances. In conjunction with the Cloud Controller, it maps application URLs to the corresponding application instances running in Linux containers on DEA nodes, distributing load between multiple instances (containers) as required.

Stackato's default router ('router2g') supports WebSocket (including "wss://" secure web sockets) and SPDY.

Settings

The Router is configured using kato config. The following settings are configurable:

  • client_inactivity_timeout: time (in seconds) the router waits for idle clients (default 1200 seconds). To change this:

    $ kato config set router2g client_inactivity_timeout 2400
    
  • backend_inactivity_timeout: time (in seconds) the router waits for applications to respond (default 1200 seconds). To change this:

    $ kato config set router2g client_inactivity_timeout 2400
    
  • prevent_x_spoofing (true|false): Enable HTTP "X-" header spoofing prevention (default 'true'). When enabled, the router discards all X- headers sent by the client (e.g. X-Forwarded-For, X-Forwarded-proto, X-Real-IP, etc.) and replaces them with values determined by the router itself. Set this option to 'false' only if the routers are behind a load balancer which terminates SSL connections; in this scenario the router will trust the X-headers set by the load balancer.

    To disable:

    $ kato config set router2g prevent_x_spoofing false --json
    

    Note

    If you have configured separate network routes to the API endpoint and user applications (e.g. private network access to the API endpoint, load-balanced public access to applications) this option must be set to 'true'. User applications will not have access to X-headers set by the load balancer.

  • session_affinity (true|false - disabled/unset by default): Enable sticky session support on the router. Overrides normal round-robin load balancing for clients with JSESSIONID, SESSIONID, or PHPSESSID cookies set (configurable in the router's config/local.json file), routing those clients to specific application instances. If the backend assigned on the first request goes down, a new one is automatically assigned. Clients can delete their sticky session assignment by removing the _STACKATO_SESSION_AFFINITY_ cookie.

  • x_frame_options: Prevent clickjacking on requests with X-Frame response header configuration. Disabled if empty (default). Valid values are:

    • DENY
    • SAMEORIGIN
    • ALLOW_FROM <uri>

    For example:

    $ kato config set router2g x_frame_options SAMEORIGIN
    

    Note

    Alternatively, end user applications can employ framekiller JavaScript snippets to help prevent frame based clickjacking.

  • acl: Access Control List settings for the router. Undefined by default.

  • cluster_endpoint_aliases: Add aliases for the API Endpoint. See the API Endpoint Alias section for an example.
  • appOnlyRouter (file setting - not in kato): This setting can be configured on router nodes in the /s/code/stackato-router/config/local.json file. Set appOnlyRouter to true and restart the router to enable. This configures the router to not serve the API Endpoint, only user-deployed applications. At least one router node in every cluster must expose the API Endpoint, but it does not need to be internet accessible if the developers pushing applications are within the same internal network as Stackato.

Restart the router role to apply any config changes to the running router(s):

$ kato restart router

router.yml

The default settings for the router are loaded from a router.yml file in the /s/code/stackato-router/config/ directory during first boot (only). You can use this file to configure the router, but the changes must be manually re-imported with the kato op import_from_yaml_file command:

$ kato op import_from_yaml_file router2g
$ kato restart router

This approach is often easier than manipulating the setings individually.

WebSockets

Applications using web sockets must use the VCAP_APP_PORT or PORT environment variables to set the default listener port of the WebSocket server.

SPDY

SPDY is a protocol developed by Google for reducing web page load time. The router supports SPDY versions 2 and 3. Applications can use SPDY over any HTTPS connection, so long as the connection consumers (the application server and browser) support it.

Access Control List

You can set the router to block specific IP addresses and ranges from connecting to Stackato and the applications it hosts. To enable the access control list:

$ kato config set router2g acl/enabled true

The rules key provides a DENY list for single IP addresses and/or ranges to block. To specify a single IP address:

$ kato config set router2g acl/rules '["192.168.1.90"]'

To add another IP address to the existing list of blocked IPs:

$ kato config push router2g acl/rules "192.168.5.10"

To set a range of IP addresses:

$ kato config set router2g acl/rules '[["192.168.3.100","192.168.3.200"]]'

To set set individual addresses and ranges together:

$ kato config set router2g acl/rules '["192.168.1.90",["192.168.3.100","192.168.3.200"]]'

Note

See also the router.yml section above for setting this configuration using a YAML file instead.

To minimalize snooping or DoS attempts, set the drop_conn key to true. This will terminate connections from blocked IP addresses abruptly without an HTTP 403 error.

$ kato config set router2g acl/drop_conn true

If the routers are behind a load balancer that sets the 'X-Forwarded-For' header, set the use_x_forwarded_for to true:

$ kato config set router2g acl/use_x_forwarded_for true

Use kato config get router2g acl to check your settings:

$ kato config get router2g acl
enabled: true
drop_conn: true
use_x_forwarded_for: false
rules:
- 192.168.1.90
- - 192.168.3.100
  - 192.168.3.200

Restart the router role to apply the changes:

$ kato restart router