Neighbor Commands

Overview

Neighbor commands enable peer-to-peer discovery and synchronization with other cpm servers on your local network. These commands support automatic network scanning, manual registration, connectivity testing, and repository synchronization between peer servers.

Table of Contents

cpm neighbors list

Description

Display all registered neighbor servers with their connection details and status.

Syntax

cpm neighbors list [flags]

Flags

Flag Type Description
--format <type> string Output format: table, json, yaml
--online-only boolean Show only reachable neighbors

Examples

cpm neighbors list

# Output:
# NEIGHBOR SERVERS
#
# Host             Port   Status   Last Seen            Added
# ---------------  -----  -------  -------------------  -------------------
# 192.168.1.100    9418   Online   2024-01-15 10:30:00  2024-01-15 09:00:00
# 192.168.1.101    9418   Online   2024-01-15 10:29:00  2024-01-15 09:00:00
# 192.168.1.102    9418   Offline  2024-01-15 09:15:00  2024-01-15 09:00:00
#
# Total: 3 neighbors (2 online)

# Online neighbors only
cpm neighbors list --online-only

# Output:
# NEIGHBOR SERVERS (online only)
#
# Host             Port   Response Time  Repositories
# ---------------  -----  -------------  ------------
# 192.168.1.100    9418   12ms           15
# 192.168.1.101    9418   8ms            23
#
# Total: 2 online neighbors

cpm neighbors discover

Description

Scan the local network for reachable cpm servers. Automatically detects peers and optionally adds them as neighbors.

Syntax

cpm neighbors discover [flags]

Flags

Flag Type Description
--network <cidr> string Network CIDR to scan (e.g., 192.168.1.0/24)
--port <number> int Port to scan (default: 9418)
--timeout <duration> string Connection timeout (default: 2s)
--add boolean Automatically add discovered neighbors

Behavior

  1. Detects local network if not specified
  2. Generates list of hosts to scan
  3. Attempts connection on cpm port (default 9418)
  4. Identifies reachable cpm servers
  5. Optionally adds discovered servers as neighbors
  6. Displays discovery results

Examples

# Discover on default network
cpm neighbors discover

# Output:
# Discovering cpm servers on local network...
# Detected network: 192.168.1.0/24
# Scanning 254 hosts...
#
# Progress: [################] 100% (254/254)
#
# DISCOVERED SERVERS
#
# Host             Port   Response Time  Version
# ---------------  -----  -------------  -------
# 192.168.1.100    9418   12ms           1.0.0
# 192.168.1.101    9418   8ms            1.0.0
# 192.168.1.102    9418   15ms           1.0.0
#
# Discovered: 3 servers
#
# To add these neighbors:
#   cpm neighbors discover --add
# Or add individually:
#   cpm neighbors add 192.168.1.100

# Discover specific network
cpm neighbors discover --network 10.0.1.0/24

# Output:
# Discovering cpm servers on 10.0.1.0/24...
# Scanning 254 hosts...
# Discovered: 5 servers

# Discover and auto-add
cpm neighbors discover --add

# Output:
# Discovering cpm servers on local network...
# Discovered: 3 servers
# Adding neighbors...
#   Added: 192.168.1.100
#   Added: 192.168.1.101
#   Added: 192.168.1.102
# Successfully added 3 neighbors

# Custom port
cpm neighbors discover --port 2222 --network 192.168.1.0/24

Performance

Discovery scans use concurrent connections with configurable limits:

  • Default concurrency: 50 simultaneous connections
  • Default timeout: 2 seconds per host
  • Typical scan time: 10-30 seconds for /24 network

cpm neighbors add

Description

Manually register a neighbor server. Useful for adding specific servers or those on different networks.

Syntax

cpm neighbors add <host>

Arguments

Argument Required Description
host Yes Neighbor host address (optionally with :port)

Examples

# Add neighbor with default port
cpm neighbors add 192.168.1.100

# Output:
# Testing connectivity to 192.168.1.100:9418...
# Connected successfully
# Neighbor '192.168.1.100' added
# Response time: 12ms
# Repositories available: 15

# Add with custom port
cpm neighbors add 192.168.1.100:2222

# Output:
# Neighbor '192.168.1.100:2222' added

# Add by hostname
cpm neighbors add cpm-server.local

# Output:
# Resolving cpm-server.local...
# Neighbor 'cpm-server.local' (192.168.1.100) added

Common Errors

Error Cause Solution
host not reachable Server offline or blocked Check connectivity
connection timeout Server not responding Verify port and firewall
neighbor already exists Already registered Use cpm neighbors list to verify

cpm neighbors remove

Description

Remove a neighbor server from the configuration. Does not affect the remote server.

Syntax

cpm neighbors remove <host>

Arguments

Argument Required Description
host Yes Neighbor host address to remove

Examples

cpm neighbors remove 192.168.1.100

