Jenkins: Configuring a Linux Slave Node

Most Jenkins instances start out by using only a single build node. Many teams will quickly outgrow this limit for any number of reasons, such as:

  • Increasing build throughput due to long build times
  • Increasing the number of concurrent builds that can run
  • Building and testing software on multiple architectures (e.g. x86, ARM)
  • Building and testing software for multiple OSes (Windows, Linux, OSX)
  • Creating a dedicated node which can run tests on hardware

The steps below describe the configuration process for bringing up new Linux-based nodes for use with the Jenkins build server. These steps assume that Linux is already installed on your machine.

  1. Install Dependencies
  2. Enable SSH
  3. Create new SSH Keys
  4. Add SSH Keys to GitHub
  5. Authorize Jenkins Master SSH Connections
  6. Assign a Static IP Address
  7. Create a Jenkins Directory
  8. Configuring the Node in Jenkins

Install Dependencies

In order to use your node as a Jenkins slave, you will need to install the following initial dependencies:

sudo apt-get install default-jre git

If your project requires additional dependencies, install them as well.

Enable SSH

My preferred method for connecting Jenkins to slave nodes is SSH.

With most new Linux installations, SSH is not enabled by default. You will need to install the openssh-server package:

sudo apt-get install openssh-server

Please substitute with your particular package manager if you are not using apt-get.

Create New SSH keys

Generate an SSH key for your build node:

ssh-keygen -t rsa -b 4096 -C "node-name"

You can specify a password, but note it down for later reference. The password will be needed when adding the Jenkins SSH key credential.

Add SSH Keys to GitHub

If you're using GitHub, you want to add your machine's SSH key to the GitHub account used by your build server. By adding the SSH key to your GitHub account, the node will be able to check out your repositories.

For most server installs I use a standalone bot account that manages the Jenkins builds. I also like to use separate keys for each node to have more granular control over access: revoking one key won't take down all my build nodes.

Follow these steps to add your SSH key to GitHub:

Authorize Jenkins Master SSH Connections

You must add the SSH key for the jenkins user on the master node to the authorized_keys file. The Jenkins master node will use SSH to connect to the slave nodes.

You will need to copy the contents of the Jenkins master's public SSH key. Then, use the following commands to add the key to the authorized_keys file:

vi ~/.ssh/authorized_keys
(paste contents)

If authorized_keys has been created for the first time, be sure to set the appropriate permissions:

chmod 600 ~/.ssh/authorized_keys

Assign a Static IP Address

In order to ensure reliable use of our slave node, it needs to have a static IP address on the local network. The instructions for this vary greatly depending on your router, so you'll need to Google for those instructions.

In order to assign a static IP address, you will need to know the MAC address for the correct link. If your device is connected over Wi-Fi, use the Wi-Fi adapter's MAC. If it's connected over Ethernet, use the Ethernet MAC.

You can use the ifconfig command to print information about each network interface available on your machine. Look for the HWaddr entry (e.g. HWaddr AF:c6:92:10:da:2f) and use that address to assign your static IP address.

Keep the assigned IP address handy for the final configuration step.

Create a Jenkins Directory

Jenkins will need a workspace directory for executing the slave node processes and storing files.

Create a jenkins directory wherever you'd like - just make sure it is writable without sudo.


mkdir ~/jenkins

Keep this directory location handy for the next step.

Configuring the Node in Jenkins

To configure a new node, navigate to "Manage Jenkins" in the classic Jenkins interface or "Administration" in Blue Ocean. Select "Manage Nodes", then "New Node".

We want to configure a new "Permanent Agent", though you can also copy an existing slave job and replace the appropriate values.

Here are the settings to configure:

  • Number of executors: 1 or more
    • Select the number of concurrent jobs that should be allowed to run on this node
  • Remote root: Use the Jenkins workspace directory that you created
  • labels: Add any descriptive labels you want to use
    • Examples: linux, build-x, x86
  • Select Use this node as much as possible
  • Method: Launch slave agents via SSH
  • Host: Use the static ip address of your new slave node
  • Credentials: Select the Jenkins master private ssh key
  • Verification strategy: non-verifying
    • You are free to use more secure methods!
  • Select Keep this agent online as much as possible

If everything was configured correctly, the node can be brought online and Jenkins can start assigning jobs!

Further Reading