🚀 merlin-box

🌐 Languages

English
简体中文

A sing-box + smartdns routing and proxy script solution based on the ASUSWRT-Merlin router environment.

This project aims to clearly separate responsibilities:

🛰️ sing-box is only responsible for proxy forwarding
🌐 smartdns is responsible for DNS resolution and domain routing
📦 ipset + iptables/ip6tables is responsible for IP routing and transparent proxy forwarding

🎥 Quick Start Tutorial

💡 Click the thumbnail below to watch the video demonstration:

Tutorial on Using WEB UI

Tutorial on Using Script Mode

📋 Features and Limitations

Item	Status	Description
IPv4 / IPv6	✅ Supported	Automatically detects IPv6 on startup; enables it if available, automatically downgrades to IPv4 if not available. You can manually disable IPv6 by modifying the MB_ENABLE_IPV6 variable in merlin-box.sh.
IPv4 / IPv6 Routing	✅ Supported	ipset + iptables/ip6tables
Block LAN-side QUIC UDP 443	✅ Handled	Blocks by default (DROP UDP 443) to prevent UDP direct connection leaks. You can disable this by modifying the MB_DISABLE_QUIC_FROM_LAN variable in merlin-box.sh.
smartdns Resolution Routing	✅ Supported	smartdns replaces dnsmasq to handle DNS resolution and domain routing.
Ad Blocking	✅ Supported	Implemented through configuring the site-blocklist.txt blackhole domain list.
Domain Blacklist	✅ Supported	Implemented through configuring the site-blacklist.txt blacklist domain list to force specified domains through the proxy.
Domain Whitelist	✅ Supported	Implemented through configuring the site-whitelist.txt whitelist domain list to force specified domains to direct connection.
Custom HOSTS	✅ Supported	Implemented through configuring the hosts.txt file for custom HOSTS, commonly used by developers to resolve domain names within the local network for debugging.
IP Whitelist	✅ Supported	Implemented through configuring ip4-whitelist.txt and ip6-whitelist.txt files to force specified IPs to direct connection.
IP Blacklist	✅ Supported	Implemented through configuring ip4-blacklist.txt and ip6-blacklist.txt files to force specified IPs through the proxy.
UDP	✅ Supported	UDP is disabled by default. To use UDP proxy, change the MB_ENABLE_UDP variable value in merlin-box.sh to 1.
Router Itself	✅ Supported	TCP proxy only, disabled by default. To enable, change the MB_ENABLE_ONESELF_PROXY variable value in merlin-box.sh to 1.
Device Blacklist	✅ Supported	Prevents neighbors from accidentally entering the Lost Forest🌳. Configure neighbors' device MAC addresses in device_blacklist.txt.
Device Whitelist	✅ Supported	Using a whitelist prevents unauthorized guests from accidentally entering the Lost Forest🌳. Configure common device MAC addresses in device_whitelist.txt.
UI	✅ Supported	WEB UI is started using ./merlin-box.sh server.
Software Center	✅ Supported	The package file supports installation in the KoolCenter Software Center.
Subscription	✅ Supported	Subscription parsing currently supports VLESS, VMess, Trojan, and Shadowsocks protocols, with compatibility for both standard URL and Base64-encoded formats.
Ping Proxy	⏳ Not Supported	Not in the current proxy scope.

💡 Notes

UDP proxy requires support from upstream nodes, and sing-box needs to be configured with an outbound that supports UDP.
Proxy functionality for the router itself requires adding a redirect inbound in the sing-box configuration.
IPv6 requires both local network and upstream server support; when MB_ENABLE_IPV6=1, the script will automatically detect local network IPv6 availability and automatically downgrade to IPv4 if unavailable.
⚠️ The script cannot detect whether the upstream server supports IPv6. If the upstream does not support IPv6 and MB_ENABLE_IPV6=1, since IPv6 priority mode will be used, you may not be able to connect to the internet.
QUIC is part of UDP. Regardless of whether UDP proxy is enabled, the project adopts an interception scheme (DROP UDP 443), which means websites that rely on H3/QUIC will not be able to access via QUIC on the client side (usually falls back to TCP/TLS; some sites may fail to open or behave abnormally).
⚠️ Device blacklist and whitelist functionality depends on whether device_blacklist.txt/device_whitelist.txt files exist. As long as the files exist, the script will enable the blacklist/whitelist functionality. If you do not need this feature, please delete these two files.
WEB UI is started using ./merlin-box.sh server, with the default port being 8080. You can specify a port when starting: ./merlin-box.sh server 8081. The default login username/password is admin/merlinbox.

