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
+````