4NK_node/docs/CONFIGURATION.md

⚙️ Guide de Configuration - 4NK_node

Guide complet pour configurer l'infrastructure 4NK_node selon vos besoins.

📋 Configuration Générale

1. Variables d'Environnement

Créer un fichier .env à la racine du projet :

# Configuration 4NK_node
PROJECT_NAME=4NK_node
NETWORK_NAME=4nk_node_btcnet

# Logs
RUST_LOG=debug,bitcoincore_rpc=trace

# Bitcoin
BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie

# Synchronisation
ENABLE_SYNC_TEST=1

# Ports
TOR_PORTS=9050:9050,9051:9051
BITCOIN_PORTS=38333:38333,18443:18443,29000:29000
BLINDBIT_PORTS=8000:8000
RELAY_1_PORTS=8090:8090,8091:8091
RELAY_2_PORTS=8092:8090,8093:8091
RELAY_3_PORTS=8094:8090,8095:8091

1.b Santé des services

• sdk_signer expose un endpoint de santé interne HTTP sur le port 9092 (sidecar httpd minimal). Le reverse proxy le publie en /signer/health.
• Les sdk_relay_* utilisent un healthcheck tolérant au démarrage : le processus doit être actif et l’indicateur /home/bitcoin/.4nk/processes présent. Les ports 8090/8091 peuvent n’ouvrir qu’après les phases initiales (scan/resync).

2. Configuration Réseau

Réseau Docker Personnalisé

# Créer un réseau personnalisé
docker network create 4nk-network --subnet=172.20.0.0/16 --gateway=172.20.0.1

# Modifier docker-compose.yml
sed -i 's/4nk_default/4nk-network/g' docker-compose.yml

Configuration de Pare-feu

# Exposition publique centralisée via reverse proxy uniquement
sudo ufw allow 80/tcp     # HTTP (redirection)
sudo ufw allow 443/tcp    # HTTPS (UI + API + WS)
sudo ufw enable
sudo ufw enable

# Vérifier les règles
sudo ufw status numbered

🔧 Configuration Bitcoin Core

1. Configuration de Base

Fichier : bitcoin/bitcoin.conf

# Configuration Bitcoin Core Signet
signet=1
rpcuser=bitcoin
rpcpassword=your_secure_password
rpcbind=0.0.0.0
rpcallowip=172.19.0.0/16
zmqpubrawblock=tcp://0.0.0.0:29000
zmqpubrawtx=tcp://0.0.0.0:29000
txindex=1
server=1
listen=1

# Configuration Signet
[signet]
listen=1
bind=0.0.0.0:38333
rpcbind=0.0.0.0:18443
rpcport=18443
fallbackfee=0.0001
blockfilterindex=1
datacarriersize=205
acceptnonstdtxn=1
dustrelayfee=0.00000001
minrelaytxfee=0.00000001
prune=0
signetchallenge=0020341c43803863c252df326e73574a27d7e19322992061017b0dc893e2eab90821
walletdir=/home/bitcoin/.bitcoin/wallets
wallet=mining
wallet=watchonly
maxtxfee=1
addnode=tlv2yqamflv22vfdzy2hha2nwmt6zrwrhjjzz4lx7qyq7lyc6wfhabyd.onion

2. Configuration Avancée

Performance

# Optimisation mémoire
dbcache=450
maxmempool=300
maxconnections=125

# Optimisation disque
txindex=1
blockfilterindex=1
coinstatsindex=1

# Optimisation réseau
listenonion=1
onion=tor:9050
proxy=tor:9050

Sécurité

# Authentification
rpcauth=bitcoin:c8ea921c7357bd6a5a8a7c43a12350a7$955e25b17672987b17c5a12f12cd8b9c1d38f0f86201c8cd47fc431f2e1c7956
rpcallowip=172.19.0.0/16
rpcworkqueue=32
rpcthreads=4
rpcdoccheck=1

# Limites
maxuploadtarget=5000
maxconnections=125

3. Configuration des Wallets

# Créer un wallet pour les relais
docker exec bitcoin-signet bitcoin-cli -signet createwallet "relay_wallet"

