Syncthing – Decentralized File Synchronization Tool

Mastering Syncthing: Secure Peer-to-Peer File Synchronization

Syncthing represents a paradigm shift in file synchronization by eliminating the need for centralized cloud servers. This open-source application enables direct device-to-device synchronization, ensuring that your files never pass through third-party servers. Whether you’re synchronizing documents between your laptop and desktop, sharing project files with collaborators, or maintaining backups across multiple machines, Syncthing provides a secure, private, and efficient solution.

The decentralized architecture of Syncthing offers significant advantages over traditional cloud synchronization services. Your data remains entirely under your control, never stored on external servers where it could be accessed by service providers or compromised in data breaches. The application uses TLS encryption for all communications and Perfect Forward Secrecy to protect against future decryption attempts, even if keys are later compromised.

How Syncthing Works

Syncthing operates by establishing secure connections between devices that share folders. Each device generates a unique identifier and cryptographic keys during initial setup. To share files, devices exchange these identifiers and approve connections, creating a trust network independent of any central authority.

The synchronization process begins with devices discovering each other through various mechanisms including local network discovery, relay servers for initial connection establishment, and NAT traversal techniques. Once connected, devices exchange file metadata and transfer only the portions of files that have changed, minimizing bandwidth usage while maintaining synchronization efficiency.

Block-level synchronization means that changes to large files don’t require transferring the entire file. If you modify one paragraph in a large document, only the affected blocks are synchronized. This approach dramatically reduces synchronization time and bandwidth consumption compared to full-file transfers.

Installing Syncthing

Syncthing is available for all major operating systems with multiple installation methods to suit different preferences and deployment scenarios.

Linux Installation

# Ubuntu/Debian - Official repository
sudo mkdir -p /etc/apt/keyrings
sudo curl -L -o /etc/apt/keyrings/syncthing-archive-keyring.gpg https://syncthing.net/release-key.gpg
echo "deb [signed-by=/etc/apt/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable" | sudo tee /etc/apt/sources.list.d/syncthing.list
sudo apt update
sudo apt install syncthing

# Fedora
sudo dnf install syncthing

# Arch Linux
sudo pacman -S syncthing

# openSUSE
sudo zypper install syncthing

# Flatpak
flatpak install flathub me.kozec.syncthingtk

# Start Syncthing
syncthing

# Enable as systemd user service
systemctl --user enable syncthing
systemctl --user start syncthing

# Check status
systemctl --user status syncthing

macOS Installation

# Homebrew installation
brew install syncthing

# Start Syncthing
syncthing

# Install as service
brew services start syncthing

# Install SyncthingBar (menu bar app)
brew install --cask syncthing

# Verify installation
syncthing --version

Windows Installation

# Chocolatey installation
choco install syncthing

# Winget installation
winget install Syncthing.Syncthing

# Scoop installation
scoop install syncthing

# Start from command line
syncthing.exe

# Install as Windows service
# Use SyncTrayzor for GUI + service management
choco install synctrayzor

Docker Deployment

# Run Syncthing in Docker
docker run -d \
  --name syncthing \
  -p 8384:8384 \
  -p 22000:22000/tcp \
  -p 22000:22000/udp \
  -p 21027:21027/udp \
  -v /path/to/config:/var/syncthing/config \
  -v /path/to/data:/var/syncthing/data \
  syncthing/syncthing:latest

# Docker Compose configuration
version: '3'
services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: syncthing
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/var/syncthing/config
      - ./data:/var/syncthing/data
    ports:
      - 8384:8384     # Web UI
      - 22000:22000/tcp # Sync Protocol
      - 22000:22000/udp # Sync Protocol
      - 21027:21027/udp # Discovery
    restart: unless-stopped

Web Interface and Configuration

Syncthing provides a web-based administration interface accessible at http://localhost:8384 by default. This interface enables all configuration tasks including adding devices, sharing folders, monitoring sync progress, and adjusting advanced settings.

# Access web UI
# Open browser to http://localhost:8384

# Configure remote access (if needed)
# Edit config.xml or use CLI
syncthing cli config gui address set 0.0.0.0:8384

# Set GUI password
syncthing cli config gui user set admin
syncthing cli config gui password set "your-secure-password"

# Generate new device ID
syncthing --device-id

# View current device ID
syncthing cli show system

Command Line Interface

The Syncthing CLI provides comprehensive control over all aspects of the application, enabling automation and headless server management.

# CLI structure
syncthing cli [command] [subcommand] [options]

# View system status
syncthing cli show system

# List configured devices
syncthing cli config devices list

