HHOW TO GUIDES

How to Setup Jenkins Agent Using SSH [Password & SSH Key]

Jenkins SSH slave setup

In this beginner’s guide, we will walk you through the steps to set up Jenkins agent nodes using SSH (Password and SSH key-based authentication).

One of the best features of Jenkins is its distributed nature. You can configure multiple build slaves for better segregation and scalability.

For example, you might want to test a cross-platform code base with a different operating system. In this case, you can set up different Jenkins agents or slaves and run the job against them.

Also, a Jenkins distributed architecture will reduce the load on the master server.

Setup Jenkins Agents/Slaves on Jenkins

In this guide, I will walk you through the steps for setting up the Jenkins agent node using password and SSH keys.

There are two ways of authentication for setting up the Linux Jenkins slave agents.

  1. Using username and password
  2. Using ssh keys.

Also, do check out my Jenkins Docker Based Agent. You can scale and manage your Jenkins agent using Docker containers.

Jenkins Agent Prerequisites

For Jenkins agent configuration, you need to have the following in the slave machines before adding it to the master.

  1. Java should be installed on your agent server.
  2. A valid Linux user account that can perform the required tasks on the agent server. (preferably a sudo user if your job requires elevated privileges)
  3. Git should be installed as most build job requires git-specific actions.

Let’s get started with the Jenkins agent node configuration.

Create a Jenkins User

It is recommended to execute all Jenkins jobs as a Jenkins user on the Jenkins agent nodes.

Note: I am using Ubuntu machine as a slave. The steps will be same for other Linux flavours as well

Step 1: Create a Jenkins user and a password using the following command.

sudo adduser jenkins --gecos ""

Type a password when prompted. The above commands should create a user and a home directory named Jenkins under “/home”.

Step 2: Now, log in as a Jenkins user.

su jenkins

Step 3: Create a “jenkins-agent” directory under /home/jenkins.

mkdir /home/jenkins/jenkins-agent

Setting up Jenkins Agents/Slaves using username and password

Step 1: Head over to Jenkins dashboard –> Manage Jenkins –> Nodes

Jenkins Nodes Option

Step 2: Select the new node option.

Jenkins new node option

Step 3: Give it a name, select the “permanent agent” option and click Create.

Step 4: Enter the details as shown in the image below and save them.

For the credential box, click the add button and enter the agent server username and password. In our case, the username is jenkins and password is the one you created when you created the Jenkins user on the agent server. This credential will be used by the Jenkins controller to connect to the agent.

To know more about each option, click the question mark on the right side of each text box.

Jnekins Agent Node Configuration

Step 4: Once you click save, the controller will automatically connect to the agent server and configure it as an agent.

If the agent is not connected automatically,

By following the same steps, you can add multiple servers as Jenkins agent nodes.

Setting up Jenkins Agent Using SSH keys

Step 1: Log in to the slave server as a jenkins user.

Step 2: Create a .ssh directory and cd into the directory.

mkdir ~/.ssh && cd ~/.ssh

Step 3: Create an ssh key pair using the following command. Press enter for all the defaults when prompted.

ssh-keygen -t rsa -C "The access key for Jenkins slaves"

Step 4: Add the public to authorized_keys file using the following command.

cat id_rsa.pub >> ~/.ssh/authorized_keys

Step 5: Now, copy the contents of the private key to the clipboard.

cat id_rsa

Add the SSH Private Key to Jenkins Credentials

Step 1: Go to Jenkins dashboard –> credentials –> Global credentials –> add credentials, select and enter all the credentials as shown below and click ok.

Jenkins agent node ssh credentials

Connect SSH Jenkins Agent to Master Node

Step 1: Follow the first 3 steps we did for slave configuration using username and password.

Step 2: Follow all the configurations in the 4th step as well. But this time, for the launch method, select the credential you created with the SSH key.

Test Jenkins Agent/Slave Nodes

