How to configure Nagios Core state retention

Nagios Core keeps host and service status in memory while it schedules checks, sends notifications, and accepts external commands. State retention decides which runtime state is restored after a daemon restart, so it affects maintenance restarts, package upgrades, and configuration changes that otherwise appear to be ignored.

The main /etc/nagios4/nagios.cfg file enables the retention file and controls program-wide state such as notification, event-handler, and check-execution switches. Host, service, and contact definitions can also set retain_status_information and retain_nonstatus_information so selected objects can keep or discard retained data without changing the whole monitoring server.

Use a restart, not only a syntax check, when the goal is to prove retention behavior because Nagios Core writes retention data during shutdown and reads it during startup. Package-managed Ubuntu and Debian systems use the nagios4 service name; source installs may use another service name, init script, or direct signal.

1. Back up the main Nagios Core configuration file.

   $ sudo cp /etc/nagios4/nagios.cfg /etc/nagios4/nagios.cfg.bak

2. Open the active main configuration file.

   $ sudoedit /etc/nagios4/nagios.cfg

   Use the main config path loaded by the local daemon. Source installs commonly use /usr/local/nagios/etc/nagios.cfg.

3. Set the global retention policy.

   retain_state_information=1
   state_retention_file=/var/lib/nagios4/retention.dat
   retention_update_interval=60
   use_retained_program_state=1
   use_retained_scheduling_info=1

   retention_update_interval is in minutes. Setting it to 0 disables periodic saves, but Nagios Core still saves retention data during shutdown or restart when retain_state_information is enabled.

   Set use_retained_program_state to 0 when edited values such as enable_notifications, execute_service_checks, or accept_passive_service_checks must override values changed through the web UI or external commands after restart.

4. Create or open the object file that needs a specific retention policy.

   $ sudoedit /etc/nagios4/conf.d/retention-configure.cfg

   Ubuntu and Debian packages load /etc/nagios4/conf.d from /etc/nagios4/nagios.cfg. Use a different loaded cfg_file or cfg_dir path when the active configuration names one.

5. Add object-level retention directives to the host, service, or template.

   define host {
       use                         linux-server
       host_name                   web01.example.net
       alias                       Web application host
       address                     192.0.2.10
       retain_status_information   0
       retain_nonstatus_information 1
   }
   
   define service {
       use                         generic-service
       host_name                   web01.example.net
       service_description         HTTP
       check_command               check_http
       retain_status_information   0
       retain_nonstatus_information 1
   }

   retain_status_information controls status-related data such as current state, check output, and attempts. retain_nonstatus_information controls non-status attributes changed at runtime, such as enabled checks, notifications, and related object flags. The same directives can be used on contact objects or contact templates.

6. Validate the Nagios Core configuration.

   $ sudo nagios4 -v /etc/nagios4/nagios.cfg
   Nagios Core 4.4.6
   ##### snipped #####
   Reading configuration data...
      Read main config file okay...
      Read object config files okay...
   
   Running pre-flight check on configuration data...
   ##### snipped #####
   Total Warnings: 0
   Total Errors:   0
   
   Things look okay - No serious problems were detected during the pre-flight check

   Use sudo /usr/local/nagios/bin/nagios -v /usr/local/nagios/etc/nagios.cfg on source installs that follow the upstream default layout.
   Related: How to validate the Nagios Core configuration

7. Restart Nagios Core so it writes and reloads the retention file.

   $ sudo systemctl restart nagios4

   A restart briefly stops check scheduling and notification processing. Use a maintenance window on busy monitoring servers.

   Use the service name for the local installation. Ubuntu and Debian packages use nagios4.
   Related: How to manage the Nagios Core system service

8. Confirm Nagios Core is active after the restart.

   $ systemctl is-active nagios4
   active

   If the service is not active, check /var/log/nagios4/nagios.log or the service journal before retrying the restart.
   Related: How to check Nagios Core logs

9. Confirm the retention file was written at the configured path.

   $ sudo ls -l /var/lib/nagios4/retention.dat
   -rw------- 1 nagios nagios 14489 Jun 25 00:52 /var/lib/nagios4/retention.dat

   A non-empty file owned by the nagios user confirms that the path is writable and state retention saved data during restart. If the file is missing, recheck retain_state_information, state_retention_file, parent directory permissions, and the daemon log.