Router

The Helion 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 value, run the following command:

    $ kato config set router2g client_inactivity_timeout <seconds>
    
  • backend_inactivity_timeout: time (in seconds) the router waits for applications to respond (default 1200 seconds). To change this value, run the following command:

    $ kato config set router2g backend_inactivity_timeout <seconds>
    
  • 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 (X-Forwarded-For, X-Forwarded-proto, X-Real-IP, and so on) 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, this setting, run the following command:

    $ kato config set router2g prevent_x_spoofing false --json
    

    Note

    If you have configured separate network routes to the API endpoint and user applications (for example, 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, 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.

    Note

    _STACKATO_SESSION_AFFINITY_ is the default name of the cookie. You can configure the name of the cookie in the router's config/local.json file.

  • 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. This setting is undefined by default.

  • cluster_endpoint_aliases*: Add aliases for the API Endpoint. See the API Endpoint Alias section for an example.
  • appOnlyRouter: This file setting is not contained in kato. The 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 Helion 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 only during first boot. 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 Helion 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