c3Surf: Dies ist das Free Surf Interface von Frank Saurbier (c3surf@arcor.de).
-------------------------------------------------------------------------------
Kurzfassung:
  Du definierst welche Hosts oder komplette Netzwerke von c3surf verwaltet werden
  Diese sind nach einem Routerstart zunchst gesperrt
  http Anfragen dieser Hosts oder Netzclients werden auf die c3surf Anmeldeseite geleitet
  Nach der Registrierung eines Benutzers auf der Anmeldeseite kann Dein Netz auf Zeit von ihm genutzt werden
  Alles wird gelogged - Du kannst ber das Web Admin-Interface von c3Surf alles steuern
-------------------------------------------------------------------------------


Installation
============

Wie gehabt:
 - "Systemanforderungen", weiter unten in diesem Dokument, einmal ansehen.
 - opt_c3surf_<versionsinfo>.tar.gz in das fli4l Verzeichnis (Buildrechner) entpacken.
 - c3surf.txt den eigenen Bedrfnissen anpassen (alles dort beschreiben)
 - ggf. in Deine httpd.txt die Rechte 'c3surf:view,admin' hinzufgen.
 - Build erstellen

Migration zur Version 2.2.2 (von 2.2.1)
 - Pflege die neue Variablen. Sie sind in der config.txt so 
   "# + new 2.2.2 + begin ------------------ delete this line" gekennzeichnet.
 - C3SURF_CONTROL_SQUID: optional zur Kontrolle von squid, 
                         da squid sich in den Listen vordrngelt 
                         ist diese option ntig.
 - Die Variablen zum berschreiben der Quota-Defaults bei LOGINUSR_ACCOUNT sind jetzt optional

Migration zur Version 2.2.1 (von 2.2.0)
 - Pflege die neue Variablen. Sie sind in der config.txt so 
   "# + new 2.2.1 + begin ------------------ delete this line" gekennzeichnet.
 - C3SURF_WORKON_TMP: Empfehlung fr Festplattenschlaf 'yes' sonst 'no' auch bei FLASH Medien (s.u.)
 - C3SURF_SAVE_QUOTA: Empfehlung 'yes' (s.u.) 

Migration zur Version 2.2.0 (von 2.1.0)
 - Pflege die neue Variable "C3SURF_CHECK_ARP" in der config nach (Empfehlung: 'yes', s.u.). 
   Sie ist in der config.txt so 
   "# + new 2.2.0 + begin ------------------ delete this line" gekennzeichnet.

Migration zur Version 2.1.0 (von frheren Versionen)
 - Pflege die neuen Variablen nach. Sie sind in der config.txt so 
   "# + new 2.1.0 + begin ------------------ delete this line" gekennzeichnet.
 - Die MAC-Blackliste (so Du eine gepflegt hast) musst Du manuell ins Verzeichnis 
   C3SURF_PERSISTENT_PATH kopieren.
 - Das Format der c3surf_login.log wurde um eine Spalte erweitert.
   Am besten die alte log sichern und in C3SURF_LOG_PATH lschen.


Config Datei und die Parameter
==============================

OPT_C3SURF='no'
  Name des Opt, ist es aktiv ('yes') oder nicht ('no').


C3SURF_LOG_PATH='/var/log/c3surf'
  Definiert das Verzeichnis fr log-Dateien von FreeSurf. 
  Du musst mit moderatem Wachstum rechnen. 
  Im Einzelen ist die bei den noch folgenden Eintrgen fr die Log-Dateien genannt.
  Bein Herunterfahren solltest Du die Logdateien auf ein permanentes Medium sichern,
  oder den Pfad gleich dorthin einstellen, wenn Du die Dateien nicht verlieren willst. 
  Der Pfad muss dann auf dem permanenten Medium existieren.

  Wichtig: die 'c3surf_mac.blacklist' liegt ab sofort (v2.1.0) nicht mehr im C3SURF_LOG_PATH, 
  sondern im persistenten Verzeichnis C3SURF_PERSISTENT_PATH. 
  Falls Du eine Blacklist gepflegt hast, 
  musst Du diese ins Verzeichnis C3SURF_PERSISTENT_PATH kopieren.

  Weiter unten legst Du fest, was gelogged werden soll.


C3SURF_DOLOG_LOGIN='yes'            
  zeichne Login / Logout auf: c3surf_login.log (default: 'yes')

C3SURF_DOLOG_INVALID='yes'          
  zeichne ungltige Logins auf: c3surf_invalid.log (default: 'yes'). 
  Wenn die OPT_LOGINUSR='yes' gewhlt ist, 
  kann eine fehlerhafte Anmeldung zu Zeit nicht aufgezeichnet werden.

C3SURF_DOLOG_PAGE='no'              
  Zeichne den Aufruf der html-Seite auf: c3surf_page.log (default: 'no').
  Jeder Zugriff auf die Anmeldeseite wird gelogged.
  Das page-log wchst vermutlich am 2. schnellsten von allen Logs 
  - nur fr Neugierige, die regelmig nachsehen.

