Run an advanced GUI installation (agent-only installer)

The agent software must be installed on each machine you intend to use with CloudBees CD/RO. An agent is a CloudBees CD/RO component that runs on a machine resource. The agent executes CloudBees CD/RO job steps, monitors step progress, and records job completion information.

Certain CloudBees CD/RO installers allow you to perform installations as a non-root user or a user without sudo privileges. To determine whether a particular installer has an option to run in this mode, refer to Installation user requirements.

Review Before You Install CloudBees CD/RO before performing this procedure.

Install {PRODUCT agent software on Windows or Linux with this installation method. For macOS or other supported UNIX agent-only machines, see Non-Server Platform Agent Installation Method.

If you have not already done so, download the agent-only installer file. To download this version, select your required installer:
- Windows agent installer: 2024.09.0.176472
- Linux agent installer: 2024.09.0.176472
  - A Linux graphical environment is required to run the GUI installer.
For more details on installers, refer to Install CloudBees CD/RO on traditional platforms.

For legacy installer downloads, navigate to CloudBees CD/RO downloads.
Start the installer:
- Windows:
  
  On Windows, an Administrator user is required to install CloudBees CD/RO. For more information about required user privileges, refer to Windows services user permissions.
  1. Navigate to the directory where you downloaded CloudBees CD/RO.
  2. Double-click the installer. This starts the installer in the GUI-based installation mode.
- Linux:
  1. Enter the following command to make the installer file executable:
    
    Command
    Current version
    
    chmod +x CloudBeesFlowAgent-x64-<version>
    ▼
    
    chmod +x CloudBeesFlowAgent-x64-2024.09.0.176472
    ▼
  2. Start the installation:
    
    For more information about required user privileges, refer to Linux services user permissions.
    
    For root or sudo installations:
    
    Navigate to the directory where you downloaded CloudBees CD/RO.
    
    Double-click the installer. This starts the installer in the GUI-based installation mode.
    
    For non-root/non-sudo installations, from the terminal, run:
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version> --nonRoot
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.09.0.176472 --nonRoot
    ▼
    
    A warning about automatic server start-up with non-root/non- sudo installations appears. Enter Yes to dismiss the warning.
Select the Advanced Agent installation option, and then click Next to continue. The Directories screen appears.
Complete the following information on the Directories screen:
- Install directory —Use this field to enter a new installation directory path for program files and binaries.
- Data directory —Use this field to enter a new installation directory path for configuration files and logs.
Click Next to continue. The Ports screen appears.
Complete the following information on the Ports screen:
- Agent port —Use this field to specify a different port to eliminate any conflicts with your existing system configuration.
- Agent local port —Use this field to specify a different port to be used by the agent for HTTP communication on the localhost network interface.
Click Next to continue. The Remote CloudBees CD/RO Server screen appears.

Complete the following information on the Remote CloudBees CD/RO Server screen:

Server Host Name —Use this field to enter the name of the CloudBees CD/RO server that will communicate with this agent. If the remote server is using a non-default HTTPS port, you must specify the Server Host Name as <host>:<port>. If you do not specify a port, HTTPS port 8443 is assumed (the same as the CloudBees CD/RO server default port).

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].
CloudBees CD/RO User Name —Use this field to enter the name of a CloudBees CD/RO user on the CloudBees CD/RO server who has sufficient privileges to create a resource. This field defaults to the CloudBees CD/RO-supplied admin user.
Password —Use this field to enter the password for the CloudBees CD/RO user. The default password for the admin user is changeme.

Discover the plugins directory —Select this check box if you want the agent machine to have access to the plugins directory. You should allow access to the plugins directory so agents have access to collections of features, third-party integrations, or third-party tools.

The plugins directory on the CloudBees CD/RO server must be “shared” before the agent machine can use “discover” to find the directory. For more information, see Universal Access to the Plugins Directory .

Create a resource —Select this check box if you want to create a resource on the remote CloudBees CD/RO server for the agent you are installing.
Trusted —Select this check box to restrict this agent to one CloudBees CD/RO server. The agent will not respond to incoming communication from any other CloudBees CD/RO server. This is useful when you want to create a secure production environment, but generally not needed for test or development systems.
Resource Name —Use this field to enter the name of the resource you would like to use for the agent. This field is available for use when the Create a resource check box is selected.
Create in default zone —Select this check box if you want to create the agent in the default zone.
Agent Gateway URL —Use this field to enter the URL of the gateway used to communicate with the CloudBees CD/RO server. This field is available for use when the Create in default zone check box is cleared.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].
Zone Name —Use this field to enter the name of the zone used during remote agent and or remote repository creation. This field is available for use when the Create in default zone check box is cleared.

Click Next to continue. The Agent Service Account screen appears:

Select the appropriate steps for your platform and complete the following information on the screen:

Linux root or sudo installations:

User Name —Use this field to enter the name of the user who owns the CloudBees CD/RO agent process.

For security, CloudBees recommends not installing an agent on the server host or giving any agents access to the server file system. Doing so may give an agent access to sensitive files such as the server passkey, database configuration, and other system resources allotted to CloudBees CD/RO.

If the agent is installed on the server host or given access to the server file system, CloudBees strongly recommends using separate users for server and agent services, so it is possible to prevent the agent from accessing sensitive files. Using the same user for both services also gives agents the same access permissions as the server user.

CloudBees strongly recommends not running agents as sudo or ROOT users in production, or long-lived development and testing environments. Running agents with these privileges poses significant security risks, as they have unlimited ability to execute operations which can be used to access any file on the agent host, or modify the configuration of that host.

Assign CloudBees CD/RO agent users only the necessary privileges to perform their functions, following the Principle of Least Privilege (PoLP). This helps to prevent permission escalation and data exposure should an agent become compromised.

For more information on how to mitigate agent security risks, refer to Agent security recommendations.

If you specify root, enter y when the following confirmation appears:

It is not recommended to use the 'root' user for running the agent process. Please confirm if you would like to proceed [y/N]▼

Group Name —Use this field to enter the name of the group who owns the CloudBees CD/RO agent process.

Windows:

User Name —Use this field to enter the name of the user who will run the CloudBees CD/RO agent service.

For more information on how to mitigate agent security risks, refer to Agent security recommendations.

Password — Use this field to enter the password of the user who will run the CloudBees CD/RO agent service.
Domain —Use this field to enter the domain name information for the user. For example, electric-cloud.com. Leave this field blank if this is a local user.

Use the local system account —Select this check box if you want the CloudBees CD/RO agent service to run as the Windows local system account.

The Windows local system account cannot access network resources such as shared file systems used for plugins or workspaces. Therefore, do not use this option for a clustered server deployment, which requires a shared file system for plugins. This option is typically used only for installing agents on numerous machines, which would otherwise require that you create a new account on each of those machines.

Select the appropriate steps for your platform and complete the information on the screen.
Click Next to continue. The Ready to Install Screen appears.
Verify your selections.

Use the Back button to change settings if needed.
Click Next to continue.

CloudBees CD/RO installs the agent and tools components. This process can take a few minutes. The Installation Wizard Complete screen appears.
Click Finish to complete the installation.
For non-root/non-sudo Linux installations, configure autostart for the CloudBees CD/RO agent service.

For instructions, see Configuring Services Autostart for Non-Root/Non-sudo Linux Installations .