added readme

README.MD

@@ -0,0 +1,74 @@
+# SCW-CAP
+
+scw-cap liest HTTP-Requests von einem Interface, auf dem der HTTP-Traffic unverschlüsselt zur Verfügung steht oder aus Apache- oder Nginx-Logfiles und schreibt die HTTP-Requests in eine NATS-Queue, von wo aus ScraperWall die Daten verarbeitet
+
+## Konfiguration
+
+scw-cap kann über Kommandozeilenparameter, Environment-Variablen und eine Konfigurationsdatei in TOML konfiguriert werden.
+
+### NATS-Konfiguration
+
+* **-nats-url <url>**: the URL of the NATS queue, z.B.. `nats://192.168.122.1:4222` for an unencrypted connection or `tls://nats.scraperwall.com:4222` for a TLS-encrypted connection
+* **-nats-user <user>**: the user with which to authenticate in NATS
+* **-nats-password <password>**: the password with which to authenticate in NATS
+* **-nats-ca <ca-file>**: the CA-Certificate for a TLS connection
+* **-nats-queue <queue-name>**: the name of the NATS queue in which to write the requests, e.g. `requests`
+
+### Live Capture von einem Netzwerkinterface
+
+Das Live-Capture liest die eingehenden HTTP-Requests mit libpcap von einem Netzwerkinterface, auf dem die Requests unverschlüsselt verfügbar sind.
+
+Dies ist die bevorzugte Methode, die Anfragen zu lesen, da nur so Cookies und alle Header-Informationen gelesen werden können.
+
+* **-live** Aktiviert das Live Capture\*
+* **-interface <interface name>:**: Das Netzwerkinterface, auf dem die unverschlüsselten Requests verfügbar sind, z.B. `eth0`
+* **-snapshot-len <len>**: Anzahl an Bytes, die pro Requests gelesen werden, z.B. `8192`
+* **-filter <expr>**: libpcap Filterausdruck, der die Pakete, die analysiert werden, so einschränkt, dass lediglich die passenden eingehenden HTTP-Requests gelesen werden, z.B. `tcp dst port 80`
+* **-promiscuous**: falls die Requests mittels Port Mirroring auf ein Interface geschrieben werden, das eigentlich nicht für die Requests zuständig ist, kann hiermit das Zielinterface promisk geschaltet werden, so dass die Requests gelesen werden können.
+
+### Capture eines Apache-Logfiles
+
+Ist Live-Capturing nicht möglich, weil z.B. die HTTP-Requests nur verschlüsselt verfügbar sind, kann man die Requests auch aus einem Apache-Logfile lesen. scw-cap tailt das Logfile und öffnet es automatisch neu,wenn es beispielsweise durch logrotate rotiert wurde.
+
+* **-apache-log <filename>**: Ort des Apache-Logfiles, z.B. `/var/log/apache/access.log`
+
+### Capture eines Nginx-Logfiles
+
+Alternativ zu Apache kann scw-cap auch Nginx-Logs verarbeiten.
+
+* **-nginx-log <filename>**: Ort des Nginx-Logfiles, z.B. `/var/log/nginx/access.log`
+* **-nginx-format <format>**: Format, in dem das Nginx-Logfile vorliegt, z.B. `'$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'`
+
+### Allgemeine Konfigurationsparameter
+
+* **-use-x-forwarded**: Falls Live-Capturing aktiv ist, sorgt dieser Parameter dafür, dass scw-cap die Quell-IP-Adresse aus dem X-Forwarded-For HTTP-Header verwendet. Man sollte dies tun, wenn SSL auf einem Load Balancer terminiert wird und die Requests dahinter unverschlüsselt an alle Worker weitergereicht werden.
+* **-quiet**: Sorgt dafür, dass nur Fehler geloggt werden
+* **-trace**: sorgt dafür, dass alle eingehenden Requests geloggt werden. Nur für Debgging sinnvoll. Produktiv sollte -trace nie aktiv sein.
+
+### Konfiguration mit TOML-Datei
+
+scw-cap kann mit einer TOML-Datei konfiguriert werden. Die Konfigurationsdatei wird mit dem Kommandozeilenparameter \*\*-config <filename> spezifiziert.
+
+```toml
+Live = true
+Interface = "eth0"
+SnapshotLen = 8192
+Filter = "tcp dst port 80"
+Promiscuous = false
+# NatsURL = "nats://192.168.122.1:4222"
+NatsURL = "tls://nats.scraperwall.systems:4222"
+NatsUser = NatsUser
+NatsPassword = NatsPassword
+NatsCA = /etc/scw-cap/ca-chain.cert.pem
+NatsQueue = "requests"
+UseXForwardedAsSource = true
+Quiet = true
+Trace = false
+# ApacheLog = "/var/log/apache2/access.log"
+# NginxLog = "/var/log/nginx/access.log"
+# NginxFormat = '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'
+```
+
+### Konfiguration über Environment-Variablen
+
+Die Environment-Variablen, mit denen scw-cap konfiguriert werden heißen identisch zu den Kommandozeilenoptionen, wobei alle Zeichen groß geschrieben werden und Bindestriche durch Unterstriche ersetzt werden müssen. Aus **-nats-url** wird z.B. `NATS_URL` und aus **-use-x-forwarded-for** wird `USE_X_FORWARDED_FOR`