Interactive Command-Line Installation

4 minute readReference

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 sudo privileges

  • (UNIX or macOS only) Any non-root account without sudo privileges

Installing agents as the root user

To install agents and tools on UNIX or macOS machines using root or an account with sudo privileges:

  1. Obtain the UNIX or macOS installer file for your agent platform as described in Non-Server Platform UNIX Agent Installation Method .

  2. Log in as root.

  3. Enter chmod +x ./commander_<OStype>.bin to ensure that the installer is executable.

    where <OStype> is the agent platform. For example:

    chmod +x ./commander_<OStype>.bin
  4. Run ./commander_<OStype>.bin.

    The following prompts appear:

    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 agent or press Enter.

    You can also install the tools only by entering Tools. The agent and tools are installed. The following prompts appear:

    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):
  5. Enter the destination directory path.

    The following prompt appears:

    Enter an existing user to own installed agent files and run agent processes:

  6. Enter the name of the user to own the CloudBees CD/RO agent files and run the agent processes.

    The following prompt appears:

    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>'):

  7. Enter the group name of the user to own the CloudBees CD/RO agent files and run the agent processes or press Enter to use the user’s primary group.

    The following prompt appears:

    Enter the agent port (default is 7800):

  8. 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 is complete, the following prompt appears:

    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.

Running the installer without root or sudo privileges is not recommended. 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:

  1. Log in as the user to own the installed agent files and run the agent processes.

  2. Obtain the UNIX or macOS installer file for your agent platform as described in Non-Server Platform UNIX Agent Installation Method .

  3. Run chmod +x ./commander_<OStype>.bin to ensure that the installer is executable.

    <OStype> is the agent platform. For example:

    chmod +x ./commander_<OStype>.bin
  4. Enter ./commander_<OStype>.bin --nonRoot to start the installation.

    The following prompts appear:

    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.
  5. Enter agent or press Enter.

    (You can also install the tools only by entering Tools.) The agent and tools will be installed. The following prompts appear:

    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):
  6. Enter the destination directory path.

    If you lack sufficient privileges on the destination directory, the following error appears, 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 appear:

    Directory "/opt/cloudbees/sda" already exists.
    +
    Do you want to delete and overwrite it (Y/n)?
  7. If the directory already exists, enter Y to overwrite it.

    The following prompts appear:

    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>'):
  8. Enter the group name of the user to own the CloudBees CD/RO agent files and run the agent processes or press Enter to use the user’s primary group.

    The group that the agent runs as must have permission to write to the $INSTALL_DIRECTORY/log directory.

    NOTE:

    If you are not a member of the group, the following prompt appears, 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 appears:

    Enter the agent port (default is 7800):

  9. 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 appear. 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 appears:

OK: Installation successful!