Advanced command-line installation (agent-only installer)

This page covers how to install CloudBees CD/RO agents using the CLI-based Advanced agent option of the Linux agent installer.

The Advanced agent option installs the following CloudBees CD/RO components on the host machine:

Agent
CloudBees CD/RO tools

Before you start

The following are important knowledge prerequisites to review before starting this procedure:

CloudBees recommends reviewing the following resources before installation:

The Advanced agent option is meant for installing an agent that will be used as a remote agent for a server running on a separate machine.

For production environments, CloudBees recommends installing each CloudBees CD/RO component on separate machines using the Advanced installation option.

Additionally, there are specific agent security recommendations available at Agent security recommendations.

Perform an Advanced Agent installation

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.12.0.177508
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.12.0.177508
  ▼
2. Start the installation:
  
  For more information about required user privileges, refer to Linux services user permissions.
  - For root or sudo installations, run:
    
    Root or sudo procedures
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version>
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.12.0.177508
    ▼
    
    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.12.0.177508 --mode console
    ▼
  - For non-root/non-sudo installations, run:
    
    Non-root/non-sudo procedures
    
    Command
    Current version
    
    ./CloudBeesFlowAgent-x64-<version> --nonRoot
    ▼
    
    ./CloudBeesFlowAgent-x64-2024.12.0.177508 --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.12.0.177508 \ --mode console \ --nonRoot
    ▼
    
    A warning about automatic server start-up with non-root/non- sudo installations appears. Enter Yes to dismiss the warning.
The installer launch prompt appears. Enter Y to continue.

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 installation directory for program files and binaries. [/opt/cloudbees/sda]▼
```
1. Press Enter to use the default /opt/cloudbees/sda, or provide a custom path.
The following prompt appears:
```
Specify the data directory for data files, configurations, and logs.
[/opt/cloudbees/sda]▼
```
1. Press Enter to use the default /opt/cloudbees/sda, or provide a custom path.
The following prompt appears:
```
Specify the agent port. [7800]▼
```
1. Press Enter to use the default port. If required, enter a different port to eliminate conflicts with your existing system configuration.
The following prompt appears:
```
Specify the agent local port. [6800]▼
```
1. Press Enter to use the default port. If required, enter a different port to eliminate conflicts with the agent HTTP communication on the localhost network interface.

The following prompt appears:

Discover the plugins directory from a remote CloudBees CD/RO 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, refer to Configure 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]▼

Enter y to create a resource for the agent on the remote CloudBees CD/RO server. Enter N to skip this step, and set up the agent resource later.

CloudBees suggests entering Y to automatically create a resource for the agent on your remote CloudBees CD/RO server. This option saves time later configuring new resources on the CloudBees CD/RO server.

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.
  1. 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.
The following prompt appears:
```
Create agent in the default zone? [n/Y]▼
```
1. Enter Y to create the agent in the default zone. Enter N to create a new zone.

The following prompt appears:

Specify the host:port of a remote CloudBees CD/RO server the agent being
installed can link to. The port is only required if it is not the default(8000)▼

Provide the URL of the CloudBees CD/RO server you want the agent to connect with.

The following prompt appears:
```
Specify the CloudBees CD/RO Agent username for logging into "<CDRO-server>".
[admin]▼
```
1. Press Enter to use admin. If using a different user, enter the username of the CloudBees CD/RO user to register the agent.
  
  This user must have sufficient permissions to create the agent resources on your CloudBees CD/RO server.
The following prompt appears:
```
Specify the password for "<username>" on "<CDRO-server>". []▼
```
1. Press Enter to use admin. If using a different user, enter the username of the CloudBees CD/RO user to register the agent.
The following prompt appears:
```
Specify the name of the resource to create on "<CDRO-server>".
[]▼
```
1. Press Enter to use your default machine name. If needed, provide a new name for the resource.
The following prompt appears:
```
Specify the hostname of the installed agent to create a new resource.
[]▼
```
1. Press Enter to use your default machine name. If needed, provide a new name for the hostname.
The following prompt appears:
```
Specify the name of the default workspace for the new resource
"<resource-name>".
[]▼
```
1. Provide a default workspace name for the jobs in the resource.

The following prompt appears:

Specify the URL for the agent gateway in the format 'https://ipOrHostname:port'
[]▼

Provide the URL for the agent gateway.

The following prompt appears:

Specify the URL for the agent gateway in the format 'https://ipOrHostname:port'
[]▼

Provide the URL for the agent gateway.

If you select not to create the agent in the default zone, the following prompt appears:
```
Specify the zone name for the agent and/or repository. []▼
```
1. Specify a zone name for the agent.

The following prompt appears:

Specify the system user the agent will run as []▼

Provide the system user to use when running agent services.

If you specify root as the agent service user, the following prompt appears:

For security reasons, CloudBees strongly recommends NOT using the 'root' user to run agent processes in production environments. For more
information, refer to:

https://docs.cloudbees.com/docs/cloudbees-cd/latest/install-trad/agent-config-recommendations

Do you still want to continue using the 'root' user to run agent processes? [y/N]▼

CloudBees strongly recommends not running the agent services as a root user. This can pose significant security risks if the agent becomes compromised.

To accept these security risk and run the agent as root, enter Y.

The following prompt appears:
```
Specify the system group the agent will run as []▼
```
1. Provide the system group of the user being used to run the agent services.

The CloudBees CD/RO agent installation starts. A success prompt is shown when the installation is complete.

Configure autostart for non-root environments

For installations performed as a Windows Administrator or with Linux root or sudo privileges, CloudBees CD/RO components start automatically upon completing the installation and during system boot. However, for non-root/non-sudo Linux installations CloudBees CD/RO components do not have the permissions to start automatically.

To configure autostart for non-root or non-sudo Linux installations of CloudBees CD/RO components, refer to Configure autostart for non-root/non-sudo Linux installations.