IPFS Private Swarm CLI - Complete Setup Guide

NPM Package

npm install ipfs-swarm-cli22

Table of Contents

1. Understanding IPFS Private Swarms
2. Installation
3. Setting Up Bootstrap Node
4. Adding Regular Nodes
5. Testing Your Swarm
6. Monitoring and Management
7. Troubleshooting
8. Advanced Configuration

Understanding IPFS Private Swarms

What is IPFS?

IPFS (InterPlanetary File System) is a distributed, peer-to-peer protocol for storing and sharing data. It creates a decentralized network where files are identified by their content (using cryptographic hashes) rather than their location.

Private Swarms Explained

A private IPFS swarm is an isolated network of IPFS nodes that:

• Only communicate with each other (not the public IPFS network)
• Share a common swarm key for authentication
• Have their own bootstrap nodes for peer discovery
• Provide complete control over data storage and access

Key Concepts

Bootstrap Node: The first/primary node in your swarm that:

• Generates the swarm key
• Acts as the entry point for other nodes
• Helps with peer discovery

Regular Node: Secondary nodes that:

• Join an existing swarm using the bootstrap node's information
• Use the same swarm key as the bootstrap node
• Can store and retrieve data from the swarm

Swarm Key: A cryptographic key that:

• Ensures only authorized nodes can join
• Provides network isolation from public IPFS
• Must be shared securely between all nodes

Multiaddr: IPFS addressing format that specifies:

• Network protocol (IP4/IP6)
• IP address and port
• Node ID (peer ID)
• Example: /ip4/192.168.1.100/tcp/4001/p2p/QmNodeID...

Installation

Prerequisites

• Linux (Ubuntu/Debian recommended) or macOS
• Node.js and npm
• sudo privileges
• Internet connection for initial setup

Install the CLI

npm install -g ipfs-swarm-cli22

Verify Installation

ipfs-swarm-cli2 --help

Setting Up Bootstrap Node

The bootstrap node is the foundation of your private swarm. Follow these steps:

Step 1: Initialize Bootstrap Node

Interactive Setup (Recommended)

ipfs-swarm-cli2 init

You'll be prompted to choose:

• Node Type: Select "Bootstrap Node (First/Primary node)"
• Network Type:
  • "Normal IP" for local network or public internet
  • "Tailscale" for secure mesh networking
• Port: Default 4001 (or choose custom)

Command Line Setup

# For normal IP networking
ipfs-swarm-cli2 init --bootstrap --normal --port 4001

# For Tailscale networking
ipfs-swarm-cli2 init --bootstrap --tailscale --port 4001

Step 2: Start Bootstrap Node

ipfs-swarm-cli2 start

Step 3: Record Bootstrap Information

After starting, you'll see output like:

📊 Node Information:
  Node ID: QmBootstrapNodeID123...
  Type: bootstrap
  Network: normal
  Port: 4001

🚀 Bootstrap Node Ready:
  Local: /ip4/127.0.0.1/tcp/4001/p2p/QmBootstrapNodeID123...
  External: /ip4/203.0.113.1/tcp/4001/p2p/QmBootstrapNodeID123...

📋 Share this information with other nodes:
  Swarm Key: /home/user/.ipfs-swarm/swarm.key
  Bootstrap Address: /ip4/203.0.113.1/tcp/4001/p2p/QmBootstrapNodeID123...

Important: Save both the swarm key file and bootstrap address - you'll need them for regular nodes!

Step 4: Verify Bootstrap Node

# Check daemon status
ipfs-swarm-cli2 status

# View detailed info
ipfs-swarm-cli2 info

# Test functionality
ipfs-swarm-cli2 test

Adding Regular Nodes

Regular nodes join the existing swarm using the bootstrap node's information.

Step 1: Copy Swarm Key

Transfer the swarm key file from the bootstrap node to your regular node:

# Copy from bootstrap node (adjust path as needed)
scp user@bootstrap-ip:/home/user/.ipfs-swarm/swarm.key ./swarm.key

Step 2: Initialize Regular Node

Interactive Setup

ipfs-swarm-cli2 init

Choose:

• Node Type: "Regular Node (Joins existing swarm)"
• Network Type: Match your bootstrap node's choice
• Port: Default 4001 (or match bootstrap)
• Swarm Key Path: Path to the copied swarm key file
• Bootstrap Address: The multiaddr from bootstrap node

Command Line Setup

# For normal networking
ipfs-swarm-cli2 init --regular --normal --port 4001 \
  --swarm-key ./swarm.key \
  --bootstrap-addr "/ip4/203.0.113.1/tcp/4001/p2p/QmBootstrapNodeID123..."

# For Tailscale networking
ipfs-swarm-cli2 init --regular --tailscale --port 4001 \
  --swarm-key ./swarm.key \
  --bootstrap-addr "/ip4/100.64.0.1/tcp/4001/p2p/QmBootstrapNodeID123..."

Step 3: Start Regular Node

ipfs-swarm-cli2 start

Step 4: Verify Connection

# Check if connected to swarm
ipfs-swarm-cli2 status

# Should show connected peers
ipfs-swarm-cli2 debug

