How to access webSockets for Jenkins inbound agents?

Article ID:360057119811
2 minute readKnowledge base

Issue

When I create a new permanent agent with webSocket enabled and Launch method "Launch agent by connecting it to the controller" I get a resulting command which does not include the webSocket option.

Resolution (launcher method)

The webSocket option is not reflected in the command because it is implicit. However, the inbound agent will attempt to connect using webSockets.

  1. Configure your permanent agent with webSocket enabled and Launch method "Launch agent by connecting it to the controller"

    inbound agent config
  2. The resulting command will be presented when accessing your new inbound agent

    inbound agent command
  3. From your remote host, run the command (notice: INFO: WebSocket connection open)

     java -jar agent.jar -jnlpUrl ${JENKINS_URL}/computer/websocket-agent/jenkins-agent.jnlp -secret ${SECRET} -workDir "/tmp/jenkins"
     Jan. 29, 2021 9:53:02 A.M. org.jenkinsci.remoting.engine.WorkDirManager initializeWorkDir
     INFO: Using /tmp/jenkins/remoting as a remoting work directory
     Jan. 29, 2021 9:53:02 A.M. org.jenkinsci.remoting.engine.WorkDirManager setupLogging
     INFO: Both error and output logs will be printed to /tmp/jenkins/remoting
     Jan. 29, 2021 9:53:02 A.M. hudson.remoting.jnlp.Main createEngine
     INFO: Setting up agent: websocket-agent
     Jan. 29, 2021 9:53:02 A.M. hudson.remoting.jnlp.Main$CuiListener <init>
     INFO: Jenkins agent is running in headless mode.
     Jan. 29, 2021 9:53:02 A.M. hudson.remoting.Engine startEngine
     INFO: Using Remoting version: 4.5
     Jan. 29, 2021 9:53:02 A.M. org.jenkinsci.remoting.engine.WorkDirManager initializeWorkDir
     INFO: Using /tmp/jenkins/remoting as a remoting work directory
     Jan. 29, 2021 9:53:02 A.M. hudson.remoting.jnlp.Main$CuiListener status
     INFO: WebSocket connection open
     Jan. 29, 2021 9:53:02 A.M. hudson.remoting.jnlp.Main$CuiListener status
     INFO: Connected

Alternative (raw method)

If you’re not seeing a "WebSocket connection open" while using the implicit launcher method (above) please ensure you are using the latest "agent.jar" and use the raw method and pass -webSocket explicitly to the command.

  1. Re-download agent.jar

     $ curl -OL https://127.0.0.1:8080/jnlpJars/agent.jar
       % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                      Dload  Upload   Total   Spent    Left  Speed
     100 1485k  100 1485k    0     0   207M      0 --:--:-- --:--:-- --:--:--  207M
     $
     $ ls -l agent.jar
     -rw-r--r--  1 me  staff  1521553 29 Jan 10:17 agent.jar
     $
     $ md5sum agent.jar
     d866f0b482db94f38e49b26b465d5db5  agent.jar
     $
  2. Verify agent.jar version

     $ java -jar agent.jar -version
     4.5
     $
  3. Use the raw method for launching agent with webSocket option

     $ java -cp agent.jar hudson.remoting.jnlp.Main -url ${JENKINS_URL} -webSocket -workDir /tmp/jenkins -secret ${TOKEN} websocket-agent
     Jan. 29, 2021 10:10:15 A.M. hudson.remoting.jnlp.Main createEngine
     INFO: Setting up agent: websocket-agent
     Jan. 29, 2021 10:10:18 A.M. hudson.remoting.Engine startEngine
     INFO: Using Remoting version: 4.5
     Jan. 29, 2021 10:10:18 A.M. org.jenkinsci.remoting.engine.WorkDirManager initializeWorkDir
     INFO: Using /tmp/jenkins/remoting as a remoting work directory
     Jan. 29, 2021 10:10:18 A.M. org.jenkinsci.remoting.engine.WorkDirManager setupLogging
     INFO: Both error and output logs will be printed to /tmp/jenkins/remoting
     $
    inbound agent raw method connect