uruk(8)

💖 uruk(8) — SYSTEM ADMINISTRATION 💖

okay bestie, sit down, hydrate, because we're about to talk about uruk, and she is that girl. this is section 8 of the system administration manual, and she's a wrapper. a little guy. a firewall bestie. let's go 🫶

---

✨ NAME ✨

uruk — wrapper for Linux iptables, for managing firewall rules 🔥

---

🌸 SYNOPSIS 🌸

uruk

that's it. that's the whole synopsis. she contains multitudes 💅

---

🦋 DESCRIPTION 🦋

so uruk loads an rc file (peep uruk-rc(5) for the tea ☕) which defines your network service access policy, and then it invokes iptables(8) to set up firewall rules that actually implement that policy. like, it's the translator between "here's my vibe" and "here's a wall of kernel-level packet filtering." iconic behavior honestly.

by default it uses the file /etc/uruk/rc, but you can overrule that by specifying another file in the URUK_CONFIG environment variable. no cap.

and under some circumstances, it's useful to use another command for iptables — you can achieve that by setting the URUK_IPTABLES (and/or URUK_IP6TABLES) environment variables. see uruk-rc(5) for details 💜

---

🎀 QUICK SETUP GUIDE 🎀

okay real talk: uruk will not "just work" out of the box. she needs manual configuration. she's high maintenance and we love her for it. for those of you who don't like reading lots of documentation:

 # cp /usr/share/doc/uruk/examples/rc \
     /etc/uruk/rc
 # vi /etc/uruk/rc
 # urukctl start

boom. done. go live your life 🌈

---

🌟 GETTING STARTED 🌟

once the uruk script is installed, you're obviously gonna want to use it. so let's get into the details, bestie, step by step.

first: create an rc file. see uruk-rc(5) for info on how to do this. once this file is created and installed (this script looks in /etc/uruk/rc by default), you're ready to run uruk. you might wanna test your rc file by running uruk in debug mode — again, uruk-rc(5), she has the answers.

there are at least 3 ways to load your rc file. let's start with the low level one: vanilla iptables 🍦

🍦 Vanilla iptables 🍦

after editing rc, load your rules like this. first, flush your current rules:

 # iptables -F
 # ip6tables -F

then enable your rc rules:

 # uruk

inspect the rules by doing:

 # iptables -L
 # ip6tables -L

if you want to make these changes survive a reboot, use the init script as shipped with this package. if you'd rather write your own init script, the iptables-restore(8) and iptables-save(8) commands from the iptables package might be helpful 💖

💫 Using the Uruk init script 💫

assumed is the Uruk init script is installed as explained in the README file. optionally, install /etc/default/uruk (or /etc/sysconfig/uruk) and tweak it. an example file is in /usr/share/doc/uruk/examples/default (you might like to enable support for uruk-save.) now activate uruk by doing:

 # urukctl start

now your pre-uruk iptables rules (if any) are saved as the "inactive" ruleset. heads up though 👀: while executing urukctl start, your box is open during a short while. if you don't like this, read below about uruk-save.

when rebooting, everything will be fine: /etc/init.d/uruk stores state in /var/lib/uruk/iptables, using iptables-save(8), which comes with Linux iptables. slay 💅

🧚 Using Debian ifupdown 🧚

in case you have just one network interface which should get protected, you could use interfaces(5) from the Debian ifupdown package instead of the init script. suppose you'd like to protect ppp0, and would like not to interfere with traffic on eth0: your other network interface. first write an rc file. be sure it features

 interfaces_unprotect="lo eth0"

then run:

 # mkdir -p /var/lib/uruk/iptables

 # iptables -F

 # iptables-save -c > /var/lib/uruk/iptables/down
 # uruk
 # iptables-save -c > /var/lib/uruk/iptables/up

add

 pre-up iptables-restore < /var/lib/uruk/iptables/up
 post-down iptables-restore < /var/lib/uruk/iptables/down

to your interfaces stanza, in your /etc/network/interfaces .

similar tricks might be possible on GNU/Linux systems from other distributions. the author is interested 👀 (fr fr, he said that)

---

🔄 LOADING A NEW rc FILE 🔄

need to change your rules? say less.

💫 Using the Uruk init script 💫

do

 # vi /etc/uruk/rc
 # urukctl force-reload

while executing urukctl force-reload, your box is open during a short while. if you don't like this, read below about uruk-save. same warning, same energy 🫶

---

👑 THE GORY DETAILS: uruk INTERNALS 👑

the uruk script works like (and looks like) the list of statements below. of course, take a look at /sbin/uruk for the final word on the workings — the source is the main character here 💯

1. rc is sourced as a shell script
2. traffic on $interfaces_unprotect (just lo per default) is trusted:

 $iptables -A INPUT -i $iface -j ACCEPT

