From: Ralph Ronnquist Date: Mon, 3 Jan 2022 13:48:33 +0000 (+1100) Subject: include docs in dist X-Git-Tag: 0.1~13 X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=c58461cf6ea38f43cdaeae95bb9d8204651eaf70;p=rrq%2Fhourglass.git include docs in dist --- diff --git a/Makefile b/Makefile index c6977ec..999f4c9 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ 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 @@ -13,8 +14,14 @@ hourglass-web: $(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 diff --git a/hourglass-guide.adoc b/hourglass-guide.adoc new file mode 100644 index 0000000..0103791 --- /dev/null +++ b/hourglass-guide.adoc @@ -0,0 +1,240 @@ += 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 <> 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. +**** diff --git a/howto.adoc b/howto.adoc deleted file mode 100644 index 0103791..0000000 --- a/howto.adoc +++ /dev/null @@ -1,240 +0,0 @@ -= 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 <> 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. -****