README.md 7.71 KB
Newer Older
Simon Bärlocher's avatar
Simon Bärlocher committed
1
2
# Ansible Role: Shorewall

3
4
[![Build Status](https://travis-ci.org/Myatu/ansible-shorewall.svg?branch=master)](https://travis-ci.org/Myatu/ansible-shorewall)

Simon Bärlocher's avatar
Simon Bärlocher committed
5
6
## Description

Mike Green's avatar
Mike Green committed
7
Ansible role which installs and configures [Shorewall](http://shorewall.org/) and Shorewall6.
Simon Bärlocher's avatar
Simon Bärlocher committed
8
9
10
11

## Installation

```
Mike Green's avatar
Mike Green committed
12
$ ansible-galaxy install Myatu.shorewall
Simon Bärlocher's avatar
Simon Bärlocher committed
13
14
15
16
```

## Requirements

Mike Green's avatar
Mike Green committed
17
18
Ansible version 2.0 or better.

19
20
21
22
23
## Role Handlers

Name | Description
--- | ---
`enable shorewall`, `enable shorewall6` | Enables and starts Shorewall / Shorewall 6
24
`restart shorewall`, `restart shorewall6` | Restarts Shorewall / Shorewall6
25

Simon Bärlocher's avatar
Simon Bärlocher committed
26
27
## Role Variables

Mike Green's avatar
Mike Green committed
28
29
30
31
32
33
34
35
36
37
*Note:* The Shorewall (IPv4) variables are prefixed by `shorewall_`, whereas the Shorewall6 (IPv6) variables are prefixed by `shorewall6_`.

Variable | Dictionary / Options
--- | ---
shorewall_package_state | "present", "latest", "absent".
shorewall_startup | "1" or "0"
shorewall_conf | *this variable uses standard option / value pairs*
shorewall_interfaces | `zone`, `interface`, `options`
shorewall_zones | `zone`, `type`, `options`, `options_in`, `options_out`
shorewall_policies | `source`, `dest`, `policy`, `log_level`, `burst_limit`, `conn_limit`
38
shorewall_rules | **sections**: `section`, **rules**: `rule`.  For each **rule**: `action`, `source`, `dest`, `proto`, `dest_port`, `source_port`, `original_dest`, `rate_limit`, `user_group`, `mark`, `connlimit`, `time`, `headers`, `switch`, `helper`, `when`
Mike Green's avatar
Mike Green committed
39
shorewall_masq | `interface`, `source`, `address`, `proto`, `ports`, `ipsec`, `mark`, `user`, `switch`, `original_dest`
40
shorewall_tunnels | `type`, `zone`, `gateway`, `gateway_zone`
Mike Green's avatar
Mike Green committed
41
42
43
shorewall_hosts | `zone`, `hosts`, `options`
shorewall_params | `name`, `value`

44

Mike Green's avatar
Mike Green committed
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
### shorewall_package_state - Shorewall package state

See the Ansible [package module](http://docs.ansible.com/ansible/package_module.html) information for more details. 

It allows you to control whether Shorewall and dependencies should be either installed (*"present"*), installed / upgraded to their most recent version (*"latest"*) or should be removed (*"absent"*).

### shorewall_startup - Shorewall startup behaviour

This updates the `/etc/default/shorewall` file's `startup` option to either enable (*"1"*) startup (using the `service` or `systemctl` commands) or disable it (*"0"*).

### shorewall_conf - Shorewall Configuration

Specify values for global Shorewall options in the `/etc/shorewall/shorewall.conf` file. See the Shorewall [shorewall.conf man page](http://shorewall.org/manpages/shorewall.conf.html) for more details.

Each shorewall.conf option may be written in lower-case, such as `ACCEPT_DEFAULT=none
` can be written as `accept_default: "none"` in the variables.

#### Example

```yaml
shorewall_conf:
  verbosity: "1"
  log_verbosity: "2"
  logfile: "/var/log/messages"
  blacklist: "\"NEW,INVALID,UNTRACKED\""
  blacklist_disposition: "DROP"
```

### shorewall_interfaces - Interfaces

Define the interfaces on the system and optionally associate them with zones in the `/etc/shorewall/interfaces` file. See the Shorewall [interfaces man page](http://www.shorewall.net/manpages/shorewall-interfaces.html) for more details.

#### Example

Simon Bärlocher's avatar
Simon Bärlocher committed
79
80
81
```yaml
shorewall_interfaces:
  - { zone: net, interface: eth0, options: "dhcp,tcpflags,logmartians,nosmurfs,sourceroute=0" }
Mike Green's avatar
Mike Green committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
```

### shorewall_zones - Zones

Declare Shorewall zones in the `/etc/shorewall/zones` file. See the Shorewall [zones man page](http://www.shorewall.net/manpages/shorewall-zones.html) for more details.

#### Example

```yaml
shorewall_zones:
  - { zone: fw, type: firewall }
  - { zone: net, type: ipv4 }
```

### shorewall_policies - Policies

Define high-level policies for connections between zones in the `/etc/shorewall/policies`. See the Shorewall [policy man page](http://www.shorewall.net/manpages/shorewall-policy.html) for more details.

#### Example
Simon Bärlocher's avatar
Simon Bärlocher committed
101

Mike Green's avatar
Mike Green committed
102
```yaml
Simon Bärlocher's avatar
Simon Bärlocher committed
103
104
105
106
shorewall_policies:
  - { source: "$FW", dest: all, policy: ACCEPT }
  - { source: net, dest: all, policy: REJECT }
  - { source: all, dest: all, policy: REJECT, log_level: info }
Mike Green's avatar
Mike Green committed
107
108
109
```

### shorewall_rules - Rules
Simon Bärlocher's avatar
Simon Bärlocher committed
110

Mike Green's avatar
Mike Green committed
111
112
113
114
Specify exceptions to policies, including DNAT and REDIRECT in the `/etc/shorewall/rules` file. See the Shorewall [rules man page](http://www.shorewall.net/manpages/shorewall-rules.html) for more details.

***WARNING***: Please be sure to include a rule for SSH on the correct port, to avoid locking Ansible - and yourself - out from the remote host.

115
116
117
118
119
#### Using the `when` conditional

An option specific to this role variable. and not part of Shorewall, is the `when` conditional. This allows a rule to be included only if the condition evaluates to True.

#### Examples
Mike Green's avatar
Mike Green committed
120
121

```yaml
Simon Bärlocher's avatar
Simon Bärlocher committed
122
123
124
125
126
127
128
129
shorewall_rules:
  - section: NEW
    rules:
    - { action: "Invalid(DROP)", source: net, dest: "$FW", proto: tcp }
    - { action: ACCEPT, source: net, dest: "$FW", proto: tcp, dest_port: ssh }
    - { action: ACCEPT, source: net, dest: "$FW", proto: icmp, dest_port: echo-request }
```

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
Using the `when` conditional:

```yaml
has_webserver: True

# And in a task:
#- name: Disable webserver rule
#  set_fact:
#    has_webserver: False

shorewall_rules:
  - section: NEW
    rules:
    - { action: "Invalid(DROP)", source: net, dest: "$FW", proto: tcp }
    - { action: ACCEPT, source: net, dest: "$FW", proto: tcp, dest_port: ssh }
    - { action: "HTTP(ACCEPT)", source: net, dest: "$FW", when: "{{ has_webserver }}" }

```


Mike Green's avatar
Mike Green committed
150
151
152
153
### shorewall_masq - Masquerade/SNAT

Define Masquerade/SNAT in the `/etc/shorewall/masq` file. See the Shorewall [masq man page](http://shorewall.org/manpages/shorewall-masq.html) for more details.

154
155
156
157
158
159
160
161
162
163
164
### shorewall_tunnels - Tunnels

Define VPN connections with endpoints on the firewall in the `/etc/shorewall/tunnels` file.  See the Shorewall [tunnels man page](http://shorewall.net/manpages/shorewall-tunnels.html) for more details.

#### Example

```yaml
shorewall_tunnels:
  - { type: ipsec, zone: net, gateway: "0.0.0.0/0", gateway_zones: "vpn1,vpn2" }
```

Mike Green's avatar
Mike Green committed
165
166
167
168
169
170
171
172
### shorewall_hosts - Hosts

Define multiple zones accessed through a single interface in the `/etc/shorewall/hosts` file. See the Shorewall [hosts man page](http://shorewall.org/manpages/shorewall-hosts.html) for more details.
 
### shorewall_params - Parameters

Assign any shell variables that you need in the `/etc/shorewall/params` file. See the Shorewall [params man page](http://shorewall.org/manpages/shorewall-params.html) for more details.
 
Simon Bärlocher's avatar
Simon Bärlocher committed
173
174
175
176
177
## Example Playbook

```yml
- hosts: all
  roles:
Mike Green's avatar
Mike Green committed
178
     - Myatu.shorewall
Simon Bärlocher's avatar
Simon Bärlocher committed
179
180
181
182
```

## Changelog

Mike Green's avatar
Mike Green committed
183
### v1.0.3
184

185
- Added: The `shorewall_rules` has an added option `when` for each rule, which acts similar to Ansible's `when` statement and allows rules to be conditional.
186
- Added: role variable `shorewall_tunnels` for use with VPNs.
187
- *Changed:* The generated `shorewall_rules` will now take into account the `?` prefix in sections (i.e. `?ESTABLISHED`), which was introduced at Shorewall version 4.6. If the Shorewall version installed is older than 4.6, this prefix will be omitted to avoid errors.
188

Mike Green's avatar
Mike Green committed
189
190
191
192
193
194
195
196
197
198
199
### v1.0

- Added: `ipset` as a package dependency;
- Added: role variable `shorewall_conf`, allowing each option in the shorewall.conf file to be defined;
- Added: role variable `shorewall_package_state` to set package state of Shorewall and dependencies;
- *Changed:* The default for `shorewall_interface` now detects the default network interface rather than fixed at `eth0` (though `eth0` is still a fall-back default);
- **Removed:** role variables: `shorewall_verbosity`, `shorewall_log_verbosity`.  Use the `shorewall_conf` role variable to configure these instead.




Simon Bärlocher's avatar
Simon Bärlocher committed
200
201
## Author

Mike Green's avatar
Mike Green committed
202
* [Michael Green](http://myatus.com)
Simon Bärlocher's avatar
Simon Bärlocher committed
203
204
205
206
207
208
* [Simon Bärlocher](https://sbaerlocher.ch)
* Farhad Shahbazi
* Sascha Biberhofer
 
## License

Mike Green's avatar
Mike Green committed
209
This project is under the MIT License. See the LICENSE file for the full license text.
Simon Bärlocher's avatar
Simon Bärlocher committed
210
211
212

## Copyright

Mike Green's avatar
Mike Green committed
213
214
215
- Copyright (c) 2017 Michael Green
- Copyright (c) 2016 Simon Bärlocher