System updates

Rudder "System updates" plugin allows to check and ensure nodes have the latest packages available installed. It is part of Rudder’s patch management features.

Specific rights and roles

This plugin enables new rights that can be used in your custom roles from user-management plugin.

  • system_update_read: allows to access campaigns and available updates pages in read-only

  • system_update_write: no additional permissions (reserved for latter usage).

  • system_update_campaign_read: access to campaign page in read-only

  • system_update_campaign_write: same, but in edit mode.

You can add any of these permissions by appending it in the list of permissions of a user:

<user name="alice" password="..." permissions="...other permissions...,system_update_campaign_read"/>

It also creates a new plugin role with all the four previous permissions enabled: system_update.

You can add that role and grant all system update permissions in the same way than previously:

<user name="alice" password="..." permissions="...other permissions...,system_update"/>

List available updates

The list of available updates is visible in the dedicated System updates page in the Patch management menu category. The information is available for all nodes with a supported OS and kept up to date automatically.

There are two entry-points for exploring updates, by node or by update.

By node

by node

By update

by update


You can access all the information about available updates through the usual nodes API.


Where does the information come from?

The Rudder agents on the systems will collect the list of available updates on the node during each inventory (by default, daily between 0-6 a.m.)

If you want to update the list of installed package or available updates you can trigger an inventory, either with the rudder agent inventory command or in the policies with the Inventory trigger generic method in the technique editor.

This list comes directly from what the node sees, and hence depends on configured repositories on the system. It allows following your existing repository management workflows, whether your nodes are directly plugged to upstream repositories or you’re using frozen snapshots to handle patch levels. The level of details available depends on what the package manager provides.

The available updates refresh (apt update or equivalent) is done automatically by the agent, by default every 4 hours (on OSes where it is not automatically done).


Apply updates

Besides listing available updates, Rudder allows you to actually apply them at scale, with its usual focus on ease of use and centralized reporting. This is done by configuring campaigns, which define an update policy for a set of nodes.

The update campaigns are visible in the dedicated Update campaigns page in the Patch management menu category. They allow scheduling full or targeted upgrades on your systems, and visualizing the results. Each campaign gets centralized reporting, with for each node, updated packages list and console output of the system update for easy troubleshooting.

Campaigns can be either one-shot events, or define a pattern of recurring events. A campaign event running on a node:

  • Schedules an execution date between its schedule start and end date

  • When the execution date is reached, the agent will:

    • Run the pre-update hooks (see below)

    • Run a system update using:

      • the default package manager on Linux nodes

      • the Windows Update client on Windows nodes

  • Reboot the node or services if needed/asked for

  • Run the post-update hooks (see below)

  • Send all the reports to the Rudder server

A system update campaign will update a node even if that node is configured in audit mode.

Define a campaign

All campaigns standard configuration consists of:

  • A campaign name

  • A description

  • A reboot/restart strategy: Configure if you want to reboot the system after an upgrade. It can also be set to only reboot if necessary or to only restart updated services (for OSes that support it).

  • An execution schedule: Can be recurring (by month or week) or one shot. You will be able to define a time slot during which the updates will take place. The upgrade on the systems will be automatically spread over the configured time windows.

  • A list of targets: Groups of nodes on which the campaign will be applied

There are two types of campaigns:

  • Full system update, called system update. They apply all available upgrades on the system.

  • Targeted system update, called software update. They apply a predefined list of target upgrades.

    • The list of upgrades to apply is configured in a Software tab in the campaign edition page. This flags a list of software upgrades as applicable if available on the target systems.

Target software updates are only available on Windows with Rudder 8.0+.

Manage update events

Each campaign produces one or more event(s). Each defined event has one of these states:

  • planned: the next scheduled tasks

  • running: this update is currently running

  • skipped: this event has been canceled, but the campaign is still defined


Explore upgrade results

Campaigns keep history of events, you can keep track of which updates have succeeded or failed, along with the full output of the package manager for each node.

The results are also available through the [REST API]( which, for example, allows creating custom update reports.

If you delete a campaign, its history will also be deleted.



For now, hooks are only available on Linux systems.

Campaigns include a mechanism to plug actions before or after the upgrade. This covers a wide variety of needs:

  • Run "pre-flight" check: available disk space check, backup check, etc. It allows stopping the update process if the system is not ready.

  • Run pre-update actions: take a VM snapshot of the system, etc.

  • Run pre-reboot "pre-fliht" checks, after the update has taken place

  • Run post-update actions: update a CMDB, notify the user, etc.

In order to allow a wide range of actions, these hooks can actually be any executable file on the system (shell/Powershell script, Python script, etc.)

The hooks are not configured in the Web interface, but need to be deployed in a pre-defined path. You can use a normal Rudder policy to deploy your hook scripts on your systems.

The used folders are:

  • Pre-upgrade: runs just before the upgrade

    • /var/rudder/system-update/hooks.d/pre-upgrade

    • If one of these scripts fails, the upgrade process is interrupted. This also skips the service restart or reboot regardless of the configuration.

  • Pre-reboot: runs just after upgrade and before reboot, only if a reboot is necessary

    • /var/rudder/system-update/hooks.d/pre-reboot

    • If one of these scripts fails, the remaining hooks won’t run, and the reboot will not happen.

    • As they happen after service restart or reboot, they have no impact on them.

  • Post-upgrade: runs after upgrade and reboot, just before reporting is made

    • /var/rudder/system-update/hooks.d/post-upgrade

    • If one of these scripts fails, the remaining hooks won’t run, but the reporting is made normally afterwards.

    • They run either directly at the end of the upgrade process if no reboot is necessary, or at next agent run after reboot if applicable.

Only executable files owned by root (and not writable by others) are run. Files are run in lexicographical order, so we recommend adopting a numeric prefix for the file (i.e.

The hooks are run as administrator user (root on Linux), without parameters, and their output is captured and added to the output logs available in the Web interface.

If you want a particular step to be faillible and not interrupt the process, you need to take care of error handling in your script.

← Secret Management User management →