Configuration¶

fnb uses TOML format configuration files. The main configuration file is fnb.toml or config.toml.

Configuration File Priority¶

Configuration files are searched in the following order (highest priority first):

./fnb.toml - Project-local configuration
~/.config/fnb/config.toml - Global user configuration (XDG compliant)
C:\Users\username\AppData\Local\fnb\config.toml - Windows user configuration
./config/*.toml - Split/merged configurations (for development/operations)

Basic Structure¶

The configuration file consists of two main sections: fetch and backup:

[fetch.label_name]
# Remote-to-local fetch configuration

[backup.label_name]
# Local-to-external backup configuration

Configuration Fields¶

Each section contains the following fields:

Field	Description	Example
`label`	Unique task identifier	`"logs"`
`summary`	Brief task description	`"Fetch logs from server"`
`host`	Remote hostname, or `"none"` for local operations	`"user@remote-host"`
`source`	rsync source path	`"~/path/to/source/"`
`target`	rsync target path	`"./local/backup/path/"`
`options`	Array of rsync options	`["-auvz", "--delete"]`
`enabled`	Whether the task is active	`true` or `false`

Complete Configuration Example¶

# Fetch configuration - from remote to local
[fetch.logs]
label = "logs"
summary = "Fetch application logs from production server"
host = "admin@prod-server.example.com"
source = "/var/log/myapp/"
target = "./backup/logs/"
options = ["-auvz", "--delete", "--exclude=*.tmp"]
enabled = true

[fetch.database]
label = "database"
summary = "Fetch database dumps"
host = "admin@db-server.example.com"
source = "/backups/database/"
target = "./backup/db/"
options = ["-auvz", "--progress"]
enabled = true

# Backup configuration - from local to external
[backup.logs]
label = "logs"
summary = "Backup logs to external storage"
host = "none"
source = "./backup/logs/"
target = "/mnt/external/logs/"
options = ["-auvz", "--delete"]
enabled = true

[backup.database]
label = "database"
summary = "Backup database to cloud storage"
host = "none"
source = "./backup/db/"
target = "/mnt/cloud/database/"
options = ["-auvz", "--progress"]
enabled = false

Path Configuration¶

Remote Paths¶

For fetch tasks, use SSH-style paths:

host = "user@hostname"
source = "/absolute/path/" or "~/relative/path/"
target = "./local/path/"

Local Paths¶

For backup tasks, use local filesystem paths:

host = "none"
source = "./local/source/"
target = "/absolute/target/path/" or "./relative/target/"

Environment Variables¶

Paths support environment variable expansion:

source = "$HOME/documents/"
target = "${BACKUP_DIR}/documents/"

rsync Options¶

Common rsync options and their purposes:

Option	Description
`-a`	Archive mode (preserves permissions, timestamps, symbolic links)
`-v`	Verbose output
`-z`	Compress during transfer
`-u`	Skip files that are newer on the receiver
`--delete`	Delete extraneous files from destination
`--progress`	Show progress during transfer
`--exclude=PATTERN`	Exclude files matching pattern
`--dry-run`	Show what would be done without making changes

Examples¶

# Basic synchronization
options = ["-auvz"]

# Synchronization with deletion and progress
options = ["-auvz", "--delete", "--progress"]

# Exclude temporary and cache files
options = ["-auvz", "--exclude=*.tmp", "--exclude=cache/"]

# Bandwidth-limited transfer
options = ["-auvz", "--bwlimit=1000"]

SSH Configuration¶

Password Authentication¶

Create a .env file for SSH passwords:

# .env
SSH_PASSWORD_prod_server=your_secure_password
SSH_PASSWORD_db_server=another_password

Environment variable format: SSH_PASSWORD_<hostname_normalized>

Key-based Authentication¶

For better security, use SSH key authentication:

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Copy public key to remote server
ssh-copy-id user@hostname

Task Labels¶

Labels must be: - Unique within each section (fetch or backup) - Alphanumeric characters and underscores only - Used for command-line operations: fnb fetch logs

Validation Rules¶

fnb validates configuration files and will report errors for:

Missing required fields
Invalid TOML syntax
Duplicate labels within sections
Invalid rsync options
Malformed host specifications

Advanced Configuration¶

Multiple Environments¶

Use separate configuration files for different environments:

# Development
fnb --config config/dev.toml fetch logs

# Production
fnb --config config/prod.toml fetch logs

Configuration Templates¶

Generate configuration templates:

# Generate complete configuration
fnb init

# Generate only config file
fnb init config

# Generate only environment file
fnb init env

Config File Discovery¶

fnb automatically discovers configuration files in this order:

--config command line option
./fnb.toml in current directory
./config.toml in current directory
./config/*.toml files
User configuration directory based on OS

Run fnb status to see which configuration file is being used.

Troubleshooting¶

Common Issues¶

Config file not found: Run fnb init to create initial configuration
Invalid TOML syntax: Check for missing quotes, brackets, or commas
Task not found: Verify label matches configuration exactly
Permission denied: Check SSH credentials and file permissions
Path not found: Verify source and target paths exist

Debugging¶

Use --dry-run to preview operations:

fnb fetch logs --dry-run
fnb backup logs --dry-run

Check configuration status:

fnb status

For detailed examples, see the Examples Guide.