Quick Start¶

Get up and running with fnb in minutes! This guide will walk you through the basic setup and your first backup operations.

Prerequisites¶

• Python 3.12 or higher
• rsync (usually pre-installed on Unix-like systems)
• SSH access to remote servers (if needed)

Installation¶

Install from PyPI (Recommended)¶

pip install fnb

See the Installation Guide for uv alternatives and running from source.

Verify Installation¶

fnb version

Initial Setup¶

1. Generate Configuration¶

Create your first configuration file:

fnb init

This creates two files:

• fnb.toml - Main configuration file
• .env.plain - Template for SSH passwords (rename to .env)

2. Configure SSH Access (Optional)¶

If you need SSH password authentication, set up the .env file:

# Rename the template
mv .env.plain .env

# Edit the file with your SSH passwords
# SSH_PASSWORD_hostname=your_password

Note: SSH key authentication is recommended for better security.

Basic Usage¶

Check Configuration Status¶

fnb status

This shows all configured tasks and their current status.

Preview Operations (Dry Run)¶

Always test with dry-run first:

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

Execute Operations¶

When you're ready, run the actual operations:

# Fetch data from remote server
fnb fetch logs

# Backup to external storage
fnb backup logs

# Or do both in sequence
fnb sync logs

Example Configuration¶

Here's a simple configuration for backing up web server logs:

# fnb.toml
[fetch.weblogs]
label = "weblogs"
summary = "Fetch web server access logs"
host = "admin@webserver.example.com"
source = "/var/log/nginx/"
target = "./backup/weblogs/"
options = ["-auvz", "--delete", "--include=*.log", "--include=**/", "--exclude=*"]
enabled = true

[backup.weblogs]
label = "weblogs"
summary = "Backup web logs to external drive"
host = "none"
source = "./backup/weblogs/"
target = "/mnt/backup-drive/weblogs/"
options = ["-auvz", "--delete", "--progress"]
enabled = true

Using This Configuration¶

# Check what will be done
fnb sync weblogs --dry-run

# Execute the complete workflow
fnb sync weblogs

# Create directories if they don't exist
fnb sync weblogs --create-dirs

Common Workflows¶

Server Backup Workflow¶

# 1. Check current status
fnb status

# 2. Test fetch operation
fnb fetch server-data --dry-run

# 3. Execute fetch
fnb fetch server-data

# 4. Test backup operation
fnb backup server-data --dry-run

# 5. Execute backup
fnb backup server-data

Complete Sync Workflow¶

# Test complete pipeline
fnb sync server-data --dry-run

# Execute complete pipeline
fnb sync server-data

# With directory creation
fnb sync server-data --create-dirs

Development Project Backup¶

# Generate specific config for projects
fnb init config

# Test project sync
fnb sync project --dry-run

# Execute, prompting interactively for the SSH password
fnb sync project --ask-password

Directory Management¶

Auto-Create Directories¶

Use --create-dirs to automatically create missing target directories:

fnb fetch logs --create-dirs
fnb backup logs --create-dirs
fnb sync logs --create-dirs

Directory Structure¶

fnb follows this typical structure:

project-root/
├── fnb.toml          # Main configuration
├── .env              # SSH passwords (optional)
└── backup/           # Local backup staging area
    ├── logs/         # Fetched logs
    ├── database/     # Database backups
    └── configs/      # Configuration files

Configuration Tips¶

1. Start Simple¶

Begin with basic configurations and add complexity gradually:

[fetch.simple]
label = "simple"
summary = "Simple fetch example"
host = "user@server"
source = "~/documents/"
target = "./backup/docs/"
options = ["-av"]
enabled = true

2. Use Dry Run¶

Always test new configurations with --dry-run first.

3. Incremental Setup¶

Add one task at a time and test thoroughly before adding more.

4. Monitor Progress¶

Use the --progress option for large transfers:

options = ["-auvz", "--progress"]

Troubleshooting¶

Common Issues¶

Config file not found:

fnb init  # Create initial config

SSH connection failed:

# Test SSH manually first
ssh user@hostname

# Prompt interactively for the SSH password
fnb fetch logs --ask-password

Directory doesn't exist:

fnb fetch logs --create-dirs

Permission denied:

• Check SSH key permissions (should be 600)
• Verify target directory permissions
• Ensure user has access to source directories

Getting Help¶

# General help
fnb --help

# Command-specific help
fnb fetch --help
fnb backup --help
fnb upload --help
fnb sync --help

Next Steps¶

Now that you have fnb running:

1. Configuration Guide - Learn advanced configuration options
2. Commands Reference - Complete command documentation
3. Examples - Real-world usage scenarios
4. FAQ - Common questions and solutions

Quick Reference¶

# Essential commands
fnb init                    # Generate config
fnb status                  # Show config status
fnb fetch LABEL            # Fetch from remote
fnb backup LABEL           # Backup locally
fnb upload LABEL           # Upload to remote
fnb sync LABEL             # Fetch + backup
fnb COMMAND --dry-run      # Preview operation
fnb COMMAND --create-dirs  # Auto-create directories
fnb COMMAND --help         # Get help

You're now ready to use fnb for your backup workflows!