| Rev | Author | # | Line |
|---|---|---|---|
| 26 | JamieCurtis | 1 | To obtain the latest development copy go to [GitHub|http://github.com/jimmyish/bearwall]. If you want a released version, go to the ~GitHub download page [here|http://github.com/jimmyish/bearwall/downloads] |
| 21 | JamieCurtis | 2 | |
| 3 | The firewall logs, and by default, syslog will put this on the screen. You can turn that off using dmesg(8). Specifically, you want to type dmesg -n 1. Or edit /etc/syslog.conf to put all the logging on another console. Firewalls shouldn't have monitors anyway. :) | ||
| 4 | |||
| 26 | JamieCurtis | 5 | If you wish to build a debian package for the firewall (one may already exist in a Hoiho repository someday) check out the debian directory from [here|http://github.com/jimmyish/bearwall-debian] into the copy you got above. |
| 21 | JamieCurtis | 6 | |
| 7 | ---- | ||
| 8 | !!!How to build and install the package | ||
| 9 | |||
| 10 | Use a prebuild debian (or ubuntu) package if you can ! | ||
| 11 | |||
| 12 | If you can't, once you have got the latest development copy, just run | ||
| 13 | <verbatim> | ||
| 14 | make install | ||
| 15 | </verbatim> | ||
| 16 | This will put things in the following places. By default the configuration lives in <tt>/usr/local/etc/linuxserver-firewall</tt>, the executable in <tt>/usr/local/sbin</tt> and rulsets live in <tt>/usr/local/share/linuxserver-firewall/ruleset.d</tt> | ||
| 23 | JamieCurtis | 17 | |
| 18 | Consider altering the default locations inside the <tt>Makefile</tt> before building if you want them to be in a different location. | ||
| 21 | JamieCurtis | 19 | |
| 20 | ---- | ||
| 21 | !!!How it works | ||
| 22 | |||
| 23 | The main engine is a script called "<tt>firewall</tt>". When you run it it sets up some chains, and runs each script in "<tt>hosts.d/*</tt>", then each script in "<tt>interfaces.d/*.if</tt>". The "<tt>ruleset.d/*</tt>" directory is used for customised rulesets, the standard scripts come with a whole heap. Theres also a support directory, but this is for internal use and shouldn't be needed. | ||
| 24 | |||
| 25 | !!The <tt>hosts.d</tt> directory | ||
| 26 | This is like the <tt>interfaces.d</tt> directory, except it's not limited per interface. This is useful if you wish to provide rules for all packets on all interfaces (eg: TypeOfService munging) or if you want to have rules that effect a host no matter which interface packets arrive/leave by. This directory doesn't get used much, but the support is there should you want it :) | ||
| 27 | |||
| 28 | !!The <tt>interfaces.d</tt> directory | ||
| 29 | This has one file per interface, the file is named after the interface with "<tt>.if</tt>" appended to it, for instance "<tt>eth0.if</tt>". Each file specifies the rules for that interface. ${if} is an environmental variable which holds the current interface name. Several chains exist for each interface: | ||
| 30 | ;${if}-in: Used by all packets entering by this interface for this host only. | ||
| 31 | ;${if}-out: Used by all packets leaving by this interface for this host only. | ||
| 32 | ;${if}-forward-in: Used by packets coming IN this interface that aren't destined for this host itself. | ||
| 33 | ;${if}-forward-out: Used by packets going OUT an interface that aren't originated by this host itself | ||
| 34 | ;${if}-postrouting-out: Used by packets that are leaving this interface after routing has taken place. | ||
| 35 | ;${if}-prerouting-in: Used by packets that have entered this interface before routing has taken place. | ||
| 36 | |||
| 37 | eg | ||
| 38 | * Dropping port 80 on forward-in on ppp0 will disallow people on the internet to connect to port 80 internally | ||
| 39 | * Dropping port 80 on forward-out on ppp0 will disallow people internally from connecting out to the internet on port 80 | ||
| 40 | |||
| 41 | You could use "${IPTABLES} --append ${if}-in ..." to add the rules for this interface, but because this is so common there is a function to do it for you called apply_policy. you use it like: | ||
| 42 | apply_policy in .... | ||
| 43 | or | ||
| 44 | apply_policy out .... | ||
| 45 | and it will correctly add the --append ${if}- for you and use the correct table too so you don't have to remember if it's the mangle, filter or nat table :) | ||
| 46 | |||
| 47 | Now, you often have a lot of rules that are common between interface, and are even common between firewall installations, for instance some rules that deny all incoming TCP connections but allow outgoing TCP connections. These are stored in the ruleset.d/ directory (discussed later). These firewall "fragments" can be loaded on the fly automatically and used as targets. There is a neat little wrapper around this that you will probably use for almost all your firewalling rules called "policy". policy takes two (or more) arguments, the first is the chain name as you would provide to "apply_policy" and the second is the target, the remaining arguments are passed directly to iptables and can be used for more filtering. | ||
| 48 | some examples: | ||
| 24 | JamieCurtis | 49 | |
| 50 | <tt>policy in tcp-strict</tt> | ||
| 51 | |||
| 21 | JamieCurtis | 52 | will load the "tcp-strict" ruleset from the ruleset.d directory, and then issue a iptables rule such as: |
| 24 | JamieCurtis | 53 | |
| 54 | <tt>/sbin/iptables --table filter --append ${if}-in --jump tcp-strict</tt> | ||
| 55 | |||
| 21 | JamieCurtis | 56 | policy will not load a ruleset twice if it's used twice, and will not load rulesets that aren't used to save memory. policy is also smart enough to know about built in rules and some aliases that can be used to make things more clear. |
| 57 | |||
| 24 | JamieCurtis | 58 | __name__ | |
| 59 | __aliases__ | ||
| 60 | ACCEPT | | ||
| 61 | ALLOW, PERMIT | ||
| 62 | DROP | | ||
| 63 | DENY, BLACKHOLE | ||
| 64 | MASQUERADE | | ||
| 65 | MASQ* | ||
| 66 | |||
| 67 | since policy uses <tt>--append</tt> you just list the rules you want for an interface one after another. A ruleset for eth0 might look like: | ||
| 68 | <verbatim> | ||
| 21 | JamieCurtis | 69 | policy in ACCEPT |
| 70 | policy out ACCEPT | ||
| 71 | policy forward-in ACCEPT | ||
| 72 | policy forward-out ACCEPT | ||
| 24 | JamieCurtis | 73 | </verbatim> |
| 21 | JamieCurtis | 74 | |
| 75 | You should only need to use "policy" in the interfaces.d/ directory. In most firewalls I put in place policy is the only command in the interfaces.d directory (sometimes I have a for loop if I've got a range of ports I want to do something with for instance). | ||
| 76 | |||
| 77 | There are also interface features which you can specify in these files. These are /proc entries in /proc/sys/net/ipv4/conf/${if}/*. there is an alias to manage these for you "if_feature". For instance: | ||
| 78 | if_feature rp_filter 1 # enable reverse path filtering for this interface | ||
| 79 | if_feature accept_redirects # accept ICMP redirects on this interface | ||
| 80 | etc... | ||
| 81 | |||
| 22 | JamieCurtis | 82 | !!<tt>classes.d</tt> |
| 21 | JamieCurtis | 83 | There are several example class files in CVS. There are several standard interface "types" (eg: "external", "internal", "dmz" etc) and then you symlink interfaces to these. eg: |
| 24 | JamieCurtis | 84 | <verbatim> |
| 21 | JamieCurtis | 85 | ln -s external eth0.if |
| 86 | ln -s internal eth1.if | ||
| 87 | ln -s dmz eth2.if | ||
| 24 | JamieCurtis | 88 | </verbatim> |
| 21 | JamieCurtis | 89 | |
| 90 | There are two new commands now that should appear as the very first rule in a interface definition. | ||
| 24 | JamieCurtis | 91 | <tt>on_startup</tt>: This means that this interface definition will be run always from the main firewall script "<tt>firewall</tt>" |
| 92 | <tt>on_demand</tt>: This interface definition will only be run if the interface is already up | ||
| 21 | JamieCurtis | 93 | |
| 94 | Also new main scripts were added: | ||
| 95 | ;fw-ipup: This brings up only one interface and presumes that the main "firewall" script has been run to set everything up. It takes one or two parameters. The first parameter is the interface name (such as eth0, eth1) and the second is an optional name for the name of the interface definition to read. For instance a wireless interface might use "home" or "work", so you could type: | ||
| 96 | ifup eth0 home | ||
| 97 | ;fw-ipdown: This removes all the firewalling rules to do with an interface. Dynamic rulesets that are loaded by that interface are __not__ removed, however won't be executed by packets so only a very slight memory overhead is kept. | ||
| 98 | |||
| 22 | JamieCurtis | 99 | !!the <tt>ruleset.d</tt> directory |
| 21 | JamieCurtis | 100 | This is used to store fragments of a firewall, each fragment does something simple and can be used by interface.d files. rulesets have the form of "''name''.rule". rulesets don't have much in the way of helper functions. The first line of them should be: |
| 101 | . support/ruleset.functions | ||
| 102 | the environmental variable ${RULE} will be set to the rule name (basically the name of the file less the ".rule" extension, and the environmental variable ${IPTABLES} will be set to the path to the iptables executable. There are also "polite_reject" and "polite_drop" which will be discussed later. | ||
| 103 | |||
| 104 | Heres a list of the various included rulesets and what they do: | ||
| 105 | ;classify: This sets the various TypeOfService bits in the IP header based on the port (protocol) of the packet. | ||
| 106 | ;icmp-strict: Ignore ICMP not due to an already established connection. This means that ping, and PathMaximumTransferUnitDiscovery works, but someone pinging us will fail. Kinda a bit of overkill, but it's here for those that are scared of this kind of thing. | ||
| 107 | ;icmp-trust: Allow all ICMP | ||
| 108 | ;martians: drop any packets that are from or to an internal IP range as specified in rfc1918. useful for external interfaces. | ||
| 109 | ;multicast-strict: Drops pretty much all multicast | ||
| 110 | ;multicast-trust: Allows some multicast through. | ||
| 111 | ;tcp-strict: Allows only outgoing TCP connections, rejects the rest, except for port 80 where it drops all packets (slowing down the still numerous codered hits). | ||
| 112 | ;tcp-trust: Allows all TCP except to some well known ports that it shouldn't have access to (eg: linuxconf, nfs and portmap etc). Useful for an interface that is connecting to another department that you trust and want traffic to flow to and from, but they don't need any of your sensitive services, so if they get compromised hopefully the attacker won't get the opertunity to compromise you too. | ||
| 113 | ;udp-strict: Disallows incoming UDP that isn't part of an already established "connection" (ie: a reply from a packet that was originated here) | ||
| 114 | ;udp-trust: Disallows incoming UDP to potentially dangerous ports (NFS, Portmap, tftp etc) | ||
| 115 | |||
| 25 | JamieCurtis | 116 | Most of these rules are configurable and rather obvious if you edit them. |
| 21 | JamieCurtis | 117 | |
| 118 | !!Misc commands | ||
| 119 | There are also some misc commands that can be used from both interfaces.d/ and ruleset.d/ | ||
| 120 | |||
| 121 | ;polite_reject: requires at least one argument, the first is the rule to append to, the rest is any other iptables options that may be used (eg: limiting it by port). polite_reject then rejects the packets ratelimited to 5/s and logs them at a rate of 2/s, rendering floods less effective. All packets that aren't rejected are dropped. | ||
| 122 | |||
| 123 | ;polite_drop: same as polite_reject but only logs at 2/s and doesn't send back reject messages. This is useful for rules where you know that the rejects aren't going to be used (for example if the source address is a martian) or it could be downright harmful (eg: the packet was directed towards a multicast or broadcast address). | ||
| 25 | JamieCurtis | 124 | |
| 125 | !! Restrictions on the use of rulesets in forwarding | ||
| 126 | |||
| 127 | Currently (as of version 1.0) there is a restriction in the use of ruleset in the forward-in of an interface. If a ruleset ACCEPT's a packet on the fw-in of an interface, the packet will ''__NOT__'' be checked by the fw-out of the outgoing interface. If this confuses you, just never use any rulesets that ACCEPT packets in the fw-in path. | ||
| 21 | JamieCurtis | 128 | |
| 129 | !!FAQ | ||
| 130 | ;__Q__:Why do I get lots of messages saying "End of ''something''" on my screen/in my syslog | ||
| 131 | ;__A__:You don't have a catch all rule for something in one of your class files. Look at the syslog messages carefully and see what interface they are dealing with and which rule you are missing. | ||
| 132 | |||
| 133 | !!Wishlist features | ||
| 134 | These are all wishlist features which may or may not get implemented :) | ||
| 22 | JamieCurtis | 135 | * Renaming interfaces based on their category : "External0" "External1" "Internal1" "Internal2" etc - thusly when an interface comes up it is named by it's purpose. Useful for those machines that have 10+ interfaces and you can never remember which is which, also important when you have multiple ppp0, or VPN interfaces that may come up in any order (do you set the permissive rule on ppp0 or ppp1?) |
| 136 | ** 1. Superceded by a program whose name I forget which has a file of MAC->interfacenames and when run renames interfaces as required. Rather nifty. | ||
| 137 | ** 2. With ppp interfaces, bring them up with 'unit N' in the command line, and they will take on that number. Solves the problem nicely. You might need pppd 2.4.2. | ||
| 138 | * Some saner defaults : A simple default so if you run the script straight out of CVS it probably does what you want. Go get the deb if you need this. | ||
| 139 | * Use iptables-save and restore to speed shutdown/startup of script? : Not really worth the effort... | ||
| 140 | * Transparent support of ipv6 : Needs investigating | ||
| 141 | * Automatically load ip_nat_* modules : done |
lib/blame.php:177: Warning: Invalid argument supplied for foreach()