To test the Jenkins agent node or slave, create a sample project and select the option as shown below.

Jenkins job with agent node label.

You need to select the node using the label option. If you start to type the letter the node list will show up.

You can then run a simple, shell script operation to check if the Jenkins agent is executing the job.

Conclusion

In this tutorial, we learned how to set up slaves for Jenkins. There is no complex step involved in this configuration.

When it comes to automating the process, you will need scripts and Jenkins CLI to do this. I will cover that in future posts.

Share if you like it and leave a comment if you have queries!!

Bibin Wilson is a cloud and DevOps consultant with over 10 years of IT experience. He has extensive hands-on experience with public cloud platforms, cloud hosting, Kubernetes and OpenShift deployments in production. He has authored over 300 tech tutorials, providing valuable insights to the DevOps community. His courses on techiescamp.com offer practical guidance and real-world examples for professionals aiming to excel in cloud, DevOps, and infrastructure automation.

27 comments

  1. SSHLauncher{host=’18.118.185.134′, port=22, credentialsId=’9c2dd1ab-12cc-4068-b384-8e589f15468f’, jvmOptions=”, javaPath=”, prefixStartSlaveCmd=”, suffixStartSlaveCmd=”, launchTimeoutSeconds=60, maxNumRetries=10, retryWaitTime=15, sshHostKeyVerificationStrategy=hudson.plugins.sshslaves.verifiers.NonVerifyingKeyVerificationStrategy, tcpNoDelay=true, trackCredentials=true}
    [09/16/24 19:08:13] [SSH] Opening SSH connection to 18.118.185.134:22.
    [09/16/24 19:08:13] [SSH] WARNING: SSH Host Keys are not being verified. Man-in-the-middle attacks may be possible against this connection.
    [09/16/24 19:08:13] [SSH] Authentication failed.
    Authentication failed.
    [09/16/24 19:08:13] Launch failed – cleaning up connection
    [09/16/24 19:08:13] [SSH] Connection closed.

    Setting up Jenkins Agents/Slaves using username and password

    Reply

  4. May I create the private-public key on the master node and later update the credentials with the master´s private key? I think this approach is more correct as the master node is always going to reach the slave node.

    Reply

    1. You are correct peter. Ideally, we should not keep the Keys in the instances. Once the setup is done, it is better to remove the private key from the instance and save it some secret management utilities like Vault.

      Reply

  5. Hi Bibin
    Nice Blog, helped me a lot, can you plz help me with the below error, it was working fine and suddenly something happened and started to throw below error:

    "[03_Puppet_Master_RegReport_Multitenant_PM1] $ /bin/sh -xe /tmp/jenkins1776057542598539097.sh
