Mudfish Exclude User Guide

info

This mudfish-exclude tool is available after Mudfish Cloud VPN 6.5.4 or above.

mudfish-exclude runs a selected Linux program outside the Mudfish routing policy.

Use it when Mudfish is running, but you want one program, such as a browser, chat app, launcher, or updater, to use your normal internet connection instead of the Mudfish path.

This is especially useful with Full VPN mode. It does not add a dashboard setting: start the selected program through mudfish-exclude instead.

Normal program      -> Mudfish path       -> Mudfish node
mudfish-exclude app -> Normal default route -> Internet

Supported Environment

mudfish-exclude is for Linux only.

Your system needs:

• Mudfish for Linux
• sudo or root permission
• cgroup v2 mounted at /sys/fs/cgroup
• the ip command
• iptables
• an IPv4 default route

This tool controls IPv4 traffic. IPv6 traffic is not redirected by mudfish-exclude.

Windows, macOS, and Android are not supported. The kernel and iptables must support cgroup matching, and the Linux main routing table must contain a working IPv4 default route.

The executable is normally installed at /opt/mudfish/<version>/bin/mudfish-exclude. Find it with:

ls /opt/mudfish/*/bin/mudfish-exclude

If it is not in PATH, use its full path in the examples below. For version 6.5.4, that path is /opt/mudfish/6.5.4/bin/mudfish-exclude.

Basic Use

Start Mudfish and connect using your items or Full VPN mode. Completely close the program you want to exclude, including its tray and background processes, before starting it again.

Run the program through mudfish-exclude:

sudo mudfish-exclude firefox

You can pass normal program arguments after the program name:

sudo mudfish-exclude firefox --private-window
sudo mudfish-exclude curl https://mudfish.net

If the command has many options, you can separate mudfish-exclude options from the program command with --:

sudo mudfish-exclude -- firefox --private-window

Quote executable paths that contain spaces:

sudo mudfish-exclude "/path/to/My Program" --option

Although you start it with sudo, the launched program is normally returned to your regular user account. This helps GUI programs use your usual home directory, desktop session, and configuration files instead of root's settings.

Where possible, the program uses the UID, GID, home directory, and desktop session environment of the user who invoked sudo. Root privileges are used to set up the network policy.

What Happens While It Runs

When you start a command, mudfish-exclude temporarily creates network policy rules for that command. Traffic from the command is marked and sent through your system's normal IPv4 default route.

When the command exits, mudfish-exclude waits for the related process group to finish and then removes the temporary rules.

Mudfish itself is not stopped. Other programs continue to use Mudfish according to your Mudfish settings.

The policy applies to the newly launched process and its child processes; it cannot be attached to an already running program. Multiple mudfish-exclude commands can run at the same time. Shared policy is removed after the last excluded program exits.

Excluded IPv4 traffic does not use Mudfish nodes, their acceleration features, or their public IP addresses.

Verify That Exclusion Works

This is easiest to check when your normal public IPv4 address differs from the Full VPN node's address. With Full VPN connected, run:

curl -4 https://myip.mudfish.net
sudo mudfish-exclude curl -4 https://myip.mudfish.net

The first result should show the node's address; the second should show the address of your normal Internet connection. The -4 option limits the test to IPv4, which this tool supports.

For a browser test, close the browser completely, run sudo mudfish-exclude firefox, and visit https://myip.mudfish.net.

Examples

Open Firefox outside Mudfish:

sudo mudfish-exclude firefox

Run Discord outside Mudfish:

sudo mudfish-exclude discord

Run Steam outside Mudfish:

sudo mudfish-exclude steam

Run a command-line download outside Mudfish:

sudo mudfish-exclude wget https://example.com/file.zip

Using Setup and Cleanup Manually

For normal use, you do not need these commands. mudfish-exclude sets up and cleans up the policy automatically.

If you need to prepare the policy once and then run several commands with the same policy, use:

sudo mudfish-exclude --setup
sudo mudfish-exclude --no-setup firefox
sudo mudfish-exclude --no-setup discord
sudo mudfish-exclude --cleanup

Always run --cleanup when you are done with manual setup mode.

First close all programs started through this tool. Running --cleanup while an excluded program is still running can immediately stop its bypass.

Manual setup does not clean up automatically. Some desktop programs move to another systemd cgroup while running. The normal one-command method tracks these moves and cleans up automatically, so it is preferable for such programs.

Advanced Options

Most users should keep the defaults.

Option	Purpose	Default
-h, --help	show help	—
--cgroup NAME	cgroup v2 name used for the excluded program	mudfish-exclude
--mark VALUE	firewall mark value	0x6d660001
--priority VALUE	IPv4 rule priority	8252
--table VALUE	IPv4 routing table number	8252
--setup	create the policy and exit	off
--cleanup	remove the policy and exit	off
--no-setup	join an existing policy and run the command	off

Change these only if Mudfish support asks you to, or if the default mark, priority, or table conflicts with another local network tool.

Do not specify a program with --setup or --cleanup. --no-setup runs the program in the specified cgroup without setting up the policy again. If you customize --cgroup, --mark, --priority, or --table, use the same values for setup, reuse, and cleanup. Avoid conflicts with existing firewall marks and policy routing rules.

Example:

sudo mudfish-exclude --table 9000 --priority 9000 firefox

Important Notes for GUI Apps

Some desktop applications reuse an already running process. For example, if a browser is already open, running sudo mudfish-exclude firefox may only ask the existing browser to open a new window. In that case, the existing browser process may not be excluded.

For best results:

• Close the application before launching it with mudfish-exclude.
• For browsers, use a separate profile if you need both Mudfish-routed and excluded browser windows at the same time.
• Start the real application command, not only a desktop shortcut.

Troubleshooting

mudfish-exclude: command not found

Find the installed executable and use its full path:

ls /opt/mudfish/*/bin/mudfish-exclude
sudo /opt/mudfish/6.5.4/bin/mudfish-exclude discord

