This page lists every setting of klav-server, with its default, and explains its logs and how to send approval notifications to the iPhone. Every setting has a safe default.
Where settings come from
- An optional TOML file, with
--config <path>(or-c) or theKLAV_CONFIGvariable. KLAV_*environment variables, which win over the file.
An unknown key in the file is an error, so a typo doesn’t pass silently:
klav-server: invalid config file: unknown field `lisen`, expected one of `listen`, `database_url`, `data_dir`, `trust_forwarded_for`, `trusted_ip_header`, `allow_registration`, `sessions`, `retention`, `log`, `limits`, `rate_limit`, `push`Environment variables
| Variable | TOML key | Default | What it does |
|---|---|---|---|
KLAV_CONFIG |
— | — | The TOML file’s path |
KLAV_LISTEN |
listen |
127.0.0.1:8080 (0.0.0.0:8080 in the image) |
Address and port |
KLAV_DATABASE_URL |
database_url |
sqlite://data/klav.db (sqlite:///data/klav.db in the image) |
sqlite://… or postgres://… |
KLAV_DATA_DIR |
data_dir |
data (/data in the image) |
Folder for attachments |
KLAV_ALLOW_REGISTRATION |
allow_registration |
true (false in docker-compose.yml) |
Accept new accounts |
KLAV_TRUST_FORWARDED_FOR |
trust_forwarded_for |
false |
Take the client’s IP address from X-Forwarded-For |
KLAV_TRUSTED_IP_HEADER |
trusted_ip_header |
none | A header your proxy sets to the client’s IP address, such as x-real-ip; not with the one above |
KLAV_LOG_FORMAT |
log.format |
json |
json or pretty |
KLAV_LOG |
log.filter |
info |
Log filter, such as info,klav_server=debug |
KLAV_APNS_KEY_PATH |
push.apns.key_path |
— | The APNs .p8 key file |
KLAV_APNS_KEY |
push.apns.key |
— | The .p8 key’s PEM content, instead of the path |
KLAV_APNS_KEY_ID |
push.apns.key_id |
— | That key’s ID |
KLAV_APNS_TEAM_ID |
push.apns.team_id |
— | Your Apple team ID |
KLAV_APNS_TOPIC |
push.apns.topic |
— | The iPhone app’s bundle ID |
Booleans take true/false, 1/0 and yes/no. For the two IP settings, see The client’s IP address.
The whole TOML file
Every key, with its default. [push.apns] has no default and stays commented out:
listen = "127.0.0.1:8080"
database_url = "sqlite://data/klav.db"
data_dir = "data"
trust_forwarded_for = false
# trusted_ip_header = "x-real-ip" # or this one, never both
allow_registration = true
[sessions]
access_ttl_secs = 900 # access token: 15 min
refresh_ttl_secs = 2592000 # refresh token: 30 days, renewed on each use
[retention]
trash_days = 30 # trash and deleted vaults, before they are purged
purge_interval_secs = 3600 # how often the purge runs
[log]
format = "json"
filter = "info"
[limits]
max_json_body_bytes = 4194304 # 4 MiB per JSON request
max_meta_bytes = 65536 # metadata of a vault or project
max_overview_bytes = 65536 # an item's overview section
max_details_bytes = 1048576 # an item's details section
max_item_versions = 50 # earlier versions kept per item
max_attachment_bytes = 104857600 # 100 MiB per attachment (encrypted)
max_attachment_chunk_bytes = 8388608 # 8 MiB per upload chunk
max_pending_upload_bytes = 1073741824 # 1 GiB of unfinished uploads per account
[rate_limit] # token buckets: refill per minute, and burst
ip_per_minute = 600 # every request, per IP address
ip_burst = 120
auth_ip_per_minute = 30 # prelogin, registration, login and refresh, per IP address
auth_ip_burst = 10
auth_email_per_minute = 10 # attempts per email and IP address
auth_email_burst = 5
account_per_minute = 1200 # signed-in requests per account
account_burst = 300
# Approval notifications to the iPhone: off by default.
# Uncomment key_path (or key), key_id, team_id and topic; with one missing,
# the server doesn't start.
# [push.apns]
# key_path = "/run/secrets/AuthKey_<KEY_ID>.p8"
# key = """-----BEGIN PRIVATE KEY-----…""" # or the content, never both
# key_id = "<KEY_ID>"
# team_id = "<TEAM_ID>"
# topic = "<your bundle ID>"Over a limit, the server answers 429 with Retry-After. Limits per IP address group IPv6 addresses by their /64. The sign-in limit per email counts by email and IP address, so someone who knows your email can’t lock you out from another network.
Logs
Logs go to standard output, one JSON object per line:
{"timestamp":"…","level":"INFO","message":"klav-server listening","listen":"127.0.0.1:8080","version":"…","target":"klav_server"}For each request the server logs the method, the route as a template (/v1/vaults/{vault_id}/items/{item_id}), the status code and the duration. It never logs bodies, encrypted data, headers (Authorization included) or query strings.
When an account is deleted, the log keeps one account deleted line with the account’s ID in its account field, never its email. Keep these lines with your backups: see Deleted accounts.
Approval notifications to the iPhone
Without [push.apns], the server sends no notifications, and the iPhone app sees agents’ requests while it is open. To notify the iPhone:
- In your Apple developer account, create a key with Apple Push Notifications service (APNs). Download its
.p8file (you can only download it once) and note its Key ID and your Team ID. - Give the key to the server, either as a file readable only by the server’s user (in Docker, a secret or a read-only volume), in
KLAV_APNS_KEY_PATH; or as content, the whole PEM with itsBEGINandENDlines, inKLAV_APNS_KEY. Line breaks may be written as literal\n. Never both. - Set
KLAV_APNS_KEY_ID,KLAV_APNS_TEAM_IDandKLAV_APNS_TOPIC, the bundle ID of the iPhone app you build and sign (see the last point below).
The four go together. If one is missing, the server doesn’t start:
klav-server: invalid configuration: APNs needs KLAV_APNS_KEY_PATH or KLAV_APNS_KEY, KLAV_APNS_KEY_ID, KLAV_APNS_TEAM_ID and KLAV_APNS_TOPIC- The server reads the key when it starts and refuses to start if it isn’t a valid P-256 key, without repeating its content. It never logs the key, its signed tokens or the devices’ tokens.
- A key given in
KLAV_APNS_KEYstays in the process’s environment, where anyone who can read it sees it. Prefer the file where you can. - Apple sees that your server notifies a device, when, and the kind of notification with a random ID. Not the agent’s name, its reason or the item.
- Apple delivers a notification only to an app signed by the same team as the key. The Klav app you get from TestFlight is signed by Klav, so a key of your own reaches only an app you build and sign yourself.