Agent registration role
To register agents for updates and TLS encryption, it's often useful to create a dedicated user and role. This article explains how.
LAST TESTED ON CHECKMK 2.4.0P1
Table of Contents
Getting Started
Background information regarding this subject is available on our:
Agent Registration for Automatic Updates
The UI way
The easiest way to build an agent registration role is by using the GUI and following these steps:
Go to Setup → Users → Roles & Permissions.
Checkmk 2.3
Duplicate the guest role and assign a meaningful name. For this knowledge base, the role is namedagent_updates_registration.
Checkmk 2.4
Duplicate the no_permissions role and assign a meaningful name. For this knowledge base, the role is also namedagent_updates_registration.Ensure the role has the following permissions:
"Use the GUI at all"
"Register Host & download monitoring agents of your hosts",
"Register all hosts & download all monitoring agents"
Optionally (for security reasons) you can disable all other permissions.
Create a user with a meaningful name and configure the following:
Authentication: Automation Secret
Assign the agent registration role created before
The config file way
We always recommend using the GUI instead of modifying .mk files. For any issue or broken config, we do not provide any support.
In exceptional circumstances, you might want to adjust configuration files with caution. Please do a backup before adjusting the files.
Pretty print the configuration for a better overview: How-to enable Pretty-print configuration files. (don't forget to activate a change after enabling pretty-print, so that the config gets rewritten in a more readable format)
Add the following section to the config file:
~/etc/check_mk/multisite.d/wato/roles.mk.
For Checkmk 2.3:
'agent_updates_registration': {'alias': 'Agent Updates Registration',
'basedon': 'guest',
'builtin': False,
'permissions': {'action.acknowledge': False,
'action.addcomment': False,
'action.aggregation_freeze': False,
'action.clearmodattr': False,
'action.customnotification': False,
'action.delete_crash_report': False,
'action.downtimes': False,
'action.enablechecks': False,
'action.fakechecks': False,
'action.notifications': False,
'action.remove_all_downtimes': False,
'action.reschedule': False,
'agent_registration.register_any_existing_host': False,
'agent_registration.register_managed_existing_host': False,
'background_jobs.delete_foreign_jobs': False,
'background_jobs.delete_jobs': False,
'background_jobs.manage_jobs': False,
'background_jobs.see_foreign_jobs': False,
'background_jobs.stop_foreign_jobs': False,
'background_jobs.stop_jobs': False,
'bi.see_all': False,
'dashboard.checkmk': False,
'dashboard.kubernetes_cluster': False,
'dashboard.kubernetes_daemonset': False,
'dashboard.kubernetes_deployment': False,
'dashboard.kubernetes_namespace': False,
'dashboard.kubernetes_overview': False,
'dashboard.kubernetes_statefulset': False,
'dashboard.linux_hosts_overview': False,
'dashboard.linux_single_overview': False,
'dashboard.main': False,
'dashboard.ntop_alerts': False,
'dashboard.ntop_flows': False,
'dashboard.ntop_top_talkers': False,
'dashboard.problems': False,
'dashboard.simple_problems': False,
'dashboard.site': False,
'dashboard.synthetic_monitoring_overview': False,
'dashboard.windows_hosts_overview': False,
'dashboard.windows_single_overview': False,
'general.acknowledge_werks': False,
'general.act': False,
'general.agent_pairing': False,
'general.change_password': False,
'general.configure_sidebar': False,
'general.csv_export': False,
'general.delete_foreign_bookmark_list': False,
'general.delete_foreign_custom_graph': False,
'general.delete_foreign_custom_snapin': False,
'general.delete_foreign_dashboards': False,
'general.delete_foreign_forecast_graph': False,
'general.delete_foreign_graph_collection': False,
'general.delete_foreign_graph_tuning': False,
'general.delete_foreign_pagetype_topic': False,
'general.delete_foreign_reports': False,
'general.delete_foreign_sla_configuration': False,
'general.delete_foreign_stored_report': False,
'general.delete_foreign_views': False,
'general.delete_stored_report': False,
'general.disable_notifications': False,
'general.edit_bookmark_list': False,
'general.edit_custom_graph': False,
'general.edit_custom_snapin': False,
'general.edit_dashboards': False,
'general.edit_forecast_graph': False,
'general.edit_foreign_bookmark_list': False,
'general.edit_foreign_custom_graph': False,
'general.edit_foreign_custom_snapin': False,
'general.edit_foreign_dashboards': False,
'general.edit_foreign_forecast_graph': False,
'general.edit_foreign_graph_collection': False,
'general.edit_foreign_graph_tuning': False,
'general.edit_foreign_pagetype_topic': False,
'general.edit_foreign_reports': False,
'general.edit_foreign_sla_configuration': False,
'general.edit_foreign_views': False,
'general.edit_graph_collection': False,
'general.edit_graph_tuning': False,
'general.edit_notifications': False,
'general.edit_pagetype_topic': False,
'general.edit_profile': False,
'general.edit_reports': False,
'general.edit_sla_configuration': False,
'general.edit_user_attributes': False,
'general.edit_views': False,
'general.force_bookmark_list': False,
'general.force_custom_graph': False,
'general.force_custom_snapin': False,
'general.force_dashboards': False,
'general.force_forecast_graph': False,
'general.force_graph_collection': False,
'general.force_graph_tuning': False,
'general.force_pagetype_topic': False,
'general.force_reports': False,
'general.force_sla_configuration': False,
'general.force_views': False,
'general.ignore_hard_limit': False,
'general.ignore_soft_limit': False,
'general.instant_reports': False,
'general.logout': False,
'general.manage_2fa': False,
'general.message': False,
'general.painter_options': False,
'general.parent_child_topology': False,
'general.publish_bookmark_list': False,
'general.publish_custom_graph': False,
'general.publish_custom_snapin': False,
'general.publish_dashboards': False,
'general.publish_dashboards_to_foreign_groups': False,
'general.publish_dashboards_to_groups': False,
'general.publish_dashboards_to_sites': False,
'general.publish_forecast_graph': False,
'general.publish_graph_collection': False,
'general.publish_graph_tuning': False,
'general.publish_pagetype_topic': False,
'general.publish_reports': False,
'general.publish_reports_to_foreign_groups': False,
'general.publish_reports_to_groups': False,
'general.publish_reports_to_sites': False,
'general.publish_sla_configuration': False,
'general.publish_stored_report': False,
'general.publish_to_foreign_groups_bookmark_list': False,
'general.publish_to_foreign_groups_custom_graph': False,
'general.publish_to_foreign_groups_custom_snapin': False,
'general.publish_to_foreign_groups_forecast_graph': False,
'general.publish_to_foreign_groups_graph_collection': False,
'general.publish_to_foreign_groups_graph_tuning': False,
'general.publish_to_foreign_groups_pagetype_topic': False,
'general.publish_to_foreign_groups_sla_configuration': False,
'general.publish_to_groups_bookmark_list': False,
'general.publish_to_groups_custom_graph': False,
'general.publish_to_groups_custom_snapin': False,
'general.publish_to_groups_forecast_graph': False,
'general.publish_to_groups_graph_collection': False,
'general.publish_to_groups_graph_tuning': False,
'general.publish_to_groups_pagetype_topic': False,
'general.publish_to_groups_sla_configuration': False,
'general.publish_to_sites_bookmark_list': False,
'general.publish_to_sites_custom_graph': False,
'general.publish_to_sites_custom_snapin': False,
'general.publish_to_sites_forecast_graph': False,
'general.publish_to_sites_graph_collection': False,
'general.publish_to_sites_graph_tuning': False,
'general.publish_to_sites_pagetype_topic': False,
'general.publish_to_sites_sla_configuration': False,
'general.publish_views': False,
'general.publish_views_to_foreign_groups': False,
'general.publish_views_to_groups': False,
'general.publish_views_to_sites': False,
'general.reporting': False,
'general.schedule_reports': False,
'general.schedule_reports_all': False,
'general.see_all': False,
'general.see_availability': False,
'general.see_crash_reports': False,
'general.see_failed_notifications': False,
'general.see_failed_notifications_24h': False,
'general.see_packaged_dashboards': False,
'general.see_packaged_reports': False,
'general.see_packaged_views': False,
'general.see_sidebar': False,
'general.see_stales_in_tactical_overview': False,
'general.see_user_bookmark_list': False,
'general.see_user_custom_graph': False,
'general.see_user_custom_snapin': False,
'general.see_user_dashboards': False,
'general.see_user_forecast_graph': False,
'general.see_user_graph_collection': False,
'general.see_user_graph_tuning': False,
'general.see_user_pagetype_topic': False,
'general.see_user_reports': False,
'general.see_user_sla_configuration': False,
'general.see_user_stored_report': False,
'general.see_user_views': False,
'general.server_side_requests': False,
'general.use': True,
'general.view_option_columns': False,
'general.view_option_refresh': False,
'graph_collection.default': False,
'icons_and_actions.action_menu': False,
'icons_and_actions.agent_deployment': False,
'icons_and_actions.aggregation_checks': False,
'icons_and_actions.aggregations': False,
'icons_and_actions.check_manpage': False,
'icons_and_actions.check_period': False,
'icons_and_actions.crashed_check': False,
'icons_and_actions.custom_action': False,
'icons_and_actions.deployment_status': False,
'icons_and_actions.download_agent_output': False,
'icons_and_actions.download_snmp_walk': False,
'icons_and_actions.icon_image': False,
'icons_and_actions.inventory': False,
'icons_and_actions.logwatch': False,
'icons_and_actions.mkeventd': False,
'icons_and_actions.network_topology': False,
'icons_and_actions.notes': False,
'icons_and_actions.ntop_host': False,
'icons_and_actions.parent_child_topology': False,
'icons_and_actions.perfgraph': False,
'icons_and_actions.prediction': False,
'icons_and_actions.reschedule': False,
'icons_and_actions.robotmk_suite_ok_log': False,
'icons_and_actions.rule_editor': False,
'icons_and_actions.stars': False,
'icons_and_actions.status_acknowledged': False,
'icons_and_actions.status_active_checks': False,
'icons_and_actions.status_comments': False,
'icons_and_actions.status_downtimes': False,
'icons_and_actions.status_flapping': False,
'icons_and_actions.status_notification_period': False,
'icons_and_actions.status_notifications_enabled': False,
'icons_and_actions.status_passive_checks': False,
'icons_and_actions.status_service_period': False,
'icons_and_actions.status_shadow': False,
'icons_and_actions.status_stale': False,
'icons_and_actions.wato': False,
'mkeventd.actions': False,
'mkeventd.activate': False,
'mkeventd.archive_events_of_hosts': False,
'mkeventd.changestate': False,
'mkeventd.config': False,
'mkeventd.delete': False,
'mkeventd.edit': False,
'mkeventd.see_in_tactical_overview': False,
'mkeventd.seeall': False,
'mkeventd.seeunrelated': False,
'mkeventd.switchmode': False,
'mkeventd.update': False,
'mkeventd.update_comment': False,
'mkeventd.update_contact': False,
'nagvis.*_*_*': False,
'nagvis.Map_delete': False,
'nagvis.Map_delete_*': False,
'nagvis.Map_edit': False,
'nagvis.Map_edit_*': False,
'nagvis.Map_view': False,
'nagvis.Map_view_*': False,
'nagvis.Rotation_view_*': False,
'notification_plugin.asciimail': False,
'notification_plugin.cisco_webex_teams': False,
'notification_plugin.ilert': False,
'notification_plugin.jira_issues': False,
'notification_plugin.mail': False,
'notification_plugin.mkeventd': False,
'notification_plugin.msteams': False,
'notification_plugin.opsgenie_issues': False,
'notification_plugin.pagerduty': False,
'notification_plugin.pushover': False,
'notification_plugin.servicenow': False,
'notification_plugin.signl4': False,
'notification_plugin.slack': False,
'notification_plugin.sms': False,
'notification_plugin.sms_api': False,
'notification_plugin.spectrum': False,
'notification_plugin.victorops': False,
'pagetype_topic.analyze': False,
'pagetype_topic.applications': False,
'pagetype_topic.bi': False,
'pagetype_topic.cloud': False,
'pagetype_topic.events': False,
'pagetype_topic.history': False,
'pagetype_topic.inventory': False,
'pagetype_topic.it_efficiency': False,
'pagetype_topic.monitoring': False,
'pagetype_topic.my_workplace': False,
'pagetype_topic.network_statistics': False,
'pagetype_topic.other': False,
'pagetype_topic.overview': False,
'pagetype_topic.problems': False,
'pagetype_topic.synthetic_monitoring': False,
'report.bi_availability': False,
'report.default': False,
'report.host': False,
'report.host_performance_graphs': False,
'report.instant': False,
'report.instant_availability': False,
'report.instant_graph_collection': False,
'report.instant_view': False,
'report.service_availability': False,
'sidesnap.admin_mini': False,
'sidesnap.biaggr_groups': False,
'sidesnap.biaggr_groups_tree': False,
'sidesnap.bookmarks': False,
'sidesnap.cmc_stats': False,
'sidesnap.dashboards': False,
'sidesnap.hostgroups': False,
'sidesnap.master_control': False,
'sidesnap.mkeventd_performance': False,
'sidesnap.nagvis_maps': False,
'sidesnap.performance': False,
'sidesnap.reports': False,
'sidesnap.search': False,
'sidesnap.servicegroups': False,
'sidesnap.sitestatus': False,
'sidesnap.speedometer': False,
'sidesnap.tactical_overview': False,
'sidesnap.tag_tree': False,
'sidesnap.time': False,
'sidesnap.views': False,
'sidesnap.wato_foldertree': False,
'view.aggr_all': False,
'view.aggr_all_api': False,
'view.aggr_all_frozen': False,
'view.aggr_frozen_diff': False,
'view.aggr_group': False,
'view.aggr_host': False,
'view.aggr_hostgroup_boxed': False,
'view.aggr_hostnameaggrs': False,
'view.aggr_hostproblems': False,
'view.aggr_problems': False,
'view.aggr_service': False,
'view.aggr_single': False,
'view.aggr_single_api': False,
'view.aggr_singlehost': False,
'view.aggr_singlehosts': False,
'view.aggr_summary': False,
'view.alerthandlers': False,
'view.alertstats': False,
'view.allhosts': False,
'view.allhosts_deploy': False,
'view.allservices': False,
'view.api_downtimes': False,
'view.bi_map_hover_host': False,
'view.bi_map_hover_service': False,
'view.cmk_servers': False,
'view.cmk_sites': False,
'view.cmk_sites_of_host': False,
'view.comments': False,
'view.comments_of_host': False,
'view.comments_of_service': False,
'view.contactnotifications': False,
'view.crash_reports': False,
'view.docker_containers': False,
'view.docker_nodes': False,
'view.downtime_history': False,
'view.downtimes': False,
'view.downtimes_of_host': False,
'view.downtimes_of_service': False,
'view.ec_event': False,
'view.ec_event_mobile': False,
'view.ec_events': False,
'view.ec_events_mobile': False,
'view.ec_events_of_host': False,
'view.ec_events_of_monhost': False,
'view.ec_history_of_event': False,
'view.ec_history_of_host': False,
'view.ec_history_recent': False,
'view.ec_historyentry': False,
'view.events': False,
'view.events_dash': False,
'view.failed_notifications': False,
'view.host': False,
'view.host_crit': False,
'view.host_dt_hist': False,
'view.host_export': False,
'view.host_graphs': False,
'view.host_ok': False,
'view.host_pending': False,
'view.host_unknown': False,
'view.host_warn': False,
'view.hostevents': False,
'view.hostgroup': False,
'view.hostgroup_down': False,
'view.hostgroup_pend': False,
'view.hostgroup_unreach': False,
'view.hostgroup_up': False,
'view.hostgroups': False,
'view.hostgroupservices': False,
'view.hostgroupservices_crit': False,
'view.hostgroupservices_ok': False,
'view.hostgroupservices_pend': False,
'view.hostgroupservices_unknwn': False,
'view.hostgroupservices_warn': False,
'view.hostnotifications': False,
'view.hostpnp': False,
'view.hostproblems': False,
'view.hostproblems_dash': False,
'view.hosts': False,
'view.hoststatus': False,
'view.hostsvcevents': False,
'view.hostsvcnotifications': False,
'view.inv_host': False,
'view.inv_host_history': False,
'view.inv_hosts_cpu': False,
'view.inv_hosts_ports': False,
'view.invbackplane_of_host': False,
'view.invbackplane_search': False,
'view.invchassis_of_host': False,
'view.invchassis_search': False,
'view.invcmksites_of_host': False,
'view.invcmksites_search': False,
'view.invcmkversions_of_host': False,
'view.invcmkversions_search': False,
'view.invcontainer_of_host': False,
'view.invcontainer_search': False,
'view.invdockercontainers_of_host': False,
'view.invdockercontainers_search': False,
'view.invdockerimages_of_host': False,
'view.invdockerimages_search': False,
'view.invfan_of_host': False,
'view.invfan_search': False,
'view.invibmmqchannels_of_host': False,
'view.invibmmqchannels_search': False,
'view.invibmmqmanagers_of_host': False,
'view.invibmmqmanagers_search': False,
'view.invibmmqqueues_of_host': False,
'view.invibmmqqueues_search': False,
'view.invinterface_of_host': False,
'view.invinterface_search': False,
'view.invkernelconfig_of_host': False,
'view.invkernelconfig_search': False,
'view.invmodule_of_host': False,
'view.invmodule_search': False,
'view.invoradataguardstats_of_host': False,
'view.invoradataguardstats_search': False,
'view.invorainstance_of_host': False,
'view.invorainstance_search': False,
'view.invorapga_of_host': False,
'view.invorapga_search': False,
'view.invorarecoveryarea_of_host': False,
'view.invorarecoveryarea_search': False,
'view.invorasga_of_host': False,
'view.invorasga_search': False,
'view.invorasystemparameter_of_host': False,
'view.invorasystemparameter_search': False,
'view.invoratablespace_of_host': False,
'view.invoratablespace_search': False,
'view.invother_of_host': False,
'view.invother_search': False,
'view.invpsu_of_host': False,
'view.invpsu_search': False,
'view.invsensor_of_host': False,
'view.invsensor_search': False,
'view.invstack_of_host': False,
'view.invstack_search': False,
'view.invswpac_of_host': False,
'view.invswpac_search': False,
'view.invsyntheticmonitoringplans_of_host': False,
'view.invsyntheticmonitoringplans_search': False,
'view.invsyntheticmonitoringtests_of_host': False,
'view.invsyntheticmonitoringtests_search': False,
'view.invtunnels_of_host': False,
'view.invtunnels_search': False,
'view.invunknown_of_host': False,
'view.invunknown_search': False,
'view.it_efficiency_servers_cpumem_esxi': False,
'view.it_efficiency_servers_cpumem_linux': False,
'view.it_efficiency_servers_cpumem_nutanix': False,
'view.it_efficiency_servers_cpumem_windows': False,
'view.it_efficiency_servers_fs_esxi': False,
'view.it_efficiency_servers_fs_linux': False,
'view.it_efficiency_servers_fs_windows': False,
'view.logfile': False,
'view.mobile_contactnotifications': False,
'view.mobile_events': False,
'view.mobile_host': False,
'view.mobile_hostproblems': False,
'view.mobile_hostproblems_unack': False,
'view.mobile_hoststatus': False,
'view.mobile_hostsvcevents': False,
'view.mobile_hostsvcnotifications': False,
'view.mobile_notifications': False,
'view.mobile_searchhost': False,
'view.mobile_searchsvc': False,
'view.mobile_service': False,
'view.mobile_svcevents': False,
'view.mobile_svcnotifications': False,
'view.mobile_svcproblems': False,
'view.mobile_svcproblems_unack': False,
'view.nagstamon_hosts': False,
'view.nagstamon_svc': False,
'view.notifications': False,
'view.pending_discovery': False,
'view.pendingsvc': False,
'view.perf_matrix': False,
'view.perf_matrix_search': False,
'view.problemsofhost': False,
'view.recentsvc': False,
'view.searchhost': False,
'view.searchpnp': False,
'view.searchsvc': False,
'view.service': False,
'view.service_check_durations': False,
'view.service_graphs': False,
'view.servicedesc': False,
'view.servicegroup': False,
'view.sitehosts': False,
'view.sitesvcs': False,
'view.sitesvcs_crit': False,
'view.sitesvcs_ok': False,
'view.sitesvcs_pend': False,
'view.sitesvcs_unknwn': False,
'view.sitesvcs_warn': False,
'view.stale_hosts': False,
'view.svc_dt_hist': False,
'view.svcevents': False,
'view.svcgroups': False,
'view.svcnotifications': False,
'view.svcproblems': False,
'view.svcproblems_dash': False,
'view.synthetic_monitoring_tests': False,
'view.topology_filters': False,
'view.topology_hover_host': False,
'view.topology_hover_service': False,
'view.uncheckedsvc': False,
'view.unmonitored_services': False,
'view.vpshere_vms': False,
'view.vsphere_servers': False,
'wato.activate': False,
'wato.activateforeign': False,
'wato.add_or_modify_executables': False,
'wato.agent_deploy_custom_files': False,
'wato.agent_deployment': False,
'wato.agents': False,
'wato.alert_handlers': False,
'wato.all_folders': False,
'wato.analyze_config': False,
'wato.auditlog': False,
'wato.automation': False,
'wato.backups': False,
'wato.bake_agents': False,
'wato.bi_admin': False,
'wato.bi_rules': False,
'wato.check_plugins': False,
'wato.clear_auditlog': False,
'wato.clone_hosts': False,
'wato.custom_attributes': False,
'wato.dcd_connections': False,
'wato.diag_host': False,
'wato.diagnostics': False,
'wato.discard': False,
'wato.discardforeign': False,
'wato.download_agent_output': False,
'wato.download_agents': True,
'wato.download_all_agents': True,
'wato.edit': False,
'wato.edit_all_passwords': False,
'wato.edit_all_predefined_conditions': False,
'wato.edit_folders': False,
'wato.edit_hosts': False,
'wato.global': False,
'wato.groups': False,
'wato.hosts': False,
'wato.hosttags': False,
'wato.icons': False,
'wato.influxdb_connections': False,
'wato.license_usage': False,
'wato.licensing': False,
'wato.licensing_settings': False,
'wato.manage_folders': False,
'wato.manage_hosts': False,
'wato.manage_mkps': False,
'wato.mkps': False,
'wato.move_hosts': False,
'wato.notifications': False,
'wato.parentscan': False,
'wato.passwords': False,
'wato.pattern_editor': False,
'wato.random_hosts': False,
'wato.rename_hosts': False,
'wato.rulesets': False,
'wato.see_all_folders': False,
'wato.seeall': False,
'wato.service_discovery_to_ignored': False,
'wato.service_discovery_to_monitored': False,
'wato.service_discovery_to_removed': False,
'wato.service_discovery_to_undecided': False,
'wato.services': False,
'wato.set_read_only': False,
'wato.show_last_user_activity': False,
'wato.sign_agents': False,
'wato.sites': False,
'wato.snapshots': False,
'wato.timeperiods': False,
'wato.update_dns_cache': False,
'wato.use': False,
'wato.user_migrate': False,
'wato.users': False}},For Checkmk 2.4:
You can use the same code block as above, but update the line 'basedon': 'guest', to 'basedon': 'no_permissions',.
In order to put it in the right place, please add a comma "," before the "})".
After registering the agent for automatic updates by using the newly created role, you will get this warning:
Successfully registered agent of host "linux" for deployment.
Note: The host "linux" is currently not known in the active monitoring configuration.
You can however add this host to the monitoring later on without having to register again.
Please check the exact spelling if you intended to register an existing host.This is totally fine, the warning is generated due to the fact that the registration role you have used have very limited permissions.
For more information regarding the registration for automatic agent updates, read this documentation section.
Agent Registration (Pairing) for TLS Encryption
Starting with Checkmk 2.2, there is a built-in user and role that can be used for registering the agent controller. The user is called agent_registration. For more information about this, check Werk #15408.
Relevant documentation sections: