From ff3b988324a5756f1e4e56c7cd94c3799378f3a4 Mon Sep 17 00:00:00 2001
From: Eric Lippmann <eric.lippmann@netways.de>
Date: Tue, 18 Nov 2014 16:21:48 +0100
Subject: [PATCH] doc: View resource configuration directives as table

---
 doc/resources.md | 140 ++++++++++++++++++++++-------------------------
 1 file changed, 64 insertions(+), 76 deletions(-)

diff --git a/doc/resources.md b/doc/resources.md
index cddfb04d1..fcded81c7 100644
--- a/doc/resources.md
+++ b/doc/resources.md
@@ -1,96 +1,84 @@
-# Resources
+# <a id="resources"></a> Resources
 
-The configuration file *config/resources.ini* contains data sources that can be referenced
-in other configurations. This allows you to manage all connections to databases at one central
-place, avoiding the need to edit several different files, when the connection information of a resource change.
+The INI configuration file **config/resources.ini** contains information about data sources that can be referenced in other
+configuration files. This allows you to manage all data sources at one central place, avoiding the need to edit several
+different files, when the information about a data source changes.
 
-## Configuration
+## <a id="resources-configuration"></a> Configuration
 
-Each section represents a resource, with the section name being the identifier used to
-reference this certain section. Depending on the resource type, each section contains different properties.
-The property *type* defines the resource type and thus how the properties are going to be interpreted.
-The available resource types are 'db', 'statusdat', 'livestatus' and 'ldap' and are
-described in detail in the following sections:
+Each section in **config/resources.ini** represents a data source with the section name being the identifier used to
+reference this specific data source. Depending on the data source type, the sections define different directives.
+The available data source types are *db*, *ldap* and *livestatus* which will described in detail in the following
+paragraphs.
 
-### db
+### <a id="resources-configuration-database"></a> Database
 
-This resource type describes a SQL database on an SQL server. Databases can contain users and groups
-to handle authentication and permissions, or monitoring data using IDO.
+A Database resource defines a connection to a SQL databases which can contain users and groups
+to handle authentication and authorization, monitoring data or user preferences.
 
-- *db*:         defines the used database vendor, which could be a value like *mysql* or *pgsql*.
-- *host*:       The hostname that is used to connect to the database.
-- *port*:       The port that is used to connect to the database.
-- *username*:   The user name that is used to authenticate.
-- *password*:   The password of the user given in *username*.
-- *dbname*:     The name of the database that contains the resources data.
+Directive       | Description
+----------------|------------
+**type**        | `db`
+**db**          | Database management system. Either `mysql` or `pgsql`.
+**host**        | Connect to the database server on the given host.
+**port**        | Port number to use for the connection.
+**username**    | The username to use when connecting to the server.
+**password**    | The password to use when connecting to the server.
+**dbname**      | The database to use.
 
-### ldap
+**Example:**
 
-The resource is a tree in a ldap domain. This resource type is usually used to fetch users and groups
-to handle authentication and permissions.
-
-- *hostname*:   The hostname that is used to connect to the ldap server.
-- *port*:       The port that is used to connect to the ldap server.
-- *root_dn*:    The root object of the tree. This is usually an organizational unit like
-                "ou=people, dc=icinga, dc=org".
-- *bind_dn*:    The user on the LDAP server that will be used to access it. Usually something
-                like "cn=admin, cn=config".
-- *bind_pw*:    The password of the user given in *bind_dn*.
+```
+[icingaweb]
+type      = db
+db        = mysql
+host      = localhost
+port      = 3306
+username  = icingaweb
+password  = icingaweb
+dbname    = icingaweb
+```
 
 
-### livestatus
+### <a id="resources-configuration-ldap"></a> LDAP
 
-A resource that points to a livestatus socket. This resource type contains monitoring data.
+A LDAP resource represents a tree in a LDAP directory. LDAP is usually used for authentication and authorization.
 
-- *socket*:     The livestatus socket. Can be either be a path to a domain socket (like
-                "/usr/local/icinga-mysql/var/rw/live") or to a TCP socket like
-                (tcp://<domain>:<port>)
+Directive       | Description
+----------------|------------
+**type**        | `ldap`
+**hostname**    | Connect to the LDAP server on the given host.
+**port**        | Port number to use for the connection.
+**root_dn**     | Root object of the tree, e.g. "ou=people,dc=icinga,dc=org"
+**bind_dn**     | The user to use when connecting to the server.
+**bind_pw**     | The password to use when connecting to the server.
 
-### statusdat
+**Example:**
 
-A resource that points to statusdat files. This resource type contains monitoring data.
-
-- *status_file*: The path to the *status.dat* file, like "/usr/local/icinga-mysql/var/status.dat"
-- *object_file*: The path to *objects.cache*, like "/usr/local/icinga-mysql/var/objects.cache"
+````
+[ad]
+type      = ldap
+hostname  = localhost
+port      = 389
+root_dn   = "ou=people,dc=icinga,dc=org"
+bind_dn   = "cn=admin,ou=people,dc=icinga,dc=org"
+bind_pw   = admin`
+````
 
 
-## Factory Implementations
+### <a id="resources-configuration-livestatus"></a> Livestatus
 
-This section contains documentation documentation for the Icinga2-Web developers that want to
-use resources defined in the *resources.ini*. Each supported resource type should have an own
-factory class, that can be used to comfortably create instances of classes that provide access
-to the data of the resources.
+A Livestatus resource represents the location of a Livestatus socket which is used for fetching monitoring data.
 
+Directive       | Description
+----------------|------------
+**type**        | `livestatus`
+**socket**      | Location of the Livestatus socket. Either a path to a local Livestatus socket or a path to a remote Livestatus socket in the format `tcp://<host>:<port>`.
 
-### ResourceFactory
+**Example:**
 
-The ResourceFactory can be used to retrieve objects to access resources. Lets assume
-for the following examples, that we have an *resources.ini* that looks like this:
-
-    [statusdat]
-    type                = statusdat
-    status_file         = /usr/local/icinga-mysql/var/status.dat
-    object_file         = /usr/local/icinga-mysql/var/objects.cache
-
-    [ldap_authentication]
-    type                = "ldap"
-    hostname            = "localhost"
-    port                = "389"
-    root_dn             = "ou=people, dc=icinga, dc=org"
-    bind_dn             = "cn=admin, cn=config"
-    bind_pw             = "admin"
-
-
-Here is an example of how to retrieve the resource 'statusdat' from the factory.
-
-    $resource = ResourceFactory::createResource(
-        ResourceFactory::getResourceConfig('statusdat')
-    );
-
-If you specify a resource that does not exist or has the wrong type,
-the factory will throw an ConfigurationException.
-
-
-You can also retrieve a list of all available resources by calling *getResourceConfigs*.
-
-    $resourceConfigs = ResourceFactory::getResourceConfigs();
+````
+[livestatus]
+type    = livestatus
+socket  = /var/run/icinga2/cmd/livestatus
+````