How to Install the Microsoft Connected Machine Agent (Arc Agent)

The Microsoft Connected Machine agent, often referred to as the Arc agent, is a critical component for managing and governing your on-premises and multi-cloud servers within the Azure environment. It allows you to extend Azure management services to your machines regardless of where they reside, bringing them under the umbrella of Azure Resource Manager. This includes capabilities like Azure Policy, Azure Security Center, Update Management, and more. This article provides a comprehensive guide on how to install the Arc agent, covering various deployment scenarios and troubleshooting tips.

Table of Contents

Understanding The Arc Agent And Its Benefits

Before diving into the installation process, it’s crucial to understand what the Arc agent is and why it’s beneficial. The Arc agent isn’t a traditional agent that constantly pushes data to Azure. Instead, it acts as a bridge, enabling Azure to communicate with your servers using standard protocols. This means you don’t need to migrate your existing infrastructure to Azure to benefit from its management features.

The primary benefits of using the Arc agent include:

Centralized Management: Manage all your servers, whether on-premises, in other clouds (AWS, GCP), or at the edge, from a single pane of glass within the Azure portal.
Azure Policy Enforcement: Apply Azure policies to your non-Azure servers, ensuring compliance and security standards are met across your entire infrastructure.
Azure Security Center Integration: Extend Azure Security Center’s threat detection and vulnerability assessment capabilities to your hybrid environment.
Update Management: Automate patching and updates for your servers, reducing the risk of security vulnerabilities.
Simplified Governance: Improve governance and compliance by managing your entire IT estate using Azure’s robust management tools.
Automation and Scripting: Utilize Azure Automation to automate tasks on your connected machines, streamlining operations.

Prerequisites For Installing The Arc Agent

Before you begin the installation, ensure you have the necessary prerequisites in place. Failing to meet these requirements can lead to installation errors or unexpected behavior.

Here’s a checklist of prerequisites:

Azure Subscription: You need an active Azure subscription. If you don’t have one, you can create a free account.
Azure Permissions: You need appropriate permissions to register machines with Azure Arc. The “Azure Connected Machine Onboarding” role is generally sufficient, along with permissions to create resource groups if necessary.
Supported Operating System: The Arc agent supports a wide range of operating systems, including Windows Server and various Linux distributions (Ubuntu, Red Hat, CentOS, SUSE, etc.). Check the official Microsoft documentation for the most up-to-date list of supported operating systems and their versions.
Connectivity: The machine you’re connecting needs outbound connectivity to Azure services over HTTPS (port 443). Specific URLs are required, which are detailed in the Microsoft documentation.
Service Principal (Optional): For automated deployments or deployments at scale, using a service principal is recommended. You’ll need to create a service principal with the “Contributor” role at the scope where you want to register the machines.
PowerShell or Bash: Depending on your operating system and deployment method, you’ll need PowerShell (for Windows) or Bash (for Linux) installed.
Azure CLI (Recommended): While not strictly required, the Azure CLI is highly recommended for managing Azure resources and generating the installation script.
Hybrid Connectivity (Proxy Server): If your server requires to go through a proxy server, make sure that the Arc Agent is configured to connect via the proxy server.

Step-by-Step Installation Guide

The installation process involves downloading the agent package, configuring it with your Azure details, and running the installation script. The following sections outline the steps for both Windows and Linux environments.

Installing The Arc Agent On Windows Server

Login to the Azure Portal: Open your web browser and navigate to the Azure portal (portal.azure.com).
Search for Azure Arc: In the search bar at the top of the portal, type “Azure Arc” and select “Azure Arc” from the results.
Add a Machine: On the Azure Arc overview page, click on “Add” under “Servers.”
Generate the Installation Script:
- Select “Add servers using interactive script.”
- Specify the resource group where you want to register the machine. If the resource group doesn’t exist, create a new one.
- Choose the region for the metadata of the connected machine. Select a region geographically closest to your machine.
- Select the operating system (Windows).
- Choose the connectivity method (public endpoint or private endpoint).
- If you’re using a proxy server, configure the proxy settings.
- Review the script and click “Download.” This will download a PowerShell script.
Run the PowerShell Script:
- Copy the downloaded PowerShell script to the Windows Server you want to connect.
- Open PowerShell as an administrator.
- Navigate to the directory where you saved the script.
- Execute the script using the command: .\OnboardingScript.ps1 (replace “OnboardingScript.ps1” with the actual name of your script).
- The script will download the Arc agent, configure it with your Azure details, and register the machine with Azure Arc.
Verify the Installation:
- After the script completes successfully, go back to the Azure portal and navigate to the resource group you specified earlier.
- You should see a new resource representing your connected Windows Server.
- The status of the machine should be “Connected.”