C3SURF_DOLOG_HTTPD='no'
  Zeichne alle mini_httpd Anfragen auf: c3surf_httpd.log (default: 'no')
  Zustzlich die Mini-httpd Logfunktion starten, aber hier ist Vorsicht geboten, 
  richtig schnelles Wachstum, bitte nur fr Test oder Debug verwenden. 
  Wenn eingeschaltet, empfielt es sich wirklich tglich die log-Datei zu prfen, 
  oder anders: Fr ganz Neugierige - heit regelmig prfen und lschen.

  opt_cpmvrmlog: kann zum regelmigen wegsichern benutzt werden. 
  Damit danach wieder korrekt gelogged wird, muss der mini_httpd neu gestartet werden. 
  Dazu gibt es das script "/usr/local/bin/c3surf_kill_httpd.sh" 
  (Config Beispiel siehe weiter unten)

C3SURF_PERSISTENT_PATH='/tmp/c3surf'
  Unbedingt anpassen, Empfehlung: '/data/c3surf'
  Definiert das Verzeichnes, welches Daten aufnimmt, 
  die nach dem Ausschalten oder nach einem Reboot erhalten bleiben sollen. 
  Idealerweise liegt dies auf einer Festplatte oder CF-Karte ('/data/c3surf'). 
  Wer seine Platte lieber den ganzen Tag ausgeschaltet haben will, 
  der kann auch ein Verzeichnis in der RAM-Disk whlen und sollte dann entsprechend
  seiner Anforderungen das Verzeichnis sporadisch auf die Platte kopieren 
  (opt_sarfile oder opt_cpmvrmlog), sonst sind die Daten nach Reboot weg. 
  Bei einem Absturz oder Stromverlust wrden die Daten bis zur letzten Sicherung fehlen.

  Was wird hier gespeichert:
  - MAC-Blackliste: 'c3surf_mac.blacklist', wird bei Bedarf angelegt (siehe Admin Interface). 
    Also wenn Du dort Eintrge veranlasst. Die Sperrung fr die mac-Adresse wurde bewut ber 
    eine eigene Datei gelst und nicht in den Paketfilter implementiert, 
    da es bei einer greren Zahl von Eintrgen sonst Probleme geben kann.
    Aber nicht vergessen, geblockte MAC-Adressen halten Standardbenutzer vom Netz fern, 
    was im normalen Anwendungsfall ausreicht, nicht jedoch die Profis. 
    Ausserdem verhindert diese MAC-Blacklist nur die Anmeldung ber c3surf / loginusr, 
    weil es eben nicht direkt in der firewall abgelegt wird.

  - Benutzerdaten: <userloginname>.data (z. B. 'frank.data'), 
    diese Dateien enthalten Daten ber die Benutzer, wie Vorname, Name und e-mail-Adresse,
    welche auch im Webinterface angezeigt werden. Weiter werden diese Dateien fr Statistiken 
    und die Kontrolle der Quotas bentigt. Die Persistenz der Benutzerdaten hat zur Folge, 
    dass die Daten aus der Konfigurationsdatei nur noch beim ersten Mal erzeugt werden. 
    Dass heit: Ist fr den Benutzer "frank" eine 'frank.data' beim Systemstart vorhanden, 
    so werden die Einstellungen in der Config-Datei ignoriert.
    Mittels LOGINUSR_ACCOUNT_n_OVERWRITE='yes' 
    kann das berschreiben der entsprechenden Benutzerdaten erzwungen werden. 
    Mittels LOGINUSR_DELETE_PERSISTENT_DATA='yes', 
    werden alle *.data Dateien beim reboot gelscht (gleiches Verhalten wie ein temporres Verzeichnis)

C3SURF_WORKON_TMP='no'
  Wer eine Festplatte im router verbaut hat und den C3SURF_PERSISTENT_PATH auf diese 
  Festplatte eingestellt hat, der kann hier 'yes' eintragen. 
  Dann werden die persistenten Daten bein router.Start von der Festplatte auf das 
  Verzeichnis C3SURF_TMP_PATH kopoiert und nur noch von dort gelesen. 
  Die Festplatte wird dann von c3surf nicht mehr geweckt. 
  Nur wenn Daten durch den Admin in die persistenten Dateien zrckgeschrieben werden.
  Persistente Daten sind:
  - Benutzer-Accounts
  - MAC-Blackliste
  - System Lock Datei (Verhindern jedern Anmeldung)
    Fr FLASH-Speicher kann hier 'no' stehen, da ja im normalen Betrieb von c3surf nur 
    gelesen wird. Schreibzugriffe verursacht nur der Admin.

