Configuring patch management

To enable patch management, create a node group for nodes you want to patch and add the node group to the PE Patch Management parent node group.

Patch management OS compatibility

Patch management is compatible with current Linux operating systems using YUM, APT, and Zypper package management, as well as Microsoft Windows operating systems. We currently test against the following platforms, and these are confirmed to be compatible.

Operating system Versions
AlmaLinux 8
Amazon Linux 2
CentOS 7
Debian 10, 11
Fedora
Note: You must install cron to run patch management on Fedora. To install cron, run dnf install cronie
36
Microsoft Windows 10, 11
Microsoft Windows Server
Note: You must use PowerShell 3.0 or higher to patch Windows nodes.
 2012, 2012 R2, 2016, 2019, 2022
Oracle Linux 7, 8
Red Hat Enterprise Linux 7, 8
Rocky Linux 8
Scientific Linux 7
SUSE Linux Enterprise Server 12, 15
Ubuntu 18.04, 20.04, 22.04
Note: If your operating system doesn't support TLSv1.2 or higher, you must Enable TLSv1 or 1.1.

Where patch information comes from

Your package management software is responsible for ensuring PE can find the latest patch information available.

The pe_patch module uses OS level tools or APIs to find patches for nodes. You still have to manage the configuration of your package manager, like YUM, APT, Zypper, WSUS, or Windows Update, so your nodes can search for updates. For example, if you need to go through a proxy and you use YUM, you must configure this on your own.

Patching involves two distinct steps. First, a cron job scans for new patches and uploads related details to PuppetDB as part of the pe_patch fact. You can specify when to run the cron job with parameters in the pe_patch class. Then, patches are applied to specified nodes using the pe_patch::patch_server task or the pe_patch::group_patching plan.
Note: If you need to restrict which packages/patches your OS finds and which patches are applied:
  • For *nix agents patching: Pin a package using yum versionlock, apt-mark, or zypper addlock. The pinned_packages field in the pe_patch fact refers to versions locked using these methods. This is different from apt-pinning packages, which is used to prioritize packages rather than locking them at a specific version.
  • For Windows agents patching: If you use WSUS or Windows Update to deliver updates, use WSUS to approve desired updates independently.

Security updates

To find security updates, the pe_patch module uses security metadata when it is available. For example, Red Hat provides security metadata as additional metadata in YUM, Debian performs checks on the repo the updates are coming from, and Windows provides this information by default.

In the console, on the Patches page, security metadata feeds into the Apply patches table where you can filter for Security updates only.

Configure Windows Update

If you are using Windows Update, we recommend you use the puppetlabs/wsus_client module and configure these parameters in the wsus_client class.
  • Set the server_url parameter to the URL of your WSUS server.
  • Set the auto_update_options parameter to AutoNotify to automatically download updates and notify users.

Create a node group for nodes under patch management

Create a node group for nodes you want to patch in Puppet Enterprise (PE) and add nodes to it. For example, create a node group for testing Windows and *nix patches prior to rolling out patches to other node groups. The PE Patch Management parent node group has the pe_patch class assigned to it and is in the console by default.

CAUTION: Adding PE infrastructure nodes to patch management node groups can cause service interruptions when certain patches are applied.
  1. In the console, click Node groups, and click Add group.
  2. Specify options for the new node group, then click Add.
    • Parent name: Select PE Patch Management.
    • Group name: Enter a name that describes the role of the node group, for example, patch test.
    • Environment: Select production.
    • Environment group: Do not select this option.
  3. Select the patching node group you created.
  4. On the Node group details page, on the Rules tab, add nodes to the group by either pinning them individually or adding a rule to automatically add nodes that meet your specifications.
    CAUTION: Do not include the same node in multiple node groups under patch management. This can cause classification conflicts.
  5. Select Run > Puppet.
Results
PE can now manage patches for the nodes in your new node group. Repeat these steps to add any additional node groups you want under patch management.

Specify patching parameters

Set parameters for node groups under patch management by first applying the pe_patch class to them, then specifying your desired parameters.

Before you begin
Create at least one node group under patch management.
  1. On the Node groups page, select the patching node group you want to add parameters to.
  2. If it doesn't already exist, add the pe_patch class to the node group.
    1. On the Classes tab, enter pe_patch and select Add class.
    2. Commit changes.
  3. In the pe_patch class, add the patch_group parameter and specify a value that describes the nodes in this node group.
    Tip: The patch_group parameter is used to identify which nodes to run patching plans against. You might specify patch_group names that match your node groups, or apply the same patch_group parameter across several patching node groups that have similar characteristics.
  4. Specify any additional patching parameters in the pe_patch class.
  5. Commit changes.
What to do next
Run Puppet on nodes in the node group before running patching tasks or plans.

Assign a patch management blackout window

Apply a blackout window to prevent PE from applying patches to nodes for a specified duration of time. For example, limit applying patches during an end-of-year change freeze.