🖥️ UI Preview

⚙️ Core Execution Logic

🌍 Domain Routing (smartdns)

res/chn-site.txt serves as the domain collection
Matching domain -> Use China DNS upstream for resolution (china group)
Other domains -> Use international DNS upstream (foreign group, proxied through socks5 by default)

smartdns configuration:

Configuration file: conf/smartdns.conf
Configuration reference: https://pymumu.github.io/smartdns/en/configuration/

📡 IP Routing (ipset + iptables/ip6tables)

res/chn-ip4.txt, res/chn-ip6.txt serve as the IP subnet collection
Loaded into ipset collections on startup:
- IPv4: merlinkbox_chn
- IPv6: merlinkbox_chn_v6
Matching IP collection -> Direct connection pass-through
Non-matching -> Transparent proxy forwarding to sing-box TPROXY port

Optional whitelist files:

IPs in these whitelists will be treated as direct connections:
- res/ip4-whitelist.txt
- res/ip6-whitelist.txt

🚀 Proxy Execution (sing-box)

Inbound:
- SOCKS: 65001 (for smartdns foreign upstream to resolve through proxy)
- TPROXY: 65002 (for transparent proxy receiving)
- REDIRECT: 65003 (for the router itself to access through the proxy)
Outbound: Configure yourself in conf/config.json

sing-box (conf/config.json) configuration reference:

https://sing-box.sagernet.org/configuration/

📁 Directory Structure

merlin-box/
├─ merlin-box.sh            # Main entry script (start/stop)
├─ start_merlin_box.sh      # For boot startup support
├─ install.sh               # KoolCenter Software Center installation script
├─ uninstall.sh             # KoolCenter Software Center uninstallation script
├─ webs                     # KoolCenter Software Center web page files
├─ ui/                      # WEB UI Development Directory
│  ├─ server                # WEB UI server
│  └─ front                 # WEB UI front-end
├─ wwwroot/                 # WEB UI static files
├─ db/                      # WEB UI database
│  └─ db.json               # WEB UI database file, note to change the login username and password after first obtaining it, the password is an md5 encrypted string
├─ bin/
│  ├─ sing-box              # sing-box executable
│  ├─ smartdns              # smartdns executable
│  └─ merlin-box             # WEB UI server executable
├─ conf/
│  ├─ config.json           # sing-box configuration
│  └─ smartdns.conf         # smartdns configuration
├─ scripts/
│  ├─ merlinbox_webui.sh    # KoolCenter Software Center backend script
│  └─ dnsmasq.postconf      # dnsmasq post-processing script (used when taking over port 53)
├─ sh/
│  ├─ fun.sh                # Core logic
│  └─ tool.sh               # Implementation of tool subcommands
├─ tools/
│  ├─ sub2box/              # Tool for converting subscriptions to sing-box configuration
│  └─ update-rules/         # Rule update scripts
└─ res/
   ├─ chn-ip4.txt           # China IPv4
   ├─ chn-ip6.txt           # China IPv6
   ├─ chn-site.txt          # China domain list
   ├─ device_blacklist.txt  # Device blacklist (devices cannot use proxy)
   ├─ device_whitelist.txt  # Device whitelist (only authorized devices can use proxy)
   ├─ site-blocklist.txt    # Blocked domain list (blackhole)
   └─ site-blacklist.txt    # Blacklist domain list (force proxy)

⚠️ Notes

The script will by default look for bin/sing-box and bin/smartdns in the project to start related services and redirect console output to logs/sing-box.log and logs/smartdns.log.
The binary files included have been tested on the following devices (limited devices available for testing).

Model	SINGBOX	SMARTDNS
RT-BE86U	linux-arm64-musl	smartdns-aarch64
RT-AC86U	linux-arm64-musl	smartdns-aarch64

🖥️ Applicable Environments and Device Notes

✅ Tested Models: RT-BE86U, RT-AC86U.
✅ Architecture Support: Pre-built packages are provided for ARM64 (64-bit) and ARM (32-bit). Download the appropriate package from the Release page.
⏳ More Models: Due to limited access to hardware, additional models have not yet been tested. In theory, any ASUSWRT-Merlin router with an ARM64 or ARM (32-bit) CPU architecture should be able to run Merlin-box. If you encounter any issues, please report them in Issues.
💾 Storage: Some routers have limited JFFS storage. Although the binary has been compressed, you may still run out of space. It is recommended to place the program on a USB drive or other external storage.
📂 Installation Directory: Merlin-box can run from any directory, but /jffs/merlin-box is recommended.