C3SURF_QUOTA='no'
  Soll der Zugang limitiert werden. Wird hier 'yes' eingetragen, 
  so wird der Zugang fr eine IP-Adresse fr C3SURF_BLOCKTIME Minuten nach Zeitablauf 
  oder berschreitung des Anmeldezhlers blockiert. 
  Als Standardwert wurde 'yes' gewhlt. Ein 'no' entspricht dem Verhalten der c3surf 
  Versionen vor der Version 2.1.0.
  WICHTIG: Auch die individuellen -TIME, -BLOCKTIME und -COUNTER bei den Accounts zum 
  LOGIN_USR werden durch diese Variable aktiviert ('yes') oder deaktiviert ('no').

C3SURF_COUNTER='0'
  Gibt die Anzahl der mglichen Unterbrechungen, innerhalb der Freiminuten an.
  Seit der Version 2.1.0 werden die Freiminuten nicht mehr nur nach dem Parkuhrprinzip verwaltet: 
  Einmal angemeldet luft die Zeit ohne Unterbrechungsmglichkeit. 
  Sondern es kann eine Anzahl von Unterbrechungen (Logout/Login) definiert werden. 
  Wird hier z. B. '1' eingetragen, so kann man sich innerhalb der Freiminuten einmal abmelden 
  und dann wieder anmelden, was 2 Anmeldungen in der Zeit entspricht. 
  Bei der folgenden Anmeldung erhlt man die von C3SURF_TIME 
  noch verbliebene Differenz von der Anmeldung davor.
  Ist zudem C3SURF_BLOCKTIME='0' gewhlt, so wird der C3SURF_COUNTER erst nach 0:00 Uhr 
  des Folgetages zurckgesetzt.
  Der Wert 0 entspricht dem Parkuhrprinzip und bildet das Verhalten von c3Surf vor der Version 2.1.0 ab.
  Mit '-1' wird diese Funktion abgeschaltet = beliebig viele Unterbrechungen der Freiminuten sind mglich.

  Ist C3SURF_QUOTA='yes', so wird nach der berschreitung des Zhlers die Sperre entsprechend 
  C3SURF_BLOCKTIME aktiviert.

C3SURF_TIME='60'
  Anzahl der Minuten, die eine Freischaltung gilt 

C3SURF_BLOCKTIME='240'
  Anzahl der Minuten, die eine IP geblockt wird, 
  wenn die Freiminuten abgelaufen sind oder wenn der Admin dies ber das Webinterface veranlasst.
  So kann ein Rechner fr diese Zeit aus dem Netz ferngehalten werden und die Nutzung eingeschrnkt werden.
  Damit bei Zeitablauf die Sperrung erfolgt, muss C3SURF_QUOTA='yes' eingestellt sein.

Sonderflle:
   '0': es erfolgt eine Sperrung der Adresse, bzw. des Nutzers bis 00:00 Uhr des Folgetages.
  '-1': es erfolgt keine Sperrung.

  Die Aufhebung der Sperre ist mit einem mittleren Fehler von einer Minute behaftet.

C3SURF_SAVE_QUOTA='yes' 
  Sichere die Quota-Werte beim Herunterfahren und lade sie beim Start des Routers.
  Damit werden bei einem normalen Reboot des Routers die temporren Dateien der 
  Quota-Verwaltung nach C3SURF_PERSISTENT_PATH geschrieben und bein Neustart von dort 
  wieder ind das temporre Verzeichnis eingelesen.
  So bleibnen die momentanen Verbrauchsdaten der Benutzer erhalten.
  Ein pltzlicher Stromausfall ist damit nicht abgedeckt.
  WICHTIG: LOGINUSR_DELETE_PERSISTENT_DATA='no', sollte eingestellt sein, 
  weil diese Option sonst beim Neustart alle Benutzer-Accounts und die zugehrigen Quota-Daten lscht.

C3SURF_CHECK_ARP='yes'                  
  Prfe im countdown modul, ob die IP eines Rechners aus der ARP Tabelle verschwunden ist. 
  So kann ein abgeschalteter Rechner erkannt werden. Jedoch manchmal mit erheblichem Zeitversatz.

C3SURF_CONTROL_HOST_OR_NET_N='n'    # Wert: ganze Zahl
  Wieviele und welche IP-Bereiche oder Hosts sollen von 3Surf kontrolliert werden. 
  Dies betrifft die Weiterleitung in ein anderes Netz (FORWARD Chain).

