Add README

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
index 0000000..90c5eff
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,65 @@
+= README
+
+check_dmesg is a Nagios-compatible check script to monitor `dmesg` for error
+messages. It requires `journalctl` to load messages from dmesg. It's written
+in Go and licensed under GPLv3+.
+
+
+== Usage
+
+    # check_dmesg
+    err/2026-02-07T11:21:43+01:00: [Firmware Bug]: the BIOS has corrupted hw-PMU resources (MSR 38d is 330)
+    emerg/2026-02-07T11:21:43+01:00: RDSEED32 is broken. Disabling the corresponding CPUID bit.
+
+Unimportant messages can be ignored using regular expressions:
+
+    # check_dmesg '^\[Firmware Bug\]' 'RDSEED32 is broken'
+
+Per default messages with priority `err` (3) and higher (`crit`, `alert`,
+`emerg`) are displayed. Use the `-prio` option to change that. For example,
+use `-prio 4` to also show warning messages.
+
+To ignore one-time messages a state file can be used in combination with the
+`-clear` option/command:
+
+    # check_dmesg -state /var/lib/check_dmesg
+    err/2026-02-07T11:21:43+01:00: [Firmware Bug]: the BIOS has corrupted hw-PMU resources (MSR 38d is 330)
+    emerg/2026-02-07T11:21:43+01:00: RDSEED32 is broken. Disabling the corresponding CPUID bit.
+    # check_dmesg -state /var/lib/check_dmesg -clear
+
+The state file saves the list of un-cleared messages (to prevent losing them
+when journald rotates old messages) and the last position in the journal (so
+only new messages are shown). `-clear` discards all saved messages. Only new
+messages are affected when changing `-prio` or ignored messages.
+
+
+== Installation
+
+    $ go build
+
+Copy `check_dmesg` to the system, e.g. into `/usr/local/lib/nagios/plugins/`.
+
+
+== Authors
+
+Written by Simon Ruderich <simon@ruderich.org>.
+
+
+== License
+
+This program is licensed under GPL version 3 or later.
+
+Copyright (C) 2026  Simon Ruderich
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.