tyler.durden/icingaweb2
1
0
Fork 0
mirror of https://github.com/Icinga/icingaweb2.git synced 2025-04-08 17:15:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

Fix typos and formatting in documentation

Browse Source 
refs #9377
This commit is contained in:
Matthias Jentsch 2015-06-15 11:09:41 +02:00
parent aac5d49eed
commit ea85254cc5
2 changed files with 74 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
doc/security.md
View File

@ -2,24 +2,28 @@
Access control is a vital part of configuring Icinga Web 2 in a secure way. Access control is a vital part of configuring Icinga Web 2 in a secure way.
It is important that not every user that has access to Icinga Web 2 is able It is important that not every user that has access to Icinga Web 2 is able
to do any action or see any host and service. For example, it is useful to allow to do any action or to see any host and service. For example, it is useful to allow
only a small group of administrators to change the Icinga Web 2 configuration, to prevent misconfiguration or security breaches. Another important use case is the creation groups of only a small group of administrators to change the Icinga Web 2 configuration,
users that can only see the fraction of hosts and services of the monitoring to prevent misconfiguration or security breaches. Another important use case is
environment they are in charge of. creating groups of users which can only see the fraction of the monitoring
environment they are in charge of.
This chapter will describe how to do the security configuration of Icinga Web 2 This chapter will describe how to do the security configuration of Icinga Web 2
and how apply permissions and restrictions to users or groups of users. and how to apply permissions and restrictions to users or groups of users.
## Basics ## Basics
Icinga Web 2 access control is done by defining **roles** that relate permissions or restrictions to **users** and **group**. Icinga Web 2 access control is done by defining **roles** that associate permissions
There are two general kinds of things to which access can be managed: actions and objects. and restrictions with **users** and **groups**. There are two general kinds of
things to which access can be managed: actions and objects.
### Actions ### Actions
Actions are all the things an Icinga Web 2 user can do, like changing a certain configuration, 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 <a href="http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc#!/icinga2/latest/doc/module/icinga2/chapter/getting-started#setting-up-external-command-pipe">Command Pipe</a> in the monitoring module. All actions must be be **allowed explicitly** using permissions. changing permissions or sending a command to the Icinga instance through the
<a href="http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc#!/icinga2/latest/doc/module/icinga2/chapter/getting-started#setting-up-external-command-pipe">Command Pipe</a>
in the monitoring module. All actions must be be **allowed explicitly** using permissions.
A permission is a simple list of identifiers of actions a user is A permission is a simple list of identifiers of actions a user is
allowed to do. Permissions are described in greater detail in the allowed to do. Permissions are described in greater detail in the
@ -39,7 +43,8 @@ in greater detail in the section [Restrictions](#restrictions).
Anyone who can **login** to Icinga Web 2 is considered a user and can be referenced to by the Anyone who can **login** to Icinga Web 2 is considered a user and can be referenced to by the
**user name** used during login. **user name** used during login.
For example, there might be user called **jdoe** authenticated For example, there might be user called **jdoe** authenticated
using Active Directory, and a user **icingaadmin** that is authenticated using a MySQL-Database as backend. Both can be referenced by using their the user names **icingaadmin** or **jdoe**, when referring to those users in the configuration. using Active Directory, and a user **icingaadmin** that is authenticated using a MySQL-Database as backend.
In the configuration, both can be referenced to by using their user names **icingaadmin** or **jdoe**.
Icinga Web 2 users and groups are not configured by a configuration file, but provided by Icinga Web 2 users and groups are not configured by a configuration file, but provided by
an **authentication backend**. For extended information on setting up authentication backends and managing users, please read the chapter [Authentication](authentication.md#authentication). an **authentication backend**. For extended information on setting up authentication backends and managing users, please read the chapter [Authentication](authentication.md#authentication).
@ -60,7 +65,7 @@ can be found at **Configuration > Authentication > Users **.
### Groups ### Groups
If there is a big amount of users to manage, it would be tedious to specify each user If there is a big amount of users to manage, it would be tedious to specify each user
separately when referring to a bigger group of users often. Because of that, it is possible to group users together into groups. separately when regularly referring to the same group of users. Because of that, it is possible to group users.
A user can be member of multiple groups and will inherit all permissions and restrictions. A user can be member of multiple groups and will inherit all permissions and restrictions.
Like users, groups are identified solely by their **name** that is provided by Like users, groups are identified solely by their **name** that is provided by
@ -71,7 +76,7 @@ Like users, groups are identified solely by their **name** that is provided by
#### Managing Groups #### Managing Groups
When using a [Database as an authentication backend](#authentication.md#authentication-configuration-db-authentication), When using a [Database as an authentication backend](#authentication.md#authentication-configuration-db-authentication),
it is possible manage groups and group memberships directly in the frontend. This configuration it is possible to manage groups and group memberships directly in the frontend. This configuration
can be found at **Configuration > Authentication > Groups **. can be found at **Configuration > Authentication > Groups **.
## Roles ## Roles
@ -82,7 +87,8 @@ users have access to all configuration options, or another role **support**
could define that a list of users or groups is restricted to see only hosts and services could define that a list of users or groups is restricted to see only hosts and services
that match a specific query. that match a specific query.
The actual permission of a certain user will be determined by merging the permissions and restrictions of the user itself and all the groups the user is part of. Permissions can The actual permission of a certain user will be determined by merging the permissions
and restrictions of the user itself and all the groups the user is member of. Permissions can
be simply added up, while restrictions follow a slighty more complex pattern, that is described be simply added up, while restrictions follow a slighty more complex pattern, that is described
in the section [Stacking Filters](#stacking-filters). in the section [Stacking Filters](#stacking-filters).
@ -98,7 +104,7 @@ configuration file:
#### Introducing Example #### Introducing Example
To get you a quick start, here is an example of how a role definition could look like: To get you a quick start, here is an example of what a role definition could look like:
[winadmin] [winadmin]
@ -108,24 +114,24 @@ To get you a quick start, here is an example of how a role definition could look
monitoring/filter/objects = "host=*win*" monitoring/filter/objects = "host=*win*"
This example creates a role called **winadmin**, that grants all permissions in **config/application/** and ** monitoring/commands/schedule-check ** and additionally only This example creates a role called **winadmin**, that grants all permissions in `config/application/*` and `monitoring/commands/schedule-check` and additionally only
allows the hosts and services that match the filter ** host=\*win* ** to be displayed. The users allows the hosts and services that match the filter `host=*win*` to be displayed. The users
**jdoe** and **janedoe** and all members of the group **admin** will be affected **jdoe** and **janedoe** and all members of the group **admin** will be affected
by this role. by this role.
#### Syntax #### <a id="syntax"></a> Syntax
Each role is defined as a section, with the name of the role as section name. The following Each role is defined as a section, with the name of the role as section name. The following
attributes can be defined for each role in a default Icinga Web 2 installation: attributes can be defined for each role in a default Icinga Web 2 installation:
| Key | Value | Directive | Description
|---------------------------|---------------------------------------------------------------------------------| ---------------------------|-----------------------------------------------------------------------------
| users | A comma-separated list of user **user names** that are affected by this role | 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 | 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 | 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 | monitoring/filter/objects | A **filter expression** that restricts the access to services and hosts
@ -137,87 +143,75 @@ all actions are **prohibited** and must be allowed explicitly by a role for any
Each action in Icinga Web 2 is denoted by a **namespaced key**, which is used to order and Each action in Icinga Web 2 is denoted by a **namespaced key**, which is used to order and
group those actions. All actions that affect the configuration of Icinga Web 2, are in a group those actions. All actions that affect the configuration of Icinga Web 2, are in a
namespace called **config**, while all configurations that affect authentication namespace called **config**, while all configurations that affect authentication
are in the namespace **config/authentication** are in the namespace `config/authentication`
**Wildcards** can be used to grant permission for all actions in a certain namespace. **Wildcards** can be used to grant permission for all actions in a certain namespace.
The permission **config/ ** would grant permission to all configuration actions, The permission `config/*` would grant permission to all configuration actions,
while just specifying a wildcard * would give permission for all actions. while just specifying a wildcard `*` would give permission for all actions.
When multiple roles assign permissions to the same user (either directly or indirectly When multiple roles assign permissions to the same user (either directly or indirectly
through a group) all permissions can simply be added together to get the users actual permission set. through a group) all permissions can simply be added together to get the users actual permission set.
#### Global permissions #### Global permissions
| Name | Permits | Name | Permits
|-------------------------------------|-----------------------------------------------------------------| -------------------------------------|-----------------------------------------------------------------
| * | Allow everything, including module-specific permissions | * | Allow everything, including module-specific permissions
| config/* | Allow all configuration actions | config/* | Allow all configuration actions
| config/application/* | Allow configuring IcingaWeb2 | config/application/* | Allow configuring IcingaWeb2
| config/application/general | Allow general settings, like logging or preferences | config/application/general | Allow general settings, like logging or preferences
| config/application/resources | Allow changing resources for retrieving data | config/application/resources | Allow changing resources for retrieving data
| config/application/userbackend | Allow changing backends for retrieving available users | config/application/userbackend | Allow changing backends for retrieving available users
| config/application/usergroupbackend | Allow changing backends for retrieving available groups | config/application/usergroupbackend | Allow changing backends for retrieving available groups
| config/authentication/* | Allow configuring IcingaWeb2 authentication mechanisms | config/authentication/* | Allow configuring IcingaWeb2 authentication mechanisms
| config/authentication/users/* | Allow all user actions | config/authentication/users/* | Allow all user actions
| config/authentication/users/show | Allow displaying avilable users | config/authentication/users/show | Allow displaying avilable users
| config/authentication/users/add | Allow adding a new user to the backend | config/authentication/users/add | Allow adding a new user to the backend
| config/authentication/users/edit | Allow editing an existing user in the backend | config/authentication/users/edit | Allow editing an existing user in the backend
| config/authentication/users/remove | Allow removing an existing user from the backend | config/authentication/users/remove | Allow removing an existing user from the backend
| config/authentication/groups/* | Allow all group actions | config/authentication/groups/* | Allow all group actions
| config/authentication/groups/show | Allow displaying all available groups | config/authentication/groups/show | Allow displaying all available groups
| config/authentication/groups/add | Allow adding a new group to the backend | config/authentication/groups/add | Allow adding a new group to the backend
| config/authentication/groups/edit | Allow editing existing groups in a backend | config/authentication/groups/edit | Allow editing existing groups in a backend
| config/authentication/groups/remove | Allow removing existing groups from the backend | config/authentication/groups/remove | Allow removing existing groups from the backend
| config/authentication/roles/* | Allow all role actions | config/authentication/roles/* | Allow all role actions
| config/authentication/roles/add | Allow adding a new role | config/authentication/roles/add | Allow adding a new role
| config/authentication/roles/show | Allow displaying available roles | config/authentication/roles/show | Allow displaying available roles
| config/authentication/roles/edit | Allow changing an existing role | config/authentication/roles/edit | Allow changing an existing role
| config/authentication/roles/remove | Allow removing an existing row | config/authentication/roles/remove | Allow removing an existing row
| config/modules | Allow enabling or disable modules and module changing settings | config/modules | Allow enabling or disabling modules
#### Monitoring module permissions #### Monitoring module permissions
The built-in monitoring module defines an additional set of permissions, that The built-in monitoring module defines an additional set of permissions, that
are described in detail in [monitoring module documentation](/icingaweb2/doc/module/doc/chapter/monitoring-security#monitoring-security). is described in detail in [monitoring module documentation](/icingaweb2/doc/module/doc/chapter/monitoring-security#monitoring-security).
## <a id="restrictions"></a> Restrictions ## <a id="restrictions"></a> Restrictions
Restrictions can be used to define what a user or group can see by specifying Restrictions can be used to define what a user or group can see by specifying
a filter expression. By default, when no restrictions are defined, a user will be able a filter expression that applies to a defined set of data. By default, when no
to see every object available. When a restriction is specified for a certain object type restrictions are defined, a user will be able to see every information that is available.
the user will only be able to see objects matched by those filters.
A restrictions is always specified for a certain **filter directive**, that defines what
### Filterable Objects data the filter is applied to. The **filter directive** is a simple identifier, that was
defined in an Icinga Web 2 module. The only filter directive that is available
Each filter expression consists of two parts: The **key** that defines **which** objects in a default installation, is the `monitoring/filter/objects` directive, defined by the monitoring module,
to filter and the filter, that defines **what** to filter. that can be used to apply filter to hosts and services. This directive was previously
mentioned in the section [Syntax](#syntax).
In a default Icinga Web 2 installations, the only objects that are filterable
are the objects provided by the monitoring module. The monitoring module provides
**hosts** and **services** as filterable objects:
| Keys | Restricsts |
|----------------------------|-----------------------------------------------|
| monitoring/filter/objects | Applies host and service filters to all hosts |
#### Filter Columns
Filters operate on object attributes. A complete list of all available filter columns on hosts and services can be found in
the [monitoring module documentation](/icingaweb2/doc/module/doc/chapter/monitoring-security#monitoring-security-restrictions).
### Filter Expressions ### 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](/icingaweb2/doc/module/doc/chapter/monitoring-security#monitoring-security-restrictions).
Any filter expression that is allowed in the filtered view, is also an allowed filter expression. Any filter expression that is allowed in the filtered view, is also an allowed filter expression.
This means, that it is possible to define negations, wildcards, and even nested This means, that it is possible to define negations, wildcards, and even nested
filter expressions containing AND and OR-Clauses. filter expressions containing AND and OR-Clauses.
The filter expression will be **implicitly** added as an **AND-Clause** to each query on the filtered objects. The following shows the filter expression **host = \*win* ** being applied on ** monitoring/filter/objects **. The filter expression will be **implicitly** added as an **AND-Clause** to each query on
the filtered data. The following shows the filter expression `host=*win*` being applied on `monitoring/filter/objects`.
Regular filter query: Regular filter query:
@ -282,12 +276,4 @@ Notice that because of the behavior of two stacking filters, a user that is memb
monitoring/filter/objects = "(hostgroup_name=bsd-servers|hostgroup_name=linux-servers)" monitoring/filter/objects = "(hostgroup_name=bsd-servers|hostgroup_name=linux-servers)"
This role allows all members of the group unix-admins to see hosts and services This role allows all members of the group unix-admins to see hosts and services
that are part of the host-group linux-servers or the host-group bsd-servers. that are part of the host-group linux-servers or the host-group bsd-servers.
## Troubleshooting
Q: I cannot see the menu for changing roles in Icinga Web 2
A: Your user lacks the permission to change the authentication configuration,
add a new role in roles.ini that gives your current user
the permission to access **config/authentication/**

4
modules/doc/doc/security.md
View File

@ -7,9 +7,9 @@ restrictions and permissions in detail:
## Permissions ## Permissions
The Icinga Web 2 monitoring plugin can send commands to the current Icinga2 instance The Icinga Web 2 monitoring module can send commands to the current Icinga2 instance
through the command pipe. A user needs specific permissions to be able to send those through the command pipe. A user needs specific permissions to be able to send those
commands when using the monitoring plugin. commands when using the monitoring module.
| Name | Permits | | Name | Permits |