hourglass-guide.adoc

   1 = Hourglass 0.1
   2 :bl: pass:[ +]
   3
   4 {bl}
   5 {bl}
   6 {bl}
   7
   8 image::hourglass-logo.png[align="center"]
   9
  10 {bl}
  11 {bl}
  12
  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.
  17
  18 <<<<<<<<<<
  19 == Overview
  20
  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.
  27
  28 === Operating Hourglass
  29
  30 .Hourglass Operator View
  31 image::hourglass-operator.png[align="center"]
  32
  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.
  36
  37 <<<<<<<<<<
  38 === Hourglass Software Architecture
  39
  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
  43 Internet.
  44
  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
  50    open time.
  51
  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.
  58
  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
  63    editor.
  64
  65 .Hourglass System Overview
  66 image::hourglass-overview.png[align="center"]
  67
  68
  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
  73 as +root+.
  74
  75 == Installing Hourglass
  76
  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,
  81 +hourglass.conf+.
  82
  83 Following unpacking, the actions to take are:
  84
  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
  89
  90
  91
  92 === Hourglass Deployment Configuration
  93
  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.
  98
  99 NOTE: The configuration should ideally remain unchanged after the
 100 first installation changes.
 101
 102
 103 === Hourglass Listener Daemon
 104
 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.
 109
 110 Once started, the listener daemon remains running to continuously
 111 update the activity log.
 112
 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.
 116
 117 === Hourglass Policy Bot
 118
 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
 122 host.
 123
 124 For a system using +cron+, an applicable +crontab+ lines looks like
 125 the following:
 126
 127 .Exsample crontab lines for regular Hourglass policy bot invocation
 128 ----
 129 PATH=$PATH:hourglass-installation-directory
 130 * * * * * hourglass control-logic > /dev/null 2>&1
 131 ----
 132
 133 // .The Hourglass Control Actuator
 134
 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.
 138
 139 === Hourglass Web Service
 140
 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
 144 override.
 145
 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:
 149 ----
 150 $ ./hourglass-web install
 151 ----
 152 That installation sets up a small +www+ sub directory with "CGI"
 153 scripting to provide the Hourglass User Interface on the selected
 154 port.
 155
 156 NOTE: The Hourglass Web Service requires a front-end HTTP server.
 157
 158 <<<<<<<<<<
 159 == APPENDIX
 160
 161 === Hourglass Deployment Variables
 162
 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.
 167
 168 .listener variables
 169 ****
 170 These variables are predominantly used by the Hourglass listener
 171 daemon.
 172
 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.
 178
 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.
 182
 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.
 187
 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.
 190 ****
 191
 192 .control bot variables
 193 ****
 194 These variables are predominantly used by the Hourglass policy bot.
 195
 196 control.action = ipset-control.lsp:: is the name of the control action
 197 script to use. Currently only +ipset-control.lsp+ is available.
 198
 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.
 203
 204 control.net = 10.0.0.0/8:: is the IP/bits code of the network to be
 205 controlled.
 206
 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
 211
 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.
 216
 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
 221 file.
 222
 223 control.activity.gap = 10:: is how many minutes of low activity is
 224 needed for identifying an idle period.
 225
 226 control.activity.clip = 1000:: is the count measure limit for low
 227 activity.
 228 ****
 229
 230 ----
 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))
 240  )
 241 ----
 242
 243 .ipset control action variables
 244 ****
 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.
 250
 251 ipset.bin = /sbin/ipset:: is the pathname for the +ipset+ binary.
 252
 253 ipset.table = TIMO:: is the name of the ipset set.
 254 ****
 255
 256 .web service variables
 257 ****
 258 These variables are predominantly used by the Hourglass web service.
 259
 260 wui.port = 1070:: is the port for the HTTP service.
 261
 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.
 265 ****
 266
 267 .special variables
 268 ****
 269 libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
 270 dynamic library.
 271
 272 tundev = /dev/net/tun:: is the pathname for the tuntap device
 273 generator.
 274 ****