Replace the version in the second command with your installed version.

network policy setup requires root

Run the command with sudo:

sudo mudfish-exclude firefox

cgroup v2 is required at /sys/fs/cgroup

Your Linux system is not using cgroup v2 in the expected location. Update the system configuration to enable cgroup v2, or use a Linux distribution that provides it by default.

Check whether cgroup v2 is available with:

test -f /sys/fs/cgroup/cgroup.controllers && echo "cgroup v2 available"

If there is no output, check your distribution's instructions for enabling cgroup v2.

iptables rule add failed or a cgroup match error

Check that iptables is installed and that both the kernel and iptables support cgroup matching. On distributions that use nftables, the tool still calls iptables directly, so a working iptables compatibility layer is required.

failed to find the IPv4 default route

The system does not have a usable IPv4 default route. Check that your normal internet connection works before running mudfish-exclude.

Check for a default route in the main table:

ip -4 route show default table main

If it is missing or already points to another VPN interface, the tool cannot set up the original Internet route.

The app still seems to use Mudfish

Close the app completely and start it again through mudfish-exclude. This is especially important for browsers, game launchers, and chat apps that keep background processes running.

Also check that Full VPN is connected and shows the node's address during normal use. Test IPv4 explicitly with curl -4. If the program passes its work to a separate service or an existing launcher, that process is outside the new process tree and may not be excluded. Confirm that the main table's default route points to your actual Internet interface.

The terminal command keeps running after I close the program

A child or background process may still be running in the exclusion cgroup. Close related tray applications, launchers, and updaters. The normal execution mode waits for all child processes before cleaning up.

Network rules remain after an interrupted run

Run cleanup manually:

First close all programs started through this tool. Policies can remain after forced termination, an unexpected terminal closure, or a system interruption.

sudo mudfish-exclude --cleanup

If you used custom --mark, --priority, --table, or --cgroup values, use the same values with --cleanup.

If network problems continue, stop Mudfish, check the system's default route and iptables rules, and then reconnect.

How It Works

mudfish-exclude places the program in a separate cgroup v2 and applies an iptables mark to IPv4 packets from that cgroup. A separate policy routing table sends marked packets through the default route found in Linux's main table, with NAT MASQUERADE applied as needed.

This does not modify the configuration or shared memory of mudrun, mudflow, mudfish, or mudwfp_proxy. The exclusion policy operates through the operating system's cgroups, iptables, and IPv4 policy routing.

Quick Reference

sudo mudfish-exclude COMMAND [ARGS...]
sudo mudfish-exclude --setup
sudo mudfish-exclude --no-setup COMMAND [ARGS...]
sudo mudfish-exclude --cleanup