aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-01-18 15:17:56 -0600
committerCraig Jennings <c@cjennings.net>2026-01-18 15:17:56 -0600
commitcb8455c242be14988cf7eeab9851f85a682910ad (patch)
tree9df2cf352a67a675189424f7ce41c7235094e0ec
parentb19ba4e0fc531b5627384c81e8d8aeae9c681795 (diff)
downloadarchangel-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-xbuild.sh11
-rw-r--r--custom/RESCUE-GUIDE.txt351
-rw-r--r--docs/session-context.org121
3 files changed, 405 insertions, 78 deletions
diff --git a/build.sh b/build.sh
index f034aec..8073423 100755
--- a/build.sh
+++ b/build.sh
@@ -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