Home

Awesome

<img src="docs/logo.svg" width="250" align="right"/>

πŸ’ΎπŸŽ‰ copyparty

turn almost any device into a file server with resumable uploads/downloads using any web browser

πŸ‘‰ Get started! or visit the read-only demo server πŸ‘€ running from a basement in finland

πŸ“· screenshots: browser // upload // unpost // thumbnails // search // fsearch // zip-DL // md-viewer

🎬 videos: upload // cli-upload // race-the-beam

readme toc

quickstart

just run copyparty-sfx.py -- that's it! πŸŽ‰

enable thumbnails (images/audio/video), media indexing, and audio transcoding by installing some recommended deps:

running copyparty without arguments (for example doubleclicking it on Windows) will give everyone read/write access to the current folder; you may want accounts and volumes

or see some usage examples for inspiration, or the complete windows example

some recommended options:

at home

make it accessible over the internet by starting a cloudflare quicktunnel like so:

first download cloudflared and then start the tunnel with cloudflared tunnel --url http://127.0.0.1:3923

as the tunnel starts, it will show a URL which you can share to let anyone browse your stash or upload files to you

since people will be connecting through cloudflare, run copyparty with --xff-hdr cf-connecting-ip to detect client IPs correctly

on servers

you may also want these, especially on servers:

and remember to open the ports you want; here's a complete example including every feature copyparty has to offer:

firewall-cmd --permanent --add-port={80,443,3921,3923,3945,3990}/tcp  # --zone=libvirt
firewall-cmd --permanent --add-port=12000-12099/tcp  # --zone=libvirt
firewall-cmd --permanent --add-port={69,1900,3969,5353}/udp  # --zone=libvirt
firewall-cmd --reload

(69:tftp, 1900:ssdp, 3921:ftp, 3923:http/https, 3945:smb, 3969:tftp, 3990:ftps, 5353:mdns, 12000:passive-ftp)

features

also see comparison to similar software

PS: something missing? post any crazy ideas you've got as a feature request or discussion πŸ€™

testimonials

small collection of user feedback

good enough, surprisingly correct, certified good software, just works, why, wow this is better than nextcloud

motivations

project goals / philosophy

notes

general notes:

browser-specific:

server-os-specific:

server notes:

bugs

roughly sorted by chance of encounter

if you have a new exciting bug to share, see reporting bugs

not my bugs

same order here too

breaking changes

upgrade notes

FAQ

"frequently" asked questions

accounts and volumes

per-folder, per-user permissions - if your setup is getting complex, consider making a config file instead of using arguments

a quick summary can be seen using --help-accounts

configuring accounts/volumes with arguments:

permissions:

examples:

anyone trying to bruteforce a password gets banned according to --ban-pw; default is 24h ban for 9 failed attempts in 1 hour

shadowing

hiding specific subfolders by mounting another volume on top of them

for example -v /mnt::r -v /var/empty:web/certs:r mounts the server folder /mnt as the webroot, but another volume is mounted at /web/certs -- so visitors can only see the contents of /mnt and /mnt/web (at URLs / and /web), but not /mnt/web/certs because URL /web/certs is mapped to /var/empty

dotfiles

unix-style hidden files/folders by starting the name with a dot

anyone can access these if they know the name, but they normally don't appear in directory listings

a client can request to see dotfiles in directory listings if global option -ed is specified, or the volume has volflag dots, or the user has permission .

dotfiles do not appear in search results unless one of the above is true, and the global option / volflag dotsrch is set

the browser

accessing a copyparty server using a web-browser

copyparty-browser-fs8

tabs

the main tabs in the ui

hotkeys

the browser has the following hotkeys (always qwerty)

navpane

switching between breadcrumbs or navpane

click the 🌲 or pressing the B hotkey to toggle between breadcrumbs path (default), or a navpane (tree-browser sidebar thing)

thumbnails

press g or η”° to toggle grid-view instead of the file listing and t toggles icons / thumbnails

copyparty-thumbs-fs8

it does static images with Pillow / pyvips / FFmpeg, and uses FFmpeg for video files, so you may want to --no-thumb or maybe just --no-vthumb depending on how dangerous your users are

audio files are covnerted into spectrograms using FFmpeg unless you --no-athumb (and some FFmpeg builds may need --th-ff-swr)

images with the following names (see --th-covers) become the thumbnail of the folder they're in: folder.png, folder.jpg, cover.png, cover.jpg

enabling multiselect lets you click files to select them, and then shift-click another file for range-select

zip downloads

download folders (or file selections) as zip or tar files

select which type of archive you want in the [βš™οΈ] config tab:

nameurl-suffixdescription
tar?tarplain gnutar, works great with curl | tar -xv
pax?tar=paxpax-format tar, futureproof, not as fast
tgz?tar=gzgzip compressed gnu-tar (slow), for curl | tar -xvz
txz?tar=xzgnu-tar with xz / lzma compression (v.slow)
zip?zip=utf8works everywhere, glitchy filenames on win7 and older
zip_dos?ziptraditional cp437 (no unicode) to fix glitchy filenames
zip_crc?zip=crccp437 with crc32 computed early for truly ancient software

you can also zip a selection of files or folders by clicking them in the browser, that brings up a selection editor and zip button in the bottom right

copyparty-zipsel-fs8

cool trick: download a folder by appending url-params ?tar&opus or ?tar&mp3 to transcode all audio files (except aac|m4a|mp3|ogg|opus|wma) to opus/mp3 before they're added to the archive

