Volume Flags

Volflags are per-volume configuration options. Many global options can be set as volflags, and most volflags can also be set as global options.

See the complete list of volflags for all available options.

Syntax

Volflags are specified in the flags: section of a volume configuration:

[/volume]
  /path/to/folder
  accs:
    rw: user
  flags:
    e2d           # simple boolean flag
    fk: 4         # flag with value
    scan: 60      # another flag with value

Upload Configuration

Deduplication

dedup

boolean

Enable symlink-based file deduplicationWhen enabled, duplicate uploads create symlinks instead of storing the file again.

flags:
  dedup
  safededup: 50  # verify file contents before dedup

hardlink

boolean

Enable hardlink-based deduplication, fallback to symlinks when impossible

hardlinkonly

boolean

Dedup with hardlink only, never symlink. Make full copy if hardlink impossible.

reflink

boolean

Enable reflink-based deduplication (CoW filesystems), fallback to full copy when impossible

safededup

number

default:"50"

How careful to be when deduplicating:

1 = just verify filesize
50 = verify file contents have not been altered (default)

nodupe

boolean

Reject duplicate files during upload (only matches within same volume)

flags:
  e2d      # required for dupe detection
  nodupe   # reject duplicates

nodupem

boolean

Also reject dupes when moving a file into another volume

noclone

boolean

Don’t use existing data on disk for dupes. Reduces HDD reads but increases network load.

Upload Rules

maxn

string

Maximum number of uploads in a time period

flags:
  maxn: 250,600  # max 250 uploads over 10 minutes (600 seconds)

maxb

string

Maximum upload bytes in a time period

flags:
  maxb: 1g,300  # max 1 GiB over 5 minutes

Suffixes: b, k, m, g, t

vmaxb

string

Total volume size limit

flags:
  vmaxb: 10g  # volume cannot exceed 10 GiB total

vmaxn

string

Maximum number of files in volume

flags:
  vmaxn: 4k  # max 4096 files in volume

string

Allow filesizes within range

flags:
  sz: 1k-3m  # only accept files between 1 KiB and 3 MiB

string

Ensure free disk space by rejecting uploads

flags:
  df: 1g  # ensure at least 1 GiB remains free

Upload Behavior

rand

boolean

Force randomized filenames, 9 characters long by default

flags:
  rand
  nrand: 12  # make random filenames 12 chars long

nrand

number

default:"9"

Length of randomized filenames

u2ow

number

default:"0"

When to overwrite existing files:

0 = never (generate new filename)
1 = if client file is newer
2 = always overwrite

flags:
  u2ow: 1  # overwrite if newer

u2ts

string

default:"c"

How to timestamp uploaded files:

c = client last-modified time
u = upload time (server time)
fc = force client time
fu = force upload time

flags:
  u2ts: fc  # always use client timestamp

magic

boolean

Enable filetype detection for nameless uploads

put_name

string

default:"put-{now.6f}-{cip}.bin"

Filename template for nameless uploads

flags:
  put_name: upload-{now}.bin

nosub

boolean

Force all uploads into the top folder of the volume (prevent subdirectories)

rm_partial

boolean

Delete unfinished uploads when they timeout (after --snap-drop period)

Upload Rotation

Move uploads into organized folder structures automatically.

rotn

string

Organize by number of files per folder

flags:
  rotn: 100,3  # 3 levels of subfolders with 100 entries each

Example: file-1234.jpg → 12/34/file-1234.jpg

rotf

string

Organize by date/time format

flags:
  rotf: %Y-%m/%d-%H  # organize by year-month/day-hour
  rotf_tz: Europe/Oslo  # timezone (default: UTC)

Example: Upload at 2026-03-03 14:30 → 2026-03/03-14/file.jpg

rotf_tz

string

default:"UTC"

Timezone for rotf date formattingExamples: Europe/Oslo, America/Toronto, Asia/Tokyo

lifetime

number

Auto-delete uploads after N seconds

flags:
  lifetime: 3600  # files deleted after 1 hour

Clients can specify shorter lifetimes when uploading.

File Permissions

chmod_f

string

default:"644"

Unix permissions for new files

flags:
  chmod_f: 644  # owner RW, others R
  chmod_f: 600  # owner RW only

chmod_d

string

default:"755"

Unix permissions for new directories

flags:
  chmod_d: 755   # owner RWX, others RX
  chmod_d: 2750  # setgid + owner RWX, group RX

