MAIN = command.lsp
LSP = $(filter-out $(MAIN),$(wildcard *.lsp))
BIN = hourglass hourglass-web
+DOCS = hourglass-guide.html hourglass-guide.pdf
OTHER = setup.sh hourglass.conf
VERSION = 0.1
$(MAKE) -C manager
mv manager/$@ $@
-hourglass-$(VERSION).tgz: $(BIN) $(OTHER)
+hourglass-$(VERSION).tgz: $(BIN) $(OTHER) $(DOCS)
tar czf $@ $^
+%.html: %.adoc
+ asciidoctor $< > $@
+
+%.pdf: %.adoc
+ asciidoctor-pdf $< > $@
+
clean:
rm -f $(BIN) hourglass-$(VERSION).tgz
--- /dev/null
+= Hourglass
+
+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.
+
+.Hourglass System Overview
+image::hourglass-overview.png[align="center"]
+
+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.
+
+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 Hourglass web service provides an HTTP based operator interface
+for editing the applicable policy.
+
+.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+.
+
+== 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 <<Hourglass Deployment Varaibles>> 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 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.
+
+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.
+****
+
+.special variables
+****
+libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
+dynamic library.
+
+tundev = /dev/net/tun:: is the pathname for the tuntap device
+generator.
+****
+++ /dev/null
-= Hourglass
-
-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.
-
-.Hourglass System Overview
-image::hourglass-overview.png[align="center"]
-
-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.
-
-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 Hourglass web service provides an HTTP based operator interface
-for editing the applicable policy.
-
-.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+.
-
-== 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 <<Hourglass Deployment Varaibles>> 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 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.
-
-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.
-****
-
-.special variables
-****
-libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
-dynamic library.
-
-tundev = /dev/net/tun:: is the pathname for the tuntap device
-generator.
-****
projects / rrq / hourglass.git / commitdiff