+ cd /opt/app/cmrs/automation/cmrsautodevconfig
+ git pull
/tmp/jenkins1776057542598539097.sh: line 3: git: command not found
Build step 'Execute shell' marked build as failure
[BFA] Scanning build for known causes...
[BFA] No failure causes found
[BFA] Done. 0s
Finished: FAILURE"

    Not sure what went wrong suddenly, plz help me on this as i have spent more than 3 to fix this, as a workaround i have created some shell scripts to call thru jenkins using plink.

    Reply

    1. Hi Simran,

      Looks like Git is not installed.

      make sure you have git installed on the agent node.

      Reply

      1. Hi Bibin,
        thankyou for your swift response. Git is installed on agent node which is Linux server here, everything was working fine few hours ago but suddenly with all the same settings intact, this error started to appear.
        Git is installed at this location /usr/bin/git. When i manually run “git pull” on Linux machine, it works fine. But same throws this error when run via jenkins job.
        Please suggest what else can i do to fix this.

        Reply

          1. I have tried that, it says “There’s no such file: usr\bin\git” although i have added windows path for git “C:\Program Files\Git\bin\git.exe” as well (Since Jenkins is installed on windows server and target deployment machine is linux). This is also not working.
            Default path for git (git.exe) was already there under Global Tool Config.
            Earlier everything was working, nothing seems to have changed.
            Is there anything else i can try.

          2. Hi Simran,

            You have mentioned that it is a Linux server. So you need to add the Linux git path, not the windows git path with backward slashes. /usr/bin/git

  8. Just an aside, but it might be worth noting in your instructions that you must have Java also installed on the slave. I didn’t realise this, and it caught me!

    Reply

  9. Is possible just copy the Master’s public key to Slave simply by ‘ssh-copy-id’? You mentioned that create the ssh key on slave then copy the private key to master. Thanks

    Reply

  10. Nice blog !! Is there any way to configure the emails from the slave node? I meant , if I have jobs running in the slave node with editable email plugin. Whenever, I trigger the email it should be sending emails uopn slave email config but not Master.

    Reply

  11. I tried to connect via “Setting Up Slaves Using Ssh Keys” I got below error log and Node still offline. Do you have any idea for this ?

    [06/05/17 16:48:03] [SSH] Opening SSH connection to 191.11.11.111:22.
    Key exchange was not finished, connection is closed.
    java.io.IOException: There was a problem while connecting to 191.11.11.111:22
    at com.trilead.ssh2.Connection.connect(Connection.java:834)
    at com.trilead.ssh2.Connection.connect(Connection.java:703)
    at com.trilead.ssh2.Connection.connect(Connection.java:617)
    at hudson.plugins.sshslaves.SSHLauncher.openConnection(SSHLauncher.java:1265)
    at hudson.plugins.sshslaves.SSHLauncher$2.call(SSHLauncher.java:790)
    at hudson.plugins.sshslaves.SSHLauncher$2.call(SSHLauncher.java:785)
    at java.util.concurrent.FutureTask.run(FutureTask.java:266)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
    at java.lang.Thread.run(Thread.java:745)
    Caused by: java.io.IOException: Key exchange was not finished, connection is closed.
    at com.trilead.ssh2.transport.KexManager.getOrWaitForConnectionInfo(KexManager.java:95)
    at com.trilead.ssh2.transport.TransportManager.getConnectionInfo(TransportManager.java:237)
    at com.trilead.ssh2.Connection.connect(Connection.java:786)
    … 9 more
    Caused by: java.io.IOException: Cannot read full block, EOF reached.
    at com.trilead.ssh2.crypto.cipher.CipherInputStream.getBlock(CipherInputStream.java:81)
    at com.trilead.ssh2.crypto.cipher.CipherInputStream.read(CipherInputStream.java:108)
    at com.trilead.ssh2.transport.TransportConnection.receiveMessage(TransportConnection.java:232)
    at com.trilead.ssh2.transport.TransportManager.receiveLoop(TransportManager.java:706)
    at com.trilead.ssh2.transport.TransportManager$1.run(TransportManager.java:502)
    … 1 more
    [06/05/17 16:48:03] Launch failed – cleaning up connection
    [06/05/17 16:48:03] [SSH] Connection closed.

    Thanks

    Reply

  13. Hello,

    Do you have to have Jenkins installed on the slave servers for this connection via SSH to work? I tried without the Jenkins install on the slaves and it did not work. My guess is that it should work because this is a system connection problem and Jenkins really doesn’t assist in any kind of way with this process. You should just need it on the master.

    Reply

  14. Under execute shell i had given shell script path and file name eg:” sh /home/sachin/Myscripts/shellll.sh”.Will this transferred to slave pc and run?.In my case it wont

    Reply

  15. Hey bibin,thanks for the blog.
    How to run a shell script in slave jenkins that configured in jenkins master or developers PC?

    Reply

    1. Under Build –> Add a Build Step, you will find an option called “execute shell”. You can add your scripts there.

      Reply
Leave a Reply

Your email address will not be published. Required fields are marked *

You May Also Like