Security Best Practices

Overview

Security is critical when running a file server accessible over the network. This guide covers authentication, HTTPS setup, permission models, and hardening techniques.

Running copyparty with default settings gives everyone read-write access. Always configure proper authentication and permissions before exposing to the internet.

Authentication

Basic Authentication

Define user accounts and passwords:

[accounts]
  alice: password123
  bob: hunter2
  admin: secure_password_here

Never use weak passwords or default credentials in production.

Password Hashing

Store passwords as hashes instead of plaintext:

Enable password hashing

[global]
  ah-alg: argon2  # Use Argon2 hashing

Generate hashed passwords

Start copyparty with plaintext passwords - it will print hashed versions:

copyparty -c /etc/copyparty.conf

Output:

replace plaintext passwords with these:
  alice: $argon2id$v=19$m=262144,t=8,p=1$...
  bob: $argon2id$v=19$m=262144,t=8,p=1$...

Update configuration

Replace plaintext passwords with hashes:

[accounts]
  alice: $argon2id$v=19$m=262144,t=8,p=1$...
  bob: $argon2id$v=19$m=262144,t=8,p=1$...

Interactive hashing (optional)

Use --ah-cli to hash passwords interactively:

copyparty --ah-alg argon2 --ah-cli

This never writes plaintext passwords to disk.

Default Argon2 settings use ~256 MiB RAM and take ~0.4 seconds per password on a decent laptop.

Important for username mode:

[global]
  usernames  # Enable username requirement

When hashing passwords with --usernames enabled, provide as username:password:

echo "alice:password123" | copyparty --ah-alg argon2 --ah-cli

Permission Model

Copyparty uses fine-grained permissions:

Permission	Description
`r`	Read: browse folders, download files, zip/tar
`w`	Write: upload files, move files into folder
`m`	Move: move files/folders from this folder
`d`	Delete: delete files/folders
`a`	Admin: see upload times, IPs, reload config
`.`	Dots: see dotfiles in listings
`g`	Get: download files only (no browsing)
`G`	Upget: upload + get filekeys
`h`	HTML: serve index.html, hide listings

Shortcuts:

A = rwmda. (all permissions)

Example Permission Configurations

Public Read, Private Write

[accounts]
  admin: hashed_password_here

[/]
  /srv/public
  accs:
    r: *        # Everyone can read
    rwmda: admin  # Only admin can write/delete/manage

Multiple User Tiers

[accounts]
  alice: pass1
  bob: pass2
  charlie: pass3

[groups]
  editors: alice, bob

[/documents]
  /srv/docs
  accs:
    r: *          # Everyone can read
    rw: @editors  # Alice and Bob can write
    rwmda: charlie  # Charlie has full control

Upload-Only Folder

[/uploads]
  /srv/uploads
  accs:
    w: *        # Anyone can upload
    r: alice    # Only alice can see/download
    rwmda: admin  # Admin has full control

Write-Only with Filekeys

[/dropbox]
  /srv/dropbox
  accs:
    wG: *       # Anyone can upload and get their filekeys
    rwmda: admin
  flags:
    fk: 6       # 6-character filekeys

Users can upload but not browse. They receive unique URLs to access their uploads.

IP-Based Authentication

Auto-login users from specific IP ranges:

[accounts]
  localuser: password
  alice: password

[global]
  ipa: [email protected]/24  # Auto-login from LAN
  ipa: [email protected]            # Auto-login from specific IP

Restrict users to specific IPs:

[global]
  ipa-nm: [email protected]/8  # Alice can only connect from 10.x.x.x

HTTPS/TLS Configuration

Using a Reverse Proxy (Recommended)

Let nginx, Apache, or Caddy handle HTTPS:

[global]
  i: 127.0.0.1  # Only accept local connections
  xff-hdr: x-forwarded-for
  rproxy: 1

See Reverse Proxy Setup for details.

Native HTTPS with cfssl

Install cfssl

# Download cfssl tools
wget https://github.com/cloudflare/cfssl/releases/latest/download/cfssl_linux_amd64
wget https://github.com/cloudflare/cfssl/releases/latest/download/cfssljson_linux_amd64
wget https://github.com/cloudflare/cfssl/releases/latest/download/cfssl-certinfo_linux_amd64

# Install
sudo mv cfssl_linux_amd64 /usr/local/bin/cfssl
sudo mv cfssljson_linux_amd64 /usr/local/bin/cfssljson
sudo mv cfssl-certinfo_linux_amd64 /usr/local/bin/cfssl-certinfo
sudo chmod +x /usr/local/bin/cfssl*

