Setting Up a Build Agent on RHEL: Hostname, User, and Sudo Configuration

In this blog, I’ll walk you through the process of setting up a build agent on a Red Hat Enterprise Linux (RHEL) system. We’ll configure a unique hostname, create a dedicated deployment user (udeploy), and assign the necessary permissions to ensure smooth, secure build and deployment operations.

Each step includes detailed commands and explanations to help you understand not just the "how," but also the "why" behind the setup.

1. Set a Unique Hostname

• When managing multiple build agents, assigning a unique hostname helps you quickly identify and manage them, especially in clustered environments or CI/CD pipelines. In this guide, we’ll name our agent: buildagent.

• Command:

    sudo hostnamectl set-hostname buildagent
  

• Explanation

  1. hostnamectl : A system utility used to view or modify the hostname of your Linux system. 2. set-hostname : The subcommand that sets the system's hostname. 3. buildagent : The unique name we're assigning to this agent.

✅ Why it matters:
A clearly named agent prevents confusion during deployments, log analysis, and automation tasks. It also ensures better monitoring and reporting in tools like Jenkins, Azure DevOps, or GitLab.

2. Update the System

• Before installing or configuring anything on your build agent, it’s important to make sure your system is fully updated. This ensures compatibility with modern software and patches any known security vulnerabilities.

• Command:

    yum update -y
  

• Explanation:

  1. yum: The default package manager for RHEL-based distributions. 2. update: Upgrades all installed packages to their latest versions. 3. -y: Automatically confirms prompts during the update process.

✅ Why it matters:
Updating ensures the system libraries and tools are current, reducing the risk of deployment failures due to outdated dependencies or security flaws.

📌 Optional Tip:
After the update completes, you can reboot the system (if required) using:

sudo reboot

3. Create a Dedicated User: udeploy

• Using a dedicated user account like udeploy for deployments enhances security and keeps automation tasks separate from the root user.

• Commands:

    sudo useradd udeploy
    sudo passwd udeploy
  

• Explanation:

  1. useradd: Creates a new user account. 2. passwd: Sets or changes the password for the specified user.

4. Grant Sudo Access to udeploy

• To allow udeploy to perform administrative tasks (like installing packages or restarting services), give it password-less sudo access.

  1. Steps:

• Edit the sudoers file:

    vi /etc/sudoers
  

• Add the following line at the bottom:

    udeploy ALL=(ALL) NOPASSWD:ALL
  

• This step ensures the udeploy user can manage deployments and perform administrative tasks effortlessly.

5. Switch to udeploy and Validate Access

• After configuring the user and permissions, switch to the udeploy account to verify its functionality.

• Commands:

    su - udeploy
    sudo -i
  

This ensures the udeploy user is ready to handle deployment and administrative tasks securely.

6. Check the connectivity of the website

• Before installing or registering the agent, verify that your system can connect to Azure DevOps. This ensures that network issues don’t disrupt the build agent setup.

  1. Commands:

      curl <http://dev.azure.com/your-project>
     

Explanation

1. curl : - A command-line tool for transferring data using various protocols. 2. sudo -i: Your Azure DevOps organization URL (Test--Project is the org name).

• My organization name is Test—Project & project name is Practice_Lecture

  • 

• Checking connectivity for my project Test—Project

  •        curl <http://dev.azure.com/https://dev.azure.com/Test--Project
    

7. Mounting the Additional SSD Disk

Purpose of Mounting an External SSD

Incorporating an external SSD into the system serves to enhance both performance and storage management. This strategic upgrade is particularly beneficial for hosting a VSTS (Azure DevOps) build agent due to the following reasons:

1. Improved Performance: SSDs offer superior read/write speeds compared to traditional HDDs. This speed significantly reduces build times, improves cache performance, and accelerates deployment processes.

2. Optimized Storage Management: By isolating the VSTS build agent’s workload on a dedicated SSD, the primary OS disk remains free of intensive I/O operations. This separation minimizes disk contention, increases system reliability, and extends the lifespan of both disks.

3. Efficient Storage Management: A separate SSD ensures sufficient space for build outputs, caches, and temporary files, improving overall reliability.

Objective:
The additional SSD will be dedicated to storing build outputs, temporary files, and cache data associated with the VSTS agent. This ensures efficient and streamlined operations for CI/CD pipelines.

📌 Need More Help?
Check out my other article: How to Mount an External Disk on RHEL for DevOps Workloads (add your actual link)

8. Prepare Directories for Build Artifacts

• To manage build artifacts and agent binaries, it's essential to set up proper directories with appropriate permissions. We’ll create a dedicated directory in the /app path and ensure the udeploy user has full access.

📁 Default Root Directory “/

The root directory / serves as the base of the Linux file system hierarchy. In many build setups, paths under / (like /mnt, /app, etc.) are used to store application-specific data or binarie

• Perform this step from the udeploy user

• “/” is the place where build images will get saved

• New directory in /app/

  • Commands:

      mkdir app    
      cd /app/
      sudo mkdir azagent
    

• Give permission to deploy user

  • Commands:

      sudo chown udeploy:udeploy azagent
    

9. Configure Agent Pool in Azure DevOps UI

• Before downloading and registering the build agent, you must create an Agent Pool in Azure DevOps. Agent pools allow multiple pipelines to share a group of build agents, improving efficiency and control.

