/ README.markdown
README.markdown
1 2 Easy Firewall Script 3 ==================== 4 5 Ever wanted a nifty firewall but have no time to learn the Linux Netfilter interface? This script will do the work. 6 7 Features 8 -------- 9 10 * IPv4 support 11 * Optional IPv6 support 12 * Ping throttling, or Ping disable 13 * Optional SSHGuard support 14 * Avoiding many types of port scans 15 * Logging for Port Scan detection 16 * Optional Multiple Port Knocking 17 * Optional Multi-home support 18 * Optional trusted interface specification 19 20 Invocation 21 ---------- 22 23 Configuration is a single command line invocation. With no arguments, the firewall will block all incoming connections. 24 25 To display a help message: 26 27 iptabs --help 28 29 To allow SSH over IPv4 and IPv6: 30 31 iptabs --enable-tcp ssh 32 33 By default pings are throttled to protect from flooding. To disable pings completely: 34 35 iptabs --drop-ping 36 37 By default ports allowed with IPv4 are also allowed with IPv6. To disable IPv6: 38 39 iptabs --drop-ipv6 40 41 But really, IPv6 is coming, try to be ready for it. 42 43 Services can be specified by name or number. Service names must match the information in `/etc/services`. Most Linux distributions come with a fairly complete list. 44 45 To enable a list of services, i.e. SSH on port 22, HTTP on port 80 and HTTPS on port 443 46 47 iptabs --enable-tcp ssh,www,https 48 49 UDP services can also be enabled: 50 51 iptabs --enable-udp echo 52 53 Any combination of TCP and UDP ports can be specified: 54 55 iptabs --enable-tcp ssh,ftp,ftp-data --enable-udp tftp 56 57 Multiple interfaces are supported via the `--interface` option. The interface will take effect for rules specifed after it. As a common example, assume `eth0` is the private network, and `eth1` is the public network. SSH should be allowed only on the private interface, but http and https should be allowed on all interfaces. 58 59 iptabes --interface eth0 --enable-tcp ssh --interface all www,https 60 61 Or, since `--interface all` is the default: 62 63 iptabes --enable-tcp http,https --interface eth0 --enable-tcp ssh 64 65 No validation is done to the interface specifier, so watch your output carefully, iptables and ip6tables will produce an error if the interface specifier is not correct. 66 67 If SSHGuard is installed, enable support for it: 68 69 iptabs --sshguard 70 71 If fwknop server support is desired on the server, enable it: 72 73 iptabs --fwknop 74 75 Note that using fwknop as a client requires no special support. 76 77 By default SYN protection is enabled, XMAS packets are dropped, NULL packets are dropped, and FIN scans are logged for programs like PSAD. Any of these can be optionally disabled. 78 79 To dump the netfilter commands to a file: 80 81 iptabs --dump-to netfilter.sh 82 83 This will write the commands to the file `netfilter.sh` instead of executing them. This is particularly handy on servers that do not have Perl installed. 84 85 Port Knocking 86 ------------- 87 88 Four part port knocking can also be enabled. Since it is Netfilter only, no cryptographic or stealth support is available. Try something like fwknop for that. 89 90 To enable port knocking to open SSH via the sequence 444, 333, 222, 111: 91 92 iptabs --knock ssh:444:333:222:111 93 94 To connect via SSH from another computer, first connect something to port 444, then port 333, then 222, then 111, then open the SSH connection. Several programs are available for this purpose, Google is your friend. 95 96 Each service can have its own port knock sequence. Remember not to enable SSH via `--enable-tcp` if port knocking is set up for it. 97 98 If some sort of external port scan detector is in use port knocking can trigger it. If this occurs, disable port knock logging: 99 100 iptabs --knock ssh:444:333:222:111 --no-knock-log 101 102 Specified by Network/Host 103 ------------------------- 104 105 A list of allowed ports can also be specified by a network or host string. For example, to allow SSH only from the 192.168.1.0 network: 106 107 iptabs --by-spec 192.168.1.0/24:tcp:ssh 108 109 Multiple ports may be specified: 110 111 iptabs --by-spec 192.168.1.0/24:tcp:ssh,http,443 112 113 Multiple invocations of `--by-spec` are allowed. The traffic is subject to the other rules, such as SSHGuard and port scan detection. 114 115 Trusted Interface 116 ----------------- 117 118 Trusted interfaces can be marked via `--trusted-iface` with a single interface, or a comma separated list of interfaces. The loopback interface is automatically marked as trusted, so do not bother adding it with this option. 119 120 Example of a single trusted interface: 121 122 iptabs --trusted-iface eth1 123 124 Example of multiple trusted interfaces: 125 126 iptabs --trusted-iface eth1,eth2,eth4 127 128 NAT/IPSec 129 --------- 130 131 IPSec and NAT are supported, in any combination. 132 133 To enable NAT from private network on eth0 to public eth1 134 135 iptabs --nat eth0:eth1 136 137 To enable IPSec tunneling 138 139 iptabs --ipsec 140 141 To enable IPSec tunneling with NAT on the private network (Note the reversal of public eth1 and private eth0) 142 143 iptabs --ipsec --nat eth1:eth0 144 145 For strongswan with NAT 146 147 iptabs --ipsec --nat eth1:eth0 --enable-udp 500,4500 148 149 Untrusted Networks/Addresses 150 ---------------------------- 151 152 Problematic networks or hosts can be blacklisted. Multiple hosts or networks may be specified with each invocation. IPv4 and IPv6 are both supported. 153 154 For example, some spammer is throwing traffic at the mail server from 192.168.1.1 155 156 iptabs --blacklist 192.168.1.1/32 157 158 Or the spammer controls a whole network 159 160 iptabs --blacklist 192.168.1.0/24 161 162 To block multiple combinations of hosts and networks use commas 163 164 iptabs --blacklist 192.168.1.2/32,192.168.2.0/24,10.0.0.0/8 165 166 The black list may be stored in a file, one per line, in CIDR notation as above. The file may have blank lines or comments. Comments are any line starting with a pound sign. 167 168 iptabs --blacklist-file blacklist.txt 169 170 This is hardly practical for spam blocking, but it is useful in other scenarios. 171 172 The blacklist chain is dynamic, so it may be modified without recreating the entire firewall. To easily add a host or network 173 174 iptabs --badguy 192.168.1.5/32 175 176 The bad guy option can also take multiple hosts and networks separated by commas. This is for use from some monitoring software that detects bad things, such as a root login attempt on a server that does not allow root to login directly. 177 178 A file with a list of addresses and/or networks to block can be specified. The format is the same as for the blacklist file option. 179 180 iptabs --badguy-file list.txt 181 182 Blacklisting can also use IPSet for faster lookups. This option should be used if a large blacklist table is expected. 183 184 iptabs --use-set --blacklist 192.168.1.1/32 185 186 The `--blacklist` option need not be present, using `--use-set` will create an empty set ready to be filled dynamically. 187 188 Make sure to specify that IPSet is in use when adding dynamically. 189 190 iptabs --use-set --badguy-file list.txt 191 192 Do *NOT* mix IPset and plain blocking. Although this will probably work it will make maintenance difficult. 193 194 The IPSet syntax changed not too long ago, so be sure to use the newest version available. For example, Debian 6.0.6 does not have an up to date version, and the kernel module must be built by hand. 195 196 Saving IPSet chains persistently does not appear to be present in a lot of distros. On Debian or Ubuntu based systems try the included iptables-persistent file. 197 198 DOS/DDOS Protection 199 ------------------- 200 201 Not exactly protection, but it might help. Enable with 202 203 iptabs --throttle 20 204 205 The number used is the limit per minute for new connections. The burst rate for new connections is four times the specified limit per minute. 206 207 iptabs --est-throttle 40 208 209 The number used is the limit per second for established connections. The burst rate for established connections is two times the specified limit per second. 210 211 OUTPUT Chain Processing 212 ----------------------- 213 214 Normally the OUTPUT chain is set to send all packets, and this should be the default for a desktop or laptop. In the case of a server the OUTPUT chain probably should be filtered. 215 216 *Great care should be used with this option.* The trusted interface mechanism will apply to the OUTPUT chain as well. The chain will also respect the blacklist and SSHGuard (if enabled). 217 218 iptabs --output-tcp ssh,http,443,8000-8999 --enable-udp 53 219 220 This will trigger output filtering, enable outgoing connections to SSH, HTTP, HTTPS, and the range 8000 through 8999. Also allowing DNS lookups through UDP port 53 (note that the inbound DNS is not enabled, therefoe DNS will fail). 221 222 iptabs --enable-tcp ssh --trusted-iface eth1 --outforce 223 224 This will configure a typical "jump server" that can receive SSH, but allow anything in or out of eth1. Note that attempting to SSH out on any other interface (eth0) will fail. the `--outforce` option will trigger OUTPUT chain processing without enabling any outbound services. 225 226 The `--outspec` option will specify rules just like --by-spec for the output chain. 227 228 Load Balancing Cluster Support 229 ------------------------------ 230 231 Rules for cluster support can be added. 232 233 The minimum specification consists of a virtual IP, number of nodes in the cluster, local node number, and the interface: 234 235 iptabs --interface eth0 --cluster-ip 10.1.1.10 --cluster-nodes 10 --cluster-local 3 --cluster http 236 237 The `--cluster` option must be last. It takes a list of ports or services separated by commas. Ranges are not allowed. 238 239 Optionally the virtual MAC and hash type may be specified: 240 241 iptabs --interface eth0 --cluster-ip 10.1.1.10 --cluster-nodes 10 --cluster-local 3 --cluster-mac aa:bb:cc:dd:ee --cluster-hashmode sourceip-sourceport --cluster http 242 243 The option `--cluster-mac` defaults to `01:02:03:04:05:06` and the option `--cluster-hashmode` defaults to `sourceip` 244 245 246 Multiple cluster specifications are allowed, but this is not recommended. 247 248 iptabs --interface eth0 --cluster-ip 10.1.1.10 --cluster-nodes 10 --cluster-local 3 --cluster http,https --interface eth1 --cluster-ip 10.1.2.10 --cluster-nodes 10 --cluster-local 3 --cluster-mac aa:bb:cc:dd:ee --cluster http,https 249 250 This is far easier using `--file` (see **Firewall Files** below for details) 251 252 # Clustering web server 253 interface eth0 254 enable-tcp http,https 255 cluster-ip 10.1.1.10 256 cluster-nodes 10 257 cluster-local 3 258 cluster http,https 259 260 IPv6 addresses are acceptable with `--cluster-ip` but this is not well tested. 261 262 **CAVEATS** 263 264 * The service list specified must also be allowed by the firewall itself. This is probably best done **after** the interface specification. See the example above. 265 * Neither failover nor recovery is triggered at the firewall level. 266 * The virtual IP address must be assigned to the device (typically as an alias), this is not done in the code. 267 * No state information is balanced, this must be done by the application layer. 268 * Do not use hostnames instead of IP addresses for `--cluster-ip` 269 270 Firewall Files 271 -------------- 272 273 The firewall tool can read firewall commands from a file instead of the command line. Commands can appear with or without the leading dashes (the command line can do this too, try it!). Comments and blank lines are ignored. A comment is a line that starts with a pound sign. 274 275 Here is an example firewall file: 276 277 # Web server firewall 278 sshguard 279 enable-tcp ssh,http,https 280 blacklist 172.168.0.0/16,10.0.0.0/8 281 282 This is equivalent to the command line 283 284 iptabs --sshguard --enable-tcp ssh,http,https --blacklist 172.168.0.0/16,10.0.0.0/8 285 286 Enjoy! 287 288 - - - 289 290 About 291 ----- 292 293 This is a rewrite in ruby. The original perl script can be found at http://github.com/john-nanney/iptabs