Skip to main content
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

  1. In Jenkins, go to Manage Jenkins → Nodes.
  2. 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

  1. Click New Node.
  2. Enter a name (for example, Ubuntu-Agent) and choose Permanent Agent.
  3. Configure the fields below:
FieldDescriptionExample
DescriptionOptional notes about this agent.“Docker + JDK17 on Ubuntu”
# of executorsMaximum parallel builds.2
Remote root directoryWorkspace, logs, and temp files on the agent./home/jenkins-agent
LabelsTags to match pipeline stages or jobs.docker, jdk17
UsageControls job assignment.“Only build jobs with label expressions matching this node.”
  1. Under Launch method, select Launch agent by connecting it to the controller and set Availability to keep it always online.
  2. 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.
  1. 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:
OptionDescription
-urlJenkins controller URL
-secretAgent’s secret for authentication
-nameNode name as registered in Jenkins
-workDirLocal 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"
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.
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

  1. Go back to Manage Jenkins → Nodes.
  2. 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)
The image shows a Jenkins interface displaying system information for an "ubuntu-agent," including system properties with hidden values.
  • JavaMelody Monitoring (threads, processes, GC stats)
The image shows a Jenkins interface with JavaMelody Monitoring options for system reports and actions, including viewing threads, OS processes, and executing the garbage collector.
  • Agent Log (connection status, version)
The image shows a Jenkins interface displaying a log for an "ubuntu-agent," indicating that the agent is successfully connected and online. The sidebar includes options like Status, Configure, and Monitoring.

​
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.

Watch Video