C3SURF_CONTROL_HOST_OR_NET_n='Netzwerk OR Host OR IP-Adresse'
  Hier kann zur Vereinfachnung ein komplettes Netz angegeben werden, 
  z. B. das WLAN, dann mssen alle WLAN-Nutzer die Anmeldeseite benutzen. 
  Oder eine Referenz auf einen Host (@Host) oder eine IP-Adresse. 
  Wer oder was hier eingetragen ist, wird auf die Anmeldeseite umgeleitet 
  und es gelten die weiter unten zu definierenden Sperrregeln.

  Beispiele:
    C3SURF_CONTROL_HOST_OR_NET_1='IP_NET_3'      # Das Netz angeben IP/MASK
    C3SURF_CONTROL_HOST_OR_NET_2='@T8200'        # oder den Host @HOST
    C3SURF_CONTROL_HOST_OR_NET_3='192.168.13.11' # oder eine IP-Adresse
    C3SURF_CONTROL_HOST_OR_NET_4='192.168.0.0/24'# Das gesamte Netz, wie Nr. 1 oben
    Alternativ kannst Du natrlich auch jede Rechneradresse einzeln angeben,
    es sind dann ja auch bloss 254 Eintrge.

    Sollen einzelne Rechner ohne Anmeldung alle Dienste nutzen knnen, 
    dann schliee doch deren IP aus der C3SURF_CONTROL_HOST_OR_NET_n Liste
    aus. Das sieht dann in CIDR Notation fr IP-Netze so aus (Beispiel
    Rechner 192.168.0.2 kann ohne c3surf Anmeldung ins Netz):
      C3SURF_CONTROL_HOST_OR_NET_N='8' # Die Anzahl der Hosts oder Netze
      C3SURF_CONTROL_HOST_OR_NET_1='192.168.0.0/31'   # 0-1
      C3SURF_CONTROL_HOST_OR_NET_2='192.168.0.3'      # control only 3 not 2
      C3SURF_CONTROL_HOST_OR_NET_3='192.168.0.4/30'   # 4-7
      C3SURF_CONTROL_HOST_OR_NET_4='192.168.0.8/29'   # 8-15
      C3SURF_CONTROL_HOST_OR_NET_5='192.168.0.16/28'  # 16-31
      C3SURF_CONTROL_HOST_OR_NET_6='192.168.0.32/27'  # 32-63
      C3SURF_CONTROL_HOST_OR_NET_7='192.168.0.64/26'  # 64-127
      C3SURF_CONTROL_HOST_OR_NET_8='192.168.0.128/25' # 128-255


C3SURF_CONTROL_PORT_N='n' # Wieviele TCP-Ports des Routers sollen gesteuert werden? Wert: ganze Zahl.
  Wieviele und welche explizit benannten Ports sollen von 3Surf kontrolliert werden. 
  Betroffen sind die IP-Bereiche und die Hosts von oben "C3SURF_CONTROL_HOST_OR_NET". 
  C3Surf steuert diese Ports und gibt diese nach einer erfolgreichen Anmeldung frei, 
  so dass die ber diese Ports existierenden Services des Routers genutzt werden knnen 
  (betrifft die INPUT chain)

C3SURF_CONTROL_PORT_n='port_nr'
  Angabe der Portnummer, der Zugriff auf die dahinter stehenden Dienste des Routers (fli4l) 
  sind bis zur Anmeldung gesperrt wird.
  Nach erfolgter Anmeldung steht der Dienst dann fr die Zeit der Freischaltung zur Verfgung.
  
  Beispiele:
    C3SURF_CONTROL_PORT_1='515'  # z.B. lpdsrv (Drucker benutzbar, nach Anmeldung)
    C3SURF_CONTROL_PORT_2='21'   # z. B. ftp - (wohl gemerkt ftp auf dem router! gibts ja nicht ;-))
    Weitere mgliche Portadressen
      21=ftp, 22=ssh, 5000=imonc, 5001=telmod, 
      8118=privoxy, 9050=tor, 3128=squid, 20000=mtgcapri
      80=http(Admin) 515=lpdsrv
  Aber entscheidend ist die eigene Konfiguration. Es gelten fr alle Ports, 
  die nicht angegeben sind natrlich immer die Regeln aus der 'base.txt'. 
  Nach einer Anmeldung gelten im brigen auch immer noch die Regeln aus der 'base.txt'. 
  3Surf ist diesen Regeln bis zur Anmeldung durch den Benutzer nur vorgeschaltet.
  Es werden also nach der Anmeldung immer noch alle Regeln beachtet.
  So kann man z. B. in der 'base.txt' den Zugriff von WLAN auf das kabelgebundene Netz verbieten.
  Dies Verbot gilt dann natrlich auch fr die ber c3Surf im WLAN angemeldeten Benutzer.

C3SURF_BLOCK_PORT_N='n'  # Wieviele TCP-Ports des Routers sollen geblockt werden? Wert: ganze Zahl.
  Permanentes Blocken von Diensten fr oben benannte Netze und Hosts "C3SURF_CONTROL_HOST_OR_NET".
  Wieviele und welche explizit benannten Ports sollen von 3Surf permanent geblockt werden.
  Es gibt dann keinen Zugriff auf die dahinter stehenden Dienste des Routers (fli4l) fr die Hosts
  und/oder Rechner der gesperrten Netze. Auch nach dem Anmelden nicht. Betrifft die INPUT-Chain.
  Eigentlich ist diese Funktion nicht notwendig, denn wer bestimmte Dienst dauerhaft sperren will,
  sollte dies besser in der 'base.txt' mit den dortigen Parametern zur INPUT Chain tun.
  Warum: weil diese Regeln hier nicht mehr gelten, sobald man den Parameter OPT_C3SURF='no' setzt.
         Wer also c3surf entsorgt, muss zuvor die hier definierten Regeln in die 'base.txt' bertragen, 
         wenn ihm die Dienstesperre fr die oben benannten Hosts oder Netze weiter wichtig ist.

