tyler.durden
/
icingaweb2
mirror of https://github.com/Icinga/icingaweb2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix some syntax bugs in markdown files 

Signed-off-by: Eric Lippmann <eric.lippmann@netways.de>
This commit is contained in:
Heike Jurzik 2016-07-08 16:39:24 +02:00 committed by Eric Lippmann
parent 8e40d3cc25
commit cbf55ffbf1
5 changed files with 84 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/02-Installation.md
View File

@ -37,7 +37,7 @@ Below is a list of official package repositories for installing Icinga Web 2 for
Distribution | Repository
------------------------|---------------------------
Debian | [debmon](http://debmon.org/packages/debmon-wheezy/icingaweb2), [Icinga Repository](http://packages.icinga.org/debian/)
Debian | [debmon](http://debmon.org/packages/debmon-jessie/icingaweb2), [Icinga Repository](http://packages.icinga.org/debian/)
Ubuntu | [Icinga Repository](http://packages.icinga.org/ubuntu/)
RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/)
openSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/)
@ -57,7 +57,7 @@ Below is a list with examples for various distributions.
**Debian (debmon)**:
```
wget -O - http://debmon.org/debmon/repo.key 2>/dev/null | apt-key add -
echo 'deb http://debmon.org/debmon debmon-wheezy main' >/etc/apt/sources.list.d/debmon.list
echo 'deb http://debmon.org/debmon debmon-jessie main' >/etc/apt/sources.list.d/debmon.list
apt-get update
```
@ -111,12 +111,6 @@ The packages for RHEL/CentOS depend on other packages which are distributed as p
> Please note that installing Icinga Web 2 on **RHEL/CentOS 5** is not supported due to EOL versions of PHP and
> PostgreSQL.
#### <a id="package-repositories-wheezy-notes"></a> Debian wheezy Notes
The packages for Debian wheezy depend on other packages which are distributed as part of the
[wheezy-backports](http://backports.debian.org/) repository. Please make sure to enable this repository by following
[these instructions](http://backports.debian.org/Instructions/).
### <a id="installing-from-package-example"></a> Installing Icinga Web 2
You can install Icinga Web 2 by using your distribution's package manager to install the `icingaweb2` package.
@ -126,7 +120,6 @@ Below is a list with examples for various distributions. The additional package
```
apt-get install icingaweb2
```
For Debian wheezy please read the [package repositories notes](#package-repositories-wheezy-notes).
**RHEL, CentOS and Fedora**:
```
@ -449,24 +442,24 @@ path = "/var/run/icinga2/cmd/icinga2.cmd"
Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/icingaweb2`.
# <a id="upgrading"></a> Upgrading Icinga Web 2
## <a id="upgrading"></a> Upgrading Icinga Web 2
## <a id="upgrading-to-2.3.x"></a> Upgrading to Icinga Web 2 2.3.x
### <a id="upgrading-to-2.3.x"></a> Upgrading to Icinga Web 2 2.3.x
* Icinga Web 2 version 2.3.x does not introduce any backward incompatible change.
## <a id="upgrading-to-2.2.0"></a> Upgrading to Icinga Web 2 2.2.0
### <a id="upgrading-to-2.2.0"></a> Upgrading to Icinga Web 2 2.2.0
* The menu entry `Authorization` beneath `Config` has been renamed to `Authentication`. The role, user backend and user
group backend configuration which was previously found beneath `Authentication` has been moved to `Application`.
## <a id="upgrading-to-2.1.x"></a> Upgrading to Icinga Web 2 2.1.x
### <a id="upgrading-to-2.1.x"></a> Upgrading to Icinga Web 2 2.1.x
* Since Icinga Web 2 version 2.1.3 LDAP user group backends respect the configuration option `group_filter`.
Users who changed the configuration manually and used the option `filter` instead
have to change it back to `group_filter`.
## <a id="upgrading-to-2.0.0"></a> Upgrading to Icinga Web 2 2.0.0
### <a id="upgrading-to-2.0.0"></a> Upgrading to Icinga Web 2 2.0.0
* Icinga Web 2 installations from package on RHEL/CentOS 7 now depend on `php-ZendFramework` which is available through
the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library
@ -488,7 +481,7 @@ Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/ici
**&lt;config-dir&gt;/preferences/&lt;username&gt;/config.ini**.
The content of the file remains unchanged.
## <a id="upgrading-to-rc1"></a> Upgrading to Icinga Web 2 Release Candidate 1
### <a id="upgrading-to-rc1"></a> Upgrading to Icinga Web 2 Release Candidate 1
The first release candidate of Icinga Web 2 introduces the following non-backward compatible changes:
@ -507,12 +500,12 @@ The first release candidate of Icinga Web 2 introduces the following non-backwar
predefined subset of filter columns. Please see the module's security
related documentation for more details.
## <a id="upgrading-to-beta3"></a> Upgrading to Icinga Web 2 Beta 3
### <a id="upgrading-to-beta3"></a> Upgrading to Icinga Web 2 Beta 3
Because Icinga Web 2 Beta 3 does not introduce any backward incompatible change you don't have to change your
configuration files after upgrading to Icinga Web 2 Beta 3.
## <a id="upgrading-to-beta2"></a> Upgrading to Icinga Web 2 Beta 2
### <a id="upgrading-to-beta2"></a> Upgrading to Icinga Web 2 Beta 2
Icinga Web 2 Beta 2 introduces access control based on roles for secured actions. If you've already set up Icinga Web 2,
you are required to create the file **roles.ini** beneath Icinga Web 2's configuration directory with the following
@ -526,5 +519,6 @@ permissions = "*"
After please log out from Icinga Web 2 and log in again for having all permissions granted.
If you delegated authentication to your web server using the `autologin` backend, you have to switch to the `external`
authentication backend to be able to log in again. The new name better reflects what’s going on. A similar change
authentication backend to be able to log in again. The new name better reflects
what's going on. A similar change
affects environments that opted for not storing preferences, your new backend is `none`.

18
doc/03-Configuration.md
View File

@ -1,15 +1,15 @@
# <a id="configuration"></a> Configuration
## Overview
## <a id="configuration-overview"></a> Overview
Apart from its web configuration capabilities, the local configuration is
stored in `/etc/icingaweb2` by default (depending on your config setup).
File/Directory | Description
---------------------------------------------------------
config.ini | General configuration (logging, preferences)
[resources.ini](04-Ressources.md) | Global resources (Icinga Web 2 database for preferences and authentication, Icinga IDO database)
roles.ini | User specific roles (e.g. `administrators`) and permissions
[authentication.ini](05-Authentication.md) | Authentication backends (e.g. database)
enabledModules | Contains symlinks to enabled modules
modules | Directory for module specific configuration
| **File/Directory** | **Description/Purpose** |
| :------------- | :------------------- |
| **config.ini** | general configuration (logging, preferences, etc.)
| [**resources.ini**](04-Ressources.md) | global resources (Icinga Web 2 database for preferences and authentication, Icinga IDO database)
| **roles.ini** | user specific roles (e.g. `administrators`) and permissions
| [**authentication.ini**](05-Authentication.md) | authentication backends (e.g. database)
| **enabledModules** | contains symlinks to enabled modules
| **modules** | directory for module specific configuration

50
doc/04-Resources.md
View File

@ -1,12 +1,12 @@
# <a id="resources"></a> Resources
The INI configuration file **config/resources.ini** contains information about data sources that can be referenced in other
The 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.
## <a id="resources-configuration"></a> Configuration
Each section in **config/resources.ini** represents a data source with the section name being the identifier used to
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*, *ssh* and *livestatus* which will described in detail in the following
paragraphs.
@ -17,7 +17,7 @@ A Database resource defines a connection to a SQL databases which can contain us
to handle authentication and authorization, monitoring data or user preferences.
Directive | Description
----------------|------------
:---------------|:------------
**type** | `db`
**db** | Database management system. In most cases `mysql` or `pgsql`.
**host** | 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.
@ -26,7 +26,7 @@ Directive | Description
**password** | The password to use when connecting to the server.
**dbname** | The database to use.
**Example:**
#### <a id="resources-configuration-database-example"></a> Example
````
[icingaweb-mysql-tcp]
@ -54,32 +54,34 @@ port = 5432
username = icingaweb
password = icingaweb
dbname = icingaweb
```
````
### <a id="resources-configuration-ldap"></a> LDAP
A LDAP resource represents a tree in a LDAP directory. LDAP is usually used for authentication and authorization.
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"
**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.
**encryption** | Type of encryption to use: `none` (default), `starttls`, `ldaps`.
**Example:**
#### <a id="resources-configuration-ldap-example"></a> Example
````
[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`
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
````
### <a id="resources-configuration-ssh"></a> SSH
@ -88,18 +90,20 @@ A SSH resource contains the information about the user and the private key locat
ssh authentication.
Directive | Description
--------------------|------------
:--------------------|:------------
**type** | `ssh`
**user** | The username to use when connecting to the server.
**private_key** | The path to the private key of the user.
**Example:**
#### <a id="resources-configuration-ssh-example"></a> Example
````
[ssh]
type = "ssh"
user = "ssh-user"
private_key = "/etc/icingaweb2/ssh/ssh-user"
type = "ssh"
user = "ssh-user"
private_key = "/etc/icingaweb2/ssh/ssh-user"
````
### <a id="resources-configuration-livestatus"></a> Livestatus
@ -107,14 +111,16 @@ private_key = "/etc/icingaweb2/ssh/ssh-user"
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>`.
**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>`)
**Example:**
#### <a id="resources-configuration-livestatus-example"></a>Example
````
[livestatus]
type = livestatus
socket = /var/run/icinga2/cmd/livestatus
````

52
doc/06-Security.md
View File

@ -11,14 +11,14 @@ environment they are in charge of.
This chapter will describe how to do the security configuration of Icinga Web 2
and how to apply permissions and restrictions to users or groups of users.
## Basics
## <a id="security-basics"></a> Basics
Icinga Web 2 access control is done by defining **roles** that associate permissions
and restrictions with **users** and **groups**. There are two general kinds of
things to which access can be managed: actions and objects.
### Actions
### <a id="security-basics-actions"></a>Actions
Actions are all the things an Icinga Web 2 user can do, like changing a certain configuration,
changing permissions or sending a command to the Icinga instance through the Icinga command pipe.
@ -28,7 +28,7 @@ A permission is a simple list of identifiers of actions a user is
allowed to do. Permissions are described in greater detail in the
section [Permissions](#permissions).
### Objects
### <a id="security-basics-objects"></a> Objects
There are all kinds of different objects in Icinga Web 2: Hosts, Services, Notifications, Downtimes and Events.
@ -37,7 +37,7 @@ By default, a user can **see everything**, but it is possible to **explicitly re
Restrictions are complex filter queries that describe what objects should be displayed to a user. Restrictions are described
in greater detail in the section [Restrictions](#restrictions).
### Users
### <a id="security-basics-users"></a>Users
Anyone who can **login** to Icinga Web 2 is considered a user and can be referenced to by the
**user name** used during login.
@ -55,13 +55,13 @@ an **authentication backend**. For extended information on setting up authentica
backend to fetch users and groups from, which must be configured separately.
</div>
#### Managing Users
#### <a id="security-basics-users-managing"></a>Managing Users
When using a [Database
as authentication backend](05-Authentication.md#authentication-configuration-db-authentication), it is possible to create, add and delete users directly in the frontend. This configuration
can be found at **Configuration > Authentication > Users **.
### Groups
### <a id="security-basics-groups"></a>Groups
If there is a big amount of users to manage, it would be tedious to specify each user
separately when regularly referring to the same group of users. Because of that, it is possible to group users.
@ -72,13 +72,13 @@ Like users, groups are identified solely by their **name** that is provided by
please read the chapter [Authentication](05-Authentication.md#authentication).
#### Managing Groups
#### <a id="security-basics-groups-managing"></a>Managing Groups
When using a [Database as an authentication backend](05-Authentication.md#authentication-configuration-db-authentication),
it is possible to manage groups and group memberships directly in the frontend. This configuration
can be found at **Configuration > Authentication > Groups **.
## Roles
## <a id="security-roles"></a>Roles
A role defines a set of **permissions** and **restrictions** and assigns
those to **users** and **groups**. For example, a role **admins** could define that certain
@ -91,7 +91,7 @@ and restrictions of the user itself and all the groups the user is member of. Pe
be simply added up, while restrictions follow a slighty more complex pattern, that is described
in the section [Stacking Filters](#stacking-filters).
### Configuration
### <a id="security-roles-configuration"></a>Configuration
Roles can be changed either through the icingaweb2 interface, by navigation
to the page **Configuration > Authentication > Roles**, or through editing the
@ -101,7 +101,7 @@ configuration file:
/etc/icingaweb2/roles.ini
#### Introducing Example
#### <a id="security-roles-configuration-example"></a>Introducing Example
To get you a quick start, here is an example of what a role definition could look like:
@ -126,11 +126,11 @@ attributes can be defined for each role in a default Icinga Web 2 installation:
Directive | Description
---------------------------|-----------------------------------------------------------------------------
users | A comma-separated list of user **user names** that are affected by this role
groups | A comma-separated list of **group names** that are affected by this role
permissions | A comma-separated list of **permissions** granted by this role
monitoring/filter/objects | A **filter expression** that restricts the access to services and hosts
:--------------------------|:----------------
**users** | a comma-separated list of user **user names** that are affected by this role
**groups** | a comma-separated list of **group names** that are affected by this role
**permissions** | a comma-separated list of **permissions** granted by this role
**monitoring/filter/objects** | a **filter expression** that restricts the access to services and hosts
@ -154,17 +154,17 @@ a module permission in the format `module/<moduleName>` for each installed modul
When multiple roles assign permissions to the same user (either directly or indirectly
through a group) all permissions are added together to get the users actual permission set.
### Global Permissions
### <a id="permissions-global"></a> Global Permissions
Name | Permits
--------------------------|--------------------------------------------------------
* | Allow everything, including module-specific permissions
config/* | Allow all configuration actions
config/modules | Allow enabling or disabling modules
module/&lt;moduleName&gt; | Allow access to module &lt;moduleName&gt;
Name | Permits
:-----------|:------------
**\*** | allow everything, including module-specific permissions
**config/\*** | allow all configuration actions
**config/modules** | allow enabling or disabling modules
**module/&lt;moduleName&gt;** | allow access to module &lt;moduleName&gt;
### Monitoring Module Permissions
### <a id="permissions-module"></a> Monitoring Module Permissions
The built-in monitoring module defines an additional set of permissions, that
is described in detail in the monitoring module documentation.
@ -183,7 +183,7 @@ in a default installation, is the `monitoring/filter/objects` directive, defined
that can be used to apply filter to hosts and services. This directive was previously
mentioned in the section [Syntax](#syntax).
### Filter Expressions
### <a id="restrictions-filter"></a>Filter Expressions
Filters operate on columns. A complete list of all available filter columns on hosts and services can be found in
the monitoring module documentation.
@ -235,7 +235,7 @@ expression:
As a result, a user is be able to see hosts that are matched by **ANY** of
the filter expressions. The following examples will show the usefulness of this behavior:
#### Example 1: Negation
#### <a id="restrictions-filter-example1"></a>Example 1: Negation
[winadmin]
groups = "windows-admins"
@ -251,7 +251,7 @@ Will only match hosts and services whose host name does **not** contain **win**
Notice that because of the behavior of two stacking filters, a user that is member of **windows-admins** and **web-admins**, will now be able to see both, Windows and non-Windows hosts and services.
#### Example 2: Hostgroups
#### <a id="restrictions-filter-example2"></a>Example 2: Hostgroups
[unix-server]
groups = "unix-admins"

14
doc/99-Vagrant.md
View File

@ -1,6 +1,10 @@
# Vagrant
# <a id="vagrant"></a> Vagrant
## Requirements
This chapter shows how to set up and use our [Icinga Vagrant
boxes](https://github.com/icinga/icinga-vagrant) that we've created for
development, tests and demo cases.
## <a id="vagrant-requirements"></a>Requirements
* Vagrant &gt;= version 1.5
* VirtualBox or Parallels Desktop
@ -13,7 +17,7 @@ Parallels requires the additional provider plugin
$ vagrant plugin install vagrant-parallels
## General
## <a id="vagrant-general"></a>General
The Icinga Web 2 project ships with a Vagrant virtual machine that integrates
the source code with various services and example data in a controlled
@ -31,7 +35,7 @@ vagrant up
After you should be able to browse [localhost:8080/icingaweb2](http://localhost:8080/icingaweb2).
## Log into Icinga Web 2
## <a id="vagrant-login"></a>Log into Icinga Web 2
Both LDAP and a MySQL are configured as authentication backend. Please use one of the following login credentials:
@ -47,7 +51,7 @@ Both LDAP and a MySQL are configured as authentication backend. Please use one o
## Testing the Source Code
## <a id="vagrant-testing"></a>Testing the Source Code
All software required to run tests is installed in the virtual machine.
In order to run all tests you have to execute the following command: