Volume Flags

Per-volume configuration options and flags in copyparty

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 deduplication

When 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

sz · string

Allow filesizes within range

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

df · 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 formatting

Examples: 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

gz · boolean

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

xz · boolean

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

pk · 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

fk · 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.

dk · 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