filebrowser

A lightweight, production-grade single-binary web file browser written in Rust.

Features

Access & Authentication

• HTTP Basic auth + session cookies (HttpOnly, SameSite=Strict)
• TOTP two-factor authentication (RFC 6238, base32 secret)
• Static API bearer tokens with optional per-volume scoping
• Argon2id password hashing (--gen-password); legacy SHA-256 accepted

Authorization

• Three volume access levels: public, readonly, private
• Granular per-user permissions via [[roles]] — override upload, mkdir, delete, rename, zip, can_write, cross_volume, share per volume or globally
• Per-volume capability flags (upload, mkdir, delete, rename, zip, share, cross_volume)

File Operations

• Directory listing (JSON) with sort/order/pagination
• File upload (multipart), mkdir, delete, rename, batch delete/move
• ZIP download of files and directory trees
• Copy / move across volumes (requires cross_volume permission)
• Recursive file search
• Full-file and partial download (Range / Content-Range, RFC 7233)
• Configurable thumbnail generation (Argon2id cache keying, JPEG quality)
• Directory listing as Atom/RSS feed (?feed=atom / ?feed=rss)

Sharing

• Shareable links with optional password, expiry and per-op ACL (allowed_ops: ["download", "list", "upload"])
• Link management API: create, list own links, delete

Performance & Reliability

• Per-volume bandwidth throttling (token-bucket, bytes/sec)
• IP-based rate limiting (configurable RPS + burst; separate login limiter)
• Config hot-reload — watch the TOML file, apply valid changes live
• Session GC and share expiry GC background tasks

Security

• IP allowlist / blocklist (CIDR and plain IP, IPv4 + IPv6)
• Configurable security headers: CSP, X-Frame-Options, HSTS, Referrer-Policy, Permissions-Policy, X-Content-Type-Options
• CSRF protection (double-submit cookie, X-CSRF-Token header)
• CORS configurable per deployment

Observability

• Append-only audit log (JSON or text) with optional read-event logging
• Prometheus metrics at /~metrics — total requests, errors, logins, per-volume bytes in/out, active session count; optional bearer token guard

Operations

• --check — validate config and exit (CI-friendly)
• --gen-password — hash a password (stdin → Argon2id PHC string)
• --gen-totp — generate a TOTP secret and provisioning URI
• --print-config — print the annotated default config template
• Self-hosted Bulma CSS — serve Bulma from the binary instead of a CDN
• Docker support — multi-stage Dockerfile, non-root user, health check

---

Quick Start

# Hash a password
echo -n "hunter2" | filebrowser --gen-password

# Validate config
filebrowser --check --config filebrowser.toml

# Run
filebrowser --config filebrowser.toml

Docker

docker build -t filebrowser .

docker run -d \
  -p 8080:8080 \
  -v /your/files:/app/files \
  -v /your/config/filebrowser.toml:/app/config/filebrowser.toml:ro \
  filebrowser

---

Configuration

Run filebrowser --print-config for a fully-annotated filebrowser.toml.

Key sections:

Section	Purpose
[server]	Host, port, TLS, body limit, hot-reload interval
[ui]	Title, theme, hidden files, pagination, self-host Bulma
[audit]	Log path, format (json/text), log reads toggle
[api]	Enable REST API, static bearer tokens
[rate_limit]	RPS, burst, login attempt limit
[security]	IP allow/blocklist, CSP, CSRF, X-Frame-Options, HSTS
[metrics]	Prometheus endpoint, bearer token guard
[thumbnails]	Enable, size, quality, cache dir, MIME filter
[[roles]]	Named permission bundles with per-volume overrides
[[volumes]]	Paths, URL prefixes, capability flags, bandwidth limit
[[users]]	Credentials (Argon2id), TOTP, roles, volume scoping

---

API Reference

See API.md for full endpoint documentation.

Route overview:

POST   /~auth/login
POST   /~auth/logout
GET    /~auth/me
GET    /~auth/totp/setup

GET    /~api/volumes
GET    /~api/list?path=…[&feed=atom|rss]
GET    /~api/stat?path=…
GET    /~api/download?path=…         (Range header supported)
GET    /~api/preview?path=…
GET    /~api/thumbnail?path=…
POST   /~api/upload                   (multipart)
POST   /~api/mkdir
DELETE /~api/delete?path=…
POST   /~api/rename
POST   /~api/copy
POST   /~api/batch
GET    /~api/zip?paths=…
GET    /~api/search?path=…&q=…

POST   /~api/shares                   (create shareable link)
GET    /~api/shares                   (list own links)
DELETE /~api/shares/:token
GET    /~share/:token                 (access share)
GET    /~share/:token/dl              (download via share)

GET    /~metrics                      (Prometheus)
GET    /~static/bulma.css             (self-hosted Bulma, if enabled)

---

Security

See SECURITY.md for the full security audit (v0.3) including findings, resolutions, and the operator hardening checklist.

---

Self-hosted Bulma CSS

To serve Bulma without a CDN dependency:

1. Download bulma.min.css from https://cdnjs.cloudflare.com/ajax/libs/bulma/1.0.4/css/bulma.min.css
2. Place it at assets/bulma.min.css (next to Cargo.toml)
3. Rebuild — the CSS is embedded in the binary at compile time
4. Set ui.self_host_bulma = true in your config

---

Building

# Debug
cargo build

# Release (LTO, stripped)
cargo build --release

# Security audit
cargo install cargo-audit && cargo audit