Testing Your Swarm

Basic Connectivity Test

On any node:

ipfs-swarm-cli2 test

Manual File Operations

# Add a file to IPFS
echo "Hello Private Swarm!" > test.txt
ipfs add test.txt
# Returns: QmHash123...

# Retrieve file from another node
ipfs cat QmHash123...
# Should return: Hello Private Swarm!

Check Peer Connections

# List connected peers
ipfs swarm peers

# Show local node addresses
ipfs swarm addrs local

# Show bootstrap list
ipfs bootstrap list

Monitoring and Management

Check Status

# Quick status check
ipfs-swarm-cli2 status

# Detailed configuration
ipfs-swarm-cli2 info

# Debug connection issues
ipfs-swarm-cli2 debug

Start/Stop Management

# Start daemon
ipfs-swarm-cli2 start

# Stop daemon
ipfs-swarm-cli2 stop

# Restart (stop then start)
ipfs-swarm-cli2 stop && ipfs-swarm-cli2 start

Manual Peer Connection

# Connect to specific peer
ipfs-swarm-cli2 connect "/ip4/192.168.1.100/tcp/4001/p2p/QmPeerID..."

Troubleshooting

Common Issues and Solutions

1. "IPFS daemon is not running"

Solution:

ipfs-swarm-cli2 start

2. "No peers connected"

Diagnosis:

ipfs-swarm-cli2 debug

Common causes:

• Firewall blocking port 4001
• Incorrect bootstrap address
• Network connectivity issues
• Swarm key mismatch

Solutions:

# Check firewall (Ubuntu/Debian)
sudo ufw status
sudo ufw allow 4001

# Test manual connection
ipfs-swarm-cli2 connect "/ip4/BOOTSTRAP_IP/tcp/4001/p2p/PEER_ID"

# Verify bootstrap configuration
ipfs bootstrap list

3. "Connection refused" errors

Solutions:

# Check if daemon is running
ps aux | grep ipfs

# Kill existing processes
ipfs-swarm-cli2 stop

# Clear and restart
ipfs-swarm-cli2 stop
ipfs-swarm-cli2 start

4. "Swarm key mismatch"

Solution:

• Ensure all nodes use the exact same swarm key file
• Re-copy the key from bootstrap node
• Reinitialize with correct key

5. Port conflicts

Symptoms:

• "Address already in use" errors
• Daemon won't start

Solutions:

# Check what's using the port
sudo netstat -tulpn | grep :4001

# Kill conflicting processes
sudo pkill -f "ipfs daemon"

# Use different port
ipfs-swarm-cli2 init --port 4002

6. Tailscale connectivity issues

Diagnosis:

ipfs-swarm-cli2 tailscale

Solutions:

# Start Tailscale
sudo tailscale up

# Check IP
tailscale ip

# Test connection
ping TAILSCALE_IP

Advanced Debugging

View Full IPFS Configuration

ipfs config show

Check Swarm Addresses

ipfs swarm addrs local

Monitor Logs

# View daemon logs
ipfs log tail

Network Diagnostics

# Test external connectivity
curl -s https://api.ipify.org  # Shows public IP

# Test port connectivity
nc -zv BOOTSTRAP_IP 4001

Advanced Configuration

Custom Port Configuration

# Initialize with custom port
ipfs-swarm-cli2 init --port 5001

# This sets:
# - Swarm port: 5001
# - API port: 6001 (5001 + 1000)
# - Gateway port: 9081 (5001 + 4080)

Tailscale Setup

# Install and configure Tailscale
ipfs-swarm-cli2 tailscale

# Initialize with Tailscale
ipfs-swarm-cli2 init --tailscale

Clean Reinstall

# Remove all IPFS data and configuration
ipfs-swarm-cli2 clean

# Reinstall from scratch
ipfs-swarm-cli2 init

Configuration Files

# Main config
~/.ipfs-swarm/config.json

# Swarm key
~/.ipfs-swarm/swarm.key

# IPFS data
~/.ipfs/

Web Interface Access

Once running, access the IPFS web interface at:

• API: http://localhost:5001 (port + 1000)
• Gateway: http://localhost:8081 (port + 4080)

Sample Network Topology

Bootstrap Node (192.168.1.100)
├── Regular Node 1 (192.168.1.101)
├── Regular Node 2 (192.168.1.102)
└── Regular Node 3 (100.64.0.1) [Tailscale]

Security Considerations

1. Swarm Key Security: Keep your swarm key secure and only share with trusted nodes
2. Network Isolation: Private swarms are isolated from public IPFS
3. Firewall Rules: Only open necessary ports (4001 by default)
4. Regular Updates: Keep IPFS updated for security patches

Performance Tips

1. Resource Allocation: IPFS can use significant CPU/memory with many files
2. Storage Management: Monitor disk usage in ~/.ipfs/blocks/
3. Connection Limits: Default connection manager limits are adequate for most use cases
4. Garbage Collection: Run ipfs repo gc periodically to clean unused data

This guide should get you started with a fully functional private IPFS swarm. For additional help, use ipfs-swarm-cli2 --help or check the debug command for connection issues.