🚀 Quick Deployment

📦 Prepare Files

Download the package matching your router's CPU architecture from the Release page, then upload the project files to your router. It is recommended to place them in /jffs/merlin-box.
Optional: This project provides ARM64 (64-bit) and ARM (32-bit) versions. If the included binaries are not compatible with your router's CPU architecture, you can try downloading the appropriate binaries from the sing-box and SmartDNS repositories and replacing the corresponding files in the project.
- bin/sing-box
- bin/smartdns
Grant execute permissions (example):

chmod +x merlin-box.sh
./merlin-box.sh init

▶️Start UI and Initialize Configuration (WEB UI)

Start the WEB UI Server
```
./merlin-box.sh server
```
Access the WEB UI

Open the following address in your browser:

http://ROUTER_IP:8080
Log in to the WEB UI

Use the default credentials:

Username: admin
Password: merlinbox

Configure Proxy Nodes

Go to Node Management, add your proxy nodes, and set the node you want to use as the default node.
Configure Other Settings

Adjust the following settings according to your needs:

DNS upstream servers
IP whitelist / blacklist
Domain blacklist
Other routing and proxy settings

Start the Proxy

Once the configuration is complete, start the proxy service.

🔧 Modify Configuration (Script Mode Manual)

1. Modify `conf/config.json` (sing-box configuration)

Configure outbounds based on your node information
Confirm that the sing-box outbound routing_mark matches the script variable (default 169)

2. Modify `conf/smartdns.conf`

Replace China/International DNS upstream as needed
Maintain domain routing rules (chn-site.txt)

3. If you need additional direct connection IPs, you can create and maintain (optional):

res/ip4-whitelist.txt
res/ip6-whitelist.txt

4. If you need to force proxy for specific IPs, you can create and maintain (optional):

res/ip4-blacklist.txt
res/ip6-blacklist.txt

5. Ad blocking/domain blocking (blackhole)

res/site-blocklist.txt

6. Force proxy domain (blacklist)

res/site-blacklist.txt This project includes Apple-related domains in this file, which helps solve many problems accessing foreign Apple services. Friends accessing China region should modify this file themselves.

7. Device blacklist and whitelist (optional)

res/device_blacklist.txt: Worried about neighbors leeching and accidentally entering the Lost Forest🌳? Configure neighbors' device MAC addresses in this file.
res/device_whitelist.txt: Using a whitelist can prevent unauthorized guests from accidentally entering the Lost Forest🌳. Configure common device MAC addresses in this file.
⚠️ If you don't need this feature, please delete the corresponding file; otherwise, the file may exist but have no configured devices, causing devices to fail to connect to the internet.

▶️ Start/Stop Commands

Main entry command:

./merlin-box.sh start                      #Start service (defaults: 1 1 0 0 1)
./merlin-box.sh start 1 1 0 0 1            #Start with explicit params: IPv6 QUIC-block UDP oneself-proxy TcpFastOpen
./merlin-box.sh stop                       #Stop service
./merlin-box.sh restart                    #Restart service
./merlin-box.sh restart 1 1 0 0 1          #Restart with explicit params: IPv6 QUIC-block UDP oneself-proxy TcpFastOpen
./merlin-box.sh server                     #Start WEB UI server, default port is 8080, can specify port on startup: ./merlin-box.sh server 8081. Supports subcommands start/stop/restart, default is start. ./merlin-box.sh server start 8081
./merlin-box.sh -h                         #Show help information
./merlin-box.sh -v                         #Show version information

▶️ start: Clean old rules -> Start sing-box -> Start smartdns -> Restart dnsmasq
start parameters (all optional, each value is 0 or 1, default is 1 1 0 0 1):
- enable_ipv6 disable_quic_from_lan enable_udp enable_oneself_proxy enable_tcp_fast_open
⏹️ stop: Stop sing-box/smartdns -> Clean iptables/ip6tables/ip rule/ipset -> Restart dnsmasq

Installation and uninstallation (boot startup):

./merlin-box.sh install                     #Install service to enable boot startup (after successful connection)
./merlin-box.sh uninstall                   #Uninstall service to disable boot startup

Tool commands:

