feat: Add Mycelium IPv6 overlay networking

- Integrate Mycelium IPv6 overlay networking - Add Mycelium configuration options to HeroPods - Enable Mycelium setup and cleanup for containers - Include Mycelium examples and documentation
2025-11-19 14:23:06 +02:00
parent 9986dca758
commit 1452d65f48
11 changed files with 1280 additions and 59 deletions
--- a/examples/virt/heropods/README.md
+++ b/examples/virt/heropods/README.md
@@ -0,0 +1,169 @@
+# HeroPods Examples
+
+This directory contains example HeroScript files demonstrating different HeroPods use cases.
+
+## Prerequisites
+
+- **Linux system** (HeroPods requires Linux-specific tools: ip, iptables, nsenter, crun)
+- **Root/sudo access** (required for network configuration and container management)
+- **Podman** (optional but recommended for image management)
+- **Hero CLI** installed and configured
+
+## Example Scripts
+
+### 1. simple_container.heroscript
+
+**Purpose**: Demonstrate basic container lifecycle management
+
+**What it does**:
+
+- Creates a HeroPods instance
+- Creates an Alpine Linux container
+- Starts the container
+- Executes basic commands inside the container (uname, ls, cat, ps, env)
+- Stops the container
+- Deletes the container
+
+**Run it**:
+
+```bash
+hero run examples/virt/heropods/simple_container.heroscript
+```
+
+**Use this when**: You want to learn the basic container operations without networking complexity.
+
+---
+
+### 2. ipv4_connection.heroscript
+
+**Purpose**: Demonstrate IPv4 networking and internet connectivity
+
+**What it does**:
+
+- Creates a HeroPods instance with bridge networking
+- Creates an Alpine Linux container
+- Starts the container with IPv4 networking
+- Verifies network configuration (interfaces, routes, DNS)
+- Tests DNS resolution
+- Tests HTTP/HTTPS connectivity to the internet
+- Stops and deletes the container
+
+**Run it**:
+
+```bash
+hero run examples/virt/heropods/ipv4_connection.heroscript
+```
+
+**Use this when**: You want to verify that IPv4 bridge networking and internet access work correctly.
+
+---
+
+### 3. container_mycelium.heroscript
+
+**Purpose**: Demonstrate Mycelium IPv6 overlay networking
+
+**What it does**:
+
+- Creates a HeroPods instance
+- Enables Mycelium IPv6 overlay network with all required configuration
+- Creates an Alpine Linux container
+- Starts the container with both IPv4 and IPv6 (Mycelium) networking
+- Verifies IPv6 configuration
+- Tests Mycelium IPv6 connectivity to public nodes
+- Verifies dual-stack networking (IPv4 + IPv6)
+- Stops and deletes the container
+
+**Run it**:
+
+```bash
+hero run examples/virt/heropods/container_mycelium.heroscript
+```
+
+**Use this when**: You want to test Mycelium IPv6 overlay networking for encrypted peer-to-peer connectivity.
+
+**Note**: Requires Mycelium to be installed and configured on the host system.
+
+---
+
+### 4. demo.heroscript
+
+**Purpose**: Quick demonstration of HeroPods with both IPv4 and IPv6 networking
+
+**What it does**:
+
+- Combines IPv4 and Mycelium IPv6 networking in a single demo
+- Shows a complete workflow from configuration to cleanup
+- Serves as a quick reference for common operations
+
+**Run it**:
+
+```bash
+hero run examples/virt/heropods/demo.heroscript
+```
+
+**Use this when**: You want a quick overview of HeroPods capabilities.
+
+---
+
+## Common Issues
+
+### Permission Denied for ping/ping6
+
+Alpine Linux containers don't have `CAP_NET_RAW` capability by default, which is required for ICMP packets (ping).
+
+**Solution**: Use `wget`, `curl`, or `nc` for connectivity testing instead of ping.
+
+### Mycelium Not Found
+
+If you get errors about Mycelium not being installed:
+
+**Solution**: The HeroPods Mycelium integration will automatically install Mycelium when you run `heropods.enable_mycelium`. Make sure you have internet connectivity and the required permissions.
+
+### Container Already Exists
+
+If you get errors about containers already existing:
+
+**Solution**: Either delete the existing container manually or set `reset:true` in the `heropods.configure` action.
+
+---
+
+## Learning Path
+
+We recommend running the examples in this order:
+
+1. **simple_container.heroscript** - Learn basic container operations
+2. **ipv4_connection.heroscript** - Understand IPv4 networking
+3. **container_mycelium.heroscript** - Explore IPv6 overlay networking
+4. **demo.heroscript** - See everything together
+
+---
+
+## Customization
+
+Feel free to modify these scripts to:
+
+- Use different container images (Ubuntu, custom images, etc.)
+- Test different network configurations
+- Add your own commands and tests
+- Experiment with multiple containers
+
+---
+
+## Documentation
+
+For more information, see:
+
+- [HeroPods Main README](../../../lib/virt/heropods/readme.md)
+- [Mycelium Integration Guide](../../../lib/virt/heropods/MYCELIUM_README.md)
+- [Production Readiness Review](../../../lib/virt/heropods/PRODUCTION_READINESS_REVIEW.md)
+
+---
+
+## Support
+
+If you encounter issues:
+
+1. Check the logs in `~/.containers/logs/`
+2. Verify your system meets the prerequisites
+3. Review the error messages carefully
+4. Consult the documentation linked above
--- a/examples/virt/heropods/container_mycelium.heroscript
+++ b/examples/virt/heropods/container_mycelium.heroscript
@@ -0,0 +1,125 @@
+#!/usr/bin/env hero
+
+// ============================================================================
+// HeroPods Example: Mycelium IPv6 Overlay Networking
+// ============================================================================
+//
+// This script demonstrates Mycelium IPv6 overlay networking:
+// - End-to-end encrypted IPv6 connectivity
+// - Peer-to-peer routing through public relay nodes
+// - Container IPv6 address assignment from host's /64 prefix
+// - Connectivity to other Mycelium nodes across the internet
+//
+// Mycelium provides each container with an IPv6 address in the 400::/7 range
+// and enables encrypted communication with other Mycelium nodes.
+// ============================================================================
+
+// Step 1: Configure HeroPods instance
+// This creates a HeroPods instance with default IPv4 networking
+!!heropods.configure
+    name:'mycelium_demo'
+    reset:false
+    use_podman:true
+
+// Step 2: Enable Mycelium IPv6 overlay network
+// All parameters are required for Mycelium configuration
+!!heropods.enable_mycelium
+    heropods:'mycelium_demo'
+    version:'v0.5.6'
+    ipv6_range:'400::/7'
+    key_path:'~/hero/cfg/priv_key.bin'
+    peers:[
+        'tcp://185.69.166.8:9651',
+        'quic://[2a02:1802:5e:0:ec4:7aff:fe51:e36b]:9651',
+        'tcp://65.109.18.113:9651',
+        'quic://[2a01:4f9:5a:1042::2]:9651',
+        'tcp://5.78.122.16:9651',
+        'quic://[2a01:4ff:1f0:8859::1]:9651',
+        'tcp://5.223.43.251:9651',
+        'quic://[2a01:4ff:2f0:3621::1]:9651',
+        'tcp://142.93.217.194:9651',
+        'quic://[2400:6180:100:d0::841:2001]:9651'
+    ]
+
+// Step 3: Create a new Alpine Linux container
+// Alpine includes basic IPv6 networking tools
+!!heropods.container_new
+    name:'mycelium_container'
+    image:'custom'
+    custom_image_name:'alpine_3_20'
+    docker_url:'docker.io/library/alpine:3.20'
+
+// Step 4: Start the container
+// This sets up both IPv4 and IPv6 (Mycelium) networking
+!!heropods.container_start
+    name:'mycelium_container'
+
+// Step 5: Verify IPv6 network configuration
+
+// Show all network interfaces (including IPv6 addresses)
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'ip addr show'
+    stdout:true
+
+// Show IPv6 addresses specifically
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'ip -6 addr show'
+    stdout:true
+
+// Show IPv6 routing table
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'ip -6 route show'
+    stdout:true
+
+// Step 6: Test Mycelium IPv6 connectivity
+// Ping a known public Mycelium node to verify connectivity
+// Note: This requires the container to have CAP_NET_RAW capability for ping6
+// If ping6 fails with permission denied, this is expected behavior in Alpine
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'ping6 -c 3 400:8f3a:8d0e:3503:db8e:6a02:2e9:83dd'
+    stdout:true
+
+// Alternative: Test IPv6 connectivity using nc (netcat) if available
+// This doesn't require special capabilities
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'nc -6 -zv -w 3 400:8f3a:8d0e:3503:db8e:6a02:2e9:83dd 80 2>&1 || echo "nc test completed"'
+    stdout:true
+
+// Step 7: Show Mycelium-specific information
+
+// Display the container's Mycelium IPv6 address
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'ip -6 addr show | grep "400:" || echo "No Mycelium IPv6 address found"'
+    stdout:true
+
+// Show IPv6 neighbors (if any)
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'ip -6 neigh show'
+    stdout:true
+
+// Step 8: Verify dual-stack networking (IPv4 + IPv6)
+// The container should have both IPv4 and IPv6 connectivity
+
+// Test IPv4 connectivity
+!!heropods.container_exec
+    name:'mycelium_container'
+    cmd:'wget -O- http://google.com --timeout=5 2>&1 | head -n 5'
+    stdout:true
+
+// Step 9: Stop the container
+// This cleans up both IPv4 and IPv6 (Mycelium) networking
+!!heropods.container_stop
+    name:'mycelium_container'
+
+// Step 10: Delete the container
+// This removes the container and all associated resources
+!!heropods.container_delete
+    name:'mycelium_container'
+
--- a/examples/virt/heropods/demo.heroscript
+++ b/examples/virt/heropods/demo.heroscript
@@ -1,32 +0,0 @@
-#!/usr/bin/env hero
-
-// Configure the heropods instance
-!!heropods.configure
-    name:'demo'
-    reset:false
-    use_podman:true
-
-// Create a new Alpine container using podman to pull the image
-// Note: Hero binary is ALWAYS automatically included in all containers
-!!heropods.container_new
-    name:'demo_container'
-    image:'custom'
-    custom_image_name:'alpine_3_20'
-    docker_url:'docker.io/library/alpine:3.20'
-
-// Start the container
-!!heropods.container_start
-    name:'demo_container'
-
-// Test network connectivity with wget (ping requires capabilities in Alpine)
-!!heropods.container_exec
-    name:'demo_container'
-    cmd:'wget -O- http://google.com --timeout=5 2>&1 | head -n 5'
-    stdout:true
-
-// Clean up
-!!heropods.container_stop
-    name:'demo_container'
-
-!!heropods.container_delete
-    name:'demo_container'
--- a/examples/virt/heropods/ipv4_connection.heroscript
+++ b/examples/virt/heropods/ipv4_connection.heroscript
@@ -0,0 +1,96 @@
+#!/usr/bin/env hero
+
+// ============================================================================
+// HeroPods Example: IPv4 Networking and Internet Connectivity
+// ============================================================================
+//
+// This script demonstrates IPv4 networking functionality:
+// - Bridge networking with automatic IP allocation
+// - NAT for outbound internet access
+// - DNS resolution
+// - HTTP connectivity testing
+//
+// The container gets an IP address from the bridge subnet (default: 10.10.0.0/24)
+// and can access the internet through NAT.
+// ============================================================================
+
+// Step 1: Configure HeroPods instance with IPv4 networking
+// This creates a HeroPods instance with bridge networking enabled
+!!heropods.configure
+    name:'ipv4_demo'
+    reset:false
+    use_podman:true
+    bridge_name:'heropods0'
+    subnet:'10.10.0.0/24'
+    gateway_ip:'10.10.0.1'
+    dns_servers:['8.8.8.8', '8.8.4.4']
+
+// Step 2: Create a new Alpine Linux container
+// Alpine is lightweight and includes basic networking tools
+!!heropods.container_new
+    name:'ipv4_container'
+    image:'custom'
+    custom_image_name:'alpine_3_20'
+    docker_url:'docker.io/library/alpine:3.20'
+
+// Step 3: Start the container
+// This sets up the veth pair and configures IPv4 networking
+!!heropods.container_start
+    name:'ipv4_container'
+
+// Step 4: Verify network configuration inside the container
+
+// Show network interfaces and IP addresses
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'ip addr show'
+    stdout:true
+
+// Show routing table
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'ip route show'
+    stdout:true
+
+// Show DNS configuration
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'cat /etc/resolv.conf'
+    stdout:true
+
+// Step 5: Test DNS resolution
+// Verify that DNS queries work correctly
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'nslookup google.com'
+    stdout:true
+
+// Step 6: Test HTTP connectivity
+// Use wget to verify internet access (ping requires CAP_NET_RAW capability)
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'wget -O- http://google.com --timeout=5 2>&1 | head -n 10'
+    stdout:true
+
+// Test another website to confirm connectivity
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'wget -O- http://example.com --timeout=5 2>&1 | head -n 10'
+    stdout:true
+
+// Step 7: Test HTTPS connectivity (if wget supports it)
+!!heropods.container_exec
+    name:'ipv4_container'
+    cmd:'wget -O- https://www.google.com --timeout=5 --no-check-certificate 2>&1 | head -n 10'
+    stdout:true
+
+// Step 8: Stop the container
+// This removes the veth pair and cleans up network configuration
+!!heropods.container_stop
+    name:'ipv4_container'
+
+// Step 9: Delete the container
+// This removes the container and all associated resources
+!!heropods.container_delete
+    name:'ipv4_container'
+
--- a/examples/virt/heropods/simple_container.heroscript
+++ b/examples/virt/heropods/simple_container.heroscript
@@ -0,0 +1,79 @@
+#!/usr/bin/env hero
+
+// ============================================================================
+// HeroPods Example: Simple Container Lifecycle Management
+// ============================================================================
+//
+// This script demonstrates the basic container lifecycle operations:
+// - Creating a container
+// - Starting a container
+// - Executing commands inside the container
+// - Stopping a container
+// - Deleting a container
+//
+// No networking tests - just basic container operations.
+// ============================================================================
+
+// Step 1: Configure HeroPods instance
+// This creates a HeroPods instance named 'simple_demo' with default settings
+!!heropods.configure
+    name:'simple_demo'
+    reset:false
+    use_podman:true
+
+// Step 2: Create a new Alpine Linux container
+// This pulls the Alpine 3.20 image from Docker Hub and prepares it for use
+!!heropods.container_new
+    name:'simple_container'
+    image:'custom'
+    custom_image_name:'alpine_3_20'
+    docker_url:'docker.io/library/alpine:3.20'
+
+// Step 3: Start the container
+// This starts the container using crun (OCI runtime)
+!!heropods.container_start
+    name:'simple_container'
+
+// Step 4: Execute basic commands inside the container
+// These commands demonstrate that the container is running and functional
+
+// Show kernel information
+!!heropods.container_exec
+    name:'simple_container'
+    cmd:'uname -a'
+    stdout:true
+
+// List root directory contents
+!!heropods.container_exec
+    name:'simple_container'
+    cmd:'ls -la /'
+    stdout:true
+
+// Show OS release information
+!!heropods.container_exec
+    name:'simple_container'
+    cmd:'cat /etc/os-release'
+    stdout:true
+
+// Show current processes
+!!heropods.container_exec
+    name:'simple_container'
+    cmd:'ps aux'
+    stdout:true
+
+// Show environment variables
+!!heropods.container_exec
+    name:'simple_container'
+    cmd:'env'
+    stdout:true
+
+// Step 5: Stop the container
+// This gracefully stops the container (SIGTERM, then SIGKILL if needed)
+!!heropods.container_stop
+    name:'simple_container'
+
+// Step 6: Delete the container
+// This removes the container and cleans up all associated resources
+!!heropods.container_delete
+    name:'simple_container'
+