hourglass-guide.adoc

   1 = Hourglass
   2
   3 This project is a collection of programs (scripts) that implement an
   4 automated network access control policy, aptly named "Hourglass". The
   5 general idea is to have the network open or closed on weekly policy
   6 schedule, with an easy-to-use interface for adhoc adjustments.
   7
   8 == Overview
   9
  10 The Hourglass policy setting includes open and close times separately
  11 for each weekday, as well as limits of the accumulated usage during
  12 the open times. For example, one could set up the network to be open
  13 between 11am and 4pm each day and each day allow for 2 hours of usage.
  14
  15 .Hourglass System Overview
  16 image::hourglass-overview.png[align="center"]
  17
  18 Network "usage" is determine by the "Hourglass listener daemon" that
  19 is set up to review network traffic and continuously register
  20 per-minute packet count measures.
  21
  22 The "Hourglass policy bot" is a per-minute "cron bot" that looks at
  23 the recent succession of measures to decide whether or not "usage" is
  24 happening and accumulate usage periods into the current daily usage
  25 time measure. It is the policy contol bot that performs the control
  26 actions of closing or opening the network for traffic.
  27
  28 The Hourglass web service provides an HTTP based operator interface
  29 for editing the applicable policy.
  30
  31 .Running as root
  32
  33 It is possible to split up the system into parts run as +root+ and
  34 parts run as dedicated a dedicated, say +hourglass+ user. However the
  35 boundaries between these have not been fully nutted out as yet, so at
  36 present all is run as +root+.
  37
  38 == Installing Hourglass
  39
  40 An Hourglass system is currently distributed as a tgz file, which
  41 should be unpacked to the depolyment directory. The unpacking should
  42 result in a two binaries, +hourglass+ and +hourglass-web+, a shell
  43 script , +setup.sh+, and a deplyment configuration file,
  44 +hourglass.conf+.
  45
  46 Following unpacking, the actions to take are:
  47
  48  1. Edit +hourglass.conf+ for the new deployment
  49  2. Start Hourglass listener daemon
  50  3. Start Hourglass policy bot
  51  4. Start Hourglass web service
  52
  53
  54
  55 === Hourglass Deployment Configuration
  56
  57 The Hourglass deployment configuration is a plain file named
  58 +hourglass.conf+ containing variable settings to configure the system
  59 appropriately for the installation. The full list of varaiables is
  60 documented in <<Hourglass Deployment Varaibles>> below.
  61
  62 NOTE: The configuration should ideally remain unchanged after the
  63 first installation changes.
  64
  65
  66 == Hourglass Listener Daemon
  67
  68 The Hourglass listener bot is adminstered via the +setup.sh+ control
  69 script, using command line action arguments of +start+ or +stop+. This
  70 script must be run as +root+ as it includes maniplations of the
  71 networking +iptables+ rules.
  72
  73 Once started, the listener daemon remains running to continuously
  74 update the activity log.
  75
  76 NOTE: The listener daemon is a network entity like a virtual host, and
  77 by means of an +iptables+ +TEE+ rule it also receives copies of the
  78 monitored network packets.
  79
  80 == Hourglass Policy Bot
  81
  82 The Hourglass policy bot needs to be set up as a +cron+ bot that
  83 executes once a minute. How this is done depends on the deployment
  84 host, and in particular how scheduled invocations are set up on that
  85 host.
  86
  87 For a system using +cron+, an applicable +crontab+ lines looks like
  88 the following:
  89
  90 .Exsample crontab lines for regular Hourglass policy bot invocation
  91 ----
  92 PATH=$PATH:hourglass-installation-directory
  93 * * * * * hourglass control-logic > /dev/null 2>&1
  94 ----
  95
  96 // .The Hourglass Control Actuator
  97
  98 NOTE: The policy bot performs it control actions via an "ipset
  99 actuator", which adds or removes the IP address detail of the
 100 controlled network to (from) the dedicated +ipset+ set.
 101
 102 == Hourglass Web Service
 103
 104 The Hourglass web service is a CGI service aimed at editing the
 105 Hourglass control policy through a simple HTML for page that also
 106 includes a presentation of current usage and an optional control
 107 override.
 108
 109 .Hourglass Operator View
 110 image::hourglass-operator.png[align="center"]
 111
 112
 113 The CGI service is wrapped into a single binary +hourglass-web+ that
 114 recognises its invocation name (link name), and the service as a whole
 115 is installed with the following:
 116 ----
 117 $ ./hourglass-web install
 118 ----
 119 That installation sets up a small +www+ sub directory with "CGI"
 120 scripting to provide the Hourglass User Interface on the selected
 121 port.
 122
 123 NOTE: The Hourglass Web Service requires a front-end HTTP server.
 124
 125 == APPENDIX
 126
 127 === Hourglass Deployment Variables
 128
 129 This is an enumeration of all Hourglass deployment variables as
 130 provided with the sample +hourglass.conf+. The configuration file may
 131 also include comments, which are lines starting with semi-colon (;) or
 132 hash (#) to end of line, and blank lines.
 133
 134 .listener variables
 135 ****
 136 These variables are predominantly used by the Hourglass listener
 137 daemon.
 138
 139 listener.net = 192.168.123:: is the first three quads of the IP
 140 address to use for the "listener network", with a final component
 141 being +1+ for the host and +2+ for the listener daemon. The listener
 142 daemon acts as a virtual host and is set up vie +setup.sh+ to receive
 143 copies of some network packets for the purpose of measuring activity.
 144
 145 listener.ports = 80 443:: is the port numbers of concern, separated by
 146 whitespace or comma, towards activity detection. Only packets to these
 147 ports will be considered.
 148
 149 listener.activity.dir = activity :: is the directory in which the
 150 activity files are stored. The Hourglass listener daemon operates
 151 continuously and populates one measure per day with a full sequence of
 152 (roughly) per-minute packet count measures.
 153
 154 listener.tap = hourglass:: is the name to use for the network tap that
 155 is set up to be the interface for the virtual listener host.
 156 ****
 157
 158 .control bot variables
 159 ****
 160 These variables are predominantly used by the Hourglass policy bot.
 161
 162 control.action = ipset-control.lsp:: is the name of the control action
 163 script to use. Currently only +ipset-control.lsp+ is available.
 164
 165 control.dat = control.dat:: is the pathname for the policy file. The
 166 content is a newlisp format expression; a list with sublists to
 167 represent the desired control policy. It is typically generated by the
 168 Hourglass web service and then used by the Hourglass control bot.
 169
 170 control.net = 10.0.0.0/8:: is the IP/bits code of the network to be
 171 controlled.
 172
 173 control.extra.dat = control-extra.dat:: is the pathname for the ad-hoc
 174 time override. This is a pair of numbers that define an overriding
 175 "network open" time period of that many hours and minutes starting at
 176 the modification time of the file itself
 177
 178 control.usage.dat = usage.dat:: the filename to use for the usage
 179 state. This is a newlisp expression of the current hours and minutes
 180 of usage. The file is generated by the Hourglass policy bot to be used
 181 and displayed via the Hourglass web service.
 182
 183 control.usage.tmp = usage.tmp:: is the temporary filename to use for
 184 the usage state update. The state update is written to this file which
 185 then is renamed as per +control.usage.dat+; this process avoids the
 186 risk of the Hourglass web service accessing an incompletely written
 187 file.
 188
 189 control.activity.gap = 10:: is how many minutes of low activity is
 190 needed for identifying an idle period.
 191
 192 control.activity.clip = 1000:: is the count measure limit for low
 193 activity.
 194 ****
 195
 196 ----
 197 ; control.dat example
 198 ; Updated at Sun Aug  8 22:53:01 2021
 199 ((1 timed (5 30) (2 0) (20 0))
 200  (2 timed (7 30) (1 0) (20 0))
 201  (3 timed (7 30) (1 0) (20 0))
 202  (4 timed (7 30) (1 0) (20 0))
 203  (5 timed (7 30) (3 0) (22 0))
 204  (6 timed (7 30) (1 0) (20 0))
 205  (7 timed (7 30) (1 0) (20 0))
 206  )
 207 ----
 208
 209 .ipset control action variables
 210 ****
 211 These variables are used by the +ipset-control.lsp+ control action
 212 script to translate the desire of open/closed network into control
 213 actions of adding/removing the +control.net+ network to/from the
 214 +ipset+ set that is set up via +setup.sh+ to constitute a blocking
 215 +iptables+ rule for network traffic.
 216
 217 ipset.bin = /sbin/ipset:: is the pathname for the +ipset+ binary.
 218
 219 ipset.table = TIMO:: is the name of the ipset set.
 220 ****
 221
 222 .web service variables
 223 ****
 224 These variables are predominantly used by the Hourglass web service.
 225
 226 wui.port = 1070:: is the port for the HTTP service.
 227
 228 wui.passwd = .htpasswd:: is the pathname for the file of authorizable
 229 users. Each line consists of the base64 encoding of a "user:password"
 230 pair as is used in the HTTP Basic Authorization scheme.
 231 ****
 232
 233 .special variables
 234 ****
 235 libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
 236 dynamic library.
 237
 238 tundev = /dev/net/tun:: is the pathname for the tuntap device
 239 generator.
 240 ****