# Créer un wallet pour le mining
docker exec bitcoin-signet bitcoin-cli -signet createwallet "mining_wallet"

# Créer un wallet watch-only
docker exec bitcoin-signet bitcoin-cli -signet createwallet "watchonly_wallet" true

🔧 Configuration Blindbit

1. Configuration de Base

Fichier : blindbit/blindbit.toml

# Configuration Blindbit Oracle
host = "0.0.0.0:8000"
chain = "signet"
rpc_endpoint = "http://bitcoin:18443"
cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie"
rpc_user = ""
rpc_pass = ""
sync_start_height = 1

# Performance
max_parallel_tweak_computations = 4
max_parallel_requests = 4

# Index
tweaks_only = 0
tweaks_full_basic = 1
tweaks_full_with_dust_filter = 1
tweaks_cut_through_with_dust_filter = 1

2. Configuration Avancée

Performance

# Optimisation des calculs
max_parallel_tweak_computations = 8
max_parallel_requests = 8

# Cache
cache_size = 1000
cache_ttl = 3600

# Logs
log_level = "info"
log_file = "/data/blindbit.log"

Sécurité

# Authentification
rpc_user = "blindbit_user"
rpc_pass = "secure_password"

# Limites
max_request_size = 1048576
rate_limit = 100

🔧 Configuration des Relais

1. Configuration de Base

Relay 1 - sdk_relay/.conf.docker.relay1

core_url=http://bitcoin:18443
core_wallet=relay_wallet
ws_url=0.0.0.0:8090
wallet_name=relay_wallet.json
network=signet
blindbit_url=http://blindbit:8000
zmq_url=tcp://bitcoin:29000
data_dir=.4nk
cookie_path=/home/bitcoin/.4nk/bitcoin.cookie
dev_mode=true
standalone=false
relay_id=relay-1

Relay 2 - sdk_relay/.conf.docker.relay2

core_url=http://bitcoin:18443
core_wallet=relay_wallet
ws_url=0.0.0.0:8090
wallet_name=relay_wallet.json
network=signet
blindbit_url=http://blindbit:8000
zmq_url=tcp://bitcoin:29000
data_dir=.4nk
cookie_path=/home/bitcoin/.4nk/bitcoin.cookie
dev_mode=true
standalone=false
relay_id=relay-2

Relay 3 - sdk_relay/.conf.docker.relay3

core_url=http://bitcoin:18443
core_wallet=relay_wallet
ws_url=0.0.0.0:8090
wallet_name=relay_wallet.json
network=signet
blindbit_url=http://blindbit:8000
zmq_url=tcp://bitcoin:29000
data_dir=.4nk
cookie_path=/home/bitcoin/.4nk/bitcoin.cookie
dev_mode=true
standalone=false
relay_id=relay-3

2. Configuration Avancée

Performance

# Optimisation mémoire
max_connections=100
connection_timeout=30
read_timeout=60

# Cache
cache_size=1000
cache_ttl=3600

# Logs
log_level=info
log_file=/home/bitcoin/.4nk/relay.log

Sécurité

# Authentification
auth_required=true
auth_token=your_secure_token

# Limites
max_message_size=1048576
rate_limit=1000

3. Configuration de Synchronisation

# Synchronisation
sync_enabled=true
sync_interval=30
sync_timeout=10

# Découverte
discovery_enabled=true
discovery_interval=60
discovery_timeout=5

# Cache de déduplication
dedup_enabled=true
dedup_ttl=300
dedup_max_size=10000

🌐 Configuration des Nœuds Externes

1. Configuration de Base

Fichier : sdk_relay/external_nodes.conf

# Configuration des nœuds externes
[relays]
external-relay-1 = "external-relay-1.example.com:8090"
external-relay-2 = "192.168.1.100:8090"
dev3-relay = "dev3.4nkweb.com:443"

[discovery]
auto_discover = true
bootstrap_nodes = [
    "bootstrap-1.4nk.net:8090",
    "bootstrap-2.4nk.net:8090"
]

