Upgrade notes

Before upgrading a Rudder server, you should make a backup by following the backup procedure.

Plugins disabled during upgrade

Each time Rudder is upgraded, plugins are disabled. You need to enable them back after upgrade.

For that, start by checking if update are available for you new version (it will be mandatory for a minor or major version upgrade) and enable them back.

If you have a subscription, it can done directly with the following commands:

rudder package update
rudder package upgrade-all
rudder package plugin enable-all

Without a subscription, proceed as you usually do get the latest plugin package, and install it from file:

rudder package install-file /path/to/plugin.rpkg

You can also check for the state of all plugins:

rudder package list --all

And enable only a chosen one, for example for scale-out relay plugin:

rudder package enable rudder-plugin-scale-out-relay

More information about rudder package command is available with rudder package --help.

Upgrade from Rudder 6.0

There is not default user anymore, you need to create a user after installation with rudder server create-user -u USERNAME, and provide a secure password.

This prevents having a time frame after installation where the server is accessible from anyone, and avoids Rudder servers left with open access.

Rudder now provides bcrypt as hash type for local user passwords. It is the default for new server, but upgraded servers will continue to use existing hashes.

It is advised to use bcrypt. To do so, you need to reset existing passwords and compute new hashes, see user management documentation for more details.

Upgrade from Rudder 6.0 is supported.

Upgrade from Rudder 5.0 (>= 5.0.16)

Upgrade from Rudder 5.0 if >= 5.0.16 is supported.

There is not default user anymore, you need to create a user after installation with rudder server create-user -u USERNAME, and provide a secure password.

This prevents having a time frame after installation where the server is accessible from anyone, and avoids Rudder servers left with open access.

Rudder now provides bcrypt as hash type for local user passwords. It is the default for new server, but upgraded servers will continue to use existing hashes.

It is advised to use bcrypt. To do so, you need to reset existing passwords and compute new hashes, see user management documentation for more details.

Rudder 6 comes with a new reporting protocol using HTTPS instead of syslog. It is enabled by default on new installations, but upgraded instances will stay on the syslog protocol for compatibility.

You can switch between reporting protocols at any time. You have three reporting options:

  • syslog: default on upgrades, same as before 6.0.

  • HTTPS with syslog compatibility: keeps compatibility with pre-6.0 agents by using HTTPS reporting for 6.0 agents but still allowing syslog reporting

  • HTTPS: default for new installs, switches to HTTPS only, and disables syslog report forwarding, removing all Rudder-specific log configuration from nodes and servers. This should only be done once all agents are upgraded to 6.0. This allows enforcing report signature and transport through HTTPS.

You can read more about reporting in the dedicated section.

The Rudder packages ncf, ncf-api-virtualenv, rudder-inventory-endpoint, rudder-inventory-ldap, rudder-jetty and rudder-techniques have been merged into rudder-webapp. This means that on a server upgrade from Rudder 5.0 those packages will all be removed.

This is normal!

The technique tools folder (in /var/rudder/tools), that was previously used to synchronize tools used by the system techniques is not used anymore. All tools have been migrated into the technique that used them.

The folder is left in place, but not automatically shared anymore.

If you relied on the tools copy mechanism to share files, you can replace it by a standard recursive copy from the shared files.

Rudder generic method condition from command will change its behaviour in audit policy mode starting 6.0.

Before the 6.0 Rudder version, when in audit policy mode, the method was not executing the command passed in parameters and would always report an error.

In order to limit the compliance drift when switching policy mode we chose to make the method behave in the exact same way in audit mode than in enforce mode because:

  • Audit and enforce policy mode should do the same check on the node, and differ on the remediation part

  • The method is mainly used to bypass missing components in the current generic methods library and so, not applying it in audit restrain Rudder from complex use cases

  • The command passed as parameter should always be system impact free, and so, it can be executed without impacting the overall configuration state of the node

Rudder 5.0.9 changes the default log level for the configuration server in Rudder.

This allows easier debugging and tracability of policy updates, so we enabled it by default, but will produce more logs. If you want to revert to the previous behavior (which only logs errors):

  • On systemd systems

    • Create a /etc/systemd/system/rudder-cf-serverd.service.d/override.conf file containing:

[Service]
Environment=VERBOSITY_OPTION=

  • Run systemctl daemon-reload then systemctl restart rudder-cf-serverd

    • On systems using the init script

  • Edit the /etc/default/rudder-agent file:

# You need to uncomment and let empty
CFENGINE_COMMUNITY_PARAMS_1=""

  • Restart the service with service rudder-agent restart

Verbosity options can be:

  • empty for only errors

  • --inform for basic messages

  • --verbose for very detailed logs

  • --debug for unreasonnably detailed logs

The executable /opt/rudder/bin/rudder-pkg can now be used with the command rudder package, and can now list, search and install plugins and their licenses directly from a repository.

Rudder 6.1 comes with a new hash function: Bcrypt which allows safer password storage. To switch from a previous hash function (SHA1, SHA256, SH512, MD5) to BCrypt you should change the hash parameter in /opt/rudder/etc/rudder-users.xml to bcrypt and update all password. To update all passwords you have two ways to proceed:

  • You can do it manually in the same file by using this command in a terminal to generate a new hash:

htpasswd -nBC 12 "" | tr -d ':\n' | sed 's/$2y/$2b/'

  • Directly from the User Management plugin (you should at least update the administrator’s password manually to log in the first time) and use the interface to update all password.

Upgrading from versions older 5.0.16 leads to problems when removing rudder-jetty package causing the upgrade command to fail and leave rudder-jetty package in a non functional state.

However your Rudder 6.0 should be working, but we recommend to upgrade at least to 5.0.16 before upgrading to 6.0.

Upgrading to versions before 6.0.3 leads to several errors (service not started, ldap conf not updated to new format …​), all these bugs are fixed in 6.0.3 and you consider upgrading at least to 6.0.3.

Upgrading to 6.0.3 disables all plugins you may have installed because compatibility of previous 6.0 plugins are not compatible with 6.0.3, please reinstall your plugins to their latest versions.

Upgrade from Rudder 5.0 (< 5.0.16), 4.3 or older

Direct upgrades from 5.0 versions older than 5.0.16, 4.3.x and older are no longer supported on 6.2. If you are still running one of those, either on servers or nodes, please first upgrade to one of the supported versions, and then upgrade to 6.2.

Compatibility between Rudder components

In the tables below:

  • a + sign means any newer versions

  • a - is used to define a range

Table 1. Compatibility table
Server Relay Linux agent Windows agent

6.1

6.0+

5.0+

5.0-6.2

6.2

6.0+

5.0+

6.0+

7.0

6.0+

5.0+

6.2+
Table 2. Compatibility table (with deprecated versions)
Server Relay Linux agent Windows agent

5.0.1-5.0.16

5.0-6.0

5.0-6.0

5.0-6.0

5.0.17

5.0-6.1

5.0-6.1

5.0-6.1

6.1

6.0+

5.0+

5.0-6.2

6.2

6.0+

5.0+

6.0+

7.0

6.0+

5.0+

6.2+

← on SLES on Debian/Ubuntu →