Is api-users.conf synced from master?

I am trying to set up a master-zone and two clients following the docs (

object ApiListener "api" {
  accept_config = true
  accept_commands = true

This works well enough except for one thing: it looks like api-users.conf isn’t synced as part of the configuration. Do I need to set that up manually on the clients, or is there something I’ve missed?

In fact, if I have to create api-users.conf on the clients, does that mean I have to give up the top-down architecture, or can I get away with just creating that one file on the clients?


for security reasons, I wouldn’t sync the API credentials to those nodes but rather have them setup locally where this really needed. If you’re really sure that this doesn’t open up security exploits, you can use the cluster config sync zones, e.g. put api-users.conf into the master or satellite zones then. I would also advise to use different ApIUsers for each zone to allow identifying (un)wanted access easier.


1 Like

That was quick :slight_smile: - so it is supposed to work that way, then? Thanks!

Suppose you have a satellite already installed and you’re syncing a host object config there.

cp conf.d/api-users.conf zones.d/satellite/
systemctl reload icinga2

wait a bit for the satellite to reconnect, sync and reload

curl -k -s -u username:password https://satellite.node:5665/v1

But that may be a security risk, you say. Would it work if I

  1. remove api-users.conf from conf.d on the master
  2. create api-users.conf (and remove all other files) in conf.d on the client
  3. add ‘include_recursive “conf.d”’ in icinga2.conf on both master and client


Before digging into the risks here, please clarify why you need the REST API on the client? The client/agent should solely execute checks e.g. via command endpoint, and nothing else.

Perhaps I use the wrong terminlogy? We have a master zone and two client/satelite (?) zones; I wish to implement passive checks, and the master can only be reached from the two clients/satelites due to configurations out side my control. It seems to work, BTW.

So, you want to feed in passive check results to the satellites which have the host/service objects synchronized, e.g. with an external script executed on a specific server, right?

The reason I am nitpicking here is that when you just sync that “one” ApiUser with a high grant of permissions, one can hijack the agent and extract that credentials. Having such, the most logical attempt to go up the chain and test whether this also works with the satellite and/or master.

In terms of passive check results, limit the permissions to exactly that (actions/process-check-result, check the docs for the proper setting). Do not use an ApiUser object which provides more or all (*) permissions.

Meaning to say, the ApiUser synced to that zone should have descriptive name and limited permissions.

object ApiUser "passive-results-satellite-zone-name" {
  password = ".."
  permissions = [


You are right, of course. I have changed my set up according to your recommendations. Thanks for your help.

1 Like