-Hourglass HOWTO
-===============
+= Hourglass
This project is a collection of programs (scripts) that implement an
automated network access control policy, aptly named "Hourglass". The
general idea is to have the network open or closed on weekly policy
schedule, with an easy-to-use interface for adhoc adjustments.
-Overview
---------
+== Overview
The Hourglass policy setting includes open and close times separately
for each weekday, as well as limits of the accumulated usage during
The Hourglass web service provides an HTTP based operator interface
for editing the applicable policy.
+.Running as root
-Installing Hourglass
---------------------
+It is possible to split up the system into parts run as +root+ and
+parts run as dedicated a dedicated, say +hourglass+ user. However the
+boundaries between these have not been fully nutted out as yet, so at
+present all is run as +root+.
+== Installing Hourglass
+An Hourglass system is currently distributed as a tgz file, which
+should be unpacked to the depolyment directory. The unpacking should
+result in a two binaries, +hourglass+ and +hourglass-web+, a shell
+script , +setup.sh+, and a deplyment configuration file,
++hourglass.conf+.
-The Hourglass system includes four components:
+Following unpacking, the actions to take are:
- 1. User interface for policy setting
- 2. Continuous determination of network traffic (usage or not)
- 3. Continuous determination of control action
- 4. Control actuator
+ 1. Edit +hourglass.conf+ for the new deployment
+ 2. Start Hourglass listener daemon
+ 3. Start Hourglass policy bot
+ 4. Start Hourglass web service
-Hourglass User Interface
-------------------------
-This software is an HTTP service aimed at editing the Hourglass
-control policy, held in the +control.dat+ file, as well as the control
-override setting, in file +control-extra.dat+, whilst also showing
-current usage measure from file +usage.dat+.
+=== Hourglass Deployment Configuration
-The server +hourglass-web+ is first installed with
+The Hourglass deployment configuration is a plain file named
++hourglass.conf+ containing variable settings to configure the system
+appropriately for the installation. The full list of varaiables is
+documented in <<Hourglass Deployment Varaibles>> below.
+
+NOTE: The configuration should ideally remain unchanged after the
+first installation changes.
+
+
+== Hourglass Listener Daemon
+
+The Hourglass listener bot is adminstered via the +setup.sh+ control
+script, using command line action arguments of +start+ or +stop+. This
+script must be run as +root+ as it includes maniplations of the
+networking +iptables+ rules.
+
+Once started, the listener daemon remains running to continuously
+update the activity log.
+
+NOTE: The listener daemon is a network entity like a virtual host, and
+by means of an +iptables+ +TEE+ rule it also receives copies of the
+monitored network packets.
+
+== Hourglass Policy Bot
+
+The Hourglass policy bot needs to be set up as a +cron+ bot that
+executes once a minute. How this is done depends on the deployment
+host, and in particular how scheduled invocations are set up on that
+host.
+
+For a system using +cron+, an applicable +crontab+ lines looks like
+the following:
+
+.Exsample crontab lines for regular Hourglass policy bot invocation
+----
+PATH=$PATH:hourglass-installation-directory
+* * * * * hourglass control-logic > /dev/null 2>&1
+----
+
+// .The Hourglass Control Actuator
+
+NOTE: The policy bot performs it control actions via an "ipset
+actuator", which adds or removes the IP address detail of the
+controlled network to (from) the dedicated +ipset+ set.
+
+== Hourglass Web Service
+
+The Hourglass web service is a CGI service aimed at editing the
+Hourglass control policy through a simple HTML for page that also
+includes a presentation of current usage and an optional control
+override.
+
+.Hourglass Operator View
+image::hourglass-operator.png[align="center"]
+
+
+The CGI service is wrapped into a single binary +hourglass-web+ that
+recognises its invocation name (link name), and the service as a whole
+is installed with the following:
----
$ ./hourglass-web install
----
That installation sets up a small +www+ sub directory with "CGI"
-scripting to provide the Hourglass User Interface on port 1070.
+scripting to provide the Hourglass User Interface on the selected
+port.
+
+NOTE: The Hourglass Web Service requires a front-end HTTP server.
+
+== APPENDIX
+
+=== Hourglass Deployment Variables
+
+This is an enumeration of all Hourglass deployment variables as
+provided with the sample +hourglass.conf+. The configuration file may
+also include comments, which are lines starting with semi-colon (;) or
+hash (#) to end of line, and blank lines.
+
+.listener variables
+****
+These variables are predominantly used by the Hourglass listener
+daemon.
+
+listener.net = 192.168.123:: is the first three quads of the IP
+address to use for the "listener network", with a final component
+being +1+ for the host and +2+ for the listener daemon. The listener
+daemon acts as a virtual host and is set up vie +setup.sh+ to receive
+copies of some network packets for the purpose of measuring activity.
+
+listener.ports = 80 443:: is the port numbers of concern, separated by
+whitespace or comma, towards activity detection. Only packets to these
+ports will be considered.
+
+listener.activity.dir = activity :: is the directory in which the
+activity files are stored. The Hourglass listener daemon operates
+continuously and populates one measure per day with a full sequence of
+(roughly) per-minute packet count measures.
+
+listener.tap = hourglass:: is the name to use for the network tap that
+is set up to be the interface for the virtual listener host.
+****
+
+.control bot variables
+****
+These variables are predominantly used by the Hourglass policy bot.
+
+control.action = ipset-control.lsp:: is the name of the control action
+script to use. Currently only +ipset-control.lsp+ is available.
+
+control.dat = control.dat:: is the pathname for the policy file. The
+content is a newlisp format expression; a list with sublists to
+represent the desired control policy. It is typically generated by the
+Hourglass web service and then used by the Hourglass control bot.
+
+control.net = 10.0.0.0/8:: is the IP/bits code of the network to be
+controlled.
+
+control.extra.dat = control-extra.dat:: is the pathname for the ad-hoc
+time override. This is a pair of numbers that define an overriding
+"network open" time period of that many hours and minutes starting at
+the modification time of the file itself
+
+control.usage.dat = usage.dat:: the filename to use for the usage
+state. This is a newlisp expression of the current hours and minutes
+of usage. The file is generated by the Hourglass policy bot to be used
+and displayed via the Hourglass web service.
+
+control.usage.tmp = usage.tmp:: is the temporary filename to use for
+the usage state update. The state update is written to this file which
+then is renamed as per +control.usage.dat+; this process avoids the
+risk of the Hourglass web service accessing an incompletely written
+file.
+
+control.activity.gap = 10:: is how many minutes of low activity is
+needed for identifying an idle period.
+
+control.activity.clip = 1000:: is the count measure limit for low
+activity.
+****
+
+----
+; control.dat example
+; Updated at Sun Aug 8 22:53:01 2021
+((1 timed (5 30) (2 0) (20 0))
+ (2 timed (7 30) (1 0) (20 0))
+ (3 timed (7 30) (1 0) (20 0))
+ (4 timed (7 30) (1 0) (20 0))
+ (5 timed (7 30) (3 0) (22 0))
+ (6 timed (7 30) (1 0) (20 0))
+ (7 timed (7 30) (1 0) (20 0))
+ )
+----
+
+.ipset control action variables
+****
+These variables are used by the +ipset-control.lsp+ control action
+script to translate the desire of open/closed network into control
+actions of adding/removing the +control.net+ network to/from the
++ipset+ set that is set up via +setup.sh+ to constitute a blocking
++iptables+ rule for network traffic.
+
+ipset.bin = /sbin/ipset:: is the pathname for the +ipset+ binary.
+
+ipset.table = TIMO:: is the name of the ipset set.
+****
+
+.web service variables
+****
+These variables are predominantly used by the Hourglass web service.
+
+wui.port = 1070:: is the port for the HTTP service.
-Hourglass Network Traffic Capture
----------------------------------
+wui.passwd = .htpasswd:: is the pathname for the file of authorizable
+users. Each line consists of the base64 encoding of a "user:password"
+pair as is used in the HTTP Basic Authorization scheme.
+****
-Hourglass Policy Bot
---------------------
+.special variables
+****
+libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
+dynamic library.
-Hourglass Control Actuator
---------------------------
+tundev = /dev/net/tun:: is the pathname for the tuntap device
+generator.
+****
projects / rrq / hourglass.git / commitdiff
