caddy storage

Export and import Caddy’s storage (TLS certificates, ACME data, etc.)

The caddy storage command provides subcommands for working with Caddy’s storage, allowing you to export and import storage contents like TLS certificates and ACME data.

EXPERIMENTAL: This command may be changed or removed in future versions.

Usage

caddy storage <subcommand> [flags]

Description

Allows exporting and importing Caddy’s storage contents. The storage contains:

• TLS certificates (from ACME or loaded files)
• ACME account data (account keys, registration info)
• ACME challenge data (for DNS and other challenges)
• OCSP staples and other TLS-related data

This is useful for:

• Migrating between storage backends
• Backing up certificates and keys
• Transferring data between servers
• Switching storage configurations

When importing to or exporting from file_system storage (the default), the command should be run as the user that owns the associated root path.

Subcommands

export

Exports storage assets as a tarball.

caddy storage export --config <path> --output <path>

import

Imports storage assets from a tarball.

caddy storage import --config <path> --input <path>

Combining Export and Import

The two commands can be combined in a pipeline to transfer directly from one storage to another:

caddy storage export --config Caddyfile.old --output - | \
    caddy storage import --config Caddyfile.new --input -

The - argument refers to stdout and stdin, respectively.

Export Flags

--config · string · required

Input configuration file (required).

The storage configuration will be extracted from this config.

--output · string · required

Output path for the tarball (required).

Use - for stdout (useful for piping).

Import Flags

--config · string · required

Configuration file to load (required).

The storage configuration will be extracted from this config.

--input · string · required

Path to tarball to import (required).

Use - for stdin (useful for piping).

Examples

Export to file

caddy storage export --config Caddyfile --output backup.tar

Creates backup.tar containing all storage assets.

Import from file

caddy storage import --config Caddyfile --input backup.tar

Restores storage assets from backup.tar.

Export to stdout

caddy storage export --config Caddyfile --output -

Writes tarball to stdout (useful for piping or compression).

Import from stdin

cat backup.tar | caddy storage import --config Caddyfile --input -

Compress backup

caddy storage export --config Caddyfile --output - | gzip > backup.tar.gz

Restore from compressed backup

gunzip -c backup.tar.gz | caddy storage import --config Caddyfile --input -

Transfer between servers

# On source server
caddy storage export --config Caddyfile --output - | \
    ssh user@destination 'caddy storage import --config /etc/caddy/Caddyfile --input -'

Migrate storage backends

Old config using file storage:

# Caddyfile.old
{
    storage file_system {
        root /var/lib/caddy/old
    }
}

New config using different storage:

# Caddyfile.new
{
    storage file_system {
        root /var/lib/caddy/new
    }
}

Migrate:

caddy storage export --config Caddyfile.old --output - | \
    caddy storage import --config Caddyfile.new --input -

Backup before upgrade

# Create backup
caddy storage export --config /etc/caddy/Caddyfile --output ~/caddy-backup-$(date +%Y%m%d).tar

# Upgrade Caddy
sudo apt update && sudo apt upgrade caddy

# If something goes wrong, restore
# caddy storage import --config /etc/caddy/Caddyfile --input ~/caddy-backup-YYYYMMDD.tar

Exit Codes

• 0 - Success
• 1 - Failed startup (invalid config or missing flags)
• 2 - Failed quit (error during export/import)

What Gets Exported

The export includes all “terminal” keys from the storage:

• Certificates - certificates/acme/.../*.crt
• Private keys - certificates/acme/.../*.key
• Account keys - acme/.../*.json
• OCSP staples - Various cached data
• Locks (if present at export time)

The exact structure depends on your storage backend and ACME usage.

Tarball Format

The export creates a standard tar archive:

# List contents
tar -tf backup.tar

# Extract to inspect
mkdir inspect
tar -xf backup.tar -C inspect
ls -R inspect

Example contents:

certificates/acme/acme-v02.api.letsencrypt.org-directory/example.com/example.com.crt
certificates/acme/acme-v02.api.letsencrypt.org-directory/example.com/example.com.key
acme/acme-v02.api.letsencrypt.org-directory/users/...

Storage Backends

Caddy supports different storage backends:

File System (default)

{
    storage file_system {
        root /var/lib/caddy
    }
}

Consul

{
    storage consul {
        address "localhost:8500"
        prefix "caddy"
    }
}

Redis

{
    storage redis {
        address "localhost:6379"
        prefix "caddy"
    }
}

S3

{
    storage s3 {
        bucket "my-caddy-storage"
        region "us-east-1"
    }
}

Migrating Between Storage Types

File System → Consul

# Export from file system
caddy storage export --config Caddyfile.fs --output certs.tar

# Import to Consul
caddy storage import --config Caddyfile.consul --input certs.tar

Consul → File System

caddy storage export --config Caddyfile.consul --output certs.tar
caddy storage import --config Caddyfile.fs --input certs.tar

Caveats

• Keys are removed during export if they’re deleted from storage while export is in progress (warning will be logged)
• Permissions matter for file_system storage - run as the correct user
• Storage must be configured in the config file for both export and import
• Concurrent access during export may lead to inconsistent state

Best Practices

1. Stop Caddy during migration

sudo systemctl stop caddy
caddy storage export --config /etc/caddy/Caddyfile --output backup.tar
# ... change storage config ...
caddy storage import --config /etc/caddy/Caddyfile --input backup.tar
sudo systemctl start caddy

2. Verify backup integrity

# Create backup
caddy storage export --config Caddyfile --output backup.tar

# Verify it's a valid tar
tar -tf backup.tar > /dev/null
if [ $? -eq 0 ]; then
    echo "Backup is valid"
fi

3. Regular backups

#!/bin/bash
# backup-caddy-storage.sh
BACKUP_DIR="/backups/caddy"
mkdir -p "$BACKUP_DIR"

caddy storage export \
    --config /etc/caddy/Caddyfile \
    --output "$BACKUP_DIR/caddy-storage-$(date +%Y%m%d-%H%M%S).tar"

# Keep only last 7 days
find "$BACKUP_DIR" -name 'caddy-storage-*.tar' -mtime +7 -delete

4. Encrypt sensitive backups

# Export and encrypt
caddy storage export --config Caddyfile --output - | \
    gpg --encrypt --recipient [e-mail] > backup.tar.gpg

# Decrypt and import
gpg --decrypt backup.tar.gpg | \
    caddy storage import --config Caddyfile --input -

Troubleshooting

Permission errors

Error: opening output file: permission denied

Run as the correct user or use sudo:

sudo -u caddy caddy storage export --config /etc/caddy/Caddyfile --output backup.tar

Storage not configured

If the config doesn’t specify storage, Caddy uses file_system storage with default paths. Make sure your config is complete.

Empty export

If export produces an empty or very small tarball:

• Check that certificates exist in storage
• Verify storage path is correct
• Ensure ACME has issued certificates

Related Commands

• caddy run - Start Caddy with storage config
• caddy validate - Validate storage configuration