uid

number

default:"-1"

Unix user-id to chown new files/folders to (-1 = don’t change)

gid

number

default:"-1"

Unix group-id to chown new files/folders to (-1 = don’t change)

wram

boolean

Allow uploading even if volume is inside a ramdisk

All uploaded data will be lost on server reboot!

Compression

boolean

Allow server-side gzip compression of uploads with ?gz URL parameter

boolean

Allow server-side lzma compression of uploads with ?xz URL parameter

string

Force server-side compression (optional: specify algorithm and level)

flags:
  pk: xz,9  # force LZMA compression at level 9

Database Configuration

Indexing

e2d

boolean

Enable database; makes files searchable and enables upload-undo

e2ds

boolean

Scan writable folders for new files on startup (also sets e2d)

e2dsa

boolean

Scan all folders for new files on startup (also sets e2d)

e2t

boolean

Enable multimedia indexing (audio/video tags)

e2ts

boolean

Scan existing files for tags on startup (also sets e2t)

e2tsr

boolean

Delete all metadata from DB for full rescan (also sets e2ts)

d2t

boolean

Disable metadata collection (overrides -e2t*)

Recommended for security when accepting uploads from untrusted users.

d2d

boolean

Disable all database features (overrides all -e2*)

Database Location

hist

string

Location for thumbnails and database

flags:
  hist: /tmp/cdb  # put .hist folder at /tmp/cdb

dbpath

string

Location for database only (keep thumbnails in volume)

flags:
  dbpath: /ssd/music-db  # database on fast SSD

landmark

string

Disable database if specified file doesn’t exist

flags:
  landmark: .enable-db  # DB disabled if .enable-db missing

Database Behavior

scan

number

Scan for new files every N seconds

flags:
  scan: 60  # rescan every 60 seconds

nohash

regex

Skip hashing files matching regex pattern

flags:
  nohash: \.iso$  # don't hash *.iso files

noidx

regex

Fully ignore files matching regex pattern

flags:
  noidx: /\.(git|svn)/  # ignore git/svn folders

noforget

boolean

Don’t forget files when deleted from disk (keep in database)

forget_ip

number

Forget uploader IP after N seconds (GDPR compliance)

flags:
  forget_ip: 43200  # forget IPs after 12 hours

no_db_ip

boolean

Never store uploader IP in database (disables unpost feature)

dbd

string

default:"wal"

Database speed-durability tradeoff:

acid = safest, slowest
swal = safe, fast
wal = balanced (default)
yolo = fastest, data loss possible

flags:
  dbd: yolo  # maximum performance, minimal safety

xlink

boolean

Cross-volume dupe detection/linking

Dangerous - can create links outside volume boundaries!

xdev

boolean

Don’t descend into other filesystems during scanning

xvol

boolean

Don’t follow symlinks leaving the volume root

Filekeys and Dirkeys

number

Generate per-file access keys (N characters long)

[/private]
  /mnt/private
  accs:
    g: *   # anyone with URL+key can download
    rw: admin
  flags:
    fk: 4  # 4-character keys

Keys are invalidated if filesize or inode changes.Example URL: https://example.com/file.jpg?k=Ab3D

fka

number

Generate slightly weaker per-file keys (not affected by filesize/inode)Better for files that may be modified.

number

Generate per-directory access keys

flags:
  dk: 6   # 6-character directory keys
  dks     # allow browsing into subdirs

dks

boolean

Per-directory keys allow browsing into subdirectories

dky

boolean

Allow seeing files (not folders) in a directory with g permission without valid dirkey

Thumbnails

dthumb

boolean

Disable all thumbnails

dvthumb

boolean

Disable video thumbnails only

dathumb

boolean

Disable audio thumbnails (spectrograms) only

dithumb

boolean

Disable image thumbnails only

thsize

string

Thumbnail resolution (WxH)

flags:
  thsize: 320x240

crop

string

Center-cropping behavior: y, n, fy, fn

th3x

string

3x resolution thumbnails: y, n, fy, fn

th_qv

number

default:"40"

WebP/JPEG thumbnail quality (10-90)

convt

number

Convert-to-image timeout in seconds

aconvt

number

Convert-to-audio timeout in seconds

th_spec_p

number

default:"1"

Make spectrograms:

0 = never
1 = fallback if no thumbnail available
2 = always

ext_th

