KodeKloud Notes

This guide walks you through setting up a new Jenkins agent (node) on a dedicated Ubuntu VM—Ubuntu-Docker-JDK17-Node20—for distributed builds. You’ll learn how to register the agent in Jenkins, launch it via JNLP, resolve common connection errors, and verify that it’s online.

1. Review Existing Nodes

In Jenkins, go to Manage Jenkins → Nodes.
By default, you’ll see only the built-in controller node.

The image shows a Jenkins dashboard displaying node information, including architecture, clock difference, and disk space details. The build queue is empty, and the build executor status shows two idle executors.

2. Add a New Node

Click New Node.
Enter a name (for example, Ubuntu-Agent) and choose Permanent Agent.
Configure the fields below:

Field	Description	Example
Description	Optional notes about this agent.	“Docker + JDK17 on Ubuntu”
# of executors	Maximum parallel builds.	`2`
Remote root directory	Workspace, logs, and temp files on the agent.	`/home/jenkins-agent`
Labels	Tags to match pipeline stages or jobs.	`docker`, `jdk17`
Usage	Controls job assignment.	“Only build jobs with label expressions matching this node.”

Under Launch method, select Launch agent by connecting it to the controller and set Availability to keep it always online.
Add any Node Properties you need—disk space monitoring, environment variables, tool locations, etc.

The image shows a Jenkins interface for configuring a node, with fields for description, number of executors, and remote root directory. There is a warning indicating that the remote directory is mandatory.

The image shows a Jenkins configuration page for managing nodes, with options for setting the number of executors, remote root directory, labels, usage, and launch method. The "Launch method" dropdown is expanded, showing different options for connecting the agent to the controller.

The image shows a Jenkins dashboard interface with node properties settings, including disk space monitoring thresholds and environment variables.

Click Save. The new node appears offline until you launch its agent process.

3. Launch the Agent via JNLP

Download agent.jar and start the agent on your VM. Here’s a quick reference for JNLP options:

Option	Description
`-url`	Jenkins controller URL
`-secret`	Agent’s secret for authentication
`-name`	Node name as registered in Jenkins
`-workDir`	Local workspace on the agent

Sample Commands

# Unix (inline secret)
curl -sO http://64.227.187.25:8080/jnlpJars/agent.jar
java -jar agent.jar \
  -url http://64.227.187.25:8080/ \
  -secret 687ec2b7…5c4a6f41 \
  -name "ubuntu-agent" \
  -workDir "/home/jenkins-agent"

:: Windows (curl.exe)
curl.exe -sO http://64.227.187.25:8080/jnlpJars/agent.jar
java -jar agent.jar ^
  -url http://64.227.187.25:8080/ ^
  -secret 687ec2b7…5c4a6f41 ^
  -name "ubuntu-agent" ^
  -workDir "C:\jenkins-agent"

# Unix (secret file)
echo 687ec2b7…5c4a6f41 > secret-file
curl -sO http://64.227.187.25:8080/jnlpJars/agent.jar
java -jar agent.jar \
  -url http://64.227.187.25:8080/ \
  -secret @secret-file \
  -name "ubuntu-agent" \
  -workDir "/home/jenkins-agent"

On your Ubuntu VM:

cd /home
curl -sO http://64.227.187.25:8080/jnlpJars/agent.jar
java -jar agent.jar \
  -url http://64.227.187.25:8080/ \
  -secret 687ec2b7…5c4a6f41 \
  -name "ubuntu-agent" \
  -workDir "/home/jenkins-agent"

Note

Ensure the agent’s JDK version matches the controller’s JDK to avoid compatibility issues.

Common Connection Error

If your agent logs show a 404 for .../jnlpAgentListener/, it means the inbound agent TCP port is disabled.

Warning

Inbound agents require a TCP port.
Go to Manage Jenkins → Configure Global Security and set TCP port for inbound agents to Fixed or Random.

The image shows a Jenkins security configuration page with options for setting the TCP port for inbound agents and CSRF protection settings. The TCP port is currently set to "Disable."

Save and re-run the JNLP command. You should see:

INFO: Using /home/jenkins-agent as a remoting work directory
INFO: Setting up agent: ubuntu-agent
INFO: Locating server among [http://64.227.187.25:8080]
INFO: Connected

4. Verify the Agent in Jenkins

Go back to Manage Jenkins → Nodes.
Confirm that ubuntu-agent is online and ready.

The image shows a Jenkins dashboard displaying node information, including architecture, disk space, and response time for two nodes: "Built-In Node" and "ubuntu-agent."

Click on the agent name to explore:

System Information (JVM, OS, environment)
JavaMelody Monitoring (threads, processes, GC stats)
Agent Log (connection status, version)

5. Inspect the Agent VM

On the agent VM, verify the working directory structure:

root@ubuntu-docker-jdk17-node20:/home# ls
agent.jar  jenkins-agent

root@ubuntu-docker-jdk17-node20:/home# cd jenkins-agent/
root@ubuntu-docker-jdk17-node20:/home/jenkins-agent# ls
remoting

As you run builds, Jenkins will create workspace, logs, and artifacts folders under /home/jenkins-agent.

Links and References

Watch Video

Watch video content