Host Key Rotation (HA)

TLDR - Quick Summary

What: Rotate SSH host keys across all nodes in an HA SFTP Gateway 3.x cluster

Method: Export backup via API, generate new keys, import via API, restart Java on all nodes

Key point: The shared database is the source of truth — update it once, restart all nodes, and they all get the new keys

Downtime: Brief service restart on each node disconnects active sessions (~10 seconds per node)

Introduction

In a High Availability SFTP Gateway deployment, multiple server nodes share a single load balancer endpoint. Clients connect to sftp.example.com and get routed to whichever node is available. For this to work seamlessly, every node must present identical SSH host keys. Otherwise, clients would see different fingerprints depending on which node handles their connection, triggering security warnings and breaking automated workflows.

This guide explains how to rotate SSH host keys across all nodes in an HA cluster while maintaining this consistency. The process leverages SFTP Gateway's database-backed architecture to update keys in one place and propagate them to all nodes automatically.

Why HA Key Rotation Is Different

On a single server, rotating host keys means updating one machine. In an HA cluster, you need to update multiple nodes simultaneously, and they all need to end up with identical keys. Manually copying key files between servers is error-prone and doesn't scale.

SFTP Gateway solves this by storing the authoritative host keys in a shared database. All nodes read from this database when their Java service starts. This means you can rotate keys by:

1. Updating the database once (via the backup/restore API)
2. Restarting the Java service on each node

The nodes will all load the same new keys from the database, maintaining perfect consistency across the cluster.

What You'll Accomplish

By the end of this guide, you will have:

1. Created rollback artifacts containing your current keys
2. Generated fresh cryptographic keys for all supported algorithms
3. Imported the new keys into the shared database
4. Restarted all nodes to load the new keys
5. Verified that every node presents identical fingerprints

The process requires brief service restarts on each node, which will disconnect active SFTP sessions on that node. You can minimize disruption by doing rolling restarts during a maintenance window.

---

Architecture Overview

Understanding how SFTP Gateway manages keys in an HA deployment will help you troubleshoot issues and make informed decisions during the rotation process.

                    ┌─────────────────────┐
                    │   Azure Load        │
                    │   Balancer          │
                    │   (sftp.example.com)│
                    └─────────┬───────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ SFTP GW  │   │ SFTP GW  │   │ SFTP GW  │
        │ Node 1   │   │ Node 2   │   │ Node 3   │
        └────┬─────┘   └────┬─────┘   └────┬─────┘
             │              │              │
             └──────────────┼──────────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │  Shared Database    │
                 │  (Source of Truth)  │
                 │  - Server Host Keys │
                 │  - Users, Settings  │
                 └─────────────────────┘

The Database as Source of Truth

In SFTP Gateway 3.x, the database is the authoritative source for server host keys, not the filesystem. Each node has a working copy of the keys in /opt/sftpgw/, but these files are recreated from the database every time the Java service starts.

This design has important implications:

• Editing files directly doesn't work - Changes to /opt/sftpgw/ssh_host_* files will be overwritten on the next service restart
• All nodes stay in sync automatically - When you update the database, all nodes get the same keys on their next restart
• The backup/restore API is your interface - YAML export/import through the API is how you read and write keys in the database

Key Files Managed by SFTP Gateway

SFTP Gateway generates and manages five key types to support different client configurations:

Key File	Algorithm	Use Case
ssh_host_rsa	RSA 4096-bit	Legacy compatibility
ssh_host_ecdsa_256	ECDSA P-256	Modern clients
ssh_host_ecdsa_384	ECDSA P-384	Higher security
ssh_host_ecdsa_521	ECDSA P-521	Maximum ECDSA security
ssh_host_ed25519	Ed25519	Recommended for modern clients

Each key type has a corresponding .pub file for the public key. The backup YAML includes both private and public keys for all types.

---

Prerequisites

Before starting the rotation, ensure you have:

• Admin access to SFTP Gateway web UI - You'll need the admin username and password
• SSH access to all SFTP Gateway nodes - Required for getting API client credentials and restarting services
• The load balancer IP and NAT port mappings - For Azure VMSS, SSH access is via NAT ports (2222, 2223, etc.)
• A secure backup location - Store rollback files somewhere safe and accessible

Azure-specific notes:

