From 8d6b01f086cda032f1b72620e84bf3e5b4d5be19 Mon Sep 17 00:00:00 2001 From: onefang Date: Thu, 6 Feb 2020 14:43:30 +1000 Subject: Clean up the README, add some more text, remove the theory part. --- README.md | 132 +++++++++++++------------------------------------------------- 1 file changed, 26 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index 9ff79f2..94eebbf 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,15 @@ badgered him about his Python scripts. It should also be much easier to use, the previous scripts needed some work before you could run them, this one you just download and run. -The source code is at [https://sledjhamr.org/cgit/apt-panopticon/](https://sledjhamr.org/cgit/apt-panopticon/) +After a discussion, it is likely that apt-panopticon will be used to +automatically decide which Devuan mirrors are in the DNS round robin. +The details of that are yet to be determined. + + +You can get the source code from [https://sledjhamr.org/cgit/apt-panopticon/](https://sledjhamr.org/cgit/apt-panopticon/) (main repo) +and [https://git.devuan.org/onefang/apt-panopticon](https://git.devuan.org/onefang/apt-panopticon) (Devuan repo). +You can get the cgp graphing source code from [https://sledjhamr.org/cgit/apt-panopticon_cgp/]() (main repo) +and [https://git.devuan.org/onefang/apt-panopticon_cgp](https://git.devuan.org/onefang/apt-panopticon_cgp) (Devuan repo). The issue tracker is at [https://sledjhamr.org/mantisbt/project_page.php?project_id=13](https://sledjhamr.org/mantisbt/project_page.php?project_id=13) @@ -56,13 +64,14 @@ If you want to have lots of graphs, also install For the apt-panopticon_cgp package, which is used to show the detailed graphs, you'll need a web server that supports PHP. apt-panopticon_cgp includes some support files for running PHP via CGI, which more web -servers support. You'll need php-cgi for that. +servers support. You'll need php-cgi for that. It's been tested with +recent versions of Apache 2 and Lightttpd. Web installation. ----------------- -This is a suggestion for installation on a Devuan based web server. +This is a suggestion for installation on a Devuan based web server. Create - @@ -74,7 +83,7 @@ Install apt-panopticon and apt-panopticon_cgp there, so you end up with - /var/www/html/apt-panopticon/apt-panopticon_cgp The script update_apt-panopticon is an example script for updating -everything, including commented out commands to update the source code. +everything, including commented out commands to update the source code. The file apt-panopticron is an example crontab file for updating everything once every ten minutes. They assume your web server user is www-data with a group of www-data, and you have a mirror user called @@ -82,9 +91,8 @@ mirrors. For mirror operators, that mirrors user would be the owner of the mirror files. You can change these to suite yourself. Once everything is updated, -/var/www/html/apt-panopticon/results/Report-web.html -will point to the main web page, and there will be a link at the bottom of -that pointing to the detailed graphs. +/var/www/html/apt-panopticon/results/Report-web.html will point to the +main web page, and there will be links that point to the detailed graphs. Note that two runs of apt-panopticon have to happen ten minutes apart at least in order to see any data on the graphs. @@ -98,9 +106,7 @@ Using it. These examples assume you are running it from the source code directory. A directory will be created called `results`, it'll be full of log files -and any files that get downloaded. There will also be `results/email` -and `results/web` directories, with the notification emails and web pages -(once I write that bit). +and any files that get downloaded. Note that unlike typical commands, you can't run single character options together, so this is wrong - @@ -115,12 +121,12 @@ Just run the script to do all of the tests - $ ./apt-panopticon.lua -Which will print any errors. If you don't want to see errors - +Which will print any CRITICAL errors. If you don't want to see errors - $ ./apt-panopticon.lua -q -If you want to see warnings as well (as usual, the more `-v` options, the more -details) - +If you want to see other errors, warnings, and even more details as well +(as usual, the more `-v` options, the more details) - $ ./apt-panopticon.lua -v @@ -184,7 +190,8 @@ and check all of it's IPs, which are the DNS RR mirrors anyway. The mirror_list.txt file also used to select which protocols to test for each mirror, it will only test those protocols the mirror lists as -supporting. +supporting. Actually it'll test the ones not supported as well, but mark +them differently in the results. Options. @@ -200,13 +207,14 @@ Print the version. -v -Print more verbose output. Normally only CRITICAL and ERROR message sare -printed. -v will print WARNING messages as well, -v -v INFO messages, -and -v -v -v DEBUG messages. All messages are logged regardless. +Print more verbose output. Normally only CRITICAL messages are printed. +-v will print ERROR messages as well, -v -v WARNING messages, -v -v -v +INFO messages, and -v -v -v -v DEBUG messages. All messages are logged +regardless. -q -Only print CRITICAL messages. +Print no output messages. -k @@ -257,91 +265,3 @@ negative argument deselects a report. Select which tests to run. The arguments are comma separated. A negative argument deselects a test. Examples are given above. - - -Theory of operation. --------------------- - -Typically you would call it without any specific mirror mentioned on the -command line. I'll start the discussion from there. - -Create the results directory. - -If -k is not given, delete results/*.log. - -Delete results/*.check. - -touch results/stamp - -Open results/apt-panopticon.log for message logging. - -Download mirror_list.txt from the reference site. Build a table of -Active mirrors keyed by the FDQN, include the listed Protocols as a sub -table. Add the round robin domain name. Resolve all the IPs and add -them to this table. Write this table to results/mirrors.lua so that the -forked tests can read it. - -checkHost() the reference site first. - -Loop through the mirrors table, and checkHost() each one, skipping the -reference site. - -Wait for all forked tests to finish. - -Delete results/*.check. - - -The checkHost() function does this - - -If there is no second argument, then the host is set to the first -argument, otherwise the host is the second argument. - -Gather the IPs for the host name with the following command - - -dig +keepopen +noall +nottlid +answer example.com A example.com AAAA -example.com CNAME example.com SRV | sort -r | uniq - -So it should end up with all the IPV4, IPV6, CNAME, and SRV records for -that host. - -For each IPv4 and IPv6 address, fork a copy of the script something like -this (including any arguments originally provided to the script) - - -ionice -c3 ./apt-panopticon.lua example.com/path x.x.x.x & - -ionice -c3 ./apt-panopticon.lua example.com/path [x:x:x:x:x:x] & - -For each CNAME, it checkHost() the host, but with the CNAME as a second -argument. - -SRV reconds don't do anything yet, coz I have yet to see one from my test -environment, so can't test it. - - -Each forked call of the script from above does this - - -Open results/example.com_x.x.x.x.log for message logging. - -Loads the mirrors table from results/mirrors.lua. - -If performing the Integrity or Updated testes, delete results/example.com -directory, downloads the reference files using wget. While it should -actually perform the Integrity and Updated tests now, those haven't been -written yet. Note that currently this downloads 4GB per mirror. - -Calls checkHost() with the host as first and second arguments, and -includes the IP this time. The inclusion of the IP causes checkHost() to -call checkFiles(). - - -checkFiles() will call checkHEAD() for each of the reference files. - - -checkHEAD() uses LuaSocket (or LuaSec for HTTPS) to send a HEAD request -to the IP, with a Host header set to the original host name. Redirects -will not be followed by that request. If the request returns a redirect, -then checkHEAD() is called recursively. If the redirect is to some host -we are not already checking, we call checkHost() on it, with an IP of -"redir". This causes checkHost() to bypass the test that would otherwise -call checkFiles(), instead gathering the IPs and fork as usual. - -- cgit v1.1