C3SURF_BLOCK_PORT_n='port_nr'
  Angabe der Portnummer, der Zugriff auf die dahinter stehenden Dienste des Routers (fli4l)
  sind dauerhaft fr die benannten Hosts oder Rechner in den benannten Netzen gesperrt.
  Auch nach erfolgter Anmeldung steht der Dienst NICHT zur Verfgung.

  Beispiele:
    C3SURF_BLOCK_PORT_1='5000'                 # z.B. imonc
    C3SURF_BLOCK_PORT_2='5001'                 # z.B. telmond
    C3SURF_BLOCK_PORT_3='20000'                # z.B. mtgcapri (OPT_MTGCAPRI)
    C3SURF_BLOCK_PORT_4='22'                   # z.B. ssh
    C3SURF_BLOCK_PORT_5='8118'                 # z.B. privoxy (PROXY)
    C3SURF_BLOCK_PORT_6='9050'                 # z.B. tor (PROXY)
    C3SURF_BLOCK_PORT_7='80'                   # z.B. httpd Admin interface (HTTPD)
    C3SURF_BLOCK_PORT_8='7437'                 # z.B. caiviar (OPT_CAIVIAR)


C3SURF_HTTPD_PORT='8080'
  Auf welchem Port und welcher IP-Adresse soll der mini_httpd fr die Benutzeranmeldung lauschen.
  http Anfragen von Rechnern werden auf diese Adresse und diesen Port umgeleitet.
  Port 8080 ist hier default.
  Folgendes ist bei der Wahl der Portnummer zu beachten (WICHTIG):
  - es sollte nicht der Port aus den httpd-Paket sein (normal ist das 80)
  - der httpd fr den Web-Admin des fli4l bindet sich im Standard an alle lokalen IPs
  - benutze auch keine Portnummer, die bereits von einem anderen Dienst genutzt wird
  Solltest Du versehentlich einen bereits verwendeten Port erwischt haben,
  versucht der fli4l diesen httpd immer wieder zu starten.
  Was der nicht will, weil der Port schon vom Admin-Interface oder einem anderen Diesnt belegt ist.
  Das kannst Du nur auf der Konsole oder in einem einschalteten Log sehen. Merken tust Du es daran,
  dass c3surf nicht funktionieren wird, und dass Dein fli4l hohe CPU-Belastung hat und furchtbar
  langsam zu laufen scheint.

C3SURF_HTTPD_LISTENIP='Host OR IP-Adresse OR IP_NETx_IPADDR'
  Gibt die angegebene lokale IP an, an die sich das Interface fr die Anmeldung binden soll.
  Entweder IP-Adresse oder @hostname hierhin werden http Anfragen der Clients bei Bedarf 
  (also wenn sie nicht angemeldet sind) umgeleitet.
  So kommen die Anwender dann schnell auf die Anmeldeseite.

  Beispiele:
    C3SURF_HTTPD_LISTENIP='@wifi-router'   # Angabe eines Hostnamens in der fli4l-Weise
    C3SURF_HTTPD_LISTENIP='192.168.11.3'   # Angabe einer IP-Adresse
    C3SURF_HTTPD_LISTENIP='IP_NET1_IPADDR' # Angabe einer IP-Adresse mittels Variable
    Der http-Diesnt fr c3surf wird immer an genau eine IP-Adresse gebunden.

Optional:
C3SURF_CONTROL_SQUID
  Mit dem Einfgen der Variable C3SURF_CONTROL_SQUID='yes' wird die Kontrolle ber squid erzwungen.
  Damit wird die c3surf Portumleitung an den Anfang gesetzt,
  was auch Auswirkungen auf andere Pakete hat (z. B. openvpn).
  Die Empfehlung ist 'no', wer es unbedingt braucht, weil er squid verwendet, der sollte prfen,
  ob nicht ungewollt noch andere Funktionen dadurch beeinflusst werden.

OPT_LOGINUSR='yes'    # yes: echte Anmeldung verwenden (wird empfohlen)
  LOGINUSR: Stellt eine echte Anmeldung (User / Password) zur Verfgung.
  Account Pflege im Moment nur hier, stellt sicher, dass Passworte nur verschlsselt bertragen werden.

LOGINUSR_DELETE_PERSISTENT_DATA='no'
  Benutzerdaten auf einer Platte bleiben seit Version 2.1.0 erhalten. Der Standardwert 'no' 
  stellt dies fr die Accountdaten sicher.
  Mit der Eingabe von 'yes' kann die Funktion von frheren c3Surf-Versionen abgebildet werden.
  Alle Benutzer-Accounts werden dann beim Neustart gelscht (wirklich alle).
  Es Danach erfolgt eine Neuanlage der Accounts, wie unten definiert.
  Das geschieht bei jedem Neustart, bis ein neues Router-Image auf den Router bertragen wird.
  Es wird empfohlen hier 'no' beizubehalten. Dann bleiben die Daten zu den Accounts erhalten.

  Dazu gehren:
  - Benutzer-Accounts
  - Quota-Daten, wenn C3SURF_SAVE_QUOTA='yes' gewhlt ist (s.o.)
  (fr einen einzelnen Account siehe: LOGINUSR_ACCOUNT_n_OVERWRITE)

