Commit 19a91a97 authored by Branko Mikić's avatar Branko Mikić
Browse files

Man page revised to reflect new additions and changes.

parent fab0e69a
......@@ -7,14 +7,28 @@ firewalls easily.
.SH
SYNOPSIS
ipturntables.sh [-4|-6]
[KERNEL_PARAMS param1,param2,...,paramN]
[PROBE_KERNEL_MODS mod1,mod2,...,modN] [RESET [default_policy]] [BASE_RULE_SET]
[ALLOW_SUBNETS on_link] [ALLOW_DHCP_CLIENT on_link] [ALLOW_LINK_LOCAL on_link] [ALLOW_SERVICE_DISCOVERY on_link] [ALLOW_TUNNEL mode on_link from_address]
[FORWARD_SUBNET subnet/mask to_link] [FORWARD_SUBNET_PROTECTIVE subnet/mask to_link] [FORWARD_PORT|FORWARD_ROUTING ip|link port(s) to_address[:to_port]]
[MAC_FILTER chain mac_address]
[POSTROUTING_MASQUERADE subnet/mask to_link]
[DEBUG_CHAIN chain_name] [REMOVE_RULES pattern]
ipturntables.sh [-4|-6] [-d]
[KERNEL_PARAMS param1,param2,...,paramN]
[PROBE_KERNEL_MODS mod1,mod2,...,modN]
[RESET [default_policy=ACCEPT|DROP|REJECT]]
[BASE_RULE_SET]
[ALLOW_DHCP on_link [client|server|both]]
[ALLOW_SUBNETS on_link]
[ALLOW_LINK_LOCAL on_link]
[ALLOW_MULTICAST_ADDRS on_link]
[ALLOW_SERVICE_DISCOVERY on_link]
[ALLOW_STATEFUL_PACKETS ip|link]
[ALLOW_TUNNEL mode on_link from_address]
[ALLOW_PORT|ALLOW_SERVICE port[,port,port,...] ip|link [tcp|udp]]
[FORWARD_SUBNET from_subnet/mask to_link]
[FORWARD_SUBNET_PROTECTIVE from_subnet/mask to_link]
[FORWARD_PORT|FORWARD_ROUTING ip|link port(s) to_address[:to_port] [tcp|udp]]
[MAC_FILTER chain mac_address]
[POSTROUTING_MASQUERADE subnet/mask on_link]
[DEBUG_CHAIN chain_name]
[REMOVE rule_regex_pattern]
[LIST [CHAIN]]
[LOG|NFLOG]
.SH DESCRIPTION
.B ipturntables.sh
......@@ -272,17 +286,90 @@ discovery of DLNA hosts. Usally these are services which should be run on
internal links on private subnets _only_. It's not recommended to allow service
discovery on a WAN interface.
.SS ALLOW_DHCP_CLIENT \fRlink
Allows a DHCP client request (Ports 67, 68 (IPv4) & 546, 547 (IPv6)) to pass on the desired link only. Is some cases this is necessary before calling ALLOW_SUBNET as that would require a fully configured IP address.
Another scenario is that providers may use dynamically created net prefixes for IPv6 on the WAN link. In order to get router & neighbour solicication working this rule allows the router himself to obtain a dhcp lease from a provider via link local only before the interface has acquired an IP address.
.SS ALLOW_DHCP \fRlink client|server|both
Allows a DHCP request (Ports 67, 68 (IPv4) & 546, 547 (IPv6)) to pass on the
desired link only. Is some cases this is necessary before calling ALLOW_SUBNET
as that would require a fully configured IP address.
.br
Another scenario is that providers may use dynamically created net prefixes for
IPv6 on the WAN link. In order to get router & neighbour solicication working
this rule allows the router itself to obtain a DHCP lease from a provider via
link local only before the interface has acquired an IP address.
.br
The mode specifies the allowed sequence of packets where 'client' only allows
to send requests and receive a DHCP response intended to obtain an IP address.
The 'server' mode allows to receive DHCP requests from a client and send a
response back and finally 'both' which allows the link to act as a client as
well as a server. The DHCP chain is now placed in the mangle table for early
processing.
.P
eg: ALLOW_DHCP_CLIENT ppp0
eg: ALLOW_DHCP ppp0 client
ALLOW_DHCP eth0 server
.P
.RS 2
Attention!
.br
It's not sufficient for a link to have just ALLOW_DHCP_CLIENT set as this allows DHCP client requests (on that interface) only. When the interface has acquired an IP address from it's DHCP server an ALLOW_SUBNET call is additionally necessary to allow traffic passing otherwise the interface is just allowed to retrieve an IP address but not using it.
On the other hand for a virtual WAN interface this may be even a requirement before allowing anything.
It's not sufficient for a link to have just ALLOW_DHCP set as this allows DHCP
client requests (on that interface) only.
.br
Especially DHCPv6 allows implicitly link local addresses on the corresponding
DHCP ports \fIonly\fR to make a DHCP handshake working even without calling
ALLOW_LINK_LOCAL function.
.br
When the interface has acquired an IP address from it's DHCP server an ALLOW_SUBNET
call is additionally necessary to allow traffic passing otherwise the interface is
just allowed to retrieve an IP address but not using it. On the other hand for a
virtual WAN interface this may be even a requirement before allowing anything.
.SS ALLOW_STATEFUL_PACKETS \fRip|link
It allows packets of state \fINEW\fR to leave over a router's local interface only
(and all IPs configured on it) and allows packets of \fIRELATED\fR and \fIESTABLISHED\fR
state back in but only for packets which were previously send from this interface and are
destined to an IP address of the given interface.
.br
In former versions of ipturntables the concept of a stateful firewall was simply
implemenented in the INPUT and OUTPUT chain for any interface that allows \fINEW\fR packets
to leave. This has been changed to have a more fine-grained control over a selection
of interfaces using stateful packet filtering. This is especially useful when a set
of multiple WAN interfaces is available but stateful packet filtering shouldn't
occur on all of them implicitly. Although \fIRELATED\fR and \fIESTABLISHED\fR packets are still
allowed to leave for any interface in the OUTPUT chain those packets can only get into
these \fIRELATED|ESTABLISHED\fR states by an interface which previously allowed to send a packet
with the \fINEW\fR state. So when there's no interface configured with ALLOW_STATEFUL_PACKETS
no packet of state \fINEW\fR will ever leave the machine. Therefore a call of ALLOW_STATEFUL_PACKETS
is now needed for any interface that should be able to send stateful traffic to the outer world.
.P
Stateful packet filtering can be achieved with layer 3 too by giving ALLOW_STATEFUL_PACKETS an
IP address argument instead of a link but be aware (!) that the behavior is different as the linux
kernel binds IP adresses to a host regardless of the interface it has been configured on!
.br
Using ALLOW_STATEFUL_PACKETS with an IP address argument implicitly allows the IP to send
stateful packets on \fIany\fR interface and that is intended (!)
.P
eg: ALLOW_STATEFUL_PACKETS eth1
ALLOW_STATEFUL_PACKETS ppp0
.P
Will allow eth1 and ppp0 to act as WAN interfaces with stateful packet filtering on each. Any
traffic on these is isolated and \fInot\fR mixed up meaning a stateful packet send from eth1
can't be received in the INPUT chain on ppp0 and vice versa.
.br
Let's assume your router's main IP is configured on another interface eg. eth0 with 10.1.1.1 address
and NAT masquerading is enabled for this address then even the router itself still can't send
stateful packets via eth1 or ppp0. This is good from a security standpoint but not always desired
as now the router can't provide any public services which in turn need to connect to public servers
on the internet eg. an NTP server (running at 10.1.1.1) trying to connect to it's public peers.
One solution would be to run the daemon with the IPs of eth1 or ppp0 to make it work. If this is
not desired for various reasons and the daemon must run on the internal IP and should be able to
communicate to the outer world it's possible to get around this by allowing stateful packets for
the 10.1.1.1 address.
.P
eg: ALLOW_STATEFUL_PACKETS 10.1.1.1
.P
.RS 2
Attention!
.br
This will allow 10.1.1.1 \fIonly\fR to send stateful packets on any interface regardless of other addresses
configured on eth0 interface.
.SS ALLOW_TUNNEL \fR"ipip|gre|sit" on_link from_address
Allows ipip, gre or sit bidirectional tunnel ethernet raw frame packets to
......@@ -297,6 +384,16 @@ logically can't be used on IPv6 firewalls.
.P
eg: ALLOW_TUNNEL sit eth2 2001:DB8::1
.SS ALLOW_MULTICAST_ADDRS \fRon_link [port,port,port,...]
Allows traffic destined to a multicast address to pass on the given link only.
If the optional port list argument is omitted any multicast traffic is allowed
to pass. This may not always be desirable to control specific multicast traffic
an optional list of allowed ports may be given to allow multicast traffic for the
given ports only.
.P
eg: ALLOW_MULTICAST_ADDRS eth0 (allows any multicast traffic)
ALLOW_MULTICAST_ADDRS eth0 5353,5355,1900,3707 (for usual ports like mDNS, LLMNR, UPNP or WSD)
.SS FORWARD_SUBNET \fRsubnet/mask destination_link
Allows any outbound traffic of the desired subnet to the desired
destination interface and allows only related and established packets back
......@@ -402,10 +499,10 @@ Attention!
iptables allows only a single ether address. So this function can't be used to filter raw ether packets
in long notation eg. ipip, grep or sit tunnel packets.
.SS REMOVE_RULES \fR"ID matching string"
.SS REMOVE \fR"rule_regex_pattern"
For a dynamic approach altering rules on the fly (eg. in (pre-|post)-up|down events this call removes any rule matching the given ID string in it's comment in \fIany\fR chain found (even in the nat table!). It may be possible that on such an operation some chains are left orphaned (with no rule referencing them anymore). To keep the rules table clean these chains are deallocated (removed) from the rules table completely.
.P
eg: REMOVE_RULES "ALLOW_SUBNETS on 0x0700a721a8d7"
eg: REMOVE "ALLOW_SUBNETS on 0x0700a721a8d7"
A protected IPv4 subnet has been forwarded and masqueraded on the eth1 interface in it's post-up event:
......@@ -438,19 +535,19 @@ Chain POSTROUTING (policy ACCEPT 230 packets, 14589 bytes)
By selecting the approriate part of the ID string the deletion scope can be managed. For only deleting the forwarding rules along with it's target chains the whole ID string is passed:
.RS 2
./ipturntables.sh -4 REMOVE_RULES "\fBFORWARD_SUBNET_PROTECTIVE eth1_0A0A0A0018_eth2\fR"
./ipturntables.sh -4 REMOVE "\fBFORWARD_SUBNET_PROTECTIVE eth1_0A0A0A0018_eth2\fR"
.RE
.P
Same goes for for removing only the masquerade rule:
.RS 2
./ipturntables.sh -4 REMOVE_RULES "\fBPOSTROUTING_MASQUERADE eth1_0A0A0A0018_eth2\fR"
./ipturntables.sh -4 REMOVE "\fBPOSTROUTING_MASQUERADE eth1_0A0A0A0018_eth2\fR"
.RE
.P
By narrowing the ID string all three rules and it's corresponding chains can be deleted at once:
.RS 2
./ipturntables.sh -4 REMOVE_RULES "\fBeth1_0A0A0A0018_eth2\fR"
./ipturntables.sh -4 REMOVE "\fBeth1_0A0A0A0018_eth2\fR"
Attention!
.br
......
......@@ -10,10 +10,10 @@ printAbout()
[PROBE_KERNEL_MODS mod1,mod2,...,modN]
[RESET [default_policy=ACCEPT|DROP|REJECT]]
[BASE_RULE_SET]
[ALLOW_DHCP on_link]
[ALLOW_DHCP on_link client|server|both]
[ALLOW_SUBNETS on_link]
[ALLOW_LINK_LOCAL on_link]
[ALLOW_MULTICAST_ADDRS ]
[ALLOW_MULTICAST_ADDRS on_link [port,port,port,...]]
[ALLOW_SERVICE_DISCOVERY on_link]
[ALLOW_STATEFUL_PACKETS ip|link]
[ALLOW_TUNNEL mode on_link from_address]
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment