8 image::hourglass-logo.png[align="center"]
13 This project is a collection of programs (scripts) that implement an
14 automated network access control policy, aptly named "Hourglass". The
15 general idea is to have the network open or closed on weekly policy
16 schedule, with an easy-to-use interface for adhoc adjustments.
21 The Hourglass policy setting includes open and close times separately
22 for each weekday, as well as limits of the accumulated usage during
23 the open times. For example, one could set up Hourglass to have the
24 network open between 11am and 4pm each day, closed otherwise and each
25 day allow for 2 hours of usage. The following is a snapshot of the
26 operator web view of the policy.
28 === Operating Hourglass
30 .Hourglass Operator View
31 image::hourglass-operator.png[align="center"]
33 The operator view includes display of thecurrent usage, a control for
34 "open override", an "ascii art" graph showing a history of usage
35 timelines, and the weekly control policy setup and control.
38 === Hourglass Software Architecture
40 This policy control is accomplished by *Hourglass* as a software
41 architecture with three interlinked components that are on a "router"
42 that networking-wise is in between the sub network to control and the
45 * One component, the *Hourglass listener daemon* continuously
46 monitors the network and generates a per-minute log of how many
47 "network packets" there were in that minute. This is the measure
48 Hourglass uses to determine whether the network is in use or not so
49 as to allow for having a limit on the accumulated usage during the
52 * Another component, the *Hourglass policy bot*, is a per-minute
53 "cron bot". It looks at the recent succession of activity measures
54 to decide whether or not "usage" is happening, and then accumulates
55 usage periods into the current total daily usage time measure. It
56 regularly considers changing the networking settings as a matter of
57 effectuating the (then) current policy.
59 * The third component, *Hourglass web service*, provides tailored
60 support for operators to view and modify the policy remotely. The
61 applicable policy is actually held in plain text on the deployment
62 host and it may of course also be directly modified with a text
65 .Hourglass System Overview
66 image::hourglass-overview.png[align="center"]
69 NOTE: The Hourglass components run as +root+. It is possible to split
70 up the system into running some as +root+ and others as, say, a
71 dedicated +hourglass+ virtual user. However the boundaries between
72 these have not been fully nutted out as yet, so at present all is run
75 == Installing Hourglass
77 An Hourglass system is currently distributed as a tgz file, which
78 should be unpacked to the depolyment directory. The unpacking should
79 result in a two binaries, +hourglass+ and +hourglass-web+, a shell
80 script , +setup.sh+, and a deplyment configuration file,
83 Following unpacking, the actions to take are:
85 1. Edit +hourglass.conf+ for the new deployment
86 2. Start Hourglass listener daemon
87 3. Start Hourglass policy bot
88 4. Start Hourglass web service
92 === Hourglass Deployment Configuration
94 The Hourglass deployment configuration is a plain file named
95 +hourglass.conf+ containing variable settings to configure the system
96 appropriately for the installation. The full list of varaiables is
97 documented in <<Hourglass Deployment Varaibles>> below.
99 NOTE: The configuration should ideally remain unchanged after the
100 first installation changes.
103 === Hourglass Listener Daemon
105 The Hourglass listener bot is adminstered via the +setup.sh+ control
106 script, using command line action arguments of +start+ or +stop+. This
107 script must be run as +root+ as it includes maniplations of the
108 networking +iptables+ rules.
110 Once started, the listener daemon remains running to continuously
111 update the activity log.
113 NOTE: The listener daemon is a network entity like a virtual host, and
114 by means of an +iptables+ +TEE+ rule it also receives copies of the
115 monitored network packets.
117 === Hourglass Policy Bot
119 The Hourglass policy bot needs to be set up as a +cron+ bot that
120 executes once a minute. How this is done depends on the deployment
121 host, and in particular how scheduled invocations are set up on that
124 For a system using +cron+, an applicable +crontab+ lines looks like
127 .Exsample crontab lines for regular Hourglass policy bot invocation
129 PATH=$PATH:hourglass-installation-directory
130 * * * * * hourglass control-logic > /dev/null 2>&1
133 // .The Hourglass Control Actuator
135 NOTE: The policy bot performs it control actions via an "ipset
136 actuator", which adds or removes the IP address detail of the
137 controlled network to (from) the dedicated +ipset+ set.
139 === Hourglass Web Service
141 The Hourglass web service is a CGI service aimed at editing the
142 Hourglass control policy through a simple HTML for page that also
143 includes a presentation of current usage and an optional control
146 The CGI service is wrapped into a single binary +hourglass-web+ that
147 recognises its invocation name (link name), and the service as a whole
148 is installed with the following:
150 $ ./hourglass-web install
152 That installation sets up a small +www+ sub directory with "CGI"
153 scripting to provide the Hourglass User Interface on the selected
156 NOTE: The Hourglass Web Service requires a front-end HTTP server.
161 === Hourglass Deployment Variables
163 This is an enumeration of all Hourglass deployment variables as
164 provided with the sample +hourglass.conf+. The configuration file may
165 also include comments, which are lines starting with semi-colon (;) or
166 hash (#) to end of line, and blank lines.
170 These variables are predominantly used by the Hourglass listener
173 listener.net = 192.168.123:: is the first three quads of the IP
174 address to use for the "listener network", with a final component
175 being +1+ for the host and +2+ for the listener daemon. The listener
176 daemon acts as a virtual host and is set up vie +setup.sh+ to receive
177 copies of some network packets for the purpose of measuring activity.
179 listener.ports = 80 443:: is the port numbers of concern, separated by
180 whitespace or comma, towards activity detection. Only packets to these
181 ports will be considered.
183 listener.activity.dir = activity :: is the directory in which the
184 activity files are stored. The Hourglass listener daemon operates
185 continuously and populates one measure per day with a full sequence of
186 (roughly) per-minute packet count measures.
188 listener.tap = hourglass:: is the name to use for the network tap that
189 is set up to be the interface for the virtual listener host.
192 .control bot variables
194 These variables are predominantly used by the Hourglass policy bot.
196 control.action = ipset-control.lsp:: is the name of the control action
197 script to use. Currently only +ipset-control.lsp+ is available.
199 control.dat = control.dat:: is the pathname for the policy file. The
200 content is a newlisp format expression; a list with sublists to
201 represent the desired control policy. It is typically generated by the
202 Hourglass web service and then used by the Hourglass control bot.
204 control.net = 10.0.0.0/8:: is the IP/bits code of the network to be
207 control.extra.dat = control-extra.dat:: is the pathname for the ad-hoc
208 time override. This is a pair of numbers that define an overriding
209 "network open" time period of that many hours and minutes starting at
210 the modification time of the file itself
212 control.usage.dat = usage.dat:: the filename to use for the usage
213 state. This is a newlisp expression of the current hours and minutes
214 of usage. The file is generated by the Hourglass policy bot to be used
215 and displayed via the Hourglass web service.
217 control.usage.tmp = usage.tmp:: is the temporary filename to use for
218 the usage state update. The state update is written to this file which
219 then is renamed as per +control.usage.dat+; this process avoids the
220 risk of the Hourglass web service accessing an incompletely written
223 control.activity.gap = 10:: is how many minutes of low activity is
224 needed for identifying an idle period.
226 control.activity.clip = 1000:: is the count measure limit for low
231 ; control.dat example
232 ; Updated at Sun Aug 8 22:53:01 2021
233 ((1 timed (5 30) (2 0) (20 0))
234 (2 timed (7 30) (1 0) (20 0))
235 (3 timed (7 30) (1 0) (20 0))
236 (4 timed (7 30) (1 0) (20 0))
237 (5 timed (7 30) (3 0) (22 0))
238 (6 timed (7 30) (1 0) (20 0))
239 (7 timed (7 30) (1 0) (20 0))
243 .ipset control action variables
245 These variables are used by the +ipset-control.lsp+ control action
246 script to translate the desire of open/closed network into control
247 actions of adding/removing the +control.net+ network to/from the
248 +ipset+ set that is set up via +setup.sh+ to constitute a blocking
249 +iptables+ rule for network traffic.
251 ipset.bin = /sbin/ipset:: is the pathname for the +ipset+ binary.
253 ipset.table = TIMO:: is the name of the ipset set.
256 .web service variables
258 These variables are predominantly used by the Hourglass web service.
260 wui.port = 1070:: is the port for the HTTP service.
262 wui.passwd = .htpasswd:: is the pathname for the file of authorizable
263 users. Each line consists of the base64 encoding of a "user:password"
264 pair as is used in the HTTP Basic Authorization scheme.
269 libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
272 tundev = /dev/net/tun:: is the pathname for the tuntap device