readme: how to integrate in your server

README.md

@@ -4,3 +4,38 @@ This is useful when you want to keep some (heavy detailed) log available, but yo
 things to disk.
 
 On your "main" syslog, send some message to this one!
+
+## Integration examples
+
+In these examples I'll refer to the usage of UNIX sockets. They are more secure than TCP/UDP sockets because
+they have file permissions, they can be "masked" using mount namespaces, etc.
+However, circlogd supports udp/tcp sockets easily, so that should not be an issue.
+
+### syslog-ng
+
+To integrate into syslog-ng, put this in `/etc/syslog-ng/conf.d/circolog.conf`
+```
+destination d_circolog {
+        unix-dgram("/run/circolog-syslog.sock"
+                   flags(syslog-protocol)
+                  );
+};
+log { source(s_src); destination(d_circolog); };
+```
+and run `circologd -syslogd-socket /run/circolog-syslog.sock -query-socket /run/circolog-query.sock`
+
+
+## Client
+
+`curl` might be enough of a client for most uses.
+
+    curl --unix-socket /run/circolog-query.sock localhost/
+
+will give you everything that circologd has in memory
+
+If you want to "follow" (as in `tail -f`) you need to use the websocket interface. However, I don't know of
+any websocket client supporting UNIX domain socket, so you have two options:
+
+ 1. wait until I write a proper `circolog-tail` client implementing it all
+ 2. Use `circologd` with `-query-addr 127.0.0.1:9080`, add some iptables rule to prevent non-root to access that
+    port, and run `ws ws://localhost:9080/ws`. You'll get all the "backlog", and will follow new log messages.