Advanced command-line 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.

If you have not already done so, download the agent-only installer file. To download this version, select your required installer:
- Linux agent installer: 2024.09.0.176472
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:
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, run:
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version>
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.09.0.176472
    ▼
    
    For root or sudo installations on Linux systems with a graphical interface installed, run:
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version> --mode console
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.09.0.176472 --mode console
    ▼
  - For non-root/non-sudo installations, run:
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version> --nonRoot
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.09.0.176472 --nonRoot
    ▼
    
    For non-root/non-sudo installations on Linux systems with a graphical interface installed, run:
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version> \ --mode console \ --nonRoot
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.09.0.176472 \ --mode console \ --nonRoot
    ▼
    
    A warning about automatic server start-up with non-root/non- sudo installations appears. Enter Yes to dismiss the warning.
After the confirmation prompt, continue the installation by entering y.

The following prompt appears:
```
Specify the type of setup you would like to perform: expressAgent or advanced. [expressAgent]▼
```

Enter advanced.

The following prompt appears:

Specify the install directory (for program files and binaries). [/opt/cloudbees/sda]▼

Enter a new installation directory path for program files and binaries.

The following prompt appears:
```
Specify the data directory (for configuration files and logs). [/opt/cloudbees/sda]▼
```
Enter a new installation directory path for configuration files and logs.

The following prompt appears:
```
Specify the agent port. [7800]▼
```
Enter a different port to eliminate any conflicts with your existing system configuration.

The following prompt appears:
```
Specify the agent local port. [6800]▼
```
Enter a different port to be used by the agent for HTTP communication on the localhost network interface.

The following prompt appears:
```
Discover the plugins directory from a remote {PRODUCT} server? [n/Y]▼
```

Enter y 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.

The following prompt appears:

Create a resource for the installed agent on a remote ClouBees CD/RO server? [n/Y]▼

Answering y automatically create a resource object for the agent on your remote CloudBees CD/RO server. This option is recommended to save time configuring new resources for existing CloudBees CD/RO servers.

Enter y to install the agent on a remote CloudBees CD/RO server.

The following prompts appears:

Create a resource for the installed agent on a remote CloudBees Software Delivery Automation server? [n/Y]▼

Answering y automatically create a resource object for the agent on your remote CloudBees Software Delivery Automation server. This option is recommended to save time configuring new resources for existing CloudBees Software Delivery Automation servers.

If selected y to createing the agent on a remote CloudBees CD/RO or CloudBees Software Delivery Automation servers, the following prompt appears:

Register as trusted agent? [y/N]▼

Making an agent trusted restricts the 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 environments.

You can run gateways without trusted agents. However, you should use gateways with trusted agents to prevent security issues in the firewall between zones connected by a gateway.

There are exceptions to using gateways without trusted agents:

The firewall between two zones is not required in your environment or is needed only to protect the CloudBees CD/RO server.

There is a specific reason to use gateways without trusted agents, such as a requirement to prevent unauthorized users from accessing your network. All incoming traffic from the internet is routed to a data center through a load balancer, and the load balancer routes the traffic to the appropriate machine in your network.

Choose one of the following options:
- If there is no gateway between the agent and CloudBees CD/RO server, enter n.
  
  If you deviated from the recommended agent options, you will see variations in the installation options that appear on your system.
- If a gateway is used to communicate with the CloudBees CD/RO server, you must select y. This option allows you to create a trusted network connection between the agent and server under the same certificate authority. This will allow the agent and the CloudBees CD/RO server to communicate across the network.
  
  If y, for root or sudo installations, the following prompt appears:
  Specify the user the agent will run as. []
  ▼
If you selected n, navigate to the next main step. If you selected y to create the agent as a trusted agent, for root or sudo installations:

Enter a username. This is the user who owns the CloudBees CD/RO agent process. For example, you might enter build.

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]▼

The following prompt appears:

Specify the group the agent will run as. []▼

Enter a Group Name. This is the group that owns the CloudBees CD/RO agent process. For example, you might enter build.

Provide the following details for the agent and resource that will be created on the remote servers:
1. Create agent in the default zone? [n/Y]
2. Specify the host:port of a remote CloudBees CD server the agent being installed can link to. The port is only required if it is not the default(8000).
  
  IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].
3. Specify the user name with which to login to "<YOUR-HOST>".
4. Specify the password for "<YOUR-USER>" on "<YOUR-HOST>".
5. Specify the name of the resource to create on "<YOUR-HOST>".
6. Specify the agent host name the new resource to be created for the installed agent.
7. Specify the name of the default workspace for the new resource "<YOUR-RESOURCE>".
8. Specify the agent gateway URL in the form 'https://ipOrHostname:port'

CloudBees CD/RO is installed on the machine. When the installation completes successfully, a prompt that contains the line CloudBees CD/RO <version> was successfully installed! appears.

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.