Configuration Reference

Liwan can be configured with a TOML configuration file or environment variables.

By default, Liwan looks for liwan.config.toml in the current directory, then ~/.config/liwan/liwan.config.toml on Linux/macOS. You can also pass --config or set LIWAN_CONFIG.

To generate an example configuration file, run liwan generate-config or liwan generate-config -o OUTPUT_PATH.

liwan.config.toml

# The base URL of the Liwan instance
base_url="http://localhost:9042"

# The address to listen on (http)
listen="0.0.0.0:9042"

# Disable fetching favicons for websites using DuckDuckGo's favicon service
# disable_favicons=true

# # Folder to store the database in (Will be created if it doesn't exist)
# # defaults to $HOME/.local/share/liwan/data on Linux/macOS
# # defaults to ./liwan-data on other platforms
# data_dir="./liwan-data"

# Trusted client IP headers (used in order).
# Defaults to all supported headers.
# trusted_headers=["cf-connecting-ip", "fly-client-ip", "true-client-ip", "x-real-ip", "cloudfront-viewer-address", "x-forwarded-for", "forwarded"]
# You can also include custom headers. Names are case-insensitive.
# trusted_headers=["X-Forwarded-For", "X-Client-IP"]

# Trusted reverse proxies (IP or CIDR).
# Empty by default, meaning all proxies are trusted.
# trusted_proxies=["127.0.0.1", "10.0.0.0/8"]

# Whether to use forwarded IP headers at all.
# If false, only the direct peer IP is used.
# use_forward_headers=true

# GeoIp settings (Optional)
[geoip]
# # MaxMind account ID and license key
# # Required to automatically download the database and keep it up to date
# maxmind_account_id="MY_ACCOUNT_ID"
# maxmind_license_key="MY_LICENSE_KEY"
# maxmind_edition="GeoLite2-City"

# # If you don't want to automatically download the database, you can specify a path to a local file.
# # Otherwise, the database will be downloaded automatically and stored in the data_dir
# maxmind_db_path="/path/to/GeoLite2-City.mmdb"

Configuration Options

TOML Key	Environment Variable	Default
base_url	LIWAN_BASE_URL	http://localhost:9042
data_dir	LIWAN_DATA_DIR	platform data dir1
listen	LIWAN_LISTEN	0.0.0.0:9042
disable_favicons	LIWAN_DISABLE_FAVICONS	false
trusted_headers	LIWAN_TRUSTED_HEADERS	all supported headers
trusted_proxies	LIWAN_TRUSTED_PROXIES	empty (all trusted)
use_forward_headers	LIWAN_USE_FORWARD_HEADERS	true
geoip.maxmind_account_id	LIWAN_MAXMIND_ACCOUNT_ID	(none)
geoip.maxmind_license_key	LIWAN_MAXMIND_LICENSE_KEY	(none)
geoip.maxmind_edition	LIWAN_MAXMIND_EDITION	GeoLite2-City
geoip.maxmind_db_path	LIWAN_MAXMIND_DB_PATH	(none)
duckdb.memory_limit	LIWAN_DUCKDB_MEMORY_LIMIT	(none)
duckdb.threads	LIWAN_DUCKDB_THREADS	(core count)

Footnotes

1. On Linux/macOS this defaults to $XDG_DATA_HOME/liwan/data or $HOME/.local/share/liwan/data. On other platforms it defaults to ./liwan-data. ↩