[security]
allowed_domains = [
    "*.4nk.net",
    "*.example.com",
    "localhost",
    "127.0.0.1"
]

[validation]
max_connection_timeout = 10
health_check_interval = 300
blacklist_threshold = 5

2. Configuration Avancée

Découverte Automatique

[discovery]
auto_discover = true
bootstrap_nodes = [
    "bootstrap-1.4nk.net:8090",
    "bootstrap-2.4nk.net:8090"
]
discovery_interval = 300
discovery_timeout = 10
max_discovered_nodes = 50

Sécurité

[security]
allowed_domains = [
    "*.4nk.net",
    "*.example.com",
    "localhost",
    "127.0.0.1"
]
blocked_domains = [
    "malicious.example.com"
]
allowed_ips = [
    "192.168.1.0/24",
    "10.0.0.0/8"
]

Validation

[validation]
max_connection_timeout = 10
health_check_interval = 300
blacklist_threshold = 5
whitelist_enabled = false
certificate_verification = true

🔧 Configuration Tor

1. Image et service Tor

• Le service Tor est désormais construit localement depuis tor/Dockerfile et monté avec tor/torrc.
• Le conteneur tourne en utilisateur debian-tor et expose uniquement le SOCKS (9050) et, en interne, un ControlPort local (127.0.0.1:9051).

Extrait docker-compose.yml (service tor):

services:
  tor:
    build: ./tor
    image: 4nk_node-tor
    container_name: tor-proxy
    ports:
      - "9050:9050"
      - "9051:9051"
    volumes:
      - ./tor/torrc:/etc/tor/torrc:ro
    command: ["tor", "-f", "/etc/tor/torrc"]
    healthcheck:
      test: ["CMD-SHELL", "nc -z 127.0.0.1 9050"]
      interval: 30s
      timeout: 5s
      retries: 3
    networks:
      - btcnet

2. Fichier tor/torrc

Configuration de base (extrait) :

SocksPort 0.0.0.0:9050
ControlPort 127.0.0.1:9051
DataDirectory /var/lib/tor
Log notice stdout
ClientUseIPv6 1
SafeLogging 1
ReducedConnectionPadding 1
SocksPolicy accept 0.0.0.0/0
AutomapHostsOnResolve 1

3. Bridges obfs4 (optionnels)

Pour contourner des filtrages réseaux, activer les bridges obfs4 dans tor/torrc :

UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
Bridge obfs4 81.64.0.218:6697 53E6469DC06BED50543AED0311D66082F4B66676 cert=zOKy+MnZ4wWbKcENcyaElPu62PEaXdE/c802ssuzCIDa2aIC1+J4LyfPhAwSiLaAo/I/bg iat-mode=0
Bridge obfs4 198.98.53.149:443 886CA31F71272FC8B3808C601FA3ABB8A2905DB4 cert=D+zypuFdMpP8riBUbInxIguzqClR0JKkP1DbkKz5es1+OP2Fao8jiXyM+B/+DYA2ZFy6UA iat-mode=0

L’image Tor installe obfs4proxy. Après modification :

sudo docker compose build tor
sudo docker compose up -d tor

Vérifications :

sudo docker compose ps tor
sudo docker logs tor-proxy --tail=40
sudo docker exec tor-proxy nc -z 127.0.0.1 9050 && echo SOCKS:OK

Notes et recommandations (Tor/bridges)

• Le ControlPort 127.0.0.1:9051 est utilisé pour le diagnostic interne. Ne pas l’exposer publiquement. Une authentification peut être activée si un contrôle à distance est requis.
• Les bridges obfs4 ci‑dessus proviennent de la page de référence du Tor Project. En cas d’échec répété (messages « general SOCKS server failure » côté Tor), ajouter 2–3 bridges supplémentaires depuis la même source et redémarrer le service Tor.
• Pour faciliter l’ajout à chaud de bridges, un fichier tor/bridges.extra est monté en lecture seule dans le conteneur et inclus via %include /etc/tor/bridges.extra. Vous pouvez y coller de nouveaux bridges sans modifier tor/torrc, puis redémarrer Tor.
• Les tests de connectivité doivent distinguer :
  • Accès SOCKS vers des services onion « publics » (ex. DuckDuckGo) pour valider le proxy Tor.
  • Accès SOCKS vers l’onion cible du signet pour valider la reachability du pair.