Before you begin
Assign the pe_patch class to the applicable node group. See Specify patching parameters for more information.

  1. On the Node groups page, select the patching node group you want to assign a blackout window to.
  2. On the Classes tab, under Parameter, add the blackout_windows parameter to the pe_patch class.
  3. In the Value field, enter your blackout window as a JSON hash of keys and an ISO compliant timestamp.
    For example, an end of year blackout window from the beginning of the day on 15 December 2020 to the end of the day on 15 January 2021 looks like this:
    {
  "End of year change freeze": {
     "start": "2020-12-15T00:00:00+10:00",
     "end": "2021-01-15T23:59:59+10:00"
  }
}
  4. Commit changes.
Results
When a user tries to patch nodes during the blackout window, the Patch blocked field on the Apply patches table changes from No to Yes for affected patches. If the user proceeds with patching, the patching task fails.

Patch management parameters

Configure and tune patch management by adjusting parameters in the pe_patch class.

patch_data_owner
User name for the owner of the patch data. String.
Default: root
patch_data_group
Group name for the owner of the patch data. String.
Default: root
patch_cron_user
User account for running the cron job that scans for new patches in the background. String.
Default: $patch_data_owner
manage_yum_utils
Determines if the yum_utils package should be managed by this module on RedHat family nodes. If true, use the yum_utils parameter to determine how it should be managed. Boolean.
Default: false
yum_utils
If managed, determines what the package is set to. Enum[installed, absent, purged, held, latest]
Default: installed
block_patching_on_warnings
Determines if the patching task should run if there were warnings present on the pe_patch fact. If true, the run will abort and take no action. If false, the run will continue and attempt to patch. Boolean.
Default: false
fact_upload
Determines if puppet fact upload runs after any changes are made to the fact cache files. Boolean.
Default: true
apt_autoremove
Determines if apt-get autoremove runs during reboot. Boolean.
Default: false
manage_delta_rpm
Determines if the delta_rpm package should be managed by this module on RedHat family nodes. If true, use the delta_rpm parameter to determine how it should be managed. Boolean.
Default: false
delta_rpm
If managed, determines what the delta_rpm package is set to. Enum[installed, absent, purged, held, latest]
Default: installed
manage_yum_plugin_security
Determines if the yum_plugin_security package should be managed by this module on RedHat family nodes. If true, use the yum_plugin_security parameter to determine how it should be managed. Boolean.
Default: false
yum_plugin_security
If managed, determines what the yum_plugin_security package is set to. Enum[installed, absent, purged, held, latest]
Default: installed
reboot_override
Determines if a node reboots after patching. This overrides the setting in the task. Variant, Boolean, Enum[always, never, patched, smart, default]
  • always - The node always reboots during the task run, even if no patches are required.
  • never (or false) - The node never reboots during the task run, even if patches are applied.
  • patched (or true) - The node reboots if patches are applied.
  • smart - Use the OS supplied tools, like needs_restarting on RHEL or a pending reboot check on Windows, to determine if a reboot is required, if it is reboots, or if it does not reboot.
  • default - Uses whatever option is set in the reboot parameter for the pe_patch::patch_server task.
Default: default
patch_group
Identifies nodes in or across patching node groups to run patching plans against.
Default: undef
pre_patching_scriptpath
The full path to an executable script or binary on the target node to be run before patching.
Default: undef
post_patching_scriptpath
The full path to an executable script or binary on the target node to be run after patching.
Default: undef
patch_cron_hour
The hour or hours to run the cron job that scans for new patches.
Default: absent, or *
patch_cron_month
The month or months to run the cron job that scans for new patches.
Default: absent, or *
patch_cron_monthday
The monthday or monthdays to run the cron job that scans for new patches.
Default: absent, or *
patch_cron_weekday
The weekday or weekdays to run the cron job that scans for new patches.
Default: absent, or *
patch_cron_min
The min or mins to run the cron job that scans for new patches.
Default: fqdn_rand(59) - a random number between 0 and 59.
ensure
Use present to install scripts, cronjobs, files, etc. Use absent to clean up system that previously hosted.
Default: present
blackout_windows
Determines a window of time when nodes cannot be patched. Hash.
:title - Name of the blackout window. String.
:start- Start of the blackout window (ISO8601 format). String.
:end - End of the blackout window (ISO8601 format). String.
Default: undef
windows_update_criteria
Determines which types of updates Windows Update searches for. To search both software and driver updates, remove the Type argument. String.
Default: IsInstalled=0 and IsHidden=0 and Type='Software'
Note: See the Microsoft documentation for more information about formatting strings for Windows Update.

Disable patch management

Use the console to disable patch management by editing the ensure parameter in the PE Patch Management node group. You can also remove patch management by deleting patching node groups.

  1. In the console, click Node groups and select the PE Patch Management node group.
  2. On the Classes tab, under the pe_patch class, select the ensure parameter,and change the value to absent.
  3. Click Add to node group and commit the change.
  4. Run Puppet.
    The client components of the pe_patch class, like cron and scripts, are removed from PE.
  5. Optional: To remove patch management from your infrastructure, click Remove node group on the Node details page for the PE Patch Management node group.
    Note: If you have any child node groups under patch management, you must remove those node groups prior to removing the PE Patch Management parent node group.
Results
The Patch Management section in the console sidebar remains active after disabling patch management, but the Patches page no longer reports patch information.