Zero-To-Awall

Awall howto for dummies

This howto is aimed at users with no (or little) experience with iptables and other firewall frameworks (like Shorewall).

This howto is going to be split into 4 parts.

1. Defining our base json file which holds our zones and base policies.
2. Creating service policies.
3. Using aliases and custom services.
4. enabling and testing policies.

NOTE: please be aware that all configuration files are stored as JSON files. JSON is not a human friendly standard, for instance it does not support comments so you will have to move them outside of the json structure. Beginners should use a decent text editor with JSON highlight support which will make your life easier. Since recent versions of awall it is also possible to use yaml instead of json but this is out of the scope of this howto.

Creating the base

Creating zones depends on the function of your firewall. Is it installed on a endpoint (server) or will it act as a router and filter/forward. For this howto we assume you are going to setup a router and use NAT to forward services (ports) to different hosts on your network.

For each interface on router we will setup a zone and assign it a zone name. We do this by creating the following file: /etc/awall/private/base.json

{
  "description": "Base zones and policies",

  "zone": {
    "WAN": { "iface": "eth0" },
    "LAN": { "iface": "eth1" },
    "VPN": { "iface": "tun+" }
  },

  "policy": [
     { "in": "VPN", "action": "accept" },
     { "out": "VPN", "action": "accept" },
     { "in": "LAN", "action": "accept" },
     { "out": "LAN", "action": "accept" },
     { "in": "_fw", "action": "accept" },
     { "in": "_fw", "out":  "WAN" , "action": "accept" },
     { "in": "WAN", "action": "drop" }
  ],

  "snat": [ { "out": "WAN" } ],

  "clamp-mss": [ { "out": "WAN" } ]

}

Lets break this down into sections

description

The description is here just for reference and will be used by awall list.

zone

This is where our zones are defined. Zones are defined based on a interface and assigned a name to be used in your policies. In our example you can see that we have two real interfaces eth0 and eth1 and one or more virtual interfaces tun+ (the plus sign stands for any digit like tun0 tun1 and so on). In case you are installing awall on an endpoint (a server) then you will most probably not have the eth1 interfaces and can leave it out. In our example the tun+ interface is added as it is very commonly used like when using openvpn.

policy

These are our main policies. It will tell our firewall what to do with when a packet enters or leaves on of the zones (interfaces). You will notice a special _fw name which means the internal firewall itself (the local machine) which means the packet does not leave the firewall via another interface but should use one of the local services. you can see that we by default do not filter any package coming from or going to our VPN zone/interface. You could instead change the default action to drop all packets and create separate policies to allow specific traffic but this is out of the scope of this howto.

snat

Apply source nat for outgoing packets. This is only needed if your firewall acts as a router and traffic behind the router needs a modified source address (translate from local ip to public ip).

clamp-mss

https://github.com/alpinelinux/awall#mss-clamping-rules

Policies (services)

Now that we have the base firewall in place we can start to define specific policies so our services will be reachable from the outside world.\ By default we are blocking all traffic coming in on our WAN interface (action=drop). The first thing we want to open is our SSH port/service. To do this we need to create a new policy inside the "optional" directory. You could be wondering why the optional name, thats is because mandatory policies are stored in /usr/share/awall/mandatory and not to be touched and our optional policies can be enabled/disabled on the run. To add our SSH policies we create a new file: /etc/awall/optional/ssh.json

{
  "description": "Allow rate-limited SSH on WAN",

  "filter": [
    {
      "in": "WAN",
      "out": "_fw",
      "service": "ssh",
      "action": "accept",
      "conn-limit": { "count": 3, "interval": 20 }
    }
  ]
}

description

This is similar for any policy

Filter

This is the actual filter that is currently set to drop the packets arriving or leaving the interface.

in

The interface the packets arrive on, in this case its the WAN interface.

out

The interface the packets leave on, in this case its _fw which means it does not leave our firewall/device and is targeted at our local SSH service.

service

This is the service definition provided by awall or a custom service which we will discuss later on.

action

The action on the packet, this inverts the default action of drop and accepts the packets.

conn-limit

This is a special feature of our firewall/iptables to allow only a certain amount of packets in a certain amount of time. For more information please check our awall manual.