• SSH user depends on your deployment (commonly ubuntu or azureuser, but configurable during VM creation)
• Access nodes via load balancer NAT ports: ssh -p 2222 <ssh-user>@<lb-ip> for instance 0, port 2223 for instance 1, etc.
• NAT port mappings can be found in the Azure Portal under Load Balancer > Inbound NAT rules

Command-line tools needed:

• curl - For API calls
• ssh-keygen - For generating new keys
• jq - For parsing JSON responses (optional but helpful)
• ssh - For remote service restarts
• base64 - For encoding keys (included in macOS/Linux)

---

Rotation Procedure

This section walks through the complete rotation process. We recommend reading through all steps before starting, and scheduling a maintenance window if your environment requires zero-downtime.

Step 1: Export Current Backup (Create Your Safety Net)

Before making any changes, export the current configuration including host keys. This backup serves two purposes: it's your rollback artifact if something goes wrong, and it lets you extract the current keys for comparison.

This step is critical. Without a backup, you cannot restore the original keys if the rotation fails or causes problems.

Via Web UI:

1. Log into SFTP Gateway web admin portal
2. Navigate to Settings > Backup & Recovery
3. Click Export
4. Save the downloaded YAML file as backup-YYYYMMDD-pre-rotation.yml

Via API:

First, get the API client credentials from any node. For Azure VMSS deployments, SSH to nodes via the load balancer NAT ports (2222 for instance 0, 2223 for instance 1, etc.):

ssh -p 2222 <ssh-user>@<load-balancer-ip> \
    "sudo grep -E 'security.client' /opt/sftpgw/application.properties"

This returns values like:

security.client-id=sftpgw_admin_ui
security.client-secret=sftpgw_admin_ui_secret

Note: The default credentials above are set by the ARM template. Your deployment may have different values.

Now authenticate using Basic Auth with the client credentials, plus form data with your admin credentials:

# Set your credentials (URL-encode special characters in password, e.g., ! becomes %21)
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
ADMIN_USER="admin"
ADMIN_PASS="yourpassword"  # URL-encoded if it contains special characters

