Overview

Daemon Mode runs continuously on client machines, automatically backing up devices according to a schedule. Configuration is managed via a YAML file at /etc/xreplicator/agent.yaml (Linux) or C:\ProgramData\xreplicator\agent.yaml (Windows).

Starting the Daemon

# Start the daemon
sudo systemctl start backup-agent
 
# Enable automatic startup on boot
sudo systemctl enable backup-agent
 
# Check status
sudo systemctl status backup-agent
 
# View logs
sudo journalctl -u backup-agent -f

# Windows (run as Administrator)
Start-Service XReplicatorAgent
Get-Service XReplicatorAgent

Configuration File

Edit the config file, then restart the service to apply changes:

sudo nano /etc/xreplicator/agent.yaml
sudo systemctl restart backup-agent

# Windows
notepad C:\ProgramData\xreplicator\agent.yaml
Restart-Service XReplicatorAgent

Example Agent Configs

• Linux: /docs/configuration/agent-config-linux
• Windows: /docs/configuration/agent-config-windows

Device Configuration

device.path (string, required)

Path to the block device or file to back up.

device:
  path: "/dev/vdb"

device.paths (array, optional)

Use this instead of device.path when backing up multiple devices.

device:
  paths:
    - "/dev/vdb"
    - "/dev/vdc"

device.sync_wait_ms (integer, default: 500)

Wait time in milliseconds after filesystem sync before backup. Ensures buffered writes are committed to disk.

Storage Configuration

storage.type (string, required)

Storage backend type. Options: "local" or "grpc".

storage.path (string, required if type is "local")

Local directory for the repository. Created automatically if it doesn’t exist.

storage:
  type: "local"
  path: "/var/lib/backup/repo"

gRPC Storage Options

TLS Options

Change Tracking (eBPF)

Recovery Options

Recovery strategies:

• "full_incremental" — Scan entire device with deduplication (safest, recommended)
• "full_backup" — Force full backup without deduplication
• "trust_bitmap" — Use persisted bitmap (fastest but risky)

Block Group (ext4)

Backup Schedule

Full Backups

Incremental Backups

Retention Policy

Pipeline Configuration

Tuning for Larger Disks (Best Practices)

For larger disks, tune for the outcome you want:

• Lower restore CPU and metadata overhead: increase chunk_size_avg_kb
• Better dedup granularity: decrease chunk_size_avg_kb
• Lower memory pressure and fewer stalls: reduce batch_size and workers

Rules to keep configurations safe

• Keep fixed_block_size_mb the same on agent and server.
• Keep max_chunk_size_mb > fixed_block_size_mb.
• Keep chunk_size_avg_kb < fixed_block_size_mb * 1024.
• Start conservative, then scale up one setting at a time.

Quick chunk-count estimation

Approximate chunk count:

chunks ~= disk_size / average_chunk_size

Example for a 100 GB disk:

• chunk_size_avg_kb: 1024 (~1 MB average): about 100,000 chunks
• chunk_size_avg_kb: 2048 (~2 MB average): about 50,000 chunks
• chunk_size_avg_kb: 4096 (~4 MB average): about 25,000 chunks

workers and batch_size change throughput/memory behavior, not the chunk count target.

Recommended profiles

Profile A: Large disks, balanced (recommended starting point)

daemon:
  pipeline:
    chunk_size_avg_kb: 4096
    fixed_block_size_mb: 16
    max_chunk_size_mb: 32
    batch_size: 100
    workers: 4

Profile B: Large disks on memory-constrained hosts

daemon:
  pipeline:
    chunk_size_avg_kb: 2048
    fixed_block_size_mb: 8
    max_chunk_size_mb: 16
    batch_size: 25
    workers: 1
    max_io_queue_depth: 2
    channel_buffer_mult: 1
    max_pipeline_memory_mb: 256

Profile C: High-throughput hosts (more CPU and RAM)

daemon:
  pipeline:
    chunk_size_avg_kb: 4096
    fixed_block_size_mb: 16
    max_chunk_size_mb: 32
    batch_size: 200
    workers: 6

Troubleshooting guidance

If agent memory grows rapidly or backups appear stuck:

• Reduce batch_size first (for example, 200 -> 100 -> 25).
• Reduce workers next (for example, 4 -> 2 -> 1).
• Keep chunk settings stable while troubleshooting.

Compression

Logging

Configuration Examples

Local Storage

storage:
  type: "local"
  path: "/var/lib/backup/repo"

gRPC with TLS (Production)

storage:
  type: "grpc"
  grpc:
    server_address: "backup.prod.example.com:50051"
    timeout: 10m
    max_retries: 5
    tls:
      enabled: true
      cert_file: "/etc/backup/tls/client.crt"
      key_file: "/etc/backup/tls/client.key"
      ca_file: "/etc/backup/tls/ca.crt"

Daily Full Backups (Database Server)

schedule:
  full_backup:
    enabled: true
    frequency: "daily"
    time: "03:00"
    max_age_days: 7
  incremental_backup:
    enabled: true
    frequency: "custom"
    interval: 15m

High Bandwidth (1 Gbps+)

daemon:
  pipeline:
    batch_size: 400
    workers: 8
  compression:
    enabled: true
    level: 1

Low Bandwidth (10 Mbps)

daemon:
  pipeline:
    batch_size: 20
    workers: 2
  compression:
    enabled: true
    level: 3

Memory-Constrained (1 GB Limit)

daemon:
  pipeline:
    max_io_queue_depth: 3
    channel_buffer_mult: 2
    max_pipeline_memory_mb: 1024
    workers: 2
    fixed_block_size_mb: 8
  compression:
    enabled: true
    level: 1