AGENT SKILL

fresh-tomato-router

Interact with FreshTomato/DD-WRT routers programmatically via curl — authentication, nvram access, port forwarding, DMZ, and configuration management.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 4
Forks
1

01 前言 Front Matter

name
fresh-tomato-router
author
Steadfaste Fleet
trigger
when you need to check or modify router settings on a FreshTomato or DD-WRT based router
version
1.0.0
platforms
[ "linux" ]
description
Interact with FreshTomato/DD-WRT routers programmatically via curl — authentication, nvram access, port forwarding, DMZ, and configuration management.

02 资源文件 1

03 SKILL.md 正文

FreshTomato Router Administration

Procedures for programmatic interaction with FreshTomato-based routers (descended from Tomato/DD-WRT firmware) using curl and shell commands.

Authentication

Username: root (not admin)

FreshTomato uses root as its admin username. Attempting admin will produce a persistent 401 Unauthorized response even with the correct password. This is a common 15-minute time sink.

# ✅ Works (root as username)
curl -sk --basic -u "root:$(cat ~/.asus)" https://192.168.1.1:8443/

# ❌ Fails (admin as username — even with correct password)
curl -sk --basic -u "admin:$(cat ~/.asus)" https://192.168.1.1:8443/
# → 401 Unauthorized

Scheme: HTTP Basic Auth per request

FreshTomato uses HTTP Basic Authentication (WWW-Authenticate: Basic realm="FreshTomato") on every request, not a session cookie or form-based login. Pass --basic -u "user:pass" on every curl invocation.

⚠️ Password safety: Never write the password literal into a command. Use $(cat /path/to/password) or a clean temp file (see secure-credential-handling skill).

Port

FreshTomato often runs HTTPS on a non-standard port. Common: :8443.

Page Navigation

How pages work

FreshTomato loads page content via AJAX from a single-page app. ASP pages contain inline nvram JavaScript objects with the configuration data. The URL format follows a pattern from the navigation tree:

/{category}-{page}.asp

Key pages

Page URL Purpose
Status / or /about.asp Overview, connectivity
Forwarding Basic /forward-basic.asp Port forwarding rules
Forwarding IPv6 /forward-basic-ipv6.asp IPv6 forwarding
DMZ /forward-dmz.asp DMZ host settings
Triggered /forward-triggered.asp Port triggering
UPnP /forward-upnp.asp UPnP configuration
DHCP /basic-network.asp Network config, DHCP
DHCP Res /forward-static.asp Static DHCP reservations
Shell /shell.cgi Command execution (see below)

Note on direct page access

Some bare .asp pages (e.g., /forward.asp) return 500 Read error. Always use the full navigation path format with the category prefix.

Port Forwarding

Port forwarding configuration is stored in nvram.portforward as a single pipe-delimited string embedded inline in /forward-basic.asp:

nvram = {
    'portforward': '1<1<<14001<<192.168.1.36<Esther App 1>...'
}

Data format

Each rule is delimited by > between entries, fields separated by <:

enabled<protocol<ext_port<local_port<local_ip<description
Field Position Values Notes
enabled 0 1=ON, 0=OFF
protocol 1 1=TCP, 2=UDP, 3=Both
ext_port 2 integer or range (e.g., 20:21) Empty = same as int_port
local_port 3 integer or range Empty = same as ext_port
local_ip 4 IPv4 address Target LAN IP
description 5 string Human-readable name

How to read

# Extract the nvram.portforward value
curl -sk --basic -u "root:$(cat ~/.asus)" \
  "https://192.168.1.1:8443/forward-basic.asp" | \
  grep -oP "portforward':\s*'[^']+"

How to update

The page has a form that submits to tomato.cgi with a portforward hidden input. The form data includes _nextpage=forward-basic.asp for the redirect-back target.

DMZ

DMZ settings live in /forward-dmz.asp:

nvram.dmz_enable — '1' or '0'
nvram.dmz_ipaddr — DMZ target IP
nvram.dmz_sip    — Source IP filter (optional)

