I want to set up Icinga2 remote clients via Puppet, but the whole page of official documentation talks about using their awesome CLI wizard, which requires to be run manually.

Any workaround? Maybe I should just go back to Nagios?


2 Answers 2


I had the same issue. This is what I use, after extracting the logic from the icinga2 node wizard code.

Variables you will need:

$pki_dir - /etc/icinga2/pki in the default installation
$fqdn - fully host+domain name of the client.
$icinga2_master - resolvable fqdn of the master
$icinga2_master_port - the port the master is connectable on.
$ticket - generated on the master via 'icinga2 pki ticket --cn $fqdn'

The code:

mkdir icinga:icinga 0700 $pki_dir
icinga2 pki new-cert --cn $fqdn --key $pki_dir/$fqdn.key --cert $pki_dir/$fqdn.crt
icinga2 pki save-cert --key $pki_dir/$fqdn.key --cert $pki_dir/$fqdn.crt --trustedcert $pki_dir/trusted-master.crt --host $icinga2_master
icinga2 pki request --host $icinga2_master --port $icinga2_master_port --ticket $ticket --key $pki_dir/$fqdn.key --cert $pki_dir/$fqdn.crt --trustedcert $pki_dir/trusted-master.crt --ca $pki_dir/ca.key
icinga2 node setup --ticket $ticket --endpoint $icinga2_master --zone $fqdn --master_host $icinga2_master --trustedcert $pki_dir/trusted-master.crt
systemctl restart icinga2  # or however you restart your icinga

It's like TryTryAgain wrote. The latest docs describe two different ways. Top-Down Remote Command Execution and Top-Down Config Sync

The difference of this approaches is that remote command execution will trigger all commands from master while config sync will sync all config files located in /etc/icinga2/zones.d to the child nodes (satelites as well as clients) and trigger command execution directly on the endpoint.

I prefer to use the Top-Down Config Sync approach because the client will run checks even if the master looses connection to the child.

You have to enable the API feature on all nodes.

# /etc/icinga2/features-enabled/api.conf

object ApiListener "api" {
  cert_path = "/etc/ssl/{{ hostname }}.pem"
  key_path = "/etc/ssl/{{ hostname }}-key.pem"
  ca_path = "/etc/ssl/rootca.pem"

  // only on satelites and clients
  accept_config = true

Now create a zone file and copy it to all nodes

# /etc/icinga2/zones.conf

// global zone used for zone overlapping configs
object Zone "global" {
  global = true

// endpoints
object Endpoint "fqdn1.of.host" {
  host = "fqdn1.of.host"

object Endpoint "fqdn2.of.host" {
  host = "fqdn2.of.host"

// for each endpoint one zone
object Zone "fqdn1.of.host" {
  endpoints = [ "fqdn1.of.host" ]

object Zone "fqdn2.of.host" {
  endpoints = [ "fqdn2.of.host" ]
  parent = "fqdn1.of.host"

best practice is to use the fqdn of your nodes as endpoint name as well as zone name. Remember: copy this zones.conf to all nodes.

Next step would be to define all services, templates and groups inside of /etc/icinga2/zones.d/ and each host in it's own hosts.conf inside of it's zone directory.

# /etc/icinga2/zones.d/global/templates.conf

template Host "generic-host" {
  max_check_attempts = 3                                                                                                                     
  check_interval = 1m 
  retry_interval = 30s

  check_command = "hostalive"

# /etc/icinga2/zones.d/fqdn1.of.host/hosts.conf

// this is the master
object Host "fqdn1.of.host" {
  import "generic-host"
  address = "fqdn1.of.host"

# /etc/icinga2/zones.d/fqdn2.of.host/hosts.conf

// this is a satelite/client
object Host "fqdn2.of.host" {
  import "generic-host"
  address = "fqdn2.of.host"

My approach was to prevent using the configs inside /etc/icinga2/conf.d because I added all the generic (and global used) stuff in /etc/icinga2/zones.d/global and the host specific stuff inside /etc/icinga2/zones.d/fqdnX.of.host

Last but not least you have to remove the include statement for conf.d

# /etc/icinga2/icinga2.conf

// include_recursive "conf.d"

That's it. This setup requires to manage your certificates manually or with the config management of your choice. It will not generate it and is not using the icinga pki. Don't see any reason why I should use a tool specific pki as long as there are specific tools for this.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .