Adding upstream version 2.12.1.upstream/2.12.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 136 insertions, 0 deletions

diff --git a/doc/04-Resources.md b/doc/04-Resources.md
new file mode 100644
index 0000000..ca362fa
--- /dev/null
+++ b/doc/04-Resources.md
@@ -0,0 +1,136 @@
+# Resources <a id="resources"></a>
+
+The configuration file `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>
+
+Each section in `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 `ssh` which will described in detail in the following
+paragraphs.
+
+Type                     | Description
+-------------------------|-----------------------------------------------
+db                       | A [database](04-Resources.md#resources-configuration-database) resource (e.g. Icinga 2 DB IDO or Icinga Web 2 user preferences)
+ldap                     | An [LDAP](04-Resources.md#resources-configuration-ldap) resource for authentication.
+ssh                      | Manage [SSH](04-Resources.md#resources-configuration-ssh) keys for remote access (e.g. command transport).
+
+
+### Database <a id="resources-configuration-database"></a>
+
+A Database resource defines a connection to a SQL database which
+can contain users and groups to handle authentication and authorization, monitoring data or user preferences.
+
+Option                              | Description
+------------------------------------|------------
+type                                | **Required.** Specifies the resource type. Must be set to `db`.
+db                                  | **Required.** Database type. In most cases `mysql` or `pgsql`.
+host                                | **Required.** Connect to the database server on the given host. For using unix domain sockets, specify `localhost` for MySQL and the path to the unix domain socket directory for PostgreSQL.
+port                                | **Required.** Port number to use. MySQL defaults to `3306`, PostgreSQL defaults to `5432`. Mandatory for connections to a PostgreSQL database.
+username                            | **Required.** The database username.
+password                            | **Required.** The database password.
+dbname                              | **Required.** The database name.
+charset                             | **Optional.** The character set for the database connection.
+use\_ssl                            | **Optional.** Use SSL. Enables the following SSL options.
+ssl\_do\_not\_verify\_server\_cert  | **Optional.** Disable validation of the server certificate. Only available for the `mysql` database and on PHP versions > 5.6.
+ssl\_cert                           | **Optional.** The file path to the SSL certificate. Only available for the `mysql` database.
+ssl\_key                            | **Optional.** The file path to the SSL key. Only available for the `mysql` database.
+ssl\_ca                             | **Optional.** The file path to the SSL certificate authority. Only available for the `mysql` database.
+ssl\_capath                         | **Optional.** The file path to the directory that contains the trusted SSL CA certificates, which are stored in PEM format.Only available for the `mysql` database.
+ssl\_cipher                         | **Optional.** A list of one or more permissible ciphers to use for SSL encryption, in a format understood by OpenSSL. For example: `DHE-RSA-AES256-SHA:AES128-SHA`. Only available for the `mysql` database.
+
+
+#### Example <a id="resources-configuration-database-example"></a>
+
+The name in brackets defines the resource name.
+
+```
+[icingaweb-mysql-tcp]
+type      = db
+db        = mysql
+host      = 127.0.0.1
+port      = 3306
+username  = icingaweb
+password  = icingaweb
+dbname    = icingaweb
+
+[icingaweb-mysql-socket]
+type      = db
+db        = mysql
+host      = localhost
+username  = icingaweb
+password  = icingaweb
+dbname    = icingaweb
+
+[icingaweb-pgsql-socket]
+type      = db
+db        = pgsql
+host      = /var/run/postgresql
+port      = 5432
+username  = icingaweb
+password  = icingaweb
+dbname    = icingaweb
+```
+
+### LDAP <a id="resources-configuration-ldap"></a>
+
+A LDAP resource represents a tree in a LDAP directory.
+LDAP is usually used for authentication and authorization.
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+type                     | **Required.** Specifies the resource type. Must be set to `ldap`.
+hostname                 | **Required.** Connect to the LDAP server on the given host. You can also provide multiple hosts separated by a space.
+port                     | **Required.** Port number to use for the connection.
+root\_dn                 | **Required.** Root object of the tree, e.g. `ou=people,dc=icinga,dc=org`.
+bind\_dn                 | **Required.** The user to use when connecting to the server.
+bind\_pw                 | **Required.** The password to use when connecting to the server.
+encryption               | **Optional.** Type of encryption to use: `none` (default), `starttls`, `ldaps`.
+timeout                  | **Optional.** Connection timeout for every LDAP connection. Defaults to `5`.
+disable_server_side_sort | **Optional.** Disable server side sorting. Defaults to automatic detection whether the server supports this.
+
+#### Server Side Sorting <a id="ldap-server-side-sort"></a>
+
+Icinga Web automatically detects whether the LDAP server supports server side sorting.
+If that is not the case, results get sorted on the client side.
+There are LDAP servers though which report that they support this feature in general but have it disabled for certain
+fields. This may lead to failures. With `disable_server_side_sort` it is possible to disable server side sorting and it
+has precedence over the automatic detection.
+
+#### Example <a id="resources-configuration-ldap-example"></a>
+
+The name in brackets defines the resource name.
+
+```
+[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
+```
+
+### SSH <a id="resources-configuration-ssh"></a>
+
+A SSH resource contains the information about the user and the private key location, which can be used for the key-based
+ssh authentication.
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+type                     | **Required.** Specifies the resource type. Must be set to `ssh`.
+user                     | **Required.** The username to use when connecting to the server.
+private\_key             | **Required.** The path to the private key of the user.
+
+#### Example <a id="resources-configuration-ssh-example"></a>
+
+The name in brackets defines the resource name.
+
+```
+[ssh]
+type        = "ssh"
+user        = "ssh-user"
+private_key = "/etc/icingaweb2/ssh/ssh-user"
+```