uploading

drag files/folders into the web-browser to upload

dragdrop is the recommended way, but you may also:

when uploading files through dragdrop or CTRL-V, this initiates an upload using up2k; there are two browser-based uploaders available:

NB: you can undo/delete your own uploads with [🧯] unpost (and this is also where you abort unfinished uploads, but you have to refresh the page first)

up2k has several advantages:

it is perfectly safe to restart / upgrade copyparty while someone is uploading to it!
all known up2k clients will resume just fine πŸ’ͺ

see up2k for details on how it works, or watch a demo video

copyparty-upload-fs8

protip: you can avoid scaring away users with contrib/plugins/minimal-up2k.js which makes it look much simpler

protip: if you enable favicon in the [βš™οΈ] settings tab (by typing something into the textbox), the icon in the browser tab will indicate upload progress -- also, the [πŸ””] and/or [πŸ”Š] switches enable visible and/or audible notifications on upload completion

the up2k UI is the epitome of polished inutitive experiences:

and then theres the tabs below it,

note that since up2k has to read each file twice, [🎈] bup can theoretically be up to 2x faster in some extreme cases (files bigger than your ram, combined with an internet connection faster than the read-speed of your HDD, or if you're uploading from a cuo2duo)

if you are resuming a massive upload and want to skip hashing the files which already finished, you can enable turbo in the [βš™οΈ] config tab, but please read the tooltip on that button

file-search

dropping files into the browser also lets you see if they exist on the server

copyparty-fsearch-fs8

when you drag/drop files into the browser, you will see two dropzones: Upload and Search

on a phone? toggle the [πŸ”Ž] switch green before tapping the big yellow Search button to select your files

the files will be hashed on the client-side, and each hash is sent to the server, which checks if that file exists somewhere

files go into [ok] if they exist (and you get a link to where it is), otherwise they land in [ng]

unpost

undo/delete accidental uploads

copyparty-unpost-fs8

you can unpost even if you don't have regular move/delete access, however only for files uploaded within the past --unpost seconds (default 12 hours) and the server must be running with -e2d

self-destruct

uploads can be given a lifetime, afer which they expire / self-destruct

the feature must be enabled per-volume with the lifetime upload rule which sets the upper limit for how long a file gets to stay on the server

clients can specify a shorter expiration time using the up2k ui -- the relevant options become visible upon navigating into a folder with lifetimes enabled -- or by using the life upload modifier

specifying a custom expiration time client-side will affect the timespan in which unposts are permitted, so keep an eye on the estimates in the up2k ui

race the beam

download files while they're still uploading (demo video) -- it's almost like peer-to-peer

requires the file to be uploaded using up2k (which is the default drag-and-drop uploader), alternatively the command-line program

file manager

cut/paste, rename, and delete files/folders (if you have permission)

file selection: click somewhere on the line (not the link itsef), then:

you can move files across browser tabs (cut in one tab, paste in another)

shares

share a file or folder by creating a temporary link

when enabled in the server settings (--shr), click the bottom-right share button to share the folder you're currently in, or alternatively:

this feature was made with identity providers in mind -- configure your reverseproxy to skip the IdP's access-control for a given URL prefix and use that to safely share specific files/folders sans the usual auth checks

when creating a share, the creator can choose any of the following options:

semi-intentional limitations:

specify --shr /foobar to enable this feature; a toplevel virtual folder named foobar is then created, and that's where all the shares will be served from

users can delete their own shares in the controlpanel, and a list of privileged users (--shr-adm) are allowed to see and/or delet any share on the server

after a share has expired, it remains visible in the controlpanel for --shr-rt minutes (default is 1 day), and the owner can revive it by extending the expiration time there

security note: using this feature does not mean that you can skip the accounts and volumes section -- you still need to restrict access to volumes that you do not intend to share with unauthenticated users! it is not sufficient to use rules in the reverseproxy to restrict access to just the /share folder.

batch rename

select some files and press F2 to bring up the rename UI

batch-rename-fs8

quick explanation of the buttons,

advanced mode: rename files based on rules to decide the new names, based on the original name (regex), or based on the tags collected from the file (artist/title/...), or a mix of both

in advanced mode,

available functions:

so,

say you have a file named meganeko - Eclipse - 07 Sirius A.mp3 (absolutely fantastic album btw) and the tags are: Album:Eclipse, Artist:meganeko, Title:Sirius A, tn:7

you could use just regex to rename it:

or you could use just tags:

or a mix of both:

the metadata keys you can use in the format field are the ones in the file-browser table header (whatever is collected with -mte and -mtp)

media player

plays almost every audio format there is (if the server has FFmpeg installed for on-demand transcoding)

the following audio formats are usually always playable, even without FFmpeg: aac|flac|m4a|mp3|ogg|opus|wav

some hilights:

click the play link next to an audio file, or copy the link target to share it (optionally with a timestamp to start playing from, like that example does)

open the [🎺] media-player-settings tab to configure it,

audio equalizer

and dynamic range compressor

can also boost the volume in general, or increase/decrease stereo width (like crossfeed just worse)

has the convenient side-effect of reducing the pause between songs, so gapless albums play better with the eq enabled (just make it flat)

not available on iPhones / iPads because AudioContext currently breaks background audio playback on iOS (15.7.8)

fix unreliable playback on android

due to phone / app settings, android phones may randomly stop playing music when the power saver kicks in, especially at the end of an album -- you can fix it by disabling power saving in the app settings of the browser you use for music streaming (preferably a dedicated one)

markdown viewer

and there are two editors

copyparty-md-read-fs8

there is a built-in extension for inline clickable thumbnails;

other notes,

markdown vars

dynamic docs with serverside variable expansion to replace stuff like {{self.ip}} with the client's IP, or {{srv.htime}} with the current time on the server

see ./srv/expand/ for usage and examples

other tricks

searching

search by size, date, path/name, mp3-tags, ...

copyparty-search-fs8

when started with -e2dsa copyparty will scan/index all your files. This avoids duplicates on upload, and also makes the volumes searchable through the web-ui:

path/name queries are space-separated, AND'ed together, and words are negated with a - prefix, so for example:

the raw field allows for more complex stuff such as ( tags like *nhato* or tags like *taishi* ) and ( not tags like *nhato* or not tags like *taishi* ) which finds all songs by either nhato or taishi, excluding collabs (terrible example, why would you do that)

for the above example to work, add the commandline argument -e2ts to also scan/index tags from music files, which brings us over to:

server config

using arguments or config files, or a mix of both:

NB: as humongous as this readme is, there is also a lot of undocumented features. Run copyparty with --help to see all available global options; all of those can be used in the [global] section of config files, and everything listed in --help-flags can be used in volumes as volflags.

zeroconf

announce enabled services on the LAN (pic) -- -z enables both mdns and ssdp

mdns

LAN domain-name and feature announcer

uses multicast dns to give copyparty a domain which any machine on the LAN can use to access it

all enabled services (webdav, ftp, smb) will appear in mDNS-aware file managers (KDE, gnome, macOS, ...)

the domain will be http://partybox.local if the machine's hostname is partybox unless --name specifies soemthing else

ssdp

windows-explorer announcer

uses ssdp to make copyparty appear in the windows file explorer on all machines on the LAN

doubleclicking the icon opens the "connect" page which explains how to mount copyparty as a local filesystem

if copyparty does not appear in windows explorer, use --zsv to see why:

qr-code

print a qr-code (screenshot) for quick access, great between phones on android hotspots which keep changing the subnet

it uses the server hostname if mdns is enbled, otherwise it'll use your external ip (default route) unless --qri specifies a specific ip-prefix or domain

ftp server

an FTP server can be started using --ftp 3921, and/or --ftps for explicit TLS (ftpes)

some recommended FTP / FTPS clients; wark = example password:

webdav server

with read-write support, supports winXP and later, macos, nautilus/gvfs ... a greay way to access copyparty straight from the file explorer in your OS

click the connect button in the control-panel to see connection instructions for windows, linux, macos

general usage:

on macos, connect from finder:

in order to grant full write-access to webdav clients, the volflag daw must be set and the account must also have delete-access (otherwise the client won't be allowed to replace the contents of existing files, which is how webdav works)

connecting to webdav from windows

using the GUI (winXP or later):

known client bugs:

tftp server

a TFTP server (read/write) can be started using --tftp 3969 (you probably want ftp instead unless you are actually communicating with hardware from the 90s (in which case we should definitely hang some time))

that makes this the first RTX DECT Base that has been updated using copyparty πŸŽ‰

most clients expect to find TFTP on port 69, but on linux and macos you need to be root to listen on that. Alternatively, listen on 3969 and use NAT on the server to forward 69 to that port;

some recommended TFTP clients:

smb server

unsafe, slow, not recommended for wan, enable with --smb for read-only or --smbw for read-write

click the connect button in the control-panel to see connection instructions for windows, linux, macos

dependencies: python3 -m pip install --user -U impacket==0.11.0

some BIG WARNINGS specific to SMB/CIFS, in decreasing importance:

and some minor issues,

known client bugs:

the smb protocol listens on TCP port 445, which is a privileged port on linux and macos, which would require running copyparty as root. However, this can be avoided by listening on another port using --smb-port 3945 and then using NAT on the server to forward the traffic from 445 to there;

authenticate with one of the following:

browser ux

tweaking the ui

see ./docs/rice for more, including how to add stuff (css/<meta>/...) to the html <head> tag, or to add your own translation

opengraph

discord and social-media embeds

can be enabled globally with --og or per-volume with volflag og

note that this disables hotlinking because the opengraph spec demands it; to sneak past this intentional limitation, you can enable opengraph selectively by user-agent, for example --og-ua '(Discord|Twitter|Slack)bot' (or volflag og_ua)

you can also hotlink files regardless by appending ?raw to the url

NOTE: because discord (and maybe others) strip query args such as ?raw in opengraph tags, any links which require a filekey or dirkey will not work

if you want to entirely replace the copyparty response with your own jinja2 template, give the template filepath to --og-tpl or volflag og_tpl (all members of HttpCli are available through the this object)

file indexing

enables dedup and music search ++

file indexing relies on two database tables, the up2k filetree (-e2d) and the metadata tags (-e2t), stored in .hist/up2k.db. Configuration can be done through arguments, volflags, or a mix of both.

through arguments:

the same arguments can be set as volflags, in addition to d2d, d2ds, d2t, d2ts, d2v for disabling:

note:

exclude-patterns

to save some time, you can provide a regex pattern for filepaths to only index by filename/path/size/last-modified (and not the hash of the file contents) by setting --no-hash \.iso$ or the volflag :c,nohash=\.iso$, this has the following consequences:

similarly, you can fully ignore files/folders using --no-idx [...] and :c,noidx=\.iso$

if you set --no-hash [...] globally, you can enable hashing for specific volumes using flag :c,nohash=

filesystem guards

avoid traversing into other filesystems using --xdev / volflag :c,xdev, skipping any symlinks or bind-mounts to another HDD for example

and/or you can --xvol / :c,xvol to ignore all symlinks leaving the volume's top directory, but still allow bind-mounts pointing elsewhere

these options will reduce performance; unlikely worst-case estimates are 14% reduction for directory listings, 35% for download-as-tar

as of copyparty v1.7.0 these options also prevent file access at runtime -- in previous versions it was just hints for the indexer

periodic rescan

filesystem monitoring; if copyparty is not the only software doing stuff on your filesystem, you may want to enable periodic rescans to keep the index up to date

argument --re-maxage 60 will rescan all volumes every 60 sec, same as volflag :c,scan=60 to specify it per-volume

uploads are disabled while a rescan is happening, so rescans will be delayed by --db-act (default 10 sec) when there is write-activity going on (uploads, renames, ...)

upload rules

set upload rules using volflags, some examples:

you can also set transaction limits which apply per-IP and per-volume, but these assume -j 1 (default) otherwise the limits will be off, for example -j 4 would allow anywhere between 1x and 4x the limits you set depending on which processing node the client gets routed to

notes:

compress uploads

files can be autocompressed on upload, either on user-request (if config allows) or forced by server-config

things to note,

some examples,

other flags

database location

in-volume (.hist/up2k.db, default) or somewhere else

copyparty creates a subfolder named .hist inside each volume where it stores the database, thumbnails, and some other stuff

this can instead be kept in a single place using the --hist argument, or the hist= volflag, or a mix of both:

note:

metadata from audio files

set -e2t to index tags on upload

-mte decides which tags to index and display in the browser (and also the display order), this can be changed per-volume:

if you add/remove a tag from mte you will need to run with -e2tsr once to rebuild the database, otherwise only new files will be affected

but instead of using -mte, -mth is a better way to hide tags in the browser: these tags will not be displayed by default, but they still get indexed and become searchable, and users can choose to unhide them in the [βš™οΈ] config pane

-mtm can be used to add or redefine a metadata mapping, say you have media files with foo and bar tags and you want them to display as qux in the browser (preferring foo if both are present), then do -mtm qux=foo,bar and now you can -mte artist,title,qux

tags that start with a . such as .bpm and .dur(ation) indicate numeric value

see the beautiful mess of a dictionary in mtag.py for the default mappings (should cover mp3,opus,flac,m4a,wav,aif,)

--no-mutagen disables Mutagen and uses FFprobe instead, which...

--mtag-to sets the tag-scan timeout; very high default (60 sec) to cater for zfs and other randomly-freezing filesystems. Lower values like 10 are usually safe, allowing for faster processing of tricky files

file parser plugins

provide custom parsers to index additional tags, also see ./bin/mtag/README.md

copyparty can invoke external programs to collect additional metadata for files using mtp (either as argument or volflag), there is a default timeout of 60sec, and only files which contain audio get analyzed by default (see ay/an/ad below)

but wait, there's more! -mtp can be used for non-audio files as well using the a flag: ay only do audio files (default), an only do non-audio files, or ad do all files (d as in dontcare)

if something doesn't work, try --mtag-v for verbose error messages

event hooks

trigger a program on uploads, renames etc (examples)

you can set hooks before and/or after an event happens, and currently you can hook uploads, moves/renames, and deletes

there's a bunch of flags and stuff, see --help-hooks

if you want to write your own hooks, see devnotes

upload events

the older, more powerful approach (examples):

-v /mnt/inc:inc:w:c,mte=+x1:c,mtp=x1=ad,kn,/usr/bin/notify-send

so filesystem location /mnt/inc shared at /inc, write-only for everyone, appending x1 to the list of tags to index (mte), and using /usr/bin/notify-send to "provide" tag x1 for any filetype (ad) with kill-on-timeout disabled (kn)

that'll run the command notify-send with the path to the uploaded file as the first and only argument (so on linux it'll show a notification on-screen)

note that this is way more complicated than the new event hooks but this approach has the following advantages:

note that it will occupy the parsing threads, so fork anything expensive (or set kn to have copyparty fork it for you) -- otoh if you want to intentionally queue/singlethread you can combine it with --mtag-mt 1

handlers

redefine behavior with plugins (examples)

replace 404 and 403 errors with something completely different (that's it for now)

identity providers

replace copyparty passwords with oauth and such

you can disable the built-in password-based login sysem, and instead replace it with a separate piece of software (an identity provider) which will then handle authenticating / authorizing of users; this makes it possible to login with passkeys / fido2 / webauthn / yubikey / ldap / active directory / oauth / many other single-sign-on contraptions

a popular choice is Authelia (config-file based), another one is authentik (GUI-based, more complex)

there is a docker-compose example which is hopefully a good starting point (alternatively see ./docs/idp.md if you're the DIY type)

a more complete example of the copyparty configuration options look like this

but if you just want to let users change their own passwords, then you probably want user-changeable passwords instead

user-changeable passwords

if permitted, users can change their own passwords in the control-panel

using the cloud as storage

connecting to an aws s3 bucket and similar

there is no built-in support for this, but you can use FUSE-software such as rclone / geesefs / JuiceFS to first mount your cloud storage as a local disk, and then let copyparty use (a folder in) that disk as a volume

you may experience poor upload performance this way, but that can sometimes be fixed by specifying the volflag sparse to force the use of sparse files; this has improved the upload speeds from 1.5 MiB/s to over 80 MiB/s in one case, but note that you are also more likely to discover funny bugs in your FUSE software this way, so buckle up

someone has also tested geesefs in combination with gocryptfs with surprisingly good results, getting 60 MiB/s upload speeds on a gbit line, but JuiceFS won with 80 MiB/s using its built-in encryption

you may improve performance by specifying larger values for --iobuf / --s-rd-sz / --s-wr-sz

hiding from google

tell search engines you dont wanna be indexed, either using the good old robots.txt or through copyparty settings:

also, --force-js disables the plain HTML folder listing, making things harder to parse for search engines

themes

you can change the default theme with --theme 2, and add your own themes by modifying browser.css or providing your own css to --css-browser, then telling copyparty they exist by increasing --themes

<table><tr><td width="33%" align="center"><a href="https://user-images.githubusercontent.com/241032/165864907-17e2ac7d-319d-4f25-8718-2f376f614b51.png"><img src="https://user-images.githubusercontent.com/241032/165867551-fceb35dd-38f0-42bb-bef3-25ba651ca69b.png"></a> 0. classic dark</td><td width="33%" align="center"><a href="https://user-images.githubusercontent.com/241032/168644399-68938de5-da9b-445f-8d92-b51c74b5f345.png"><img src="https://user-images.githubusercontent.com/241032/168644404-8e1a2fdc-6e59-4c41-905e-ba5399ed686f.png"></a> 2. flat pm-monokai</td><td width="33%" align="center"><a href="https://user-images.githubusercontent.com/241032/165864901-db13a429-a5da-496d-8bc6-ce838547f69d.png"><img src="https://user-images.githubusercontent.com/241032/165867560-aa834aef-58dc-4abe-baef-7e562b647945.png"></a> 4. vice</td></tr><tr><td align="center"><a href="https://user-images.githubusercontent.com/241032/165864905-692682eb-6fb4-4d40-b6fe-27d2c7d3e2a7.png"><img src="https://user-images.githubusercontent.com/241032/165867555-080b73b6-6d85-41bb-a7c6-ad277c608365.png"></a> 1. classic light</td><td align="center"><a href="https://user-images.githubusercontent.com/241032/168645276-fb02fd19-190a-407a-b8d3-d58fee277e02.png"><img src="https://user-images.githubusercontent.com/241032/168645280-f0662b3c-9764-4875-a2e2-d91cc8199b23.png"></a> 3. flat light </td><td align="center"><a href="https://user-images.githubusercontent.com/241032/165864898-10ce7052-a117-4fcf-845b-b56c91687908.png"><img src="https://user-images.githubusercontent.com/241032/165867562-f3003d45-dd2a-4564-8aae-fed44c1ae064.png"></a> 5. <a href="https://blog.codinghorror.com/a-tribute-to-the-windows-31-hot-dog-stand-color-scheme/">hotdog stand</a></td></tr></table>

the classname of the HTML tag is set according to the selected theme, which is used to set colors as css variables ++

see the top of ./copyparty/web/browser.css where the color variables are set, and there's layout-specific stuff near the bottom

if you want to change the fonts, see ./docs/rice/

complete examples

reverse-proxy

running copyparty next to other websites hosted on an existing webserver such as nginx, caddy, or apache

you can either:

some reverse proxies (such as Caddy) can automatically obtain a valid https/tls certificate for you, and some support HTTP/2 and QUIC which could be a nice speed boost, depending on a lot of factors

for improved security (and a 10% performance boost) consider listening on a unix-socket with -i unix:770:www:/tmp/party.sock (permission 770 means only members of group www can access it)

example webserver configs:

real-ip

teaching copyparty how to see client IPs when running behind a reverse-proxy, or a WAF, or another protection service such as cloudflare

if you (and maybe everybody else) keep getting a message that says thank you for playing, then you've gotten banned for malicious traffic. This ban applies to the IP address that copyparty thinks identifies the shady client -- so, depending on your setup, you might have to tell copyparty where to find the correct IP

for most common setups, there should be a helpful message in the server-log explaining what to do, but see docs/xff.md if you want to learn more, including a quick hack to just make it work (which is not recommended, but hey...)

prometheus

metrics/stats can be enabled at URL /.cpr/metrics for grafana / prometheus / etc (openmetrics 1.0.0)

must be enabled with --stats since it reduces startup time a tiny bit, and you probably want -e2dsa too

the endpoint is only accessible by admin accounts, meaning the a in rwmda in the following example commandline: python3 -m copyparty -a ed:wark -v /mnt/nas::rwmda,ed --stats -e2dsa

follow a guide for setting up node_exporter except have it read from copyparty instead; example /etc/prometheus/prometheus.yml below

scrape_configs:
  - job_name: copyparty
    metrics_path: /.cpr/metrics
    basic_auth:
      password: wark
    static_configs:
      - targets: ['192.168.123.1:3923']

currently the following metrics are available,

these are available unless --nos-vst is specified:

and these are available per-volume only:

and these are per-volume and total:

some of the metrics have additional requirements to function correctly,

the following options are available to disable some of the metrics:

note: the following metrics are counted incorrectly if multiprocessing is enabled with -j: cpp_http_conns, cpp_http_reqs, cpp_sus_reqs, cpp_active_bans, cpp_total_bans

other extremely specific features

you'll never find a use for these:

custom mimetypes

change the association of a file extension

using commandline args, you can do something like --mime gif=image/jif and --mime ts=text/x.typescript (can be specified multiple times)

in a config-file, this is the same as:

[global]
  mime: gif=image/jif
  mime: ts=text/x.typescript

run copyparty with --mimes to list all the default mappings

feature chickenbits

buggy feature? rip it out by setting any of the following environment variables to disable its associated bell or whistle,

env-varwhat it does
PRTY_NO_IFADDRdisable ip/nic discovery by poking into your OS with ctypes
PRTY_NO_IPV6disable some ipv6 support (should not be necessary since windows 2000)
PRTY_NO_LZMAdisable streaming xz compression of incoming uploads
PRTY_NO_MPdisable all use of the python multiprocessing module (actual multithreading, cpu-count for parsers/thumbnailers)
PRTY_NO_SQLITEdisable all database-related functionality (file indexing, metadata indexing, most file deduplication logic)
PRTY_NO_TLSdisable native HTTPS support; if you still want to accept HTTPS connections then TLS must now be terminated by a reverse-proxy
PRTY_NO_TPOKEdisable systemd-tmpfilesd avoider

example: PRTY_NO_IFADDR=1 python3 copyparty-sfx.py

packages

the party might be closer than you think

if your distro/OS is not mentioned below, there might be some hints in the Β«on serversΒ» section

arch package

now available on aur maintained by @icxes

it comes with a systemd service and expects to find one or more config files in /etc/copyparty.d/

fedora package

does not exist yet; using the copr-pypi builds is NOT recommended because updates can be delayed by several months

nix package

nix profile install github:9001/copyparty

requires a flake-enabled installation of nix

some recommended dependencies are enabled by default; override the package if you want to add/remove some features/deps

ffmpeg-full was chosen over ffmpeg-headless mainly because we need withWebp (and withOpenmpt is also nice) and being able to use a cached build felt more important than optimizing for size at the time -- PRs welcome if you disagree πŸ‘

nixos module

for this setup, you will need a flake-enabled installation of NixOS.

{
  # add copyparty flake to your inputs
  inputs.copyparty.url = "github:9001/copyparty";

  # ensure that copyparty is an allowed argument to the outputs function
  outputs = { self, nixpkgs, copyparty }: {
    nixosConfigurations.yourHostName = nixpkgs.lib.nixosSystem {
      modules = [
        # load the copyparty NixOS module
        copyparty.nixosModules.default
        ({ pkgs, ... }: {
          # add the copyparty overlay to expose the package to the module
          nixpkgs.overlays = [ copyparty.overlays.default ];
          # (optional) install the package globally
          environment.systemPackages = [ pkgs.copyparty ];
          # configure the copyparty module
          services.copyparty.enable = true;
        })
      ];
    };
  };
}

copyparty on NixOS is configured via services.copyparty options, for example:

services.copyparty = {
  enable = true;
  # directly maps to values in the [global] section of the copyparty config.
  # see `copyparty --help` for available options
  settings = {
    i = "0.0.0.0";
    # use lists to set multiple values
    p = [ 3210 3211 ];
    # use booleans to set binary flags
    no-reload = true;
    # using 'false' will do nothing and omit the value when generating a config
    ignored-flag = false;
  };

  # create users
  accounts = {
    # specify the account name as the key
    ed = {
      # provide the path to a file containing the password, keeping it out of /nix/store
      # must be readable by the copyparty service user
      passwordFile = "/run/keys/copyparty/ed_password";
    };
    # or do both in one go
    k.passwordFile = "/run/keys/copyparty/k_password";
  };

  # create a volume
  volumes = {
    # create a volume at "/" (the webroot), which will
    "/" = {
      # share the contents of "/srv/copyparty"
      path = "/srv/copyparty";
      # see `copyparty --help-accounts` for available options
      access = {
        # everyone gets read-access, but
        r = "*";
        # users "ed" and "k" get read-write
        rw = [ "ed" "k" ];
      };
      # see `copyparty --help-flags` for available options
      flags = {
        # "fk" enables filekeys (necessary for upget permission) (4 chars long)
        fk = 4;
        # scan for new files every 60sec
        scan = 60;
        # volflag "e2d" enables the uploads database
        e2d = true;
        # "d2t" disables multimedia parsers (in case the uploads are malicious)
        d2t = true;
        # skips hashing file contents if path matches *.iso
        nohash = "\.iso$";
      };
    };
  };
  # you may increase the open file limit for the process
  openFilesLimit = 8192;
};

the passwordFile at /run/keys/copyparty/ could for example be generated by agenix, or you could just dump it in the nix store instead if that's acceptable

browser support

TLDR: yes

copyparty-ie4-fs8

ie = internet-explorer, ff = firefox, c = chrome, iOS = iPhone/iPad, Andr = Android

featureie6ie9ie10ie11ff 52c 49iOSAndr
browse filesyepyepyepyepyepyepyepyep
thumbnail view-yepyepyepyepyepyepyep
basic uploaderyepyepyepyepyepyepyepyep
up2k--*1*1yepyepyepyep
make directoryyepyepyepyepyepyepyepyep
send messageyepyepyepyepyepyepyepyep
set sort order-yepyepyepyepyepyepyep
zip selection-yepyepyepyepyepyepyep
file rename-yepyepyepyepyepyepyep
file cut/paste-yepyepyepyepyepyepyep
navpane-yepyepyepyepyepyepyep
image viewer-yepyepyepyepyepyepyep
video player-yepyepyepyepyepyepyep
markdown editor--*2*2yepyepyepyep
markdown viewer-*2*2*2yepyepyepyep
play mp3/m4a-yepyepyepyepyepyepyep
play ogg/opus----yepyep*3yep
= feature =ie6ie9ie10ie11ff 52c 49iOSAndr

quick summary of more eccentric web-browsers trying to view a directory index:

browserwill it blend
links (2.21/macports)can browse, login, upload/mkdir/msg
lynx (2.8.9/macports)can browse, login, upload/mkdir/msg
w3m (0.5.3/macports)can browse, login, upload at 100kB/s, mkdir/msg
netsurf (3.10/arch)is basically ie6 with much better css (javascript has almost no effect)
opera (11.60/winxp)OK: thumbnails, image-viewer, zip-selection, rename/cut/paste. NG: up2k, navpane, markdown, audio
ie4 and netscape 4.0can browse, upload with ?b=u, auth with &pw=wark
ncsa mosaic 2.7does not get a pass, pic1 - pic2
SerenityOS (7e98457)hits a page fault, works with ?b=u, file upload not-impl

client examples

interact with copyparty using non-browser clients

copyparty returns a truncated sha512sum of your PUT/POST as base64; you can generate the same checksum locally to verify uplaods:

b512(){ printf "$((sha512sum||shasum -a512)|sed -E 's/ .*//;s/(..)/\\x\1/g')"|base64|tr '+/' '-_'|head -c44;}
b512 <movie.mkv

you can provide passwords using header PW: hunter2, cookie cppwd=hunter2, url-param ?pw=hunter2, or with basic-authentication (either as the username or password)

NOTE: curl will not send the original filename if you use -T combined with url-params! Also, make sure to always leave a trailing slash in URLs unless you want to override the filename

folder sync

sync folders to/from copyparty

the commandline uploader u2c.py with --dr is the best way to sync a folder to copyparty; verifies checksums and does files in parallel, and deletes unexpected files on the server after upload has finished which makes file-renames really cheap (it'll rename serverside and skip uploading)

alternatively there is rclone which allows for bidirectional sync and is way more flexible (stream files straight from sftp/s3/gcs to copyparty, ...), although there is no integrity check and it won't work with files over 100 MiB if copyparty is behind cloudflare

mount as drive

a remote copyparty server as a local filesystem; go to the control-panel and click connect to see a list of commands to do that

alternatively, some alternatives roughly sorted by speed (unreproducible benchmark), best first:

most clients will fail to mount the root of a copyparty server unless there is a root volume (so you get the admin-panel instead of a browser when accessing it) -- in that case, mount a specific volume instead

if you have volumes that are accessible without a password, then some webdav clients (such as davfs2) require the global-option --dav-auth to access any password-protected areas

android app

upload to copyparty with one tap

<a href="https://f-droid.org/packages/me.ocv.partyup/"><img src="https://ocv.me/fdroid.png" alt="Get it on F-Droid" height="50" /> '' <img src="https://img.shields.io/f-droid/v/me.ocv.partyup.svg" alt="f-droid version info" /></a> '' <a href="https://github.com/9001/party-up"><img src="https://img.shields.io/github/release/9001/party-up.svg?logo=github" alt="github version info" /></a>

the app is NOT the full copyparty server! just a basic upload client, nothing fancy yet

if you want to run the copyparty server on your android device, see install on android

iOS shortcuts

there is no iPhone app, but the following shortcuts are almost as good:

performance

defaults are usually fine - expect 8 GiB/s download, 1 GiB/s upload

below are some tweaks roughly ordered by usefulness:

client-side

when uploading files,

security

there is a discord server with an @everyone for all important updates (at the lack of better ideas)

some notes on hardening

safety profiles:

other misc notes:

gotchas

behavior that might be unexpected

cors

cross-site request config

by default, except for GET and HEAD operations, all requests must either:

cors can be configured with --acao and --acam, or the protections entirely disabled with --allow-csrf

filekeys

prevent filename bruteforcing

volflag fk generates filekeys (per-file accesskeys) for all files; users which have full read-access (permission r) will then see URLs with the correct filekey ?k=... appended to the end, and g users must provide that URL including the correct key to avoid a 404

by default, filekeys are generated based on salt (--fk-salt) + filesystem-path + file-size + inode (if not windows); add volflag fka to generate slightly weaker filekeys which will not be invalidated if the file is edited (only salt + path)

permissions wG (write + upget) lets users upload files and receive their own filekeys, still without being able to see other uploads

dirkeys

share specific folders in a volume without giving away full read-access to the rest -- the visitor only needs the g (get) permission to view the link

volflag dk generates dirkeys (per-directory accesskeys) for all folders, granting read-access to that folder; by default only that folder itself, no subfolders

volflag dky disables the actual key-check, meaning anyone can see the contents of a folder where they have g access, but not its subdirectories

volflag dks lets people enter subfolders as well, and also enables download-as-zip/tar

dirkeys are generated based on another salt (--dk-salt) + filesystem-path and have a few limitations:

password hashing

you can hash passwords before putting them into config files / providing them as arguments; see --help-pwhash for all the details

--ah-alg argon2 enables it, and if you have any plaintext passwords then it'll print the hashed versions on startup so you can replace them

optionally also specify --ah-cli to enter an interactive mode where it will hash passwords without ever writing the plaintext ones to disk

the default configs take about 0.4 sec and 256 MiB RAM to process a new password on a decent laptop

https

both HTTP and HTTPS are accepted by default, but letting a reverse proxy handle the https/tls/ssl would be better (probably more secure by default)

copyparty doesn't speak HTTP/2 or QUIC, so using a reverse proxy would solve that as well -- but note that HTTP/1 is usually faster than both HTTP/2 and HTTP/3

if cfssl is installed, copyparty will automatically create a CA and server-cert on startup

recovering from crashes

client crashes

frefox wsod

firefox 87 can crash during uploads -- the entire browser goes, including all other browser tabs, everything turns white

however you can hit F12 in the up2k tab and use the devtools to see how far you got in the uploads:

HTTP API

see devnotes

dependencies

mandatory deps:

optional dependencies

install these to enable bonus features

enable hashed passwords in config: argon2-cffi

enable ftp-server:

enable music tags:

enable thumbnails of...

enable smb support (not recommended):

pyvips gives higher quality thumbnails than Pillow and is 320% faster, using 270% more ram: sudo apt install libvips42 && python3 -m pip install --user -U pyvips

dependency chickenbits

prevent loading an optional dependency , for example if:

set any of the following environment variables to disable its associated optional feature,

env-varwhat it does
PRTY_NO_ARGON2disable argon2-cffi password hashing
PRTY_NO_CFSSLnever attempt to generate self-signed certificates using cfssl
PRTY_NO_FFMPEGaudio transcoding goes byebye, thumbnailing must be handled by Pillow/libvips
PRTY_NO_FFPROBEaudio transcoding goes byebye, thumbnailing must be handled by Pillow/libvips, metadata-scanning must be handled by mutagen
PRTY_NO_MUTAGENdo not use mutagen for reading metadata from media files; will fallback to ffprobe
PRTY_NO_PILdisable all Pillow-based thumbnail support; will fallback to libvips or ffmpeg
PRTY_NO_PILFdisable Pillow ImageFont text rendering, used for folder thumbnails
PRTY_NO_PIL_AVIFdisable 3rd-party Pillow plugin for AVIF support
PRTY_NO_PIL_HEIFdisable 3rd-party Pillow plugin for HEIF support
PRTY_NO_PIL_WEBPdisable use of native webp support in Pillow
PRTY_NO_PSUTILdo not use psutil for reaping stuck hooks and plugins on Windows
PRTY_NO_VIPSdisable all libvips-based thumbnail support; will fallback to Pillow or ffmpeg

example: PRTY_NO_PIL=1 python3 copyparty-sfx.py

optional gpl stuff

some bundled tools have copyleft dependencies, see ./bin/#mtag

these are standalone programs and will never be imported / evaluated by copyparty, and must be enabled through -mtp configs

sfx

the self-contained "binary" (recommended!) copyparty-sfx.py will unpack itself and run copyparty, assuming you have python installed of course

you can reduce the sfx size by repacking it; see ./docs/devnotes.md#sfx-repack

copyparty.exe

download copyparty.exe (win8+) or copyparty32.exe (win7+)

copyparty-exe-fs8

can be convenient on machines where installing python is problematic, however is not recommended -- if possible, please use copyparty-sfx.py instead

meanwhile copyparty-sfx.py instead relies on your system python which gives better performance and will stay safe as long as you keep your python install up-to-date

then again, if you are already into downloading shady binaries from the internet, you may also want my minimal builds of ffmpeg and ffprobe which enables copyparty to extract multimedia-info, do audio-transcoding, and thumbnails/spectrograms/waveforms, however it's much better to instead grab a recent official build every once ina while if you can afford the size

zipapp

another emergency alternative, copyparty.pyz has less features, requires python 3.7 or newer, worse compression, and more importantly is unable to benefit from more recent versions of jinja2 and such (which makes it less secure)... lots of drawbacks with this one really -- but it may just work if the regular sfx fails to start because the computer is messed up in certain funky ways, so it's worth a shot if all else fails

run it by doubleclicking it, or try typing python copyparty.pyz in your terminal/console/commandline/telex if that fails

it is a python zipapp meaning it doesn't have to unpack its own python code anywhere to run, so if the filesystem is busted it has a better chance of getting somewhere

install on android

install Termux + its companion app Termux:API (see ocv.me/termux) and then copy-paste this into Termux (long-tap) all at once:

yes | pkg upgrade && termux-setup-storage && yes | pkg install python termux-api && python -m ensurepip && python -m pip install --user -U copyparty && { grep -qE 'PATH=.*\.local/bin' ~/.bashrc 2>/dev/null || { echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && . ~/.bashrc; }; }
echo $?

after the initial setup, you can launch copyparty at any time by running copyparty anywhere in Termux -- and if you run it with --qr you'll get a neat qr-code pointing to your external ip

if you want thumbnails (photos+videos) and you're okay with spending another 132 MiB of storage, pkg install ffmpeg && python3 -m pip install --user -U pillow

reporting bugs

ideas for context to include, and where to submit them

please get in touch using any of the following URLs:

in general, commandline arguments (and config file if any)

if something broke during an upload (replacing FILENAME with a part of the filename that broke):

journalctl -aS '48 hour ago' -u copyparty | grep -C10 FILENAME | tee bug.log

if there's a wall of base64 in the log (thread stacks) then please include that, especially if you run into something freezing up or getting stuck, for example OperationalError('database is locked') -- alternatively you can visit /?stack to see the stacks live, so http://127.0.0.1:3923/?stack for example

devnotes

for build instructions etc, see ./docs/devnotes.md

see ./docs/TODO.md for planned features / fixes / changes