Additional remote agent options

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes additional options for running a Bamboo remote agent. Additional options can be found in How to extend the Remote agent installation command using JVM parameters.



Changing where the remote agent stores its data

By default, the remote agent will store its data in a USER_HOME/bamboo-agent-home. If you wish to specify a different directory, add the following command line parameter before the JAR file name:

-Dbamboo.home=RemoteAgentHome

Where RemoteAgentHome is the path to the Bamboo agent home directory you created in step 1.1.

Your command line should appear similar to the example provided below. Note that the command will work only in the cmd (Command Prompt for Windows) and Terminal (for MacOS and Linux).

java -Dbamboo.home=RemoteAgentHome -jar atlassian-bamboo-agent-installer-X.X-SNAPSHOT.jar http://bamboo-host-server:8085/agentServer/

The name of the jar file (e.g. atlassian-bamboo-agent-installer-2.2-SNAPSHOT.jar) will vary depending on the version of Bamboo you are running.

Disabling auto-capability detection for the remote agent

There may be situations where you want to prevent Bamboo from automatically detecting and adding capabilities (such as JDKs) to the remote agent, or where you don't want to run the remote agent with default capabilities.

Elastic agents don't support the DISABLE_AGENT_AUTO_CAPABILITY_DETECTION system property.

The DISABLE_AGENT_AUTO_CAPABILITY_DETECTION system property is handled only from the wrapper.conf file, not from the command line.

To update the property for a remote agent, add the following line to the <bamboo-agent-home>/conf/wrapper.conf file:

wrapper.java.additional.3=-DDISABLE_AGENT_AUTO_CAPABILITY_DETECTION=true

Then restart the agent with regular command java -jar agent.jar URL_TO_SERVER SECURITY_TOKEN

Specifying a custom log4j file for the remote agent

You can specify a custom log4j file in the wrapper.conf file. The file is located in <bamboo-agent-home>/conf/wrapper.conf

Find the #wrapper.java.additional.3=-Dlog4j.configuration= line, uncomment it and provide path to log4j.properties file at your disk. Then restart the agent with regular command java -jar agent.jar URL_TO_SERVER SECURITY_TOKEN.


Changing the logging on the remote agent

By default, the remote agent will use the same logging level as the Bamboo server. However, you can control the level of logging of your remote agent independently of your Bamboo server by setting up a separate logging configuration file.

See Logging in Bamboo for further details.

Accepting self-signed certificates installed on the server

Use the text-based keytool utility or GUI-based Portecle to add the self-signed certificate to the trusted certificates in your keystore.

Add "socket.verifyHostName=false" settings to Client Broker URL at Bamboo general configuration.

Disabling hostname verification for certificates

If you are connecting to your Bamboo server via https (SSL is enabled) using a hostname or IP address that does not match the Common Name of your Bamboo server's certificate (or any of its Subject Alternative Names) you need to disable hostname verification:

 Add the following parameter to the remote agent's command line:

-Dbamboo.agent.ignoreServerCertName=true

Your command line will look something like this:

java -Dbamboo.agent.ignoreServerCertName=true -jar atlassian-bamboo-agent-installer-X.X-SNAPSHOT.jar https://bamboo-host-server:8085/agentServer/


(warning) Note that this reduces the security of your configuration, as the identity of your Bamboo server will not be authenticated by the remote agent.

Running Bamboo without the Remote Agent Supervisor

The remote agent supervisor is included in the remote agent JAR bundled with Bamboo. The appropriate remote agent supervisor for the operating system of your remote machine, will be automatically installed when you run the default remote agent start-up command line.

The remote agent supervisor cannot be installed on a small number of operating systems (i.e. the remote agent will start without the remote agent supervisor). If the remote agent supervisor fails to install, please check the operated systems list on the remote agent supervisor page. If your operating system is on the list and the remote agent supervisor still fails to install, please raise a support request in the Bamboo project.

