1 files changed, 87 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e53e8b9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# Audit module for Icinga Web 2
+
+#### Table of Contents
+
+1. [About](#about)
+2. [License](#license)
+3. [Support](#support)
+4. [Requirements](#requirements)
+5. [Installation](#installation)
+6. [Configuration](#configuration)
+
+## About
+
+## License
+
+Icinga Web 2 and this Icinga Web 2 module are licensed under the terms of the GNU General Public License Version 2,
+you will find a copy of this license in the LICENSE file included in the source package.
+
+## Support
+
+Join the [Icinga community channels](https://www.icinga.com/community/get-involved/) for questions.
+
+## Requirements
+
+* [Icinga Web 2](https://www.icinga.com/products/icinga-web-2/) (>= 2.6.0)
+
+## Installation
+
+Extract this module to your Icinga Web 2 modules directory as `audit` directory.
+
+Git clone:
+
+    cd /usr/share/icingaweb2/modules
+    git clone https://github.com/Icinga/icingaweb2-module-audit.git audit
+
+Tarball download (latest [release](https://github.com/Icinga/icingaweb2-module-audit/releases/latest)):
+
+    cd /usr/share/icingaweb2/modules
+    wget https://github.com/Icinga/icingaweb2-module-audit/archive/v1.0.0.zip
+    unzip v1.0.0.zip
+    mv icingaweb2-module-audit-1.0.0 audit
+
+### Enable Icinga Web 2 module
+
+Enable the module in the Icinga Web 2 frontend in `Configuration -> Modules -> audit -> enable`.
+You can also enable the module by using the `icingacli` command:
+
+    icingacli module enable audit
+
+## Configuration
+
+By default the audit module does not log anything. Its logging facilities need to be configured first.
+
+There are currently two choices:
+
+* Standard Log
+* JSON Log
+
+### Standard Log
+
+The standard log is a normal log with human readable messages. It's possible to log to a file and to syslog.
+The configuration view in the frontend is located here: `Configuration -> Modules -> audit -> Configuration`
+
+> **Note**
+>
+> When logging to a file and with the proper permission, this can be viewed in the frontend under `Reporting -> Audit Log`
+
+### JSON Log
+
+The JSON log is supposed to be consumed by other applications. It writes one JSON object per line to a file.
+
+These objects have the following properties:
+
+* `activity_time`  
+    A unix timestamp specifying when the activity occurred.
+* `activity`  
+    An arbitrary identifier specifying the type of activity.
+* `identity`  
+    An arbitrary name identifying the responsible subject.
+* `message`  
+    A human readable message. This is the same that appears in the standard log.
+* `data` *(may be absent)*  
+    An arbitrary number of additional properties dependent on the type of activity.
+
+Please see the documentation of the type of activity for more details. ([Icinga Web 2 activities](https://www.icinga.com/docs/icingaweb2/latest/doc/15-Auditing/))
+
+An example for *Filebeat* how this log may be consumed can be found [here](https://www.elastic.co/blog/structured-logging-filebeat).