Shell Command Execution

FreshTomato has a shell.cgi endpoint that can execute arbitrary shell commands on the router:

curl -sk --basic -u "root:$(cat ~/.asus)" \
  -X POST "https://192.168.1.1:8443/shell.cgi" \
  -d "action=execute&command=nvram+show+|+grep+forward"

This runs commands as root on the router. Useful for dumping nvram, checking iptables rules, or restarting services without the web UI.

Navigation Structure

The side navigation is built dynamically in JavaScript. The nav tree can be found in tomato.js. Key sections:

  • Status: overview, device list, logs
  • Basic: network, IPv6, identification, time, DDNS, DHCP reservation
  • Advanced: firewall, adblock, routing, VLAN, wireless
  • Port Forwarding: basic, basic IPv6, DMZ, triggered, UPnP
  • Administration: access, config, scripts, upgrade

Password File Location

The router password file is at ~/.asus (not ~/.asus_password). This is a single-line file containing the FreshTomato admin password.

cat ~/.asus
# → outputs: <password>

Always reference it via subshell: $(cat ~/.asus). Never embed the literal password into commands or scripts.

End-to-End Port Verification Chain

When a port is unreachable despite a router forwarding rule being configured and enabled, the issue can be in any of four layers. Check them in order:

Layer 1: Router Port Forward

  1. Read the forward rule from the router: curl -sk --basic -u "$(cat ~/.asus)" "…/forward-basic.asp" | grep -oP "portforward':\\s*'[^']+"
  2. Verify: rule exists, enabled (first field is 1), target IP is correct, target port is correct

Layer 2: nginx Proxy (if the port forwards to a nginx server)

  1. Verify nginx is running on the target machine: systemctl is-active nginx or pgrep nginx
  2. Check that nginx is listening on the target port: ss -tlnp | grep <port>
  3. If nginx is NOT listening on the port, the nginx site config needs a listen <port> ssl; directive

Layer 3: UFW / Firewall on Target Machine

  1. Check if UFW is active: sudo ufw status
  2. Check if the port is allowed: sudo ufw status | grep <port>
  3. If the port is missing, allow it: sudo ufw allow <port>
  4. Test TCP reachability from a different LAN machine (e.g., Moses):
    timeout 5 bash -c 'echo > /dev/tcp/<target-ip>/<port> 2>&1 && echo "OPEN" || echo "CLOSED"'
    
    • OPEN = port accepts connections (fast response)
    • CLOSED = port sends RST (immediate "Connection refused")
    • Hang + timeout = firewall silently drops packets (like UFW deny or iptables DROP)

Layer 4: Service Not Running

  1. Check the listening service: ss -tlnp | grep <port> — if nothing shows, the service isn't listening
  2. Check the service health: systemctl --user status <service> or curl http://127.0.0.1:<internal-port>/health
  3. Check UFW is allowing the service's internal port (not just the nginx external port)

Common Patterns

Symptom Likely Layer Test
External HTTP 000 (timeout), internal LAN also timeout Layer 3 (UFW drop) or Layer 1 (router not forwarding) Check UFW first; then check router rule
External HTTP 000, internal LAN immediate "connection refused" Layer 4 (service down) ss -tlnp on target machine
External HTTP 000, internal LAN has HTTP 200 Layer 1 (router forward not set) Check router nvram
External HTTP 401, internal LAN has HTTP 200 Layer 2 (nginx auth) works Correct — nginx is present, just needs auth
External HTTP 000 on one port, HTTP 200 on another (e.g., :14007 works but :14004 doesn't) Layer 3 (UFW blocking specific port on target) sudo ufw status | grep <port> on target machine

Verification

After changing port forwarding rules, verify end-to-end:

# Check from outside the LAN (replace with your public IP)
curl -s -o /dev/null -w "%{http_code}" http://your.public.ip:80

# Check locally on the target server
ss -tlnp | grep -E ':(80|443) '

04 同仓库更多 Skills