Start copyparty

Copyparty will auto-generate certificates:

copyparty --crt-dir /etc/copyparty/certs

Certificates are saved to --crt-dir for distribution.

Install CA certificate

Distribute ca.pem to all client devices and install as trusted CA.

This is a self-signed certificate. For public deployments, use Let’s Encrypt via reverse proxy.

Hardening

Safety Profiles

Copyparty provides security shortcuts:

Profile: `-s` (Safe)

copyparty -s

Enables:

--no-thumb - Disable thumbnails (no FFmpeg/Pillow on uploads)
--no-mtag-ff - Use Mutagen instead of FFmpeg for tags
--dotpart - Hide uploads while incomplete
--no-robots - Tell search engines to stay away
--force-js - Require JavaScript (harder for crawlers)

Profile: `-ss` (Safer)

All of -s plus:

--unpost 0 - Disable upload undo
--no-del - Disable delete
--no-mv - Disable move/rename
--hardlink - Use hardlinks for deduplication
--vague-403 - Return 404 instead of 403
-nih - Remove hostname from listings

Profile: `-sss` (Safest)

All of -ss plus:

--no-dav - Disable WebDAV
--no-logues - Disable prologues/epilogues
--no-readme - Disable README rendering
-lo cpp-%Y-%m%d-%H%M%S.txt.xz - Log to compressed files
-ls **,*,ln,p,r - Scan for dangerous symlinks on startup

Per-Volume Hardening

Disable HTML rendering for untrusted uploads:

[/uploads]
  /srv/uploads
  accs:
    w: *
  flags:
    nohtml  # Serve HTML as plaintext, disable markdown

This prevents XSS attacks from uploaded files.

Filekeys (Prevent Bruteforcing)

Require secret keys to access files:

[/private]
  /srv/private
  accs:
    r: alice
    g: *      # Others need filekeys
  flags:
    fk: 4     # 4-character filekeys

Users with r permission see URLs like:

https://example.com/private/document.pdf?k=x3tK

Users with g permission need the key to access the file. Dirkeys (directory access keys):

flags:
  dk: true   # Enable directory keys
  dks: true  # Allow access to subdirectories

CORS Configuration

By default, non-GET/HEAD requests must:

Have no Origin header, OR
Have Origin matching the server domain, OR
Include PW header with password

Customize CORS:

[global]
  acao: https://trusted-site.com  # Allow specific origin
  acam: GET,POST                  # Allowed methods
  allow-csrf: true                # Disable CORS (not recommended)

Rate Limiting and Bans

Default settings:

Password attempts: 9 failures in 1 hour = 24 hour ban
Configure with --ban-pw

[global]
  ban-pw: 5,3600,86400  # 5 attempts, 1 hour window, 24h ban

View active bans in the control panel (requires admin permission).

Additional Security Measures

Restrict Access by IP

Listen only on localhost (for reverse proxy):

[global]
  i: 127.0.0.1

Or specific interface:

[global]
  i: 192.168.1.100

Disable Unnecessary Features

[global]
  no-dav      # Disable WebDAV
  no-ftp      # Disable FTP
  no-robots   # robots.txt: noindex, nofollow
  force-js    # Require JavaScript (anti-crawler)

Hide Server Information

[global]
  nih         # Remove hostname from UI
  no-ver      # Don't show version in control panel

Protect Against XSS

[/uploads]
  /srv/uploads
  flags:
    nohtml     # Serve HTML as text
    no-readme  # Don't render README.md
    no-logues  # Don't render .prologue/.epilogue

Systemd Security Hardening

The example systemd service includes hardening:

[Service]
MemoryMax=50%
MemorySwapMax=50%
ProtectClock=true
ProtectControlGroups=true
ProtectHostname=true
ProtectKernelLogs=true
ProtectKernelModules=true
ProtectKernelTunables=true
ProtectProc=invisible
RemoveIPC=true
RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true

See Systemd Service for details.

Docker Security

Run as non-root user:

docker run -u 1000:1000 ...

Limit resources:

services:
  copyparty:
    image: copyparty/ac
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G

Chroot Isolation

Run copyparty in a chroot for maximum isolation:

# Using prisonparty.sh
/usr/local/bin/prisonparty.sh /var/lib/copyparty-jail copyparty copyparty \
  /mnt/share \
  -- \
  /usr/bin/python3 /usr/local/bin/copyparty-sfx.py -v /mnt/share::rw

