Configuration Reference

Every configurable field, documented. Tune backup behavior to your needs.

Ways to Configure

Ginkgo Backup offers three ways to configure: the GUI (recommended for most users), the CLI (ginkgo init command), and the HTTP API (for automation). All config is stored in a SQLite database and can be changed at any time.

Backup Source Configuration

Fields available when creating or updating a backup source. Use a JSON body when creating via API.

Field	Type	Default	Description
`path`	string	—	Source path (required)
`name`	string	directory name	Display name
`group`	string	—	Group label for organizing sources
`enabled`	bool	true	Whether the source is active (false when paused)
`schedule`	string	manual	Schedule: manual / hourly / daily / weekly / monthly
`schedule_config`	string (JSON)	—	Schedule detail, e.g. {"hour":2,"minute":30}
`retention`	string	smart	Retention policy: keep_all / smart / custom
`retention_custom`	string	—	Custom retention rules (when retention=custom)
`excludes`	[]string	[]	Exclude patterns (glob syntax, comma-separated)
`enable_ai`	bool	false	Enable AI-powered snapshot notes
`watch_mode`	string	auto	Watch mode: auto / poll / disabled
`compression_type`	string	zstd	Compression algorithm (fixed zstd, not changeable)
`compression_level`	int	1	Compression level (fixed 1, not changeable)
`chunk_concurrency`	int	0 (auto)	Chunk concurrency, 0 = auto by CPU
`repo_paths`	[]string	—	Repository paths (multi-target for 3-2-1)

Schedule Types in Detail

The schedule_config field uses different JSON structures depending on the schedule type:

schedule	schedule_config	Description
`manual`	`—`	No automatic backup, manual trigger only
`hourly`	`{"interval_minutes": 60}`	Run at a fixed interval (default 60 min)
`daily`	`{"hour": 2, "minute": 30}`	Run daily at the specified time
`weekly`	`{"day": "monday", "hour": 3}`	Run weekly on the specified day and time
`monthly`	`{"date": 1, "hour": 2}`	Run monthly on the specified date and time

Retention Policies in Detail

Ginkgo uses GFS (Grandfather-Father-Son) retention to manage historical versions:

retention	Description
`keep_all`	Keep all snapshots, never delete (highest space usage)
`smart`	Smart GFS (recommended): 24 hourly + 30 daily + 12 weekly + 12 monthly + 3 yearly
`custom`	Custom GFS bucket sizes via retention_custom

Exclude Patterns

The excludes field uses glob syntax, comma-separated. You can also create a .ginkgo-backupignore file in the source directory (same syntax as .gitignore).

pattern	matches
`/Cache/`	Any directory named Cache at any depth
`*/.tmp`	All .tmp files
`/logs/`	Any directory named logs at any depth
`node_modules/**`	node_modules in the source root
`!/important/`	Negative pattern: re-include important directories

Compression

Ginkgo always uses zstd (level 1) for all backup data. It is not configurable:

algorithm	level	Description
`zstd`	1	Fixed algorithm and level, applied to all backup sources

File Watch Modes

watch_mode controls how file changes are detected for real-time backup:

watch_mode	Description
`auto`	Auto-select: prefer native OS file events, fall back to polling
`poll`	Force polling: scan directory periodically, best compatibility but slightly higher CPU
`disabled`	Disable real-time watch, only run on schedule

Repository Configuration

Fields available when creating a repository:

Field	Type	Default	Description
`path`	string	—	Repository path (local path or cloud://backendID/path)
`display_name`	string	—	Display name
`type`	string	local	Type: local / s3 / webdav
`encrypted`	bool	false	Enable encryption
`password`	string	—	Encryption password (required when encrypted=true)
`compression`	string	zstd	Compression algorithm

Global Settings

Read/write app-level settings via the /api/v1/settings endpoint:

Shell

# View current settings
curl http://127.0.0.1:9275/api/v1/settings \
  -H "Authorization: Bearer $TOKEN"

# Update settings
curl -X PUT http://127.0.0.1:9275/api/v1/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language": "en", "theme": "dark"}'

Snapshot Pinning

Pinned snapshots are protected from retention and GC. Useful for preserving critical points in time:

curl

# Pin a snapshot
curl -X POST http://127.0.0.1:9275/api/v1/pins/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": 123}'

# Unpin
curl -X POST http://127.0.0.1:9275/api/v1/pins/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": 123}'