doc: View resource configuration directives as table

This commit is contained in:
Eric Lippmann 2014-11-18 16:21:48 +01:00
parent 3df3018735
commit ff3b988324
1 changed files with 64 additions and 76 deletions

View File

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