See Systemd Service - Chroot Setup.

Monitoring and Auditing

Enable Logging

[global]
  lo: /var/log/copyparty/%Y-%m%d.log
  ansi  # Color-coded logs

Compressed logs:

[global]
  lo: /var/log/copyparty/%Y-%m%d.log.xz

Admin Features

Users with a permission can:

View uploader IPs and timestamps
Reload configuration
View active bans
Monitor upload progress

[/admin]
  /srv/admin
  accs:
    rwmda: admin  # Full access including admin features

Prometheus Metrics

Enable monitoring endpoint:

[global]
  stats     # Enable /.cpr/metrics endpoint
  e2dsa     # Required for volume metrics

Only accessible by admin users. See README - Prometheus for details.

Common Security Scenarios

[accounts]
  admin: hashed_password

[/public]
  /srv/public
  accs:
    r: *       # Anyone can read
    w: *       # Anyone can upload
    da: admin  # Only admin can delete
  flags:
    nohtml     # Prevent XSS
    unpost: 0  # Disable upload undo

Private Cloud Storage

[accounts]
  alice: pass1
  bob: pass2

[/alice]
  /srv/alice
  accs:
    rwmda: alice

[/bob]
  /srv/bob
  accs:
    rwmda: bob

[/shared]
  /srv/shared
  accs:
    rw: alice, bob

Read-Only Archive

[/archive]
  /srv/archive
  accs:
    r: *       # Public read
    # No write permissions

Authenticated Download Server

[accounts]
  user: password

[/downloads]
  /srv/downloads
  accs:
    r: user    # Only authenticated users
  flags:
    fk: 6      # Filekeys for sharing

Security Checklist

Security Updates

Stay informed about security issues:

Join the Discord server for announcements
Watch the GitHub repository
Check releases regularly

Always update to the latest version to ensure you have the latest security patches.

Next Steps

Systemd Service

Configure systemd with security hardening

Reverse Proxy

Set up nginx or Apache

Docker

Container security best practices

Get Started

Core Features

Configuration

Deployment

Guides

​Overview

​Authentication

​Basic Authentication

​Password Hashing

​Permission Model

​Example Permission Configurations

​Public Read, Private Write

​Multiple User Tiers

​Upload-Only Folder

​Write-Only with Filekeys

​IP-Based Authentication

​HTTPS/TLS Configuration

​Using a Reverse Proxy (Recommended)

​Native HTTPS with cfssl

​Hardening

​Safety Profiles

​Profile: -s (Safe)

​Profile: -ss (Safer)

​Profile: -sss (Safest)

​Per-Volume Hardening

​Filekeys (Prevent Bruteforcing)

​CORS Configuration

​Rate Limiting and Bans

​Additional Security Measures

​Restrict Access by IP

​Disable Unnecessary Features

​Hide Server Information

​Protect Against XSS

​Systemd Security Hardening

​Docker Security

​Chroot Isolation

​Monitoring and Auditing

​Enable Logging

​Admin Features

​Prometheus Metrics

​Common Security Scenarios

​Public File Sharing with Upload

​Private Cloud Storage

​Read-Only Archive

​Authenticated Download Server

​Security Checklist

​Security Updates

​Next Steps

Systemd Service

Reverse Proxy

Docker

Build docs developers (and LLMs) love

Overview

Authentication

Basic Authentication

Password Hashing

Permission Model

Example Permission Configurations

Public Read, Private Write

Multiple User Tiers

Upload-Only Folder

Write-Only with Filekeys

IP-Based Authentication

HTTPS/TLS Configuration

Using a Reverse Proxy (Recommended)

Native HTTPS with cfssl

Hardening

Safety Profiles

Profile: `-s` (Safe)

Profile: `-ss` (Safer)

Profile: `-sss` (Safest)

Per-Volume Hardening

Filekeys (Prevent Bruteforcing)

CORS Configuration

Rate Limiting and Bans

Additional Security Measures

Restrict Access by IP

Disable Unnecessary Features

Hide Server Information

Protect Against XSS

Systemd Security Hardening

Docker Security

Chroot Isolation

Monitoring and Auditing

Enable Logging

Admin Features

Prometheus Metrics

Common Security Scenarios

Public File Sharing with Upload

Private Cloud Storage

Read-Only Archive

Authenticated Download Server

Security Checklist

Security Updates

Next Steps