Mutiauk - TUN Interface for Muti Metroo

Mutiauk is a companion tool that provides transparent Layer 3 traffic interception using a TUN interface, forwarding traffic through Muti Metroo's SOCKS5 proxy.

Linux Only - Root Required

Mutiauk currently runs only on Linux systems. Unlike Muti Metroo agents which run unprivileged, Mutiauk requires root privileges to create and manage the TUN interface.

Overview

While Muti Metroo's SOCKS5 proxy requires applications to be SOCKS-aware, Mutiauk provides transparent proxying by:

Creating a TUN network interface
Intercepting L3 (IP) traffic destined for configured routes
Forwarding TCP and UDP connections through Muti Metroo's SOCKS5 proxy
Returning responses back through the TUN interface

This enables any application to use the mesh network without modification.

Features

Feature	Description
Transparent Proxying	No application changes required
TCP Support	Full TCP connection forwarding
UDP Support	UDP datagram forwarding via SOCKS5 UDP ASSOCIATE
Route-Based	Only intercept traffic for configured destinations
Autoroutes	Automatically fetch routes from Muti Metroo API
Userspace	No kernel modules required (uses TUN)

Download

Download for Linux (amd64)

Download for Linux (arm64)

Quick Start

# Download and install
curl -L -o mutiauk https://github.com/postalsys/Mutiauk/releases/latest/download/mutiauk-linux-amd64
chmod +x mutiauk
sudo mv mutiauk /usr/local/bin/

# Run the interactive setup wizard (recommended)
sudo mutiauk setup

The setup wizard will guide you through configuring:

TUN interface settings (name, MTU, IP address)
SOCKS5 proxy connection
Routes to forward through the proxy
Optional systemd service installation

Root Required

Mutiauk requires root privileges to create and manage the TUN interface.

Manual Configuration

If you prefer manual configuration instead of the wizard:

# Create config directory and file
sudo mkdir -p /etc/mutiauk
sudo tee /etc/mutiauk/config.yaml > /dev/null << 'EOF'
tun:
  name: tun0
  mtu: 1400
  address: 10.200.200.1/24

socks5:
  server: 127.0.0.1:1080

routes:
  - destination: 10.0.0.0/8
    enabled: true
  - destination: 192.168.0.0/16
    enabled: true
EOF

# Start the daemon
sudo mutiauk daemon start

Configuration

Mutiauk uses a YAML configuration file (default: /etc/mutiauk/config.yaml).

Configuration File Structure

daemon:
  pid_file: /var/run/mutiauk.pid
  socket_path: /var/run/mutiauk.sock

tun:
  name: tun0
  mtu: 1400
  address: 10.200.200.1/24
  address6: fd00:200::1/64  # Optional IPv6

socks5:
  server: 127.0.0.1:1080
  username: ""  # Optional auth
  password: ""
  timeout: 30s
  keepalive: 60s

routes:
  - destination: 10.0.0.0/8
    comment: "Internal network"
    enabled: true
  - destination: 192.168.0.0/16
    comment: "Private network"
    enabled: true

nat:
  table_size: 65536
  tcp_timeout: 1h
  udp_timeout: 5m

logging:
  level: info
  format: json

Automatic Routes (Autoroutes)

Mutiauk can automatically fetch CIDR routes from Muti Metroo's API and apply them to the local routing table. This enables dynamic route discovery without manual configuration.

autoroutes:
  enabled: true
  url: "http://localhost:8080"  # Muti Metroo API URL
  poll_interval: 30s            # How often to fetch routes
  timeout: 10s                  # HTTP request timeout

When enabled, Mutiauk:

Polls the Muti Metroo /api/dashboard endpoint at the configured interval
Extracts CIDR routes advertised by all connected agents
Filters out unsafe routes (default routes, loopback, link-local, multicast)
Applies valid routes to the TUN interface

Filtered Routes (not added automatically):

