From e9e30ab3b9654e29ec5b9f7931f13c4b56f42dfd Mon Sep 17 00:00:00 2001 From: Stefan Midjich Date: Thu, 15 Dec 2016 12:22:22 +0100 Subject: [PATCH] some more docs. --- README.md | 29 +++++++++++++++++++++++++++++ plugins/README.md | 3 +++ 2 files changed, 32 insertions(+) create mode 100644 plugins/README.md diff --git a/README.md b/README.md index ec40392..51e16c8 100644 --- a/README.md +++ b/README.md @@ -45,3 +45,32 @@ Also with plugins there are options to connect other authentication methods like # Deployment See examples in docs/examples directory. + +# Technical details + +## IPtables + +At the heart is iptables doing the following. + + 1. Labeling all traffic with the number 99 in the mangle table. + 2. Labeled ICMP, DNS and HTTP traffic is redirected to the portal server in the nat table. + 3. All other labeled traffic is dropped. + 4. Authenticated clients are jumped out of the mangle table before being labeled, using the RETURN target. + 5. Authenticated clients are also deleted from conntrack after having their exception rules created in the mangle table. + +## Portal + +All this is of course triggered by the portal application written in Python using Bottle. + + 1. A clients redirected HTTP traffic puts them in the portal webpage. + 2. They send a POST form to the /approve url. This can be with user info, personal info, or simply an approve button for a EULA. + 3. The portal executes its plugins in the order that their config section appears in plugins.cfg. + 4. Each plugin is passed the request object from Bottle which contains form values among other things. + +## Plugins + +There's only one relevant plugin right now, iptables. But the idea is that you could add RADIUS plugins or other services. The mandatory flag in plugins.cfg decides if a plugin must pass before a client is authenticated. So you can string several plugins together for several actions that must be performed. + +### iptables plugin + + 1. Executes the iptables_cmd defined in plugins.cfg, with arguments being the client IP and potentially the client MAC address. diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000..e0abcdc --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,3 @@ +# iptables plugin + +Mac address discovery using arping is not always reliable in large complex networks.