# Get access token
TOKEN=$(curl -s -X POST "https://sftp.example.com/backend/login" \
    -u "${CLIENT_ID}:${CLIENT_SECRET}" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&username=${ADMIN_USER}&password=${ADMIN_PASS}&scope=read" \
    --insecure | jq -r '.access_token')

echo "Token: ${TOKEN:0:20}..."  # Show first 20 chars to verify

# Export backup
curl -s -X GET "https://sftp.example.com/backend/3.0.0/backup" \
    -H "Authorization: Bearer $TOKEN" \
    --insecure \
    -o backup-$(date +%Y%m%d)-pre-rotation.yml

echo "Backup saved. Size: $(wc -c < backup-$(date +%Y%m%d)-pre-rotation.yml) bytes"

Note: Use --insecure if the server uses a self-signed certificate. In production, configure proper TLS certificates.

Store this backup file securely. You may need it for rollback or audit purposes.

Step 2: Create Minimal Rollback YAML

The full backup contains everything: users, folders, permissions, and settings. For a focused rollback that only restores host keys, extract just the hostkeys section.

This minimal file is easier to work with and won't accidentally overwrite other configuration changes if you need to roll back.

# Extract the hostkeys section (from "hostkeys:" to the next top-level key)
sed -n '/^hostkeys:/,/^[a-zA-Z]/p' backup-*-pre-rotation.yml | sed '$d' > rollback-hostkeys-only.yml

# Add the required version header
{
  echo '!<2022-05-05>'
  echo 'version: "2022-05-05"'
  cat rollback-hostkeys-only.yml
} > rollback-hostkeys.yml

Example structure of the rollback file:

The backup uses a list format with base64-encoded keys:

!<2022-05-05>
version: "2022-05-05"
hostkeys:
- keyName: "ssh_host_ed25519"
  keyValue: "LS0tLS1CRUdJTi..."   # Base64-encoded private key
- keyName: "ssh_host_ed25519.pub"
  keyValue: "LS0tLSBCRUdJTi..."   # Base64-encoded SSH2 format public key
- keyName: "ssh_host_rsa"
  keyValue: "LS0tLS1CRUdJTi..."
- keyName: "ssh_host_rsa.pub"
  keyValue: "LS0tLSBCRUdJTi..."
# ... etc for ecdsa_256, ecdsa_384, ecdsa_521

Note: The version header (!<2022-05-05> and version: "2022-05-05") is required for imports to work.

Step 3: Generate New Host Keys

Generate fresh keys on your local workstation, not on the SFTP Gateway servers. This keeps the new private keys off the network until they're securely transmitted via the API.

The following script creates all five key types that SFTP Gateway expects:

WORK_DIR=$(mktemp -d)
cd "$WORK_DIR"

echo "Generating new host keys in: $WORK_DIR"

# RSA 4096-bit (for legacy client compatibility)
ssh-keygen -t rsa -b 4096 -f ssh_host_rsa -N "" -C "sftpgw-rotated-$(date +%Y%m%d)"

# ECDSA (all three curve sizes for maximum compatibility)
ssh-keygen -t ecdsa -b 256 -f ssh_host_ecdsa_256 -N "" -C "sftpgw-rotated-$(date +%Y%m%d)"
ssh-keygen -t ecdsa -b 384 -f ssh_host_ecdsa_384 -N "" -C "sftpgw-rotated-$(date +%Y%m%d)"
ssh-keygen -t ecdsa -b 521 -f ssh_host_ecdsa_521 -N "" -C "sftpgw-rotated-$(date +%Y%m%d)"

# Ed25519 (recommended for modern clients)
ssh-keygen -t ed25519 -f ssh_host_ed25519 -N "" -C "sftpgw-rotated-$(date +%Y%m%d)"

echo ""
echo "Keys generated successfully:"
ls -la

echo ""
echo "New ED25519 fingerprint:"
ssh-keygen -lf ssh_host_ed25519.pub

The -N "" flag creates keys without a passphrase (required for server use). The comment includes the rotation date for future reference.

Step 4: Create Import YAML with New Keys

Package the newly generated keys into a YAML file that matches the format SFTP Gateway expects. The import format requires:

1. A version header (!<2022-05-05> and version: "2022-05-05")
2. Keys in list format with keyName and keyValue pairs
3. All key values base64-encoded
4. Public keys converted to SSH2 format before base64 encoding

WORK_DIR="$1"  # Directory containing generated keys
OUTPUT="new-hostkeys.yml"

# Start with version header
cat > "$OUTPUT" << 'EOF'
!<2022-05-05>
version: "2022-05-05"
hostkeys:
EOF

# Add each key type
for keytype in ssh_host_rsa ssh_host_ecdsa_256 ssh_host_ecdsa_384 ssh_host_ecdsa_521 ssh_host_ed25519; do
    # Private key - base64 encode the entire file (tr -d '\n' removes line breaks on macOS)
    PRIV_B64=$(base64 < "$WORK_DIR/$keytype" | tr -d '\n')
    echo "- keyName: \"$keytype\"" >> "$OUTPUT"
    echo "  keyValue: \"$PRIV_B64\"" >> "$OUTPUT"

    # Public key - convert to SSH2 format, then base64 encode
    PUB_SSH2=$(ssh-keygen -e -f "$WORK_DIR/${keytype}.pub" -m SSH2)
    PUB_B64=$(echo "$PUB_SSH2" | base64 | tr -d '\n')
    echo "- keyName: \"${keytype}.pub\"" >> "$OUTPUT"
    echo "  keyValue: \"$PUB_B64\"" >> "$OUTPUT"
done

echo "Created: $OUTPUT"
echo "File size: $(wc -c < $OUTPUT) bytes"

The generated file should look like:

!<2022-05-05>
version: "2022-05-05"
hostkeys:
- keyName: "ssh_host_rsa"
  keyValue: "LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0t..."
- keyName: "ssh_host_rsa.pub"
  keyValue: "LS0tLSBCRUdJTiBTU0gyIFBVQkxJQyBLRVkgLS0tLQpD..."
# ... etc

Step 5: Import New Keys to Database

This step updates the shared database with your new keys. After this completes successfully, the database contains the new keys, but the running services on each node are still using the old keys loaded in memory.

Via Web UI:

1. Log into SFTP Gateway web admin portal
2. Navigate to Settings > Backup & Recovery
3. Click Import and select new-hostkeys.yml
4. Verify the import log shows the keys were updated successfully

Via API:

# Import the new keys
RESPONSE=$(curl -s -X POST "https://sftp.example.com/backend/3.0.0/backup" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-yaml" \
    --data-binary @new-hostkeys.yml \
    --insecure)

echo "Import response: $RESPONSE"

A successful import returns a JSON array showing which keys were loaded:

["Key ssh_host_ed25519 loaded successfully","Key ssh_host_ecdsa_384 loaded successfully","Key ssh_host_ecdsa_256 loaded successfully","Key ssh_host_ecdsa_521 loaded successfully","Key ssh_host_rsa loaded successfully","Banner text successfully added."]

You should see success messages for all 5 key types. If you see an error, check the YAML syntax, ensure the version header is present, and verify you're authenticated.

Step 6: Restart Java on All Nodes

Now you need to make each node reload its keys from the database. This requires restarting the Java service (sftpgw-admin-api) on every node in the cluster.

Important considerations:

• Each restart will disconnect active SFTP sessions on that node
• The load balancer will route traffic to other nodes during the restart
• Allow a few seconds between node restarts for services to stabilize

Restart each node:

For Azure VMSS deployments, access nodes through the load balancer's NAT ports:

# Define your load balancer IP, SSH user, and NAT ports
LB_IP="<load-balancer-ip>"
SSH_USER="<ssh-user>"  # e.g., ubuntu or azureuser
NAT_PORTS=(2222 2223)  # Add more ports if you have more instances

for port in "${NAT_PORTS[@]}"; do
    echo "=== Restarting Java on instance (port $port) ==="
    ssh -p "$port" "$SSH_USER@$LB_IP" "sudo systemctl restart sftpgw-admin-api"

    # Wait for service to start
    sleep 5

    # Verify it's running
    if ssh -p "$port" "$SSH_USER@$LB_IP" "sudo systemctl is-active --quiet sftpgw-admin-api"; then
        echo "Instance on port $port: Service restarted successfully"
    else
        echo "WARNING: Instance on port $port may not have restarted properly"
        ssh -p "$port" "$SSH_USER@$LB_IP" "sudo systemctl status sftpgw-admin-api"
    fi
    echo ""
done

Note: The SSH user depends on your deployment configuration (commonly ubuntu or azureuser). NAT ports are assigned sequentially starting from 2222 (instance 0 = 2222, instance 1 = 2223, etc.).

If any node fails to restart, check the logs before proceeding:

ssh -p <nat-port> <ssh-user>@<lb-ip> "sudo journalctl -u sftpgw-admin-api -n 50"

Step 7: Verify New Keys Are Active

The final step is confirming that all nodes now serve the new fingerprints. This is crucial for HA deployments because you need to verify consistency across the cluster.

Test through the load balancer multiple times:

# Scan multiple times to hit different nodes
echo "Scanning load balancer endpoint (multiple requests to hit different nodes):"
for i in {1..5}; do
    echo "=== Scan $i ==="
    ssh-keyscan sftp.example.com 2>/dev/null | ssh-keygen -lf -
    sleep 2
done

All scans should return identical fingerprints. If you see different fingerprints on different scans, some nodes haven't restarted properly or aren't reading from the database correctly.

Verify each node directly:

LB_IP="<load-balancer-ip>"
SSH_USER="<ssh-user>"
for port in 2222 2223; do
    echo "=== Instance on port $port ==="
    # Use the private key file (not .pub) because public keys are in SSH2 format
    ssh -p "$port" "$SSH_USER@$LB_IP" "sudo ssh-keygen -lf /opt/sftpgw/ssh_host_ed25519"
done

All nodes should show the same fingerprint. If they match, your rotation is complete.

Note: We check the fingerprint on the private key file rather than the .pub file because SFTP Gateway stores public keys in SSH2 format (for Java compatibility), which ssh-keygen -l cannot parse directly.

---

Rollback Procedure

If something goes wrong after importing new keys, you can restore the original keys. This section covers your options, from quickest to most comprehensive.

Option A: Import Rollback YAML (Recommended)

Use the minimal rollback file you created in Step 2. This restores only the host keys without affecting users, folders, or other settings.

Via Web UI:

1. Navigate to Settings > Backup & Recovery
2. Click Import and select rollback-hostkeys.yml
3. Restart Java on all nodes (see Step 6)

Via API:

# Import the rollback keys (ensure rollback file has version header)
curl -X POST "https://sftp.example.com/backend/3.0.0/backup" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-yaml" \
    --data-binary @rollback-hostkeys.yml \
    --insecure

# Restart all nodes (Azure VMSS via NAT ports)
LB_IP="<load-balancer-ip>"
SSH_USER="<ssh-user>"  # e.g., ubuntu or azureuser
for port in 2222 2223; do
    echo "Restarting instance on port $port..."
    ssh -p "$port" "$SSH_USER@$LB_IP" "sudo systemctl restart sftpgw-admin-api"
    sleep 3
done

Note: Ensure your rollback file has the version header (!<2022-05-05> and version: "2022-05-05"). If it was extracted from an older backup that lacks this, add it manually.

Option B: Import Full Backup

If you don't have the minimal rollback file, use the complete pre-rotation backup:

curl -X POST "https://sftp.example.com/backend/3.0.0/backup" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-yaml" \
    --data-binary @backup-YYYYMMDD-pre-rotation.yml \
    --insecure

⚠️ WARNING: This restores ALL settings from the backup timestamp, not just host keys. Any configuration changes made after the backup (new users, modified folders, etc.) will be lost.

Option C: Manual Recovery from Filesystem

If you have old keys backed up from /opt/sftpgw/ on any node:

1. Copy the old key files to a working directory
2. Create a YAML import file from those keys (following the format in Step 4)
3. Import via web UI or API
4. Restart Java on all nodes

This approach is more labor-intensive but works as a last resort if you don't have a proper YAML backup.

---

Automation Script

For environments that rotate keys regularly, we provide a script that automates the entire process. It handles authentication, backup creation, key generation, import, and service restarts.

Usage:

# Preview what would happen (no changes made)
./scripts/rotate-hostkeys-ha.sh \
    --gateway https://sftp.example.com \
    --nodes "node1,node2,node3" \
    --dry-run

# Execute the rotation
SFTPGW_PASSWORD=yourpassword ./scripts/rotate-hostkeys-ha.sh \
    --gateway https://sftp.example.com \
    --nodes "node1,node2,node3"

The script will:

1. Authenticate to the SFTP Gateway API
2. Export a full backup (rollback artifact)
3. Extract a minimal host-keys-only rollback file
4. Generate new keys locally
5. Create and import the new key YAML
6. Restart Java on each node sequentially
7. Verify the new fingerprints

All backup and rollback files are saved to ./hostkey-backups/ (or specify with --backup-dir).

See ./scripts/rotate-hostkeys-ha.sh --help for all options.

---

Quick Reference

This section provides copy-paste commands for common operations.

Get Access Token

TOKEN=$(curl -s -X POST "https://sftp.example.com/backend/login" \
    -u "${CLIENT_ID}:${CLIENT_SECRET}" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&username=${ADMIN_USER}&password=${ADMIN_PASS}&scope=read" \
    --insecure | jq -r '.access_token')

Export Backup (API)

curl -X GET "https://sftp.example.com/backend/3.0.0/backup" \
    -H "Authorization: Bearer $TOKEN" \
    --insecure -o backup.yml

Import Backup (API)

curl -X POST "https://sftp.example.com/backend/3.0.0/backup" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-yaml" \
    --data-binary @import.yml \
    --insecure

Restart Java Service

sudo systemctl restart sftpgw-admin-api

Check Service Status

sudo systemctl status sftpgw-admin-api
sudo journalctl -u sftpgw-admin-api -n 50

Verify Key Fingerprints

ssh-keyscan sftp.example.com 2>/dev/null | ssh-keygen -lf -

Check Keys on Specific Node

# Use private key file (public keys are SSH2 format)
sudo ssh-keygen -lf /opt/sftpgw/ssh_host_ed25519

---

Troubleshooting

Import Succeeds but Keys Don't Change

The import updates the database, but nodes continue using keys loaded in memory until restarted.

Solution: Ensure you've restarted the Java service on ALL nodes:

LB_IP="<load-balancer-ip>"
SSH_USER="<ssh-user>"  # e.g., ubuntu or azureuser
for port in 2222 2223; do
    ssh -p "$port" "$SSH_USER@$LB_IP" "sudo systemctl restart sftpgw-admin-api"
done

Also check /var/log/sftpgw/sftpgw-admin-api.log for errors reading keys from the database.

Nodes Show Different Fingerprints

Some nodes may not have restarted properly, or may have failed to read from the database.

Diagnosis:

# Check each node's current fingerprint (use private key file, not .pub)
LB_IP="<load-balancer-ip>"
SSH_USER="<ssh-user>"  # e.g., ubuntu or azureuser
for port in 2222 2223; do
    echo "=== Instance on port $port ==="
    ssh -p "$port" "$SSH_USER@$LB_IP" "sudo ssh-keygen -lf /opt/sftpgw/ssh_host_ed25519"
    ssh -p "$port" "$SSH_USER@$LB_IP" "sudo systemctl is-active sftpgw-admin-api"
done

Solution: Restart the Java service on any node showing old fingerprints:

ssh -p <nat-port> <ssh-user>@<load-balancer-ip> "sudo systemctl restart sftpgw-admin-api"

Service Won't Start After Import

This usually indicates a problem with the YAML format — invalid syntax, missing keys, or malformed data.

Diagnosis:

ssh -p <nat-port> <ssh-user>@<lb-ip> "sudo journalctl -u sftpgw-admin-api -n 100"

Solution:

1. Roll back using the pre-rotation backup
2. Review the import YAML for syntax errors
3. Regenerate keys and try again

Import Fails with "missing type id property 'version'"

This error occurs when the import YAML is missing the required version header.

Solution: Add the version header to the beginning of your import file:

!<2022-05-05>
version: "2022-05-05"
hostkeys:
- keyName: "ssh_host_ed25519"
  keyValue: "..."

Both lines are required: the YAML tag !<2022-05-05> and the version: "2022-05-05" field.

Authentication Fails for API Calls

SFTP Gateway 3.x uses OAuth2-style authentication requiring both client credentials and user credentials.

Step 1: Get the client credentials from the server (use NAT port for your instance):

ssh -p 2222 <ssh-user>@<load-balancer-ip> "sudo grep -E 'security.client' /opt/sftpgw/application.properties"

Step 2: Authenticate using Basic Auth with client credentials plus form data with admin credentials:

# URL-encode special characters in password (e.g., ! becomes %21)
TOKEN=$(curl -s -X POST "https://sftp.example.com/backend/login" \
    -u "${CLIENT_ID}:${CLIENT_SECRET}" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&username=${ADMIN_USER}&password=${ADMIN_PASS}&scope=read" \
    --insecure | jq -r '.access_token')

Common issues:

• 401 Unauthorized: Check that client credentials from application.properties are correct
• Special characters in password: URL-encode them (e.g., Password1! becomes Password1%21)
• Wrong Content-Type: Must be application/x-www-form-urlencoded, not JSON

Load Balancer Health Checks Fail During Restart

During node restarts, the load balancer may mark nodes as unhealthy temporarily.

Solution: This is expected behavior. The load balancer will route traffic to healthy nodes. Wait for all restarts to complete and verify health checks pass before considering the rotation complete.

---

Client Communication

After rotating keys, your users will see host key warnings on their next connection. Proactive communication prevents confusion and support tickets.

Notification Template

Subject: Scheduled SFTP Host Key Rotation - Action Required

On [DATE], we will rotate the SSH host keys for sftp.example.com as part
of our security maintenance procedures.

After the rotation, you will see a warning about the host key changing
on your next connection. This is expected and not a security concern.

To update your known_hosts file after the rotation, run:
    ssh-keygen -R sftp.example.com
    ssh-keyscan sftp.example.com >> ~/.ssh/known_hosts

Or accept the new key when prompted on your next connection.

New fingerprints (available after rotation):
- ED25519: SHA256:xxxxxxxxxxxx
- RSA: SHA256:yyyyyyyyyyyy

The maintenance window is [TIME] to [TIME]. Brief disconnections may
occur during this period.

Questions? Contact support@example.com

---

Summary

Rotating host keys in an HA SFTP Gateway deployment requires coordinating changes across all nodes through the shared database. The key points to remember:

1. Database is the source of truth - Always update keys via the backup/restore API, not by editing files
2. Backup first - Create rollback artifacts before making changes
3. Restart all nodes - Every node must restart to load new keys from the database
4. Verify consistency - Check that all nodes present identical fingerprints
5. Communicate with users - Let clients know about the change to prevent confusion

The process is straightforward once you understand the architecture. With proper backups and verification, you can rotate keys confidently.

---

References

• Backup and Recovery
• Server Host Keys
• HA Stack Upgrade
• Common Issues
• API Documentation