Node Setup - Knotsday

Overview

This guide walks you through a complete Bitcoin Knots installation on Ubuntu. By the end, you will have a fully synced node running on a properly formatted ext4 drive.

Do not use exFAT or NTFS for your blockchain storage. exFAT has no journaling — a crash or power loss during writes can silently zero out block files, corrupting your data with no way to recover. Always use ext4.

Step 1: Prepare Your Drive

Identify your drive

Plug in your 2 TB drive and find its device name:

lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT,MODEL

Look for your drive (e.g. /dev/sda or /dev/sdb). Note the device name — you will need it for formatting.

Double-check the device name. Formatting the wrong drive will destroy all data on it. Your system drive is usually /dev/nvme0n1 or /dev/sda — make sure you are targeting the correct external drive.

Format as ext4

If the drive has existing partitions you want to keep the partition table, just format the target partition. For a fresh drive, create a single ext4 partition:

# Unmount if currently mounted
sudo umount /dev/sdX1

# Create a new GPT partition table and single partition
sudo parted /dev/sdX mklabel gpt
sudo parted /dev/sdX mkpart primary ext4 0% 100%

# Format as ext4 with a label
sudo mkfs.ext4 -L bitcoin /dev/sdX1

# Set ownership so your user can write to it
sudo mkdir -p /media/$USER/bitcoin
sudo mount /dev/sdX1 /media/$USER/bitcoin
sudo chown $USER:$USER /media/$USER/bitcoin

Replace /dev/sdX with your actual device (e.g. /dev/sdb). Replace sdX1 with the partition (e.g. sdb1).

Auto-mount on boot

Add the drive to /etc/fstab so it mounts automatically:

# Get the UUID of your partition
sudo blkid /dev/sdX1

# Add to /etc/fstab (replace UUID with yours)
echo 'UUID=your-uuid-here /media/$USER/bitcoin ext4 defaults,noatime 0 2' | sudo tee -a /etc/fstab

# Test the fstab entry
sudo mount -a

Or use the automated script: prepare-drive.sh

Step 2: Install Bitcoin Knots

Download the latest release

Visit bitcoinknots.org and download the latest Linux x86_64 tarball, or use the command line:

# Set the version (check bitcoinknots.org for the latest)
KNOTS_VERSION="29.3.knots20260508"

# Download
cd /tmp
wget "https://bitcoinknots.org/files/29.x/${KNOTS_VERSION}/bitcoin-${KNOTS_VERSION}-x86_64-linux-gnu.tar.gz"

# Extract
tar xzf "bitcoin-${KNOTS_VERSION}-x86_64-linux-gnu.tar.gz"

# Install to ~/.local/bin
mkdir -p ~/.local/bin
cp "bitcoin-${KNOTS_VERSION}/bin/"* ~/.local/bin/

# Verify
bitcoind --version

Make sure ~/.local/bin is in your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc if needed.

Configure Bitcoin Knots

Create the configuration file:

mkdir -p ~/.bitcoin

cat > ~/.bitcoin/bitcoin.conf <<'EOF'
# Bitcoin Knots Configuration
# ===========================

# Point to your ext4 drive
datadir=/media/YOUR_USER/bitcoin/.bitcoin

# Run as a daemon
daemon=1

# Full transaction index
txindex=1

# UTXO statistics index
coinstatsindex=1

# RPC server
server=1

# RPC credentials (CHANGE THESE)
rpcuser=your_rpc_username
rpcpassword=your_secure_rpc_password_here

# Reject replace-by-fee abuse
mempoolreplacement=0

# Performance tuning
# Start with high dbcache for initial sync, lower to 1000 after
dbcache=4000
rpcworkqueue=128
rpcthreads=8
EOF

Change the RPC credentials! Use a strong random password. You can generate one with: python3 -c "import secrets; print(secrets.token_hex(32))"

Create the data directory

mkdir -p /media/YOUR_USER/bitcoin/.bitcoin

Step 3: Start the Node

Initial sync

# Start the GUI (recommended for first run)
bitcoin-qt &

# Or start the daemon
bitcoind

# Check sync progress
bitcoin-cli -rpcuser=your_rpc_username \
  -rpcpassword=your_secure_rpc_password_here \
  getblockchaininfo

The initial sync downloads and validates the entire blockchain (~600+ GB). This takes several hours to a full day depending on your internet speed and CPU.

During initial sync, dbcache=4000 (4 GB) significantly speeds things up by keeping more of the UTXO set in RAM. After sync completes, you can lower it to 1000 to save memory.

Verify it is working

# Check block height (should be increasing)
bitcoin-cli -rpcuser=your_rpc_username \
  -rpcpassword=your_secure_rpc_password_here \
  getblockcount

# Check network connections
bitcoin-cli -rpcuser=your_rpc_username \
  -rpcpassword=your_secure_rpc_password_here \
  getconnectioncount

# Check sync progress (1.0 = fully synced)
bitcoin-cli -rpcuser=your_rpc_username \
  -rpcpassword=your_secure_rpc_password_here \
  getblockchaininfo | grep verificationprogress

Step 4: Updating Bitcoin Knots

Update to a new version

When a new version is released:

# Stop the running node
bitcoin-cli -rpcuser=your_rpc_username \
  -rpcpassword=your_secure_rpc_password_here \
  stop

# Wait for it to shut down
sleep 10

# Download and install the new version (same as step 4)
KNOTS_VERSION="NEW_VERSION_HERE"
cd /tmp
wget "https://bitcoinknots.org/files/29.x/${KNOTS_VERSION}/bitcoin-${KNOTS_VERSION}-x86_64-linux-gnu.tar.gz"
tar xzf "bitcoin-${KNOTS_VERSION}-x86_64-linux-gnu.tar.gz"
cp "bitcoin-${KNOTS_VERSION}/bin/"* ~/.local/bin/

# Start the node again
bitcoind

# Verify the version
bitcoind --version

Automated Setup Script

For a one-command setup, download and review the install script:

# Download the script
wget https://knotsday.com/scripts/setup-knots.sh

# ALWAYS review scripts before running them
cat setup-knots.sh

# Make executable and run
chmod +x setup-knots.sh
./setup-knots.sh

The script handles drive preparation, Bitcoin Knots installation, configuration, and initial startup. See the full script source.

Troubleshooting

Node won't start

Check the debug log:

tail -50 /media/YOUR_USER/bitcoin/.bitcoin/debug.log

"Failed to read block" errors

This means block files are corrupted. If you see this, run a reindex:

bitcoin-qt -reindex &

The node will scan all existing block files, rebuild indexes, and re-download any missing data from peers. This takes several hours.

Common cause: Using exFAT or NTFS instead of ext4. If your drive is not ext4, back up your data, reformat to ext4, restore, and reindex. See the migration script.

Sync is very slow

Increase dbcache (e.g. dbcache=8000 if you have 16+ GB RAM)
Make sure you are using an SSD, not an HDD
Check your internet connection — Bitcoin uses port 8333
Close other disk-intensive applications during initial sync

Next Steps

Your node is running. You are validating every transaction and every block. You are enforcing the rules. But you can go further:

Solo Mine (Bitaxe / ASIC)

Point a Bitaxe or dedicated ASIC at your node and mine blocks that enforce your rules.

Bitaxe Guide

Readiness Check

Verify every system is operational before the charge at dawn.

Readiness