auth: add manual page, and minor code changes

basics of the helper module explained.

2 files changed, 77 insertions, 2 deletions

diff --git a/squark-auth.8 b/squark-auth.8
new file mode 100644
index 0000000..7d83c9d
--- /dev/null
+++ b/squark-auth.8
@@ -0,0 +1,73 @@
+.TH squark-auth 8 "23 July 2010" "" "Squark Documentation"
+
+.SH NAME
+squark-auth \- Squark authentication helper for Squid
+
+.SH SYNOPSIS
+.BI "squark-auth [" "option" "]..."
+
+.SH DESCRIPTION
+.B squark\-auth
+is an external acl helper for Squid. It maps IP-address to
+credentials information collected from managed switches using SNMP.
+
+.SS Theory Of Operation
+The code first maps received IP to a MAC using SNMP query from the
+router connecting to client IP's subnet.
+.PP
+This is followed with MAC tracing of the MAC address. The switch 
+BRIDGE-MIB forwarding database is queried to detect which switch port
+is active for the MAC. LLDP-MIB is then queried to receive IP-address
+of the switch connected to this port. This is repeated until we end up
+in "edge switch" which does not have any LLDP information available
+for the port where the MAC address is assigned.
+.PP
+Finally, the edge switch is interrogated for detailed information of
+the port and connected client.
+
+.SH OPTIONS
+The following options are recognized:
+
+.IP "\fB\-c \fIsnmp\-communicty"
+Specifies the SNMP community to be used. Currently the same community
+is used for all switches.
+
+.IP "\fB\-r \fIlayer3\-root\-ip"
+The management IP-address of the default gateway router for the clients.
+If you have multiple "routing switches", this should be the closest such
+switch to the machine running squark\-auth.
+
+.IP "\fB\-i \fIlayer3\-root\-interface"
+The router's network interface connected to the subnet containing the
+clients.
+
+.IP "\fB\-R \fIlayer2\-root\-ip"
+In case the router and the first switch are different devices and the
+router does not support BRIDGE-MIB, this can be used to specify the
+IP-address of the first switch. Defaults to \fIlayer3\-root\-ip\fR.
+
+.IP "\fB-v \fIlayer2\-vlan"
+The VLAN index of the client's subnet for the layer2 switches.
+
+.IP "\fB-f \fIusername\-format"
+Specifies the format of the username to given back for squid. The
+following format specifiers are supported:
+.TS Header
+llw(2i).
+%I	Client IP address
+%M	Client MAC address
+%N	Edge switch sysName
+%L	Edge switch sysLocation
+%i	Edge switch port ifIndex
+%n	Edge switch port ifName 
+%d	Edge switch port ifDescr
+%w	Edge switch HP ProCurve WebAuth username
+.TE
+
+Defaults to "%w".
+
+.IP "\fB-T \fItopology\-file"
+Load external topology information for switches not supporting LLDP.
+
+.SH AUTHORS
+Timo Teras <timo.teras@iki.fi>
diff --git a/squark-auth.c b/squark-auth.c
index 84240c9..73f9e0f 100644
--- a/squark-auth.c
+++ b/squark-auth.c
@@ -1,6 +1,6 @@
 /* squark-auth.c - Squid User Authentication and Rating Kit
  *   An external acl helper for Squid which collects authentication
- *   information for IP-address from switches via SNMP.
+ *   information about an IP-address from switches via SNMP.
  *
  * Copyright (C) 2010 Timo Teräs <timo.teras@iki.fi>
  * All rights reserved.
@@ -14,6 +14,8 @@
  * - implement Q-BRIDGE-MIB query
  * - map vlan names to vlan index
  * - print some usage information
+ * - poll lldpStatsRemTablesLastChangeTime when doing switch update
+ *   to figure out if lldp info is valid or not
  */
 
 #include <fcntl.h>
@@ -28,7 +30,7 @@
 /* Compile time configurables */
 #define SWITCH_HASH_SIZE		128
 #define PORT_HASH_SIZE			128
-#define CACHE_TIME			30 /* seconds */
+#define CACHE_TIME			120 /* seconds */
 
 /* Some helpers */
 #define ARRAY_SIZE(x)	(sizeof(x) / sizeof((x)[0]))