LOGINUSR_ACCOUNT_N='n'   # Anzahl Accounts, Wert: ganze Zahl
  Gibt die Anzahl der User-Accounts an.

LOGINUSR_ACCOUNT_n_USER='user1'
  Username fr die Anmeldung (Pflicht: '' also leer lassen ist unzulssig)

LOGINUSR_ACCOUNT_n_PWD='user1_secret'
  Password fr die Anmeldung (Pflicht: '' also leer lassen ist unzulssig)

LOGINUSR_ACCOUNT_n_FORENAME='Vorname'
  Vorname des Nutzers fr die bessere Verwaltung 
  (Optional, leer lassen erlaubt).
   Dieser Inhalt wird im Log und Admin-Interface angezeigt,
  so kann der Admin besser erkennen, wer gerade online ist.

LOGINUSR_ACCOUNT_n_SURNAME='Nachname'
  Nachname des Nutzers fr die bessere Verwaltung 
  (Optional, lassen erlaubt). 
  Dieser Inhalt wird im Log und Admin-Interface angezeigt, 
  so kann der Admin besser erkennen, wer gerade online ist.

LOGINUSR_ACCOUNT_n_EMAIL='usr1@home.de'
  Email des Nutzers fr die bessere Verwaltung 
  (Optional, lassen erlaubt). 
  Dieser Inhalt wird auch Log und Admin-Interface angezeigt,
  so kann der Admin besser erkennen, wer gerade online ist.

LOGINUSR_ACCOUNT_n_OVERWRITE='yes'      
  Optional: berschreibe persistente Nutzerdaten beim Router-Neustart.
  Seit Version 2.1.0 kann ein Verzeichnis fr persistente Daten angegeben werden.
  Dort werden die Daten fr die Accounts gespreichert.
  Damit stehen diese Daten unverndert nach einem Reboot zur Verfgung.
  Mit dieser Option knnen der Benutzer-Account und alle zugehrigen persistenen Daten
  (Statistiken) berschrieben werden.

LOGINUSR_ACCOUNT_n_TIME='60'            
  Optional: Anzahl der Minuten nur fr diesen Nutzer, berschreibt C3SURF_TIME.
  Siehe auch C3SURF_TIME. Fehlt dieser Parameter, so gilt C3SURF_TIME.
  Das berschreiben macht natrlich nur Sinn, wenn C3SURF_QUOTA='yes' eingestellt ist.

LOGINUSR_ACCOUNT_n_BLOCKTIME='240'
  Optional: Sperrzeit nur fr diesen Nutzer, berschreibt C3SURF_BLOCKTIME
  Siehe auch C3SURF_BLOCKTIME. Fehlt dieser Parameter, so gilt C3SURF_BLOCKTIME.
  Das berschreiben macht natrlich nur Sinn, wenn C3SURF_QUOTA='yes' eingestellt ist.

LOGINUSR_ACCOUNT_n_COUNTER='1'
  Optional: Anzahl der Anmeldungen nur fr diesen Nutzer, berschreibt C3SURF_COUNTER
  Siehe auch C3SURF_COUNTER. Fehlt dieser Parameter, so gilt C3SURF_COUNTER.
  Das berschreiben macht natrlich nur Sinn, wenn C3SURF_QUOTA='yes' eingestellt ist.



Web-Admin Interface
===================
Rechte: c3surf:view,admin

  view:  den Eintrag im Admin Men anzeigen
  admin: fr die Nutzung der Funktionen im Web-Interface

  in httpd.txt einpflegen fr Admins oder Nutzer die nicht ber das Recht "all" vergen,
  aber mit FreeSurf arbeiten sollen.

  Der fli4l-Admin mit dem Recht "all" sieht es sowieso und kann alles damit tun.
  Zu finden in Web-Admin unter Opt:
  als "3Surf", wenn OPT_LOGINUSR='no' (sprich: FreeSurf)
  als "LoginUsr", wenn OPT_LOGINUSR='yes'

LOGINUSER Option
================
  Es wird eine echte Benutzeranmeldung, hnlich der von Hotspot Portalen benutzt.
  Nur wer ber einen Benutzer-Account und ein Kennwort verfgt kann das Internet
  und die Dienste des Routers nutzen.

