Merge branch 'master' of git.lattuga.net:boyska/circolog

docs/.gitignore

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

docs/docs/hacking.md

@@ -0,0 +1,16 @@
+## Why not on github.com
+
+We love collaboration between people, and software development can be
+a wonderful playground. Nevertheless, we are not comfortable with the
+social-neworkish nature of github. 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,61 @@
+# Circolog
+
+Circolog proposes a different 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
+
+- It keeps 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: highlight 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.
+
+
+- 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) with any client.
+
+
+- Fast, secure by default (?), easy to 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,35 @@
+## Installation and Configuration
+
+
+If you trust us, just get the compiled binaries and copy them to
+`/usr/local/{s,}bin/` (but you shouldn't: [TODO: compiling -> altra pagina]).
+
+Running circolog 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!
+
+[TODO: add scripts]
+
+### 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/query.md

@@ -1,14 +1,15 @@
 Query language
-===================
+==============
 
-circolog uses a sql-inspired query language. If you know SQL, then you can use "where clauses" in circolog. If
+Circolog uses a sql-inspired query language. If you know SQL, then you can use
-you don't know SQL, don't worry: the language is easy enough for you to learn the most basic queries without
+"where clauses" in circolog. If you don't know SQL, don't worry: the language
-worrying too much.
+is easy enough for you to learn the most basic queries without worrying too
+much.
 
 You can only filter the rows, you can't sort them or group them in any way.
 
 Reference
------------
+---------
 
 Available fields:
  - `msg`: the string with the main information
@@ -19,3 +20,7 @@ Available fields:
  - `sev`: an integer describing severity
 
 
+Examples
+--------
+
+TODO

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'