How to Setup Jenkins Master and Slave on Ubuntu

Jenkins is an automation server forked from the Hudson project. It has support for many SCM (Source Control Management) software systems including Git, SVN, and Mercurial. Jenkins provides hundreds of plugins to automate your project. Jenkins offers support for a master/slave' architecture, allowing it to host a large number of project builds.

How Jenkins 'master/slave' works?

Jenkins master/slave architecture is used for distributed build environments, where the workload of building projects is distributed to multiple agent nodes, and we can use different environments for each build.

In the Jenkins 'master/slave' architecture, a master represents itself as a basic Jenkins installation and handles all tasks for the build system. The Jenkins master node will be used for scheduling jobs, monitoring slave nodes, dispatching builds to slave nodes, record and representing the build result, and execute build jobs directly.

The Jenkins slave nodes set up for offload build projects from the master, and it's required an established connection between the master and slaves. Jenkins slave nodes can run on various operating systems like Windows and Linux, and there is no need to install full Jenkins packages on it.

This tutorial will teach us how to set up Jenkins master-slave architecture using the latest Ubuntu version. We will learn to set up the Jenkins master server and add other Ubuntu nodes as Jenkins slaves.


  • Ubuntu Server (Ubuntu 22.04 - Ubuntu 16.04)
    • master -
    • slave01 -
    • slave02 -
  • Root privileges

What we will do?

  1. Install Jenkins Master
  2. Configure Jenkins Master Credentials
  3. Configure Slave Agent Nodes
  4. Add New Slave Nodes
  5. Prepare Slave Agent Nodes to Execute Build
  6. Testing

Step 1 - Install Jenkins Master

In this tutorial, we will not cover the basic Jenkins installation. Several articles on HowtoForge cover the Jenkins installation.

Following is our Ubuntu master server with Jenkins installed on it.

Install Jenkins Master

Step 2 - Configure Jenkins Master Credentials

When you get the master server Jenkins installed, we need to configure the master server itself. By default, there are different ways to start Jenkins agent nodes, we can launch the agent nodes through SSH, a windows administrative account, and via Java Web Start (JNLP), pick the best way depending on your environment setup and operating system.

For this guide, we will launch the agent nodes through ssh, and we need to set up Jenkins credentials on our master server.

Generate SSH Key

We will be using the ssh key authentication to set up our agent nodes, so we need to generate the ssh key for the Jenkins user and then manually upload the key to each server node using 'ssh-copy-id'.

On the Jenkins master server, login to the Jenkins user and generate the ssh key.

su - jenkins

And you will get the 'id_rsa' private and '' public key in the '.ssh' directory.

Generate SSH Key

Setup Credentials on Jenkins

Open your Jenkins dashboard and click on the 'Credentials' menu on the left.

Setup Credentials on Jenkins

And click the 'global' domain link.

Now click 'Add Credentials'.

Add Credentials

Now choose the authentication method.

  • Kind: SSH Username with private key
  • Scope: Global
  • Username: jenkins
  • Private key: Enter directly and paste the 'id_rsa' private key of Jenkins user from the master server.

Click 'OK'.

choose the authentication method

And the Jenkins credential with ssh auth key method have been created.

Jenkins credential with ssh auth key method have been created

Step 3 - Set up Slave Nodes

Now we will set up the slave node servers by installing java on those servers and creating a new Jenkins user.

Install Java

Install the 'software-properties-common' packages and add the java PPA repository.

sudo apt install software-properties-common apt-transport-https -y
sudo add-apt-repository ppa:openjdk-r/ppa -y

Now install java OpenJDK using apt command below.

sudo apt install openjdk-8-jdk -y

After the installation is complete, check the installed java version.

java -version

And you will get Java OpenJDK 1.8 installed on the system.

Install Java

Add New Jenkins User

Now add the 'Jenkins' user to all agent nodes.

Run the command below.

useradd -m -s /bin/bash jenkins
passwd Jenkins

The 'Jenkins' user for agent nodes has been created.

Add New Jenkins User

Copy the SSH Key from Master to Slave

