.\" Automatically generated by Pandoc 3.1.3
.nh
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "firehol-synproxy" "5" "Built 30 Mar 2024" "FireHOL Reference" "3.1.7"
.hy
.SH NAME
.PP
firehol-synproxy - configure synproxy
.SH SYNOPSIS
.PP
synproxy \f[I]type\f[R] \f[I]rules-to-match-request\f[R]
\f[I]action\f[R] [\f[I]action options\f[R]]
.SH DESCRIPTION
.IP \[bu] 2
\f[B]type\f[R] defines where the SYNPROXY will be attached.
It can be \f[V]input\f[R] (or \f[V]in\f[R]), \f[V]forward\f[R] (or
\f[V]pass\f[R]):
.RS 2
.IP \[bu] 2
use \f[V]input\f[R] (or \f[V]in\f[R]) when the IP of the real server is
an IP assigned to a physical interface of the machine (i.e.\ the IP is
at the firewall itself)
.IP \[bu] 2
use \f[V]forward\f[R] (or \f[V]pass\f[R]) when the IP of the real server
is routed by the machine (i.e.\ SYNPROXY should look at the FORWARD
chain for this traffic).
.RE
.IP \[bu] 2
\f[V]rules to match request\f[R] are FireHOL optional rule parameters
and should match the original client REQUEST, before any destination
NAT.
\f[V]inface\f[R] and \f[V]dst\f[R] are required:
.RS 2
.IP \[bu] 2
\f[V]inface\f[R] is one or more interfaces the REQUEST should be
received from
.IP \[bu] 2
\f[V]dst\f[R] is the IP of the real server, as seen by the client
(before any destination NAT)
.RE
.IP \[bu] 2
\f[B]action\f[R] defines how SYNPROXY will reach the real server and can
be:
.RS 2
.IP \[bu] 2
\f[V]accept\f[R] to just allow the REQUEST reach the real server without
any destination NAT
.IP \[bu] 2
\f[V]dnat to IP:PORT\f[R] or \f[V]dnat to IP1-IP2:PORT1-PORT2\f[R] or
\f[V]dnat to IP\f[R] or \f[V]dnat to :PORT\f[R] to have SYNPROXY reach a
server on another machine in a DMZ (different IP and/or PORT compared to
the original request).
The synproxy statement supports everything supported by the dnat helper
(see firehol-nat(5)).
.IP \[bu] 2
\f[V]redirect to PORT\f[R] to divert the request to a port on the
firewall itself.
The synproxy statement supports everything supported by the redirect
helper (see firehol-nat(5)).
.IP \[bu] 2
\f[V]action CUSTOM_ACTION\f[R] to have any other FireHOL action
performed on the NEW socket.
Use the \f[V]action\f[R] helper to define custom actions (see
[firehol-action(5)][]).
.IP \[bu] 2
\f[V]action options\f[R] are everything supported by FireHOL optional
rule parameters that should be applied only on the final action of SYN
packet from SYNPROXY to the real server.
For example this can be used to append \f[V]loglimit \[dq]TEXT\[dq]\f[R]
to have something logged by iptables, or limit the concurrent sockets
with \f[V]connlimit\f[R].
Generally, everything you can write on the same line after
\f[V]server http accept\f[R] is also accepted here.
.RE
.SH BACKGROUND
.PP
SYNPROXY is a TCP SYN packets proxy.
It can be used to protect any TCP server (like a web server) from SYN
floods and similar DDos attacks.
.PP
SYNPROXY is a netfilter module, in the Linux kernel.
It is optimized to handle millions of packets per second utilizing all
CPUs available without any concurrency locking between the connections.
.PP
The net effect of this, is that the real servers will not notice any
change during the attack.
The valid TCP connections will pass through and served, while the attack
will be stopped at the firewall.
.PP
For more information on why you should use a SYNPROXY, check these
articles:
.IP \[bu] 2
http://rhelblog.redhat.com/2014/04/11/mitigate-tcp-syn-flood-attacks-with-red-hat-enterprise-linux-7-beta/
.IP \[bu] 2
https://r00t-services.net/knowledgebase/14/Homemade-DDoS-Protection-Using-IPTables-SYNPROXY.html
.PP
SYNPROXY is included in the Linux kernels since version 3.12.
.SH HOW IT WORKS
.IP \[bu] 2
When a SYNPROXY is used, clients transparently get connected to the
SYNPROXY.
So the 3-way TCP handshake happens first between the client and the
SYNPROXY:
.RS 2
.IP \[bu] 2
Clients send TCP SYN to server A
.IP \[bu] 2
At the firewall, when this packet arrives it is marked as UNTRACKED
.IP \[bu] 2
The UNTRACKED TCP SYN packet is then given to SYNPROXY
.IP \[bu] 2
SYNPROXY gets this and responds (as server A) with TCP SYN+ACK
(UNTRACKED)
.IP \[bu] 2
Client responds with TCP ACK (marked as INVALID or UNTRACKED in
iptables) which is also given to SYNPROXY
.RE
.IP \[bu] 2
Once a client has been connected to the SYNPROXY, SYNPROXY automatically
initiates a 3-way TCP handshake with the real server, spoofing the SYN
packet so that the real server will see that the original client is
attempting to connect:
.RS 2
.IP \[bu] 2
SYNPROXY sends TCP SYN to real server A.
This is a NEW connection in iptables and happens on the OUTPUT chain.
The source IP of the packet is the IP of the client
.IP \[bu] 2
The real server A responds with SYN+ACK to the client
.IP \[bu] 2
SYNPROXY receives this and responds back to the server with ACK.
The connection is now marked as ESTABLISHED
.RE
.IP \[bu] 2
Once the connection has been established, SYNPROXY leaves the traffic
flow between the client and the server
.PP
So, SYNPROXY can be used for any kind of TCP traffic.
It can be used for both unencrypted and encrypted traffic, since it does
not interfere with the content itself.
.SH USE CASES
.PP
In FireHOL SYNPROXY support is implemented as a helper.
The \f[V]synproxy\f[R] command can be used to set up any number of
SYNPROXYs.
.PP
FireHOL can set up SYNPROXY for any of these cases:
.IP "1." 3
\f[B]real server on the firewall itself, on the same port\f[R]
(e.g.\ SYNPROXY on port 80, real server on port 80 too).
.IP "2." 3
\f[B]real server on the firewall itself, on a different port\f[R]
(e.g.\ SYNPROXY on port 2200, real server on port 22).
.IP "3." 3
\f[B]real server on a different machine, without NAT\f[R]
(e.g.\ SYNPROXY on a router catching traffic towards IP A, port 80 and
real server is at IP A port 80 too).
.IP "4." 3
\f[B]real server on a different machine, with NAT\f[R] (e.g.\ SYNPROXY
on a router catching traffic towards IP A, port 80 and real server is at
IP 10.1.1.1 port 90).
.IP "5." 3
\f[B]screening incoming traffic that should never be sent to a real
server\f[R] so that traps and dynamic blacklists can be created using
traffic that has been screened by SYNPROXY (eliminate \[lq]internet
noise\[rq] and spoofed packets).
.PP
So, generally, all cases are covered.
.SH DESIGN
.PP
The general guidelines for using \f[V]synproxy\f[R] in FireHOL, are:
.IP "1." 3
\f[B]Design your firewall as you would normally do without SYNPROXY\f[R]
.IP "2." 3
Test that it works without SYNPROXY.
Test especially the servers you want to protect.
They should be working too
.IP "3." 3
Add \f[V]synproxy\f[R] statements for the servers you want to protect.
.PP
To achieve these requirements:
.IP "1." 3
The helper will automatically do everything needed for SYNPROXY to:
.RS 4
.IP \[bu] 2
receive the initial SYN packet from the client
.IP \[bu] 2
respond back to the client with SYN+ACK
.IP \[bu] 2
receive the first ACK packet from the client
.IP \[bu] 2
send the initial SYN packet to the server
.RE
.PP
There are cases where the above are very tricky to achieve.
You don\[cq]t need to match these in your \f[V]firehol.conf\f[R].
The \f[V]synproxy\f[R] helper will automatically take care of them.
However:
.RS
.PP
You do need the allow the flow of traffic between the real server and
the real client (as you normally do without a \f[V]synproxy\f[R], with a
\f[V]client\f[R], \f[V]server\f[R], or \f[V]route\f[R] statement in an
\f[V]interface\f[R] or \f[V]router\f[R] section).
.RE
.IP "2." 3
The helper will prevent the 3-way TCP handshake between SYNPROXY and the
real server interact with other \f[B]destination NAT\f[R] rules you may
have.
However for this to happen, make sure you place the \f[V]synproxy\f[R]
statements above any destination NAT rules (\f[V]redirect\f[R],
\f[V]dnat\f[R], \f[V]transparent_squid\f[R],
\f[V]transparent_proxy\f[R], \f[V]tproxy\f[R], etc).
So:
.RS 4
.RS
.PP
SYNPROXY will interact with destination NAT you have in
\f[V]firehol.conf\f[R] \f[B]only\f[R] if the \f[V]synproxy\f[R]
statements are place below the destination NAT ones.
.PP
You normally do not need to have \f[V]synproxy\f[R] interact with other
destination NAT rules.
The \f[V]synproxy\f[R] helper will handle the destination NAT
(\f[V]dnat\f[R] or \f[V]redirect\f[R]) it needs by itself.
.PP
So \f[B]place \f[VB]synproxy\f[B] statements above all destination NAT
statements, unless you know what you are doing\f[R].
.RE
.RE
.IP "3." 3
The helper will allow the 3-way TCP handshake between SYNPROXY and the
real server interact with \f[B]source NAT\f[R] rules you may have
(\f[V]snat\f[R], \f[V]masquerade\f[R]), since these may be needed to
reach the real server.
.SH LIMITATIONS
.IP "1." 3
Internally there are matches that are made without taking into account
the original \f[V]inface\f[R].
So, in case different actions have to be taken depending on the
interface the request is received, \f[V]src\f[R] should be added to
differentiate the traffic between the two flows.
.IP "2." 3
SYNPROXY does not inherit MARKs from the original request packets.
It should and it would make matching a lot easier, but it does not.
This means that for all packets generated by SYNPROXY, \f[V]inface\f[R]
is lost.
.IP "3." 3
FireHOL internally uses a MARK to tag packets send from SYNPROXY to the
target server.
This is used for 3 reasons:
.RS 4
.IP \[bu] 2
isolate these packets from other destination NAT rules.
If they were not isolated from the destination NAT rules, then packets
from the SYNPROXY could be matched by a transparent proxy and enter your
web proxy.
They could be matched by a transparent proxy because they actually
originate from the local machine.
.IP \[bu] 2
isolate the same packets from the rest of the packet filtering rules.
Without this isolation, most probably the packets will have been dropped
since they come from lo.
.IP \[bu] 2
report if orphan synproxy packets are encountered.
So packets the FireHOL engine failed to match properly, should appear
with a iptables log saying \[lq]ORPHAN SYNPROXY->SERVER\[rq].
If you don\[cq]t have such logs, everything works as expected.
.RE
.SH OTHER OPTIONS
.PP
You can change the TCP options used by \f[V]synproxy\f[R] by setting the
variable \f[V]FIREHOL_SYNPROXY_OPTIONS\f[R].
The default is this:
.IP
.nf
\f[C]
FIREHOL_SYNPROXY_OPTIONS=\[dq]--sack-perm --timestamp --wscale 7 --mss 1460\[dq]
\f[R]
.fi
.PP
If you want to see it in action in the iptables log, then enable
logging:
.IP
.nf
\f[C]
FIREHOL_SYNPROXY_LOG=1
\f[R]
.fi
.PP
The default is disabled (0).
If you enable it, every step of the 3-way setup between the client and
SYNPROXY and the SYN packet of SYNPROXY towards the real server will be
logged by iptables.
.PP
Using the variable \f[V]FIREHOL_CONNTRACK_LOOSE_MATCHING\f[R] you can
set \f[V]net.netfilter.nf_conntrack_tcp_loose\f[R].
FireHOL will automatically set this to 0 when a synproxy is set up.
.PP
Using the variable \f[V]FIREHOL_TCP_TIMESTAMPS\f[R] you can set
\f[V]net.ipv4.tcp_timestamps\f[R].
FireHOL will automatically set this to 1 when a synproxy is set up.
.PP
Using the variable \f[V]FIREHOL_TCP_SYN_COOKIES\f[R] you can set
\f[V]net.ipv4.tcp_syncookies\f[R].
FireHOL will automatically set this to 1 when a synproxy is set up.
.PP
On a busy server, you are advised to increase the maximum connection
tracker entries and its hash table size.
.IP \[bu] 2
Using the variable \f[V]FIREHOL_CONNTRACK_HASHSIZE\f[R] you can set
\f[V]/sys/module/nf_conntrack/parameters/hashsize\f[R].
.IP \[bu] 2
Using the variable \f[V]FIREHOL_CONNTRACK_MAX\f[R] you can set
\f[V]net.netfilter.nf_conntrack_max\f[R].
.PP
FireHOL will not alter these variables by itself.
.SH SYNPROXY AND DYNAMIC IP
.PP
By default the \f[V]synproxy\f[R] helper requires from you to define a
\f[V]dst IP\f[R] of the server that is to be protected.
This is required because the destination IP will be used to match the
SYN packet the synproxy sends to the server.
.PP
There is however another way that allows the use of synproxy in
environments where the IP of the server is unknown (like a dynamic IP
DSL):
.IP "1." 3
First you need to set \f[V]FIREHOL_SYNPROXY_EXCLUDE_OWNER=1\f[R].
This will make synproxy not match packets that are generated by the
local machine, even if the process that generates them uses your public
IP (the packets in order to be matched they will need not have a UID or
GID).
.IP "2." 3
Next you will need to exclude you lan IPs by adding
\f[V]src not \[dq]${UNROUTABLE_IPS}\[dq]\f[R] (or any other network you
know you use) to the synproxy statement.
.SH EXAMPLES
.PP
Protect a web server running on the firewall with IP 1.2.3.4, from
clients on eth0:
.IP
.nf
\f[C]
ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 80 accept