Installing The Arc Agent On Linux

Login to the Azure Portal: Open your web browser and navigate to the Azure portal (portal.azure.com).
Search for Azure Arc: In the search bar at the top of the portal, type “Azure Arc” and select “Azure Arc” from the results.
Add a Machine: On the Azure Arc overview page, click on “Add” under “Servers.”
Generate the Installation Script:
- Select “Add servers using interactive script.”
- Specify the resource group where you want to register the machine. If the resource group doesn’t exist, create a new one.
- Choose the region for the metadata of the connected machine. Select a region geographically closest to your machine.
- Select the operating system (Linux).
- Choose the connectivity method (public endpoint or private endpoint).
- If you’re using a proxy server, configure the proxy settings.
- Review the script and click “Download.” This will download a Bash script.
Run the Bash Script:
- Copy the downloaded Bash script to the Linux server you want to connect.
- Open a terminal.
- Navigate to the directory where you saved the script.
- Make the script executable using the command: chmod +x ./OnboardingScript.sh (replace “OnboardingScript.sh” with the actual name of your script).
- Execute the script using the command: sudo ./OnboardingScript.sh (you’ll likely need sudo privileges).
- The script will download the Arc agent, configure it with your Azure details, and register the machine with Azure Arc.
Verify the Installation:
- After the script completes successfully, go back to the Azure portal and navigate to the resource group you specified earlier.
- You should see a new resource representing your connected Linux server.
- The status of the machine should be “Connected.”

Automated Deployment Using A Service Principal

For large-scale deployments, using a service principal is highly recommended to automate the installation process. A service principal is a security identity within Azure Active Directory that applications, services, and automation tools can use to access specific Azure resources.

Here’s how to use a service principal for Arc agent installation:

Create a Service Principal: You can create a service principal using the Azure CLI.

bash az ad sp create-for-rbac --name "ArcAgentSP" --role "Contributor" --scopes "/subscriptions/<your_subscription_id>"

Replace <your_subscription_id> with your Azure subscription ID.
Important: Securely store the appId and password (or clientSecret) that are outputted after running the command. These are the credentials for your service principal.
Modify the Installation Script:
- When generating the installation script in the Azure portal, select the option to use a service principal.
- Provide the appId (client ID), password (client secret), and tenant ID of your service principal.
Run the Script: Execute the generated script as described in the previous sections for Windows or Linux. The script will use the service principal credentials to authenticate with Azure, automating the registration process.

Troubleshooting Common Issues

While the installation process is generally straightforward, you might encounter some common issues. Here are some troubleshooting tips:

Connectivity Problems: If the script fails to download the agent package or connect to Azure services, check your network connectivity. Ensure that the server has outbound access to the required Azure endpoints over HTTPS (port 443). If you’re using a proxy server, verify that the proxy settings are correctly configured in the script.
Permission Errors: If you encounter permission errors, make sure you’re running the script with administrator privileges (on Windows) or using sudo (on Linux). Also, verify that the Azure account you’re using has the necessary permissions to register machines with Azure Arc.
Agent Not Connecting: After the installation completes, it might take a few minutes for the agent to connect to Azure. If the machine’s status in the Azure portal remains “Disconnected” for an extended period, check the agent logs on the server for any errors.
- Windows: The agent logs are typically located in C:\ProgramData\AzureConnectedMachineAgent\Log.
- Linux: The agent logs are typically located in /var/opt/azcmagent/log.
Script Errors: Carefully review the error messages displayed in the terminal or PowerShell window when running the script. These messages often provide clues about the cause of the problem. Double-check that you’ve provided the correct Azure subscription ID, resource group name, and other configuration parameters.
Proxy Configuration Issues: Incorrect proxy server settings are a common cause of installation failures. Ensure that the proxy server is reachable from the server you’re trying to connect and that the proxy settings are correctly configured in the installation script. Check to make sure that the proxy address is in the format of http://<proxy_address>:<proxy_port> or https://<proxy_address>:<proxy_port>.
DNS Resolution: Ensure that the server can resolve the necessary Azure service endpoints through DNS. If you’re using a custom DNS server, verify that it’s correctly configured to resolve Azure’s DNS names.
Time Synchronization: Ensure that the server’s time is synchronized with a reliable time source. Time synchronization issues can sometimes cause authentication problems.