Was macht 3Surf
===============
  Du kannst ein Netz oder einzelne Hosts angeben, die nach Hochfahren zunchst gesperrt sind.
  Diese knnen dann ber ein eigenen Webinterface von den Benutzern selbst auf Zeit freigeschaltet werden.
  Dazu registriert sich der Benutzer formlos ber das Webinterface.
  Ist die LOGINUSR - Option aktiviert, dann knnen sich nur Benutzer anmelden,
  die einen gltigen Account besitzen. Die Benutzernamen und Passworte pflegst Du.

  Du kannst ber das Admin-Interface Deines Routers die Benutzer sehen, Ausloggen,
  temporr Sperren oder die MAC-Adresse dauerhaft sperren.
  Die Sperrung betrifft immer nur die Anmeldung ber 3Surf und wird von 3Surf verwaltet.
  Kommt der Rechner ber eine andere NIC an Deinen Router, hat die Sperre keine Wirkung.

  Die Anmeldung erfolgt durch Vorname, Name und e-mailadresse oder durch User/Password.
  Nach Ablauf einer eingestellten Zeit, wird der Zugang wieder gesperrt und kann durch
  neue Anmeldung wieder freigeschaltet werden.

  Du kannst die Anmeldeseite auch fr die Benutzer sperren 
  (siehe FreeSurf bzw. LoginUsr im OPT-Menue des Webinterfaces).

  Du kannst das alles im Admin-Web-Interface nachvollziehen.

  Willst Du bestimmte Rechner dauerhaft freischalten, so kannst Du dies im Webinterface tun.
  Siehe dazu die ARP-Liste oder die DHCP-Leases.

  Jede Nutzung kann seit Version 2.1.0 mit Quotas versehen werden.
  Damit kann die Nutzung in der Zeit eingeschrnkt werden.
  Mit den Parametern "-TIME", "-BLOCKTIME" und "-COUNTER" lsst sich dabei sehr viel einstellen,
  auch Benutzerbezogen.

Beispiele
  TIME  BLOCK COUNTER  ergibt QUOTA, wenn C3SURF_QUOTA="yes"
        TIME
  60    -1       0     60 Min Zeit, keine Sperre nach Ablauf, mit jeder Anmeldung (Verhalten wie vor v2.1.0)
  60    240      0     60 Min Zeit, danach fr 240 gesperrt, mit Anmeldung luft die Zeit (wie Parkuhr)
  60     0      -1     60 Min Zeit, nach Ablauf bis 00:00 Uhr gesperrt, beliebige An- Abmeldungszahl
  60    -1       1     60 Min Zeit, keine Sperre nach Ablauf, die Zeit kann 1x unterbrochen werden
  60    -1      -1     60 Min Zeit, keine Sperre nach Ablauf, beliebige An- Abmeldungszahl

Systemanforderungen
===================
  Der fli4l muss als DNS-Server bei den Clients eingetragen sein,
  der fli4l muss automatische Einwahl nutzen oder online sein,
  sonst klappt die automatische Umleitung auf die Anmeldeseite nicht!

  Die Pakete easycron und httpd sind erforderlich.

  Die Entwicklung begonnen habe ich unter 3.1.4. 
  Verwendet wird es jetzt unter 3.4.0.
  Nicht fr Version 3.0.x oder frhere, definitiv NICHT!!

OPT_LOGINUSER
=============
  Stellt ein pseudoechte Anmeldung fr Benutzer bereit. 
  Damit kann nicht mehr jeder das Internet oder die Dienste Deines Routers nutzen.
  Ich habe es so entwickelt, dass im laufenden Bertrieb eine Umschaltung erfolgen kann.
  Diese ist aber nicht implementiert.

  Pseudoecht: es ist eben keine echte Benutzeranmeldung, 
  aber die Software substituiert seit Version 2.1.0 jeden Benutzer auf eine Rechneradresse
  und handhabt das alles transparent. So wird nach Ablauf der Quota nicht der Rechner (IP-Adresse),
  sondern der Benutzer geblockt.

WARNUNG:
========
  Ohne OPT_LOGINUSR='yes' ist es jeder Person mglich, die fr ihren Rechner eine IP-Adresse 
  vom Router zugewiesen bekommen hat (z. B. aus einem offenen WLAN), 
  einen freien Zugriff auf das Internet und die Dienste Deines Routers, 
  die Du nicht geblockt hast, zu bekommen. c3Surf untersttzt beim Blocken der Dienste,
  ist aber kein Ersatz fr eine "ordentliche" Konfiguration der Firewall in der "base.txt".

  Empfehlung: 
    Achte darauf, dass Du Deinen Router mit einer "Recovery-Version" versehen hast - fr alle Flle.
    Ich habe die zwar noch nicht gebraucht, aber sicher ist sicher.
    Mit einer unglcklichen Konfiguration kannst Du Dich komplett aussperren.

PROBLEME, NDERUNGEN und FEHLER:
================================
  nderungen, die Du gemacht hast, schickst Du mir bitte. Mit einer kurzen Beschreibung,
  ich verspreche, dass ich die nderungen bei Gefallen in das nchste Release bernehme.
  Falls gar nix luft : Fehlerbeschreibung erstellen, mit Config-Info und mailto:c3surf@arcor.de.
  Oder die fli4l-foren nutzen, ich lese diese.

