How-To Alpine Wall: Difference between revisions

From Alpine Linux
(added links to see-also section)
(added wikilink and simplified introduction)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
[https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax. The purpose of this page is to illustrate Alpine Wall (AWall) by example. This page explains AWall from the viewpoint of a Shorewall user.
This page shows how to configure Alpine Wall(awall) as compared to {{pkg|Shorewall}} firewall. This comparison is meant to help readers who are familiar with Shorewall learn AWall. Awall users should follow the AWall configuration examples. Use the Shorewall examples as contextual references, or ignore them, if unfamiliar with Shorewall.
 
[[Zero-To-Awall]] howto page is meant for users with no firewall experience and [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax.  


== Installation ==
== Installation ==
Install the {{pkg|awall}} package by running the following command:{{cmd|# apk add iptables awall}}


Install the {{pkg|awall}} package and make sure you are running the latest version by running the following commands:
Note that awall requires {{pkg|iptables}} but works with both backends [[nftables]] and legacy [[iptables]]. It does not interact with nftables directly.
{{cmd|<nowiki># apk add iptables awall
$ apk version awall</nowiki>}}


== Prerequisites ==
== Configuration ==  


After installing AWall, you need to load the following iptables modules:
The easier method for performing initial steps for running awall: {{cmd|# awall activate}}
{{cmd|<nowiki># modprobe ip_tables
The above command has special handling for the first run, when firewall is not yet enabled in the kernel. It performs the  below manual steps and also updates the default runlevel and files in {{Path|/etc/conf.d}}
# modprobe iptable_nat    #if NAT is used</nowiki>}}


This is needed only one time after awall installation.
Use the below commands for performing initial setup manually.
* To update /etc/iptables: {{cmd|# awall translate}}
* To start the [[OpenRC]] services for iptables and load modules and rules for IPv4 and IPv6 {{cmd|<nowiki># rc-service iptables start 
# rc-service ip6tables start </nowiki>}}


To make the firewall autostart at boot and autoload the needed modules:
=== Configuration files ===
{{cmd|<nowiki># rc-update add iptables
# rc-update add ip6tables</nowiki>}}
 
== Configuration files ==


Your [[Alpine Wall]] configuration files go in {{Path|/etc/awall/optional}}. From version 0.2.12 and later, Awall will look for ''Policy'' files in both the former and {{Path|/usr/share/awall/optional}}
Your [[Alpine Wall]] configuration files go in {{Path|/etc/awall/optional}}. From version 0.2.12 and later, Awall will look for ''Policy'' files in both the former and {{Path|/usr/share/awall/optional}}
Line 35: Line 35:
* services ''(like {{Path|/usr/share/shorewall/macro.HTTP}})''
* services ''(like {{Path|/usr/share/shorewall/macro.HTTP}})''


== Basic home firewall ==
== Basic home firewall configuration ==


The below example shows the "Basic home firewall" configuration for both Shorewall and AWall. Based on below example, it can be clearly seen that AWall ''Policy'' files are not equivalent to Shorewall's {{Path|/etc/shorewall/policy}} files.  
The examples below show how to configure a basic home firewall using AWall. Note that AWall Policy files differ substantially from Shorewall's policy files in syntax and layout.


=== Shorewall configuration ===
=== Shorewall configuration ===


Let's suppose you have the following Shorewall configuration: {{cat|/etc/shorewall/zones|inet  ipv4
Let's suppose you have the following Shorewall configuration files in {{Path|/etc/shorewall/}}, which you want to convert to a [[#AWall configuration|configuration for AWall]].  {{cat|/etc/shorewall/zones|inet  ipv4
loc  ipv4}}
loc  ipv4}}


Line 55: Line 55:
=== AWall configuration ===
=== AWall configuration ===


The equivalent AWall configuration that does the same thing as the above Shorewall example is given below.
The equivalent AWall configuration that does the same thing as the above [[#Shorewall configuration|Shorewall example]] is given below.


Create a new file called {{Path|/etc/awall/optional/home-policy.json}} and add the following content {{Cat|/etc/awall/optional/home-policy.json|<nowiki>
Create a new file called {{Path|/etc/awall/optional/home-policy.json}} and add the following content {{Cat|/etc/awall/optional/home-policy.json|<nowiki>
Line 74: Line 74:
     { "out": "inet" }
     { "out": "inet" }
   ]
   ]
}</nowiki>
}</nowiki>}}
}}
 
The above configuration will:
The above configuration will:
* Create a description of your ''Policy''
* Create a description of your ''Policy''
Line 88: Line 88:
=== Activating/Applying a Policy ===
=== Activating/Applying a Policy ===


After saving the ''Policy'' you can run the following commands to activate your firewall settings:
After saving the ''Policy'' you can run the following commands to activate your firewall settings.
{{cmd|awall list                 # Listing available 'Policy(s)' (This step is optional)
To listing available 'Policy(s)' {{cmd|# awall list}}
awall enable test-policy    # Enables the 'Policy'
To enable the 'Policy' created in the previous section:{{cmd|# awall enable home-policy}}    
awall activate              # Genereates firewall configuration from the 'Policy' files and enables it (starts the firewall)}}
To generate firewall configuration from the 'Policy' file and enable it i.e start the firewall: {{Cmd|# awall activate}}            


If you have multiple policies, after enabling or disabling them, you need to always run ''awall activate'' in order to update the iptables rules.
If you have multiple policies, after enabling or disabling them, you need to always run {{Codeline|'''awall activate'''}} in order to update the iptables rules.


== Advanced configuration ==
== Advanced configuration ==


Assuming you have your {{Path|/etc/awall/optional/home-policy.json}} with your "Basic home firewall" settings, you could choose to modify that file to test the below examples.
Assuming you have your {{Path|/etc/awall/optional/home-policy.json}} with your "Basic home firewall" settings, you could choose to modify that file to test the below examples. You could also create new files in {{Path|/etc/awall/optional/}} for testing some of the below examples.


{{Tip|You could also create new files in {{Path|/etc/awall/optional/}} for testing some of the below examples}}
AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. '' in the file {{Path|/usr/share/awall/mandatory/services.json}})''
 
{{Note|If you are adding the sample content given in this section to an already existing policy file, then make sure you add "," signs where they are needed!}}


=== Logging ===
=== Logging ===
Line 107: Line 109:
You could add the following row to the "policy" section in your ''Policy'' file in order to see the dropped packets.
You could add the following row to the "policy" section in your ''Policy'' file in order to see the dropped packets.
<pre>{ "in": "inet", "out": "loc", "action": "drop" }</pre>
<pre>{ "in": "inet", "out": "loc", "action": "drop" }</pre>
{{Note|If you are adding the above content to an already existing file, then make sure you add "," signs where they are needed!}}


=== Port forwarding ===
=== Port forwarding ===


Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet".<br>
Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet".<br>
With Shorewall you would have a rule like this in your {{Path|/etc/shorewall/rules}}:
With Shorewall you would have a rule like this in your {{Cat|/etc/shorewall/rules|<nowiki>#ACTION  SOURCE  DEST              PROTO  DEST PORT(S)   SOURCEPORT(S)   ORIGINALDEST
<pre>
DNAT    inet    loc:192.168.1.10  tcp    80</nowiki>}}
#ACTION  SOURCE  DEST              PROTO  DEST   SOURCE    ORIGINAL
#                                          PORT(S) PORT(S)   DEST
DNAT    inet    loc:192.168.1.10  tcp    80
</pre>


Lets configure our AWall ''Policy'' file likewise by adding the following content.
Lets configure our AWall ''Policy'' file likewise by adding the following content.
Line 139: Line 135:
* "variable" section where we specify some IP-addresses
* "variable" section where we specify some IP-addresses
* "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)
* "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)
{{Note|If you are adding the above content to a already existing file, then make sure you add "," signs where they are needed!}}
{{Tip|AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. ''(see {{Path|/usr/share/awall/mandatory/services.json}})''}}


If you need to forward to a different port (e.g. 8080) you can do:
If you need to forward to a different port (e.g. 8080) you can do:
Line 160: Line 154:
   }
   }
</pre>
</pre>
{{Note|If you are adding the above content to a already existing file, then make sure you add "," signs where they are needed!}}


=== Inherit services or variables ===  
=== Inherit services or variables ===  
Line 185: Line 178:


== See also ==
== See also ==
* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
* [[Zero-To-Awall]]
* [[Zero-To-Awall]]
* [https://www.cyberciti.biz/faq/how-to-set-up-a-firewall-with-awall-on-alpine-linux/ How To Set Up a Firewall with Awall on Alpine Linux]
* [https://www.cyberciti.biz/faq/how-to-set-up-a-firewall-with-awall-on-alpine-linux/ How To Set Up a Firewall with Awall on Alpine Linux]


[[Category:Firewall]]
[[Category:Firewall]]

Latest revision as of 16:56, 24 January 2026

This page shows how to configure Alpine Wall(awall) as compared to Shorewall firewall. This comparison is meant to help readers who are familiar with Shorewall learn AWall. Awall users should follow the AWall configuration examples. Use the Shorewall examples as contextual references, or ignore them, if unfamiliar with Shorewall.

Zero-To-Awall howto page is meant for users with no firewall experience and Alpine Wall User Guide is the official source for details about the syntax.

Installation

Install the awall package by running the following command:

# apk add iptables awall

Note that awall requires iptables but works with both backends nftables and legacy iptables. It does not interact with nftables directly.

Configuration

The easier method for performing initial steps for running awall:

# awall activate

The above command has special handling for the first run, when firewall is not yet enabled in the kernel. It performs the below manual steps and also updates the default runlevel and files in /etc/conf.d

Use the below commands for performing initial setup manually.

  • To update /etc/iptables:

    # awall translate

  • To start the OpenRC services for iptables and load modules and rules for IPv4 and IPv6

    # rc-service iptables start # rc-service ip6tables start

Configuration files

Your Alpine Wall configuration files go in /etc/awall/optional. From version 0.2.12 and later, Awall will look for Policy files in both the former and /usr/share/awall/optional Each such file is called a Policy.

You may have multiple Policy files. It is useful to have separate files for eg. HTTP, FTP, etc.

The Policy(s) can be enabled or disabled by using the command:

# awall [enable|disable]

An AWall Policy can contain definitions of:

  • variables (like /etc/shorewall/params)
  • zones (like /etc/shorewall/zones)
  • interfaces (like /etc/shorewall/interfaces)
  • policies (like /etc/shorewall/policy)
  • filters and NAT rules (like /etc/shorewall/rules)
  • services (like /usr/share/shorewall/macro.HTTP)

Basic home firewall configuration

The examples below show how to configure a basic home firewall using AWall. Note that AWall Policy files differ substantially from Shorewall's policy files in syntax and layout.

Shorewall configuration

Let's suppose you have the following Shorewall configuration files in /etc/shorewall/, which you want to convert to a configuration for AWall.

Contents of /etc/shorewall/zones

inet ipv4 loc ipv4

Contents of /etc/shorewall/interfaces

inet eth0 loc eth1

Contents of /etc/shorewall/policy

fw all ACCEPT loc inet ACCEPT all all DROP

Contents of /etc/shorewall/masq

eth0 0.0.0.0/0

AWall configuration

The equivalent AWall configuration that does the same thing as the above Shorewall example is given below.

Create a new file called /etc/awall/optional/home-policy.json and add the following content

Contents of /etc/awall/optional/home-policy.json

{ "description": "Home firewall", "zone": { "inet": { "iface": "eth0" }, "loc": { "iface": "eth1" } }, "policy": [ { "in": "_fw", "action": "accept" }, { "in": "loc", "out": "inet", "action": "accept" } ], "snat": [ { "out": "inet" } ] }

The above configuration will:

  • Create a description of your Policy
  • Define zones
  • Define policy
  • Define snat (to masqurade the outgoing traffic)

snat means "source NAT". It does not mean "static NAT".

Tip: AWall has a built-in zone named "_fw" which is the "firewall itself". This corresponds to the Shorewall "fw" zone.

Activating/Applying a Policy

After saving the Policy you can run the following commands to activate your firewall settings.

To listing available 'Policy(s)'

# awall list

To enable the 'Policy' created in the previous section:

# awall enable home-policy

To generate firewall configuration from the 'Policy' file and enable it i.e start the firewall:

# awall activate

If you have multiple policies, after enabling or disabling them, you need to always run awall activate in order to update the iptables rules.

Advanced configuration

Assuming you have your /etc/awall/optional/home-policy.json with your "Basic home firewall" settings, you could choose to modify that file to test the below examples. You could also create new files in /etc/awall/optional/ for testing some of the below examples.

AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. in the file /usr/share/awall/mandatory/services.json)

Note: If you are adding the sample content given in this section to an already existing policy file, then make sure you add "," signs where they are needed!

Logging

AWall will (since v0.2.7) automatically log dropped packets.

You could add the following row to the "policy" section in your Policy file in order to see the dropped packets. 

{ "in": "inet", "out": "loc", "action": "drop" }

Port forwarding

Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet".

With Shorewall you would have a rule like this in your

Contents of /etc/shorewall/rules

#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCEPORT(S) ORIGINALDEST DNAT inet loc:192.168.1.10 tcp 80

Lets configure our AWall Policy file likewise by adding the following content. 

  "variable": {
    "APACHE": "192.168.1.10",
    "STATIC_IP": "1.2.3.4"
    },

  "filter": [
    { "in": "inet", 
      "dest": "$STATIC_IP", 
      "service": "http", 
      "action": "accept", 
      "dnat": "$APACHE" 
      }
    ]

As you can see in the above example, we create a

  • "variable" section where we specify some IP-addresses
  • "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)

If you need to forward to a different port (e.g. 8080) you can do: 

"dnat": [
  {"in": "inet", "dest": "$STATIC_IP", "to-addr": "$APACHE", "service": "http", "to-port": 8080 }
]

Create your own service definitions

Note: You can not override a "service" definition that comes from /usr/share/awall/mandatory/services.json

You can add your own service definitions into your Policy files: 

"service": {  
  "openvpn": { "proto": "udp", "port": 1194 }
  }

Inherit services or variables

You can import a Policy into other Policy files for inheriting services or variables definitions: 

"import": "myfirewall"

Customize policy loading order

By default policies are loaded on alphabetical order. The load order can be changed with the keywords "before" and "after": 

"before": "myfirewall"
"after": "someotherpolicy"

Troubleshooting

If you end up in some kind of trouble, you might find some commands useful when debugging:

awall # (With no parameters) Shows some basic help about awall application awall dump # Dump definitions like zones and variables iptables -L -n # Show what's in iptables

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=How-To_Alpine_Wall&oldid=31985"