# Add new device
syncthing cli config devices add --device-id DEVICE-ID-HERE --name "My Device"

# Remove device
syncthing cli config devices remove --device-id DEVICE-ID-HERE

# List shared folders
syncthing cli config folders list

# Add new folder
syncthing cli config folders add --id "documents" --path "/home/user/Documents" --label "Documents"

# Share folder with device
syncthing cli config folders MY-FOLDER-ID devices add --device-id DEVICE-ID-HERE

# Pause synchronization
syncthing cli operations pause

# Resume synchronization
syncthing cli operations resume

# Trigger immediate sync
syncthing cli operations scan --folder "folder-id"

# View connection status
syncthing cli show connections

# View folder status
syncthing cli show folder-status --folder "folder-id"

# Generate API key
syncthing cli config options api-key get

Folder Configuration and Sharing

Folders represent the fundamental synchronization unit in Syncthing. Each folder can be shared with different devices with varying permissions and synchronization settings.

Folder Types

# Send & Receive (default)
# Full bidirectional sync - changes on any device propagate to all

# Send Only
# This device sends changes but ignores incoming changes
# Useful for backup sources or publish-only scenarios
syncthing cli config folders MY-FOLDER type set sendonly

# Receive Only
# This device accepts changes but doesn't send
# Useful for backup destinations or mirrors
syncthing cli config folders MY-FOLDER type set receiveonly

Ignore Patterns

# Create .stignore file in folder root
# Patterns follow gitignore-like syntax

# Ignore specific file
secret.txt

# Ignore file type
*.tmp
*.log

# Ignore directory
node_modules
.git
__pycache__

