1. Introduction
In this article we will present information on all aspects of user management and permissions in Checkmk. Before we go into the details, however, we’ll first need to explain a few terms.
In Checkmk a User is one with access to the User interface. They have one or more Roles. From these roles Permissions are derived.
Once a user is made responsible for specific hosts and services, they are identified as a Contact. A contact normally sees only their own hosts and services in the user interface, and receives notifications regarding possible problems.
There are also users who are not contacts. An example would be cmkadmin,
which is generated automatically when an instance is created.
This can in fact see all hosts and services, but only because its admin role
includes the See all hosts and services permission — not because it is a contact for all.
If a contact has only been created for the purpose of notifications (e.g., for forwarding notifications to a ticket system), it can be sensible to set it up so that a login is not possible from the interface.
A Contact is always a member of one or more Contact Groups.
The purpose of these groups is the allocation of contacts to hosts and services.
For example: the contact hhirsch could be in the linux contact group,
and this can in turn be allocated to all Linux hosts via rules.
A direct allocation of contacts to hosts or services is not possible, and in practice
would create difficulties (e.g., when ‘retiring’ a user).
To summarise:
Users can utilise the user interface.
Contacts are users who are responsible for specific hosts and services.
Contact Groups define what someone is responsible for.
Roles define a user’s Permissions.
2. User management with WATO
2.1. Overview
User management can be found in the Users WATO module 
.
In a newly-created instance this page will appear as below:
Here cmkadmin can be seen — the only user which is automatically
generated when a new instance is created. In Checkmk-Appliance this user can have
a different name because you can specify the name and password yourself.
This very first user has the following characteristics:
It has the Administrator (
admin) role and therefore has all permissions!It is a contact for nothing and receives no notifications.
It can however view everything (due to its
adminrole).The default password should be replaced by a new one as soon as possible!
Incidentally, on the User’s page title line you can always see who you are logged-in as — your logon-ID and (role):
The mask for creating a new user with 
, or for
editing an existing user with 
consists of five sections.
The first subsection menu is for the identity:
2.2. Identity
As always in Checkmk, the ID of a dataset — (here Username) — cannot be changed retrospectively. This will be used for the registration, and also as an internal key in all files and file structures.
The email address is optional and only required if the user is to be a contact who should receive notifications by email (SMTP configuration necessary). The Pager address field is analogous and is intended for notifications per SMS or similar systems. If you are coding your own notification scripts, the values in these fields can be accessed and used as required.
Via Authorized sites you can optionally restrict access to specific existing sites. This is useful especially in very large environments, such as a distributed monitoring with hundreds of sites: If a user only needs a portion of these sites for his hosts, the GUI will contact only the authorized sites to build views. This in turn greatly improves performance.
2.3. Security
The second subsection menu is for the login and permissions. The Automation secret for machine accounts option is intended for accounts that are controlled by scripts which access Checkmk per HTTP, and which are authenticated via the URL. Later we will show how this works see below.
At least one role must be selected. You can theoretically give multiple roles to a user — in which case the user will receive the authorisations from all of these roles. With the three predefined roles (see below) this would make little sense however.
If you lock a user with the disable the login to this account option,
it will appear with the 
symbol in the table.
It will not be able to login but will nonetheless remain in the system.
If it is a contact its notifications will not be affected and it will still receive emails, etc.
If the user was logged in at the time of the locking action, it will be automatically logged out.
2.4. Contact groups
As soon as a user is allocated to one or more contact groups it will become a contact. For a new instance the contact group Everything is automatically generated, which will always include all hosts and all services. A user in this group is automatically responsible for all hosts and services.
2.5. Notifications
In the Notifications box, you can use the Receive fallback notifications option to specify that this contact should receive alerts for events when no notification rule applies.
2.6. Personal settings
All settings in the last subsection menu can also be changed by the user themselves
using 
— (except when in the guest role).
Apart from the choice of language, the interface contains some rarely-required settings — as always
details for these can be found in the online help 
.
3. Contact groups
3.1. Creating and editing contact groups
Contact groups are the link between hosts and services on one side and contacts on the other.
Every contact group represents a responsibility for a specific area in your IT landscape.
For example, the SAP contact group could include all personnel who manage a SAP system,
and the group allocated to all hosts and services providing service in this area.
Contact groups are administered with the 
Contact Groups WATO module.
The following screenshot shows this module with four defined contact groups:
The creation of a new group is a simple matter. As always, the ID is fixed, and the alias is a display name that can be changed at any later time:
The new contact group is at first empty in two respects: it contains neither contacts nor hosts and services. The allocation of contact groups to contacts is achieved with the user profile, as we have already seen in user editing. The allocation of hosts and services is performed as follows:
3.2. Allocating hosts to a contact group
There are two methods for adding hosts to contact groups: via Folder and via Rules. Both methods can also be used in combination. In this case the host is allocated the sum of the respective contact groups.
Allocation via folders
The attributes of a folder are accessed using the 
button when in the folder.
Here you will find the Permissions option.
Activate this check box to access the contact group selection:
The actual purpose of this option is to set permissions for administering hosts in WATO — which will be covered in detail below. When assigning permissions for specific contact groups, at the same time you can enter these as contact groups for the hosts in monitoring. You can also decide whether these should be applicable to hosts in subfolders, and if the host’s services should also explicitly receive these groups. Services without an explicit allocation in fact inherit all of a host’s groups, including those allocated via rules.
Attention: The Inheritance of these Permissions-Attributes via the folder is overridden by this procedure. This allows you to allocate other contact groups to subfolders. The allocations are thus cumulative through all parent folders if in these the Add these groups as contacts in all subfolders option is active.
Incidentally, the contact group options may also be found in a simplified form directly in a host’s details. Hence there you can also allocate contact groups to individual hosts. As this can quickly become complex however, it should only be used in exceptional cases, and if really necessary it would probably be preferable to work with rules.
Allocation via rules
The second method — allocating contact groups via rules — is somewhat more involved, but is considerably more flexible however. This is also very useful if your folder structure has not been built following an organised plan, so there is therefore no clear way to simply allocate the folders to contact groups.
The rule set required for this — Assignment of hosts to contact groups can be accessed
quickly via the contact group’s WATO module and using the 
button.
In this rule set you will find a predefined rule which is generated when an
instance is created, and which assigns all of the hosts to the Everything contact group.
Please note that this rule set is defined so that all relevant rules will be evaluated, and not just the first one! It can in fact be useful to have a host belonging to multiple contact groups, and in such a cases each assignment will require its own rule.
3.3. Assigning services to contact groups
It is not always a matter of course to have a service in the same contact group as its host. Therefore, using the Assignment of services to contact groups rule set you can assign services to contact groups — independently of the host’s groups. The following rules apply:
If no contact group is assigned to a service, it will automatically receive the same contact groups as its host.
When at least one contact group is explicitly assigned to a service, the service will no longer inherit its host’s contact groups.
In a simple environment it is sufficient to just allocate contact groups to the hosts. Once more differentiation is required rules for the services can also be defined.
4. Visibility of hosts and services
4.1. Overview
The fact that a normal user — (the ‘user’ role) — only sees the objects for which
they are a contact becomes more important as monitoring environments get larger.
This not only simplifies the overview, but also precludes users from interfering where they have no business being.
As the administrator — (the ‘admin’ role) — you can of course see everything.
This is controlled by the See all host and services permission.
In your
personal settings
you will find the Only show hosts and services the user is a contact for check box.
With this you can optionally give up the ‘See all’ permission and thereafter see
only the hosts and services for which you are a contact.
This option is intended for dual roles — for someone who is simultaneously both
the administrator and a normal user of the monitoring.
The ‘guest’ role is predefined so that your users can also see everything.
An intervention or personal settings are deactivated here.
For normal users the visibility in the complete status overview is constructed so that in the system it appears as if those hosts and services for which one is not a contact simply do not exist.
Among others, the following elements influence the visibility:
All tabular host and service Views
The Tactical Overview
Dashboards including the ‘Globes’.
Reporting created by the user
4.2. Visibility of services
As we showed earlier it is possible that one can be a contact for a host, but not for all of its services. You will nonetheless be able to see all of the host’s services in the GUI.
This exception is predefined in this way because it is generally so useful. In practice, for example, this means that the colleague who is responsible for the host itself can also see such services (hardware, operating systems, etc.) that actually have nothing to do with the host. They will receive no notifications from these however!
If you don’t like this you can change it. The 
global
option for this is Monitoring Core ⇒ Authorization settings.
If here you change Hosts to Strict - Must be explicit contact of a service
users will only be able to see services if they are directly assigned as
contacts for the service.
All of this actually has nothing to do with a service inheriting its host’s contact groups in the case of it not having any groups of its own defined. You would then be a contact for the service — and receive its notifications.
4.3. Host and service groups
The second setting in this option concerns host and service groups. You can normally always see a group if you can see at least one of the group’s elements — the group will however appear to contain only those elements that are visible to you.
Switching to Strict - must be contact of all members hides all groups for which you are not a contact for at least one host or service in the group.
Please note that both of these settings for visibility have no influence on notifications.
5. Notifications
Contact assignments also have an influence on notifications. By default Checkmk notifies all contacts of an affected host or service when problems occur. This is handled by a notifications rule which is automatically created for a new instance. This is a very sensible procedure.
Nonetheless, you can customise the rule or supplement it with additional rules if desired, so that in an extreme case a notification can be triggered quite independently of contact groups. A common situation is when there are specific notifications that a user does not want to receive, or vice versa, a user does want to be informed of problems with certain hosts or services, even if they are not responsible for those services (and consequently is not a contact).
Details can be found in the Article on notifications.
6. Roles and permissions
6.1. Predefined roles
Checkmk always assigns permissions to users using rules — never directly. A role is nothing more than a list of permissions. It is important to understand that roles define the level of permissions and not an actual connection to any hosts or services. Contact groups exist for this purpose.
Checkmk is provided with the following three predefined roles — which are never deleted, but which may be customised as required:
| Role | Permissions | Function |
|---|---|---|
admin | All permissions — notably the authority to change permissions. | The Checkmk Administrator, responsible for managing the monitoring system itself. |
user | May only view its own hosts and services, may only make changes to shared folders in WATO for which it has been authorised, and in general is not permitted to do anything that affects other users. | The normal Checkmk monitoring user who reacts to notifications. |
guest | May see everything but change nothing. | Intended ‘just for looking’ — whereby all guests share a common account. Also useful for public status screens that hang on a wall. |
Roles are managed in the WATO 
Roles & Permissions module:
Incidentally — when a new Checkmk instance is created only a single user with the
admin role will be generated (cmkadmin).
The other two roles will not be used initially.
Should you require a guest user you will have to create it yourself.
6.2. Adapting existing rules
As usual, the editing mode for a rule is accessed via the symbol:
The functions of the numerous permissions, here in excerpts, can be found
in the online help.
What is special here — for every permission there are three possible selections: yes, no and default (yes), or respectively default(no). All values are initially set to default. For the permissions themselves, at first it makes no difference whether you set them to yes or default (yes). A new version of Checkmk can alter these default values however (this occurs very rarely). Explicitly made settings will not be affected by such a change.
Additionally, with this principle you can very quickly identify where a Checkmk varies from standard.
6.3. Defining your own roles
It might come as a surprise that there is no button for creating a new role.
There is a purpose behind this! New roles are derived from existing roles using
the 
Clone button. The new role is not simply a copy,
but retains a connection to the source role (Based on role):
This connection has an important function, one with which all of the cloned role’s permissions that have not been explicitly set — i.e. those that remain set to default — will be inherited from the original role. Subsequent changes to the source role will then be passed on. This is very practical when one considers how many permissions are available. With simple copies it would be easy to lose the overview — which is what actually makes your self-defined roles so special.
This derivation solves another problem: since we are actively developing Checkmk new
permissions are added from time to time. At these times we decide in which of the three
roles — admin, user and guest — the new permission should be included.
Because your own roles have been derived from one of these three, the new permission will be
automatically preset to a sensible value. It would be simply very impractical, for example,
if you defined your own user role in which new permissions were always missing.
You would then be in the situation where for every new feature your role would have to
be adapted in order for your users to be able to use it.
6.4. Comparing roles with the matrix view
The 
button helps if you wish to compare the permissions in the individual roles.
This generates the display below, in which not only the individual roles’ permissions can be
compared, but in which you can also see the positions in which explicit permissions have been set
(
Symbol), or respectively, removed (
Symbol).
7. Personal settings
A small number of the user settings can be self-managed by every user.
This is found at the foot of the side bar at the button.
This opens the below menu:
The most important function here is changing the password.
The user must enter both the existing and the new password. As always, a description of the other
setting options can be found in the online help.
In a distributed monitoring, following each change the new settings will be immediately passed on to all slave monitoring instances. Only in this way can it be ensured that the new password will immediately function everywhere — meaning it will not be dependent on the next activation of changes. This however only works for sites that are accessible to the network at this point of time. All other sites will receive the updates with their next successful Activate changes.
8. Automation user (for Webservices)
When connecting Checkmk to other systems it is often desired that specific tasks normally performed using the GUI be automated. Some examples of these are:
Setting and removing downtimes with scripts
Managing hosts in WATO with the Web-API
Retrieving data from views as CSV or JSON files for further processing
Retrieving the current status of BI-Aggregates, in order to create services from them
In this situation an external software must be able to open specific Checkmk-Overview URLs automatically. And naturally, here the question is how the user login is to be performed. The usual method using the login mask is cumbersome, requiring the opening of a number of URLs in sequence and the saving of a cookie.
To simplify this procedure Checkmk offers the concept of the Automation user. These users are intended exclusively for remote control and don’t permit normal GUI logins. Authorisation is achieved using specific variables in the URL.
An automation user is created like a normal user, but instead of a password it
receives an Automation secret — which can be generated automatically with the
randomising die:
Just like a normal user, an automation user has a role and can also be a contact. With these you can thus restrict its permissions and visibility of hosts and services as required.
When opening websites automatically, you enter the following additional variables in the URL:
_username | the automation user’s ID |
_secret | the user’s Automation secret |
Here is an example for opening a view in the JSON-Format with the automation
user automation and the secret as in the above image:
root@linux# curl 'http://moni01.mycompany.net/mysite/check_mk/view.py?_username=automation&_secret=GLV@GYCAKINOLICMAFVP&view_name=svcproblems&output_format=json'
[
"service_state",
"host",
"service_description",
"service_icons",
"svc_plugin_output",
"svc_state_age",
"svc_check_age",
"perfometer"
],
[
"CRIT",
"stable",
"Filesystem /",
"menu pnp",
"CRIT - 96.0% used (207.27 of 215.81 GB), (warn/crit at 80.00/90.00%), trend: +217.07 MB / 24 hours",
"119 min",
"30 sec",
"96%"
],
...If the script that opens the URL is running directly in the monitoring instance you can
read the user’s secret directly from the file system. This is not a security flaw,
rather it is specifically intended to be so. With this the automation script can be written without
containing the secret and also without requiring configurations data. To this end, simply select the file:
~/var/check_mk/web/myuser/automation.secret:
OMD[mysite]:~$ cat var/check_mk/web/automation/automation.secret
GLV@GYCAKINOLICMAFVPIn the shell you can easily save this file’s content in a variable:
OMD[mysite]:~$ SECRET=$(cat var/check_mk/web/automation/automation.secret)
OMD[mysite]:~$ echo "$SECRET"
GLV@GYCAKINOLICMAFVPThis also, for example, makes use of the downtime script, which can be
found in the Checkmk Treasures, and with which script-controlled planned downtimes
for hosts and services can be specified and deleted.
If the automation user is called automation as shown in our example,
only a single argument needs to be entered — the hostname for which the downtime is to be defined:
OMD[mysite]:~$ ~/share/doc/check_mk/treasures/downtime myhost123You can learn about further options for this script in this online help:
OMD[mysite]:~$ ~/share/doc/check_mk/treasures/downtime --help9. Automatic login via the URL
As we have seen with automation users using script contro you can open URLs arbitrarily without logging in. In situations requiring a real browser this does not function, as the login data for any contained links (e.g., images and iFrames) will not be forwarded.
The best example for this is the desire to hang a screen which continuously displays a particular Checkmk dashboard on a wall. The screen should be controlled by a computer that on starting automatically opens the browser, logs itself in to Checkmk, and calls up the dashboard.
In order to realise this, the best method is to first create a special user.
The guest role is well-suited here because it has all read permissions,
but does not allow changes or interventions
The URL for an automatic login is constructed as follows:
Determine the the actual URL to be displayed (e.g., that of the dashboard) with your browser — ideally so that only the right-most frame is displayed, without the side bar.
Add this URL, leaving out out everything before
/mysite/…Append both variables into the URL -
_usernameand_password- in the following format:&_username=myuser&_password=mysecretAdd a
&_login=1
Here is an example of such a URL:
Please note:
Substitute your own values for the
mycmkserver,mysite,myuserandmypasswordfields in the example.If the special characters
&or%are present in these values, or in the value for the_origtargetfield, they must be substituted as follows:&by%26and%by%25.
Test this by logging out of Checkmk in your browser, and then pasting the contructed URL in the browser’s address field. You should then arrive directly in the target site — without a login screen. You will nonetheless be logged in, and can directly access the links contained on the page.
You can also try the finished URL with curl on the command line.
If you have done everything correctly you will receive the result “302 Found” and a (“The document
has moved…”) redirection.
OMD[mysite]:~$ curl 'http://localhost/mysite/check_mk/login.py?_origtarget=/mysite/check_mk/dashboard.py?name=mydashboard&_username=myuser&_password=mypassword&_login=1'
302 Found
Found
The document has moved here.
If an error occurs you will receive the login mask’s HTML code - this ends with the following code: