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.
This section describes how to install agents and tools on macOS (not Linux or Windows) machines. Agent upgrades are not supported on this platform.
You can install agents using any of the following accounts:
-
root -
Any account with
sudoprivileges -
(UNIX or macOS only) Any non-root account without sudo privileges
|
You must install Rosetta 2 on machines with an Apple M1 chip. Terminal installations do not prompt you to install Rosetta 2. To install Rosetta 2, run the following command:
For more information, refer to install Rosetta on your Mac. |
Installing agents as the root user
To install agents and tools on UNIX or macOS machines using root or an account with sudo privileges:
-
Obtain the UNIX or macOS installer file for your agent platform as described in Non-server installation for UNIX agents.
-
Log in as root.
-
Enter
chmod +x ./commander_<OStype>.binto ensure that the installer is executable.where
<OStype>is the agent platform. For example:chmod +x ./commander_<OStype>.bin -
Run
./commander_<OStype>.bin.The following prompts display:
Checking installer integrity, please wait... {PRODUCT} 7.2.0.116649 for macOS Installer Copyright 2006-2018 CloudBees, Inc. All rights reserved. Press CTRL-C to exit at any time. Press Enter to accept default settings. log file: /tmp/commander_install_20170321_115947.log This suite installer can install several different product options. Note: The default is to install everything. Which products would you like to install (agent, tools):Enter
agentor pressEnter.You can also install the tools only by entering
Tools. The agent and tools are installed. The following prompts display:Installing agent and tools. Where would you like the software to be installed? NOTE: The destination should NOT be an nfs filesystem. Enter destination directory (default is /opt): -
Enter the destination directory path.
The following prompt displays:
Enter an existing user to own installed agent files and run agent processes: -
Enter the name of the user to own the CloudBees CD/RO agent files and run the agent processes.
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
sudoorROOTusers 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.
The following prompt displays:
Enter an existing user group to own installed agent files and run agent processes. Or hit Enter to choose the primary group (default is '<primary group>'): -
Enter the group name of the user to own the CloudBees CD/RO agent files and run the agent processes or press
Enterto use the user’s primary group.The following prompt displays:
Enter the agent port (default is 7800): -
Accept the default port or specify a different port if needed to eliminate conflicts with your existing system configuration, and then press
Enter.The installer extracts and installs the software. When the installation completes, the following prompt displays:
OK: Installation successful!
Installing agents as a non-root user
In this type of installation, the installer starts the agent service and runs it as the user that performed the installation.
| CloudBees does not recommend running the installer without root or sudo privileges. When run without root or sudo privileges, the installer cannot install the files that provide automatic start for the agent services, so you must configure automatic restart manually. |
To install agents and tools on UNIX or macOS machines using a non-root account without sudo privileges:
-
Log in as the user to own the installed agent files and run the agent processes.
-
Obtain the UNIX or macOS installer file for your agent platform as described in Non-server installation for UNIX agents.
-
Run
chmod +x ./commander_<OStype>.binto ensure that the installer is executable.<OStype>is the agent platform. For example:chmod +x ./commander_<OStype>.bin -
Enter
./commander_<OStype>.bin --nonRootto start the installation.The following prompts display:
Checking installer integrity, please wait... {PRODUCT} 7.2.0.116649 for macOS Installer Copyright 2006-2018 CloudBees, Inc. All rights reserved. Press CTRL-C to exit at any time. Press Enter to accept default settings. log file: /tmp/commander_install_20170321_115947.log This suite installer can install several different product options. Note: The default is to install everything. Which products would you like to install (agent, tools): NOTE: Failure to include the `--nonRoot` argument causes the following error: This installer must be invoked in a root context. ERROR: Install failed. Exiting installer. -
Enter
agentor pressEnter.(You can also install the tools only by entering
Tools.) The agent and tools will be installed. The following prompts display:Installing agent and tools. Where would you like the software to be installed? NOTE: The destination should NOT be an nfs filesystem. Enter destination directory (default is /opt): -
Enter the destination directory path.
If you lack sufficient privileges on the destination directory, the following error displays, and you must obtain sufficient privileges before continuing: Could not create "/bin/cloudbees/sda".If the directory that you entered already exists, the following prompts display:
Directory "/opt/cloudbees/sda" already exists. Do you want to delete and overwrite it (Y/n)? -
If the directory already exists, enter
Yto overwrite it.The following prompts display:
Non-root install mode. Current user 'build' will be used as owner for installed agent files and run agent processes. Enter an existing user group to own installed agent files and run agent processes. Or hit Enter to choose the primary group (default is '<primary group>'):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
sudoorROOTusers 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.
-
Enter the group name of the user to own the CloudBees CD/RO agent files and run the agent processes or press
Enterto use the user’s primary group.If you are not a member of the group, the following prompt displays, and you must enter a different group: The combination of agent user 'build' and agent group 'foo' is invalid. Please try again. Enter an existing user group to own installed agent files and run agent processes. Or hit Enter to choose the primary group (default is '<primary group>'):After you successfully enter the group name, the following prompt displays:
Enter the agent port (default is 7800): -
Accept the default port or specify a different port if needed to eliminate conflicts with your existing system configuration, and then press
Enter.The installer extracts and installs the software. Then the following prompts display. Note that the directory to contain the agent services varies by platform:
Please wait while the services are configured and started... Services are started automatically during configuration. To manually start services use following command(s): /opt/cloudbees/sda/startup/ecmdrAgent start To start services at system startup, copy files at /opt/cloudbees/sda/startup to the init.d directory '/etc/rc.d/init.d' and make corresponding links in /etc/rcX.d directories.When the installation is complete, the following prompt displays:
OK: Installation successful!