Fiber Node Backup

TL;DR

Stop the node, tar the entire node directory, store the archive and FIBER_SECRET_KEY_PASSWORD securely. To restore, extract the archive and start the node with the same password.

This guide explains how to securely back up Fiber node data to safeguard funds, maintain node identity, and ensure smooth migration or upgrades. Never store plaintext private keys, as they risk theft if exposed.

1. Why Back Up?

Backups protect:

• Funds: The encrypted private key (ckb/key) and its password (FIBER_SECRET_KEY_PASSWORD) are critical for accessing funds. Losing either makes funds unrecoverable.
• Node Identity: The network ID key (fiber/sk) allows other nodes to recognize your node. Losing it disrupts network communication.

Warning: Always stop the node before backing up to prevent data corruption, which could cause errors or loss of funds.

2. Backing Up Node Data

Back up the entire node directory (node1), which includes:

• ckb/key (encrypted private key)
• fiber/sk (network ID key)
• fiber/store (database files)
• config.yml (configuration)

Steps:

1. Stop the Node:

   # Check for running node processes
   ps aux | grep fnn
   # Example output: ckb 3585187 0.7 2.4 756932 194052 ? Sl May07 71:52 ./fnn -c ./node1/config.yml -d ./node1
   # Terminate it (replace 3585187 with your process ID)
   kill 3585187

2. Create Backup:

   tar -zcvf node1.tar.gz node1

3. Store Securely: Save node1.tar.gz and the FIBER_SECRET_KEY_PASSWORD in an offline, encrypted environment (e.g., an encrypted drive or password manager).

Note: A future update will allow backups without stopping the node. Check release notes for updates.

3. Restoring Node Data

Steps:

1. Extract Backup:

   tar -zxvf node1.tar.gz

2. Start Node:

   FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' ./fnn -c ./node1/config.yml -d ./node1

   If the backup was created with an older Fiber version, the node will detect the database version mismatch on startup and prompt you to confirm a migration. Simply follow the on-screen prompt to proceed.

Warning: Using the wrong password will trigger a startup error (Secret key file error: decryption failed). Double-check the password before starting.

4. Handling Forgotten Passwords

If you lose the FIBER_SECRET_KEY_PASSWORD but have a plaintext private key (not recommended), you can reset the password.

Steps:

1. Extract Backup:

   tar -zxvf node1.tar.gz

2. Remove Encrypted Key:

   rm -rf node1/ckb

3. Add Plaintext Key:

   mkdir node1/ckb
   echo "YOUR_PLAINTEXT_KEY" > node1/ckb/key

4. Start Node with New Password:

   FIBER_SECRET_KEY_PASSWORD='NEW_PASSWORD' ./fnn -c ./node1/config.yml -d ./node1

5. Secure the Key: The ckb/key file will be re-encrypted with the new password. Store the new password securely.

5. Cross-Version Restore

When restoring a backup created on an older Fiber version, the on-disk database schema may differ. How you proceed depends on the source version.

From v0.8.x to v0.9.0-rc4

No extra steps are needed. Extract the backup and start the new fnn binary — it will detect the older database and run migration automatically on startup, prompting you for confirmation before proceeding.

tar -zxvf node1.tar.gz
FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' ./fnn -c ./node1/config.yml -d ./node1

From v0.7.x or older to v0.9.0-rc4

Databases older than version 20260302100001 (pre-v0.8.x) cannot be migrated directly by the v0.9.0-rc4 fnn binary. You must first upgrade the database using the v0.8.x fnn-migrate tool, then start the new node.

1. Download the fnn-migrate binary from the v0.8.x release assets.
2. Run migration to upgrade the database to version 20260302100001:

   ./fnn-migrate -d ./node1

3. Start the v0.9.0-rc4 node — it will handle any remaining migration automatically:

   FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' ./fnn -c ./node1/config.yml -d ./node1