From: Ralph Ronnquist Date: Tue, 4 Jan 2022 23:38:16 +0000 (+1100) Subject: editorial X-Git-Tag: 0.1~12 X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=5776a37ab6a4d7fc626e490ac9054f077516644b;p=rrq%2Fhourglass.git editorial --- diff --git a/hourglass-guide.adoc b/hourglass-guide.adoc index 0103791..cbdd7e5 100644 --- a/hourglass-guide.adoc +++ b/hourglass-guide.adoc @@ -1,39 +1,76 @@ -= Hourglass += Hourglass 0.1 +:bl: pass:[ +] + +{bl} +{bl} +{bl} + +image::hourglass-logo.png[align="center"] + +{bl} +{bl} 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 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. +the open times. For example, one could set up Hourglass to have the +network open between 11am and 4pm each day, closed otherwise and each +day allow for 2 hours of usage. The following is a snapshot of the +operator web view of the policy. -.Hourglass System Overview -image::hourglass-overview.png[align="center"] +=== Operating Hourglass -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. +.Hourglass Operator View +image::hourglass-operator.png[align="center"] -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. +The operator view includes display of thecurrent usage, a control for +"open override", an "ascii art" graph showing a history of usage +timelines, and the weekly control policy setup and control. + +<<<<<<<<<< +=== Hourglass Software Architecture + +This policy control is accomplished by *Hourglass* as a software +architecture with three interlinked components that are on a "router" +that networking-wise is in between the sub network to control and the +Internet. + + * One component, the *Hourglass listener daemon* continuously + monitors the network and generates a per-minute log of how many + "network packets" there were in that minute. This is the measure + Hourglass uses to determine whether the network is in use or not so + as to allow for having a limit on the accumulated usage during the + open time. + + * Another component, the *Hourglass policy bot*, is a per-minute + "cron bot". It looks at the recent succession of activity measures + to decide whether or not "usage" is happening, and then accumulates + usage periods into the current total daily usage time measure. It + regularly considers changing the networking settings as a matter of + effectuating the (then) current policy. + + * The third component, *Hourglass web service*, provides tailored + support for operators to view and modify the policy remotely. The + applicable policy is actually held in plain text on the deployment + host and it may of course also be directly modified with a text + editor. -The Hourglass web service provides an HTTP based operator interface -for editing the applicable policy. +.Hourglass System Overview +image::hourglass-overview.png[align="center"] -.Running as root -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+. +NOTE: The Hourglass components run as +root+. It is possible to split +up the system into running some as +root+ and others as, say, a +dedicated +hourglass+ virtual user. However the boundaries between +these have not been fully nutted out as yet, so at present all is run +as +root+. == Installing Hourglass @@ -63,7 +100,7 @@ NOTE: The configuration should ideally remain unchanged after the first installation changes. -== Hourglass Listener Daemon +=== 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 @@ -77,7 +114,7 @@ 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 +=== 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 @@ -99,17 +136,13 @@ 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 +=== 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: @@ -122,6 +155,7 @@ port. NOTE: The Hourglass Web Service requires a front-end HTTP server. +<<<<<<<<<< == APPENDIX === Hourglass Deployment Variables diff --git a/hourglass-logo.png b/hourglass-logo.png new file mode 100644 index 0000000..1511183 Binary files /dev/null and b/hourglass-logo.png differ diff --git a/hourglass-overview.png b/hourglass-overview.png index 8ab71d0..f3ad942 100644 Binary files a/hourglass-overview.png and b/hourglass-overview.png differ