• À la date d’édition, le proxy SOCKS fonctionne (onion publics accessibles), mais le pair signet .onion:38333 est injoignable (host unreachable). La configuration du signet (signetchallenge et addnode) doit rester inchangée, conformément à la contrainte fonctionnelle.

Outils de diagnostic réseau

• Installer netcat-openbsd sur l’hôte et dans les conteneurs pertinents pour faciliter les vérifications :
  • Hôte : sudo apt-get install -y netcat-openbsd
  • Conteneur Bitcoin (root) : apt-get update && apt-get install -y --no-install-recommends netcat-openbsd
• Exemples de vérifications :
  • nc -vz -w 10 -x 127.0.0.1:9050 -X 5 <onion> 80
  • nc -vz -w 10 -x 127.0.0.1:9050 -X 5 <onion_signet> 38333

DNS externes (ex. dev.4nkweb.com)

• Si un nom de domaine (ex. dev.4nkweb.com) doit pointer vers un service, s’assurer qu’un enregistrement DNS A/AAAA existe. En l’absence de résolution, les tests échoueront côté HTTP/HTTPS et TCP.
• En phase de test, une entrée temporaire peut être ajoutée dans /etc/hosts si l’IP est connue.

🔧 Configuration Docker Compose

1. Configuration de Base

Fichier : docker-compose.yml

# Compose modernisé (sans clé version), publication unique via reverse proxy
services:
  reverse_proxy:
    image: nginx:alpine
    depends_on:
      - sdk_relay_1
    volumes:
      - ./proxy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
      - ./ihm_client/dist:/usr/share/nginx/html:ro
    ports:
      - "80:80"
      - "443:443"
    networks:
      btcnet:
        aliases:
          - reverse_proxy

  # Tous les autres services sont internes (pas de ports exposés)
  bitcoin:
    networks:
      - btcnet
  blindbit:
    networks:
      - btcnet
  sdk_relay_1:
    networks:
      - btcnet

2. Configuration Avancée

Ressources

services:
  bitcoin:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'
        reservations:
          memory: 1G
          cpus: '0.5'

  sdk_relay_1:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M
          cpus: '0.25'

Sécurité

services:
  bitcoin:
    security_opt:
      - no-new-privileges:true
    read_only: false
    tmpfs:
      - /tmp:noexec,nosuid,size=100m

  sdk_relay_1:
    security_opt:
      - no-new-privileges:true
    read_only: false
    tmpfs:
      - /tmp:noexec,nosuid,size=50m

🔧 Configuration SSL/TLS

1. Certificat Auto-Signé

# Générer et protéger des certificats auto-signés
./scripts/generate_certs.sh

# Les certificats sont montés par le reverse proxy :
#   - certs/server.crt -> /etc/nginx/certs/server.crt
#   - certs/server.key -> /etc/nginx/certs/server.key

2. Certificat Let's Encrypt

# Installer certbot
sudo apt install certbot python3-certbot-nginx

# Obtenir un certificat
sudo certbot --nginx -d your-domain.com

# Configuration automatique
sudo certbot renew --dry-run

3. Production (webroot, HSTS et renouvellement)

• Le reverse proxy sert les challenges ACME en HTTP: /.well-known/acme-challenge/ via le montage ./acme -> /var/www/certbot.
• Le certificat de production est installé dans ./certs/server.crt et ./certs/server.key.
• HSTS est activé par défaut (entête Strict-Transport-Security: max-age=31536000; includeSubDomains).
• Renouvellement: script idempotent scripts/renew_certs.sh (webroot certbot + reload Nginx).
• Déploiement initial automatisé: scripts/deploy_first_install_with_certs.sh (avec certificats) ou scripts/deploy_first_install_no_certs.sh (auto‑signé).

