What this module does #
The firewall is the server's front door: it decides which connections get in and which are rejected. On these machines that job is done by ufw (Ubuntu's firewall), and the firewall module gives you a convenient control to operate it without memorizing ufw syntax.
With it you can see the firewall's status at a glance (active state, default policy and rules), manually block an IP or range that's giving you trouble, release that block when it's no longer needed, and open or close ports while keeping the configuration in sync with what ufw applies.
Automatic bans for intrusion attempts (SSH brute force, etc.) are handled by fail2ban on its own. This module works with your manual blocks: block, unblock and flush only touch what you add by hand and never interfere with fail2ban's bans.
Common tasks #
Choose what you want to do. Each recipe comes with the command already written — just swap the IP or port for yours and hit Copy.
1
View the firewall status
Check whether it's active, its default policy and how many rules it has.
Connect to your server over SSH and ask for the summary:
$ sudo imaxe firewall statusNeed it for a script? Add --json and you'll get the same information in a machine-readable form:
$ sudo imaxe firewall status --json2
Block an abusive IP
Cut off access for an IP or range that's bothering you.
Block a specific IP, noting the reason so you'll remember it later:
$ sudo imaxe firewall block 203.0.113.10 --reason "abuso"Only want a temporary block? Give it a duration with --ttl and it will lift itself. You can also block a whole range in CIDR notation:
$ sudo imaxe firewall block 203.0.113.10 --reason "abuso" --ttl 24h
$ sudo imaxe firewall block 203.0.113.0/24 --reason "escaneo"--ttl, the block expires on its own when the time is up.3
See which IPs I've blocked
Review the list of manual blocks you have active.
List the IPs and ranges you've blocked by hand (remember: fail2ban bans don't show up here):
$ sudo imaxe firewall blocked4
Unblock an IP
Release a manual block that's no longer needed.
Release the exact IP or range you blocked (just as it appears in blocked):
$ sudo imaxe firewall unblock 203.0.113.105
Open or close a port
Let a new service through or close one you no longer offer.
Open a port (with a comment so you know what it's for). You can restrict who gets in with --from:
$ sudo imaxe firewall allow 443/tcp --comment "https"
$ sudo imaxe firewall allow 5432/tcp --from 203.0.113.0/24 --comment "postgres interno"Close a port you no longer use:
$ sudo imaxe firewall deny 8080/tcpfirewall.yml. Check it with imaxe firewall rules list.Don't close port 22 (SSH) if you're connected over SSH: you'd lose access to the server. The module keeps 22/tcp allowed by default precisely to avoid that scare. And remember that flush deletes all your manual blocks at once.
Synopsis #
imaxe firewall <subcomando> [<ip>|<puerto>] [flags]All subcommands require root privileges (use sudo) because they operate on ufw and write to /etc/imaxe/. Add --json to status, blocked or rules list to get machine-readable output suitable for scripting.
Subcommands #
| Subcommand | What it does | Relevant flags |
|---|---|---|
| status | Firewall status: active state, default policy, number of rules and manual blocks. | --json |
| blocked | Lists the manually blocked IPs/ranges (does not include fail2ban's bans). | --json |
| block | Manually blocks an IP or range, with an optional reason and duration. | --reason, --ttl |
| unblock | Releases a manual block. Does not touch fail2ban's bans. | — |
| flush | Deletes all manual blocks (destructive). Does not touch fail2ban's bans. | --yes |
| rules list | Lists the port rules (allowed ports, sources). | --json |
| allow | Opens a port and reflects it in the config. | --from, --comment |
| deny | Closes a port and reflects it in the config. | --from |
| reload | Reloads ufw (reapplies its active rules). | — |
rules groups the management of port rules; for now its only subcommand is rules list.
Arguments and flags #
| Argument / Flag | Type | Default | Description |
|---|---|---|---|
| <ip>[/cidr] req. | string | — | IP or CIDR range to operate on in block and unblock (e.g. 203.0.113.10 or 203.0.113.0/24). |
| <port>[/proto] req. | string | — | Port to operate on in allow and deny (e.g. 443 or 443/tcp). |
| --reason | string | — | In block: reason for the block (informational). |
| --ttl | duration | permanent | In block: duration of the block (e.g. 24h). Permanent by default. |
| --from | cidr | any | In allow/deny: restricts the source to a specific CIDR. |
| --comment | string | — | In allow: descriptive comment for the rule. |
| --yes | bool | false | In flush: confirms without prompting (destructive operation). |
| --json | bool | false | In status/blocked/rules list: emits the result as JSON on stdout. |
Files and paths #
| Path | Contents |
|---|---|
| /etc/imaxe/firewall.yml | Module configuration: allowed ports that allow/deny keep in sync with ufw. |
Example of firewall.yml:
allow:
- { port: 22, proto: tcp, comment: "ssh" }
- { port: 443, proto: tcp, comment: "https" }Exit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
Follow the status and rules live while you debug:
$ sudo imaxe firewall status
$ sudo imaxe firewall rules listTroubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| You get NOTFOUND (code 3) when unblocking | The IP doesn't exactly match the block you set (missing the /cidr, for example). | Run imaxe firewall blocked and copy the entry verbatim for the unblock. |
I blocked an IP but it's still banned after unblock | The block was set by fail2ban, not by you. | This module only releases manual blocks; automatic bans are handled by fail2ban separately. |
| I opened a port but no traffic comes in | The rule is in ufw but an external firewall (security group) is still closed. | Check with imaxe firewall rules list and open the port in your cloud provider too. |
| I lost SSH access after changing rules | Port 22 was closed or restricted. | Access via the provider's console and re-allow 22/tcp with imaxe firewall allow 22/tcp. |
Stuck with the Firewall module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.