copyparty 1.16.11__tar.gz → 1.16.13__tar.gz

{copyparty-1.16.11 → copyparty-1.16.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: copyparty
-Version: 1.16.11
+Version: 1.16.13
 Summary:   Portable file server with accelerated resumable uploads, deduplication, WebDAV, FTP, zeroconf, media indexer, video thumbnails, audio transcoding, and write-only folders
 Author-email: ed <copyparty@ocv.me>
 License: MIT
@@ -201,6 +201,9 @@ just run **[copyparty-sfx.py](https://github.com/9001/copyparty/releases/latest/
 * or if you are on android, [install copyparty in termux](#install-on-android)
 * or maybe you have a [synology nas / dsm](./docs/synology-dsm.md)
 * or if your computer is messed up and nothing else works, [try the pyz](#zipapp)
+* or if you don't trust copyparty yet and want to isolate it a little, then...
+  * ...maybe [prisonparty](./bin/prisonparty.sh) to create a tiny [chroot](https://wiki.archlinux.org/title/Chroot) (very portable),
+  * ...or [bubbleparty](./bin/bubbleparty.sh) to wrap it in [bubblewrap](https://github.com/containers/bubblewrap) (much better)
 * or if you prefer to [use docker](./scripts/docker/) 🐋 you can do that too
   * docker has all deps built-in, so skip this step:
 
@@ -312,7 +315,7 @@ also see [comparison to similar software](./docs/versus.md)
   * ☑ search by name/path/date/size
   * ☑ [search by ID3-tags etc.](#searching)
 * client support
-  * ☑ [folder sync](#folder-sync)
+  * ☑ [folder sync](#folder-sync) (one-way only; full sync will never be supported)
   * ☑ [curl-friendly](https://user-images.githubusercontent.com/241032/215322619-ea5fd606-3654-40ad-94ee-2bc058647bb2.png)
   * ☑ [opengraph](#opengraph) (discord embeds)
 * markdown
@@ -529,6 +532,40 @@ examples:
 
 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`
+
+```yaml
+[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
 
@@ -536,6 +573,8 @@ 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
 
@@ -547,6 +586,19 @@ a client can request to see dotfiles in directory listings if global option `-ed
 
 dotfiles do not appear in search results unless one of the above is true, **and** the global option / volflag `dotsrch` is set
 
+config file example, where the same permission to see dotfiles is given in two different ways just for reference:
+
+```yaml
+[/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
 
@@ -669,6 +721,26 @@ enabling `multiselect` lets you click files to select them, and then shift-click
 * `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`
 
+to show `/icons/exe.png` as the thumbnail for all .exe files, `--ext-th=exe=/icons/exe.png` (optionally as a volflag)
+
+config file example:
+
+```yaml
+[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
+    th-covers:  folder.png,folder.jpg,cover.png,cover.jpg  # the default
+```
+
 
 ## zip downloads
 
@@ -793,6 +865,14 @@ 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:
+
+```yaml
+[global]
+  e2d            # enable up2k database (remember uploads)
+  unpost: 43200  # 12 hours (default)
+```
+
 
 ### self-destruct
 
@@ -958,6 +1038,15 @@ will show uploader IP and upload-time if the visitor has the admin permission
 
 note that the [🧯 unpost](#unpost) feature is better suited for viewing *your own* recent uploads, as it includes the option to undo/delete them
 
+config file example:
+
+```yaml
+[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
 
@@ -1102,7 +1191,16 @@ using arguments or config files, or a mix of both:
 
 announce enabled services on the LAN ([pic](https://user-images.githubusercontent.com/241032/215344737-0eae8d98-9496-4256-9aa8-cd2f6971810d.png))  -- `-z` enables both [mdns](#mdns) and [ssdp](#ssdp)
 
-* `--z-on` / `--z-off`' limits the feature to certain networks
+* `--z-on` / `--z-off` limits the feature to certain networks
+
+config file example:
+
+```yaml
+[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
@@ -1243,7 +1341,7 @@ dependencies: `python3 -m pip install --user -U impacket==0.11.0`
 
 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](./bin/prisonparty.sh)
+* 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](./bin/prisonparty.sh) or [bubbleparty](./bin/bubbleparty.sh)
   * 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](#shadowing) probably works as expected but no guarantees
 
@@ -1329,6 +1427,18 @@ advantages of using symlinks (default):
 
 global-option `--xlink` / volflag `xlink` additionally enables deduplication across volumes, but this is probably buggy and not recommended
 
+config file example:
+
+```yaml
+[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
@@ -1360,6 +1470,14 @@ note:
 * `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
 * the rescan button in the admin panel has no effect unless the volume has `-e2ds` or higher
 
+config file example (these options are recommended btw):
+
+```yaml
+[global]
+  e2dsa  # scan and index all files in all volumes on startup
+  e2ts   # check newly-discovered or uploaded files for media tags
+```
+
 ### exclude-patterns
 
 to save some time,  you can provide a regex pattern for filepaths to only index by filename/path/size/last-modified (and not the hash of the file contents) by setting `--no-hash '\.iso$'` or the volflag `:c,nohash=\.iso$`, this has the following consequences:
@@ -1369,12 +1487,24 @@ to save some time,  you can provide a regex pattern for filepaths to only index
 
 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:
+
+```yaml
+[/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
@@ -1395,6 +1525,20 @@ argument `--re-maxage 60` will rescan all volumes every 60 sec, same as volflag
 
 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:
+
+```yaml
+[global]
+  re-maxage: 3600
+
+[/pics]
+  /mnt/nas/pics
+  flags:
+    scan: 900
+```
+
 
 ## upload rules
 
@@ -1420,6 +1564,26 @@ you can also set transaction limits which apply per-IP and per-volume, but these
 notes:
 * `vmaxb` and `vmaxn` requires either the `e2ds` volflag or `-e2dsa` global-option
 
+config file example:
+
+```yaml
+[/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
 
@@ -1465,10 +1629,24 @@ this can instead be kept in a single place using the `--hist` argument, or the `
 * `--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)
 
 note:
+* putting the hist-folders on an SSD is strongly recommended for performance
 * markdown edits are always stored in a local `.hist` 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
 
+config file example:
+
+```yaml
+[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
+```
+
 
 ## metadata from audio files
 
@@ -1520,6 +1698,18 @@ copyparty can invoke external programs to collect additional metadata for files
 
 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:
+
+```yaml
+[/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
 
@@ -1548,13 +1738,35 @@ the PUSH and REQ examples have `t3` (timeout after 3 seconds) because they block
 
 see [zmq-recv.py](https://github.com/9001/copyparty/blob/hovudstraum/bin/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:
+
+```yaml
+[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](./bin/mtag/)):
 
 ```
--v /mnt/inc:inc:w:c,mte=+x1:c,mtp=x1=ad,kn,/usr/bin/notify-send
+-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:
+
+```yaml
+[/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`)
@@ -1568,6 +1780,8 @@ note that this is way more complicated than the new [event hooks](#event-hooks)
 
 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
 
@@ -1575,6 +1789,8 @@ redefine behavior with plugins ([examples](./bin/handlers/))
 
 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](./contrib/plugins/)
+
 
 ## ip auth
 
@@ -1636,6 +1852,8 @@ 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](https://rclone.org/) / [geesefs](https://github.com/yandex-cloud/geesefs) / [JuiceFS](https://juicefs.com/en/) 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](https://github.com/9001/copyparty/releases/tag/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)
@@ -1896,7 +2114,7 @@ change the association of a file extension
 
 using commandline args, you can do something like `--mime gif=image/jif` and `--mime ts=text/x.typescript` (can be specified multiple times)
 
-in a config-file, this is the same as:
+in a config file, this is the same as:
 
 ```yaml
 [global]
@@ -2156,6 +2374,8 @@ NOTE: curl will not send the original filename if you use `-T` combined with url
 
 sync folders to/from copyparty
 
+NOTE: full bidirectional sync, like what [nextcloud](https://docs.nextcloud.com/server/latest/user_manual/sv/files/desktop_mobile_sync.html) and [syncthing](https://syncthing.net/) does, will never be supported! Only single-direction sync (server-to-client, or client-to-server) is possible with copyparty
+
 the commandline uploader [u2c.py](https://github.com/9001/copyparty/tree/hovudstraum/bin#u2cpy) with `--dr` is the best way to sync a folder to copyparty; verifies checksums and does files in parallel, and deletes unexpected files on the server after upload has finished which makes file-renames really cheap (it'll rename serverside and skip uploading)
 
 alternatively there is [rclone](./docs/rclone.md) which allows for bidirectional sync and is *way* more flexible (stream files straight from sftp/s3/gcs to copyparty, ...), although there is no integrity check and it won't work with files over 100 MiB if copyparty is behind cloudflare