Upgrade notes

Upgrade from a previous Rudder 5.0

Migration from any 5.0 minor version is supported (see below for migration from older versions).

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

Upgrade from Rudder 4.1, 4.2 or 4.3

Migration from 4.1, 4.2 or 4.3 are supported, so you can upgrade directly to 5.0.

Upgrading from 4.1.18 or earlier can cause transient missing /opt/rudder/etc/uuid.hive - as this file is no longer part of the packaging. The issue will resolve itself, and happen only once - any subsequent upgrade will not exhibit this problem anymore.

If you don’t want to wait up to 5 minutes for this issue to correct itself, you can run:

rudder agent check

that will restore the file from backup.

The following features are now provided as plugins and no more available as part of default Rudder installation starting from 5.0:

  • LDAP-based authentication

  • Relay servers

  • Changes validation workflow (change requests)

If you were using them, upgrade will disable them and you will have to install the plugin. Read the plugins page on our website for more information.

On RHEL/centOS and SLES systems, when upgrading from a 4.1 older than 4.1.13, a 4.2 older than 4.2.7 or a 4.3 older than 4.3.3, it is necessary to explicitely upgrade rudder-agent (in the same command as the other packages) when upgrading a relay or a root server, because of a dependency misconfiguration in the agent package.

This has been fixed in the packages, but the problem is caused by the package in the version your are upgrading from.

During migration from Rudder 4.x to 5.0, you may encounter an OpenSSL bug resulting in a connection error between nodes and policy server. Problematic Linux distibutions are (but may not be limited to): RHEL 6 (any version), RHEL 7.3 and older, SLES 12SP3 or older, Debian 8 or older, Ubuntu 14 or older.

Diagnosis:

Rudder agent can’t communicate with Rudder server, and rudder agent update -i display an SSL error looking like:

Peeked nothing important in TCP stream, considering the protocol as TLS error: Failed to accept TLS connection: (-1 SSL_ERROR_SSL) illegal zero content

Cause:

The problem, traced in that ticket for Rudder, is due to a bug in OpenSSL for version 1.1.1 and up which are only compatible with OpenSSL 1.0.2 and up. Yet Rudder 4.1, 4.2 or 4.3 use OpenSSL provided by the system and some Linux distributions supported by these versions of Rudder only provide flavors of OpenSSL 1.0.1.

Solution:

As far as we know, there is three solutions available to migrate Rudder servers and agent from 4.x to 5.0 and avoid the communication problem:

  • the simplest solution is to contact Rudder support which can provide a specially compiled version of Rudder policy server with OpenSSL 1.0.2 for use during the migration. Once the migration is done, the common Rudder policy server component can be reinstalled to ensure using the last version of OpenSSL. Rudder support can also provide compatible scale out relays to segment your migration.

  • the second solution, if available on your system, is to update OpenSSL to version 1.0.2 or newer on Rudder server version 4.x and then migrate agents to Rudder 5.0. Once all agents are migrated to 5.0, you can safelly migrate Rudder server to that version. Alternatively, you can update OpenSSL version to 1.0.2 or higher on nodes with Rudder 4.3 and migrate Rudder server to 5.0.

  • the last solution is to migrate the whole system (Rudder server and nodes) to Rudder 5.0 in one go. In that case, know that once you migrate the server, nodes won’t be able to update their policies anymore. If you want to migrate Rudder on nodes with a Rudder policy, be sure to do it before upgrading Rudder server.

We are sorry for any inconvenience resulting from this problem. If you need more information or help, please don’t hesitate to contact us by email or other means of communication like chat or irc (#rudder on freenode).

If your Rudder server was upgraded from a 4.1 or older installation on Ubuntu 12.04 LTS or 14.04 LTS, you may still be using port 5514 for syslog communication with nodes.

It not necessary anymore, you can switch back to the default by changing the port in the rudder.syslog.port line in /opt/rudder/etc/rudder-web.properties to 514.

Upgrade from Rudder 4.0 or older

Direct upgrades from 4.0.x and older are no longer supported on 5.0. 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 5.0.

Compatibility between Rudder agent 5.0 and older server versions

4.1, 4.2 and 4.3 servers

Rudder agents 5.0 are compatible with 4.1, 4.2 and 4.3 Rudder servers.

Older servers

Rudder agents 5.0 are not compatible with Rudder servers older than 4.1. You need to upgrade your server to a compatible version before the agents.

Compatibility between Rudder server 5.0 and older agent versions

4.1, 4.2 and 4.3 agents

Rudder agent 4.1, 4.2 and 4.3 are fully compatible with Rudder server 5.0. It is therefore not strictly necessary to update all your agents to 5.0.

Older agents

These agents are not compatible with Rudder 5.0, and you have to upgrade them. Be careful to follow the upgrade path explained above.


← on SLES on Debian/Ubuntu →