fmnisme · fmnisme · Mar 7, 2016 · Mar 7, 2016 · Mar 7, 2016 · Mar 7, 2016
diff --git a/README.md b/README.md
@@ -1,40 +1,17 @@
 #Feature
-1. basic auth
-2. objects(zone support)
-3. actions
-4. events
-5. status
 
-#Developing
-1. cert auth
-2. Configuration Management
-
-#Usage
-```
-from icinga2api.client import Client
-client = Client('https://localhost:5665','username','passowrd')
+1. basic and certificate auth
+1. config file support
+1. objects (zone support)
+1. actions
+1. events
+1. status
 
-#list host
-```
-filters = {
-    "attrs" : ["name", "address"],
-}
-client.objects.list('hosts',filters=filters)
-```
+#Developing
 
-#create host
-```
-config = {
-    "templates": [ "generic-host" ],
-    "attrs": {
-        "address": "192.168.1.100",
-        'vars.os': 'Windows',
-        'vars.services.mysql': {'ports': [3306, 3307]},
-        'zone' : 'Zone1',
-    }
-}
-print client.objects.create('hosts','test1',config)
-```
+1. Code cleanup
+1. Configuration Management
 
+#Usage
 
-**read source commentary for more examples.**
+See the **doc** directory.
diff --git a/doc/1-about.md b/doc/1-about.md
@@ -0,0 +1,16 @@
+# <a id="about-icinga2"></a> About python-icinga2api
+
+python-icinga2api is a [Python](http://www.python.org) module to interact with the [Icinga 2 RESTful API](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/icinga2-api).
+
+## <a id="features"></a> Features
+
+1. basic and certificate auth
+1. config file support
+1. objects (zone support)
+1. actions
+1. events
+1. status
+
+## <a id="development-info"></a> Development
+
+The code is based on [fmnisme's version](https://github.com/fmnisme/python-icinga2api). Forking, reporting bugs and sending PRs is very appreciated.
diff --git a/doc/2-authentication.md b/doc/2-authentication.md
@@ -0,0 +1,49 @@
+# <a id="basics"></a> Basics
+
+## <a id="authentication"></a> Authentication
+
+You can use the client with either username/password combination or using certificates.
+
+Example using username and password:
+
+    from icinga2api.client import Client
+    client = Client('https://localhost:5665', 'username', 'password')
+
+Example using certificates:
+
+    from icinga2api.client import Client
+    client = Client('https://icinga2:5665',
+                    certificate='/etc/ssl/certs/myhostname.crt',
+                    key='/etc/ssl/keys/myhostname.key')
+
+If your public and private are in the same file, just use the `certificate` parameter.
+
+
+## <a id="config-file"></a> Config file
+
+You can also specify a config file (in ini format) containing all necessary information.
+
+Example:
+
+    client = Client('https://localhost:5665', config_file='/etc/icinga2api')
+
+The config file looks like:
+
+    [api]
+    url = https://icinga2:5665
+    certificate = /etc/ssl/certs/myhostname.crt
+    key = /etc/ssl/private/myhostname.key
+    ca_certificate = /etc/ssl/certs/ca.crt
+
+
+## <a id="server-verification"></a> Server verification
+
+To verify the server certificate specify a ca file as `ca_file` parameter.
+
+Example:
+
+    from icinga2api.client import Client
+    client = Client('https://icinga2:5665',
+                    certificate='/etc/ssl/certs/myhostname.crt',
+                    key='/etc/ssl/keys/myhostname.key',
+                    ca_file='/etc/ssl/certs/my_ca.crt')
diff --git a/doc/3-objects.md b/doc/3-objects.md
@@ -0,0 +1,149 @@
+# <a id="objects"></a> Objects
+
+## <a id="objects-get"></a> objects.get()
+
+To get a single object (`Host`, `Service`, ...) use the funtion `objects.get()`.
+
+  Parameter      | Type      | Description
+  ---------------|-----------|------------
+  object\_type   | string    | **Required.** The object type to get, e.g. `Host`, `Service`.
+  name           | string    | **Required.** The objects name.
+  attrs          | list      | **Optional.** Get only the specified objects attributes.
+  joins          | bool      | **Optional.** Also get the joined object, e.g. for a `Service` the `Host` object.
+
+Examples:
+
+Get host `webserver01.domain`:
+
+    client.objects.get('Host', 'webserver01.domain')
+
+Get service `ping4` of host `webserver01.domain`:
+
+    client.objects.get('Service', 'webserver01.domain!ping4')
+
+Get host `webserver01.domain` but the attributes `address` and `state`:
+
+    client.objects.get('Host', 'webserver01.domain', attrs=['address', 'state'])
+
+Get service `ping4` of host `webserver01.domain` and the host attributes:
+
+    client.objects.get('Service', 'webserver01.domain!ping4', joins=True)
+
+## <a id="objects-list"></a> objects.list()
+
+To get a list of objects (`Host`, `Service`, ...) use the funtion `objects.list()`. You can use `filter` to ...
+
+  Parameter     | Type       | Description
+  --------------|------------|--------------
+  object\_type  | string     | **Required.** The object type to get, e.g. `Host`, `Service`.
+  name          | string     | **Optional.** The objects name.
+  attrs         | list       | **Optional.** Get only the specified objects attributes.
+  filter        | string     | **Optional.** The filter expression, see [documentation](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-filters).
+  filter\_vars  | dictionary | **Optional.** Variables which are available to your filter expression.
+  joins         | bool       | **Optional.** Also get the joined object, e.g. for a `Service` the `Host` object.
+
+Examples:
+
+Get all hosts:
+
+    client.objects.list('Host')
+
+Get all hosts but limit attributes to `address` and `state`
+
+    client.objects.list('Host', attrs=['address', 'state'])
+
+Get all hosts which have "webserver" in their host name
+
+    client.objects.list('Host', filter='match("webserver\*", host.name)')
+
+Get all services which names start with "vHost" and are assigned to hosts named "webserver\*" using `filter_vars`
+
+    hostname_pattern = 'webserver\*'
+    service_pattern = 'vHost\*'
+    client.objects.list('Service',
+                        filter='match(hpattern, host.name) && match(spattern, service.name)',
+                        filter_vars={'hpattern': hostname_pattern, 'spattern': service_pattern})
+
+Get all services and the joined host name:
+
+    client.objects.list('Service', joins=['host.name'])
+
+
+## <a id="objects-create"></a> objects.create()
+
+Create an object using `templates` and specify attributes (`attrs`).
+
+  Parameter     | Type       | Description
+  --------------|------------|--------------
+  object\_type  | string     | **Required.** The object type to get, e.g. `Host`, `Service`.
+  name          | string     | **Optional.** The objects name.
+  templates     | list       | **Optional.** A list of templates to import.
+  attrs         | dictionary | **Optional.** The objects attributes.
+
+Examples:
+
+Create a host:
+
+    client.objects.create(
+        'Host',
+        'localhost',
+        ['generic-host'],
+        {'address': '127.0.0.1'})
+
+Create a service for Host "localhost":
+
+    client.objects.create(
+        'Service',
+        'localhost!dummy',
+        ['generic-service'],
+        {'check_command': 'dummy'})
+
+
+## <a id="objects-update"></a> objects.update()
+
+Update an object with the specified attributes.
+
+  Parameter     | Type       | Description
+  --------------|------------|--------------
+  object\_type  | string     | **Required.** The object type to get, e.g. `Host`, `Service`.
+  name          | string     | **Optional.** The objects name.
+  attrs         | dictionary | **Optional.** The objects attributes.
+
+Examples:
+
+Change the ip address of a host:
+
+    client.objects.update(
+        'Host',
+        'localhost',
+        {'address': '127.0.1.1'})
+
+Update a service and change the check interval:
+
+    client.objects.create('Service',
+           'localhost!dummy',
+           ['generic-service'],
+           {'check_interval': '10m'})
+
+
+## <a id="objects-delete"></a> objects.delete()
+
+Update an object with the specified attributes.
+
+  Parameter     | Type       | Description
+  --------------|------------|--------------
+  object\_type  | string     | **Required.** The object type to get, e.g. `Host`, `Service`.
+  name          | string     | **Optional.** The objects name.
+  filter        | string     | **Optional.** Filter expression for matching the objects.
+  filter\_vars  | dictionary | **Optional.** Variables which are available to your filter expression.
+  cascade       | boolean    | **Optional.** Also delete dependent objects. Defaults to `True`.
+
+Examples:
+
+Delete the "localhost":
+
+    client.objects.delete('Host', 'localhost')
+
+Delete all services matching `vhost\*`:
+
+    client.objects.delete('Service', filter='match("vhost\*", service.name)')