forked from boyska/circolog
85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
A syslog daemon implementing circular buffer, in-memory storage.
|
|
|
|
This is useful when you want to keep some (heavily detailed) log available, but you don't want to log too many
|
|
things to disk. Remember: logging is useful, but can be dangerous to your users' privacy!
|
|
|
|
On your "main" syslog, forward (part of the) messages 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
|
|
|
|
`circolog` has its own client: `circolog-tail`. It is intended to resemble `tail -f` for the most basic
|
|
options; however, it will include filtering options that are common when you want to read logs, because that's
|
|
very easy when you have structured logs available.
|
|
|
|
However, one design point of circolog is to be usable without having a specific client: so the logs are
|
|
offered on both HTTP and websocket. This means that you can use `curl` if you want:
|
|
|
|
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. Use `circolog-tail`
|
|
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.
|
|
|
|
### HTTP URLs and parameters
|
|
|
|
When using HTTP, logs are served on `/`. Valid parameters are:
|
|
|
|
* `l`. This is the amount of lines to send. This is essentially the same as the `-n` parameter on tail
|
|
Using `l=-1` (the default) means "give me every log message that you have
|
|
* `fmt`. This selects the output format. When `fmt=json` is used, each message is returned as JSON structured
|
|
data. The format of those JSON messages is still unstable. `fmt=syslog`, the default, outputs messages using "syslog style" (RFC XXXXXX)
|
|
|
|
To use websocket, request path `/ws`. The same parameters of `/` are recognized.
|
|
|
|
## Control daemon
|
|
|
|
Circologd can be controlled, on some aspects, at run-time. It has 2 mechanisms for that: the easiest, and more
|
|
limited, is sending a signal with kill; the second, and more powerful, is a control socket, where you can give
|
|
commands to it. This control socket is just HTTP, so again `curl` is your friend. In the future a
|
|
`circolog-ctl` client will be developed.
|
|
|
|
### Pause
|
|
|
|
When circologd is paused, every new message it receives is immediately discarded. No exception. The backlog
|
|
is, however, preserved. This means that you can trigger the event that you want to investigate, pause
|
|
circolog, then analyze the logs.
|
|
Pausing might be the easiest way to make circologd only run "when needed".
|
|
|
|
When circologd resumes, no previous message is lost.
|
|
|
|
|
|
To pause circologd with signals , send a `USR1` signal to the main pid. To "resume", send a `USR1` again.
|
|
|
|
To pause with HTTP, send a `POST /pause/toggle` to your circologd control socket.
|
|
|
|
### Clear
|
|
|
|
When you clear the circologd's buffer, it will discard every message it has, but will keep collecting new
|
|
messages.
|
|
|
|
You can do that with `POST /logs/clear`
|