System Service Installation

Install once, run forever. The agent starts automatically when the system boots and restarts if it crashes - no manual intervention needed.

What you get:

Automatic start on boot - agent runs without logging in
Crash recovery - system restarts the agent if it dies
Managed lifecycle - start, stop, and check status with standard commands
Security hardening - runs as a dedicated user with limited privileges

Linux (systemd)

Installation

# Install as service (requires root) - auto-starts immediately
sudo muti-metroo service install -c /etc/muti-metroo/config.yaml

This copies the binary to /usr/local/bin/muti-metroo, creates a systemd unit file at /etc/systemd/system/muti-metroo.service, enables boot startup, and starts the service immediately.

Binary Deployment

By default, service install copies the binary to a standard system location (/usr/local/bin on Linux/macOS, C:\Program Files\<name> on Windows). The service definition references the installed copy. Use --deploy=false to skip this and reference the binary at its current path.

Service Management

# Check status
sudo systemctl status muti-metroo

# View logs
sudo journalctl -u muti-metroo -f

# Restart (after config changes)
sudo systemctl restart muti-metroo

# Stop
sudo systemctl stop muti-metroo

No Manual Start Needed

The service install command automatically enables and starts the service. You don't need to run systemctl enable or systemctl start manually.

Uninstall

# Stop and disable
sudo systemctl stop muti-metroo
sudo systemctl disable muti-metroo

# Uninstall service
sudo muti-metroo service uninstall

# Clean up files (optional)
sudo rm -rf /etc/muti-metroo
sudo rm -rf /var/lib/muti-metroo

Systemd Unit File

The installer creates:

# /etc/systemd/system/muti-metroo.service
[Unit]
Description=Userspace mesh networking agent for virtual TCP tunnels
Documentation=https://github.com/postalsys/muti-metroo
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/muti-metroo run -c /etc/muti-metroo/config.yaml
WorkingDirectory=/etc/muti-metroo
Restart=on-failure
RestartSec=5
TimeoutStopSec=30

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=true
ReadWritePaths=/etc/muti-metroo /var/lib/muti-metroo

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=muti-metroo

[Install]
WantedBy=multi-user.target

note

The ReadWritePaths directive includes both the config directory and the data directory specified in your config file. This allows the service to write to the data directory while maintaining strict filesystem protection.

Custom Installation

For manual setup:

# Create user
sudo useradd -r -s /sbin/nologin muti-metroo

# Create directories
sudo mkdir -p /etc/muti-metroo
sudo mkdir -p /var/lib/muti-metroo
sudo chown muti-metroo:muti-metroo /var/lib/muti-metroo

# Copy binary
sudo cp muti-metroo /usr/local/bin/

# Copy config
sudo cp ./config.yaml /etc/muti-metroo/
sudo chown root:muti-metroo /etc/muti-metroo/config.yaml
sudo chmod 640 /etc/muti-metroo/config.yaml