# Prompt:
# Remove neighbor '192.168.1.100'? (y/N): y

# Output:
# Neighbor '192.168.1.100' removed

cpm neighbors ping

Description

Test connectivity to a neighbor server. Verifies server is reachable and responding.

Syntax

cpm neighbors ping <host>

Arguments

Argument Required Description
host Yes Neighbor host address to ping

Examples

cpm neighbors ping 192.168.1.100

# Output:
# Pinging 192.168.1.100:9418...
# Connected successfully
# Response time: 12ms
# Server version: 1.0.0
# Status: Online
# Repositories: 15

cpm neighbors ping offline-server

# Output:
# Pinging offline-server:9418...
# Connection timeout
# Status: Offline

cpm neighbors sync

Description

Synchronize a repository with a neighbor server. Supports bidirectional sync (push to or pull from neighbor).

Syntax

cpm neighbors sync <repo> [flags]

Arguments

Argument Required Description
repo Yes Repository name to synchronize

Flags

Flag Type Description
--to <neighbor> string Push repository to neighbor
--from <neighbor> string Pull repository from neighbor

Behavior

  1. Validates repository exists (local for push, remote for pull)
  2. Establishes connection with neighbor
  3. Uses rsync for efficient transfer
  4. Updates local database with sync timestamp
  5. Displays transfer statistics

Examples

# Push to neighbor
cpm neighbors sync myrepo --to 192.168.1.100

# Output:
# Syncing repository 'myrepo' to neighbor 192.168.1.100...
# Connecting...
# Transferring files...
#
# Files transferred: 147
# Total size: 24.5 MB
# Transfer time: 2.8s
# Average speed: 8.8 MB/s
#
# Repository 'myrepo' successfully synced to 192.168.1.100

# Pull from neighbor
cpm neighbors sync webapp --from 192.168.1.101

# Output:
# Syncing repository 'webapp' from neighbor 192.168.1.101...
# Connecting...
# Transferring files...
#
# Files received: 892
# Total size: 156.8 MB
# Transfer time: 15.2s
# Average speed: 10.3 MB/s
#
# Repository 'webapp' successfully synced from 192.168.1.101

Neighbor Discovery Workflows

Initial Network Discovery

# Discover all neighbors
cpm neighbors discover

# Review discovered neighbors
cpm neighbors list

# Add selected neighbors
cpm neighbors add 192.168.1.100
cpm neighbors add 192.168.1.101

# Test connectivity
cpm neighbors ping 192.168.1.100
cpm neighbors ping 192.168.1.101

# Sync repository
cpm neighbors sync myrepo --to 192.168.1.100

Automatic Discovery and Setup

# Discover and auto-add all neighbors
cpm neighbors discover --add

# Verify all neighbors
cpm neighbors list

# Test all neighbors
for neighbor in $(cpm neighbors list --format json | jq -r '.[].host'); do
  echo "Testing $neighbor..."
  cpm neighbors ping $neighbor
done

# Sync repository to all neighbors
for neighbor in $(cpm neighbors list --format json | jq -r '.[].host'); do
  cpm neighbors sync myrepo --to $neighbor
done

Peer-to-Peer Backup

# Setup bidirectional sync
cpm neighbors add 192.168.1.100
cpm neighbors add 192.168.1.101

# Push local repos to neighbors
for repo in $(cpm list --format json | jq -r '.[].name'); do
  cpm neighbors sync $repo --to 192.168.1.100
  cpm neighbors sync $repo --to 192.168.1.101
done

# Pull repos from neighbor
cpm neighbors sync external-repo --from 192.168.1.100

Network Health Check

# Check all neighbors
echo "Neighbor Health Check"
echo "===================="

for neighbor in $(cpm neighbors list --format json | jq -r '.[].host'); do
  echo "Checking $neighbor..."
  if cpm neighbors ping $neighbor > /dev/null 2>&1; then
    echo "  Status: Online"
  else
    echo "  Status: Offline"
    cpm neighbors remove $neighbor --force
  fi
done

Best Practices

Discovery

  • Run discovery periodically to find new neighbors
  • Scan during off-peak hours to minimize network impact
  • Use specific network ranges for targeted discovery
  • Document discovered neighbors and their purposes

Neighbor Management

  • Keep neighbor list current (remove offline neighbors)
  • Test connectivity regularly
  • Monitor neighbor availability
  • Use hostnames when possible for easier management

Synchronization

  • Sync critical repositories to multiple neighbors
  • Schedule regular sync operations
  • Monitor sync success/failure
  • Implement retry logic for failed syncs

Network Configuration

  • Ensure port 9418 (or custom port) is accessible
  • Configure firewall rules for neighbor communication
  • Use consistent ports across all servers
  • Document network topology

Security

  • Neighbor discovery trusts local network
  • Use SSH keys for authenticated sync operations
  • Restrict neighbor port access to trusted networks
  • Regular security audits of neighbor access

See Also