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.

Practice

1. Which statement correctly describes the difference between SSH and JNLP agent connection methods in Jenkins?

easy

A. SSH agents connect by Jenkins initiating the connection; JNLP agents connect by the agent initiating the connection.

B. JNLP agents connect by Jenkins initiating the connection; SSH agents connect by the agent initiating the connection.

C. Both SSH and JNLP agents require Jenkins to initiate the connection.

D. Both SSH and JNLP agents require the agent to initiate the connection.

Solution

1. Step 1: Understand SSH agent connection

   SSH agents connect by Jenkins server initiating an SSH connection to the agent machine.

2. Step 2: Understand JNLP agent connection

   JNLP agents connect by the agent itself initiating a connection back to the Jenkins server.

3. Final Answer:

   SSH agents connect by Jenkins initiating the connection; JNLP agents connect by the agent initiating the connection. -> Option A

4. Quick Check:

   SSH = Jenkins initiates, JNLP = Agent initiates [OK]

Hint: Remember: SSH = Jenkins connects out, JNLP = agent connects in [OK]

Common Mistakes:

• Confusing which side initiates the connection
• Thinking both methods work the same way
• Assuming JNLP requires SSH protocol

2. Which of the following is the correct syntax to configure a Jenkins SSH agent in the Jenkins UI?

easy

A. Provide Jenkins server IP and SSH port only.

B. Provide Jenkins server URL and agent secret key only.

C. Provide only the agent's IP address without credentials.

D. Provide agent's hostname, SSH credentials, and remote root directory.

Solution

1. Step 1: Identify SSH agent configuration requirements

   SSH agents require hostname, SSH credentials (username/key), and remote root directory to connect properly.

2. Step 2: Eliminate incorrect options

   Options A, B, and C miss essential details like credentials or directory, so they are incorrect.

3. Final Answer:

   Provide agent's hostname, SSH credentials, and remote root directory. -> Option D

4. Quick Check:

   SSH agent needs hostname + credentials + directory [OK]

Hint: SSH agent setup needs hostname, credentials, and directory [OK]

Common Mistakes:

• Skipping SSH credentials in configuration
• Confusing JNLP secret with SSH setup
• Providing incomplete connection details

3. Given a Jenkins agent configured with JNLP, what will happen if the agent machine cannot reach the Jenkins server URL?

medium

A. The agent will connect using SSH fallback automatically.

B. The agent will connect successfully because Jenkins initiates the connection.

C. The agent will fail to connect because it initiates the connection to Jenkins.

D. The Jenkins server will push jobs to the agent regardless.

Solution

1. Step 1: Understand JNLP connection direction

   JNLP agents initiate the connection to the Jenkins server URL, so the agent must reach the server.

2. Step 2: Analyze network failure impact

   If the agent cannot reach the Jenkins server URL, the connection attempt fails and the agent cannot connect.

3. Final Answer:

   The agent will fail to connect because it initiates the connection to Jenkins. -> Option C

4. Quick Check:

   JNLP agent needs network access to Jenkins [OK]

Hint: JNLP agent must reach Jenkins URL to connect [OK]

Common Mistakes:

• Assuming Jenkins initiates JNLP connection
• Thinking SSH fallback is automatic
• Believing Jenkins can push jobs without agent connection

4. You configured an SSH agent in Jenkins but the connection keeps failing with authentication errors. What is the most likely cause?

medium

A. Agent machine cannot reach Jenkins server URL.

B. Incorrect SSH credentials or missing SSH key on the agent machine.

C. JNLP agent secret key is invalid.

D. Jenkins server firewall blocks outgoing SSH connections.

Solution

1. Step 1: Identify cause of SSH authentication failure

   Authentication errors usually mean wrong username/password or missing SSH key on the agent side.

2. Step 2: Eliminate other options

   Agent machine cannot reach Jenkins server URL. relates to JNLP, not SSH. JNLP agent secret key is invalid. is about JNLP secret. Jenkins server firewall blocks outgoing SSH connections. is unlikely as Jenkins initiates SSH outbound.

3. Final Answer:

   Incorrect SSH credentials or missing SSH key on the agent machine. -> Option B

4. Quick Check:

   SSH auth errors = bad credentials or missing key [OK]

Hint: Check SSH credentials and keys first for connection errors [OK]

Common Mistakes:

• Confusing JNLP secret with SSH credentials
• Ignoring network reachability issues
• Assuming firewall blocks inbound SSH to Jenkins

5. You need to connect Jenkins agents located behind strict firewalls that block incoming connections to the agent machines. Which connection method should you choose and why?

hard

A. Use JNLP because agents initiate connections to Jenkins, bypassing firewall restrictions.

B. Use SSH because Jenkins can initiate connections to agents behind firewalls.

C. Use SSH with VPN to bypass firewall restrictions.

D. Use JNLP but disable agent authentication for easier connection.

Solution

1. Step 1: Analyze firewall impact on connection methods

   Firewalls blocking incoming connections to agents prevent Jenkins from initiating SSH connections.

2. Step 2: Choose method allowing agent-initiated connection

   JNLP agents initiate connection to Jenkins server, so they can connect despite firewall restrictions on incoming traffic.

3. Step 3: Evaluate other options

   SSH requires Jenkins to connect in, VPN adds complexity, disabling authentication is insecure and not recommended.

4. Final Answer:

   Use JNLP because agents initiate connections to Jenkins, bypassing firewall restrictions. -> Option A

5. Quick Check:

   Firewall blocks incoming? Choose agent-initiated JNLP [OK]

Hint: Firewalls blocking incoming? Pick JNLP agent connection [OK]

Common Mistakes:

• Choosing SSH despite firewall inbound block
• Disabling authentication for convenience
• Ignoring VPN complexity and security