# Copy certificates
sudo cp -r ./certs /etc/muti-metroo/
sudo chown -R root:muti-metroo /etc/muti-metroo/certs
sudo chmod 750 /etc/muti-metroo/certs
sudo chmod 640 /etc/muti-metroo/certs/*

# Create unit file
sudo nano /etc/systemd/system/muti-metroo.service
# (paste unit file content)

# Reload and start
sudo systemctl daemon-reload
sudo systemctl enable --now muti-metroo

Configuration for Service

# /etc/muti-metroo/config.yaml
agent:
  id: "auto"
  display_name: "${HOSTNAME}"
  data_dir: "/var/lib/muti-metroo"
  log_level: "info"
  log_format: "json"

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "/etc/muti-metroo/certs/agent.crt"
      key: "/etc/muti-metroo/certs/agent.key"

socks5:
  enabled: true
  address: "127.0.0.1:1080"

http:
  enabled: true
  address: "127.0.0.1:8080"

Windows Service

Installation

Run as Administrator:

# Install service
muti-metroo.exe service install -c C:\ProgramData\muti-metroo\config.yaml

Non-Admin Alternative

Windows Service installation requires Administrator privileges. If you don't have admin access, use DLL Mode with the Registry Run key instead - it provides similar background execution and starts automatically at user login without requiring elevation.

Service Management

# Start
sc start muti-metroo

# Stop
sc stop muti-metroo

# Status
sc query muti-metroo

# Configure automatic start
sc config muti-metroo start= auto

Or use Services GUI:

Open services.msc
Find "Muti Metroo"
Right-click for Start/Stop/Properties

Uninstall

Run as Administrator:

# Stop service
sc stop muti-metroo

# Uninstall
muti-metroo.exe service uninstall

Windows Paths

C:\ProgramData\muti-metroo\
  config.yaml           # Configuration
  data\                 # Agent data
    agent_id            # Agent identity
  certs\                # Certificates
    agent.crt
    agent.key
    ca.crt
C:\Program Files\muti-metroo\
  muti-metroo.exe       # Binary

Configuration for Windows

# C:\ProgramData\muti-metroo\config.yaml
agent:
  id: "auto"
  data_dir: "C:\\ProgramData\\muti-metroo\\data"
  log_level: "info"
  log_format: "json"

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "C:\\ProgramData\\muti-metroo\\certs\\agent.crt"
      key: "C:\\ProgramData\\muti-metroo\\certs\\agent.key"

socks5:
  enabled: true
  address: "127.0.0.1:1080"

http:
  enabled: true
  address: "127.0.0.1:8080"

Windows User Service (Registry Run)

For users without Administrator access, install as a user service using the Registry Run key and the DLL.

Requirements

muti-metroo.exe - CLI for installation and management
muti-metroo.dll - DLL for background execution via rundll32
config.yaml - Configuration file

Installation

# Install as user service (no admin required)
muti-metroo service install --user --dll C:\path\to\muti-metroo.dll -c C:\path\to\config.yaml

# Install with custom service name
muti-metroo service install --user -n "My Tunnel" --dll C:\path\to\muti-metroo.dll -c C:\path\to\config.yaml

Flags:

--user: Install as user service (required for Registry Run mode)
--dll <path>: Path to muti-metroo.dll (required)
-c, --config <path>: Path to config file (required)
-n, --name <name>: Custom service name (default: muti-metroo). The name is converted to PascalCase for the Registry value (e.g., "My Tunnel" becomes "MyTunnel").

This creates a Registry Run entry at HKCU\Software\Microsoft\Windows\CurrentVersion\Run that:

Starts immediately after installation (no reboot required)
Runs automatically at each user logon
Uses rundll32.exe to execute the DLL
Runs with current user privileges
No console window (background execution)

Service Management

# Check status (shows DLL and config paths)
muti-metroo service status

# View registry entry (default name)
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v MutiMetroo

# View registry entry (custom name, e.g., -n "My Tunnel" becomes "MyTunnel")
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v MyTunnel

# Stop manually (if needed)
taskkill /F /IM rundll32.exe

Registry Value Names

The -n flag sets the service name, which is converted to PascalCase for the registry value:

muti-metroo (default) becomes MutiMetroo
my-tunnel becomes MyTunnel
My Tunnel becomes MyTunnel

note

The service starts automatically after installation and at each user logon. To restart the service, uninstall and reinstall it, or log out and log back in.

Uninstall

# Uninstall (no admin required)
muti-metroo service uninstall

Comparison: Windows Service vs Registry Run

Feature	Windows Service	Registry Run
Requires admin	Yes	No
Auto-restart on crash	Yes	No
Start timing	At boot (before login)	At user logon
Console window	No	No
Runs as	SYSTEM/service account	Current user
Process name	`muti-metroo.exe`	`rundll32.exe`
Requires DLL	No	Yes

Choose Windows Service when:

You have Administrator access
Agent must start before any user logs in
You need automatic crash recovery

Choose Registry Run when:

You don't have Administrator access
User-level execution is acceptable
Minimal installation footprint desired

macOS (launchd)

Installation

# Install as service (requires root)
sudo muti-metroo service install -c /etc/muti-metroo/config.yaml

This creates a launchd plist at /Library/LaunchDaemons/com.muti-metroo.plist.

Service Management

# Check status
muti-metroo service status

# Stop service
sudo launchctl stop com.muti-metroo

# Start service
sudo launchctl start com.muti-metroo

# View logs (in the config file's directory)
tail -f /etc/muti-metroo/muti-metroo.log
tail -f /etc/muti-metroo/muti-metroo.err.log

Uninstall

# Uninstall service
sudo muti-metroo service uninstall

# Clean up files (optional)
sudo rm -rf /etc/muti-metroo
sudo rm -rf /var/lib/muti-metroo

Launchd Plist

The installer creates:

<!-- /Library/LaunchDaemons/com.muti-metroo.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.muti-metroo</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/muti-metroo</string>
        <string>run</string>
        <string>-c</string>
        <string>/etc/muti-metroo/config.yaml</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/etc/muti-metroo</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
    </dict>

    <key>ThrottleInterval</key>
    <integer>5</integer>

    <key>StandardOutPath</key>
    <string>/etc/muti-metroo/muti-metroo.log</string>

    <key>StandardErrorPath</key>
    <string>/etc/muti-metroo/muti-metroo.err.log</string>

    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>

note

Log files are created in the config file's directory (WorkingDirectory). The KeepAlive with SuccessfulExit=false ensures the service restarts only if it exits with an error, not on clean shutdown.

Custom Installation

For manual setup:

# Copy binary
sudo cp muti-metroo /usr/local/bin/

# Create directories
sudo mkdir -p /etc/muti-metroo
sudo mkdir -p /var/lib/muti-metroo

# Copy config and certs
sudo cp ./config.yaml /etc/muti-metroo/
sudo cp -r ./certs /etc/muti-metroo/

# Create plist manually (use template above)
sudo nano /Library/LaunchDaemons/com.muti-metroo.plist

# Load and start
sudo launchctl load -w /Library/LaunchDaemons/com.muti-metroo.plist

Configuration for macOS

# /etc/muti-metroo/config.yaml
agent:
  id: "auto"
  display_name: "${HOSTNAME}"
  data_dir: "/var/lib/muti-metroo"
  log_level: "info"
  log_format: "json"

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "/etc/muti-metroo/certs/agent.crt"
      key: "/etc/muti-metroo/certs/agent.key"

socks5:
  enabled: true
  address: "127.0.0.1:1080"

http:
  enabled: true
  address: "127.0.0.1:8080"

Security Considerations

File Permissions

# Linux
sudo chmod 700 /var/lib/muti-metroo
sudo chmod 640 /etc/muti-metroo/config.yaml
sudo chmod 600 /etc/muti-metroo/certs/*.key
sudo chmod 644 /etc/muti-metroo/certs/*.crt

Network Ports

If using ports below 1024, either:

Run as root (not recommended)

Use capabilities:

sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/muti-metroo

Use ports above 1024

Firewall Rules

# Linux (firewalld)
sudo firewall-cmd --permanent --add-port=4433/udp
sudo firewall-cmd --permanent --add-port=1080/tcp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

# Linux (ufw)
sudo ufw allow 4433/udp
sudo ufw allow 1080/tcp
sudo ufw allow 8080/tcp

Troubleshooting

Service Won't Start

# Check systemd logs
sudo journalctl -u muti-metroo -n 50

# Check service status
sudo systemctl status muti-metroo

# Test config manually
sudo -u muti-metroo /usr/local/bin/muti-metroo run -c /etc/muti-metroo/config.yaml

Permission Denied

# Check file ownership
ls -la /etc/muti-metroo/
ls -la /var/lib/muti-metroo/

# Fix permissions
sudo chown -R muti-metroo:muti-metroo /var/lib/muti-metroo

Port Already in Use

# Find what's using the port
sudo lsof -i :4433
sudo netstat -tlnp | grep 4433

Next Steps

High Availability - Redundancy setup
Troubleshooting - Common issues

Linux (systemd)​

Installation​

Service Management​

Uninstall​

Systemd Unit File​

Custom Installation​

Configuration for Service​

Windows Service​

Installation​

Service Management​

Uninstall​

Windows Paths​

Configuration for Windows​

Windows User Service (Registry Run)​

Requirements​

Installation​

Service Management​

Uninstall​

Comparison: Windows Service vs Registry Run​

macOS (launchd)​

Installation​

Service Management​

Uninstall​

Launchd Plist​

Custom Installation​

Configuration for macOS​

Security Considerations​

File Permissions​

Network Ports​

Firewall Rules​

Troubleshooting​

Service Won't Start​

Permission Denied​

Port Already in Use​

See Also​

Next Steps​

Linux (systemd)

Installation

Service Management

Uninstall

Systemd Unit File

Custom Installation

Configuration for Service

Windows Service

Installation

Service Management

Uninstall

Windows Paths

Configuration for Windows

Windows User Service (Registry Run)

Requirements

Installation

Service Management

Uninstall

Comparison: Windows Service vs Registry Run

macOS (launchd)

Installation

Service Management

Uninstall

Launchd Plist

Custom Installation

Configuration for macOS

Security Considerations

File Permissions

Network Ports

Firewall Rules

Troubleshooting

Service Won't Start

Permission Denied

Port Already in Use

See Also

Next Steps