Agent connection methods (SSH, JNLP) in Jenkins - Commands & Configuration

Introduction

Jenkins uses agents to run tasks on different machines. Agents connect to the main Jenkins server using methods like SSH or JNLP. These methods help Jenkins distribute work safely and efficiently.

When you want to run builds on a remote Linux server using secure shell access.

When you need to connect an agent behind a firewall that cannot accept incoming SSH connections.

When you want to add a Windows machine as an agent without setting up SSH.

When you want the agent to initiate the connection to Jenkins to avoid network restrictions.

When you want to manage agents dynamically with Jenkins controlling their lifecycle.

Commands

Connect to the agent server via SSH using the Jenkins private key to verify the connection manually.

Terminal

ssh -i ~/.ssh/jenkins_key jenkins@agent-server

Expected Output

Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-50-generic x86_64)

jenkins@agent-server:~$

→

-i ~/.ssh/jenkins_key - Use this private key file for authentication

Start the Jenkins agent using JNLP by connecting to the Jenkins server URL with the secret key for authentication.

Terminal

java -jar agent.jar -jnlpUrl http://jenkins-server/computer/my-agent/slave-agent.jnlp -secret 1234567890abcdef

Expected Output

INFO: Connecting to Jenkins at http://jenkins-server

INFO: Connected

INFO: Agent successfully connected and online

→

-jnlpUrl - URL to the agent's JNLP file on Jenkins

→

-secret - Secret key for secure authentication

Start the Jenkins agent using JNLP without specifying a secret, which will fail if Jenkins requires authentication.

Terminal

java -jar agent.jar -jnlpUrl http://jenkins-server/computer/my-agent/slave-agent.jnlp

Expected Output

ERROR: Authentication failed: Secret key missing or invalid

Run the Jenkins agent on the remote server via SSH by executing the JNLP agent command remotely.

Terminal

ssh jenkins@agent-server 'java -jar /home/jenkins/agent.jar -jnlpUrl http://jenkins-server/computer/my-agent/slave-agent.jnlp -secret 1234567890abcdef'

Expected Output

INFO: Connecting to Jenkins at http://jenkins-server

INFO: Connected

INFO: Agent successfully connected and online

Key Concept

If you remember nothing else from this pattern, remember: SSH agents connect by Jenkins reaching out to the agent, while JNLP agents connect by the agent reaching out to Jenkins.

Common Mistakes

Trying to start a JNLP agent without the secret key.

Jenkins requires the secret key to authenticate the agent connection, so the connection will fail.

Always provide the correct secret key when starting a JNLP agent.

Assuming SSH connection works without setting up SSH keys or user permissions.

Without proper SSH keys and permissions, Jenkins cannot connect to the agent server securely.

Set up SSH keys and ensure the Jenkins user has permission to connect to the agent server.

Using JNLP when the agent server cannot reach the Jenkins server due to firewall restrictions.

JNLP requires the agent to initiate the connection, so network restrictions can block it.

Use SSH agents or adjust firewall rules to allow the agent to connect to Jenkins.

Summary

SSH agents connect by Jenkins logging into the agent machine using SSH to run tasks.

JNLP agents connect by the agent machine running a Java command to reach out to Jenkins.

Always provide the secret key for JNLP agents to authenticate successfully.