service_autorestart

Table of Contents

1. Description
2. Setup
   • What service_autorestart affects
   • Setup requirements
   • Beginning with service_autorestart
3. Usage
   • Cross-platform autorestart
   • SystemD autorestart
   • Windows autorestart

Description

This module solves the problem of configuring a service to automatically restart itself in case the service fails or dies. In Windows this is called "Service Recovery" or "Service Failure" and can be found in the Service configuration dialog under the "Recovery" tab. On Linux systems this is simply a parameter on the service unit file in SystemD.

Setup

What service_autorestart affects

On Linux, this module changes the SystemD unit file for the service specified, adding the Restart= and RestartSec= parameters.

On Windows, this module configures the Service Recovery (Service Failure) options using the CLI command sc.exe.

Setup Requirements

This module uses the new Puppet Resource API.

In Puppet >= 6 the Resource API is included with the agent and server installations.

If you're running Puppet <= 5 then you'll need to install the Resource API using the puppetlabs/resource_api module on the forge.

Beginning with service_autorestart

Basic usage to enable automatic restarts of a service in a cross-plaform way (works for SystemD and Windows):

service_autorestart::generic { 'myservice': }

This will declare the appropriate resources to configure service autorestart depending on your OS. It will also automatically declare the correct notify and require relationships depending on the OS so that things happen in the right order. Example: on Windows the service resource must exist. On Linux the SystemD unit file must exist and we must then invoke systemctl daemon-reload after making our change (requires the use of camptocamp/sytemd module by default).

Usage

Cross-platform autorestart

The service_autorestart::generic resource provides basic configuration for enabling the automatic restart capability of a service when it fails. It is intentionally limited on options. If you need to tweak settings, please declare one of the OS specific resources.

service_autorestart::generic { 'myservice': }

SystemD autorestart

Basic usage, configure auto-restart for the Puppet service

service_autorestart::systemd { 'puppet': }

Customize the delay between restarts

service_autorestart::systemd { 'myservice':
  delay => '90s',
}

Customize the path and when action restarts

service_autorestart::systemd { nginx':
  path  => '/usr/local/lib/systemd/system/nginx.service',
  value => 'on-abort',
  delay => '90s',
}

Disable auto-notify relationships

service_autorestart::systemd { 'puppet':
  autonotify_path                    => false,
  autonotify_systemctl_daemon_reload => false,
}

Windows autorestart

Basic usage, auto-restart the Puppet service

service_autorestart::windows { 'puppet': }

Delay restarting the service for 60 seconds.

service_autorestart::windows { 'puppet':
  delay => 60000,  # delay is in milliseconds
}

Reboot the computer when the service fails

service_autorestart::windows { 'myservice':
  action         => 'reboot',
  reboot_message => 'service "myservice" failed, rebooting',
}

Run a command when the service fails

service_autorestart::windows { 'myservice':
  action  => 'run_command',
  command => 'msg "myservice failed, showing a popup so you know"',
}

Windows Low-level Service Recovery management

Apart from the high-level defines for Windows auto-restarts, we also provide a resource service_recovery to control all aspects of Windows Service Recovery in a fine-grained way:

service_recovery { 'myservice':
  reboot_message  => "Rebooting because 'myservice' failed",
  command         => 'msg "myservice failed, showing a popup so you know"',
  failure_actions => [
    {
      action => 'restart',
      delay  => 60000,
    },
    {
      action => 'reboot',
      delay  => 120000,
    },
    {
      action => 'run_command',
      delay  => 180000,
    },
  ],
}

For more details on this resource and the options see REFERENCE.md.

Reference

Table of Contents

Defined types

• service_autorestart::generic: Configures a service for auto-restart in a platform agnostic way.
• service_autorestart::systemd: Manages the auto-restart (aka service recovery) for a SystemD service.
• service_autorestart::windows: Manages the auto-restart (aka service recovery) for a Windows service.

Resource types

• service_recovery: Manages the Recovery/Failure settings for a Windows Service Autorequires: Puppet will auto-require the service resource with the same 'na

Defined types

service_autorestart::generic

This is very simplistic and doesn't allow tweaking of the parmeters. If you need to tweak settings, you'll need to declare the service_autorestart::windows or service_autorestart::systemd directly.

service_autorestart::systemd

Manages the auto-restart (aka service recovery) for a SystemD service.

Examples

Basic usage

service_autorestart::systemd { 'puppet': }

Customize the delay between restarts

service_autorestart::systemd { 'puppet':
  delay => '90s',
}

Customize the path and when action restarts

service_autorestart::systemd { 'puppet':
  path  => '/usr/local/lib/systemd/system/puppet.service',
  value => 'on-abort',
  delay => '90s',
}

Disable auto-notify relationships

service_autorestart::systemd { 'puppet':
  autonotify_path                    => false,
  autonotify_systemctl_daemon_reload => false,
}

Parameters

The following parameters are available in the service_autorestart::systemd defined type.

path

Data type: String

Path to the systemd service file for this service

Default value: "/usr/lib/systemd/system/${title}.service"

value

Data type: String

