.TH FWRULES 6
.SH NAME
fwrules \- firewall rule files
.SH DESCRIPTION
.IR Fw (8)
decides what may cross a network by matching traffic against a file of
rules.
The file is an
.IR ndb (6)
file: one entry is one rule.
.PP
A rule set for a machine that may look up names and fetch pages, and do
nothing else:
.IP
.EX
allow=out	proto=udp	port=53
allow=out	proto=tcp	port=53
allow=out	proto=tcp	port=80
allow=out	proto=tcp	port=443

deny=*	log=yes
.EE
.PP
Rules are matched from the top, the first one that matches decides, and
traffic matching none of them is denied.
A file with no rules therefore permits nothing, and the last rule above
changes nothing about what is allowed - it exists so that the refusals
are written down instead of happening silently.
.PP
There is no rule permitting the replies to any of this, and none is
needed: see
.B STATE
below.
.SH ACTION
Every rule begins with an action, whose value is the direction it
governs:
.TP
.BI allow= dir
permit.
.TP
.BI deny= dir
refuse.
.PP
.I Dir
is
.BR out ,
.BR in ,
or
.B *
for either.
.B Out
is traffic begun from the side being protected;
.B in
is traffic begun toward it.
That holds wherever the rule is enforced: on a gateway the protected
side is the inside, and in a namespace it is the program, whose
.B connect
is
.B out
and whose
.B announce
is
.BR in .
.B Connect
and
.B announce
are accepted as older spellings of
.B out
and
.BR in .
.SH ATTRIBUTES
The rest of a rule says what it matches.
An attribute that is absent does not constrain, so there is never a
.B *
to write:
.TP
.BI proto= name
a protocol:
.BR tcp ,
.BR udp ,
.BR icmp ,
and so on.
.TP
.BI port= n
the port at the far end.
.TP
.BI lport= n
the port at this end.
A program announcing a port is naming this end, so
.B announce 17019
is matched by
.BR lport=17019 ,
and by
.B port=
never - at that moment nobody has called, so there is no far end.
An
.B in
rule naming an
.B ip
therefore cannot decide an announce; it decides the connection that
arrives, which is asked about separately when there is a caller to name.
.TP
.BI ip= address
the address at the far end, optionally carrying a
.BI / mask
suffix.
IPv4 and IPv6 are written the usual way and need no distinguishing.
.TP
.BI ipmask= mask
the mask, written separately, as
.B /24
or in full.
.TP
.B log=yes
note every match of this rule in
.BR /sys/log/fw .
.PP
An unrecognised attribute is an error, and
.I fw
refuses to start rather than run with it ignored: a mistyped constraint
would otherwise silently widen the rule it was meant to narrow.
.PP
An entry may be spread over indented continuation lines, as any
.IR ndb (6)
entry may:
.IP
.EX
allow=out
	proto=tcp
	port=443
.EE
.SH ORDER
The first match decides, so a rule carving an exception out of a
broader rule must come above it.
This is right:
.IP
.EX
deny=out	ip=1.1.1.1
allow=out	proto=tcp	port=443
.EE
.PP
and this is not, because 1.1.1.1:443 matches the allow first and the
deny is never reached:
.IP
.EX
allow=out	proto=tcp	port=443
deny=out	ip=1.1.1.1
.EE
.PP
Rules are numbered from one in the order they appear, and that is the
number a refusal names in
.BR /sys/log/fw .
.SH STATE
Connections are tracked, so a rule permitting traffic one way permits
the replies without a second rule.
A permitted packet records the protocol and both addresses and ports;
anything matching that, either way round, passes without consulting the
rules again.
.PP
UDP has no connections, so a flow is that same tuple and lasts 60
seconds after the last packet.
TCP lasts 300 seconds, everything else 30.
ICMP has no ports, so its flows are the two addresses alone, which is
enough for a reply to an echo to be recognised, but does not tie an
ICMP error to the connection it is about.
.PP
A fragmented datagram is a train: only its first piece carries ports, so
that piece is matched against the rules and the rest of the train
inherits the answer.
A train whose first piece was never seen - or was refused - is judged on
its addresses alone.
.PP
When the rules change, connections the new rules forbid are dropped
rather than left to finish: a block blocks.
.SH EXAMPLES
A gateway.
The machines behind it may reach the web, one host is refused outright,
and the only thing the internet may reach is a web server:
.IP
.EX
#  the exception first, or the allows below would match
#  1.1.1.1:443 before this was ever reached
deny=out	ip=1.1.1.1

#  out: what the machines behind me may reach
allow=out	proto=udp	port=53
allow=out	proto=tcp	port=53
allow=out	proto=tcp	port=80
allow=out	proto=tcp	port=443

#  in: what the internet may reach here
allow=in	proto=tcp	lport=443

#  and note anything else that tries, either way
deny=*	log=yes
.EE
.PP
On a gateway facing the internet that last rule will log a great deal,
since the internet knocks on every door constantly.
Narrow it to
.B deny=out
if only the traffic from your own machines is worth recording.
.PP
A program that may resolve names and fetch pages over TLS, and nothing
else:
.IP
.EX
allow=out	proto=udp	port=53
allow=out	proto=tcp	port=443
.EE
.PP
A service that answers on one port and never calls out:
.IP
.EX
allow=in	proto=tcp	lport=17019
.EE
.PP
No network at all.
An empty file permits nothing, so this is a complete rule set:
.IP
.EX
#  nothing
.EE
.SH FILES
.TP
.B /lib/fw
rule sets
.TP
.B /lib/fw/example.ndb
every attribute, with comments
.SH "SEE ALSO"
.IR fw (8),
.IR ndb (6)
.SH BUGS
A rule cannot name which network card it applies to, so a machine
filtering two cards needs a file for each.