docs with mkdocs

docs/.gitignore

@@ -0,0 +1 @@
+site

docs/docs/hacking.md

@@ -0,0 +1,15 @@
+## Why not on github.com
+
+We love collaboration between people, and software developement can be a wonderful playground. Nevertheless, we are not comfortable with the social-neworkish nature of github, and also the choice of a platform is something that is meaningful in itself.
+Fortunately go allows to pull packages from any git server that is publicly available. Therefore do not be afraid of go-getting from git.lattuga.net.
+
+[Spiegare meglio la natura autogestita di lattuga]
+
+### So how to collaborate
+
+If you want to collaborate to the software, either drop a mail to <indirizzo@scamuffo.com> or open an account on git.lattuga.net to open a PR.
+We are also reachable at [IRC irc.mufhd0.net]
+
+
+
+

docs/docs/index.md

@@ -0,0 +1,54 @@
+# Circolog
+
+Circolog proposes a differnt approach to the problem of having useful logs.
+
+Circolog is a syslog server which doesn't write to disk. Ever. It doesn't consume tons of RAM like elasticsearch/logstash, nor does it give you plots and a very long history.
+It is however a very useful tool when you want to minimize disk writes. We wrote it thinking about user privacy: your logs can be just as sensitive as your database if you log too much!
+
+[Spiegone su casi d'uso, buttare i log, debuggare rapidamente magari applicazioni verbose, eccetera]
+
+## Why it is cool in 2 minutes
+
+Keep your users safer
+
+Read logs conveniently:
+   filter with a proper (and easy) query language!
+
+        grep is powerful, but sometimes you want something more expressive:
+
+            circolog-tail -where 'app_name=="apache" and message LIKE "%memory%"'
+
+            circolog-tail -where '(app_name"apache" OR app_name LIKE "php%") AND message LIKE "%memory%"'
+
+    circolog-tail -where 'app_name=="mysql" OR severity >= warning'
+
+   colors to highlight high severity and visually group related message
+
+        [screenshot]
+
+      It's not only about being nice, we swear! coloring logs also means reaching the most important entries easily, and grouping related entries together.
+      
+
+    output logs in the format you prefer _now_
+
+    depending on what you're doing, log format might be useful... or distracting. For example, how many times have you used the `hostname` part of it? With the common disk-based logging, you need to choose once and for all how your logs will be saved. With circolog 
+
+
+Hackable
+
+    We think that circolog-tail is pretty cool, but you definitely can reuse simpler tools to get logs and filter them the way you prefer. clients can read logs using plain HTTP (or websocket). Most of the cool features of circolog-tail are actually implemented server-side, so you can use filters (or other options) wih any client.
+
+
+Fast, secure by default (?), easy deploy
+
+    Those are features that you should expect, not be surprised of! circolog can easily process thousands of log entries per seconds, has sane defaults and can be deployed as a single binary
+
+
+## Security considerations
+
+While we try our best not to introduce vulnerabilities, this software is not meant to be exposed on the wider internet.
+Beware of binding it on something different from localhost.
+
+Even without being exposed, care must be given to socket permissions: don't let unprivileged users read your logs!
+We suggest that you use a dedicated user/group to run circolog, and make root part of that group.
+

docs/docs/install.md

@@ -0,0 +1,25 @@
+## Installation and Configuration
+
+
+If you trust us, just get the compiled binaries and copy them to /usr/local/{s,}bin/ (but you shouldn't: [compiling -> altra pagina]).
+
+Running circologd is pretty easy: just run `circologd` by hand or in your favourite service manager: [here are some contrib scripts] for sysV, systemd, supervisor... but consider them as hints, don't just copy them!
+
+### System Integration
+
+While circologd can be your only syslog daemon, you might want to couple it with another syslog to have the best of both worlds. For example, you could use rsyslog (or syslog-ng) to write important (ie: priority >= notice) log to persistent storage, letting circolog handle short-term but heavily detailed logs.
+
+Or you could make circolog get messages from journald. While possibilities are endless, we tried to document some common setups.
+
+#### Use Case: circologd as the only syslog
+
+[mica lo so se funziona, credo di no, ma proviamo]
+bind it to /dev/log
+
+#### Use Case: circologd receiving messages from syslog-ng
+
+#### Use Case: circologd receiving messages from journald
+
+[TODO: il codice va ancora scritto: bisogna bindare /run/systemd/journal/syslog con formato != rfc5424
+
+

docs/docs/systemd.md

@@ -0,0 +1,29 @@
+unit systemd con utente dinamico:
+    - no adduser/altre conf
+    - utente con pochi permessi
+    - accesso consentito al gruppo adm
+
+    [Unit]
+    Description=In-memory logging
+
+    [Service]
+    DynamicUser=true
+    Group=adm
+    RuntimeDirectory=circolog
+    # this is important: circologd will respect umask, so if you want to have files that are not world-readable, you must set it
+    RuntimeDirectoryMode=0750
+    UMask=0026
+    ProtectSystem=full
+    ExecStart=/usr/local/sbin/circologd -syslogd-socket /run/circolog/syslog.sock  -buffer-size 2000 -query-socket /run/circolog/query.sock
+    # security restrictions; useful, but not needed
+    PrivateTmp=true
+    PrivateNetwork=true
+    NoNewPrivileges=true
+    Restrictnamespaces=true
+
+    #optional: watchdog
+    WatchdogSec=30
+
+    [Install]
+    WantedBy=multi-user.target
+

docs/mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: Circolog
+nav:
+    - Home: index.md
+    - Install: install.md
+    - Queries: query.md
+    - Hacking: hacking.md
+repo_url: https://git.lattuga.net/boyska/circolog
+repo_name: 'Repository'