doc: View resource configuration directives as table
This commit is contained in:
Eric Lippmann
parent
3df3018735
commit
ff3b988324
140
doc/resources.md
140
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
|
||||
````
|
||||
|
|
|
|||
Loading…
Reference in New Issue