editorial

diff --git a/hourglass-guide.adoc b/hourglass-guide.adoc
index 0103791c9a49d246888317362c35767c5bb44a07..cbdd7e513ecd4a86377070b022aacae68be46b67 100644 (file)
--- 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 (file)
index 0000000..1511183
Binary files /dev/null and b/hourglass-logo.png differ

diff --git a/hourglass-overview.png b/hourglass-overview.png
index 8ab71d003dea38ff920fc80fd7548a2c27199ecd..f3ad942ed30cb742df8e580231660f885cc16f11 100644 (file)
Binary files a/hourglass-overview.png and b/hourglass-overview.png differ