-Hourglass Howto
-===============
+= Hourglass
-This is a collection of programs (scripts) that implement an automated
-network access control policy. The general idea is to declare the open
-and close times for each weekday as well as a time limit of
-accumulated usage during the open time.
+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.
-For example, that the network should be open between 3pm and 8pm and
-allow for 2 hours of usage within those times.
+== Overview
-The Hourglass system includes four components:
+The Hourglass policy setting includes open and close times separately
+for each weekday, as well as limits of the accumulated usage during
+the open times. For example, one could set up the network to be open
+between 11am and 4pm each day and each day allow for 2 hours of usage.
- 1. User interface for policy setting
- 2. Continuous determination of network traffic (usage or not)
- 3. Continuous determination of control action
- 4. Control actuator
+.Hourglass System Overview
+image::hourglass-overview.png[align="center"]
-.Dependencies
+Network "usage" is determine by the "Hourglass listener daemon" that
+is set up to review network traffic and continuously register
+per-minute packet count measures.
-newlisp::
-ipset::
-iptables::
+The "Hourglass policy bot" is a per-minute "cron bot" that looks at
+the recent succession of measures to decide whether or not "usage" is
+happening and accumulate usage periods into the current daily usage
+time measure. It is the policy contol bot that performs the control
+actions of closing or opening the network for traffic.
-Hourglass User Interface
-------------------------
+The Hourglass web service provides an HTTP based operator interface
+for editing the applicable policy.
-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+.
+.Running as root
-The server +hourglass-web+ is first installed with
+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+.
+
+Following unpacking, the actions to take are:
+
+ 1. Edit +hourglass.conf+ for the new deployment
+ 2. Start Hourglass listener daemon
+ 3. Start Hourglass policy bot
+ 4. Start Hourglass web service
+
+
+
+=== Hourglass Deployment Configuration
+
+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 / blobdiff