X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=howto.adoc;h=0103791c9a49d246888317362c35767c5bb44a07;hb=82160a454336609f23906f49bb2378bd7b2612f8;hp=fea2a54d1dddf5169600002161d2e1c673a9cf2b;hpb=4466d2ec250322c1b603d041703259586e213b22;p=rrq%2Fhourglass.git diff --git a/howto.adoc b/howto.adoc index fea2a54..0103791 100644 --- a/howto.adoc +++ b/howto.adoc @@ -1,47 +1,240 @@ -Hourglass Howto -=============== += Hourglass -This is a collection of programs (scripts) that implement an automated -network access control policy. The general idea is to declare the open -and close times for each weekday as well as a time limit of -accumulated usage during the open time. +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. -For example, that the network should be open between 3pm and 8pm and -allow for 2 hours of usage within those times. +== Overview -The Hourglass system includes four components: +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. - 1. User interface for policy setting - 2. Continuous determination of network traffic (usage or not) - 3. Continuous determination of control action - 4. Control actuator +.Hourglass System Overview +image::hourglass-overview.png[align="center"] -.Dependencies +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. -newlisp:: -ipset:: -iptables:: +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. -Hourglass User Interface ------------------------- +The Hourglass web service provides an HTTP based operator interface +for editing the applicable policy. -This software is an HTTP service aimed at editing the Hourglass -control policy, held in the +control.dat+ file, as well as the control -override setting, in file +control-extra.dat+, whilst also showing -current usage measure from file +usage.dat+. +.Running as root -The server +hourglass-web+ is first installed with +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+. + +== Installing Hourglass + +An Hourglass system is currently distributed as a tgz file, which +should be unpacked to the depolyment directory. The unpacking should +result in a two binaries, +hourglass+ and +hourglass-web+, a shell +script , +setup.sh+, and a deplyment configuration file, ++hourglass.conf+. + +Following unpacking, the actions to take are: + + 1. Edit +hourglass.conf+ for the new deployment + 2. Start Hourglass listener daemon + 3. Start Hourglass policy bot + 4. Start Hourglass web service + + + +=== Hourglass Deployment Configuration + +The Hourglass deployment configuration is a plain file named ++hourglass.conf+ containing variable settings to configure the system +appropriately for the installation. The full list of varaiables is +documented in <> below. + +NOTE: The configuration should ideally remain unchanged after the +first installation changes. + + +== 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 +script must be run as +root+ as it includes maniplations of the +networking +iptables+ rules. + +Once started, the listener daemon remains running to continuously +update the activity log. + +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 + +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 +host, and in particular how scheduled invocations are set up on that +host. + +For a system using +cron+, an applicable +crontab+ lines looks like +the following: + +.Exsample crontab lines for regular Hourglass policy bot invocation +---- +PATH=$PATH:hourglass-installation-directory +* * * * * hourglass control-logic > /dev/null 2>&1 +---- + +// .The Hourglass Control Actuator + +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 + +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: ---- $ ./hourglass-web install ---- That installation sets up a small +www+ sub directory with "CGI" -scripting to provide the Hourglass User Interface on port 1070. +scripting to provide the Hourglass User Interface on the selected +port. + +NOTE: The Hourglass Web Service requires a front-end HTTP server. + +== APPENDIX + +=== Hourglass Deployment Variables + +This is an enumeration of all Hourglass deployment variables as +provided with the sample +hourglass.conf+. The configuration file may +also include comments, which are lines starting with semi-colon (;) or +hash (#) to end of line, and blank lines. + +.listener variables +**** +These variables are predominantly used by the Hourglass listener +daemon. + +listener.net = 192.168.123:: is the first three quads of the IP +address to use for the "listener network", with a final component +being +1+ for the host and +2+ for the listener daemon. The listener +daemon acts as a virtual host and is set up vie +setup.sh+ to receive +copies of some network packets for the purpose of measuring activity. + +listener.ports = 80 443:: is the port numbers of concern, separated by +whitespace or comma, towards activity detection. Only packets to these +ports will be considered. + +listener.activity.dir = activity :: is the directory in which the +activity files are stored. The Hourglass listener daemon operates +continuously and populates one measure per day with a full sequence of +(roughly) per-minute packet count measures. + +listener.tap = hourglass:: is the name to use for the network tap that +is set up to be the interface for the virtual listener host. +**** + +.control bot variables +**** +These variables are predominantly used by the Hourglass policy bot. + +control.action = ipset-control.lsp:: is the name of the control action +script to use. Currently only +ipset-control.lsp+ is available. + +control.dat = control.dat:: is the pathname for the policy file. The +content is a newlisp format expression; a list with sublists to +represent the desired control policy. It is typically generated by the +Hourglass web service and then used by the Hourglass control bot. + +control.net = 10.0.0.0/8:: is the IP/bits code of the network to be +controlled. + +control.extra.dat = control-extra.dat:: is the pathname for the ad-hoc +time override. This is a pair of numbers that define an overriding +"network open" time period of that many hours and minutes starting at +the modification time of the file itself + +control.usage.dat = usage.dat:: the filename to use for the usage +state. This is a newlisp expression of the current hours and minutes +of usage. The file is generated by the Hourglass policy bot to be used +and displayed via the Hourglass web service. + +control.usage.tmp = usage.tmp:: is the temporary filename to use for +the usage state update. The state update is written to this file which +then is renamed as per +control.usage.dat+; this process avoids the +risk of the Hourglass web service accessing an incompletely written +file. + +control.activity.gap = 10:: is how many minutes of low activity is +needed for identifying an idle period. + +control.activity.clip = 1000:: is the count measure limit for low +activity. +**** + +---- +; control.dat example +; Updated at Sun Aug 8 22:53:01 2021 +((1 timed (5 30) (2 0) (20 0)) + (2 timed (7 30) (1 0) (20 0)) + (3 timed (7 30) (1 0) (20 0)) + (4 timed (7 30) (1 0) (20 0)) + (5 timed (7 30) (3 0) (22 0)) + (6 timed (7 30) (1 0) (20 0)) + (7 timed (7 30) (1 0) (20 0)) + ) +---- + +.ipset control action variables +**** +These variables are used by the +ipset-control.lsp+ control action +script to translate the desire of open/closed network into control +actions of adding/removing the +control.net+ network to/from the ++ipset+ set that is set up via +setup.sh+ to constitute a blocking ++iptables+ rule for network traffic. + +ipset.bin = /sbin/ipset:: is the pathname for the +ipset+ binary. + +ipset.table = TIMO:: is the name of the ipset set. +**** + +.web service variables +**** +These variables are predominantly used by the Hourglass web service. + +wui.port = 1070:: is the port for the HTTP service. -Hourglass Network Traffic Capture ---------------------------------- +wui.passwd = .htpasswd:: is the pathname for the file of authorizable +users. Each line consists of the base64 encoding of a "user:password" +pair as is used in the HTTP Basic Authorization scheme. +**** -Hourglass Policy Bot --------------------- +.special variables +**** +libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6 +dynamic library. -Hourglass Control Actuator --------------------------- +tundev = /dev/net/tun:: is the pathname for the tuntap device +generator. +****