# Network Reference Guide **Document Version:** 1.0 **Last Updated:** 2025-12-10 ## Table of Contents - [Complete Port Matrix](#complete-port-matrix) - [DHCP Option Reference](#dhcp-option-reference) - [DNS Zone File Examples](#dns-zone-file-examples) - [Firewall Rule Templates](#firewall-rule-templates) - [VLAN Tagging Guide](#vlan-tagging-guide) - [Network Troubleshooting Flowcharts](#network-troubleshooting-flowcharts) ## Complete Port Matrix ### Service Port Overview | Service | API Port | Raft/Consensus | Additional | Protocol | Source | Destination | |-----------------|----------|----------------|---------------|----------|----------------|----------------| | **Chainfire** | 2379 | 2380 | 2381 (gossip) | TCP | Cluster nodes | Cluster nodes | | **FlareDB** | 2479 | 2480 | - | TCP | Cluster nodes | Cluster nodes | | **IAM** | 8080 | - | - | TCP | Clients,nodes | Control plane | | **PlasmaVMC** | 9090 | - | - | TCP | Clients,nodes | Control plane | | **PrismNET** | 9091 | - | 4789 (VXLAN) | TCP/UDP | Cluster nodes | Cluster nodes | | **FlashDNS** | 53 | - | 853 (DoT) | TCP/UDP | Clients,nodes | Cluster nodes | | **FiberLB** | 9092 | - | 80,443 (pass) | TCP | Clients | Load balancers | | **LightningStor**| 9093 | 9094 | 3260 (iSCSI) | TCP | Worker nodes | Storage nodes | | **K8sHost** | 10250 | - | 2379,2380 | TCP | Control plane | Worker nodes | ### Detailed Port Breakdown #### Chainfire | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 2379 | Inbound | Client API | 10.0.0.0/8 | Control plane | Yes | | 2380 | Inbound | Raft consensus | Control plane | Control plane | Yes | | 2381 | Inbound | Gossip protocol | Cluster nodes | Cluster nodes | Yes | | 2379 | Outbound | Client API | Control plane | Control plane | Yes | | 2380 | Outbound | Raft replication | Control plane | Control plane | Yes | | 2381 | Outbound | Gossip protocol | Cluster nodes | Cluster nodes | Yes | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 2379 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 2380 -s 10.0.200.0/24 -j ACCEPT iptables -A INPUT -p tcp --dport 2381 -s 10.0.200.0/24 -j ACCEPT # nftables nft add rule inet filter input tcp dport 2379 ip saddr 10.0.0.0/8 accept nft add rule inet filter input tcp dport { 2380, 2381 } ip saddr 10.0.200.0/24 accept ``` #### FlareDB | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 2479 | Inbound | Client API | 10.0.0.0/8 | Control plane | Yes | | 2480 | Inbound | Raft consensus | Control plane | Control plane | Yes | | 2479 | Outbound | Client API | Control plane | Control plane | Yes | | 2480 | Outbound | Raft replication | Control plane | Control plane | Yes | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 2479 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 2480 -s 10.0.200.0/24 -j ACCEPT # nftables nft add rule inet filter input tcp dport 2479 ip saddr 10.0.0.0/8 accept nft add rule inet filter input tcp dport 2480 ip saddr 10.0.200.0/24 accept ``` #### IAM | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 8080 | Inbound | API (HTTP) | 10.0.0.0/8 | Control plane | Yes | | 8443 | Inbound | API (HTTPS) | 10.0.0.0/8 | Control plane | Optional | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 8080 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 8443 -s 10.0.0.0/8 -j ACCEPT # nftables nft add rule inet filter input tcp dport { 8080, 8443 } ip saddr 10.0.0.0/8 accept ``` #### PlasmaVMC | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 9090 | Inbound | API | 10.0.0.0/8 | Control plane | Yes | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 9090 -s 10.0.0.0/8 -j ACCEPT # nftables nft add rule inet filter input tcp dport 9090 ip saddr 10.0.0.0/8 accept ``` #### PrismNET | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 9091 | Inbound | API | 10.0.0.0/8 | Control plane | Yes | | 4789 | Inbound | VXLAN overlay | Cluster nodes | Cluster nodes | Yes | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 9091 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p udp --dport 4789 -s 10.0.200.0/24 -j ACCEPT # nftables nft add rule inet filter input tcp dport 9091 ip saddr 10.0.0.0/8 accept nft add rule inet filter input udp dport 4789 ip saddr 10.0.200.0/24 accept ``` #### FlashDNS | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 53 | Inbound | DNS (UDP) | 10.0.0.0/8 | Cluster nodes | Yes | | 53 | Inbound | DNS (TCP) | 10.0.0.0/8 | Cluster nodes | Yes | | 853 | Inbound | DNS-over-TLS | 10.0.0.0/8 | Cluster nodes | Optional | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p udp --dport 53 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 53 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 853 -s 10.0.0.0/8 -j ACCEPT # nftables nft add rule inet filter input udp dport 53 ip saddr 10.0.0.0/8 accept nft add rule inet filter input tcp dport { 53, 853 } ip saddr 10.0.0.0/8 accept ``` #### FiberLB | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 9092 | Inbound | API | 10.0.0.0/8 | Load balancers | Yes | | 80 | Inbound | HTTP (passthrough)| 0.0.0.0/0 | Load balancers | Optional | | 443 | Inbound | HTTPS (passthrough)| 0.0.0.0/0 | Load balancers | Optional | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 9092 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 80 -j ACCEPT # Allow from anywhere iptables -A INPUT -p tcp --dport 443 -j ACCEPT # nftables nft add rule inet filter input tcp dport 9092 ip saddr 10.0.0.0/8 accept nft add rule inet filter input tcp dport { 80, 443 } accept ``` #### K8sHost | Port | Direction | Purpose | Source Subnet | Destination | Required | |------|-----------|-------------------|------------------|-------------------|----------| | 10250| Inbound | Kubelet API | Control plane | Worker nodes | Yes | | 10256| Inbound | Health check | Control plane | Worker nodes | Optional | | 30000-32767 | Inbound | NodePort services | Clients | Worker nodes | Optional | **Firewall Rules:** ```bash # iptables iptables -A INPUT -p tcp --dport 10250 -s 10.0.200.0/24 -j ACCEPT iptables -A INPUT -p tcp --dport 10256 -s 10.0.200.0/24 -j ACCEPT iptables -A INPUT -p tcp --dport 30000:32767 -s 10.0.0.0/8 -j ACCEPT # nftables nft add rule inet filter input tcp dport { 10250, 10256 } ip saddr 10.0.200.0/24 accept nft add rule inet filter input tcp dport 30000-32767 ip saddr 10.0.0.0/8 accept ``` ### Management and Infrastructure Ports | Service | Port | Protocol | Purpose | Source | Destination | |------------|-------|----------|--------------------------|---------------|-------------| | SSH | 22 | TCP | Remote management | Admin subnet | All nodes | | NTP | 123 | UDP | Time synchronization | All nodes | NTP servers | | DHCP | 67,68 | UDP | IP address assignment | PXE clients | PXE server | | TFTP | 69 | UDP | PXE bootloader download | PXE clients | PXE server | | HTTP | 80 | TCP | PXE boot scripts/images | PXE clients | PXE server | | HTTPS | 443 | TCP | Secure management | Admin clients | All nodes | | Prometheus | 9100 | TCP | Node exporter metrics | Prometheus | All nodes | | IPMI | 623 | UDP | BMC remote management | Admin subnet | BMC network | **Firewall Rules (Management):** ```bash # iptables iptables -A INPUT -p tcp --dport 22 -s 10.0.10.0/24 -j ACCEPT iptables -A INPUT -p udp --dport 123 -j ACCEPT iptables -A INPUT -p tcp --dport 9100 -s 10.0.10.0/24 -j ACCEPT # nftables nft add rule inet filter input tcp dport 22 ip saddr 10.0.10.0/24 accept nft add rule inet filter input udp dport 123 accept nft add rule inet filter input tcp dport 9100 ip saddr 10.0.10.0/24 accept ``` ## DHCP Option Reference ### Standard DHCP Options | Option | Name | Type | Purpose | Example Value | |--------|-----------------------|---------|--------------------------------------|-------------------------| | 1 | Subnet Mask | IP | Network subnet mask | 255.255.255.0 | | 3 | Router | IP | Default gateway | 10.0.100.1 | | 6 | Domain Name Server | IP list | DNS servers | 10.0.100.1, 8.8.8.8 | | 12 | Host Name | String | Client hostname | node01 | | 15 | Domain Name | String | DNS domain suffix | example.com | | 28 | Broadcast Address | IP | Broadcast address | 10.0.100.255 | | 42 | NTP Servers | IP list | Time servers | 10.0.100.1 | | 51 | Lease Time | Int32 | DHCP lease duration (seconds) | 86400 | ### PXE-Specific DHCP Options | Option | Name | Type | Purpose | Example Value | |--------|-----------------------|---------|--------------------------------------|------------------------------------| | 60 | Vendor Class ID | String | Client vendor identification | PXEClient | | 66 | TFTP Server Name | String | TFTP server hostname or IP | 10.0.100.10 | | 67 | Boot File Name | String | Boot file to download | undionly.kpxe | | 77 | User Class | String | Client user class (iPXE detection) | iPXE | | 93 | Client Architecture | Uint16 | Client architecture type | 0x0000 (BIOS), 0x0007 (UEFI x64) | | 94 | Client Network Interface | Bytes | NIC type and version | 0x010201 (UNDI v2.1) | | 97 | UUID/GUID | Bytes | Client system UUID | Machine-specific | ### Option 93 (Client Architecture) Values | Value | Architecture | Boot Method | |--------|---------------------------|------------------| | 0x0000 | x86 BIOS | Legacy PXE | | 0x0001 | NEC PC-98 | Not supported | | 0x0002 | EFI Itanium | EFI PXE | | 0x0006 | x86 UEFI HTTP Boot | HTTP Boot | | 0x0007 | x64 UEFI | UEFI PXE | | 0x0008 | EFI Xscale | Not supported | | 0x0009 | x64 UEFI HTTP Boot | HTTP Boot | | 0x000a | ARM 32-bit UEFI | ARM PXE | | 0x000b | ARM 64-bit UEFI | ARM PXE | ### ISC DHCP Configuration Examples **Basic PXE Configuration:** ```dhcp # /etc/dhcp/dhcpd.conf # Global options option architecture-type code 93 = unsigned integer 16; default-lease-time 600; max-lease-time 7200; authoritative; # Subnet configuration subnet 10.0.100.0 netmask 255.255.255.0 { range 10.0.100.100 10.0.100.200; option routers 10.0.100.1; option domain-name-servers 10.0.100.1, 8.8.8.8; option domain-name "example.com"; option broadcast-address 10.0.100.255; option ntp-servers 10.0.100.1; # PXE boot server next-server 10.0.100.10; # Boot file selection based on architecture if exists user-class and option user-class = "iPXE" { filename "http://10.0.100.10:8080/boot/ipxe/boot.ipxe"; } elsif option architecture-type = 00:00 { filename "undionly.kpxe"; } elsif option architecture-type = 00:07 { filename "ipxe.efi"; } elsif option architecture-type = 00:09 { filename "ipxe.efi"; } else { filename "ipxe.efi"; } } # Static host reservations host node01 { hardware ethernet 52:54:00:12:34:56; fixed-address 10.0.100.50; option host-name "node01"; } ``` **Advanced PXE Configuration with Classes:** ```dhcp # Define client classes class "pxeclients" { match if substring (option vendor-class-identifier, 0, 9) = "PXEClient"; } class "ipxeclients" { match if exists user-class and option user-class = "iPXE"; } # Subnet configuration subnet 10.0.100.0 netmask 255.255.255.0 { # ... (basic options) ... # Different boot files per class class "ipxeclients" { filename "http://10.0.100.10:8080/boot/ipxe/boot.ipxe"; } class "pxeclients" { if option architecture-type = 00:00 { filename "undionly.kpxe"; } elsif option architecture-type = 00:07 { filename "ipxe.efi"; } } } ``` ## DNS Zone File Examples ### Forward Zone (example.com) ```zone ; /var/named/example.com.zone $TTL 86400 @ IN SOA ns1.example.com. admin.example.com. ( 2025121001 ; Serial 3600 ; Refresh (1 hour) 1800 ; Retry (30 minutes) 604800 ; Expire (1 week) 86400 ; Minimum TTL (1 day) ) ; Name servers @ IN NS ns1.example.com. @ IN NS ns2.example.com. ; Name server A records ns1 IN A 10.0.200.10 ns2 IN A 10.0.200.11 ; Control plane nodes node01 IN A 10.0.200.10 node02 IN A 10.0.200.11 node03 IN A 10.0.200.12 ; Worker nodes worker01 IN A 10.0.200.20 worker02 IN A 10.0.200.21 worker03 IN A 10.0.200.22 ; Service VIPs (virtual IPs for load balancing) chainfire IN A 10.0.200.100 flaredb IN A 10.0.200.101 iam IN A 10.0.200.102 plasmavmc IN A 10.0.200.103 ; Service CNAMEs (point to VIP or specific node) api IN CNAME iam.example.com. db IN CNAME flaredb.example.com. vm IN CNAME plasmavmc.example.com. ; Wildcard for ingress (optional) *.apps IN A 10.0.200.105 ``` ### Reverse Zone (10.0.200.0/24) ```zone ; /var/named/200.0.10.in-addr.arpa.zone $TTL 86400 @ IN SOA ns1.example.com. admin.example.com. ( 2025121001 ; Serial 3600 ; Refresh 1800 ; Retry 604800 ; Expire 86400 ; Minimum TTL ) ; Name servers @ IN NS ns1.example.com. @ IN NS ns2.example.com. ; Control plane nodes 10.200.0.10 IN PTR node01.example.com. 11.200.0.10 IN PTR node02.example.com. 12.200.0.10 IN PTR node03.example.com. ; Worker nodes 20.200.0.10 IN PTR worker01.example.com. 21.200.0.10 IN PTR worker02.example.com. 22.200.0.10 IN PTR worker03.example.com. ; Service VIPs 100.200.0.10 IN PTR chainfire.example.com. 101.200.0.10 IN PTR flaredb.example.com. 102.200.0.10 IN PTR iam.example.com. 103.200.0.10 IN PTR plasmavmc.example.com. ``` ### DNS Configuration (BIND9) ```conf // /etc/named.conf options { directory "/var/named"; listen-on port 53 { 10.0.200.10; 127.0.0.1; }; allow-query { 10.0.0.0/8; localhost; }; recursion yes; forwarders { 8.8.8.8; 8.8.4.4; }; }; zone "example.com" IN { type master; file "example.com.zone"; allow-update { none; }; }; zone "200.0.10.in-addr.arpa" IN { type master; file "200.0.10.in-addr.arpa.zone"; allow-update { none; }; }; ``` ## Firewall Rule Templates ### iptables Complete Ruleset ```bash #!/bin/bash # /etc/iptables/rules.v4 # Flush existing rules iptables -F iptables -X iptables -t nat -F iptables -t nat -X iptables -t mangle -F iptables -t mangle -X # Default policies iptables -P INPUT DROP iptables -P FORWARD DROP iptables -P OUTPUT ACCEPT # Allow loopback iptables -A INPUT -i lo -j ACCEPT # Allow established connections iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT # Allow SSH from management network iptables -A INPUT -p tcp --dport 22 -s 10.0.10.0/24 -j ACCEPT # Allow ICMP (ping) iptables -A INPUT -p icmp -j ACCEPT # PlasmaCloud services (cluster subnet only) iptables -A INPUT -p tcp --dport 2379 -s 10.0.200.0/24 -j ACCEPT # Chainfire API iptables -A INPUT -p tcp --dport 2380 -s 10.0.200.0/24 -j ACCEPT # Chainfire Raft iptables -A INPUT -p tcp --dport 2381 -s 10.0.200.0/24 -j ACCEPT # Chainfire Gossip iptables -A INPUT -p tcp --dport 2479 -s 10.0.200.0/24 -j ACCEPT # FlareDB API iptables -A INPUT -p tcp --dport 2480 -s 10.0.200.0/24 -j ACCEPT # FlareDB Raft # Allow IAM from internal network iptables -A INPUT -p tcp --dport 8080 -s 10.0.0.0/8 -j ACCEPT # Allow PlasmaVMC from internal network iptables -A INPUT -p tcp --dport 9090 -s 10.0.0.0/8 -j ACCEPT # Allow FlashDNS iptables -A INPUT -p udp --dport 53 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 53 -s 10.0.0.0/8 -j ACCEPT # Allow PrismNET VXLAN iptables -A INPUT -p udp --dport 4789 -s 10.0.200.0/24 -j ACCEPT # Allow Prometheus metrics from monitoring server iptables -A INPUT -p tcp --dport 9100 -s 10.0.10.5 -j ACCEPT # Log dropped packets (optional, for debugging) iptables -A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables INPUT DROP: " --log-level 7 # Save rules iptables-save > /etc/iptables/rules.v4 ``` ### nftables Complete Ruleset ```nft #!/usr/sbin/nft -f # /etc/nftables.conf flush ruleset table inet filter { chain input { type filter hook input priority 0; policy drop; # Allow loopback iif lo accept # Allow established connections ct state established,related accept # Allow ICMP ip protocol icmp accept ip6 nexthdr icmpv6 accept # Allow SSH from management network tcp dport 22 ip saddr 10.0.10.0/24 accept # PlasmaCloud services (cluster subnet) tcp dport { 2379, 2380, 2381 } ip saddr 10.0.200.0/24 accept # Chainfire tcp dport { 2479, 2480 } ip saddr 10.0.200.0/24 accept # FlareDB # PlasmaCloud services (internal network) tcp dport { 8080, 9090 } ip saddr 10.0.0.0/8 accept # FlashDNS udp dport 53 ip saddr 10.0.0.0/8 accept tcp dport 53 ip saddr 10.0.0.0/8 accept # PrismNET VXLAN udp dport 4789 ip saddr 10.0.200.0/24 accept # Prometheus metrics tcp dport 9100 ip saddr 10.0.10.5 accept # Log dropped packets log prefix "nftables drop: " level debug limit rate 5/minute } chain forward { type filter hook forward priority 0; policy drop; } chain output { type filter hook output priority 0; policy accept; } } ``` ### NixOS Firewall Configuration ```nix # In configuration.nix { config, pkgs, lib, ... }: { networking.firewall = { enable = true; # Allow specific ports allowedTCPPorts = [ 22 ]; # SSH only # Allow ports from specific sources (requires extraCommands) extraCommands = '' # Chainfire iptables -A INPUT -p tcp --dport 2379 -s 10.0.200.0/24 -j ACCEPT iptables -A INPUT -p tcp --dport 2380 -s 10.0.200.0/24 -j ACCEPT iptables -A INPUT -p tcp --dport 2381 -s 10.0.200.0/24 -j ACCEPT # FlareDB iptables -A INPUT -p tcp --dport 2479 -s 10.0.200.0/24 -j ACCEPT iptables -A INPUT -p tcp --dport 2480 -s 10.0.200.0/24 -j ACCEPT # IAM iptables -A INPUT -p tcp --dport 8080 -s 10.0.0.0/8 -j ACCEPT # PlasmaVMC iptables -A INPUT -p tcp --dport 9090 -s 10.0.0.0/8 -j ACCEPT # FlashDNS iptables -A INPUT -p udp --dport 53 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 53 -s 10.0.0.0/8 -j ACCEPT # PrismNET VXLAN iptables -A INPUT -p udp --dport 4789 -s 10.0.200.0/24 -j ACCEPT ''; extraStopCommands = '' # Cleanup on firewall stop iptables -D INPUT -p tcp --dport 2379 -s 10.0.200.0/24 -j ACCEPT || true # ... (other cleanup) ... ''; }; } ``` ## VLAN Tagging Guide ### VLAN Configuration Overview | VLAN ID | Name | Subnet | Purpose | |---------|------------------|------------------|--------------------------------| | 10 | Management | 10.0.10.0/24 | BMC/IPMI, admin access | | 100 | Provisioning | 10.0.100.0/24 | PXE boot, temporary | | 200 | Production | 10.0.200.0/24 | Cluster communication | | 300 | Client | 10.0.300.0/24 | External client access | | 400 | Storage | 10.0.400.0/24 | iSCSI, NFS, block storage | | 4789 | VXLAN Overlay | Dynamic | PrismNET virtual networks | ### Linux VLAN Configuration (ip command) ```bash # Create VLAN interface ip link add link eth0 name eth0.100 type vlan id 100 ip link set dev eth0.100 up # Assign IP address ip addr add 10.0.100.50/24 dev eth0.100 # Add route ip route add 10.0.100.0/24 dev eth0.100 # Make persistent (systemd-networkd) cat > /etc/systemd/network/10-eth0.100.netdev < /etc/systemd/network/20-eth0.100.network < Enter BIOS, enable network boot │ PXE enabled? │ Set boot order: Network → Disk └────────┬───────┘ │ Yes v ┌────────────────┐ │ DHCP server │───No───> Check DHCP server: │ running? │ - systemctl status dhcpd4 └────────┬───────┘ - Verify interface config │ Yes - Check firewall (UDP 67/68) v ┌────────────────┐ │ Server getting │───No───> Monitor DHCP logs: │ IP address? │ - journalctl -u dhcpd4 -f └────────┬───────┘ - tcpdump -i eth0 port 67 │ Yes - Verify server is on same subnet v ┌────────────────┐ │ TFTP download │───No───> Check TFTP server: │ working? │ - systemctl status atftpd └────────┬───────┘ - tftp localhost -c get undionly.kpxe │ Yes - Verify files exist v ┌────────────────┐ │ iPXE loads and │───No───> Check HTTP server: │ downloads boot │ - systemctl status nginx │ script? │ - curl http://10.0.100.10/boot/ipxe/boot.ipxe └────────┬───────┘ │ Yes v ┌────────────────┐ │ Kernel/initrd │───No───> Verify netboot images: │ download and │ - Check file sizes (bzImage ~10MB, initrd ~200MB) │ boot? │ - Verify HTTP accessibility └────────┬───────┘ - Check console for error messages │ Yes v ┌────────────────┐ │ NixOS installer│ │ boots, SSH │ │ accessible │ └────────────────┘ ``` ### Cluster Join Failure Troubleshooting ``` ┌─────────────────────────────┐ │ Node boots but does not │ │ join cluster │ └──────────────┬──────────────┘ │ v ┌────────────────┐ │ Check first- │ │ boot logs: │ │ journalctl -u │ │ chainfire- │ │ cluster-join │ └────────┬───────┘ │ v ┌────────────────┐ │ Service │───No───> Check main service: │ started? │ - systemctl status chainfire.service └────────┬───────┘ - journalctl -u chainfire.service │ Yes - Verify config file exists v ┌────────────────┐ │ cluster-config │───No───> Check configuration: │ .json exists? │ - ls -l /etc/nixos/secrets/cluster-config.json └────────┬───────┘ - jq . /etc/nixos/secrets/cluster-config.json │ Yes v ┌────────────────┐ │ Health check │───No───> Wait or troubleshoot: │ passes? │ - curl -k https://localhost:2379/health └────────┬───────┘ - Check TLS certificates │ Yes - Check port not in use v ┌────────────────┐ │ Bootstrap mode │ │ or join mode? │ └───┬────────┬───┘ │ │ Bootstrap Join │ │ v v ┌──────────┐ ┌──────────┐ │ Peers │ │ Leader │───No───> Check network: │ reachable│ │ reachable│ - ping leader │? │ │? │ - curl -k https://leader:2379/health └────┬─────┘ └────┬─────┘ - Check firewall │ Yes │ Yes v v ┌──────────┐ ┌──────────┐ │ Cluster │ │ Join API │───No───> Manual join: │ forms │ │ succeeds?│ - curl -k -X POST https://leader:2379/admin/member/add │ auto- │ └────┬─────┘ │ matically│ │ Yes └──────────┘ v │ ┌──────────┐ └──────>│ Cluster │ │ healthy │ └──────────┘ ``` ### Network Connectivity Troubleshooting ``` ┌─────────────────────────────┐ │ Nodes cannot communicate │ └──────────────┬──────────────┘ │ v ┌────────────────┐ │ Basic IP │───No───> Check network config: │ connectivity? │ - ip addr show │ (ping) │ - ip route show └────────┬───────┘ - Fix interface/routing │ Yes v ┌────────────────┐ │ DNS resolution │───No───> Check DNS: │ working? │ - cat /etc/resolv.conf │ (dig/nslookup) │ - dig @10.0.200.1 node01.example.com └────────┬───────┘ - Add to /etc/hosts as workaround │ Yes v ┌────────────────┐ │ Specific port │───No───> Check firewall: │ reachable? │ - iptables -L -n | grep │ (nc -zv) │ - Add firewall rules └────────┬───────┘ - Restart service │ Yes v ┌────────────────┐ │ TLS handshake │───No───> Check certificates: │ succeeds? │ - openssl s_client -connect host:port │ (openssl) │ - Verify cert paths └────────┬───────┘ - Check cert expiry │ Yes v ┌────────────────┐ │ Application │ │ responds │ └────────────────┘ ``` --- **Document End**