1. Overview and Core Principles

This document provides correct methods and considerations for firewall configuration for RobustOS Pro system users.

1.1 Core Principles

The system's firewall is uniformly managed by a system service named router. It generates iptables rules in memory based on UCI (Unified Configuration Interface) configuration information, then loads them into the system kernel all at once.

This mechanism leads to the following two important principles:

1. Rule Cleanup Scope: When the system network service restarts or configuration changes occur (such as executing fw_restart), the system cleans up and rebuilds rules with the ROSPRO-FIREWALL comment; manually created rules without this comment will not be cleared by service restarts, but they are not managed by the system and may cause rule drift and conflicts.

2. Temporary vs. Persistent: Rules added directly via iptables temporarily will not be retained after device restart (become invalid upon system reboot). All firewall rules that need to take effect long-term (persistent) must be configured through the official methods introduced in this document.

This is the most important and fundamental principle for interacting with this system's firewall.

1.2 System Characteristics

Before configuring, please understand some key characteristics of this system:

• Firewall Command: fw_restart is the command to apply firewall configuration changes.

• Permission Requirements: All related operations require root privileges or execution via sudo.

• iptables Path: The full path to the iptables command is /usr/sbin/iptables.

• Custom Rule Method: Officially supported custom rule loading through /tmp/fw.d/ scripts; combine with persistence solutions to ensure they take effect after restart.

2. Operations to Avoid (Don'ts)

The following operations conflict with the system's built-in firewall management logic and must not be performed, otherwise they may cause network anomalies or configuration loss.

• Do not add persistent rules directly using iptables

  • Risk: Commands like iptables -A INPUT ... are not persistent configurations: they will be lost after device restart; if they contain the ROSPRO-FIREWALL comment, they will be cleaned by the system during fw_restart; if they don't contain this comment, although they won't be cleaned by fw_restart, they will be outside system management, easily conflicting with generated rules, which is an unsupported practice.

• Do not edit system-generated temporary files

  • Risk: Rule files generated by the system in the /tmp directory (such as /tmp/.ipt) are dynamic, and any manual edits will be immediately overwritten.

  • Note: /tmp/fw.d/ is a directory reserved for custom scripts and allows creation and modification.

• Do not directly modify system built-in chains

  • Risk: Directly modifying main system chains like INPUT, FORWARD, etc. will break the firewall architecture.

  • Correct Approach: Rules should be added to custom chains provided by the system, such as input_rule, forwarding_rule, etc. (see Appendix).

3. Adding Rules Using /tmp/fw.d/ Scripts

This method creates an executable script in the /tmp/fw.d/ directory. The firewall service will automatically execute all scripts in this directory when it restarts.

• Advantages: Supports multiple commands, complex logic (such as loops, conditional statements), calling external programs, etc.

• Limitations: Files in the /tmp directory are lost after system restart and require self-implemented persistence.

Operation Steps

1. Create script file: Script filenames are recommended to start with a number to control execution order (such as 50-myapp-rules).

Example: Opening Multiple Ports for an Application

sudo bash -c 'cat > /tmp/fw.d/50-myapp-rules << '\''EOF'\''
#!/bin/sh
# MyApp custom firewall rules

# Important: Must use full path to iptables
IPTABLES_CMD="/usr/sbin/iptables"

# Allow application main port 8888
$IPTABLES_CMD -A input_rule -p tcp --dport 8888 -j ACCEPT

# Allow application management port 8889
$IPTABLES_CMD -A input_rule -p tcp --dport 8889 -j ACCEPT

echo "MyApp firewall rules loaded."
EOF'

2. Add execute permissions:

sudo chmod +x /tmp/fw.d/50-myapp-rules

3. Apply and Verify:

# Apply all firewall configurations, including new script
sudo fw_restart

# Verify rules are in effect
sudo /usr/sbin/iptables -L input_rule -n -v | grep -E "8888|8889"

Making Scripts Persistent (systemd-based, Recommended)

Since the /tmp directory is temporary, scripts will be lost after restart. If you need rules to remain effective after boot, it's recommended to use systemd to automatically copy scripts and reload the firewall at boot.

1. Place the script in a persistent directory and ensure it's executable:

sudo install -D -m 0755 /tmp/fw.d/50-myapp-rules /opt/myapp/50-myapp-rules.sh

2. Create a systemd unit file:

# /etc/systemd/system/myapp-firewall.service
[Unit]
Description=Load custom firewall rules at boot
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/bin/mkdir -p /tmp/fw.d
ExecStart=/bin/cp /opt/myapp/50-myapp-rules.sh /tmp/fw.d/50-myapp-rules
ExecStart=/bin/chmod +x /tmp/fw.d/50-myapp-rules
ExecStart=/usr/bin/env fw_restart

[Install]
WantedBy=multi-user.target

3. Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable myapp-firewall.service
sudo systemctl start myapp-firewall.service
sudo systemctl status myapp-firewall.service --no-pager

1. Verify rules are in effect:

sudo /usr/sbin/iptables -L input_rule -n -v | grep -E "8888|8889"

4. Common Troubleshooting

• Issue 1: Rules not taking effect?

  1. Check permissions (/tmp/fw.d/ script): Ensure script has execute permissions (ls -l /tmp/fw.d/).

  2. Check path: Ensure script uses the full path /usr/sbin/iptables.

  3. Check chain name: Ensure rules are added to the correct custom chain, such as input_rule, not INPUT.

  4. Manually execute script: Run the script directly (sudo /tmp/fw.d/50-myapp-rules) to see if there are error messages.

• Issue 2: Rules disappear after system restart?

  • Reason: Used /tmp/fw.d/ script method but did not configure persistence. The /tmp directory is cleared after system restart.

  • Solution: Refer to the persistence solution in Section 3.

5. Appendix: Quick Reference

5.1 Common Commands

# Apply all firewall configurations
sudo fw_restart

# View all rules in input_rule chain (with line numbers and statistics)
sudo /usr/sbin/iptables -L input_rule -n -v --line-numbers

# View all rules in nat table
sudo /usr/sbin/iptables -t nat -L -n -v

# View rules with traffic matches
sudo /usr/sbin/iptables -L input_rule -n -v | grep -v "0     0"

# View custom scripts
ls -lh /tmp/fw.d/

# View firewall-related logs in real-time
sudo journalctl -f | grep -E "iptables|firewall"

5.2 Available Custom Chains

You should add custom rules to the following system-preset chains, rather than directly operating on main chains like INPUT, FORWARD, etc.