Config file reference

kittehlist uses the KDL format for its configuration file. Currently, the file must adhere to KDL 1.x, but 2.0 will be supported in the future.

Configuration options can be one of:

• nested groups server { ... }
• simple options, such as port in port 80
• positional arguments for simple options or nested groups, like "blahblah" in static-file-dir "blahblah"
• properties for simple options or nested groups, like database url="postgres@localhost"

Duration format

Durations can be specified in jiff’s friendly format format, so among others, any of the following are possible:

• Single timespans with units, like 2s, 2seconds, 2 s, or 2 seconds. Note that microseconds can be written with the proper µs.
• Timespans combined from multiple units, like 2 days 1s or 3 years 1h 3min.

Since KDL is not aware of these formats, you always have to put these durations in quotes.

server

Configuration for the web server.

Example:

server {
    bind {
        host "localhost:81"
    }
    static-file--dir "/usr/share/kittehlist/frontend"
    enable-csp true
}

bind

Where the server should listen.

You can specify IP host definitions, or Unix domain sockets (only on Unix systems, obviously). Multiple hosts and Unix domain sockets can be specified, and kittehlist will bind to all of them.

Example:

bind {
    host "localhost:80"
    host "[fd42::1]:8084"
    unix "/run/kittehlist/kittehlist"
}

host (option)

Type: Socket address; can be specified multiple times

IP host to bind to. This must have the format host:addr.

On most systems, ports below 1024 (such as the default HTTP port 80) require special permissions.

unix (option)

Type: File path; can be specified multiple times

Unix domain socket to bind to.

The socket must not be pre-existing. The directory of the socket must be pre-existing.

base (option)

Type: String

What base path/host/domain kittehlist is being exposed from.

When this option is enabled, various HTML attributes will be set appropriately. This is most important for functional Progressive WebApp (PWA) support, where the manifest must contain the correct base path.

Note that kittehlist does not support being served from anything but the top-level path. Things will break if you try to do this. Also, kittehlist does not try to match the HTTP Host header against this value, since there aren’t multiple virtual servers in kittehlist. If you need this functionality, use a reverse proxy instead.

Examples:

base "http://kittehlist.example.com"
base "https://kittehlist.example.com"
// IP addresses are also possible
base "https://[2001:0db8::1234]"
// invalid, will break in multiple ways
base "https://example.org/kittehlist"

static-file-dir (option)

Type: File path

Directory from where kittehlist will serve its static files.

enable-csp (option)

Type: Boolean (true or false)

Enable the Content Security Policy (CSP).

By default, kittehlist has a strong CSP configuration. It allows:

• any file sourced from the same origin (fallback for all other content types)
• WebAssembly evaluation (to run the frontend code)
• a limited amount of inline JavaScript, verified via ‘unsafe-hashes’ SHA512 hashes:
  • various event handlers that directly call WebAssembly functions
  • the inline frontend loader script, which does the following:
    • load the WebAssembly module
    • load the wasm-bindgen JavaScript wrapper
    • attach event handler functions to the window object

If desired, this CSP can be disabled. It is strongly recommended to serve your own CSP from a reverse proxy in this case.

Note that WebAssembly evaluation via 'wasm-unsafe-eval' is currently required, as there is no standard way of starting WebAssembly without it.

workers (option)

Type: Natural number (positive integer)

How many web workers kittehlist should start per host.

This determines the maximum number of simultaneous connections that can be handled for one of the bind definitions. Therefore, the total number of workers is workers * length(bind).

The default is the number of logical cores (threads) of the system. Note that many systems can benefit from more workers than this, as worker I/O obviously doesn’t block a core from serving other requests.

database

Configuration for the database.

Example:

database url="postgres://postgres:postgres@localhost/kittehlist" {
    connection-timeout "30 seconds"
    max-connections 15
}

url (property)

Type: String

URL or connection string for the PostgreSQL database which kittelist will connect to.

The most common format for PostgreSQL URLs is postgres://user:password@host:port/database. However, any connection string accepted by libpq is allowed. See the linked documentation for additional possible options, including security options like TLS and database password files.

max-connections (option)

Type: Natural number (positive integer)

Maximum number of connections to the database.

Make sure that the database can handle this number of connections. Also, if this value is lower than the worker count, kittehlist may return errors on some requests, because not enough connections are available.

kittehlist doesn’t always open this many connections, only when necessary.

SignedDuration (option)

Type: Duration

Timeout for connecting to the database.

This timeout applies per database worker.

log

Configuration for logging.

Example:

log {
    syslog
    default-level "info"
    format "{msg} {time}"
    level "kittehlist" "trace"
    level "actix_server" "debug"
}

syslog

Specify this option to log to syslog directly. This disables standard output logging and makes the format option ineffective.

This tries to connect to syslog:

• by Unix socket /dev/log or /var/run/syslog (in this order)
• by TCP connection to localhost:601
• by UDP connection to localhost:514

Examples:

syslog
syslog application_name="not-kittehlist"

application-name (positional argument)

Type: String

Application name that kittehlist will send. Default is “kittehlist”.

default-level (option)

Type:

Default logging level.

This level only applies to modules that are not configured with a separate level option.

The default is info. It is generally not recommended to set this to debug or trace unless you are debugging third-party dependencies and/or have been asked to do so as part of a bug report.

format (option)

Type: String

Log format.

kittehlist uses a custom log format that supports {placeholders}. Even though this looks like the Rust or Python format string syntax, none of the formatting options from them is currently supported. kittehlist uses some custom options for certain formats, which are separated by a : from the main placeholder. Multiple options each use their own :. If you want to include literal curly braces, use {{ and }}.

Supported placeholders:

• {level}: Prints the log level as capitalized colored text, always 5 characters wide, left-aligned. You can customize the printout by adding one of these options:
  • no_align to remove the default alignment.
  • no_color to remove the color.
• {message}: Prints the log message itself.
• {time}: Prints the current time as an ISO 8601 timestamp of the current UTC time with seconds precision. Use the local option to use the local time zone instead.
• {module}: Prints the module that the log message originates from.

The default format is unspecified and may change at any time. If you need to rely on a certain log format, set this option.

level (option)

Type: Two positional arguments, module and level; can be specified multiple times

Change log levels per module.

This option can be specified multiple times as level <module> <log level>. Each directive changes the log level of a different module.

Examples:

level "kittehlist" "trace"
level "actix_server" "info"
level "actix_server::middleware" "error"

Useful modules includes:

• kittehlist (this is mainly what you want)
• kittehlist_api (related to kittehlist’s data model and cryptography)
• actix_server (web server operation)
• actix_web::middleware::logger (logs requests nginx-style)