Local Users
To log in, you first need to create a local user. The command to create one is:
./cmdbsyncer sys create_user mail@example.com
You can manage users in the UI under Settings → User.
Forced password change
With Force password change set on a user, every page of the web interface leads to the password form until the password was changed. Login, logout, the form itself and the 2FA setup stay reachable. The REST API and MCP are not affected, as service users and tokens have no way to change a password there.
Password reset
The login page offers a reset by mail. After setting a new password you log in as usual, including 2FA. Disabled users get no mail, and disabling a user ends their running session.
A new password ends all other running sessions of that user, whether it was changed by the user, reset by mail or set by an admin. The session that changed it stays logged in. It also revokes the personal API tokens of that user.
The link in the mail takes its address from the Host header of the request, unless you set
PUBLIC_URL in the local config, e.g.
'https://syncer.example.com', without BASE_PREFIX. Set it unless a proxy in front of the
syncer overwrites that header: otherwise whoever requests a reset mail for somebody else can
make its link point to a server of their own. Without PUBLIC_URL the log has a warning on
every reset.
Permissions (roles)
A user is either a global admin (full access to everything) or is granted individual permissions. Each permission unlocks the matching part of the UI:
| Permission | Grants access to |
|---|---|
| Hosts / Objects | the Host and Objects lists |
| Account Management | the Accounts views and the values in View Cache Details of a host, which can hold account credentials |
| Projects Since 4.3 | the Projects views |
| Cron Since 4.3 | the Cron groups + status views |
| Data Quality Since 4.3 | the Data Quality dashboard and Attribute Values |
| Generic Rules | Filter, Rewrite and Custom Attribute rules |
| Approvals | the critical-label approval queue |
| Log View, Files, User Management, … | the matching views |
| Secret Store Since 4.5 | the Secret Store: list, create, edit and bind entries (the Checkmk permission opens it as well) |
| Secret Store: show plaintext values Since 4.5 | showing the value of a Secret Store entry, on top of the Secret Store permission |
| Checkmk / Netbox / Ansible / … | the per-module menus |
| Checkmk: Data Quality Check Since 4.3 | only the Checkmk Data Quality Check page, without the rest of the Checkmk menu |
Since 4.3
Users without any Settings-area permission no longer see the Settings menu at all. "Projects" and "Cron" are now their own permissions (Projects used to require the Checkmk permission).
Limits of User Management
Without being a global admin, a user with this permission can't make anyone a global
admin and doesn't see 2FA secrets. They can only grant permissions and API roles they hold
themselves; the API role all covers every API role. Users with more rights can't be
changed or deleted. Restrictions to accounts or templates can't be seen or changed, and a
new user inherits the restrictions of the one creating it. Delegating user management
therefore means granting the permissions of the users to manage as well.
API roles
Separately from the UI permissions, a user has API roles that gate the
REST API. A role grants every endpoint below its path — e.g.
objects grants /api/v1/objects/*, syncer grants /api/v1/syncer/*; all grants
everything. Without a matching role the API returns 401.
Personal API tokens
Since 4.3
Every user can generate personal API tokens under Profile → API Tokens to authenticate against the REST API instead of sending their password. A token carries the user's own API roles and account scope, is shown once on creation, can be labelled and given an optional expiry, and can be revoked any time. See REST API → Personal API tokens.
A new password revokes all tokens of that user, whether it was changed by the user, reset by
mail, set by an admin or set with sys create_user. They stay in the list, marked as revoked,
and clients using them get a 401. The owner logs in with the new password and creates a new
token. A password changed in LDAP or at the OIDC provider never reaches the syncer, so it
leaves the tokens valid: revoke them by hand. The MCP server takes name and
password only, not these tokens.
Read-only users
Since 4.3
Ticking Read only on a user under Settings → User turns their account into a look-but-don't-touch account. It works the other way round from the permissions above and beats all of them, global admin included: the user keeps every view their roles open up and can change nothing.
This covers every way into the syncer:
- Web interface — no Create, Edit or Delete buttons, no bulk actions, no Commit button, no import or clone. Lists, detail pages, the log and the CSV export stay available.
- REST API — every reading call works as before, every writing one is answered with
403. A personal API token authenticates as its owner and carries the flag, so it is no way around the restriction. - MCP server — the reading tools work, the writing ones answer with an error.
Two things stay open, because they are the user's own account rather than syncer data: their password, 2FA, theme and API tokens, and their own saved searches.
Read only cannot be lifted from inside
A read-only user cannot edit users either, so they cannot clear the flag on themselves. Another admin has to do it.
Restricting a user to accounts
Since 4.3
Under Settings → User → Restrict to accounts you can limit a user to one or more accounts. When set, the user only sees and can act on hosts bound to those accounts — both in the REST API and in the web-UI Host and Objects lists (and the bulk Set Account action only offers those accounts). Leave it empty for full access.
Restricting a user to CMDB templates
Since 4.3
Under Settings → User → Restrict to templates you can limit a user to one or more CMDB templates. It works like the account restriction, only on the template side: the user sees just the hosts carrying one of those templates — in the web-UI Host, Objects and Archive lists as well as over the REST API — and can only assign those templates, in the host form and on the Checkmk Data Quality page. Leave it empty for full access.
Both restrictions can be combined: a user carrying an account and a template allowlist only reaches hosts that satisfy each of them.
This holds for every bulk action and every page about a host, as well as for the approval queue. Re-apply to matching hosts goes over all hosts a template matches, so it isn't available to restricted users.
Secret Store and host import (since 4.5)
A restricted user, global admins included, only reaches Secret Store entries bound to their own hosts and never global entries. In the host import preview they are only offered their own accounts and templates and cannot overwrite an existing host outside their scope.
Data Quality Check
On the Checkmk Data Quality Check page a restricted user also sees the hosts no template has claimed yet — those are the ones they may take over with their own template. Hosts carrying somebody else's template stay invisible, and creating hosts there requires picking one of their templates, so a newly created host does not disappear from its creator.