Configuring Katana

NOTE: Katana will automatically create an example config file for you to base your setup on.

The config file is a list of "listeners", each listener has it's own configuration and main port.

Configuring Katana

Property	Default	Description
type	http	For future use ;)
name	www	The name of the server, for your use.
port	80	The port of the server, note that there will is a separate port field for SSL (ssl.port).
debug_mode	false	Enables debug mode, very spammy.
is_behind_proxy	false	Whether or not to trust the X-Forwarded-For header, enable this if you are behind another proxy such as Cloudflare or CloudFront.
servlets	...	The actual gravy of Katana, see the Configuring Servlets section down below.
ssl	...	The SSL configuration, see the Configuring SSL section down below.

Configuring SSL

Property	Default	Description
enabled	false	Whether or not to enable SSL.
port	443	The port of the server, note that this is separate from the http port (default 80).
force	false	Whether or not to forcefully redirect clients to port 443.
allow_insecure	true	Whether or not to actually process any requests on the http port (default 80).
dh_size	2048	The Diffie–Hellman key size for use in ECDH protocols. Values less than 2048 are considered insecure.
enabled_cipher_suites	...	The list of cipher suites to use for SSL, note that the default list will get you an A on Qualys SSL Labs.
tls	...	The SSL versions to use, note that SSLv3, TLSv1, and TLSv1_1 are considered insecure and should not be used.
certificate_file		The certificate to use. Usually "crt.pem"
private_key_file		The private key to use. Usually "key.pem"
trust_chain_file		The chain of trust to use. Usually "chain.pem". Note, do not use any file called "chain-only."

Configuring Servlets

All servlets have these properties:

Property	Default	Description
type	...	The type of servlet to use, see the types and their additional options down below.
priority	1	The priority of this servlet, higher values have precedent over lower values.
hostnames	["*"]	The hostnames to match, e.g example.com, *.example.org. Use an asterix as wildcard.
cors_allowed_hosts	["*"]	The origin hostnames to add CORS headers for, every configured hostname is automatically added to this list.

The File Servlet

The file servlet type allows you to serve a file based on a regex path. For example, you may wish to expose a log file but not the entire logs folder, with this you can set path to /my/logs/path.log and the file to /var/www/logs/whatever.log.

Property	Description
file	The file to serve. Cannot be a directory.
path	The path to match, you can use regex to match paths dynamically. (e.g /thing/.*/log.log)

Example File Servlet (Serves the contents of `example.log` on /logs/example.log)

{
    "type": "file",
    "priority": 1,
    "hostnames": [
        "*"
    ],
    "cors_allowed_hosts": [
        "*"
    ],
    "file": "./example.log",
    "path": "/logs/example.log"
}

The Redirect Servlet

The redirect servlet type allows you to redirect an entire hostname to another URL.

Property	Description
redirect_url	The URL to redirect the user to.
include_path	Whether or not to preserve the request path.

Example Redirect Servlet (Redirects `search.example.com` to `google.com`, preserving the path.)

{
    "type": "redirect",
    "priority": 1,
    "hostnames": [
        "search.example.com"
    ],
    "cors_allowed_hosts": [
        "*"
    ],
    "redirect_url": "https://google.com",
    "include_path": true
}

The Static Servlet

The static servlet type allows you to serve an entire directory on a hostname.

Property	Description
directory	The directory to serve files from. Note that Katana will NOT serve and files from outside of this directory, only subdirectories.
require_file_extensions	Whether or not to to require file extensions, if you're serving a website and wish to be able to use /about instead of /about.html then enable this option.

Example Static Servlet (Serves the contents of `www`)

{
    "type": "static",
    "priority": 1,
    "hostnames": [
        "*"
    ],
    "cors_allowed_hosts": [
        "*"
    ],
    "directory": "./www",
    "require_file_extensions": false
}

The Proxy Servlet

The proxy servlet type allows you to dynamically forward requests to a different http server with ease.

Property	Description
proxy_url	The URL to proxy traffic to. Use http or https, websocket will automatically be rewritten to the appropriate protocol for you.
proxy_path	The path to match. Set to null if you want to proxy the ENTIRE hostname.
include_path	Whether or not to include the request path in the final proxy url. There must only be ONE wildcard and it MUST be at the end of the URL. e.g If your proxy_path is set to /subservice/.* and your proxy_url is http://localhost:1234 then requests made to /subservice/directory/test.html will get forwarded to http://localhost:1234/directory/test.html.
forward_ip	Whether or not to forward the user's IP to the proxy target, the IP will be appended to the X-Forwarded-For header.
allow_http	Whether or not to process plain HTTP requests.
allow_websockets	Whether or not to proxy WebSocket requests.
ignore_bad_ssl	Whether or not to ignore invalid certificated on the proxy target, useful for using a self-signed cert on a local intranet.
forward_host	Whether or not to forward the host header to the proxy target.
follow_redirects	Whether or not the proxy client should follow redirects before sending the response to the user. The default (false) is considered "normal" behavior.
solve_for_ip	This feature allows you to have a wildcard, say *.example.com, and request a resource at 10-0-0-2.example.com which will map to 10.0.0.2 (use the {ip} placeholder in the proxy url). It is strongly recommended you only allow a known range in your hostnames, such as 10-*.example.com

Example Proxy Servlet (Proxies `localhost` to `https://example.com`, including the path)

{
    "type": "proxy",
    "priority": 1,
    "hostnames": [
        "localhost",
        "127.0.0.1"
    ],
    "cors_allowed_hosts": [
        "*"
    ],
    "proxy_url": "https://example.com",
    "proxy_path": null,
    "include_path": true,
    "forward_ip": true,
    "allow_http": true,
    "allow_websockets": true,
    "ignore_bad_ssl": false,
    "forward_host": false,
    "follow_redirects": false,
    "solve_for_ip": false
}

The Echo Servlet

The echo servlet will echo back the HTTP request in 1.1 format.

Property	Description
N/A	N/A

Example Echo Servlet

{
    "type": "echo",
    "priority": 1,
    "hostnames": [
        "echo.example.com"
    ],
    "cors_allowed_hosts": [
        "*"
    ]
}

The WebhookToWS Servlet

The webhook_to_ws servlet allows multiple machines to receive webhooks, over websocket.

Property	Description
path	The path to match on the hostname. This is a startsWith operation.
websocket_secret	The secret key websocket clients must use.
allowed_methods	The allowed Webhook HTTP methods.

Example WebhookToWS Servlet

{
    "type": "webhook_to_ws",
    "priority": 1,
    "hostnames": [
        "webhook.example.com"
    ],
    "cors_allowed_hosts": [
        "*"
    ],
    "path": "/",
    "websocket_secret": "abc123",
    "allowed_methods": ["POST"]
}

WebhookToWS WebSocket Details

WebSockets connect to the path they wish to receive events for. 
So if your `path` is set to `/` and a webhook comes in on `/user1` 
then you will receive events on `ws://<hostname>:<port>/user1`.

You will receive a JSON payload with the following properties: 
`request_id`, `method`, `body_b64`. The first websocket to reply 
will become the response. The reply format is as follows: 
`request_id`, `code` (http status code), `body_b64`, `headers` (key:value map).