Core Concepts Cheatsheet

A dense, scannable reference for Syncthing's fundamental concepts. Use this as a quick lookup during configuration and troubleshooting without re-reading full lessons.

Learning Focus

Bookmark this page. When something is "not working," scan this page first — the answer is usually a misunderstood concept rather than a bug.

Terminology

Term	Definition
Device ID	63-character SHA-256 fingerprint of the TLS certificate. Globally unique. Used for all pairing.
Folder ID	Short string (`docs-sync`) that identifies a synced folder. Must be the same on both peers for a folder pair to connect.
Folder Label	Human-readable display name. Does not need to match between peers.
Announcement	The process by which a device tells discovery servers its current IP/port.
Discovery	Finding the address of a peer using their Device ID.
Relay	A public server that forwards data when peers cannot connect directly. Direct P2P is always preferred.
Conflict	When the same file is modified on two peers simultaneously, Syncthing keeps both versions.
`.stfolder`	Sentinel file created at the root of every sync folder. Prevents sync from running on an unmounted directory.
`.stignore`	File-level ignore rules (gitignore syntax). Controls which files Syncthing skips.
`.stversions`	Directory where old versions of files are stored when versioning is enabled.

Device States

State	Meaning
Connected (Direct)	P2P connection active — fastest mode
Connected (Relayed)	Connection via a relay server — slower, but functional
Disconnected	Not currently reachable. Check firewall, power, network.
Paused	Sync intentionally suspended by user or config
Unused	Device added to config but not yet sharing any folder

Folder States

State	Meaning
Idle	Folder fully synced with all connected peers
Syncing	Actively transferring files
Scanning	Re-indexing local files after a change or rescan
Waiting to Scan	Debounce period — file change detected, waiting briefly before scan
Error	Non-recoverable issue (disk full, permissions, missing mount) — see logs
Out of Sync	Connected to peer but files differ — sync in progress or blocked
Paused	Sync suspended for this folder

Folder Types

flowchart LR
  subgraph sendreceive [Send and Receive — bidirectional]
    A[Device A] <-->|changes both ways| B[Device B]
  end
  subgraph sendonly [Send Only — source of truth]
    C[Source Device] -->|pushes only| D[Peer]
  end
  subgraph receiveonly [Receive Only — passive mirror]
    E[Source] -->|syncs to| F[Mirror — no write-back]
  end
  subgraph receiveencrypted [Receive Encrypted — blind backup]
    G[Primary] -->|encrypted blobs| H[Untrusted Backup Node]
  end

Discovery and Connection Flow

sequenceDiagram
  participant A as Device A
  participant DS as Discovery Server
  participant B as Device B

  A->>DS: Announce: I am DeviceID, reachable at IP:22000
  B->>DS: Query: where is DeviceID?
  DS-->>B: IP:22000
  B->>A: Direct TCP/TLS connection on port 22000
  A-->>B: Mutual TLS handshake — both verify Device IDs
  B->>A: Sync begins

Key Port Reference

Port	Protocol	Purpose	Expose?
`22000`	TCP + UDP	Sync data (P2P)	✅ Yes
`21027`	UDP	Local LAN discovery	LAN only
`8384`	TCP	GUI / REST API	❌ Never
`22067`	TCP	Relay server (if self-hosted)	✅ If running relay

Configuration File Locations

Context	Config Path
User service	`~/.local/share/syncthing/config.xml`
System service (syncthing user)	`/home/syncthing/.local/share/syncthing/config.xml`
Certificates	`config_dir/cert.pem`, `config_dir/key.pem`
Database	`config_dir/index-v0.14.0.db/`
GUI HTTPS cert	`config_dir/https-cert.pem`, `config_dir/https-key.pem`

Common Ignore Patterns Quick Reference

# In .stignore at the folder root:

# Temporary files
*.tmp
*.swp
~$*

# OS artifacts
.DS_Store
Thumbs.db
desktop.ini

# IDE / editor
.idea/
.vscode/
*.code-workspace

# Build artifacts
node_modules/
vendor/
dist/
*.pyc
__pycache__/

# Secrets (never sync these)
.env
*.pem
*.key
id_rsa

# Inherit from parent directory's .stignore (default)
#include .stignore

Essential Commands

# Get Device ID
syncthing --device-id

# Run in foreground (testing)
syncthing serve --no-browser

# Start user service
systemctl --user start syncthing

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

# API ping
curl -H "X-API-Key: $ST_KEY" https://localhost:8384/rest/system/ping --cacert $ST_CERT

# Trigger folder rescan
curl -X POST -H "X-API-Key: $ST_KEY" "https://localhost:8384/rest/db/scan?folder=ID" --cacert $ST_CERT

Terminology​

Device States​

Folder States​

Folder Types​

Discovery and Connection Flow​

Key Port Reference​

Configuration File Locations​

Common Ignore Patterns Quick Reference​

Essential Commands​

What's Next​