copyparty: Reference Cheatsheet
Cheatsheet · Self-hosted · File server
copyparty: Reference Cheatsheet
copyparty turns almost any machine into a file server: one Python file, a web UI with resumable uploads, a media player and search, plus WebDAV, FTP, SFTP, TFTP and SMB on the side. This sheet covers v1.20.26 (14 October 2026): installing and running, the config file, accounts and permission letters, volumes and shadowing, the volflags that matter, up2k uploads, indexing and media, every protocol and port, shares and filekeys, logins and SSO, reverse proxies, Docker and systemd, hardening with the recent security releases, client tools and gotchas. Four diagrams.
python3 copyparty-sfx.py -c party.conf cpx · bub.im
WHAT
What copyparty is
A single process that maps folders on disk to URL paths (volumes), grants per-user permission letters on each, and serves them over every protocol it speaks. Nothing else is required to start; optional packages add thumbnails, media tags, FTPS, SFTP and hashed passwords.
fig 1 · every protocol lands in the same VFS and permission check; dashed listeners are LAN-only and off by default
| Area | What you get |
|---|---|
| Web UI | file browser with list and thumbnail grid, media player with playlists and equalizer, text and markdown viewer and editor, batch rename, cut and paste across tabs, zip and tar downloads |
| Uploads | drag and drop with up2k (chunked, checksummed, resumable, parallel, no size limit), a basic uploader for old browsers, PUT and POST for scripts |
| Find | search by name, path, size, date and media tags; drop files on the page to check whether the server already has them |
| Protocols | HTTP and HTTPS, WebDAV, FTP and FTPS, SFTP (since v1.20.0), TFTP, SMB, mDNS and SSDP announcements, OPDS, RSS, WOPI office editing, Prometheus metrics |
| Runs on | Linux, Windows (also as copyparty.exe), macOS, BSD, Android in Termux, iOS in a-Shell, Docker |
| Default | careful started with no arguments, it shares the current folder read-write for everyone on port 3923 |
RUN
Install and run
| Method | Command | Notes |
|---|---|---|
| Self-extracting script | python3 copyparty-sfx.py | from the GitHub release or copyparty.eu/py; unpacks into $TEMP; plain FTP built in |
| Zipapp | python3 copyparty.pyz | no extraction step, slightly slower |
| PyPI | python3 -m pip install –user -U copyparty | then run copyparty |
| uv | uv tool run copyparty | no install step |
| Windows | copyparty.exe | no Python needed; includes Pillow; add ffmpeg for video thumbnails and tags |
| Packages | pacman -S copyparty; brew install copyparty ffmpeg | also Fedora, Gentoo ::guru, Nix and a NixOS module |
| Docker | copyparty/ac | see Docker and systemd below |
| Phones | Termux on Android, a-Shell on iOS | serve the phone’s storage on the LAN |
| Optional feature | Install |
|---|---|
| image thumbnails | Pillow, or pyvips, or ffmpeg |
| video and audio thumbs, transcoding | ffmpeg + ffprobe in PATH |
| music tags | mutagen, or ffprobe |
| FTPS (TLS) | pyftpdlib + pyopenssl |
| SFTP | paramiko |
| hashed passwords | argon2-cffi |
| HEIF, AVIF, JPEG XL | pyvips or ffmpeg |
| SMB (not advised) | impacket==0.13.0 |
| Handy flag | Does |
|---|---|
| –deps | lists the optional dependencies it found |
| –exit cfg | parses the config, prints volumes and permissions, exits |
| –vc | explains how the config file was parsed |
| –cgen | turns the current arguments into a config file |
| –qr | prints a QR code of the URL on startup |
| –help-flags | every volflag; also –help-accounts, –help-auth, –help-idp |
| /?h | login page and control panel in the browser |
# Debian: thumbnails and tags sudo apt install --no-install-recommends python3-pil ffmpeg # share /mnt/music read-only for all, /srv/inc writable by ed, index files and tags python3 copyparty-sfx.py -e2dsa -e2ts -a ed:hunter2 \ -v /mnt/music:music:r -v /srv/inc:inc:rw,ed # the same as a config file, which is the better habit python3 copyparty-sfx.py -c party.conf PRTY_CONFIG=party.conf python3 copyparty-sfx.py
CONF
The config file
Not quite YAML. Any –help option works in [global] without its dashes; accounts, groups and one section per volume follow. This example was parsed with –exit cfg on v1.20.26.
party.conf
[global]
p: 3923
e2dsa, e2ts # index files, then media tags
shr: /share # enable share links
no-robots, force-js
df: 4g # keep 4 GiB free on every volume
[accounts]
ed: hunter2 # user: password
kim: correcthorse
[groups]
admins: ed
[/] # URL path
/srv/pub # folder on disk
accs:
r: * # anyone may browse and download
A: @admins # admins get everything
[/inc]
/srv/inc
accs:
wG: * # anyone may upload and gets a secret link back
rwmd: ed, kim
flags:
nodupe, fk: 8 # reject dupes, 8-character filekeys
sz: 1k-2g # allowed upload size
lifetime: 604800
[/music]
/mnt/music
accs:
r: @acct # every logged-in user
[/private] # hides /srv/pub/private
//NULL # shadowed: never reachable| Rule | Detail |
|---|---|
| Comments | an inline comment needs two spaces before the # |
| Several options per line | comma-separated, as in e2dsa, e2ts; only the last one on the line may take a value |
| Volume section | [/url], then the folder path on the next line, then accs: and optional flags: |
| Several files | -c can repeat; in Docker every *.conf in /cfg is loaded |
| Environment variables | ${VAR} is expanded by default; the old $VAR form stops startup (see –env-expand) |
| Reload | systemctl reload copyparty, signal USR1, or the reload button for users with a; changes in [global] need a restart |
| Conflicts | the config file wins over command-line arguments |
ACCS
Accounts, groups and permission letters
fig 2 · permissions live on volumes, not folders; to restrict a subfolder, mount a volume on it
| Letter | Grants | Note |
|---|---|---|
| r | browse, download, zip and tar, see filekeys and dirkeys | the usual read access |
| w | upload, move or copy files into the folder | needs r to see the uploads |
| m | move files and folders out of the folder | needs w at the destination |
| d | delete permanently | also needed for overwrite and for u2c.py sync |
| g | download a file by exact URL; no listing, no zip | pair with filekeys so names cannot be guessed |
| G | g, and uploaders see the filekeys of their own uploads | wG is a drop box with receipts |
| h | g, but a folder returns its index.html | a classic web server with listings off |
| . | may ask to see dotfiles in listings | per user, unlike the dots volflag |
| a | admin: upload times and uploader IPs, config reload | not the same as A |
| A | everything: rwmda. | owners only |
| Who | Means |
|---|---|
| * | everyone, logged in or not |
| ed, kim | named users |
| @admins | a group from [groups] or –grp |
| @acct | every user with an account (rename with –grp-all) |
| *,-@acct | only people who are not logged in |
| @admins,-james | a group minus one user |
| Recipe | accs |
|---|---|
| public, owner edits | r: * / A: ed |
| blind drop box | w: * |
| drop box with links | wG: * + flags fk: 8 |
| private folder | rw: ed |
| static site | h: * |
| readers who see dotfiles | r.: ed |
# command-line form: -v src:dst:perm,user:perm,user:c,volflag
copyparty -a u1:p1 -a u2:p2 -a u3:p3 \
-v /mnt/music:music:r,u1,u2:rw,u3 \
-v /mnt/inc:inc:w,u1:rm,u2 \
-v /mnt/ss:i:rw,u1:g:c,fk=4Password only By default a login is just a password, and the account is found by it. Turn on –usernames to require user:password, and then hash with that form too.
VFS
Volumes, shadowing, dotfiles, symlinks
| Topic | How it works | Control |
|---|---|---|
| Mapping | each volume maps a URL path to a folder; a deeper volume replaces the folder it sits on | one [/url] section or -v each |
| Shadowing | a volume with no accs, or mapped to //NULL, hides that subfolder entirely; files can be volumes too | unsafe on case-insensitive filesystems (Windows, macOS, FAT32, exFAT); trust it only when the startup log shows casechk:n |
| Dotfiles | hidden from listings, still reachable by exact name | -ed, volflag dots, letter .; in search only with dotsrch |
| Symlinks out of a volume | followed by default | xvol stops it, xdev stays on one filesystem; –ls ‘**,*,ln,p,r’ checks at startup |
| Missing folder | created on startup | nospawn warns instead, assert_root refuses to start |
| State per volume | a .hist folder holds up2k.db, thumbnails and unfinished uploads | hist: /var/cache/cpp, or /cfg/hists/ in Docker |
| Server state | sessions, shares, IdP cache, salts, certificates, SFTP host keys | under $XDG_CONFIG_HOME/copyparty; keep it private and backed up |
FLAG
Volflags that matter
Per-volume options. On the command line append :c,flag or :c,flag=value to a -v; in a config file list them under flags:. A flag set in [global] applies to every volume; -flag removes it from one. The full list is in –help-flags.
| Group | Volflag | Does |
|---|---|---|
| upload | nodupe, nodupem | reject a file that already exists in the volume (and on moves) |
| upload | dedup, hardlink, hardlinkonly, reflink | store duplicates as symlinks, hardlinks or reflinks instead of copies |
| upload | sz=1k-3m, df=4g | allowed file size; free space to keep |
| upload | vmaxb=1g, vmaxn=4k | cap the volume’s total size or file count (needs e2ds) |
| upload | maxn=250,3600, maxb=1g,300 | per-IP limits: files per window, bytes per window (seconds) |
| upload | nosub, rotn=1000,2, rotf=%Y/%m/%d | no uploads into subfolders; spread uploads into numbered or dated folders |
| upload | lifetime=3600 | uploads delete themselves after that many seconds |
| upload | rand, nrand=12 | random file names |
| upload | u2ow=0|1|2, u2ts=c|u | overwrite never, if newer, always; keep the client’s mtime or use upload time |
| upload | chmod_f=644, chmod_d=755, uid, gid | mode and owner of new files and folders |
| db | e2d, e2ds, e2dsa | database on; scan writable folders; scan all folders at startup |
| db | e2t, e2ts, d2t | media tags on; scan existing files; tags off for this volume |
| db | scan=60 | rescan for outside changes every 60 seconds |
| db | nohash=\.iso$, noidx=\.iso$ | skip hashing, or skip indexing entirely, for matching paths |
| db | dbd=acid|swal|wal|yolo | database durability against speed; wal is the default |
| db | forget_ip=43200, no_db_ip | drop uploader IPs after N minutes, or never store them (kills unpost) |
| access | fk=8, fka=8 | per-file access keys in URLs, required with g; fka survives edits |
| access | dk, dks, dky | per-folder access keys; dks lets the key open subfolders |
| access | dots, dotsrch | everyone with r may show dotfiles; dotfiles appear in search |
| access | zip_who=2, zipmaxs=2g, zipmaxn=9k | who may download as zip or tar, and how much |
| access | shr_who=no|a|auth, unp_who=1 | who may create shares; how unpost matches the uploader |
| safety | nohtml, noscript | serve HTML and SVG as text, or block their scripts with CSP |
| safety | dthumb, dvthumb, dathumb | no thumbnails at all, for video, for audio |
| safety | xvol, xdev | do not follow symlinks out of the volume or onto other filesystems |
| safety | no_readme, no_logues | do not render uploaded README.md or .prologue/.epilogue.html |
| safety | norobots, davauth | ask crawlers to stay away; make WebDAV clients log in everywhere |
| ux | grid, sort, html_head, og | grid view by default, sort order, extra head HTML, Discord-style embeds |
| hooks | xau=CMD, xbu, xbd, xiu, xban | run a script after or before upload, delete, idle, ban |
UP
Uploads
Drag files or folders onto the page, or paste with Ctrl-V. The default uploader, up2k, hashes each file in chunks first, asks the server what is missing, then sends chunks in parallel and has every one verified. Restarting the server mid-upload is safe.
fig 3 · no size limit even behind a proxy that caps request size, and a server restart mid-upload is safe
| Uploader | Strengths | Limits |
|---|---|---|
| up2k (web, default) | folders, resume after any break, dedup before sending, preserves mtime, parallel chunks, no size limit | reads each file twice (hash, then send) |
| bup (basic uploader) | works in nearly any browser | one request per file, no resume |
| u2c.py | up2k from the command line; resume, search, one-way sync with –dr | Python on the client |
| PUT and POST | curl, wget, ShareX, scripts | no resume; respects proxy body limits |
| Server option | Effect |
|---|---|
| –u2sz 64,96 | target and max POST in MiB; 96 keeps under Cloudflare’s limit |
| –u2j 2 | chunks in flight per browser; 2 to 6 across oceans |
| –u2ow 2 | overwrite by default (users still need d) |
| –unpost 43200 | uploaders may undo their uploads for 12 h (needs -e2d) |
| –snap-drop 1440 | forget unfinished uploads after 24 h |
| –dotpart | hide files from listings until they finish |
| –df 4 | refuse uploads that would leave less than 4 GiB free |
| Dedup mode | Trade-off |
|---|---|
| dedup | symlinks; break if anything but copyparty moves the files |
| hardlink | look like normal files, but editing one edits every copy |
| hardlinkonly | as hardlink; full copy instead of a symlink when impossible |
| reflink | btrfs, ZFS, XFS: safest, copies are independent |
| –redup sym=hard | converts existing dupes; try –redup-dry first |
| Feature | How |
|---|---|
| Unpost | the unpost tab lists your recent uploads to delete or abort; matched by IP and account (–unp-who) |
| Self-destruct | volflag lifetime sets the maximum; uploaders may choose shorter in the UI |
| Race the beam | others can download a file while it is still arriving through up2k (nopipe turns it off) |
| File search | drop files on the Search zone: they are hashed locally and looked up, nothing is uploaded |
| Append | ?apnd on a PUT appends to an existing file; who may is –apnd-who (default delete + write) |
IDX
Indexing, search and media
| Option | Effect | Note |
|---|---|---|
| -e2d | upload database: search, unpost, dedup | knows only what arrives through copyparty |
| -e2ds, -e2dsa | also scan writable, or all, folders at startup | -e2dsa is the usual choice |
| -e2t, -e2ts, -e2tsr | media tags; scan existing files; wipe and rescan tags | mutagen is safer, ffprobe finds more |
| -e2v | rehash every file and compare with the database | -e2vu updates, -e2vp panics on mismatch |
| –re-maxage 3600 | rescan for outside changes every hour | volflag scan |
| –no-hash, –no-idx | regex of paths to skip hashing or indexing | one big regex, not repeated |
| –hist /var/cache/cpp | databases and thumbnails outside the volumes | good for read-only media |
| –dbd wal | durability profile: acid, swal, wal, yolo | yolo can lose the whole database on power loss |
| -mte, -mth, -mtp | tags to index, tags hidden by default, tag plugins | bpm and musical key with the dj Docker image |
| –no-thumb, –th-size 320×256 | thumbnails off; thumbnail size | Pillow for images, FFmpeg for video and audio |
| –srch-time 45, –srch-hits 7999 | search deadline and result cap | –srch-icase for full Unicode case folding |
NET
Protocols and ports
Every protocol enforces the same volumes and letters. Only HTTP and WebDAV are on by default; the rest need a flag and sometimes a package.
| Protocol | Enable | Port | Notes |
|---|---|---|---|
| HTTP, HTTPS | on; -p 3923 | 3923 tcp | both on one port; –http-only or –https-only; HTTP/1.1 only, so put HTTP/2 and real certificates on a proxy |
| WebDAV | on; –no-dav | same as HTTP | –daw lets PUT overwrite (risky, prefer the volflag); –dav-auth for davfs2; needs d to overwrite |
| FTP, FTPS | –ftp 3921, –ftps 3990 | tcp + passive range | passive ports with –ftp-pr 12000-12099, NAT with –ftp-nat; run v1.20.19 or later |
| SFTP | –sftp 3922 | 3922 tcp | needs paramiko; SSH keys with –sftp-key ‘ed ssh-ed25519 AAAA…’; passwords only with –sftp-pw |
| TFTP | –tftp 3969 | 3969 or 69 udp | primitive access control; for PXE and network gear on a trusted LAN |
| SMB | –smb (+ –smbw) | 445 tcp | dangerous read-only by default; refuses to start without –hack-me-bro; not with hashed passwords; never on the internet |
| Zeroconf | -z (–zm, –zs) | 5353, 1900 udp | mDNS for Linux and macOS, SSDP for Windows; limit with –z-on eth0 |
| OPDS, RSS | –opds, volflag rss | HTTP | e-book readers; ?rss feeds of folders |
| WOPI | –wopi –wopi-url URL | HTTP | edit office files in Collabora Online and similar |
| Metrics | –stats | HTTP | OpenMetrics at /.cpr/metrics for admins or –stats-u |
# open only what you enabled; this is everything
firewall-cmd --permanent --add-port={80,443,3921,3922,3923,3945,3990}/tcp
firewall-cmd --permanent --add-port=12000-12099/tcp
firewall-cmd --permanent --add-port={69,1900,3969,5353}/udp
firewall-cmd --reloadAUTH
Logins, password hashing, SSO and IP rules
| Send the password as | Example |
|---|---|
| login page | https://fs.example.com/?h |
| header | PW: hunter2 |
| URL parameter | ?pw=hunter2 |
| basic auth | https://ed:hunter2@host/ |
| cookie | cppwd=hunter2 |
| with –usernames | PW: ed:hunter2 |
| Option | Does |
|---|---|
| –ah-alg argon2 | hashed passwords; needs argon2-cffi; about 0.4 s and 256 MiB per check |
| –ah-gen PW, –ah-cli | print a hash (starts with +), or hash interactively |
| –show-ah-salt | print the salt, so hashes made elsewhere match the service |
| –logout 8086 | idle hours before a session ends (default about a year) |
| –chpw | users may change their own passwords |
| –no-bauth, –bauth-last | refuse basic auth, or let a cookie win over it |
| Identity source | Options | Rule |
|---|---|---|
| IdP header (Authelia, authentik, oauth2-proxy) | –idp-h-usr remote-user –idp-h-grp remote-groups | the proxy must strip any client copy of these headers; add a secret header and –idp-h-key |
| Mapped header (Tailscale) | –idp-hm-usr ^Tailscale-User-Login^[email protected]^alice | one mapping per user |
| IdP buttons | –idp-login /idp/login/?redir={dst}, –idp-logout | login and logout links go to the IdP |
| IdP volumes | [/u/${u}] with rwmda: ${u}; [/lounge/${g}] | a home folder per user and a shared one per group, created on first visit; read docs/idp.md before relying on them |
| IP to user | –ipu 192.168.123.0/24=spartacus | auto-login by subnet; null-map the proxy IP: –ipu 172.24.27.9/32= |
| User only from | –ipr 10.0.0.0/8=ed | ed is refused from anywhere else |
| Whole server only from | –ipa lan, or –ipar behind a proxy | –ipa sees the TCP address, –ipar the forwarded one |
| Precedence | –auth-ord idp,ipu | first match wins; add pw to let a password override the IdP |
| Ban rule | Default N,W,B | Meaning |
|---|---|---|
| –ban-pw | 9,60,1440 | more than 9 wrong passwords in 60 minutes: banned for a day |
| –ban-404 | 50,60,1440 | 404 floods, only for users with g, G or h |
| –ban-403, –ban-422 | 9,2,1440 | forbidden or malformed requests in quick succession |
| –ban-url | 9,2,1440 | scanner URLs such as .php and wp-admin, for users with g, G or h |
| –dont-ban | no | exempt a level: av, aa, rw, auth or any |
# hash once, paste the +... value into [accounts], add ah-alg: argon2 to [global]
python3 -m pip install --user argon2-cffi
copyparty --ah-alg argon2 --ah-gen hunter2RP
Behind a reverse proxy
The recommended way to serve copyparty on the internet: the proxy does TLS and HTTP/2, copyparty listens on a unix socket, and the real client IP arrives in a header copyparty trusts only from the proxy. Bans, unpost and IP rules all depend on that IP.
fig 4 · the proxy terminates TLS and speaks HTTP/2; copyparty sees the real client through the header it trusts
| Option | Default | Set it to |
|---|---|---|
| -i | :: | unix:770:www:/dev/shm/party.sock (group www can connect), or 127.0.0.1 |
| –xff-hdr | x-forwarded-for | x-real-ip from nginx, cf-connecting-ip behind Cloudflare |
| –rproxy | 9999999 | 1 when the header holds one IP; -1, -2 to count hops from the right in a chain; 0 only when no proxy at all |
| –xff-src | 127.0.0.0/8, ::1/128 | the proxy’s address, or lan; any only behind Cloudflare with an IP allowlist at the edge |
| –rp-loc | empty | /files when proxied on a subpath instead of its own (sub)domain |
| –xf-host, –xf-proto | x-forwarded-host, -proto | keep, and make the proxy send them |
| –site | empty | https://fs.example.com/ for correct links in shares and hooks |
/etc/nginx/conf.d/copyparty.conf (trimmed from contrib/nginx)
upstream cpp_uds {
server unix:/dev/shm/party.sock fail_timeout=1s;
keepalive 1;
}
server {
listen 443 ssl;
server_name fs.example.com;
location / {
proxy_pass http://cpp_uds;
proxy_redirect off;
proxy_http_version 1.1;
proxy_buffering off;
proxy_request_buffering off;
proxy_set_header Connection "Keep-Alive";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
client_max_body_size 1024M;
client_header_timeout 610m;
client_body_timeout 610m;
send_timeout 610m;| Proxy | Note |
|---|---|
| Speed ranking | haproxy, caddy, traefik, nginx, apache, lighttpd; unix sockets beat TCP by 5 to 10% |
| Caddy | caddy reverse-proxy –from :8080 –to unix///dev/shm/party.sock |
| Traefik | v3.6.7 or later (CVE-2025-66490); no unix socket support |
| Cloudflare tunnel | cloudflared tunnel –url http://127.0.0.1:3923, then –xff-hdr cf-connecting-ip; requests over 100 MiB fail, which up2k avoids; turn Rocket Loader off |
| SELinux (Fedora, RHEL) | setsebool -P httpd_can_network_connect 1 for TCP upstreams |
| Ports 80 and 443 without a proxy | setcap CAP_NET_BIND_SERVICE=+eip on the Python binary, or NAT 80 to 3923; never run as root |
OPS
Docker and systemd
| Image | Adds | Size |
|---|---|---|
| copyparty/min | copyparty only | 57 MiB |
| copyparty/im | Pillow thumbnails, mutagen tags | 70 MiB |
| copyparty/ac | + FFmpeg: video and audio thumbs, transcoding recommended | 163 MiB |
| copyparty/iv | + vips for more image formats | 211 MiB |
| copyparty/dj | + bpm and musical key detection | 309 MiB |
| Container rule | Detail |
|---|---|
| /w | shared folder; mount your data below it |
| /cfg | every *.conf is loaded |
| -u 1000 | run as your user; drop it on rootless podman |
| :z | append to every -v on SELinux hosts |
| hist: /cfg/hists/ | keep databases and thumbnails out of the data |
| Registry | Docker Hub, or ghcr.io/9001/copyparty-ac |
docker run --rm -it -u 1000 -p 3923:3923 \ -v /mnt/nas:/w -v $PWD/cfgdir:/cfg copyparty/ac
/etc/systemd/system/copyparty.service (key lines from contrib/systemd)
[Unit] Description=copyparty file server [Service] Type=notify ExecReload=/bin/kill -s USR1 $MAINPID User=copyparty Group=copyparty WorkingDirectory=/var/lib/copyparty Environment=XDG_CONFIG_HOME=/var/lib/copyparty/.config AmbientCapabilities=CAP_NET_BIND_SERVICE MemoryMax=50% ProtectKernelTunables=true ProtectProc=invisible RestrictNamespaces=true RestrictSUIDSGID=true ExecStart=/usr/bin/python3 /usr/local/bin/copyparty-sfx.py -c /etc/copyparty.conf [Install] WantedBy=multi-user.target
More isolation prisonparty.sh runs copyparty in a small chroot and bubbleparty.sh in bubblewrap; both ship in the repository’s bin folder, with a matching prisonparty unit in contrib.
SEC
Hardening
Three built-in safety profiles stack on each other. Start from -ss for anything reachable from the internet and add back only what you need.
| Profile | Turns on | Costs |
|---|---|---|
| -s | –dotpart –no-thumb –no-mtag-ff –no-robots –force-js | no thumbnails or transcoding, so FFmpeg, Pillow and vips never touch uploads |
| -ss | -s + –no-html –no-readme –no-logues –unpost=0 –no-del –no-mv –reflink –dav-auth –vague-403 -nih | no delete, move or unpost for anyone; HTML shown as text |
| -sss | -ss + –no-dav, logging to cpp-%Y-%m%d-%H%M%S.txt.xz, and –ls=**,*,ln,p,r | no WebDAV; refuses to start on dangerous symlinks |
| Control | How | Why |
|---|---|---|
| Never run without accounts on a network | -c party.conf | no arguments means read-write for everyone |
| Hash passwords, require usernames | –ah-alg argon2 –usernames | config leaks stop being password leaks; logins are not found by password alone |
| Untrusted uploads | volflags nohtml, d2t, dthumb; letters wG with fk | no XSS from uploaded HTML or SVG, no parsers on hostile files |
| Uploaded scripts in listings | –no-readme –no-logues, or –no-dot-ren | README.md and .epilogue.html run sandboxed scripts for visitors |
| Real client IPs | –xff-hdr, –xff-src, –rproxy | bans otherwise hit the proxy, and everyone |
| Know when you are vulnerable | –vc-url https://api.copyparty.eu/advisories | checks every 3 h, warns admins; –vc-exit stops the server |
| Sandbox FFmpeg | –th-bwrap CMD –use-bwrap y | off by default; usually impossible inside containers |
| Symlinks | xvol, xdev, –ls ‘**,*,ln,p,r’ | no escape from the volume through links or mounts |
| Shadowing on Windows or macOS | separate folders instead | case folding defeats it (GHSA-3c88-p299-7hvr, mitigated in 1.20.25) |
| LAN-only protocols | no –smb or –tftp on public hosts | SMB has known issues that will not be fixed |
| Keep CSRF protection | never –allow-csrf, –getmod, –cookie-lax | each lets other sites act as your users |
| Bound zip downloads | –zipmaxs 2g –zip-who 2 | one click cannot stream the whole server |
| Restrict reach | –ipa lan, –ipr CIDR=user | admin accounts usable only from known networks |
| Privacy | –forget-ip 43200 | uploader IPs dropped after 30 days |
| Logs on disk | -lo /var/log/copyparty/cpp-%Y-%m%d.txt.xz | evidence after an incident |
| Release | Date | Fixed |
|---|---|---|
| v1.18.5 | 2025-07-27 | XSS through a crafted link or a malicious audio file’s tags |
| v1.18.7 | 2025-07-30 | another XSS through a crafted URL |
| v1.19.8 | 2025-09-07 | CVE-2025-58753: a share of single files exposed the sibling files |
| v1.20.9 | 2026-02-25 | XSS through a crafted link |
| v1.20.17 | 2026-07-06 | a filekey could become a dirkey where both were on; CSP nonces arrive |
| v1.20.19 | 2026-07-27 | FTP and FTPS uploads outside the defined volumes |
| v1.20.25 | 2026-10-06 | shadowing bypass on case-insensitive filesystems (mitigated, not cured) |
CLI
Client tools and hotkeys
The control panel’s connect page, /?hc, generates ready commands for rclone, WebDAV mounts and u2c.py for your server.
# PUT keeps the name if the URL ends with a slash; POST with ?want=url returns a link curl -H pw:hunter2 -T movie.mkv https://fs.example.com/inc/ curl -H pw:hunter2 -F [email protected] 'https://fs.example.com/inc/?want=url' echo "backup done" | curl -H pw:hunter2 -T- 'https://fs.example.com/inc/log.txt?apnd' # u2c.py: resumable uploads, one-way sync (needs e2dsa and r, w, d), search U2C_PW=hunter2 python3 u2c.py https://fs.example.com/inc/ ./photos/ U2C_PW=hunter2 python3 u2c.py --dr https://fs.example.com/backup/ ./backup/ python3 u2c.py -s https://fs.example.com/ ./maybe-there.iso # rclone over WebDAV, then mount rclone config create cpp-rw webdav url=https://fs.example.com/ vendor=owncloud \ headers=Cookie,cppwd=hunter2 pacer_min_sleep=0.01ms rclone mount --vfs-cache-mode writes cpp-rw: ~/party
| Tool | Use |
|---|---|
| rclone (WebDAV) | fastest mount, read-write; also two-way sync |
| partyfuse.py | read-only FUSE mount, also of nginx and IIS listings |
| davfs2, Windows WebDAV | read-write mounts; davfs2 needs –dav-auth with mixed folders |
| PartyUP! | one-tap Android upload client (F-Droid); not a server |
| ShareX, ishare, Flameshot | screenshot upload configs in contrib |
| Checksum | replies carry a truncated base64 SHA-512 of the upload |
| Key | In the browser |
|---|---|
| ? | show all hotkeys |
| G, T, B | grid or list, thumbnails, navpane |
| I, K, M | previous, next, parent folder |
| Ctrl-X, Ctrl-C, Ctrl-V | cut, copy, paste (also across tabs) |
| F2, Ctrl-K, Y | rename, delete, download selection |
| Space, Ctrl-A | select file, select all |
| J, L, P, U, O | player: previous, next, play, skip back, forward |
FIX
Gotchas
| Symptom | Cause | Fix |
|---|---|---|
| “thank you for playing” | banned; behind a proxy usually the proxy’s IP | configure real-ip, then wait or restart; see –ban-* |
| Strangers can upload and delete | started without -v or a config | always run with accounts and volumes |
| Search finds nothing old | only -e2d: uploads indexed, existing files not | -e2dsa |
| vmaxb, vmaxn ignored | no filesystem index | add e2ds to the volume |
| Unpost tab empty | no database, older than 12 h, other IP or account | -e2d; check –unpost, –unp-who |
| Expired shares never vanish | no database | e2d on at least one volume |
| Password-protected shares stopped working | password hashing settings changed | recreate the shares |
| Logged-in users cannot see a public folder | accs *,-@acct | use * if that was not the intent |
| Large uploads fail through nginx | the default client_max_body_size of 1 MiB | raise it to 1024M as in the contrib config |
| “Looks like javascript is broken” | a proxy or CDN rewrites pages and breaks the CSP nonce | turn off Cloudflare Rocket Loader or the rewriting proxy feature |
| Editing one file changed its duplicates | hardlink dedup | reflink on btrfs, ZFS, XFS |
| Files vanished after moving them by hand | symlink dedup | move only through copyparty, or use hardlinks or reflinks |
| A shadowed folder is reachable on Windows | case-insensitive filesystem | do not rely on shadowing there |
| Config change ignored after reload | it was in [global] | restart instead |
| A value turned into part of a comment | one space before # | two spaces before inline comments |
| curl upload lost its file name | -T combined with URL parameters | send the password as a header and end the URL with / |
| davfs2 cannot open private folders | it does not answer the login prompt per folder | –dav-auth |
Checked against copyparty v1.20.26: –help, –help-flags, –help-accounts, –help-auth, –help-idp, –help-pwhash, –help-dedup, –help-dbd, the README, docs/changelog.md, docs/rclone.md, contrib/nginx, contrib/systemd and scripts/docker. The example config was parsed by the program itself.
copyparty Cheatsheet · REV 2026.10
© 2026 · BUB.IM · made in vim
0 comments