The value of the Reset= setting for the SystemD service. https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=

Default value: 'on-failure'

delay

Data type: Optional[String]

The value of the ResetSec= setting for the SystemD service. https://www.freedesktop.org/software/systemd/man/systemd.service.html#RestartSec=

Default value: undef

autonotify_path

Data type: Boolean

Flag to enable creating an automatic notify relationship between the File[$path] and the Ini settings to modify the Restart parameters. Even if enabled, the relationships are protected with a guard, so if File[$path] is not defined the relationship will not be created. This prevents errors in environments where these resources aren't managed by Puppet

Default value: true

autonotify_systemctl_daemon_reload

Data type: Boolean

Flag to enable creating an automatic notify relationship between the 'systemctl daemon-reload' command and the Ini settings to modify the Restart parameters. The settings will be applied first and the notify the Class['systemd::systemctl::daemon_reload'] of changes. This is enabled by default but probably only useful if you use the camptocamp/systemd module. Even if enabled, the relationships are protected with a guard, so if Class['systemd::systemctl::daemon_reload'] is not defined the relationship will not be created. This prevents errors in environments where these resources aren't managed by Puppet or the camptocamp/systemd module is not used.

Default value: true

service_autorestart::windows

Manages the auto-restart (aka service recovery) for a Windows service.

Examples

Auto-restart the Puppet service

service_autorestart::windows { 'puppet': }

Delay restarting the service for 60 seconds.

service_autorestart::windows { 'puppet':
  delay => 60000,  # delay is in milliseconds
}

Reboot the computer when the service fails

service_autorestart::windows { 'myservice':
  action         => 'reboot',
  reboot_message => 'service "myservice" failed, rebooting',
}

Run a command when the service fails

service_autorestart::windows { 'myservice':
  action  => 'run_command',
  command => 'msg "myservice failed, showing a popup so you know"',
}

Parameters

The following parameters are available in the service_autorestart::windows defined type.

action

Data type: Enum['noop', 'reboot', 'restart', 'run_command']

• 'noop' = take no action.
• 'reboot' = reboot the computer, displaying reboot_message before rebooting.
• 'restart' = restart the service.
• run_command = executes the command when the service fails

Default value: 'restart'

delay

Data type: Integer[0]

Number of millisecondsseconds (positive number) to wait before restarting the service.

Default value: 1000

reset_period

Data type: Integer[0]

Number of seconds to wait before resetting the "failed" count. Default: 86,400 = 1 day (Windows default).

Default value: 86400

reboot_message

Data type: Optional[String]

Message to display before rebooting the computer. This is only used when specifying action => 'reboot'

Default value: undef

command

Data type: Optional[String]

Command to run on failure. This is only used when specifying an `action => 'command'.

Default value: undef

Resource types

service_recovery

Manages the Recovery/Failure settings for a Windows Service Autorequires: Puppet will auto-require the service resource with the same 'name' as this resource.

Properties

The following properties are available in the service_recovery type.

reset_period

Data type: Integer[0]

Number of seconds to wait before resetting the "failed" count. Default: 86,400 = 1 day (Windows default).

Default value: 86400

reboot_message

Data type: Optional[String]

Message to display before rebooting the computer. This only matters if you use a "failure_action" with an "action" of "reboot".

command

Data type: Optional[String]

    Command to run on failure. This only matters if you use a "failure_action" with an
    "action" of "run_command". Note: Windows uses the same command for each failure,
    you can not specify a unique command per-failure.'

failure_actions

Data type: Array[Struct[{action => Enum["noop", "reboot", "restart", "run_command"], delay => Integer[0]} ], 0, 3]

    List of actions to perform when the service fails. This takes two parameters "action",
    the type of action to execute. Action "noop" means take no action. Action "reboot"
    means reboot the computer display the "reboot_message" prior to rebooting. Action
    "restart" means restart the service. Action "run_command" executes the "command"
    when the service fails. The "delay" parameter is measure in milliseconds. The maximum
    size of this array is 3.'

Default value: []

Parameters

The following parameters are available in the service_recovery type.

name

namevar

Data type: String[1]

Name of the service.

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.4

Bugfixes

• Fixed data/common.yaml to contain a valid hash, fixing Puppet Server side warnings.

Release 0.1.3

Features

• PDK update to 1.18.0

Release 0.1.2

Bugfixes

• Fixed service_autorestart::systemd from throwing and error on Ubuntu because it was using a different path for .service files. We now use module-level hiera data to default these locations.

Release 0.1.1

Bugfixes

• Change from using $facts['os']['family'] to $facts['service_provider'] from puppetlabs/stdlib. This allows service_autorestart::generic to "do the right thing" when detecting systemd.

Release 0.1.0

Features

Initial implemention including the following types:

• service_autorestart::generic - Single type to define a basic service_autorestart::xxx resource depending on what OS is in $facts
• service_autorestart::systemd - Resource to manage autorestart capability on SystemD OSes.
• service_autorestart::windows - Resource to manage autorestart capability on Windows.
• service_recovery - Resource to manage low-level configuration of Service Recovery on Windows.

Bugfixes

Known Issues