LITERATUR
=========
  Wer gerne sein Netz fr andere zur Verfgung stellt, der sollte sich auch einmal mit der 
  rechtlichen Situation auseinander setzen.
  Es gibt ein unter CC stehende Arbeit dazu: 
  Rechtsfragen offener Netze: http://digbib.ubka.uni-karlsruhe.de/volltexte/1000007749

Autor     : Mantz, Reto
Reihe     : Schriften des Zentrums fr Angewandte Rechtswissenschaft / ZAR, 
            Zentrum fr Angewandte Rechtswissenschaft, Universitt Karlsruhe (TH)
Band      : 8
Verlag    : Universittsverlag Karlsruhe
ISBN      : 978-3-86644-222-1
Erschienen: 10.04.2008

LIZENZ
======
  Ich stelle diese meine Arbeit unter GNU General Public License in Version 2 oder folgende.
  Damit ist diese Software frei fr Benutzer, Entwickler und Firmen.
  Es ist guter Stil, wenn Urheber in einer weiteren Verwertung oder Verffentlichung genannt werden. 
  Daran solltest Du immer denken.
  --------------------------------------------------------------------------
  ## This program is free software; you can redistribute it and/or modify ##
  ## it under the terms of the GNU General Public License as published by ##
  ## the Free Software Foundation; either version 2 of the License, or    ##
  ## (at your option) any later version.                                  ##
  --------------------------------------------------------------------------

----------------------------------------------------------------------------
SPENDEN
=======
PayPal    : c3surf@arcor.de
            mit Hinweis: c3surf Spende

  Ich habe viel meiner Zeit investiert, das war diese Software mir wert. 
  Wenn die Software Dir etwas wert ist, freue ich mich ber eine Spende. 
----------------------------------------------------------------------------


----------------------------------------------------------------------------
ANHANG
======
  Wie ist c3surf entstanden
  =========================
     Meine alten Rechner konnten nur WLAN WEP Verschlsselung mit 48bit. 
     Da kann ich auch gleich ein offenes, nicht verschlsseltes WLAN betreiben. 
     Aber ich mchte schon wissen wer das Netz bei mir nutzt. 
     Also brauchte ich ein Paket, welches eine formlose Registrierung in 
     meinem Netz ermglicht. 
     Pate stand "opt_onco" (onco is Copyright (c) 2001-2007 Michael Mattes),
     einen Dank an Ihn als Ideenlieferant fr mich.
     Jedoch fehlte mir dort die eigene Registrierung durch den Benutzer.
     Also baute ich etwas drum herum. Spter dann ein eigenes "opt_c3surf".
     Was eigentlich opt_3surf heien (sprich: FreeSurf) sollte.
     Doch als das Paket fertig gebaut war, scheiterte das '3surf'
     an den fli4l-Namenskonventionen. Da hatte ich viel Spass bei der berarbeitung.

     Spter erweiterte ich es um die OPT_LOGINUSR Option. Seit dem kann eine "fast"
     echte Anmeldung nachgestellt werden.

     Seit der Version 2.3.0 kann c3surf auch Gutscheine generieren.

ANDERE OPTS HOWTOS
==================
  cpmvrmlog Config
  ================
      Beispiel fr das c3surf-Logverzeichnis, mit restart des mini_httpd

      # archive c3surf log dir
      # einmal im Monat am 1. um 01:30
      # maximal 12 Archive aufbewahren
      CPMVRMLOG_n_ACTION='move'
      CPMVRMLOG_n_SOURCE='/var/log/c3surf/c3surf_*.log'
      CPMVRMLOG_n_DESTINATION='/data/Archive/log/c3surf'
      CPMVRMLOG_n_CUSTOM='/usr/local/bin/c3surf_kill_httpd.sh'
      CPMVRMLOG_n_MAXCOUNT='12'
      CPMVRMLOG_n_CRONTIME='30 1 1 * *'

  samba ohne Anmeldung erlauben
  =============================
      Man nehme das opt_usercmd und trage dort folgendes ein.
      USERCMD_BOOT_N='3'
      USERCMD_BOOT_1='/sbin/iptables -I c3surf_control 1 -v -p udp --dport 137:138 -j RETURN' # samba thru c3surf
      USERCMD_BOOT_2='/sbin/iptables -I c3surf_control 1 -v -p tcp --dport 455 -j RETURN'     # samba thru c3surf
      USERCMD_BOOT_3='/sbin/iptables -I c3surf_control 1 -v -p tcp --dport 139 -j RETURN'     # samba thru c3surf

      Durch hinzufgen der Option "-d IPsambaHOST" in den oberen Zeilen, 
      kann die jeweilige Regel noch um den Zielrechner erweitert werden.

      Damit werden die samba ports normal durch die FORWARD-chain geleitet und nicht mehr von c3surf geblockt. 
      Solltest Du in der FORWARD-chain samba weiterleitung verbieten, so ndern diese Eintragungen nichts daran.

      Es gelten also immer noch die Einstellungen Deiner base.txt.
