11 files changed, 326 insertions, 0 deletions
diff --git a/doc/02-Installation.md b/doc/02-Installation.md
new file mode 100644
index 0000000..607996c
--- /dev/null
+++ b/doc/02-Installation.md
@@ -0,0 +1,38 @@
+<a id="Installation"></a>Installation
+=====================================
+
+## Requirements
+
+* Icinga Director (&gt;= 1.1.0)
+* php-xml for optional XML file support
+* php-yaml for optional YAML file support
+* php-zip for optional XLSX file support
+
+When running `PHP 7.x` you'll need the latest `2.x beta` version for [php-yaml](http://pecl.php.net/package/yaml).
+In case your Linux distribution offers precompiled packages they should be fine, regardless of whether they ship `php-yaml` or `php-syck`. In either case please
+let me know as I didn't test them on different operatingsystems yet.
+
+## Install the Fileshipper module
+
+As with any Icinga Web 2 module, installation is pretty straight-forward. In
+case you're installing it from source, all you have to do is to drop the `fileshipper`
+module in one of your module paths. You can examine (and set) the module path(s)
+in `Configuration / Application`. In a typical environment you'll probably drop the
+module to `/usr/share/icingaweb2/modules/fileshipper`. Please note that the directory
+name MUST be `fileshipper` and not `icingaweb2-module-fileshipper` or anything else.
+To do so you could run the following commands on the CLI.
+
+```sh
+cd /usr/share/icingaweb2/modules
+git clone https://github.com/Icinga/icingaweb2-module-fileshipper.git fileshipper
+```
+
+Last but not least go to `Configuration / Modules` and enable the `fileshipper`
+module, or run the following command on the CLI:
+
+```sh
+icingacli module enable fileshipper
+```
+
+That's all, now you are ready to define your first [Import Source](03-ImportSource.md)
+definitions and to ship hand-crafted plain Icinga 2 [Config Files](04-FileShipping.md)!
diff --git a/doc/03-ImportSource.md b/doc/03-ImportSource.md
new file mode 100644
index 0000000..16db474
--- /dev/null
+++ b/doc/03-ImportSource.md
@@ -0,0 +1,73 @@
+<a id="ImportSource"></a>Use plain files as an Import Source
+============================================================
+
+The following screenshot shows a bunch of `Import Source` definitions defined
+in the `Icinga Director` based on the this module:
+
+![Icinga Web 2 Fileshipper](screenshot/fileshipper/01_fileshipper-imports-overview.png)
+
+Hint: This chapter assumes that you are already familiar with the `Icinga Director`
+[Import and Sync](https://github.com/Icinga/icingaweb2-module-director/blob/master/doc/70-Import-and-Sync.md) mechanism.
+
+
+<a id="fileshipper-importsource"></a>Add a new Import Source
+------------------------------------------------------------
+
+Given that, the next steps should be fairly easy. From the Import Source overview
+shown above click `Add import source` and choose the `Import from files` option
+provided by the `fileshipper` module:
+
+![Add a Fileshipper Import Source](screenshot/fileshipper/02_fileshipper-add-importsource.png)
+
+
+<a id="fileshipper-format"></a>Choose a File Format
+---------------------------------------------------
+
+Next opt for a specific `File Format`:
+
+![Choose a File Format](screenshot/fileshipper/03_fileshipper-choose-format.png)
+
+Some file formats may ask for additional settings like the `CSV` one does:
+
+![CSV file format settings](screenshot/fileshipper/05_fileshipper-csv-details.png)
+
+In case you want to learn more about supported file formats please read the
+related [documentation](11-FileFormats.md).
+
+<a id="fileshipper-file"></a>Select Directory and File(s)
+---------------------------------------------------------
+
+You are also asked to choose a `Base Directory`:
+
+![Choose a Base Directory](screenshot/fileshipper/04_fileshipper-choose-basedir.png)
+
+Initially, this list is empty. The module doesn't allow you to freely choose any
+file on your system. You have to provide a safe set of base directories in your
+`fileshipper`'s module config directory, usually `/etc/icingaweb2/modules/fileshipper`.
+There you need to create an `imports.ini` that could look as follows:
+
+```ini
+[A bunch of files]
+basedir = "/var/cache/various_files"
+
+[Puppet facts store (YAML directory)]
+basedir = "/var/cache/sample-nodes"
+```
+
+Now you are ready to choose a specific file:
+
+![Choose a specific file](screenshot/fileshipper/06_fileshipper-choose-file.png)
+
+For some use-cases it might also be quite useful to import `all files` in a given
+directory at once:
+
+<a id="fileshipper-puppet"></a>Special Use Case: Puppet
+-------------------------------------------------------
+
+![Choose a specific file](screenshot/fileshipper/07_fileshipper-whole-directory.png)
+
+The example on the screenshot has been configured to import all hosts from a
+Puppet-based environment. If there where a PuppetDB it would have made more sense
+to use the [PuppetDB module](https://github.com/Thomas-Gelf/icingaweb2-module-puppetdb).
+But without such, the `facts store` on the Puppet Master makes still a good data
+source for this task.
diff --git a/doc/04-FileShipping.md b/doc/04-FileShipping.md
new file mode 100644
index 0000000..757b784
--- /dev/null
+++ b/doc/04-FileShipping.md
@@ -0,0 +1,39 @@
+<a id="FileShipping"></a>Plain config file shipping
+===================================================
+
+Icinga 2 offers a very powerful configuration format. By definition, it isn't
+a configuration format at all, it's a DSL, a Domain Specific Language. There is
+no chance to implement all of it's feature in a config tool like Icinga Director,
+that would make as much sense as trying to create a GUI for Ruby or Perl.
+
+So, sometimes one might want to ship additional hand-crafted Icinga 2 config
+files not generated by the Director. Sadly, that way you loose a lot of it's
+features like tracking changes, keeping deployment history and more. That's what
+this part of fileshipper has been designed for. It allows you to tell Director
+to deploy additional config files without even trying to understand them.
+
+To enable this, please create a `directories.ini` in this modules config dir,
+usually `/etc/icingaweb2/modules/fileshipper`:
+
+```ini
+[custom-rules]
+source = /usr/local/src/custom-rules.git
+target = zones.d/director-global/custom-rules
+
+[test]
+source = /tmp/replication-test
+target = zones.d/director-global/having-fun
+extensions = .conf .md
+```
+
+In this example all local files from `source` will be deployed to the given target
+directory. Please take care, use of this module requires advanced understanding of
+Icinga2 configuration. Per default only `.conf` files are synced, you can override
+this with a custom space-separated list for the `extensions` parameter.
+
+In case you want to trigger specific actions like re-rendering or deploying the
+config on changes you might want to have a look at our sample GIT hook in
+[contrib/git-hooks/post-merge](../contrib/git-hooks/post-merge).
+
+When working with Puppet or similar, please consider notifying an `exec` resource
+with `refreshonly` set to `true` instead.
diff --git a/doc/11-FileFormats.md b/doc/11-FileFormats.md
new file mode 100644
index 0000000..5147ceb
--- /dev/null
+++ b/doc/11-FileFormats.md
@@ -0,0 +1,176 @@
+<a id="FileFormats"></a> Supported File Formats
+===============================================
+
+Depending on the installed libraries the Import Source currently supports
+multiple file formats. In case you're missing any of the following formats
+in your Director frontend please re-read our [Installation instructions](02-Installation.md).
+
+
+CSV (Comma Separated Value)
+---------------------------
+
+[CSV](https://en.wikipedia.org/wiki/Comma-separated_values) is a not so well
+defined data format, therefore the Import Source has to make some assumptions
+and ask for optional settings.
+
+Basically, the rules to follow are:
+
+* a header line is required
+* each row has to have as many columns as the header line
+* defining a value enclosure is mandatory, but you do not have to use it in your
+  CSV files. So while your import source might be asking for `"hostname";"ip"`,
+  it would also accept `hostname;ip` in your source files
+* a field delimiter is required, this is mostly comma (`,`) or semicolon (`;`).
+  You could also opt for other separators to fit your very custom file format
+  containing tabular data
+
+### Sample CSV file
+
+```csv
+"host","address","location"
+"csv1.example.com","127.0.0.1","HQ"
+"csv2.example.com","127.0.0.2","HQ"
+"csv3.example.com","127.0.0.3","HQ"
+```
+
+### More complex but perfectly valid CSV sample
+
+```csv
+"hostname","ip address","location"
+csv1,"127.0.0.2","H\"ome"
+"csv2",127.0.0.2,"asdf"
+"csv3","127.0.0.3","Nott"", at Home"
+```
+
+
+JSON - JavaScript Object Notation
+---------------------------------
+
+[JSON](https://en.wikipedia.org/wiki/JSON) is a pretty simple standarized format
+with good support among most scripting and programming languages. Nothing special
+to say here, as it is easy to validate.
+
+### Simple JSON example
+
+This example shows an array of objects:
+
+```json
+[{"host": "json1", "address": "127.0.0.1"},{"host": "json2", "address": "127.0.0.2"}]
+```
+
+This is the easiest machine-readable form of a JSON import file.
+
+
+### Pretty-formatted extended JSON example
+
+Single-line JSON files are not very human-friendly, so you'll often meet pretty-
+printed JSON. Such files also make also prefectly valid import candidates:
+
+```json
+{
+  "json1.example.com": {
+    "host": "json1.example.com",
+    "address": "127.0.0.1",
+    "location": "HQ",
+    "groups": [ "Linux Servers" ]
+  },
+  "json2.example.com": {
+    "host": "json2.example.com",
+    "address": "127.0.0.2",
+    "location": "HQ",
+    "groups": [ "Windows Servers", "Lab" ]
+  }
+}
+```
+
+Microsoft Excel
+---------------
+
+XSLX, the Microsoft Excel 2007+ format is supported since v1.1.0.
+
+
+XML - Extensible Markup Language
+--------------------------------
+
+When working with [XML](https://en.wikipedia.org/wiki/XML) please try to ship
+simple files as shown in the following example. We'd love to add more features
+like better attribute support or [XPath](https://en.wikipedia.org/wiki/XPATH)-
+based filters. In case you need such, please let us know and ship some exmple
+data, helping us to better understand your requirements!
+
+### Simple XML example
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?> 
+<hosts>
+  <host>
+    <name>xml1</name>
+    <address>127.0.0.1</address>
+  </host>
+  <host>
+    <name>xml2</name>
+    <address>127.0.0.2</address>
+  </host>
+</hosts>
+```
+
+
+YAML (Ain't Markup Language)
+----------------------------
+
+[YAML](https://en.wikipedia.org/wiki/YAML) is all but simple and well defined,
+it allows you to write the same data in various ways. In case you opt for it
+you might have your reasons and should already be familiar with how to generate
+such files.
+
+### Simple YAML example
+
+So, let's start with a simple example:
+
+```yaml
+---
+- host: "yaml1.example.com"
+  address: "127.0.0.1"
+  location: "HQ"
+- host: "yaml2.example.com"
+  address: "127.0.0.2"
+  location: "HQ"
+- host: "yaml3.example.com"
+  address: "127.0.0.3"
+  location: "HQ"
+```
+
+### Advanced YAML example
+
+People who think that NoSQL solves all there data problems tend to believe that
+YAML solve all their config problems. So, YAML is pretty hip and widely used
+among tools in hyped niches such as configuration management. I'll pick [Puppet](https://puppet.com/)
+as an example, but this might work in a similar way for many other tools.
+
+Instead of a single YAML file I have to deal with a directory full of files in
+this case. Our [Import Source documentation](03-ImportSource.md) already shows
+how to configure such, here you can see part of such a file:
+
+```yaml
+--- !ruby/object:Puppet::Node::Facts
+  name: foreman.localdomain
+  values: 
+    architecture: x86_64
+    timezone: CEST
+    kernel: Linux
+    system_uptime: "{\x22seconds\x22=>5415, \x22hours\x22=>1, \x22days\x22=>0, \x22uptime\x22=>\x221:30 hours\x22}"
+    domain: localdomain
+    virtual: kvm
+    is_virtual: "true"
+    hardwaremodel: x86_64
+    operatingsystem: CentOS
+    facterversion: "2.4.6"
+    filesystems: xfs
+    fqdn: foreman.localdomain
+    hardwareisa: x86_64
+    hostname: foreman
+```
+
+If this looks foreign to you don't worry, most similar constructs are handled in
+a smooth way by the underlying YAML parser.
+
diff --git a/doc/screenshot/fileshipper/01_fileshipper-imports-overview.png b/doc/screenshot/fileshipper/01_fileshipper-imports-overview.png
new file mode 100644
index 0000000..4a10487
--- /dev/null
+++ b/doc/screenshot/fileshipper/01_fileshipper-imports-overview.png
diff --git a/doc/screenshot/fileshipper/02_fileshipper-add-importsource.png b/doc/screenshot/fileshipper/02_fileshipper-add-importsource.png
new file mode 100644
index 0000000..8bfbc15
--- /dev/null
+++ b/doc/screenshot/fileshipper/02_fileshipper-add-importsource.png
diff --git a/doc/screenshot/fileshipper/03_fileshipper-choose-format.png b/doc/screenshot/fileshipper/03_fileshipper-choose-format.png
new file mode 100644
index 0000000..47fa9b6
--- /dev/null
+++ b/doc/screenshot/fileshipper/03_fileshipper-choose-format.png
diff --git a/doc/screenshot/fileshipper/04_fileshipper-choose-basedir.png b/doc/screenshot/fileshipper/04_fileshipper-choose-basedir.png
new file mode 100644
index 0000000..a3258e3
--- /dev/null
+++ b/doc/screenshot/fileshipper/04_fileshipper-choose-basedir.png
diff --git a/doc/screenshot/fileshipper/05_fileshipper-csv-details.png b/doc/screenshot/fileshipper/05_fileshipper-csv-details.png
new file mode 100644
index 0000000..9936e78
--- /dev/null
+++ b/doc/screenshot/fileshipper/05_fileshipper-csv-details.png
diff --git a/doc/screenshot/fileshipper/06_fileshipper-choose-file.png b/doc/screenshot/fileshipper/06_fileshipper-choose-file.png
new file mode 100644
index 0000000..e20ba49
--- /dev/null
+++ b/doc/screenshot/fileshipper/06_fileshipper-choose-file.png
diff --git a/doc/screenshot/fileshipper/07_fileshipper-whole-directory.png b/doc/screenshot/fileshipper/07_fileshipper-whole-directory.png
new file mode 100644
index 0000000..4f66c1c
--- /dev/null
+++ b/doc/screenshot/fileshipper/07_fileshipper-whole-directory.png