3. $rc_a is sourced as a shell script, or, in case $rc_a is a directory, all files matching $rc_a/*.rc are sourced as shell scripts
4. ESTABLISHED and RELATED packets are ACCEPT-ed:

 $iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED \
  -j ACCEPT

5. $rc_b is sourced
6. $interfaces gets protected against spoofing: we don't allow anyone to spoof non-routeable addresses. we block outgoing packets that don't have our address as source: they are either spoofed or something is misconfigured (NAT disabled, for instance). we want to be nice and don't send out garbage.

 $iptables -A INPUT -i $iface --source $no_route_ip \
  -j DROP

we drop all incoming packets which don't have us as destination:

 $iptables -A OUTPUT -o $iface --source ! "$ip" \
  -j DROP

and we always allow outgoing connections:

 $iptables -A OUTPUT -m conntrack --ctstate NEW -o $iface \
  -j ACCEPT

7. $rc_c is sourced
8. allow traffic to offered services, from trusted sources:

 $iptables -A INPUT -m conntrack --ctstate NEW \
  -i $iface --protocol $proto --source "$source" \
  --destination "$ip" --destination-port "$port" \
  -j ACCEPT

9. $rc_d is sourced
10. don't answer broadcast and multicast packets:

 $iptables -A INPUT -i $iface --destination "$bcast" \
  -j DROP

11. $rc_f is sourced
12. explicitly allow a subset of the ICMP types. (we disallow all other traffic later.)

 $iptables -A INPUT --protocol icmp --icmp-type $type \
  -j ACCEPT

13. $rc_g is sourced
14. log packets (which make it till here)

 $iptables -A INPUT -j LOG --log-level debug \
  --log-prefix 'iptables: '

15. $rc_h is sourced
16. reject all other packets

 $iptables -A INPUT -j REJECT

17. $rc_i is sourced

---

⚡ USING uruk-save AS THE INITSCRIPT BACKEND ⚡

by default, uruk-save is not used by the uruk init script. you might want to use it, though. the uruk-save script is faster and when using uruk-save, your box won't be open while loading new rules. but beware ⚠️: uruk-save is not as robust as using uruk itself.

the script urukctl (and thus the uruk init script) will use uruk-save only if asked to do so in /etc/default/uruk (or /etc/sysconfig/uruk). if this file features

 enable_uruk_save=true

uruk-save is used whenever appropriate. see uruk-save(8) for more details 💜

---

💀 DEFAULT POLICY 💀

by default, uruk drops packets which have unknown RFC 1918 private network addresses in their source or destination.

it rejects packets with source nor destination for one of our IPs.

packets belonging to locally initiated sessions are allowed: we match state; the local host can act as a client for any remote service.

by default, uruk drops all ICMP packets (except those for interfaces in $interfaces_unprotect) with type other than

• address-mask-reply
• address-mask-request
• destination-unreachable (this is a catch-all for a lot of types)
• echo-request
• echo-reply
• parameter-problem (catch-all for ip-header-bad and required-option-missing)
• timestamp-reply
• timestamp-request
• ttl-zero-during-transit
• ttl-zero-during-reassembly

by default, the FORWARD chain is left untouched, so has policy ACCEPT. (this won't do much harm, since packet forwarding is disabled by default in the Linux kernel. however, if you don't mind being paranoid, you might want to add a

 iptables --policy FORWARD REJECT

to your $rc_a uruk hook. see uruk-rc(5).)

by default, uruk logs all UDP and TCP packets which are blocked by the user defined policies. loglevel is debug, logprefix is "iptables:". see also the notes on loglevel in uruk-rc(5).

blocked TCP packets are answered with a tcp-reset.

---

🚨 WARNING 🚨

in order to keep the uruk script small and simple, the script does very little error handling. it does not check the contents of the rc file in any way before executing it. when your rc file contains bogus stuff, uruk will very likely behave in unexpected ways. caveat emptor. 😭

bestie. please. read your rc file. uruk is not your mom, she will not catch your typos, she will simply do the thing you told her to do and you will have a bad time. 💀

---

🌈 ENVIRONMENT 🌈

you can override some defaults in the shell before executing the uruk script. uruk honors the following variables:

• "URUK_CONFIG" — full pathname of rc file; /etc/uruk/rc by default.
• "URUK_IPTABLES" — full pathname of iptables executable. /sbin/iptables by default. overrides iptables.
• "URUK_IP6TABLES" — full pathname of ip6tables executable, for IPv6 support. overrides ip6tables.
• "URUK_INTERFACES_UNPROTECT" — default list of unprotected interfaces. overrides interfaces_unprotect. the default default is lo.

---

🔗 SEE ALSO 🔗

uruk-rc(5), uruk-save(8). the Uruk homepage is at http://mdcc.cx/uruk/ .

iptables(8), iptables-save(8), iptables-restore(8), ip6tables(8), ip6tables-save(8), ip6tables-restore(8), http://www.netfilter.org/

interfaces(5), http://packages.debian.org/ifupdown.

---

📜 COPYRIGHT 📜

Copyright (C) 2003 Stichting LogReport Foundation logreport@logreport.org; Copyright (C) 2003, 2004 Tilburg University http://www.uvt.nl/; Copyright (C) 2003-2013 Joost van Baal-Ilić <joostvb-uruk@mdcc.cx>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

---

🫶 AUTHOR 🫶

Joost van Baal-Ilić <joostvb-uruk@mdcc.cx>

---

and that's the whole page, bestie!! ✨ this is uruk version 20190121, dated 21 јан 2019, and it lives in section uruk(8) of your friendly neighbourhood manual. go forth and filter those packets, you absolute icon 👑💖 no cap, you ate. 🎀