πΎπ 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 on a nuc in my basement
π· screenshots: browser // upload // unpost // thumbnails // search // fsearch // zip-DL // md-viewer
π¬ videos: upload // cli-upload // race-the-beam
made in Norway π³π΄
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:
Alpine: apk add py3-pillow ffmpeg
Debian: apt install --no-install-recommends python3-pil ffmpeg
Fedora: rpmfusion + dnf install python3-pillow ffmpeg --allowerasing
rpmfusion + FreeBSD: pkg install py39-sqlite3 py39-pillow ffmpeg
MacOS: port install py-Pillow ffmpeg
MacOS (alternative): brew install pillow ffmpeg
(alternative): Windows: python -m pip install --user -U Pillow install python and ffmpeg manually; do not use winget or Microsoft Store (it breaks $PATH) copyparty.exe comes with Pillow and only needs ffmpeg for mediatags/videothumbs
see optional dependencies to enable even more features
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:
-e2dsa enables general file indexing
enables general file indexing -e2ts enables audio metadata indexing (needs either FFprobe or Mutagen)
enables audio metadata indexing (needs either FFprobe or Mutagen) -v /mnt/music:/music:r:rw,foo -a foo:bar shares /mnt/music as /music , r eadable by anyone, and read-write for user foo , password bar replace :r:rw,foo with :r,foo to only make the folder readable by foo and nobody else see accounts and volumes (or --help-accounts ) for the syntax and other permissions
shares as , eadable by anyone, and read-write for user , password
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
but if you have a domain, then you probably want to skip the random autogenerated URL and instead make a permanent cloudflare tunnel
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:
contrib/systemd/copyparty.service to run copyparty as a systemd service (see guide inside)
contrib/systemd/prisonparty.service to run it in a chroot (for extra security)
contrib/openrc/copyparty to run copyparty on Alpine / Gentoo
contrib/rc/copyparty to run copyparty on FreeBSD
nixos module to run copyparty on NixOS hosts
contrib/nginx/copyparty.conf to reverse-proxy behind nginx (for better https)
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
UI ΠΏΡΠΎΡΡΠΎ ΡΠΆΠ°ΡΠ½ΠΎ. ΠΡΠ»ΠΈ Π±ΡΠ΄Ρ ΠΎΠΏΠΈΡΡΠ²Π°ΡΡ Π΄Π΅ΡΠ°Π»ΡΠ½ΠΎ Π½Π΅ ΡΠΌΠΎΠ³Ρ ΡΠ΄Π΅ΡΠΆΠ°ΡΡΡΡ Π² ΡΠ°ΠΌΠΊΠ°Ρ
ΠΏΡΠΈΠ»ΠΈΡΠΈΠΉ
motivations
project goals / philosophy
inverse linux philosophy -- do all the things, and do an okay job quick drop-in service to get a lot of features in a pinch some of the alternatives might be a better fit for you
run anywhere, support everything as many web-browsers and python versions as possible every browser should at least be able to browse, download, upload files be a good emergency solution for transferring stuff between ancient boxes minimal dependencies but optional dependencies adding bonus-features are ok everything being plaintext makes it possible to proofread for malicious code no preparations / setup necessary, just run the sfx (which is also plaintext)
adaptable, malleable, hackable no build steps; modify the js/python without needing node.js or anything like that
becoming rich is specifically not a motivation, but if you wanna donate then see my github profile regarding donations for my FOSS stuff in general (also THANKS!)
notes
general notes:
paper-printing is affected by dark/light-mode! use lightmode for color, darkmode for grayscale because no browsers currently implement the media-query to do this properly orz
browser-specific:
iPhone/iPad: use Firefox to download files
Android-Chrome: increase "parallel uploads" for higher speed (android bug)
Android-Firefox: takes a while to select files (their fix for βοΈ)
Desktop-Firefox: may use gigabytes of RAM if your files are massive seems to be OK now
seems to be OK now Desktop-Firefox: may stop you from unplugging USB flashdrives until you visit about:memory and click Minimize memory usage
server-os-specific:
RHEL8 / Rocky8: you can run copyparty using /usr/libexec/platform-python
server notes:
pypy is supported but regular cpython is faster if you enable the database
bugs
roughly sorted by chance of encounter
general: --th-ff-jpg may fix video thumbnails on some FFmpeg versions (macos, some linux) --th-ff-swr may fix audio thumbnails on some FFmpeg versions if the up2k.db (filesystem index) is on a samba-share or network disk, you'll get unpredictable behavior if the share is disconnected for a bit use --hist or the hist volflag ( -v [...]:c,hist=/tmp/foo ) to place the db and thumbnails on a local disk instead or, if you only want to move the db (and not the thumbnails), then use --dbpath or the dbpath volflag all volumes must exist / be available on startup; up2k (mtp especially) gets funky otherwise probably more, pls let me know
python 3.4 and older (including 2.7): many rare and exciting edge-cases because python didn't handle EINTR yet downloads from copyparty may suddenly fail, but uploads should be fine
python 2.7 on Windows: cannot index non-ascii filenames with -e2d cannot handle filenames with mojibake
if you have a new exciting bug to share, see reporting bugs
not my bugs
same order here too
Chrome issue 1317069 -- if you try to upload a folder which contains symlinks by dragging it into the browser, the symlinked files will not get uploaded
Chrome issue 1352210 -- plaintext http may be faster at filehashing than https (but also extremely CPU-intensive)
Chrome issue 383568268 -- filereaders in webworkers can OOM / crash the browser-tab copyparty has a workaround which seems to work well enough
Firefox issue 1790500 -- entire browser can crash after uploading ~4000 small files
Android: music playback randomly stops due to battery usage settings
iPhones: the volume control doesn't work because apple doesn't want it to AudioContext will probably never be a viable workaround as apple introduces new issues faster than they fix current ones
iPhones: music volume goes on a rollercoaster during song changes nothing I can do about it because AudioContext is still broken in safari
iPhones: the preload feature (in the media-player-options tab) can cause a tiny audio glitch 20sec before the end of each song, but disabling it may cause worse iOS bugs to appear instead just a hunch, but disabling preloading may cause playback to stop entirely, or possibly mess with bluetooth speakers tried to add a tooltip regarding this but looks like apple broke my tooltips
iPhones: preloaded awo files make safari log MEDIA_ERR_NETWORK errors as playback starts, but the song plays just fine so eh whatever awo, opus-weba, is apple's new take on opus support, replacing opus-caf which was technically limited to cbr opus
iPhones: preloading another awo file may cause playback to stop can be somewhat mitigated with mp.au.play() in mp.onpreload but that can hit a race condition in safari that starts playing the same audio object twice in parallel...
Windows: folders cannot be accessed if the name ends with . python or windows bug
Windows: msys2-python 3.8.6 occasionally throws RuntimeError: release unlocked lock when leaving a scoped mutex in up2k this is an msys2 bug, the regular windows edition of python is fine
VirtualBox: sqlite throws Disk I/O Error when running in a VM and the up2k database is in a vboxsf use --hist or the hist volflag ( -v [...]:c,hist=/tmp/foo ) to place the db and thumbnails inside the vm instead or, if you only want to move the db (and not the thumbnails), then use --dbpath or the dbpath volflag also happens on mergerfs, so put the db elsewhere
Ubuntu: dragging files from certain folders into firefox or chrome is impossible due to snap security policies -- see snap connections firefox for the allowlist, removable-media permits all of /mnt and /media apparently
breaking changes
upgrade notes
1.9.16 (2023-11-04): --stats /prometheus: cpp_bans renamed to cpp_active_bans , and that + cpp_uptime are gauges
(2023-11-04): 1.6.0 (2023-01-29): http-api: delete/move is now POST instead of GET everything other than GET and HEAD must pass cors validation
(2023-01-29): 1.5.0 (2022-12-03): new chunksize formula for files larger than 128 GiB users: upgrade to the latest cli uploader if you use that devs: update third-party up2k clients (if those even exist)
(2022-12-03): new chunksize formula for files larger than 128 GiB
FAQ
"frequently" asked questions
CopyParty? nope! the name is either copyparty (all-lowercase) or Copyparty -- it's one word after all :>
can I change the π² spinning pine-tree loading animation? yeah... :-(
is it possible to block read-access to folders unless you know the exact URL for a particular file inside? yes, using the g permission, see the examples there you can also do this with linux filesystem permissions; chmod 111 music will make it possible to access files and folders inside the music folder but not list the immediate contents -- also works with other software, not just copyparty
can I link someone to a password-protected volume/file by including the password in the URL? yes, by adding ?pw=hunter2 to the end; replace ? with & if there are parameters in the URL already, meaning it contains a ? near the end
how do I stop .hist folders from appearing everywhere on my HDD? by default, a .hist folder is created inside each volume for the filesystem index, thumbnails, audio transcodes, and markdown document history. Use the --hist global-option or the hist volflag to move it somewhere else; see database location
can I make copyparty download a file to my server if I give it a URL? yes, using hooks
firefox refuses to connect over https, saying "Secure Connection Failed" or "SEC_ERROR_BAD_SIGNATURE", but the usual button to "Accept the Risk and Continue" is not shown firefox has corrupted its certstore; fix this by exiting firefox, then find and delete the file named cert9.db somewhere in your firefox profile folder
the server keeps saying thank you for playing when I try to access the website you've gotten banned for malicious traffic! if this happens by mistake, and you're running a reverse-proxy and/or something like cloudflare, see real-ip on how to fix this
copyparty seems to think I am using http, even though the URL is https your reverse-proxy is not sending the X-Forwarded-Proto: https header; this could be because your reverse-proxy itself is confused. Ensure that none of the intermediates (such as cloudflare) are terminating https before the traffic hits your entrypoint
thumbnails are broken (you get a colorful square which says the filetype instead) you need to install FFmpeg or Pillow ; see thumbnails
thumbnails are broken (some images appear, but other files just get a blank box, and/or the broken-image placeholder) probably due to a reverse-proxy messing with the request URLs and stripping the query parameters ( ?th=w ), so check your URL rewrite rules could also be due to incorrect caching settings in reverse-proxies and/or CDNs, so make sure that nothing is set to ignore the query string could also be due to misbehaving privacy-related browser extensions, so try to disable those
i want to learn python and/or programming and am considering looking at the copyparty source code in that occasion _ | _ __ _ _ | _ (_ | (_) | | (_) | _
accounts and volumes
per-folder, per-user permissions - if your setup is getting complex, consider making a config file instead of using arguments
much easier to manage, and you can modify the config at runtime with systemctl reload copyparty or more conveniently using the [reload cfg] button in the control-panel (if the user has a /admin in any volume) changes to the [global] config section requires a restart to take effect
or more conveniently using the button in the control-panel (if the user has /admin in any volume)
a quick summary can be seen using --help-accounts
configuring accounts/volumes with arguments:
-a usr:pwd adds account usr with password pwd
adds account with password -v .::r adds current-folder . as the webroot, r eadable by anyone the syntax is -v src:dst:perm:perm:... so local-path, url-path, and one or more permissions to set granting the same permissions to multiple accounts:
-v .::r,usr1,usr2:rw,usr3,usr4 = usr1/2 read-only, 3/4 read-write
adds current-folder as the webroot, eadable by anyone
permissions:
r (read): browse folder contents, download files, download as zip/tar, see filekeys/dirkeys
(read): browse folder contents, download files, download as zip/tar, see filekeys/dirkeys w (write): upload files, move/copy files into this folder
(write): upload files, move/copy files into this folder m (move): move files/folders from this folder
(move): move files/folders from this folder d (delete): delete files/folders
(delete): delete files/folders . (dots): user can ask to show dotfiles in directory listings
(dots): user can ask to show dotfiles in directory listings g (get): only download files, cannot see folder contents or zip/tar
(get): only download files, cannot see folder contents or zip/tar G (upget): same as g except uploaders get to see their own filekeys (see fk in examples below)
(upget): same as except uploaders get to see their own filekeys (see in examples below) h (html): same as g except folders return their index.html, and filekeys are not necessary for index.html
(html): same as except folders return their index.html, and filekeys are not necessary for index.html a (admin): can see upload time, uploader IPs, config-reload
(admin): can see upload time, uploader IPs, config-reload A ("all"): same as rwmda. (read/write/move/delete/admin/dotfiles)
examples:
add accounts named u1, u2, u3 with passwords p1, p2, p3: -a u1:p1 -a u2:p2 -a u3:p3
make folder /srv the root of the filesystem, read-only by anyone: -v /srv::r
the root of the filesystem, read-only by anyone: make folder /mnt/music available at /music , read-only for u1 and u2, read-write for u3: -v /mnt/music:music:r,u1,u2:rw,u3 unauthorized users accessing the webroot can see that the music folder exists, but cannot open it
available at , read-only for u1 and u2, read-write for u3: make folder /mnt/incoming available at /inc , write-only for u1, read-move for u2: -v /mnt/incoming:inc:w,u1:rm,u2 unauthorized users accessing the webroot can see that the inc folder exists, but cannot open it u1 can open the inc folder, but cannot see the contents, only upload new files to it u2 can browse it and move files from /inc into any folder where u2 has write-access
available at , write-only for u1, read-move for u2: make folder /mnt/ss available at /i , read-write for u1, get-only for everyone else, and enable filekeys: -v /mnt/ss:i:rw,u1:g:c,fk=4 c,fk=4 sets the fk (filekey) volflag to 4, meaning each file gets a 4-character accesskey u1 can upload files, browse the folder, and see the generated filekeys other users cannot browse the folder, but can access the files if they have the full file URL with the filekey replacing the g permission with wg would let anonymous users upload files, but not see the required filekey to access it replacing the g permission with wG would let anonymous users upload files, receiving a working direct link in return
available at , read-write for u1, get-only for everyone else, and enable filekeys:
anyone trying to bruteforce a password gets banned according to --ban-pw ; default is 24h ban for 9 failed attempts in 1 hour
and if you want to use config files instead of commandline args (good!) then here's the same examples as a configfile; save it as foobar.conf and use it like this: python copyparty-sfx.py -c foobar.conf
[accounts] u1 : p1 # create account "u1" with password "p1" u2 : p2 # (note that comments must have u3 : p3 # two spaces before the # sign) [/] # this URL will be mapped to... /srv # ...this folder on the server filesystem accs : r : * # read-only for everyone, no account necessary [/music] # create another volume at this URL, /mnt/music # which is mapped to this folder accs : r : u1, u2 # only these accounts can read, rw : u3 # and only u3 can read-write [/inc] /mnt/incoming accs : w : u1 # u1 can upload but not see/download any files, rm : u2 # u2 can browse + move files out of this volume [/i] /mnt/ss accs : rw : u1 # u1 can read-write, g : * # everyone can access files if they know the URL flags : fk : 4 # each file URL will have a 4-character password
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
the example config file right above this section may explain this better; the first volume / is mapped to /srv which means http://127.0.0.1:3923/music would try to read /srv/music on the server filesystem, but since there's another volume at /music mapped to /mnt/music then it'll go to /mnt/music instead
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
even if user has permission to see dotfiles, they are default-hidden unless --see-dots is set, and/or user has enabled the dotfiles option in the settings tab
config file example, where the same permission to see dotfiles is given in two different ways just for reference:
[/foo] /srv/foo accs : r. : ed # user "ed" has read-access + dot-access in this volume; # dotfiles are visible in listings, but not in searches flags : dotsrch # dotfiles will now appear in search results too dots # another way to let everyone see dotfiles in this vol
the browser
accessing a copyparty server using a web-browser
tabs
the main tabs in the ui
[π] search by size, date, path/name, mp3-tags ...
search by size, date, path/name, mp3-tags ... [π§―] unpost: undo/delete accidental uploads
unpost: undo/delete accidental uploads [π] and [π] are the uploaders
and are the uploaders [π] mkdir: create directories
mkdir: create directories [π] new-md: create a new markdown document
new-md: create a new markdown document [π] send-msg: either to server-log or into textfiles if --urlform save
send-msg: either to server-log or into textfiles if [πΊ] audio-player config options
audio-player config options [βοΈ] general client config options
hotkeys
the browser has the following hotkeys (always qwerty)
? show hotkeys help
show hotkeys help B toggle breadcrumbs / navpane
toggle breadcrumbs / navpane I/K prev/next folder
prev/next folder M parent folder (or unexpand current)
parent folder (or unexpand current) V toggle folders / textfiles in the navpane
toggle folders / textfiles in the navpane G toggle list / grid view -- same as η° bottom-right
toggle list / grid view -- same as bottom-right T toggle thumbnails / icons
toggle thumbnails / icons ESC close various things
close various things ctrl-K delete selected files/folders
delete selected files/folders ctrl-X cut selected files/folders
cut selected files/folders ctrl-C copy selected files/folders to clipboard
copy selected files/folders to clipboard ctrl-V paste (move/copy)
paste (move/copy) Y download selected files
download selected files F2 rename selected file/folder
rename selected file/folder when a file/folder is selected (in not-grid-view): Up/Down move cursor shift+ Up/Down select and move cursor ctrl+ Up/Down move cursor and scroll viewport Space toggle file selection Ctrl-A toggle select all
when a textfile is open: I/K prev/next textfile S toggle selection of open file M close textfile
when playing audio: J/L prev/next song U/O skip 10sec back/forward 0..9 jump to 0%..90% P play/pause (also starts playing the folder) Y download file
when viewing images / playing videos: J/L, Left/Right prev/next file Home/End first/last file F toggle fullscreen S toggle selection R rotate clockwise (shift=ccw) Y download file Esc close viewer videos: U/O skip 10sec back/forward 0..9 jump to 0%..90% P/K/Space play/pause M mute C continue playing next video V loop entire file [ loop range (start) ] loop range (end)
when the navpane is open: A/D adjust tree width
in the grid view: S toggle multiselect shift+ A/D zoom
in the markdown editor: ^s save ^h header ^k autoformat table ^u jump to next unicode character ^e toggle editor / preview ^up, ^down jump paragraphs
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)
[+] and [-] (or hotkeys A / D ) adjust the size
and (or hotkeys / ) adjust the size [π―] jumps to the currently open folder
jumps to the currently open folder [π] toggles between showing folders and textfiles
toggles between showing folders and textfiles [π] shows the name of all parent folders in a docked panel
shows the name of all parent folders in a docked panel [a] toggles automatic widening as you go deeper
toggles automatic widening as you go deeper [β΅] toggles wordwrap
toggles wordwrap [π] show full name on hover (if wordwrap is off)
thumbnails
press g or η° to toggle grid-view instead of the file listing and t toggles icons / thumbnails
can be made default globally with --grid or per-volume with volflag grid
or per-volume with volflag enable by adding ?imgs to a link, or disable with ?imgs=0
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
pyvips is 3x faster than Pillow, Pillow is 3x faster than FFmpeg
disable thumbnails for specific volumes with volflag dthumb for all, or dvthumb / dathumb / dithumb for video/audio/images only
for all, or / / for video/audio/images only for installing FFmpeg on windows, see optional dependencies
audio files are converted 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
the order is significant, so if both cover.png and folder.jpg exist in a folder, it will pick the first matching --th-covers entry ( folder.jpg )
and exist in a folder, it will pick the first matching entry ( ) and, if you enable file indexing, it will also try those names as dotfiles ( .folder.jpg and so), and then fallback on the first picture in the folder (if it has any pictures at all)
enabling multiselect lets you click files to select them, and then shift-click another file for range-select
multiselect is mostly intended for phones/tablets, but the sel option in the [βοΈ] settings tab is better suited for desktop use, allowing selection by CTRL-clicking and range-selection with SHIFT-click, all without affecting regular clicking the sel option can be made default globally with --gsel or per-volume with volflag gsel
is mostly intended for phones/tablets, but the option in the tab is better suited for desktop use, allowing selection by CTRL-clicking and range-selection with SHIFT-click, all without affecting regular clicking
to show /icons/exe.png and /icons/elf.gif as the thumbnail for all .exe and .elf files respectively, do this: --ext-th=exe=/icons/exe.png --ext-th=elf=/icons/elf.gif
optionally as separate volflags for each mapping; see config file example below
the supported image formats are jpg, png, gif, webp, ico be careful with svg; chrome will crash if you have too many unique svg files showing on the same page (the limit is 250 or so) -- showing the same handful of svg files thousands of times is ok however
config file example:
[global] no-thumb # disable ALL thumbnails and audio transcoding no-vthumb # only disable video thumbnails [/music] /mnt/nas/music accs : r : * # everyone can read flags : dthumb # disable ALL thumbnails and audio transcoding dvthumb # only disable video thumbnails ext-th : exe=/ico/exe.png # /ico/exe.png is the thumbnail of *.exe ext-th : elf=/ico/elf.gif # ...and /ico/elf.gif is used for *.elf th-covers : folder.png,folder.jpg,cover.png,cover.jpg # the default
zip downloads
download folders (or file selections) as zip or tar files
select which type of archive you want in the [βοΈ] config tab:
name url-suffix description tar ?tar plain gnutar, works great with curl | tar -xv pax ?tar=pax pax-format tar, futureproof, not as fast tgz ?tar=gz gzip compressed gnu-tar (slow), for curl | tar -xvz txz ?tar=xz gnu-tar with xz / lzma compression (v.slow) zip ?zip works everywhere, glitchy filenames on win7 and older zip_dos ?zip=dos traditional cp437 (no unicode) to fix glitchy filenames zip_crc ?zip=crc cp437 with crc32 computed early for truly ancient software
gzip default level is 3 (0=fast, 9=best), change with ?tar=gz:9
(0=fast, 9=best), change with xz default level is 1 (0=fast, 9=best), change with ?tar=xz:9
(0=fast, 9=best), change with bz2 default level is 2 (1=fast, 9=best), change with ?tar=bz2:9
(1=fast, 9=best), change with hidden files (dotfiles) are excluded unless account is allowed to list them up2k.db and dir.txt is always excluded
bsdtar supports streaming unzipping: curl foo?zip | bsdtar -xv good, because copyparty's zip is faster than tar on small files but ?tar is better for large files, especially if the total exceeds 4 GiB
zip_crc will take longer to download since the server has to read each file twice this is only to support MS-DOS PKZIP v2.04g (october 1993) and older how are you accessing copyparty actually
will take longer to download since the server has to read each file twice
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
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
super useful if you're 5 minutes away from takeoff and realize you don't have any music on your phone but your server only has flac files and downloading those will burn through all your data + there wouldn't be enough time anyways
and url-params &j / &w produce jpeg/webm thumbnails/spectrograms instead of the original audio/video/images ( &p for audio waveforms) can also be used to pregenerate thumbnails; combine with --th-maxage=9999999 or --th-clean=0
/ produce jpeg/webm thumbnails/spectrograms instead of the original audio/video/images ( for audio waveforms)
uploading
drag files/folders into the web-browser to upload
dragdrop is the recommended way, but you may also:
select some files (not folders) in your file explorer and press CTRL-V inside the browser window
use the command-line uploader
upload using curl, sharex, ishare, ...
when uploading files through dragdrop or CTRL-V, this initiates an upload using up2k ; there are two browser-based uploaders available:
[π] bup , the basic uploader, supports almost every browser since netscape 4.0
, the basic uploader, supports almost every browser since netscape 4.0 [π] up2k , the good / fancy one
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:
you can drop folders into the browser (files are added recursively)
files are processed in chunks, and each chunk is checksummed uploads autoresume if they are interrupted by network issues uploads resume if you reboot your browser or pc, just upload the same files again server detects any corruption; the client reuploads affected chunks the client doesn't upload anything that already exists on the server no filesize limit, even when a proxy limits the request size (for example Cloudflare)
much higher speeds than ftp/scp/tarpipe on some internet connections (mainly american ones) thanks to parallel connections
the last-modified timestamp of the file is preserved
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
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 intuitive experiences:
"parallel uploads" specifies how many chunks to upload at the same time
[π] analysis of other files should continue while one is uploading
analysis of other files should continue while one is uploading [π₯] shows a simpler UI for faster uploads from slow devices
shows a simpler UI for faster uploads from slow devices [π‘οΈ] decides when to overwrite existing files on the server π‘οΈ = never (generate a new filename instead) π = overwrite if the server-file is older β»οΈ = always overwrite if the files are different
decides when to overwrite existing files on the server [π²] generate random filenames during upload
generate random filenames during upload [π] switch between upload and file-search mode ignore [π] if you add files by dragging them into the browser
switch between upload and file-search mode
and then theres the tabs below it,
[ok] is the files which completed successfully
is the files which completed successfully [ng] is the ones that failed / got rejected (already exists, ...)
is the ones that failed / got rejected (already exists, ...) [done] shows a combined list of [ok] and [ng] , chronological order
shows a combined list of and , chronological order [busy] files which are currently hashing, pending-upload, or uploading plus up to 3 entries each from [done] and [que] for context
files which are currently hashing, pending-upload, or uploading [que] is all the files that are still queued
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
if the server is behind a proxy which imposes a request-size limit, you can configure up2k to sneak below the limit with server-option --u2sz (the default is 96 MiB to support Cloudflare)
if you want to replace existing files on the server with new uploads by default, run with --u2ow 2 (only works if users have the delete-permission, and can still be disabled with π‘οΈ in the UI)
dropping files into the browser also lets you see if they exist on the server
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]
the main reason filesearch is combined with the uploader is cause the code was too spaghetti to separate it out somewhere else, this is no longer the case but now i've warmed up to the idea too much
unpost
undo/delete accidental uploads using the [π§―] tab in the UI
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
config file example:
[global] e2d # enable up2k database (remember uploads) unpost : 43200 # 12 hours (default)
uploads can be given a lifetime, after 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
incoming files
the control-panel shows the ETA for all incoming files , but only for files being uploaded into volumes where you have read-access
file manager
cut/paste, rename, and delete files/folders (if you have permission)
file selection: click somewhere on the line (not the link itself), then:
space to toggle
up/down to move
shift-up/down to move-and-select
ctrl-shift-up/down to also scroll
shift-click another line for range-select
cut: select some files and ctrl-x
copy: select some files and ctrl-c
paste: ctrl-v in another folder
rename: F2
you can copy/move files across browser tabs (cut/copy 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:
select a folder first to share that folder instead
select one or more files to share only those files
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:
password-protection
expire after a certain time; 0 or blank means infinite
or blank means infinite allow visitors to upload (if the user who creates the share has write-access)
semi-intentional limitations:
cleanup of expired shares only works when global option e2d is set, and/or at least one volume on the server has volflag e2d
is set, and/or at least one volume on the server has volflag only folders from the same volume are shared; if you are sharing a folder which contains other volumes, then the contents of those volumes will not be available
if you change password hashing settings after creating a password-protected share, then that share will stop working
related to IdP volumes being forgotten on shutdown, any shares pointing into a user's IdP volume will be unavailable until that user makes their first request after a restart
no option to "delete after first access" because tricky when linking something to discord (for example) it'll get accessed by their scraper and that would count as a hit browsers wouldn't be able to resume a broken download unless the requester's IP gets allowlisted for X minutes (ref. tricky)
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
you can name it whatever, foobar is just an example
is just an example if you're using config files, put shr: /foobar inside the [global] section instead
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
quick explanation of the buttons,
[β
apply rename] confirms and begins renaming
confirms and begins renaming [β cancel] aborts and closes the rename window
aborts and closes the rename window [βΊ reset] reverts any filename changes back to the original name
reverts any filename changes back to the original name [decode] does a URL-decode on the filename, fixing stuff like & and %20
does a URL-decode on the filename, fixing stuff like and [advanced] toggles advanced mode
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,
[case] toggles case-sensitive regex
toggles case-sensitive regex regex is the regex pattern to apply to the original filename; any files which don't match will be skipped
is the regex pattern to apply to the original filename; any files which don't match will be skipped format is the new filename, taking values from regex capturing groups and/or from file tags very loosely based on foobar2000 syntax
is the new filename, taking values from regex capturing groups and/or from file tags presets lets you save rename rules for later
available functions:
$lpad(text, length, pad_char)
$rpad(text, length, pad_char)
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:
regex = (.*) - (.*) - ([0-9]{2}) (.*)
= format = (3). (1) - (4)
= output = 07. meganeko - Sirius A.mp3
or you could use just tags:
format = $lpad((tn),2,0). (artist) - (title).(ext)
= output = 7. meganeko - Sirius A.mp3
or a mix of both:
regex = - ([0-9]{2})
= format = (1). (artist) - (title).(ext)
= output = 07. meganeko - Sirius A.mp3
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 )
rss feeds
monitor a folder with your RSS reader , optionally recursive
must be enabled per-volume with volflag rss or globally with --rss
the feed includes itunes metadata for use with podcast readers such as AntennaPod
a feed example: https://cd.ocv.me/a/d2/d22/?rss&fext=mp3
url parameters:
pw=hunter2 for password auth
for password auth recursive to also include subfolders
to also include subfolders title=foo changes the feed title (default: folder name)
changes the feed title (default: folder name) fext=mp3,opus only include mp3 and opus files (default: all)
only include mp3 and opus files (default: all) nf=30 only show the first 30 results (default: 250)
only show the first 30 results (default: 250) sort=m sort by mtime (file last-modified), newest first (default) u = upload-time; NOTE: non-uploaded files have upload-time 0 n = filename a = filesize uppercase = reverse-sort; M = oldest file first
sort by mtime (file last-modified), newest first (default)
recent uploads
list all recent uploads by clicking "show recent uploads" in the controlpanel
will show uploader IP and upload-time if the visitor has the admin permission
global-option --ups-when makes upload-time visible to all users, and not just admins
global-option --ups-who (volflag ups_who ) specifies who gets access (0=nobody, 1=admins, 2=everyone), default=2
note that the π§― unpost feature is better suited for viewing your own recent uploads, as it includes the option to undo/delete them
config file example:
[global] ups-when # everyone can see upload times ups-who : 1 # but only admins can see the list, # so ups-when doesn't take effect
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:
OS integration; control playback from your phone's lockscreen (windows // iOS // android)
shows the audio waveform in the seekbar
not perfectly gapless but can get really close (see settings + eq below); good enough to enjoy gapless albums as intended
videos can be played as audio, without wasting bandwidth on the video
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,
"switches": [π] repeats one single song forever [π] shuffles the files inside each folder [preload] starts loading the next track when it's about to end, reduces the silence between songs [full] does a full preload by downloading the entire next file; good for unreliable connections, bad for slow connections [~s] toggles the seekbar waveform display [/np] enables buttons to copy the now-playing info as an irc message [π»] enables buttons to create an m3u playlist with the selected songs [os-ctl] makes it possible to control audio playback from the lockscreen of your device (enables mediasession) [seek] allows seeking with lockscreen controls (buggy on some devices) [art] shows album art on the lockscreen [π―] keeps the playing song scrolled into view (good when using the player as a taskbar dock) [β] shrinks the playback controls
"buttons": [uncache] may fix songs that won't play correctly due to bad files in browser cache
"at end of folder": [loop] keeps looping the folder [next] plays into the next folder
"transcode": [flac] converts flac and wav files into opus (if supported by browser) or mp3 [aac] converts aac and m4a files into opus (if supported by browser) or mp3 [oth] converts all other known formats into opus (if supported by browser) or mp3 aac|ac3|aif|aiff|alac|alaw|amr|ape|au|dfpwm|dts|flac|gsm|it|m4a|mo3|mod|mp2|mp3|mpc|mptm|mt2|mulaw|ogg|okt|opus|ra|s3m|tak|tta|ulaw|wav|wma|wv|xm|xpk
"transcode to": [opus] produces an opus whenever transcoding is necessary (the best choice on Android and PCs) [awo] is opus in a weba file, good for iPhones (iOS 17.5 and newer) but Apple is still fixing some state-confusion bugs as of iOS 18.2.1 [caf] is opus in a caf file, good for iPhones (iOS 11 through 17), technically unsupported by Apple but works for the most part [mp3] -- the myth, the legend, the undying master of mediocre sound quality that definitely works everywhere
"tint" reduces the contrast of the playback bar
playlists
create and play m3u8 playlists -- see example text and player
click a file with the extension m3u or m3u8 (for example mixtape.m3u or touhou.m3u8 ) and you get two choices: Play / Edit
playlists can include songs across folders anywhere on the server, but filekeys/dirkeys are NOT supported, so the listener must have read-access or get-access to the files
creating a playlist
with a standalone mediaplayer or copyparty
you can use foobar2000, deadbeef, just about any standalone player should work -- but you might need to edit the filepaths in the playlist so they fit with the server-URLs
alternatively, you can create the playlist using copyparty itself:
open the [πΊ] media-player-settings tab and enable the [π»] create-playlist feature -- this adds two new buttons in the bottom-right tray, [π»add] and [π»copy] which appear when you listen to music, or when you select a few audiofiles
click the π»add button while a song is playing (or when you've selected some songs) and they'll be added to "the list" (you can't see it yet)
at any time, click π»copy to send the playlist to your clipboard you can then continue adding more songs if you'd like if you want to wipe the playlist and start from scratch, just refresh the page
create a new textfile, name it something.m3u and paste the playlist there
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)
textfile viewer
with realtime streaming of logfiles and such (demo) , and terminal colors work too
click -txt- next to a textfile to open the viewer, which has the following toolbar buttons:
βοΈ edit opens the textfile editor
opens the textfile editor π‘ follow starts monitoring the file for changes, streaming new lines in realtime similar to tail -f link directly to a file with tailing enabled by adding &tail to the textviewer URL
starts monitoring the file for changes, streaming new lines in realtime
markdown viewer
and there are two editors
there is a built-in extension for inline clickable thumbnails;
enable it by adding somewhere in the doc
somewhere in the doc add thumbnails with !th[l](your.jpg) where l means left-align ( r = right-align)
where means left-align ( = right-align) a single line with --- clears the float / inlining
clears the float / inlining in the case of README.md being displayed below a file listing, thumbnails will open in the gallery viewer
other notes,
the document preview has a max-width which is the same as an A4 paper when printed
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
you can link a particular timestamp in an audio file by adding it to the URL, such as &20 / &20s / &1m20 / &t=1:20 after the .../#af-c8960dab
enabling the audio equalizer can help make gapless albums fully gapless in some browsers (chrome), so consider leaving it on with all the values at zero
get a plaintext file listing by adding ?ls=t to a URL, or a compact colored one with ?ls=v (for unix terminals)
if you are using media hotkeys to switch songs and are getting tired of seeing the OSD popup which Windows doesn't let you disable, consider ./contrib/media-osd-bgone.ps1
click the bottom-left Ο to open a javascript prompt for debugging
files named .prologue.html / .epilogue.html will be rendered before/after directory listings unless --no-logues
files named descript.ion / DESCRIPT.ION are parsed and displayed in the file listing, or as the epilogue if nonstandard
files named README.md / readme.md will be rendered after directory listings unless --no-readme (but .epilogue.html takes precedence) and PREADME.md / preadme.md is shown above directory listings unless --no-readme or .prologue.html
README.md and *logue.html can contain placeholder values which are replaced server-side before embedding into directory listings; see --help-exp
searching
search by size, date, path/name, mp3-tags, ...
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:
make search queries by size / date / directory-path / filename , or...
/ / / , or... drag/drop a local file to see if the same contents exist somewhere on the server, see file-search
path/name queries are space-separated, AND'ed together, and words are negated with a - prefix, so for example:
path: shibayan -bossa finds all files where one of the folders contain shibayan but filters out any results where bossa exists somewhere in the path
finds all files where one of the folders contain but filters out any results where exists somewhere in the path name: demetori styx gives you good stuff
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:
config files ( -c some.conf ) can set additional commandline arguments; see ./docs/example.conf and ./docs/example2.conf
) can set additional commandline arguments; see ./docs/example.conf and ./docs/example2.conf kill -s USR1 (same as systemctl reload copyparty ) to reload accounts and volumes from config files without restarting or click the [reload cfg] button in the control-panel if the user has a /admin in any volume changes to the [global] config section requires a restart to take effect
(same as ) to reload accounts and volumes from config files without restarting
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.
if running in docker/podman, try this: docker run --rm -it copyparty/ac --help
or see this (probably outdated): https://ocv.me/copyparty/helptext.html
or if you prefer plaintext, https://ocv.me/copyparty/helptext.txt
zeroconf
announce enabled services on the LAN (pic) -- -z enables both mdns and ssdp
--z-on / --z-off limits the feature to certain networks
config file example:
[global] z # enable all zeroconf features (mdns, ssdp) zm # only enables mdns (does nothing since we already have z) z-on : 192.168.0.0/16, 10.1.2.0/24 # restrict to certain subnets
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 partybox.local if the machine's hostname is partybox unless --name specifies something else
and the web-UI will be available at http://partybox.local:3923/
if you want to get rid of the :3923 so you can use http://partybox.local/ instead then see listen on port 80 and 443
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:
maybe the discovery multicast was sent from an IP which does not intersect with the server subnets
print a qr-code (screenshot) for quick access, great between phones on android hotspots which keep changing the subnet
--qr enables it
enables it --qrs does https instead of http
does https instead of http --qrl lootbox/?pw=hunter2 appends to the url, linking to the lootbox folder with password hunter2
appends to the url, linking to the folder with password --qrz 1 forces 1x zoom instead of autoscaling to fit the terminal size 1x may render incorrectly on some terminals/fonts, but 2x should always work
forces 1x zoom instead of autoscaling to fit the terminal size
it uses the server hostname if mdns is enabled, 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)
based on pyftpdlib
needs a dedicated port (cannot share with the HTTP/HTTPS API)
uploads are not resumable -- delete and restart if necessary
runs in active mode by default, you probably want --ftp-pr 12000-13000 if you enable both ftp and ftps , the port-range will be divided in half some older software (filezilla on debian-stable) cannot passive-mode with TLS
login with any username + your password, or put your password in the username field
some recommended FTP / FTPS clients; wark = example password:
https://winscp.net/eng/download.php
https://filezilla-project.org/ struggles a bit with ftps in active-mode, but is fine otherwise
https://rclone.org/ does FTPS with tls=false explicit_tls=true
lftp -u k,wark -p 3921 127.0.0.1 -e ls
lftp -u k,wark -p 3990 127.0.0.1 -e 'set ssl:verify-certificate no; ls'
webdav server
with read-write support, supports winXP and later, macos, nautilus/gvfs ... a great 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:
login with any username + your password, or put your password in the username field (password field can be empty/whatever)
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)
note: if you have enabled IdP authentication then that may cause issues for some/most webdav clients; see the webdav section in the IdP docs
connecting to webdav from windows
using the GUI (winXP or later):
rightclick [my computer] -> [map network drive] -> Folder: http://192.168.123.1:3923/ on winXP only, click the Sign up for online storage hyperlink instead and put the URL there providing your password as the username is recommended; the password field can be anything or empty
the webdav client that's built into windows has the following list of bugs; you can avoid all of these by connecting with rclone instead:
win7+ doesn't actually send the password to the server when reauthenticating after a reboot unless you first try to login with an incorrect password and then switch to the correct password or just type your password into the username field instead to get around it entirely
connecting to a folder which allows anonymous read will make writing impossible, as windows has decided it doesn't need to login workaround: connect twice; first to a folder which requires auth, then to the folder you actually want, and leave both of those mounted or set the server-option --dav-auth to force password-auth for all webdav clients
win7+ may open a new tcp connection for every file and sometimes forgets to close them, eventually needing a reboot maybe NIC-related (??), happens with win10-ltsc on e1000e but not virtio
windows cannot access folders which contain filenames with invalid unicode or forbidden characters ( <>:"/\|?* ), or names ending with .
), or names ending with winxp cannot show unicode characters outside of some range latin-1 is fine, hiragana is not (not even as shift-jis on japanese xp)
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 π
based on partftpy
no accounts; read from world-readable folders, write to world-writable, overwrite in world-deletable
needs a dedicated port (cannot share with the HTTP/HTTPS API) run as root (or see below) to use the spec-recommended port 69 (nice)
can reply from a predefined portrange (good for firewalls)
only supports the binary/octet/image transfer mode (no netascii)
RFC 7440 is not supported, so will be extremely slow over WAN assuming default blksize (512), expect 1100 KiB/s over 100BASE-T, 400-500 KiB/s over wifi, 200 on bad wifi
supported, so will be extremely slow over WAN
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;
on linux: iptables -t nat -A PREROUTING -i eth0 -p udp --dport 69 -j REDIRECT --to-port 3969
some recommended TFTP clients:
curl (cross-platform, read/write) get: curl --tftp-blksize 1428 tftp://127.0.0.1:3969/firmware.bin put: curl --tftp-blksize 1428 -T firmware.bin tftp://127.0.0.1:3969/
windows: tftp.exe (you probably already have it) tftp -i 127.0.0.1 put firmware.bin
(you probably already have it) linux: tftp-hpa , atftp atftp --option "blksize 1428" 127.0.0.1 3969 -p -l firmware.bin -r firmware.bin tftp -v -m binary 127.0.0.1 3969 -c put firmware.bin
,
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
newer versions of impacket will hopefully work just fine but there is monkeypatching so maybe not
some BIG WARNINGS specific to SMB/CIFS, in decreasing importance:
not entirely confident that read-only is read-only
the smb backend is not fully integrated with vfs, meaning there could be security issues (path traversal). Please use --smb-port (see below) and prisonparty or bubbleparty account passwords work per-volume as expected, and so does account permissions (read/write/move/delete), but --smbw must be given to allow write-access from smb shadowing probably works as expected but no guarantees
(see below) and prisonparty or bubbleparty
and some minor issues,
clients only see the first ~400 files in big folders; this was originally due to impacket#1433 which was fixed in impacket-0.12, so you can disable the workaround with --smb-nwa-1 but then you get unacceptably poor performance instead
hot-reload of server config ( /?reload=cfg ) does not include the [global] section (commandline args)
) does not include the section (commandline args) listens on the first IPv4 -i interface only (default = :: = 0.0.0.0 = all)
interface only (default = :: = 0.0.0.0 = all) login doesn't work on winxp, but anonymous access is ok -- remove all accounts from copyparty config for that to work win10 onwards does not allow connecting anonymously / without accounts
python3 only
slow (the builtin webdav support in windows is 5x faster, and rclone-webdav is 30x faster)
known client bugs:
on win7 only, --smb1 is much faster than smb2 (default) because it keeps rescanning folders on smb2 however smb1 is buggy and is not enabled by default on win10 onwards
is much faster than smb2 (default) because it keeps rescanning folders on smb2 windows cannot access folders which contain filenames with invalid unicode or forbidden characters ( <>:"/\|?* ), or names ending with .
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;
on linux: iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 445 -j REDIRECT --to-port 3945
authenticate with one of the following:
username $username , password $password
, password username $password , password k
browser ux
tweaking the ui
set default sort order globally with --sort or per-volume with the sort volflag; specify one or more comma-separated columns to sort by, and prefix the column name with - for reverse sort the column names you can use are visible as tooltips when hovering over the column headers in the directory listing, for example href ext sz ts tags/.up_at tags/Circle tags/.tn tags/Artist tags/Title to sort in music order (album, track, artist, title) with filename as fallback, you could --sort tags/Circle,tags/.tn,tags/Artist,tags/Title,href to sort by upload date, first enable showing the upload date in the listing with -e2d -mte +.up_at and then --sort tags/.up_at
or per-volume with the volflag; specify one or more comma-separated columns to sort by, and prefix the column name with for reverse sort
see ./docs/rice for more, including how to add stuff (css/ /...) to the html 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
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 deduplication
enable symlink-based upload deduplication globally with --dedup or per-volume with volflag dedup
by default, when someone tries to upload a file that already exists on the server, the upload will be politely declined, and the server will copy the existing file over to where the upload would have gone
if you enable deduplication with --dedup then it'll create a symlink instead of a full copy, thus reducing disk space usage
on the contrary, if your server is hooked up to s3-glacier or similar storage where reading is expensive, and you cannot use --safe-dedup=1 because you have other software tampering with your files, so you want to entirely disable detection of duplicate data instead, then you can specify --no-clone globally or noclone as a volflag
warning: when enabling dedup, you should also:
enable indexing with -e2dsa or volflag e2dsa (see file indexing section below); strongly recommended
or volflag (see file indexing section below); strongly recommended ...and/or --hardlink-only to use hardlink-based deduplication instead of symlinks; see explanation below
it will not be safe to rename/delete files if you only enable dedup and none of the above; if you enable indexing then it is not necessary to also do hardlinks (but you may still want to)
by default, deduplication is done based on symlinks (symbolic links); these are tiny files which are pointers to the nearest full copy of the file
you can choose to use hardlinks instead of softlinks, globally with --hardlink-only or volflag hardlinkonly ;
advantages of using hardlinks:
hardlinks are more compatible with other software; they behave entirely like regular files
you can safely move and rename files using other file managers symlinks need to be managed by copyparty to ensure the destinations remain correct
advantages of using symlinks (default):
each symlink can have its own last-modified timestamp, but a single timestamp is shared by all hardlinks
symlinks make it more obvious to other software that the file is not a regular file, so this can be less dangerous hardlinks look like regular files, so other software may assume they are safe to edit without affecting the other copies
warning: if you edit the contents of a deduplicated file, then you will also edit all other copies of that file! This is especially surprising with hardlinks, because they look like regular files, but that same file exists in multiple locations
global-option --xlink / volflag xlink additionally enables deduplication across volumes, but this is probably buggy and not recommended
config file example:
[global] e2dsa # scan and index filesystem on startup dedup # symlink-based deduplication for all volumes [/media] /mnt/nas/media flags : hardlinkonly # this vol does hardlinks instead of symlinks
file indexing
enable music search, upload-undo, and better dedup
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:
-e2d enables file indexing on upload
enables file indexing on upload -e2ds also scans writable folders for new files on startup
also scans writable folders for new files on startup -e2dsa also scans all mounted volumes (including readonly ones)
also scans all mounted volumes (including readonly ones) -e2t enables metadata indexing on upload
enables metadata indexing on upload -e2ts also scans for tags in all files that don't have tags yet
also scans for tags in all files that don't have tags yet -e2tsr also deletes all existing tags, doing a full reindex
also deletes all existing tags, doing a full reindex -e2v verifies file integrity at startup, comparing hashes from the db
verifies file integrity at startup, comparing hashes from the db -e2vu patches the database with the new hashes from the filesystem
patches the database with the new hashes from the filesystem -e2vp panics and kills copyparty instead
the same arguments can be set as volflags, in addition to d2d , d2ds , d2t , d2ts , d2v for disabling:
-v ~/music::r:c,e2ds,e2tsr does a full reindex of everything on startup
does a full reindex of everything on startup -v ~/music::r:c,d2d disables all indexing, even if any -e2* are on
disables indexing, even if any are on -v ~/music::r:c,d2t disables all -e2t* (tags), does not affect -e2d*
disables all (tags), does not affect -v ~/music::r:c,d2ds disables on-boot scans; only index new uploads
disables on-boot scans; only index new uploads -v ~/music::r:c,d2ts same except only affecting tags
note:
upload-times can be displayed in the file listing by enabling the .up_at metadata key, either globally with -e2d -mte +.up_at or per-volume with volflags e2d,mte=+.up_at (will have a ~17% performance impact on directory listings)
metadata key, either globally with or per-volume with volflags (will have a ~17% performance impact on directory listings) e2tsr is probably always overkill, since e2ds / e2dsa would pick up any file modifications and e2ts would then reindex those, unless there is a new copyparty version with new parsers and the release note says otherwise
config file example (these options are recommended btw):
[global] e2dsa # scan and index all files in all volumes on startup e2ts # check newly-discovered or uploaded files for media tags
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:
initial indexing is way faster, especially when the volume is on a network disk
makes it impossible to file-search
if someone uploads the same file contents, the upload will not be detected as a dupe, so it will not get symlinked or rejected
similarly, you can fully ignore files/folders using --no-idx [...] and :c,noidx=\.iso$
NOTE: no-idx and/or no-hash prevents deduplication of those files
when running on macos, all the usual apple metadata files are excluded by default
if you set --no-hash [...] globally, you can enable hashing for specific volumes using flag :c,nohash=
to exclude certain filepaths from search-results, use --srch-excl or volflag srch_excl instead of --no-idx , for example --srch-excl 'password|logs/[0-9]'
config file example:
[/games] /mnt/nas/games flags : noidx : \.iso$ # skip indexing iso-files srch_excl : password|logs/[0-9] # filter search results
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
symlinks are permitted with xvol if they point into another volume where the user has the same level of access
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, ...)
note: folder-thumbnails are selected during filesystem indexing, so periodic rescans can be used to keep them accurate as images are uploaded/deleted (or manually do a rescan with the reload button in the controlpanel)
config file example:
[global] re-maxage : 3600 [/pics] /mnt/nas/pics flags : scan : 900
upload rules
set upload rules using volflags, some examples:
:c,sz=1k-3m sets allowed filesize between 1 KiB and 3 MiB inclusive (suffixes: b , k , m , g )
sets allowed filesize between 1 KiB and 3 MiB inclusive (suffixes: , , , ) :c,df=4g block uploads if there would be less than 4 GiB free disk space afterwards
block uploads if there would be less than 4 GiB free disk space afterwards :c,vmaxb=1g block uploads if total volume size would exceed 1 GiB afterwards
block uploads if total volume size would exceed 1 GiB afterwards :c,vmaxn=4k block uploads if volume would contain more than 4096 files afterwards
block uploads if volume would contain more than 4096 files afterwards :c,nosub disallow uploading into subdirectories; goes well with rotn and rotf :
disallow uploading into subdirectories; goes well with and : :c,rotn=1000,2 moves uploads into subfolders, up to 1000 files in each folder before making a new one, two levels deep (must be at least 1)
moves uploads into subfolders, up to 1000 files in each folder before making a new one, two levels deep (must be at least 1) :c,rotf=%Y/%m/%d/%H enforces files to be uploaded into a structure of subfolders according to that date format if someone uploads to /foo/bar the path would be rewritten to /foo/bar/2021/08/06/23 for example but the actual value is not verified, just the structure, so the uploader can choose any values which conform to the format string just to avoid additional complexity in up2k which is enough of a mess already
enforces files to be uploaded into a structure of subfolders according to that date format :c,lifetime=300 delete uploaded files when they become 5 minutes old
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
:c,maxn=250,3600 allows 250 files over 1 hour from each IP (tracked per-volume)
allows 250 files over 1 hour from each IP (tracked per-volume) :c,maxb=1g,300 allows 1 GiB total over 5 minutes from each IP (tracked per-volume)
notes:
vmaxb and vmaxn requires either the e2ds volflag or -e2dsa global-option
config file example:
[/inc] /mnt/nas/uploads accs : w : * # anyone can upload here rw : ed # only user "ed" can read-write flags : e2ds # filesystem indexing is required for many of these: sz : 1k-3m # accept upload only if filesize in this range df : 4g # free disk space cannot go lower than this vmaxb : 1g # volume can never exceed 1 GiB vmaxn : 4k # ...or 4000 files, whichever comes first nosub # must upload to toplevel folder lifetime : 300 # uploads are deleted after 5min maxn : 250,3600 # each IP can upload 250 files in 1 hour maxb : 1g,300 # each IP can upload 1 GiB over 5 minutes
compress uploads
files can be autocompressed on upload, either on user-request (if config allows) or forced by server-config
volflag gz allows gz compression
allows gz compression volflag xz allows lzma compression
allows lzma compression volflag pk forces compression on all files
compression on all files url parameter pk requests compression with server-default algorithm
requests compression with server-default algorithm url parameter gz or xz requests compression with a specific algorithm
or requests compression with a specific algorithm url parameter xz requests xz compression
things to note,
the gz and xz arguments take a single optional argument, the compression level (range 0 to 9)
and arguments take a single optional argument, the compression level (range 0 to 9) the pk volflag takes the optional argument ALGORITHM,LEVEL which will then be forced for all uploads, for example gz,9 or xz,0
volflag takes the optional argument which will then be forced for all uploads, for example or default compression is gzip level 9
all upload methods except up2k are supported
the files will be indexed after compression, so dupe-detection and file-search will not work as expected
some examples,
-v inc:inc:w:c,pk=xz,0
folder named inc, shared at inc, write-only for everyone, forces xz compression at level 0
folder named inc, shared at inc, write-only for everyone, forces xz compression at level 0 -v inc:inc:w:c,pk
same write-only inc, but forces gz compression (default) instead of xz
same write-only inc, but forces gz compression (default) instead of xz -v inc:inc:w:c,gz
allows (but does not force) gz compression if client uploads to /inc?pk or /inc?gz or /inc?gz=4
other flags
:c,magic enables filetype detection for nameless uploads, same as --magic needs https://pypi.org/project/python-magic/ python3 -m pip install --user -U python-magic on windows grab this instead python3 -m pip install --user -U python-magic-bin
enables filetype detection for nameless uploads, same as
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:
--hist ~/.cache/copyparty -v ~/music::r:c,hist=- sets ~/.cache/copyparty as the default place to put volume info, but ~/music gets the regular .hist subfolder ( - restores default behavior)
by default, the per-volume up2k.db sqlite3-database for -e2d and -e2t is stored next to the thumbnails according to the --hist option, but the global-option --dbpath and/or volflag dbpath can be used to put the database somewhere else
if your storage backend is unreliable (NFS or bad HDDs), you can specify one or more "landmarks" to look for before doing anything database-related. A landmark is a file which is always expected to exist inside the volume. This avoids spurious filesystem rescans in the event of an outage. One line per landmark (see example below)
note:
putting the hist-folders on an SSD is strongly recommended for performance
markdown edits are always stored in a local .hist subdirectory
subdirectory on windows the volflag path is cyglike, so /c/temp means C:\temp but use regular paths for --hist you can use cygpaths for volumes too, -v C:\Users::r and -v /c/users::r both work
means but use regular paths for
config file example:
[global] hist : ~/.cache/copyparty # put db/thumbs/etc. here by default [/pics] /mnt/nas/pics flags : hist : - # restore the default (/mnt/nas/pics/.hist/) hist : /mnt/nas/cache/pics/ # can be absolute path landmark : me.jpg # /mnt/nas/pics/me.jpg must be readable to enable db landmark : info/a.txt^=ok # and this textfile must start with "ok"
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:
-v ~/music::r:c,mte=title,artist indexes and displays title followed by artist
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...
is about 20x slower than Mutagen
catches a few tags that Mutagen doesn't melodic key, video resolution, framerate, pixfmt
avoids pulling any GPL code into copyparty
more importantly runs FFprobe on incoming files which is bad if your FFmpeg has a cve
--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)
-mtp .bpm=~/bin/audio-bpm.py will execute ~/bin/audio-bpm.py with the audio file as argument 1 to provide the .bpm tag, if that does not exist in the audio metadata
will execute with the audio file as argument 1 to provide the tag, if that does not exist in the audio metadata -mtp key=f,t5,~/bin/audio-key.py uses ~/bin/audio-key.py to get the key tag, replacing any existing metadata tag ( f, ), aborting if it takes longer than 5sec ( t5, )
uses to get the tag, replacing any existing metadata tag ( ), aborting if it takes longer than 5sec ( ) -v ~/music::r:c,mtp=.bpm=~/bin/audio-bpm.py:c,mtp=key=f,t5,~/bin/audio-key.py both as a per-volume config wow this is getting ugly
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)
"audio file" also means videos btw, as long as there is an audio stream
-mtp ext=an,~/bin/file-ext.py runs ~/bin/file-ext.py to get the ext tag only if file is not audio ( an )
runs to get the tag only if file is not audio ( ) -mtp arch,built,ver,orig=an,eexe,edll,~/bin/exe.py runs ~/bin/exe.py to get properties about windows-binaries only if file is not audio ( an ) and file extension is exe or dll
runs to get properties about windows-binaries only if file is not audio ( ) and file extension is exe or dll if you want to daisychain parsers, use the p flag to set processing order -mtp foo=p1,~/a.py runs before -mtp foo=p2,~/b.py and will forward all the tags detected so far as json to the stdin of b.py
flag to set processing order option c0 disables capturing of stdout/stderr, so copyparty will not receive any tags from the process at all -- instead the invoked program is free to print whatever to the console, just using copyparty as a launcher c1 captures stdout only, c2 only stderr, and c3 (default) captures both
disables capturing of stdout/stderr, so copyparty will not receive any tags from the process at all -- instead the invoked program is free to print whatever to the console, just using copyparty as a launcher you can control how the parser is killed if it times out with option kt killing the entire process tree (default), km just the main process, or kn let it continue running until copyparty is terminated
if something doesn't work, try --mtag-v for verbose error messages
config file example; note that mtp is an additive option so all of the mtp options will take effect:
[/music] /mnt/nas/music flags : mtp : .bpm=~/bin/audio-bpm.py # assign ".bpm" (numeric) with script mtp : key=f,t5,~/bin/audio-key.py # force/overwrite, 5sec timeout mtp : ext=an,~/bin/file-ext.py # will only run on non-audio files mtp : arch,built,ver,orig=an,eexe,edll,~/bin/exe.py # only exe/dll
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
zeromq
event-hooks can send zeromq messages instead of running programs
to send a 0mq message every time a file is uploaded,
--xau zmq:pub:tcp://*:5556 sends a PUB to any/all connected SUB clients
sends a PUB to any/all connected SUB clients --xau t3,zmq:push:tcp://*:5557 sends a PUSH to exactly one connected PULL client
sends a PUSH to exactly one connected PULL client --xau t3,j,zmq:req:tcp://localhost:5555 sends a REQ to the connected REP client
the PUSH and REQ examples have t3 (timeout after 3 seconds) because they block if there's no clients to talk to
the REQ example does t3,j to send extended upload-info as json instead of just the filesystem-path
see zmq-recv.py if you need something to receive the messages with
config file example; note that the hooks are additive options, so all of the xau options will take effect:
[global] xau : zmq:pub:tcp://*:5556` # send a PUB to any/all connected SUB clients xau : t3,zmq:push:tcp://*:5557` # send PUSH to exactly one connected PULL cli xau : t3,j,zmq:req:tcp://localhost:5555` # send REQ to the connected REP cli
upload events
the older, more powerful approach (examples):
-v /mnt/inc:inc:w:c,e2d,e2t,mte=+x1:c,mtp=x1=ad,kn,/usr/bin/notify-send
that was the commandline example; here's the config file example:
[/inc] /mnt/inc accs : w : * flags : e2d, e2t # enable indexing of uploaded files and their tags mte : +x1 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:
non-blocking and multithreaded; doesn't hold other uploads back
you get access to tags from FFmpeg and other mtp parsers
only trigger on new unique files, not dupes
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
for reference, if you were to do this using event hooks instead, it would be like this: -e2d --xau notify-send,hello,--
handlers
redefine behavior with plugins (examples)
replace 404 and 403 errors with something completely different (that's it for now)
as for client-side stuff, there is plugins for modifying UI/UX
ip auth
autologin based on IP range (CIDR) , using the global-option --ipu
for example, if everyone with an IP that starts with 192.168.123 should automatically log in as the user spartacus , then you can either specify --ipu=192.168.123.0/24=spartacus as a commandline option, or put this in a config file:
[global] ipu : 192.168.123.0/24=spartacus
repeat the option to map additional subnets
be careful with this one! if you have a reverseproxy, then you definitely want to make sure you have real-ip configured correctly, and it's probably a good idea to nullmap the reverseproxy's IP just in case; so if your reverseproxy is sending requests from 172.24.27.9 then that would be --ipu=172.24.27.9/32=
identity providers
replace copyparty passwords with oauth and such
you can disable the built-in password-based login system, 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
the regular config-defined users will be used as a fallback for requests which don't include a valid (trusted) IdP username header
some popular identity providers are Authelia (config-file based) and 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
not compatible with identity providers
must be enabled with --chpw because account-sharing is a popular usecase if you want to enable the feature but deny password-changing for a specific list of accounts, you can do that with --chpw-no name1,name2,name3,...
to perform a password reset, edit the server config and give the user another password there, then do a config reload or server restart
the custom passwords are kept in a textfile at filesystem-path --chpw-db , by default chpw.json in the copyparty config folder if you run multiple copyparty instances with different users you almost definitely want to specify separate DBs for each instance if password hashing is enabled, the passwords in the db are also hashed ...which means that all user-defined passwords will be forgotten if you change password-hashing settings
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
if copyparty is unable to access the local folder that rclone/geesefs/JuiceFS provides (for example if it looks invisible) then you may need to run rclone with --allow-other and/or enable user_allow_other in /etc/fuse.conf
you will probably get decent speeds with the default config, however most likely restricted to using one TCP connection per file, so the upload-client won't be able to send multiple chunks in parallel
before v1.13.5 it was recommended to use the volflag sparse to force-allow multiple chunks in parallel; this would improve the upload-speed from 1.5 MiB/s to over 80 MiB/s at the risk of provoking latent bugs in S3 or JuiceFS. But v1.13.5 added chunk-stitching, so this is now probably much less important. On the contrary, nosparse may now increase performance in some cases. Please try all three options (default, sparse , nosparse ) as the optimal choice depends on your network conditions and software stack (both the FUSE-driver and cloud-server)
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
if you've experimented with this and made interesting observations, please share your findings so we can add a section with specific recommendations :-)
hiding from google
tell search engines you don't wanna be indexed, either using the good old robots.txt or through copyparty settings:
--no-robots adds HTTP ( X-Robots-Tag ) and HTML ( ) headers with noindex, nofollow globally
adds HTTP ( ) and HTML ( ) headers with globally volflag [...]:c,norobots does the same thing for that single volume
does the same thing for that single volume volflag [...]:c,robots ALLOWS search-engine crawling for that volume, even if --no-robots is set globally
also, --force-js disables the plain HTML folder listing, making things harder to parse for some search engines -- note that crawlers which understand javascript (such as google) will not be affected
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
the classname of the HTML tag is set according to the selected theme, which is used to set colors as css variables ++
each theme generally has a dark theme (even numbers) and a light theme (odd numbers), showing in pairs
the first theme (theme 0 and 1) is html.a , second theme (2 and 3) is html.b
, second theme (2 and 3) is if a light theme is selected, html.y is set, otherwise html.z is
is set, otherwise is so if the dark edition of the 2nd theme is selected, you use any of html.b , html.z , html.bz to specify rules
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
see running on windows for a fancy windows setup or use any of the examples below, just replace python copyparty-sfx.py with copyparty.exe if you're using the exe edition
allow anyone to download or upload files into the current folder:
python copyparty-sfx.py enable searching and music indexing with -e2dsa -e2ts start an FTP server on port 3921 with --ftp 3921 announce it on your LAN with -z so it appears in windows/Linux file managers
anyone can upload, but nobody can see any files (even the uploader):
python copyparty-sfx.py -e2dsa -v .::w block uploads if there's less than 4 GiB free disk space with --df 4 show a popup on new uploads with --xau bin/hooks/notify.py
anyone can upload, and receive "secret" links for each upload they do:
python copyparty-sfx.py -e2dsa -v .::wG:c,fk=8
anyone can browse ( r ), only kevin (password okgo ) can upload/move/delete ( A ) files:
python copyparty-sfx.py -e2dsa -a kevin:okgo -v .::r:A,kevin
read-only music server:
python copyparty-sfx.py -v /mnt/nas/music:/music:r -e2dsa -e2ts --no-robots --force-js --theme 2 ...with bpm and key scanning
-mtp .bpm=f,audio-bpm.py -mtp key=f,audio-key.py ...with a read-write folder for kevin whose password is okgo
-a kevin:okgo -v /mnt/nas/inc:/inc:rw,kevin ...with logging to disk
-lo log/cpp-%Y-%m%d-%H%M%S.txt.xz
listen on port 80 and 443
become a real webserver which people can access by just going to your IP or domain without specifying a port
if you're on windows, then you just need to add the commandline argument -p 80,443 and you're done! nice
if you're on macos, sorry, I don't know
if you're on Linux, you have the following 4 options:
option 1: set up a reverse-proxy -- this one makes a lot of sense if you're running on a proper headless server, because that way you get real HTTPS too
option 2: NAT to port 3923 -- this is cumbersome since you'll need to do it every time you reboot, and the exact command may depend on your linux distribution: iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3923 iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3923
option 3: disable the security policy which prevents the use of 80 and 443; this is probably fine: setcap CAP_NET_BIND_SERVICE=+eip $(realpath $(which python)) python copyparty-sfx.py -p 80,443
option 4: run copyparty as root (please don't)
running copyparty next to other websites hosted on an existing webserver such as nginx, caddy, or apache
you can either:
give copyparty its own domain or subdomain (recommended)
or do location-based proxying, using --rp-loc=/stuff to tell copyparty where it is mounted -- has a slight performance cost and higher chance of bugs if copyparty says incorrect --rp-loc or webserver config; expected vpath starting with [...] it's likely because the webserver is stripping away the proxy location from the request URLs -- see the ProxyPass in the apache example below
to tell copyparty where it is mounted -- has a slight performance cost and higher chance of bugs
when running behind a reverse-proxy (this includes services like cloudflare), it is important to configure real-ip correctly, as many features rely on knowing the client's IP. Look out for red and yellow log messages which explain how to do this. But basically, set --xff-hdr to the name of the http header to read the IP from (usually x-forwarded-for , but cloudflare uses cf-connecting-ip ), and then --xff-src to the IP of the reverse-proxy so copyparty will trust the xff-hdr. Note that --rp-loc in particular will not work at all unless you do this
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
warning: nginx-QUIC (HTTP/3) is still experimental and can make uploads much slower, so HTTP/1.1 is recommended for now
nginx-QUIC (HTTP/3) is still experimental and can make uploads much slower, so HTTP/1.1 is recommended for now depending on server/client, HTTP/1.1 can also be 5x faster than HTTP/2
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 / reverse-proxy configs:
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...)
reverse-proxy performance
most reverse-proxies support connecting to copyparty either using uds/unix-sockets ( /dev/shm/party.sock , faster/recommended) or using tcp ( 127.0.0.1 )
with copyparty listening on a uds / unix-socket / unix-domain-socket and the reverse-proxy connecting to that:
index.html upload download software 28'900 req/s 6'900 MiB/s 7'400 MiB/s no-proxy 18'750 req/s 3'500 MiB/s 2'370 MiB/s haproxy 9'900 req/s 3'750 MiB/s 2'200 MiB/s caddy 18'700 req/s 2'200 MiB/s 1'570 MiB/s nginx 9'700 req/s 1'750 MiB/s 1'830 MiB/s apache 9'900 req/s 1'300 MiB/s 1'470 MiB/s lighttpd
when connecting the reverse-proxy to 127.0.0.1 instead (the basic and/or old-fasioned way), speeds are a bit worse:
index.html upload download software 21'200 req/s 5'700 MiB/s 6'700 MiB/s no-proxy 14'500 req/s 1'700 MiB/s 2'170 MiB/s haproxy 11'100 req/s 2'750 MiB/s 2'000 MiB/s traefik 8'400 req/s 2'300 MiB/s 1'950 MiB/s caddy 13'400 req/s 1'100 MiB/s 1'480 MiB/s nginx 8'400 req/s 1'000 MiB/s 1'000 MiB/s apache 6'500 req/s 1'270 MiB/s 1'500 MiB/s lighttpd
in summary, haproxy > caddy > traefik > nginx > apache > lighttpd , and use uds when possible (traefik does not support it yet)
if these results are bullshit because my config exampels are bad, please submit corrections!
permanent cloudflare tunnel
if you have a domain and want to get your copyparty online real quick, either from your home-PC behind a CGNAT or from a server without an existing reverse-proxy setup, one approach is to create a Cloudflare Tunnel (formerly "Argo Tunnel")
I'd recommend making a Locally-managed tunnel for more control, but if you prefer to make a Remotely-managed tunnel then this is currently how:
cloudflare dashboard Β» zero trust Β» networks Β» tunnels Β» create a tunnel Β» cloudflared Β» choose a cool subdomain and leave the path blank, and use service type = http and URL = 127.0.0.1:3923
and if you want to just run the tunnel without installing it, skip the cloudflared service install BASE64 step and instead do cloudflared --no-autoupdate tunnel run --token BASE64
NOTE: since people will be connecting through cloudflare, as mentioned in real-ip you should run copyparty with --xff-hdr cf-connecting-ip to detect client IPs correctly
config file example:
[global] xff-hdr : cf-connecting-ip
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,
cpp_uptime_seconds time since last copyparty restart
time since last copyparty restart cpp_boot_unixtime_seconds same but as an absolute timestamp
same but as an absolute timestamp cpp_active_dl number of active downloads
number of active downloads cpp_http_conns number of open http(s) connections
number of open http(s) connections cpp_http_reqs number of http(s) requests handled
number of http(s) requests handled cpp_sus_reqs number of 403/422/malicious requests
number of 403/422/malicious requests cpp_active_bans number of currently banned IPs
number of currently