Verifying The Agent Installation

After installing the Arc agent, it’s crucial to verify that it’s functioning correctly. Here are several ways to verify the installation:

Azure Portal: As mentioned earlier, the primary way to verify the installation is by checking the status of the connected machine in the Azure portal. Navigate to the resource group where you registered the machine and look for the resource representing your server. The status should be “Connected.”
Agent Status Command: The Arc agent provides a command-line tool that you can use to check its status.
- Windows: Open PowerShell as an administrator and run the command: azcmagent show
- Linux: Open a terminal and run the command: azcmagent show
This command will display information about the agent, including its status, version, and configuration settings.
Agent Logs: As mentioned in the troubleshooting section, the agent logs contain valuable information about its operation. Check the logs for any errors or warnings that might indicate a problem.
Azure Activity Log: You can also check the Azure Activity Log for events related to the connected machine. This can help you track when the machine was registered, when policies were applied, and other relevant events.
Azure Resource Graph Explorer: Use Azure Resource Graph Explorer to query all connected machines and their properties. This is helpful for verifying the installation across a large number of servers.

Uninstalling The Arc Agent

If you need to uninstall the Arc agent, follow these steps:

Windows:
1. Open the Control Panel and go to “Programs and Features.”
2. Find the “Azure Connected Machine Agent” in the list of installed programs.
3. Select the agent and click “Uninstall.”
4. Follow the on-screen prompts to complete the uninstallation.
5. Delete the connected machine resource in the Azure Portal.
Linux:
1. Open a terminal.
2. Run the following command: sudo /opt/azcmagent/uninstall.sh
3. Follow the on-screen prompts to complete the uninstallation.
4. Delete the connected machine resource in the Azure Portal.

Important: After uninstalling the agent, it’s essential to delete the corresponding resource in the Azure portal to remove the machine from your Azure inventory.

Conclusion

Installing the Microsoft Connected Machine agent (Arc agent) is a crucial step in extending Azure management and governance capabilities to your hybrid and multi-cloud environments. By following the steps outlined in this article, you can successfully install the agent on your Windows and Linux servers, automate the deployment process using a service principal, and troubleshoot common issues. Remember to regularly monitor the agent’s status and logs to ensure it’s functioning correctly and providing the desired level of management and security for your connected machines. The centralization of server management is a huge advantage in modern infrastructure.

What Is The Microsoft Connected Machine Agent (Arc Agent), And Why Would I Want To Install It?

The Microsoft Connected Machine Agent, also known as the Arc Agent, is a software package that enables you to manage on-premises, multicloud, and edge servers through the Azure portal. By installing the agent on your servers, you can extend Azure management capabilities, such as Azure Policy, Azure Monitor, Azure Security Center, and Azure Update Management, to these resources, regardless of their physical location. This provides a centralized and consistent way to govern and monitor your entire server infrastructure.

Essentially, the Arc Agent acts as a bridge, connecting your non-Azure servers to the Azure ecosystem. This connection allows you to treat these servers as Azure resources, enabling you to apply Azure’s security, compliance, and monitoring policies. By unifying management across your hybrid and multicloud environments, you can simplify operations, improve security posture, and gain better visibility into your entire IT estate.

What Are The Prerequisites For Installing The Arc Agent?

Before installing the Arc Agent, ensure your target servers meet specific requirements. First, the server must have outbound connectivity to Azure over HTTPS (port 443). Verify that your network firewalls and proxy settings allow communication with the required Azure endpoints. Supported operating systems include various versions of Windows Server and Linux distributions, which you can find on the official Microsoft Azure Arc documentation. You also need appropriate permissions in your Azure subscription to onboard the servers.

Furthermore, you need an Azure account with an active subscription and either the “Azure Connected Machine Onboarding” role or the “Contributor” role to register the server with Azure Arc. Consider the server’s system requirements, such as memory and CPU, as the Arc Agent consumes resources. Also, review any network configuration needs such as DNS resolution to Azure services. Finally, make sure the server is able to retrieve the necessary installation packages from either Microsoft repositories or local storage.

How Do I Install The Arc Agent On A Windows Server?

