diff options
| author | Craig Jennings <c@cjennings.net> | 2026-01-18 15:17:56 -0600 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-01-18 15:17:56 -0600 |
| commit | cb8455c242be14988cf7eeab9851f85a682910ad (patch) | |
| tree | 9df2cf352a67a675189424f7ce41c7235094e0ec | |
| parent | b19ba4e0fc531b5627384c81e8d8aeae9c681795 (diff) | |
| download | archangel-cb8455c242be14988cf7eeab9851f85a682910ad.tar.gz archangel-cb8455c242be14988cf7eeab9851f85a682910ad.zip | |
Add network diagnostics tools and rescue guide documentation
Packages added:
- mtr: combined ping + traceroute
- iperf3: bandwidth testing
- iftop: live bandwidth monitor by connection
- nethogs: bandwidth monitor by process
- ethtool: NIC configuration and diagnostics
- tcpdump: packet capture
- bind: dig/nslookup DNS tools
- nmap: network scanner
- wireshark-cli: tshark packet analysis
Rescue guide section 7 expanded with scenarios for:
- Network path analysis with mtr
- Bandwidth testing with iperf3
- Live monitoring with iftop and nethogs
- Interface diagnostics with ethtool
- Packet capture with tcpdump
- Network scanning with nmap
- Deep packet analysis with tshark
| -rwxr-xr-x | build.sh | 11 | ||||
| -rw-r--r-- | custom/RESCUE-GUIDE.txt | 351 | ||||
| -rw-r--r-- | docs/session-context.org | 121 |
3 files changed, 405 insertions, 78 deletions
@@ -175,6 +175,17 @@ btrfs-progs f2fs-tools exfatprogs +# Network diagnostics +mtr +iperf3 +iftop +nethogs +ethtool +tcpdump +bind +nmap +wireshark-cli + EOF # Get kernel version for ISO naming diff --git a/custom/RESCUE-GUIDE.txt b/custom/RESCUE-GUIDE.txt index ae9406f..02ac2a6 100644 --- a/custom/RESCUE-GUIDE.txt +++ b/custom/RESCUE-GUIDE.txt @@ -1339,6 +1339,13 @@ QUICK REFERENCE tldr ping # Test connectivity tldr ss # Socket statistics (netstat replacement) tldr curl # Transfer data from URLs + tldr mtr # Combined ping + traceroute + tldr iperf3 # Network bandwidth testing + tldr tcpdump # Packet capture and analysis + tldr nmap # Network scanner + man iftop # Live bandwidth monitor + man nethogs # Per-process bandwidth + man tshark # Wireshark CLI (packet analysis) FIRST: Check basic network connectivity --------------------------------------- @@ -1468,20 +1475,338 @@ With progress and compression: rsync -avzP /local/path/ user@host:/remote/path/ -SCENARIO: Test network speed and latency ----------------------------------------- -Ping with timing: +SCENARIO: Test network path and latency (mtr) +--------------------------------------------- +mtr combines ping and traceroute into one tool. Shows packet loss and +latency at each hop in real-time. + +Interactive mode (updates continuously): + + mtr google.com + +Report mode (runs 10 cycles and exits): + + mtr -r -c 10 google.com + +With IP addresses only (faster, no DNS lookups): + + mtr -n google.com + +Show both hostnames and IPs: + + mtr -b google.com + +Reading mtr output: + - Loss% = packet loss at that hop (>0% = problem) + - Snt = packets sent + - Last/Avg/Best/Wrst = latency in ms + - StDev = latency variation (high = inconsistent) + +Common patterns: + - High loss at one hop, normal after = that router deprioritizes ICMP (OK) + - Loss increasing at each hop = real network problem + - Sudden latency jump = congested link or long physical distance + + +SCENARIO: Test bandwidth between two machines (iperf3) +------------------------------------------------------ +iperf3 measures actual throughput between two endpoints. +Requires iperf3 running on both ends. + +On the server (machine to test TO): + + iperf3 -s # Listen on default port 5201 + +On the client (machine to test FROM): + + iperf3 -c server-ip # Basic test (10 seconds) + iperf3 -c server-ip -t 30 # Test for 30 seconds + iperf3 -c server-ip -R # Reverse (test download instead of upload) + +Test both directions: + + iperf3 -c server-ip # Upload speed + iperf3 -c server-ip -R # Download speed + +With parallel streams (better for high-latency links): + + iperf3 -c server-ip -P 4 # 4 parallel streams + +Test UDP (for VoIP/streaming quality): + + iperf3 -c server-ip -u -b 100M # UDP at 100 Mbps + +Interpreting results: + - Bitrate = actual throughput achieved + - Retr = TCP retransmissions (high = packet loss) + - Cwnd = TCP congestion window + + +SCENARIO: Monitor live bandwidth usage (iftop) +---------------------------------------------- +iftop shows bandwidth usage per connection in real-time. +Like top, but for network traffic. + +Monitor all interfaces: + + iftop + +Monitor specific interface: + + iftop -i eth0 + iftop -i wlan0 + +Without DNS lookups (faster): + + iftop -n + +Show port numbers: + + iftop -P + +Filter to specific host: + + iftop -f "host 192.168.1.100" + +Interactive commands while running: + h = help + n = toggle DNS resolution + s = toggle source display + d = toggle destination display + p = toggle port display + P = pause display + q = quit + + +SCENARIO: Find which process is using bandwidth (nethogs) +--------------------------------------------------------- +nethogs shows bandwidth usage per process, not per connection. +Essential for finding what's eating your bandwidth. + +Monitor all interfaces: + + nethogs + +Monitor specific interface: + + nethogs eth0 + +Refresh faster (every 0.5 seconds): + + nethogs -d 0.5 + +Interactive commands: + m = cycle through display modes (KB/s, KB, B, MB) + r = sort by received + s = sort by sent + q = quit + + +SCENARIO: Check network interface details (ethtool) +--------------------------------------------------- +ethtool shows and configures network interface settings. + +Show interface status: + + ethtool eth0 + +Key information: + - Speed: 1000Mb/s (link speed) + - Duplex: Full (full or half duplex) + - Link detected: yes (cable connected) + +Show driver information: + + ethtool -i eth0 + +Show interface statistics: + + ethtool -S eth0 + +Check for errors (look for non-zero values): + + ethtool -S eth0 | grep -i error + ethtool -S eth0 | grep -i drop + +Wake-on-LAN settings: + + ethtool eth0 | grep Wake-on + +Enable Wake-on-LAN: + + ethtool -s eth0 wol g + + +SCENARIO: Capture and analyze packets (tcpdump) +----------------------------------------------- +tcpdump captures network traffic for analysis. +Essential for debugging network issues at the packet level. + +Capture all traffic on an interface: + + tcpdump -i eth0 + +Capture with more detail: + + tcpdump -i eth0 -v # Verbose + tcpdump -i eth0 -vv # More verbose + tcpdump -i eth0 -X # Show packet contents in hex + ASCII + +Capture to a file (for later analysis): + + tcpdump -i eth0 -w capture.pcap + +Read a capture file: + + tcpdump -r capture.pcap + +Common filters: + + tcpdump -i eth0 host 192.168.1.100 # Traffic to/from host + tcpdump -i eth0 port 80 # HTTP traffic + tcpdump -i eth0 port 443 # HTTPS traffic + tcpdump -i eth0 tcp # TCP only + tcpdump -i eth0 udp # UDP only + tcpdump -i eth0 icmp # Ping traffic + tcpdump -i eth0 'port 22 and host 10.0.0.1' # SSH to specific host + +Capture only N packets: + + tcpdump -i eth0 -c 100 # Stop after 100 packets + +Show only packet summaries (no payload): + + tcpdump -i eth0 -q + +Useful for debugging: + + # See DNS queries + tcpdump -i eth0 port 53 + + # See all SYN packets (connection attempts) + tcpdump -i eth0 'tcp[tcpflags] & tcp-syn != 0' + + # See HTTP requests + tcpdump -i eth0 -A port 80 | grep -E '^(GET|POST|HEAD)' + + +SCENARIO: Scan network and discover hosts (nmap) +------------------------------------------------ +nmap is a powerful network scanner for discovery and security auditing. + +Discover hosts on local network: + + nmap -sn 192.168.1.0/24 # Ping scan (no port scan) + +Quick scan of common ports: + + nmap 192.168.1.100 # Top 1000 ports + +Scan specific ports: + + nmap -p 22,80,443 192.168.1.100 + nmap -p 1-1000 192.168.1.100 # Port range + nmap -p- 192.168.1.100 # All 65535 ports (slow) + +Service version detection: + + nmap -sV 192.168.1.100 # Detect service versions + +Operating system detection: + + nmap -O 192.168.1.100 # Requires root + +Comprehensive scan: + + nmap -A 192.168.1.100 # OS detection, version, scripts, traceroute + +Fast scan (fewer ports): + + nmap -F 192.168.1.100 # Top 100 ports only + +Scan multiple hosts: + + nmap 192.168.1.1-50 # Range + nmap 192.168.1.1 192.168.1.2 # Specific hosts + nmap -iL hosts.txt # From file + +Output formats: + + nmap -oN scan.txt 192.168.1.100 # Normal output + nmap -oX scan.xml 192.168.1.100 # XML output + nmap -oG scan.grep 192.168.1.100 # Greppable output + +Common use cases: + + # Find all web servers on network + nmap -p 80,443 192.168.1.0/24 + + # Find SSH servers + nmap -p 22 192.168.1.0/24 + + # Find all live hosts quickly + nmap -sn -T4 192.168.1.0/24 + + +SCENARIO: Deep packet analysis (tshark/Wireshark CLI) +----------------------------------------------------- +tshark is the command-line version of Wireshark. More powerful than +tcpdump for protocol analysis. + +Capture on interface: + + tshark -i eth0 + +Capture to file: + + tshark -i eth0 -w capture.pcap + +Read and analyze capture file: + + tshark -r capture.pcap + +Filter during capture: + + tshark -i eth0 -f "port 80" # Capture filter (BPF syntax) + +Filter during display: + + tshark -r capture.pcap -Y "http" # HTTP traffic + tshark -r capture.pcap -Y "dns" # DNS traffic + tshark -r capture.pcap -Y "tcp.port == 443" # HTTPS + tshark -r capture.pcap -Y "ip.addr == 192.168.1.1" # Specific host + +Show specific fields: + + tshark -r capture.pcap -T fields -e ip.src -e ip.dst -e tcp.port + +Protocol statistics: + + tshark -r capture.pcap -q -z io,stat,1 # I/O statistics + tshark -r capture.pcap -q -z conv,tcp # TCP conversations + tshark -r capture.pcap -q -z http,tree # HTTP statistics + +Follow a TCP stream: + + tshark -r capture.pcap -q -z follow,tcp,ascii,0 # First TCP stream + +Extract HTTP objects: + + tshark -r capture.pcap --export-objects http,./extracted/ - ping -c 10 hostname # 10 pings with statistics +Useful filters: -Traceroute (find network path): + # Failed TCP connections + tshark -r capture.pcap -Y "tcp.flags.reset == 1" - traceroute hostname - traceroute -I hostname # Use ICMP (may work better) + # DNS queries only + tshark -r capture.pcap -Y "dns.flags.response == 0" -Test bandwidth (if iperf3 server available): + # HTTP requests + tshark -r capture.pcap -Y "http.request" - iperf3 -c server-ip # Test to iperf3 server + # TLS handshakes + tshark -r capture.pcap -Y "tls.handshake" SCENARIO: Debug DNS issues @@ -1553,6 +1878,14 @@ NETWORK TROUBLESHOOTING TIPS 6. rsync -avzP is better than scp for large transfers (resumable) 7. Check firewall if services aren't reachable: iptables -L 8. For WiFi issues, check rfkill: rfkill list +9. mtr is better than traceroute - shows packet loss at each hop +10. Use iperf3 to test actual throughput, not just connectivity +11. nethogs shows bandwidth by process; iftop shows by connection +12. tcpdump -w saves packets; analyze later with tshark +13. nmap -sn for quick host discovery without port scanning +14. ethtool shows link speed and cable status (Link detected: yes/no) +15. High latency + low packet loss = congestion; high loss = hardware issue +16. tcpdump and tshark capture files (.pcap) are interchangeable ================================================================================ 8. ENCRYPTION & GPG diff --git a/docs/session-context.org b/docs/session-context.org index c6a2a4a..a9ae82e 100644 --- a/docs/session-context.org +++ b/docs/session-context.org @@ -3,72 +3,55 @@ * Current Session State -** What We're Working On -All 3 unattended installation tests completed successfully. - -** Bugs Found and Fixed This Session - -*** Bug 1: gather_input returns non-zero exit code -- Cause: `[[ -n "$WIFI_SSID" ]] && info "..."` returns 1 when WIFI_SSID is empty -- The bare `return` inherits this exit code -- With `set -e`, script exits immediately -- Fix: Changed `return` to `return 0` -- Commit: 2f5bb37 - -*** Bug 2: pacstrap hangs on provider prompts -- Cause: pacstrap prompts for package provider selection (iptables, initramfs) -- In unattended mode, no input is available -- Fix: Pipe `yes ""` to pacstrap to auto-select defaults -- Commit: 1dc4e95 - -*** Bug 3: fsck hook in mkinitcpio -- Cause: fsck hook was included in HOOKS for ZFS root -- ZFS doesn't use fsck, causes error messages -- Fix: Removed fsck from HOOKS line -- Commit: 1dc4e95 - -*** Bug 4: Missing hostid for ZFS boot -- Cause: ZFS uses hostid to identify pool ownership -- Without hostid, pool import can fail -- Fix: Generate/copy hostid and add spl.spl_hostid to kernel cmdline -- Commit: 1dc4e95 - -** Testing Status -- Test 1: 2-disk mirror - PASSED (installation complete, boots to passphrase prompt) -- Test 2: 2-disk stripe - PASSED (installation complete) -- Test 3: Single disk - PASSED (installation complete) - -** Key Progress This Session - -*** Config File Support for Unattended Installs -- Added --config-file /path/to/config argument -- Config only used when explicitly specified (prevents accidental disk wipes) -- Example config at /root/install-archzfs.conf.example on ISO -- Validates required fields: HOSTNAME, TIMEZONE, DISKS, ZFS_PASSPHRASE, ROOT_PASSWORD - -*** Boot Fixes for ZFS -- Removed fsck from mkinitcpio HOOKS -- Added hostid generation/copy to installed system -- Added spl.spl_hostid to kernel command line -- Removed 'quiet' from kernel params for visible boot messages - -** Files Modified This Session -- custom/install-archzfs - Config file support, bug fixes -- custom/install-archzfs.conf.example - Template for unattended installs -- build.sh - Copies example config to ISO -- .gitignore - Ignore VM disk images - -** Recent Commits -- 2f5bb37: Fix unattended mode exit issue (return 0) -- 1dc4e95: Add config file support for unattended installations - -** Test Configuration -- VM: ./scripts/test-vm.sh --multi-disk (for RAID testing) -- VM: ./scripts/test-vm.sh (for single disk) -- SSH: sshpass -p archzfs ssh -p 2222 root@localhost (live ISO) -- Config file: /root/test-mirror.conf - -** Test Credentials -- Live ISO root password: archzfs -- Test ZFS passphrase: testpass123 -- Test root password: testpass123 +** What We Completed This Session + +Rescue guide and recovery tools work - sections 6, 7, and 8 completed. + +*** Packages Added to build.sh +- partimage (legacy partition imaging) +- f2fs-tools (Flash-Friendly FS) +- exfatprogs (exFAT filesystem) +- emacs (editor) + +*** RESCUE-GUIDE.txt Sections Completed +All 8 sections now complete: +1. ZFS Recovery - done previously +2. Data Recovery - done previously +3. Boot Repair - done previously +4. Windows Recovery - done previously +5. Hardware Diagnostics - done previously +6. Disk Operations - completed this session + - partclone, fsarchiver, partimage + - nwipe secure wiping + - XFS, Btrfs, F2FS, exFAT filesystem tools + - Partitioning with parted/gdisk +7. Network Troubleshooting - completed this session + - Basic connectivity debugging + - NetworkManager and manual config + - SSHFS for remote file access + - SCP/rsync file transfers + - DNS debugging +8. Encryption & GPG - completed this session + - GPG symmetric/asymmetric decryption + - Key import/export + - File signing/verification + - LUKS partition encryption + - eCryptfs home directory recovery + +** Commits Made +- 6df73f6: Add disk, network, and encryption tools with rescue guide sections + +** Git Status +- All changes committed and pushed +- Working tree clean +- Up to date with origin/main + +** Project State +- RESCUE-GUIDE.txt is now complete (all 8 sections written) +- ISO needs rebuild to include new packages +- Ready for testing + +** Next Steps +- Rebuild ISO with new packages +- Test that all rescue tools are present on ISO +- Consider any additional scenarios for rescue guide |