# Ignore by pattern
**/cache/**

# Negate pattern (don't ignore)
!important.tmp

# Case-insensitive pattern
(?i)*.TMP

# Example .stignore for development project
.git
node_modules
*.log
.env
.DS_Store
Thumbs.db
*.pyc
__pycache__
.cache
tmp/

Advanced Configuration

Syncthing offers numerous advanced options for fine-tuning synchronization behavior, network usage, and conflict resolution.

# Configuration file location
# Linux: ~/.local/state/syncthing/config.xml
# macOS: ~/Library/Application Support/Syncthing/config.xml
# Windows: %LOCALAPPDATA%\Syncthing\config.xml

# Set bandwidth limits
syncthing cli config options max-recv-kbps set 5000
syncthing cli config options max-send-kbps set 2000

# Configure global discovery
syncthing cli config options global-announce-enabled set true

# Configure local discovery
syncthing cli config options local-announce-enabled set true

# Set relay usage
syncthing cli config options relays-enabled set true

# Configure file versioning
syncthing cli config folders MY-FOLDER versioning type set simple
syncthing cli config folders MY-FOLDER versioning params set keep 5

# Staggered versioning (time-based)
syncthing cli config folders MY-FOLDER versioning type set staggered
syncthing cli config folders MY-FOLDER versioning params set maxAge 31536000

# External versioning (custom script)
syncthing cli config folders MY-FOLDER versioning type set external
syncthing cli config folders MY-FOLDER versioning params set command /path/to/versioning-script.sh

File Versioning Strategies

Syncthing’s file versioning protects against accidental deletions and modifications by archiving previous versions of changed or deleted files.

# Simple versioning
# Keeps last N versions of each file
# Fast and predictable

# Staggered versioning
# Keeps versions based on age tiers:
# - First hour: one version per 30 seconds
# - First day: one version per hour
# - First month: one version per day
# - Until max age: one version per week

# Trash can versioning
# Moves deleted files to .stversions folder
# Cleans up after specified days

# External versioning
# Calls external command for each version
# Script receives: folder path, file path, device ID

# Example external versioning script
#!/bin/bash
# Store versions in dated directories
FOLDER=$1
FILE=$2
DATE=$(date +%Y-%m-%d)
VERSION_DIR="$FOLDER/.versions/$DATE"
mkdir -p "$VERSION_DIR"
cp "$FOLDER/$FILE" "$VERSION_DIR/"

Security Configuration

Syncthing implements multiple layers of security that can be customized according to your threat model and privacy requirements.

# Device authentication
# Each device identified by unique ID derived from certificate
# Connections only established with explicitly trusted devices

# View device certificates
syncthing cli show system | grep Certificate

# Disable global discovery (maximum privacy)
syncthing cli config options global-announce-enabled set false

# Disable relay servers (direct connections only)
syncthing cli config options relays-enabled set false

# Require TLS for web UI
syncthing cli config gui use-tls set true

# Set API key for external access
syncthing cli config options api-key set "your-secure-api-key"

# Configure allowed networks for device
syncthing cli config devices DEVICE-ID allowed-networks add "192.168.1.0/24"

# Block specific device permanently
syncthing cli config devices DEVICE-ID paused set true

REST API Usage

Syncthing’s REST API enables programmatic control and monitoring, perfect for automation and integration with other systems.

# Get API key from config
API_KEY=$(syncthing cli config options api-key get)

# API endpoints base
BASE_URL="http://localhost:8384/rest"

# Get system status
curl -H "X-API-Key: $API_KEY" "$BASE_URL/system/status"

# Get sync completion
curl -H "X-API-Key: $API_KEY" "$BASE_URL/db/completion?folder=default&device=DEVICE-ID"

# Trigger folder rescan
curl -X POST -H "X-API-Key: $API_KEY" "$BASE_URL/db/scan?folder=default"

# Pause syncing
curl -X POST -H "X-API-Key: $API_KEY" "$BASE_URL/system/pause"

# Resume syncing
curl -X POST -H "X-API-Key: $API_KEY" "$BASE_URL/system/resume"

# Get folder status
curl -H "X-API-Key: $API_KEY" "$BASE_URL/db/status?folder=default"

# Get list of devices
curl -H "X-API-Key: $API_KEY" "$BASE_URL/config/devices"

# Python example
import requests

API_KEY = "your-api-key"
BASE = "http://localhost:8384/rest"
headers = {"X-API-Key": API_KEY}

def get_status():
    r = requests.get(f"{BASE}/system/status", headers=headers)
    return r.json()

def scan_folder(folder_id):
    r = requests.post(f"{BASE}/db/scan", params={"folder": folder_id}, headers=headers)
    return r.status_code == 200

Mobile Synchronization

Android users can participate in Syncthing networks using the official Syncthing-Fork application. While iOS lacks an official client, workarounds exist using third-party apps and WebDAV bridges.

# Android: Install Syncthing-Fork from F-Droid or Play Store
# Configure same folders as desktop devices
# Enable "Run on Mobile Data" if needed
# Configure "Sync Only When Charging" to preserve battery

# Note: iOS requires alternative approaches
# Consider using Möbius Sync (paid) or WebDAV bridge

Troubleshooting and Monitoring

Effective troubleshooting requires understanding Syncthing’s logging system and common issue patterns.

# View logs
journalctl --user -u syncthing -f

# Enable debug logging
syncthing --verbose

# Check for conflicts
# Conflict files named: filename.sync-conflict-YYYYMMDD-HHMMSS-DEVICE.ext
find /path/to/folder -name "*.sync-conflict-*"

# Reset folder to force rescan
syncthing cli operations reset-folder --folder "folder-id"

# View pending changes
curl -H "X-API-Key: $API_KEY" "http://localhost:8384/rest/db/need?folder=default"

# Check connection status
syncthing cli show connections | grep -A5 "DEVICE-ID"

# Verify device connectivity
# Ensure ports 22000 (TCP/UDP) and 21027 (UDP) accessible

# Test direct connection (bypass relays)
# Add device with addresses: tcp://192.168.1.100:22000

Backup Integration

Syncthing can serve as a foundation for backup strategies when combined with versioning and dedicated backup devices.

# Set up backup server configuration
# 1. Create "Receive Only" folder on backup server
# 2. Enable staggered versioning with long retention
# 3. Share folder from source devices as "Send Only"

# Backup server setup example
syncthing cli config folders add \
  --id "photos-backup" \
  --path "/backup/photos" \
  --label "Photos Backup" \
  --type "receiveonly"

syncthing cli config folders photos-backup versioning type set staggered
syncthing cli config folders photos-backup versioning params set maxAge 31536000

# Add source device
syncthing cli config folders photos-backup devices add --device-id SOURCE-DEVICE-ID

Performance Optimization

Tuning Syncthing for optimal performance involves balancing resource usage with synchronization speed according to your specific requirements.

# Increase file watcher limit (Linux)
echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Adjust scan interval (reduce for large folders)
syncthing cli config folders MY-FOLDER rescan-interval-s set 3600

# Configure parallel transfers
syncthing cli config options max-concurrent-incoming-request-kib set 256

# Tune TCP settings for high-latency connections
syncthing cli config options reconnection-interval-s set 60

Conclusion

Syncthing delivers on the promise of secure, decentralized file synchronization without compromising on features or usability. Its peer-to-peer architecture eliminates third-party dependencies while providing robust synchronization capabilities across all major platforms. Whether for personal use, team collaboration, or enterprise backup solutions, Syncthing provides the foundation for file synchronization infrastructure that you truly control.