interface eth0 wan
    server http accept
\f[R]
.fi
.PP
Protect a web server running on port 90 on the firewall with IP 1.2.3.4,
from clients on eth0 that believe the web server is running on port 80:
.IP
.nf
\f[C]
server_myhttp_ports=\[dq]tcp/90\[dq]
client_myhttp_ports=\[dq]default\[dq]

ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 80 redirect to 90

interface eth0 wan
    server myhttp accept # packet filtering works with the real ports
\f[R]
.fi
.PP
Protect a web server running on another machine (5.6.7.8), while the
firewall is the router (without NAT):
.IP
.nf
\f[C]
ipv4 synproxy forward inface eth0 dst 5.6.7.8 dport 80 accept

router wan2lan inface eth0 outface eth1
    server http accept dst 5.6.7.8
\f[R]
.fi
.PP
Protect a web server running on another machine in a DMZ (public IP is
1.2.3.4 on eth0, web server IP is 10.1.1.1 on eth1):
.IP
.nf
\f[C]
ipv4 synproxy input inface eth0 \[rs]
    dst 1.2.3.4 dport 80 dnat to 10.1.1.1

router wan2lan inface eth0 outface eth1
    server http accept dst 10.1.1.1
\f[R]
.fi
.PP
Note that we used \f[V]input\f[R] not \f[V]forward\f[R], because the
firewall has the IP 1.2.3.4 on its eth0 interface.
The client request is expected on input.
.PP
Protect an array of 10 web servers running on 10 other machines in a DMZ
(public IP is 1.2.3.4 on eth0, web servers IPs are 10.1.1.1 to 10.1.1.10
on eth1):
.IP
.nf
\f[C]
ipv4 synproxy input inface eth0 \[rs]
    dst 1.2.3.4 dport 80 dnat to 10.1.1.1-10.1.1.10 persistent

