Install Rudder relay on Debian or Ubuntu

Relay servers won’t work if you don’t have a valid scale-out-relay plugin installed.

If you install a relay without that plugin, policy generation will fail, preventing new policies to be applied to your Nodes.

More information about plugins in the dedicated section

Installation

Each official package is signed with our GPG signature. To ensure the packages you will install are official builds and have not been altered, import our key into apt using the following command:

wget --quiet -O /etc/apt/trusted.gpg.d/rudder_apt_key.gpg "https://repository.rudder.io/apt/rudder_apt_key.gpg"

Our key fingerprint is:

pub  4096R/474A19E8 2011-12-15 Rudder Project (release key) <security@rudder-project.org>
      Key fingerprint = 7C16 9817 7904 212D D58C  B4D1 9322 C330 474A 19E8

On ancient versions (before Debian 7 and before Ubuntu 10.04), you need to use the apt-key tool instead:

wget --quiet -O- "https://repository.rudder.io/rpm/rudder_rpm_key.pub" | sudo apt-key add -

Add Rudder’s package repository:

# If lsb_release is not installed on your machine, change $(lb_release -cs) by your distribution codename.
# Ex:
#   stretch for Debian 9
#   bionic  for Ubuntu 18.04 LTS

echo "deb [arch=$(dpkg --print-architecture)] http://repository.rudder.io/apt/8.2/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/rudder.list

If you have an active subscription, use the following to get access to long term support. You need to replace the username (LOGIN) and the password (PASSWORD) by your Rudder account:

echo "deb [arch=$(dpkg --print-architecture)] https://download.rudder.io/apt/8.2/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/rudder.list

# for recent debian (>=10) and ubuntu (>=20)
echo 'machine download.rudder.io login LOGIN password PASSWORD' > /etc/apt/auth.conf.d/rudder.conf
chmod 640 /etc/apt/auth.conf.d/rudder.conf

# on old debian (<10) and ubuntu (<20) use this instead
#echo 'machine download.rudder.io login LOGIN password PASSWORD' >> /etc/apt/auth.conf
#chmod 640 /etc/apt/auth.conf

Update your local package database to retrieve the list of packages available in our repository:

apt-get update

Install the package:

apt-get install rudder-relay

To complete this step, please make sure that your node is configured successfully and appears in your Rudder web interface.

On Rudder server

You have to tell the Rudder server that a node will be a relay. To do so, launch the rudder-node-to-relay script on the server, supplying the UUID of the host to be considered as a relay. You can find the UUID of your node with the rudder agent info command.

rudder server node-to-relay <aaaaaaaa-bbbb-cccc-dddd-eeeeeeee>

Validation

When every step has completed successfully:

  • The Rudder server will recognize the new node as a relay

  • It will generate specific policies for the relay

  • The relay will update and switch to its new role

You may have to run rudder agent run command on the relay, before adding new nodes under this relay.

This is an example of node details pane showing a Rudder relay. Note the "Role: Rudder relay" part that shows that the machine has successfully changed from a node to a relay.

Relay
Figure 1. Rudder relay node

Adding nodes to a relay

When you have at least one relay, you will likely want to add nodes on it.

You then have two possible cases:

  • You want to switch an already existing node to the relay

  • You want to add a new one

The procedure on both cases is the same, you have to:

  • Update the policy server with the IP address or the fully qualified domain name of the relay (instead of Rudder server) and reset pinned public key

rudder agent policy-server <rudder relay ip or hostname>
rudder agent server-keys-reset

  • Trigger an inventory immediately to make sure the node is registered correctly

rudder agent inventory

After those steps, the node should be registered correctly on your Rudder infrastructure.


← on AIX on RHEL/CentOS →