./merlin-box.sh tool compress_singbox       #Compress sing-box executable ¹
./merlin-box.sh tool compress_smartdns      #Compress smartdns executable ¹
./merlin-box.sh tool compress_merlinbox     #Compress merlin-box executable ¹
./merlin-box.sh tool show_devices           #Show current DHCP lease device list  
./merlin-box.sh tool update_rules           #Update rule files ²
./merlin-box.sh tool build_singbox          #Build sing-box executable ¹
./merlin-box.sh tool download_smartdns      #Download smartdns executable ¹
./merlin-box.sh tool sub2nodes              #Convert subscription to node list 
./merlin-box.sh tool sub2box                #Convert subscription to sing-box configuration ³
./merlin-box.sh tool build_ui               #Build WEB UI front-end and resources
./merlin-box.sh tool build_merlinbox        #Build merlin-box server
./merlin-box.sh tool package                #Build final package
./merlin-box.sh tool -h

Commands are only executed on the local system (or WSL), not on the router. Compression depends on the upx tool.

The binary files included in this repository have been compressed.
⚠️ While compression can significantly reduce file size, startup will be slower than the original program.

Rule updates have two behaviors:

In development mode, a Python script is called to download the latest rule files from three sources and overwrite the local files.
In production mode (on the router), wget is used to download the latest rule files from the raw files of this repository and overwrite the local files.

Subscription conversion has two behaviors:

In development mode, a Python script is called to convert the subscription to sing-box configuration.
In production mode (on the router), the merlin-box (under development) binary file is called for conversion.

📡 Protocol Support

In theory, any protocol supported by sing-box can be integrated into this solution as long as it is correctly configured in conf/config.json.

🙏 Reference Projects

ASUSWRT-Merlin
https://github.com/RMerl/asuswrt-merlin.ng
https://sourceforge.net/projects/asuswrt-merlin/files/
sing-box
https://github.com/sagernet/sing-box
smartdns
https://github.com/pymumu/smartdns
fancyss
https://github.com/hq450/fancyss

📜 LICENSE

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Navigation Menu

Repository navigation

About

Repository files navigation

🚀 merlin-box

🌐 Languages

🎥 Quick Start Tutorial

📋 Features and Limitations

💡 Notes

🖥️ UI Preview

⚙️ Core Execution Logic

🌍 Domain Routing (smartdns)

📡 IP Routing (ipset + iptables/ip6tables)

🚀 Proxy Execution (sing-box)

📁 Directory Structure

⚠️ Notes

🖥️ Applicable Environments and Device Notes

🚀 Quick Deployment

📦 Prepare Files

▶️Start UI and Initialize Configuration (WEB UI)

🔧 Modify Configuration (Script Mode Manual)

1. Modify `conf/config.json` (sing-box configuration)

2. Modify `conf/smartdns.conf`

3. If you need additional direct connection IPs, you can create and maintain (optional):

4. If you need to force proxy for specific IPs, you can create and maintain (optional):

5. Ad blocking/domain blocking (blackhole)

6. Force proxy domain (blacklist)

7. Device blacklist and whitelist (optional)

▶️ Start/Stop Commands

📡 Protocol Support

🙏 Reference Projects

📜 LICENSE

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
conf		conf
db		db
res		res
scripts		scripts
sh		sh
tools		tools
ui		ui
webs		webs
wwwroot		wwwroot
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
install.sh		install.sh
merlin-box.sh		merlin-box.sh
start_merlin_box.sh		start_merlin_box.sh
uninstall.sh		uninstall.sh

Latest commit

History

Folders and files

Repository files navigation

🚀 merlin-box

🌐 Languages

🎥 Quick Start Tutorial

📋 Features and Limitations

💡 Notes

🖥️ UI Preview

⚙️ Core Execution Logic

🌍 Domain Routing (smartdns)

📡 IP Routing (ipset + iptables/ip6tables)

🚀 Proxy Execution (sing-box)

📁 Directory Structure

⚠️ Notes

🖥️ Applicable Environments and Device Notes

🚀 Quick Deployment

📦 Prepare Files

▶️Start UI and Initialize Configuration (WEB UI)

🔧 Modify Configuration (Script Mode Manual)

1. Modify conf/config.json (sing-box configuration)

2. Modify conf/smartdns.conf

3. If you need additional direct connection IPs, you can create and maintain (optional):

4. If you need to force proxy for specific IPs, you can create and maintain (optional):

5. Ad blocking/domain blocking (blackhole)

6. Force proxy domain (blacklist)

7. Device blacklist and whitelist (optional)

▶️ Start/Stop Commands

📡 Protocol Support

🙏 Reference Projects

📜 LICENSE

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. Modify `conf/config.json` (sing-box configuration)

2. Modify `conf/smartdns.conf`