If you need to run the remote agent without running the remote agent supervisor, you can execute the classic version of the remote agent JAR.
The classic agent jar is available from Bamboo's agent installation page for download. Follow the steps below to run the classic version of the remote agent:

  1. Browse to:

    http://<host>:8085/admin/agent/addRemoteAgent.action
  2. Select the the direct agent JAR is available at bamboo-agent-2.2.2.jar link and save classic agent jar.
  3. Start the agent with or without token key:

    java -jar bamboo-agent-2.2.2.jar http://<host>:8085/agentServer/ <tokenKey>

    <tokenKey> is required if Security Token Verification is enabled.

(info) The name of the jar file (e.g. bamboo-agent-2.2.2.jar) will vary depending on the version of Bamboo you are running

Running the remote agent with different start-up commands

The remote agent supervisor is executed by default when you run the default remote agent start-up command line. The remote agent supervisor is implemented via a Java Service wrapper. The wrapper allows you to execute a number of general start-up commands when the remote agent is run. These commands are appended to the end of the default remote agent start-up command line:

java -jar atlassian-bamboo-agent-installer-2.2-SNAPSHOT.jar http://bamboo-host-server:8085/agentServer <wrapper_command>


where <wrapper_command> is one of the keywords described below:

  • console — runs the remote agent in the foreground, i.e. display all of the commands on the screen. The agent home directory will be populated only if it is empty. This parameter is used by default.
  • start — runs the remote agent in the background, i.e. no commands are displayed on screen. If you have installed the remote agent as a Windows service, this command will work with the service.
  • stop — stops a remote agent that is running. If you have installed the remote agent as a Windows service, this command will work with the service.
  • status — (non-Windows OS only) returns the status of the remote agent, e.g. "Remote agent is not running."
  • install — installs the files for the remote agent, but does not start it. This will overwrite any changes that have been made to the wrapper.conf file. The agent home directory will be populated, regardless of whether it is empty or not, i.e. existing files will be overwritten. You may wish to use this option, if you want to customize the remote agent files before starting it.

(info) The name of the jar file (e.g. atlassian-bamboo-agent-installer-2.2-SNAPSHOT.jar) will vary depending on the version of Bamboo you are running.

Installing the remote agent as a Windows service (Windows only)

The remote agent supervisor is executed by default when you run the default remote agent start-up command line. The remote agent supervisor is implemented via a Java Service wrapper. The wrapper allows you to install or uninstall the remote agent as a service in Windows (i.e. start the Bamboo remote agent automatically when the machine boots). This is done by appending the appropriate wrapper commands to the end of the default remote agent start-up command line:

java -jar atlassian-bamboo-agent-installer-2.2-SNAPSHOT.jar http://bamboo-host-server:8085/agentServer <wrapper_command>

where <wrapper_command> is one of the keywords described below:

  • installntservice — (Windows only) installs the remote agent as a Windows service.
  • uninstallntservice — (Windows only) uninstalls the remote agent as a Windows service.

(info) The name of the jar file (e.g. atlassian-bamboo-agent-installer-2.2-SNAPSHOT.jar) will vary depending on the version of Bamboo you are running.

If you have installed the NT service, you will be able to use the start and stop start-up console commands with the service.

  • The remote agents connect to the Bamboo server on the normal http/https port and 54663. You need to ensure that the network firewall isn't blocking these ports.If you're having issues connecting the remote agent with the Bamboo server, please this Troubleshooting Guide
  • On Windows, when the Bamboo remote agent is installed as a service under the Local System user account. The temporary folder created by the agent isn't accessible by any other application. To allow enable to that folder, configure the agent to use a commonly accessible temporary folder by defining a new Java property in the service wrapper:

    1. Go to: <BAMBOO_AGENT_HOME>/conf/wrapper.conf
    2. Add the following line using the next property number as X:
      wrapper.java.additional.X=-Djava.io.tmpdir=C:\path\to\temp
    3. Restart the agent.






Last modified on Oct 12, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.