string

Use custom thumbnail for file extension

flags:
  ext_th: exe=/icons/exe.png
  ext_th: pdf=/icons/pdf.svg

Client and UX

grid

boolean

Show grid/thumbnails view by default

gsel

boolean

Enable selecting files in grid by ctrl-click

sort

string

Default sort order

flags:
  sort: href  # sort by filename (default)

nsort

boolean

Natural-sort of leading digits in filenames (e.g., file2 before file10)

unlist

regex

Don’t list files matching regex

flags:
  unlist: ^\.

dlni

boolean

Force-download files on click (no inline preview)

nodirsz

boolean

Don’t show total folder size (~30% faster listings)

du_who

string

default:"all"

Who can see disk usage info:

no = nobody
a = admin permission
rw = read-write access
w = write access
auth = authenticated users
all = everyone

ufavico

string

Per-volume favicon URL

flags:
  ufavico: /icons/music.ico

tcolor

string

Theme color (hint for browsers, discord embeds)

flags:
  tcolor: #fc0

Document Embedding

readmes

string

default:"readme.md,README.md"

Files to embed as readmes

flags:
  readmes: README.md,readme.txt,info.md

preadmes

string

Files to embed as preadmes (before file listing)

prologues

string

Files to embed above/before files

epilogues

string

Files to embed below/after files

wo_up_readme

boolean

Write-only users can upload prologues/epilogues without getting renamed

Security

nohtml

boolean

Return HTML and markdown as text/plain (prevents XSS)

[/uploads]
  /mnt/uploads
  accs:
    w: *  # untrusted uploads
  flags:
    nohtml  # prevent XSS attacks

robots

boolean

Allow indexing by search engines (default)

norobots

boolean

Ask search engines not to index this volume

dotsrch

boolean

Show dotfiles in search results (if user can see dotfiles)

dots

boolean

Allow all users with read-access to enable showing dotfiles in listings

Other Features

rss

boolean

Enable RSS feeds (add ?rss to folder URL)

opds

boolean

Enable OPDS feeds for e-book readers

shr_who

string

default:"auth"

Who can create shares:

no = nobody
a = admin permission
auth = authenticated users

zip_who

string

Restrict download-as-zip/tar access (0=nobody, 1=admins, 2=everyone)

zipmaxn

string

Reject zip download if more than N files

flags:
  zipmaxn: 9k  # max 9000 files in zip

zipmaxs

string

Reject zip download if total size exceeds limit

flags:
  zipmaxs: 2g  # max 2 GiB zip

nospawn

boolean

Don’t create volume’s folder if it doesn’t exist

assert_root

boolean

Crash on startup if volume’s folder doesn’t exist

Complete Example

[/music]
  /mnt/music
  accs:
    r: *
    rw: admin
  flags:
    # Database
    e2dsa      # scan all on startup
    e2ts       # index audio tags
    scan: 300  # rescan every 5 minutes
    hist: /ssd/music-cache
    
    # Thumbnails
    dathumb    # no audio spectrograms
    thsize: 320x320
    th_qv: 60  # higher quality thumbnails
    
    # Client UX
    grid       # show thumbnails by default
    sort: n    # sort by filename
    nsort      # natural number sorting
    
    # Features
    rss        # enable RSS feeds
    robots     # allow search engines

Get Started

Core Features

Configuration

Deployment

Guides

Syntax

Upload Configuration

Deduplication

Upload Rules

Upload Behavior

Upload Rotation

File Permissions

Compression

Database Configuration

Indexing

Database Location

Database Behavior

Filekeys and Dirkeys

Thumbnails

Client and UX

Document Embedding

Security

Other Features

Complete Example

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

Guides

​Syntax

​Upload Configuration

​Deduplication

​Upload Rules

​Upload Behavior

​Upload Rotation

​File Permissions

​Compression

​Database Configuration

​Indexing

​Database Location

​Database Behavior

​Filekeys and Dirkeys

​Thumbnails

​Client and UX

​Document Embedding

​Security

​Other Features

​Complete Example

Build docs developers (and LLMs) love

Syntax

Upload Configuration

Deduplication

Upload Rules

Upload Behavior

Upload Rotation

File Permissions

Compression

Database Configuration

Indexing

Database Location

Database Behavior

Filekeys and Dirkeys

Thumbnails

Client and UX

Document Embedding

Security

Other Features

Complete Example