Agent connection methods (SSH, JNLP) in Jenkins - Step-by-Step Execution

Process Flow - Agent connection methods (SSH, JNLP)

Start Jenkins Master

↓

Choose Agent Connection Method

↓

SSH Agent

↓

Master connects

↓

Agent ready for jobs

↓

Run Jobs

Jenkins master and agent connect using either SSH where master initiates connection, or JNLP where agent initiates connection, enabling job execution.

Execution Sample

Jenkins

ssh-agent setup:
ssh user@agent-host

jnlp-agent setup:
java -jar agent.jar -jnlpUrl http://master/computer/agent/slave-agent.jnlp

Shows commands to connect Jenkins agent via SSH and JNLP methods.

Process Table

Step	Action	Connection Method	Result	Next Step
1	Jenkins master starts	N/A	Master ready	Choose agent connection method
2	Select SSH method	SSH	Master prepares SSH connection	Master connects to agent via SSH
3	Master runs ssh user@agent-host	SSH	SSH session established	Agent ready for jobs
4	Agent accepts SSH connection	SSH	Agent connected	Run jobs on agent
5	Select JNLP method	JNLP	Agent downloads agent.jar	Agent runs java -jar agent.jar
6	Agent runs java -jar with JNLP URL	JNLP	Agent connects to master	Agent ready for jobs
7	Agent connected via JNLP	JNLP	Agent connected	Run jobs on agent
8	Jobs dispatched	SSH or JNLP	Jobs run on agent	Execution complete

💡 Jobs run on agent; connection established either by SSH initiated by master or JNLP initiated by agent.

Status Tracker

Variable	Start	After SSH Connect	After JNLP Connect	Final
Connection Status	Disconnected	Connected (SSH)	Connected (JNLP)	Connected
Agent Ready	No	Yes (SSH)	Yes (JNLP)	Yes

Key Moments - 2 Insights

Why does SSH connection start from the master but JNLP connection starts from the agent?

SSH requires master to initiate connection to agent's SSH server (see execution_table step 3), while JNLP agent runs on the agent machine and connects back to master (see step 6).

What happens if the agent machine blocks incoming SSH connections?

SSH connection will fail at step 3 in execution_table, but JNLP can still work because agent initiates connection outbound to master (step 6).

Visual Quiz - 3 Questions

Look at the execution table, at which step does the agent initiate the connection to the master?

A Step 3

B Step 6

C Step 4

D Step 2

💡 Hint

Check the 'Action' and 'Connection Method' columns for JNLP where agent runs java -jar to connect.

According to the variable tracker, what is the connection status after SSH connect?

A Disconnected

B Connected (JNLP)

C Connected (SSH)

D Connecting

💡 Hint

Look at the 'Connection Status' row under 'After SSH Connect' column.

If the agent blocks incoming SSH but allows outbound connections, which method will succeed?

A JNLP only

B Both SSH and JNLP

C SSH only

D Neither

💡 Hint

Refer to key_moments explanation about connection initiation direction.

Concept Snapshot

Jenkins agents connect to master via two main methods:
- SSH: Master initiates connection to agent's SSH server.
- JNLP: Agent runs a Java client that connects back to master.
SSH requires agent to accept incoming connections.
JNLP works well when agent cannot accept inbound connections.
Both enable agents to run jobs dispatched by master.

Full Transcript

This visual execution shows how Jenkins agents connect to the master using SSH or JNLP methods. The master starts and chooses the connection method. For SSH, the master initiates an SSH session to the agent machine, which must accept incoming SSH connections. For JNLP, the agent machine runs a Java client that connects back to the master, useful when the agent cannot accept inbound connections. The execution table traces each step from starting the master, selecting connection method, establishing connection, to running jobs. The variable tracker shows connection status and agent readiness changing from disconnected to connected. Key moments clarify why connection initiation direction matters and what happens if SSH is blocked. The quiz tests understanding of connection initiation steps and conditions for success. The snapshot summarizes the two methods and their key differences.

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