router wan2lan inface eth0 outface eth1
    server http accept dst 10.1.1.1-10.1.1.10
\f[R]
.fi
.PP
The above configuration is a load balancer.
Requests towards 1.2.3.4 port 80 will be distributed to the 10 web
servers with persistence (each client will always see one of them).
.PP
Catch all traffic towards SSH port tcp/22 and send it to
\f[V]TRAP_AND_DROP\f[R] as explained in Working With Traps.
At the same time, allow SSH on port tcp/2200 (without altering the ssh
server):
.IP
.nf
\f[C]
 # definition of action TRAP_AND_DROP
 ipv4 action TRAP_AND_DROP sockets_suspects_trap 3600 86400 1 src not \[dq]${UNROUTABLE_IPS}\[dq] next action DROP

 # send ssh traffic to TRAP_AND_DROP
 ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 22 action TRAP_AND_DROP

 # accept ssh traffic on tcp/2200
 ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 2200 redirect to 22

 interface eth0 wan
    server ssh accept
\f[R]
.fi
.SH SEE ALSO
.IP \[bu] 2
firehol(1) - FireHOL program
.IP \[bu] 2
firehol.conf(5) - FireHOL configuration
.IP \[bu] 2
firehol-interface(5) - interface definition
.IP \[bu] 2
firehol-router(5) - router definition
.IP \[bu] 2
firehol-params(5) - optional rule parameters
.IP \[bu] 2
firehol-masquerade(5) - masquerade helper
.IP \[bu] 2
FireHOL Website (http://firehol.org/)
.IP \[bu] 2
FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)
.IP \[bu] 2
FireHOL Online Documentation (http://firehol.org/documentation/)
.IP \[bu] 2
NAT
HOWTO (http://www.netfilter.org/documentation/HOWTO/NAT-HOWTO-6.html)
.IP \[bu] 2
netfilter flow
diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg)
.SH AUTHORS
FireHOL Team.