Route	Reason
`0.0.0.0/0`, `::/0`	Default routes - would capture all traffic
`127.0.0.0/8`, `::1/128`	Loopback - localhost traffic
`169.254.0.0/16`, `fe80::/10`	Link-local - breaks DHCP/ARP
`224.0.0.0/4`, `ff00::/8`	Multicast - not SOCKS-routable
Domain routes	Domain-based routing handled by Muti Metroo

Ephemeral Routes

Autoroutes are ephemeral - they are not saved to the config file and are re-fetched when Mutiauk restarts. Static routes in the routes section always take precedence over autoroutes.

CLI Commands

# Daemon management
mutiauk daemon start      # Start the daemon
mutiauk daemon stop       # Stop the daemon
mutiauk daemon reload     # Reload configuration (SIGHUP)
mutiauk daemon status     # Check if daemon is running

# Route management
mutiauk route list        # List active routes
mutiauk route add <cidr>  # Add a route
mutiauk route remove <cidr>  # Remove a route
mutiauk route plan        # Show pending route changes
mutiauk route apply       # Apply routes from config file
mutiauk route check       # Check for route conflicts

# System status
mutiauk status            # Show comprehensive status with connectivity tests
mutiauk status --json     # Output status in JSON format
mutiauk status --skip-tests  # Skip connectivity tests (faster)

# Setup wizard
sudo mutiauk setup        # Interactive configuration wizard

# Service management (Linux systemd)
sudo mutiauk service install -c /etc/mutiauk/config.yaml
sudo mutiauk service uninstall
mutiauk service status

# Other
mutiauk version           # Show version information

Setup Wizard

The setup wizard (mutiauk setup) provides an interactive guided configuration experience. It walks you through each configuration step with sensible defaults and input validation.

Wizard Steps

Configuration File Location
- Default: /etc/mutiauk/config.yaml
- Creates parent directories if needed
- Warns before overwriting existing files
TUN Interface Configuration
- Interface name (default: tun0)
- MTU size (default: 1400)
- IPv4 address in CIDR notation (default: 10.200.200.1/24)
- Optional IPv6 address
SOCKS5 Proxy Configuration
- Server address and port (e.g., 127.0.0.1:1080)
- Optional username/password authentication
Route Configuration
- Option to add common private network routes (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
- Add custom routes with optional comments
Service Installation (Linux only)
- Optionally install as a systemd service
- Automatically starts and enables the service

Example Session

======================================================================
                       Mutiauk Setup Wizard
======================================================================
                   TUN-based SOCKS5 Proxy Agent

This wizard will help you configure Mutiauk.
Press Enter to accept default values shown in [brackets].

----------------------------------------------------------------------
Configuration File
----------------------------------------------------------------------
Where should the configuration file be saved?

Config file path [/etc/mutiauk/config.yaml]:
[OK] Created directory /etc/mutiauk

----------------------------------------------------------------------
TUN Interface
----------------------------------------------------------------------
Configure the virtual network interface.

Interface name [tun0]:
MTU [1400]:
IPv4 address (CIDR) [10.200.200.1/24]:
Configure IPv6 address? [y/N]:

----------------------------------------------------------------------
SOCKS5 Proxy
----------------------------------------------------------------------
Configure the upstream SOCKS5 proxy server.

SOCKS5 server address [127.0.0.1:1080]:
Does the SOCKS5 server require authentication? [y/N]:

----------------------------------------------------------------------
Routes
----------------------------------------------------------------------
Configure which traffic to route through the SOCKS5 proxy.

Use common private network routes? [Y/n]:
[OK] Added standard private network routes

----------------------------------------------------------------------
Configuration Summary
----------------------------------------------------------------------
  Config file:     /etc/mutiauk/config.yaml
  TUN interface:   tun0
  TUN address:     10.200.200.1/24
  MTU:             1400
  SOCKS5 server:   127.0.0.1:1080
  Routes:          3 configured
                   - 10.0.0.0/8 (Private class A)
                   - 172.16.0.0/12 (Private class B)
                   - 192.168.0.0/16 (Private class C)

----------------------------------------------------------------------
Service Installation
----------------------------------------------------------------------
Install Mutiauk as a systemd service? [Y/n]:
[OK] Service installed and started!

Global CLI Options

Option	Default	Description
`-c, --config`	`/etc/mutiauk/config.yaml`	Path to configuration file
`-v, --verbose`	`false`	Enable verbose logging

Use Cases

Transparent Corporate Access

Route traffic to corporate networks without configuring each application:

# /etc/mutiauk/config.yaml
tun:
  name: tun0
  address: 10.200.200.1/24

socks5:
  server: 127.0.0.1:1080

routes:
  - destination: 10.0.0.0/8
    comment: "Corporate network"
    enabled: true

sudo mutiauk daemon start

Development Environment

Test applications against remote environments transparently:

# /etc/mutiauk/config.yaml
routes:
  - destination: 192.168.100.0/24
    comment: "Staging environment"
    enabled: true

Container/VM Traffic

Route traffic from containers or VMs through the mesh by configuring their default gateway to the TUN interface.

Network Scanning with Nmap

Use Mutiauk to route nmap scans through the SOCKS5 proxy for transparent network reconnaissance:

# /etc/mutiauk/config.yaml
tun:
  name: tun0
  address: 10.200.200.1/24

socks5:
  server: 127.0.0.1:1080

routes:
  - destination: 192.168.50.0/24
    comment: "Target network"
    enabled: true

# Start Mutiauk
sudo mutiauk daemon start

# TCP Connect scan (works transparently through SOCKS5)
nmap -sT -Pn --top-ports 100 192.168.50.1

# UDP scan (uses SOCKS5 UDP ASSOCIATE)
nmap -sU -Pn --top-ports 20 192.168.50.1

# Service version detection
nmap -sT -sV -Pn 192.168.50.1

Nmap Options for Mutiauk

Use -sT (TCP Connect scan) instead of -sS (SYN scan) since raw sockets bypass the TUN interface
Use -Pn to skip host discovery (ICMP is not forwarded)
UDP scans work but show open|filtered since ICMP unreachable messages cannot be received through the proxy

Architecture

Mutiauk operates as a userspace network stack:

TUN Interface: Receives raw IP packets from the kernel
L3 Processing: Parses IP headers to determine protocol and destination
L4 Proxy:
- TCP: Establishes SOCKS5 CONNECT for each connection
- UDP: Uses SOCKS5 UDP ASSOCIATE for datagram forwarding
Response Handling: Wraps responses back into IP packets for the TUN interface

Limitations

Linux only: Uses Linux TUN interface (no macOS/Windows support)
IPv4 only: IPv6 support planned for future releases
No ICMP: ICMP traffic (ping) is not forwarded
Requires root: TUN interface creation requires elevated privileges

Troubleshooting

TUN Creation Failed

Error: failed to create TUN interface: operation not permitted

Run with sudo or as root
Check if TUN module is loaded: lsmod | grep tun
Load TUN module: sudo modprobe tun

No Connectivity

Verify Muti Metroo SOCKS5 is running: curl -x socks5://127.0.0.1:1080 https://example.com
Check routes are correctly specified
Verify TUN interface is up: ip addr show mutiauk0

DNS Not Working

Use --dns to specify a DNS server reachable through the mesh
Or configure system DNS to use a server in the routed network

Mutiauk on GitHub - Source code and releases
Muti Metroo Download - Main Muti Metroo binary
SOCKS5 Configuration - Configure SOCKS5 ingress
UDP Relay - UDP support through SOCKS5

Overview​

Features​

Download​

Quick Start​

Manual Configuration​

Configuration​

Configuration File Structure​

Automatic Routes (Autoroutes)​

CLI Commands​

Setup Wizard​

Wizard Steps​

Example Session​

Global CLI Options​

Use Cases​

Transparent Corporate Access​

Development Environment​

Container/VM Traffic​

Network Scanning with Nmap​

Architecture​

Limitations​

Troubleshooting​

TUN Creation Failed​

No Connectivity​

DNS Not Working​

Related​