Next, we must upload the key '' from the master to slave server nodes. We need to upload to each server nodes using 'ssh-copy-id' command as below.

ssh-copy-id [email protected]
ssh-copy-id [email protected]

Type the Jenkins user password.

The ssh key '' has been uploaded to all agent nodes.

Copy the SSH Key from Master to Slave

Step 4 - Add New Slave Nodes

On the Jenkins dashboard, click the 'Manage Jenkins' menu, and click 'Manage Nodes'.

Add New Slave Nodes

Click the 'New Node'.

New Node

Type the node name 'slave01', choose the 'permanent agent', and click 'OK'.

node name

Now type node information details.

  • Description: slave01 node agent server
  • Remote root directory: /home/jenkins
  • Labels: slave01
  • Launch method: Launch slave agent via SSH, type the host ip address '', choose the authentication using 'Jenkins' credential.

node information

Now click 'Save' button and wait for the master server to connect to all agent nodes and launch the agent services.

Below are the results when the master server is connected to all agent nodes.

master server is connected to all agent nodes

Jenkins slave nodes has been added to the master server.

Step 5 - Prepare Slave Agent Nodes to Execute Build

In this step, we will configure the Jenkins master to execute build on the slave agent nodes.

Click on the 'Manage Jenkins' menu and then click 'Configure System'.

Prepare Slave Agent Nodes to Execute Build

Now go to the 'Slave Setups' section and define all you need as shown below.

the 'Slave Setups' section

More info about the 'Slave Setups' on link.

Click 'Save' button and now we're ready to execute build on slave agent nodes.

Step 6 - Testing

Now we want to create a new simple build for Jenkins and execute the build on the bot 'slave01' and 'slave02' agent nodes.

On the Jenkins dashboard, click the 'New Item' menu.

Testing Jenkins

Type the item name, choose the freestyle project, and click 'OK'.

Add Freestyle project

On the general section, type the job description and check the 'Restrict where this project can be run' option.

On the 'Label Expression', specify the node such as 'slave01'.

Select a node

Move to the build section and, choose the 'Execute shell' option, type the command as below.

top -b -n 1 | head -n 10 && hostname

Click the 'Save' button, and you will be redirected to the job page.

Job page

Click the 'Build Now' to build the project, and then click item on the 'Build History' section.

Build now

And the following is my result.

Build on the 'slave01' agent node.

Jenkins script result output

Build on the 'slave02' agent node.

Build on node 02

Installation and configuration of Jenkins master/slave architecture and the distributed builds Jenkins have been completed successfully.


Share this page:

9 Comment(s)

Add comment

Please register in our forum first to comment.


By: Joana at: 2018-10-23 14:34:03

Thank you very much for the tutorial, everything worked as expected!

By: Sunny at: 2018-10-27 16:44:39

I'm getting this error - even tho I can ssh from master to slave. Any suggestions:

This agent is offline because Jenkins failed to launch the agent process on it. See log for more details


By: Rohan at: 2019-01-25 04:07:22

Awesome Article with step by step explanation to install Jenkins

By: Gerard at: 2019-04-26 13:35:01

In "useradd -m -s /bin/bash Jenkins" the username has a capital "J" .. Shouldn't this be a "j" ? 

By: till at: 2019-04-26 13:38:08

Yes, should be lowercase as shown in the screenshot. I've corrected the tutorial text.

By: medhun at: 2019-05-03 10:19:03

Can anyone pls help me on the below one?

ssh-copy-id [email protected]

/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/var/lib/jenkins/.ssh/"

/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed


/usr/bin/ssh-copy-id: ERROR: ssh: connect to host private-ip-slave-agent port 22: Connection timed out


By: gopi at: 2019-10-14 00:41:43


can we create a Linux local machine as a slave to aws ec2 Master Jenkins ? if yes please guide me how to do it or share me the links if you have. Thank you

By: Matt Corr at: 2019-10-19 12:28:35

Thanks very much for this article! Very helpful and it all worked :)

By: Johnny at: 2022-02-23 16:00:37

Thank you, and good instructions!! I successfully deployed one jenkins slave server and the job built on the slave.