• Why configure an agent pool?

  • Organizes and groups your agents logically.

  • Controls which pipelines can use which agents.

  • Makes it easy to scale agent infrastructure across environments.

• Steps to add an agent pool:

  1. Navigate to the Agent Pools section in Azure DevOps UI (dev.azure.com/Test--Practice/Practice-lecture).

     • 

     • 

     • 

  2. Add a new agent pool:

     • Click Add Pool → Provide a name for the pool (e.g., Linux-Agents).

     • Grant access to all pipelines (optional but recommended).

       • 

       • 

       • 

       • 

  3. Open the created agent pool:

     • Click on the pool → Select New Agent.

       • 

  4. Select agent details:

     • Choose Linux as the agent type.

       • 

       • 

       • 

     • Copy the command link provided beside Download agent.

• Command to download the agent:

    cd /azagent
    wget (paste the link copied from Azure DevOps UI)
  

  

  • Explanation

    1. wget: Downloads the agent package using the link provided in Azure DevOps. /azagent: Directory where the agent will be downloaded (you can use another directory if preferred).

10: Unzip the Agent Package

• Why unzip the package?

  • After downloading the Azure DevOps agent package, it needs to be extracted before configuration. This step prepares the files needed to connect and run the agent.

• 💡 Why unzip the package?

  Azure DevOps distributes agents as compressed .tar.gz files. Extracting this package reveals the scripts and binaries needed for configuration, execution, and service setup.

• Command:

    tar -xvzf vsts-agent-linux-x64-3.239.1.tar.gz
  

• Explanation:

  • tar -xvzf: Extracts a .tar.gz file.

  • vsts-agent-linux-x64-3.239.1.tar.gz: Name of the downloaded agent file (replace with the actual file name).

  • Make sure you're in the /app/azagent/ directory before running this command.

11. ⚙️ Configure the Agent

This is the most important step: registering the agent with Azure DevOps, linking it to the right agent pool, and setting up connectivity using a Personal Access Token (PAT).

This guide provides detailed steps for configuring an Azure DevOps agent, installing it as a service, and managing or removing configurations. Each step includes commands with explanations to ensure smooth execution.

• Why configure the agent?

  • Configuration connects the local build agent to Azure DevOps so it can execute pipeline jobs. This step ensures authentication, identification, and correct integration with the agent pool.

    📂 Step 1: Navigate to the Agent Directory

    • Command:

        cd /app/azagent/
      

      • Explanation:

        cd /opt/azagent/: Changes the directory to the agent installation folder.

⚙️ Step 2: Run the Configuration Script

• Command:

    ./config.sh --proxyurl <your-proxy-url>
  

  • Explanation

    1. ./config.sh: Launches the configuration script for the agent. 2. --proxyurl <your-proxy-url>: If your organization uses a proxy, include its URL (replace <your-proxy-url> with the actual URL). If not, omit this option.

3. Answer the configuration prompts:

• Example input during the script execution:

    Enter Server Url > https://dev.azure.com/{organisation-name or project name}
    Enter authentication type (press enter for PAT) -> (Just press Enter)
    Enter Personal access token -> <Your-PAT>
    Enter Agent Pool -> Linux-Agents
    Enter Agent Name -> buildagent
    Enter Work Folder -> (Press Enter to use default)
  

• Explanation:

  • Replace {organisation-name} with your Azure DevOps organization name.

  • Use a valid Personal Access Token (PAT) generated in Azure DevOps for authentication.

  • Choose the correct Agent Pool (e.g., Linux-Agents) and provide an Agent Name (e.g., buildagent).

  • The Work Folder is the directory where temporary files are stored; pressing Enter will use the default location.

Step 12: Install and Start the Agent

• Why install the agent as a service?

  • Installing the agent as a service ensures it starts automatically when the system boots.

1. Install the agent as a service:

• Command:

    sudo ./svc.sh install udeploy
  

• Explanation:

  • svc.sh install: Creates a service file to manage the agent.

  • udeploy: The username under which the agent runs. If omitted, it defaults to the user invoking the sudo command.

    • 

2. Start the service:

• Command:

    sudo ./svc.sh start
  

• Explanation:

  • svc.sh start: Starts the agent service, allowing it to begin processing pipeline jobs.

    • 

3. Verify the agent in Azure DevOps UI:

• Navigate to the Agent Pool section in Azure DevOps and confirm that the agent is displayed as "Online."

  • 

Step 13: Remove All Configurations (Optional)

• Why remove configurations?

  • To decommission or reconfigure the agent, removing its settings and stopping the service is necessary.

• Commands:

  
    sudo ./svc.sh stop
    sudo ./svc.sh uninstall
    ./config.sh remove
  

• Explanation:

  • svc.sh stop: Stops the running agent service.

  • svc.sh uninstall: Removes the service file created during installation.

  • config.sh remove: Deletes the agent's configuration, making it ready for a fresh setup.

Conclusion

Congratulations! You have successfully set up a build agent on Red Hat Enterprise Linux (RHEL). This agent is now ready to handle builds and deployments efficiently, providing a seamless experience for your CI/CD pipelines. Regularly monitor its performance and update configurations as needed to ensure optimal operation.