Add README.md file

Signed-off-by: David Oberhollenzer <david.oberhollenzer@tele2.at>

2 files changed, 119 insertions, 1 deletions

diff --git a/Makefile.am b/Makefile.am
index f4719a3..296bf99 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -10,4 +10,4 @@ syslog_SOURCES = syslog.c protomap.c
 dist_man1_MANS = syslog.1
 bin_PROGRAMS = syslog
 sbin_PROGRAMS = usyslogd klogd
-EXTRA_DIST = LICENSE
+EXTRA_DIST = LICENSE README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3c83d68
--- /dev/null
+++ b/README.md
@@ -0,0 +1,118 @@
+# About
+
+This package contains a tiny syslogd implementation called `usyslogd` and
+accompanying utilities, such as a tiny `klogd` that forwards kernel message
+to syslog and a utility program called `syslog` that can be used to generate
+syslog message from the command line or shell scripts.
+
+The syslog daemon opens a socket in `/dev/log`, processes syslog messages and
+forwards the parsed message to a modular backend interface.
+
+Currently, there is only one implementation of the backend interface that dumps
+the log messages into files in the processes working directory (by default
+`/var/log`).
+
+A simple log rotation scheme has been implemented.
+
+## License
+
+The source code in this package is provided under the OpenBSD flavored ISC
+license. So you can practically do as you wish, as long as you retain the
+original copyright notice.
+
+
+## Portability
+
+The programs in this package have been written for and tested on a GNU/Linux
+system, so their may be some GNU-isms in there in addition to Linux specific
+code.
+
+The `usyslogd` implementation has not been written to any specifications but
+instead to work with the messages generated by Musl libc. It may not properly
+parse the formats generated by other libc implementations or by programs that
+roll their own.
+
+The `klogd` daemon is Linux specific but independent of the syslog
+implementation and could in theory be used with other syslog daemons.
+
+The `syslog` utility program only uses functionality form the standard C
+library and should *in theory* work on any modern GNU/Linux or BSD system.
+The facility IDs may need to be adjusted (it uses the ones from `usyslogd`).
+
+
+The file backend of `usyslogd` tries to take over ownership of `/var/log`
+and make it inaccessible for all other users. This may be an issue if some
+program tries to put its own log files there as non-root user, or programs
+that try to read from them as non-root (e.g. `utmp`, `btmp`, `wtmp`, `faillog`,
+`lastlog`).
+
+
+# The syslog implementation
+
+## Security Considerations
+
+By default, the daemon switches its working directory to `/var/log`. The
+directory is created if it doesn't exist and the daemon always tries to
+change its mode to one that doesn't allow other users (except group members)
+to access the directory.
+
+If told to so on the command line, the daemon chroots to the log directory.
+
+By default, the daemon then tries to drop privileges by switching to user and
+group named `syslogd` if they exist (any other user or group can be specified
+on the command line; doing so causes syslogd to fail if they don't exist).
+
+
+On a system that hosts accounts for multiple users that may be more or less
+trusted, one may consider only giving system services access to the syslog
+socket and not allowing regular users. Otherwise, a user may flood the syslog
+daemon with messages, possibly leading to resource starvation, or (in the case
+of size limited log rotation outlined below) to the loss of otherwise critical
+log messages. Since this is not the primary target of the Pygos system that
+this package has been written for, such a mechanism is not yet implemented.
+
+In case of a system where only daemons are running, the above mentioned
+security measure is useless. If a remote attacker manages to get regular user
+privileges, you already have a different, much greater problem. Also, a remote
+attacker would have to compromise a local daemon that already has special
+access to the syslog socket, which is again your least concern in this
+scenario.
+
+
+## Logrotation
+
+The backend can be configured to do log rotation in a continuous fashion (i.e.
+in a way that log messages aren't lost), or in a way where it drops old
+messages. Furthermore, the backend can be configured to automatically do a log
+rotation if a certain size threshold is hit.
+
+If the `usyslogd` receives a `SIGHUP`, it tells the backend to do log rotation.
+
+In the case of the size threshold, the backend is expected to do the rotation
+on its own if the predetermined limit is hit.
+
+
+## File Based Backend
+
+The file based backend writes log messages to files in the current working
+directory (by default `/var/log`), named either after the ident string (if
+specified) or the facility name.
+
+Log messages are prefixed with an ISO 8601 time stamp, optionally the facility
+name (unless part of the file name), the log level and the senders PID. Each
+of those fields is enclosed in brackets.
+
+Log rotation in a continuous fashion means renaming the existing log file to
+one suffixed with the current time stamp. Overwriting old messages renaming
+the log file by appending a constant `.1` suffix.
+
+
+# Possible Future Directions
+
+In the near term future, the daemon probably requires more fine grained control
+over logging such as setting a minimum log level or a way to configure limits
+per facility or service.
+
+Future directions may include adding other backends, such as forwarding the
+log messages to a central server, for instance using syslog over UDP/TCP or
+using the front end of some time series database.