Installing the Arc Agent on a Windows Server involves downloading the agent package and running an installation script. You can download the Windows Agent package (AzureConnectedMachineAgent.msi) directly from the Azure portal or via a PowerShell command. Once downloaded, open a PowerShell console as an administrator and use the following command to install the agent: `msiexec.exe /i AzureConnectedMachineAgent.msi /quiet /l*v! install.log`. This command performs a silent installation, and you can check the install.log file for any errors.

After the installation, you need to connect the agent to your Azure subscription. This is typically done using the `azcmagent connect` command in PowerShell. This command requires you to authenticate with your Azure account, select the appropriate subscription, resource group, and Azure region. Follow the prompts provided by the `azcmagent connect` command to successfully onboard your Windows Server to Azure Arc. Once complete, you should see your server listed as an Azure Arc-enabled server in the Azure portal.

How Do I Install The Arc Agent On A Linux Server?

The installation process for the Arc Agent on a Linux server involves downloading the appropriate package for your Linux distribution and running an installation command. Download the installation package (e.g., .deb for Debian/Ubuntu or .rpm for Red Hat/CentOS/SUSE) directly from the Azure portal or via a command-line tool. Once downloaded, use the appropriate package manager to install the agent. For example, on Debian/Ubuntu, use `sudo apt install ./AzureConnectedMachineAgent.deb`, and on Red Hat/CentOS/SUSE, use `sudo yum localinstall ./AzureConnectedMachineAgent.rpm` or `sudo zypper install ./AzureConnectedMachineAgent.rpm`.

After the installation, you need to connect the agent to your Azure subscription. Similar to Windows, you use the `azcmagent connect` command. Open a terminal and run `sudo azcmagent connect`. This command will prompt you to authenticate with your Azure account, select the appropriate subscription, resource group, and Azure region. Complete the authentication and resource selection process as instructed. Upon successful completion, your Linux server will be registered as an Azure Arc-enabled server in the Azure portal.

What Are Some Common Troubleshooting Steps If The Arc Agent Installation Fails?

If the Arc Agent installation fails, start by checking the installation logs. For Windows, examine the install.log file created during the MSI installation. For Linux, check the system logs using tools like `journalctl` or the distribution-specific logs in `/var/log`. Look for any error messages or warnings that might indicate the cause of the failure. Common issues include missing dependencies, incorrect permissions, or network connectivity problems.

Another common cause of installation failure is related to network configuration. Ensure that the server can communicate with the required Azure endpoints over HTTPS (port 443). Verify that your firewall rules and proxy settings are correctly configured. Also, double-check your Azure subscription and account permissions to ensure you have the necessary rights to onboard servers. Finally, consider verifying that the server meets the minimum system requirements for the Arc Agent.

How Do I Update The Arc Agent After It’s Installed?

Updating the Arc Agent involves downloading the latest version of the agent package and running the appropriate upgrade command. For Windows servers, download the latest AzureConnectedMachineAgent.msi file and run the following command in an elevated PowerShell prompt: `msiexec.exe /i AzureConnectedMachineAgent.msi REINSTALL=ALL REINSTALLMODE=omus /quiet /l*v! upgrade.log`. This command performs a silent upgrade of the agent.

For Linux servers, download the latest package for your distribution (e.g., .deb or .rpm). Use the package manager to upgrade the agent. For example, on Debian/Ubuntu, use `sudo apt install ./AzureConnectedMachineAgent.deb`, and on Red Hat/CentOS/SUSE, use `sudo yum localupdate ./AzureConnectedMachineAgent.rpm` or `sudo zypper install ./AzureConnectedMachineAgent.rpm`. Regularly updating the Arc Agent is essential to ensure you have the latest features, bug fixes, and security patches.

How Do I Remove The Arc Agent From A Server?

Removing the Arc Agent requires uninstalling the software package from the server’s operating system. On Windows servers, you can uninstall the agent through the Control Panel or using PowerShell. In PowerShell, run `msiexec.exe /x AzureConnectedMachineAgent.msi /quiet /l*v! uninstall.log` to perform a silent uninstall. Ensure you run PowerShell as an administrator to successfully remove the agent.

On Linux servers, use the appropriate package manager to uninstall the agent. For Debian/Ubuntu, use `sudo apt remove azure-connectedmachine-agent`. For Red Hat/CentOS/SUSE, use `sudo yum remove AzureConnectedMachineAgent` or `sudo zypper remove AzureConnectedMachineAgent`. After uninstalling the agent, it’s also recommended to remove the server’s resource entry from the Azure portal to completely disconnect the server from Azure Arc. Failure to do so could cause confusion and inaccurate inventory.