Documentation

Point tileserver-rs at a PMTiles archive on any SSH/SFTP host and serve it as vector or raster tiles — no download, no local copy. Range reads happen over a single reused SFTP session per source.

[[sources]]
id = "remote"
type = "pmtiles"
path = "sftp://user@host:22/data/tiles.pmtiles"

Enable the feature at build time (it is not in the default build):

cargo build --release --features sftp

URL format

sftp://<user>@<host>[:<port>]/<absolute/remote/path>.pmtiles
  • user and host are required; port defaults to 22.
  • The remote path is always absolute (a leading / is implied after the host).

Authentication

Key-based only — password auth is intentionally unsupported. The identity is resolved with this precedence (highest first):

  1. Per-source options.ssh_identity
  2. TILESERVER_SSH_IDENTITY environment variable
  3. --ssh-identity <path> CLI flag
  4. ~/.ssh/id_ed25519
  5. ~/.ssh/id_rsa
  6. $SSH_AUTH_SOCK SSH agent

If no identity is found, the source fails to load at startup and the error lists every location that was tried.

Host key verification

Verification is fail-closed. On connect, the server key is checked against known_hosts:

  • Match → connect.
  • Mismatch → refuse with a host-key-mismatch error (SHA-256 fingerprints logged), before any range read.
  • Unknown host → refused when strict_host_key = true (the default). Set strict_host_key = false (globally or per-source) to accept first-seen keys (TOFU).

known_hosts resolution precedence: per-source options.ssh_known_hosts_path → [sftp].known_hosts_path → ~/.ssh/known_hosts. The parser understands literal hosts, *.example.com wildcards, [host]:port entries, comma-separated host lists, and hashed (|1|…) entries.

Configuration

[sftp]
# Global default known_hosts file (per-source override wins).
known_hosts_path = "/home/tiles/.ssh/known_hosts"
strict_host_key = true      # fail-closed on unknown hosts (default)

[[sources]]
id = "remote"
type = "pmtiles"
path = "sftp://tiles@files.example.com:22/srv/tiles/planet.pmtiles"

[sources.options]
ssh_identity = "/home/tiles/.ssh/tileserver_key"
# ssh_user = "tiles"                     # override the URL user
# ssh_port = 2222                        # override the URL port
# ssh_known_hosts_path = "/etc/ssh/known_hosts"
# ssh_strict_host_key_checking = true

Connection management

One SFTP session per source is established at load time and reused for every range read. If the session drops, the backend reconnects with exponential backoff (100 ms → 30 s cap), emitting a tracing warning with the attempt count and delay on each retry.

Security guidance

  • Never use --ssh-insecure-skip-host-key-verify in production — it accepts any host key and is a hidden, test-only flag that logs a loud warning at startup.
  • Use a dedicated SSH key for tileserver-rs, not your personal identity.
  • Prefer a locked-down, chrooted SFTP-only account on the host.
  • Pin exact known_hosts entries; avoid wildcard hostnames for production sources.