INTRODUCTION

Uruk is a simple shell script (uruk(5)) which calls Linux
iptables.  It uses a template file to get lists of source addresses, allowed to
use specific network services.


REQUIREMENTS

Uruk is useful only on Linux systems.  However, the rc file (see uruk-rc(5))
could be used by other packet filtering engine wrappers too.

For this script to work, your Linux kernel needs stuff from the
netfilter/iptables project ( http://www.netfilter.org/ ).  The specific needed
settings are

 .config variable           module name   description in ``make config''

 CONFIG_IP_NF_IPTABLES      ip_tables.o   (``IP tables support'')
 CONFIG_IP_NF_TARGET_LOG    ipt_LOG.o     (``LOG target support'')
 CONFIG_IP_NF_TARGET_REJECT ipt_REJECT.o  (``REJECT target support'')
 CONFIG_IP_NF_CONNTRACK                   (``Connection tracking'')

.  Furthermore, you need the iptables(8) command, as shipped with the iptables
package from the netfilter project.


For retypesetting the documentation (the uruk(8), uruk-rc(5) and uruk-save(8)
manpages), you'll need zoem >= 05-328.  Zoem is a an interpretive macro
language, for creating mark-up languages, by Stijn van Dongen.  Information
about zoem, as well as tarballs for download, can be found on the zoem webpage
at http://micans.org/zoem/ .  Binary zoem packages are shipped with Debian
GNU/Linux and other distributions ( https://repology.org/project/zoem ).
However, pretypesetted uruk docs are shipped with the tarball: you likely
don't need zoem.


INSTALL

If you use the uruk Debian package or the uruk RPM, use your package manager to
take care of installation; skip this section.  If you'd prefer to install using
the uruk .tar.gz release however, do read on.

See the INSTALL file for generic installation instructions.

The traditional SysV Uruk init script, in init/uruk, gets installed in
/usr/local/etc/init.d/ by default.  Symlinks are _not_ created.  You'll have to
create them yourself, after running 'make install'.  E.g. do:

 # cd /etc/init.d && ln -s /usr/local/etc/init.d/uruk
 # update-rc.d uruk defaults

.

(If you lack update-rc.d, do something like

 # cd /etc/
 # ln -s ../init.d/uruk rc0.d/K92uruk
 # ln -s ../init.d/uruk rc1.d/K92uruk
 # ln -s ../init.d/uruk rc2.d/S20uruk
 # ln -s ../init.d/uruk rc3.d/S20uruk
 # ln -s ../init.d/uruk rc4.d/S20uruk
 # ln -s ../init.d/uruk rc5.d/S08uruk
 # ln -s ../init.d/uruk rc6.d/K92uruk

)

A uruk.service file is shipped too, for systems using the init system as
implemented by systemd.


UPGRADE

For upgrades from any version: run /etc/init.d/uruk force-reload after
installation.  Read the NEWS file.


* upgrading from uruk <= 20100831

Support for IPv6 packet filtering has been enabled by default in the uruk init
script.

If you'd like to start using IPv6 filtering now, and you interact with uruk
using the init script, you don't have to change anything.  You might however
like to do some janitoring on your file /etc/default/uruk: you now can remove
any setting of enable_ipv6 in this file.  If you run /usr/sbin/uruk directly,
you don't have to edit any special configuration file.  In both cases, if you
want to block/allow specific IPv6 traffic, you'll have to adjust the uruk rc
file of course.  See /usr/share/doc/uruk/examples/rc for hints on how to do
that.

If you don't want to use any IPv6 filtering, and you interact with uruk using
the init script, be sure your /etc/default/uruk has "enable_ipv6=false".  If
you run /usr/sbin/uruk directly, add URUK_IP6TABLES=':' to the top of your uruk
rc file.

If you have been using IPv6 filtering, and want to continue to do so, you don't
have to change anything.  You might however like to do some janitoring on your
file /etc/default/uruk: you now can remove any setting of enable_ipv6 in this
file.


* upgrading from uruk <= 20100717

IPv6 support is now blessed mature.  It is enabled by default in the uruk
script.

If you'd like to start using IPv6 filtering now, and you interact with uruk
using the init script, you have to add "enable_ipv6=true" to /etc/default/uruk
to enable IPv6 filtering.  If you run /usr/sbin/uruk directly, you don't have
to edit any special configuration file.  In both cases, if you want to
block/allow specific IPv6 traffic, you'll have to adjust the uruk rc file of
course.  See /usr/share/doc/uruk/examples/rc for hints on how to do that.

If you don't want to use any IPv6 filtering, and you interact with uruk using
the init script, you're safe.  If you run /usr/sbin/uruk directly, add
URUK_IP6TABLES=':' to the top of your uruk rc file.

If you have been using IPv6 filtering, and want to continue to do so, you don't
have to change anything.  You might however like to do some janitoring on your
rc file: a statement like

 ip6tables=${URUK_IP6TABLES:-/sbin/ip6tables}

is no longer needed: you no longer need to override the $ip6tables variable.
(The statement "enable_ipv6=true" in /etc/default/uruk is still needed.)


* upgrading from uruk <= 20050718

You might like to use the experimental IPv6 support.  See the NEWS file.

Behaviour of the uruk init script has changed.  Before 20050718, you were
advised to run

 /etc/init.d/uruk stop; uruk; /etc/init.d/uruk save active

.  This has changed.  One now should run

 /etc/init.d/uruk force-reload

after changing the uruk rc file.

Some details: To understand this, consider the uruk states: Iptables rules are
kept in:

 liverules inactivestatefile activestatefile uruk-rc

. Actions on copying rules from one to the other are:

 init.d/uruk stop
 init.d/uruk start
 init.d/uruk reload
 sbin/uruk
 uruk-save

The actions perform the following copies:

 sbin/uruk         : uruk-rc            -> liverules
 uruk-save         : uruk-rc            -> activestatefile

Uruk's init behaviour <= 20050718:

 init.d/uruk stop  : inactivestatefile  -> liverules [1]
 init.d/uruk start : activestatefile    -> liverules [1]
 init.d/uruk reload: activestatefile    -> liverules [1]

Uruk's init behaviour > 20050718:

 init.d/uruk stop  : inactivestatefile  -> liverules [1]
 init.d/uruk start : liverules          -> inactivestatefile;
                     uruk-rc            -> activestatefile  ;
                     uruk-rc            -> liverules
 init.d/uruk force-reload:
                     uruk-rc            -> activestatefile  ;
                     uruk-rc            -> liverules

[1] depends on wether or not inactivestatefile and activestatefile are present.


* upgrading from uruk < 20031026

After uruk version 20031026, the hooks are no longer called rc_1, rc_2, ....
rc_10, but rc_a, ... rc_i.  rc_1 is taken over by rc_a; rc_9 and rc_10 are
taken over by rc_i.  For most situations, replacing ``-A block'' with ``-A
INPUT'' suffices to translate rc_<n> to rc_<a>.  However, please take a look at
the uruk script itself to find out.  uruk-rc(5) is updated and contains some
examples.


POST INSTALLATION STUFF

Uruk will _not_ "just work" out of the box.  It needs manual configuration.
See the uruk(8) manpage for quick setup instructions.


HACKING

Uruk version control is handled using git.  You can get a fresh copy by running

 git clone http://git.mdcc.cx/uruk.git

See http://git-scm.com/ for information about git.  (Until june 2010, the
uruk code was maintained using GNU Arch.)


MORE INFORMATION, SIMILAR TOOLS

The uruk(8), uruk-rc(5) and uruk-save(8) manpages are available in HTML format
too.  By default, they're installed in /usr/local/share/doc/uruk/html/ .

The Uruk webpage is at http://mdcc.cx/uruk/ .

Tools doing similar stuff as this script are Auke Kok's ``ferm'', available
from http://www.geo.vu.nl/~koka/ferm/ and Arno van Amersfoort's
``arno-iptables-firewall'', available from
http://rocky.eld.leidenuniv.nl/page/iptables/iptframe.htm .  Other tools, with
varying levels of userfriendlyness (or bloatedness) are: ipmasq, shorewall,
firestarter, ipmenu, fireflier, firewall-easy, fwbuilder, fwctl, gfcc, lokkit,
gnome-lokkit, gshield, guarddog, hlfl, knetfilter, mason and gshield.  Another
list of alternatives is in the "Securing Debian Manual",
http://www.debian.org/doc/manuals/securing-debian-howto/ch-sec-services.en.html#s-firewall-pack
; this howto is also available via the Debian harden-doc package.  And yet
another list is available from https://wiki.debian.org/Firewalls .


TRIVIA

Uruk is named after the city of Uruk in Mesopotamia (now Iraq), that Gilgamesh
ruled in the Epic of Gilgamesh.  This epic reads something like:

 View its strong walls, for which there is no equal.

(I only have access to a Dutch translation here, which reads:

 De muren van Oeroek, het Oeroek van de schaapskooien, liet hij bouwen.
 ...
 Bekijk zijn onvergelijkelijke borstwering.
 ...
 Bestijg de muren van Oeroek, loop erop.
 Beproef de fundering, bekijk het tichelwerk.
 Is zijn tichelwerk niet van baksteen?

.)

The city of Uruk is known under the name Erech in the bible:

  9 He was a mighty hunter before the LORD: wherefore it is said, Even as
 Nimrod the mighty hunter before the LORD.
  10 And the beginning of his kingdom was Babel, and Erech, and Accad, and
 Calneh, in the land of Shinar.
                                         Gen 10:9-10, KJV

It has nothing to do with http://www.uruk.org/ , where Erich Boleyn's Home Page
is.


# this file maintained at http://git.mdcc.cx/uruk.git