Exécution manuelle:

./scripts/renew_certs.sh

Cron (quotidien à 03:00):

0 3 * * * /home/debian/4NK_node/scripts/renew_certs.sh >> /home/debian/4NK_node/logs/cert_renew.log 2>&1

🔧 Configuration de Monitoring

1. Prometheus

# docker-compose.yml addition
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'
      - '--storage.tsdb.retention.time=200h'
      - '--web.enable-lifecycle'

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

volumes:
  prometheus_data:
  grafana_data:

2. Configuration Prometheus

Fichier : prometheus.yml

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

scrape_configs:
  - job_name: 'bitcoin'
    static_configs:
      - targets: ['bitcoin:18443']

  - job_name: 'blindbit'
    static_configs:
      - targets: ['blindbit:8000']

  - job_name: 'sdk_relay'
    static_configs:
      - targets: ['sdk_relay_1:8091']

🔧 Configuration de Sauvegarde

1. Script de Sauvegarde

#!/bin/bash
# backup_4nk.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/4nk_node_$DATE"

mkdir -p $BACKUP_DIR

# Sauvegarder les configurations
cp -r sdk_relay/.conf* $BACKUP_DIR/
cp external_nodes.conf $BACKUP_DIR/
cp bitcoin/bitcoin.conf $BACKUP_DIR/
cp blindbit/blindbit.toml $BACKUP_DIR/

# Sauvegarder les données Bitcoin
docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin
docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz $BACKUP_DIR/

# Sauvegarder les données Blindbit
docker exec blindbit-oracle tar czf /tmp/blindbit-backup.tar.gz /data
docker cp blindbit-oracle:/tmp/blindbit-backup.tar.gz $BACKUP_DIR/

# Sauvegarder les données des relais
for i in {1..3}; do
    docker exec sdk_relay_$i tar czf /tmp/relay_$i-backup.tar.gz /home/bitcoin/.4nk
    docker cp sdk_relay_$i:/tmp/relay_$i-backup.tar.gz $BACKUP_DIR/
done

# Nettoyer les anciennes sauvegardes (garder 7 jours)
find /backup -name "4nk_node_*" -type d -mtime +7 -exec rm -rf {} \;

echo "Sauvegarde terminée: $BACKUP_DIR"

2. Configuration Cron

# Ajouter au cron pour sauvegarde automatique
echo "0 2 * * * /path/to/backup_4nk.sh" | crontab -

🔧 Configuration de Logs

1. Rotation des Logs

# Configuration logrotate
cat > /etc/logrotate.d/4nk-node << EOF
/var/lib/docker/containers/*/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
    size 100M
}
EOF

2. Centralisation des Logs

# docker-compose.yml addition
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0
    container_name: elasticsearch
    environment:
      - discovery.type=single-node
    ports:
      - "9200:9200"
    volumes:
      - elasticsearch_data:/usr/share/elasticsearch/data

  kibana:
    image: docker.elastic.co/kibana/kibana:7.17.0
    container_name: kibana
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

  filebeat:
    image: docker.elastic.co/beats/filebeat:7.17.0
    container_name: filebeat
    volumes:
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - ./filebeat.yml:/usr/share/filebeat/filebeat.yml:ro
    depends_on:
      - elasticsearch

volumes:
  elasticsearch_data:

📝 Checklist de Configuration

• Variables d'environnement configurées
• Configuration Bitcoin Core vérifiée
• Configuration Blindbit vérifiée
• Configurations des relais vérifiées
• Configuration des nœuds externes vérifiée
• Configuration Tor vérifiée
• Configuration Docker Compose vérifiée
• SSL/TLS configuré (si nécessaire)
• Monitoring configuré (si nécessaire)
• Sauvegarde configurée
• Logs configurés
• Pare-feu configuré
• Tests de configuration passés

🎯 Commandes de Configuration

# Vérifier la configuration
docker-compose config

# Tester la configuration
./test_final_sync.sh

# Appliquer la configuration
./restart_4nk_node.sh

# Vérifier les logs
docker-compose logs --tail=50

---