Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Connect hybrid machines to Azure using a deployment script description: In this article, you learn how to install the agent and connect machines to Azure by using Azure Arc-enabled servers using the deployment script you create in the Azure portal. ms.date: 01/28/2026 ms.topic: how-to ms.custom: linux-related-content # Customer intent: "As a system administrator, I want to automate the installation and onboarding of hybrid machines to Azure using a deployment script, so that I can efficiently manage my servers and ensure their connectivity with Azure Arc." --- # Connect hybrid machines to Azure using a deployment script You can enable Azure Arc-enabled servers for one or more Windows or Linux machines in your environment by performing a set of steps manually. Or you can use an automated method by running a template script that we provide. This script automates the download and installation of both agents. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn) before you begin. [!INCLUDE [sql-server-auto-onboard](includes/sql-server-auto-onboard.md)] ## Prerequisites * This method requires that you have administrator permissions on the machine to install and configure the agent. On Linux, use the root account, and on Windows, you must be a member of the Local Administrators group. * Before you get started, review the [Connected Machine agent prerequisites](prerequisites.md) and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see [supported Azure regions](overview.md#supported-regions). > [!NOTE] > Follow best security practices and *avoid* using an Azure account with **Owner** access to onboard servers. Instead, use an account that only has the **Azure Connected Machine Onboarding** or **Azure Connected Machine Resource Administrator** role assignment. To learn more, see [Azure Identity Management and access control security best practices](/azure/security/fundamentals/identity-management-best-practices#use-role-based-access-control). ## Generate the installation script from the Azure portal Use the Azure portal to create a script that automates the agent download and installation and establishes the connection with Azure Arc. To complete the process, perform the following steps: 1. At the top of the [Azure portal](https://portal.azure.com), search for and select **Azure Arc**. 1. In the service menu, expand **Infrastructure**, then select **Machines**. 1. Select **Onboard/Create**, then select **Onboard existing machines**. 1. On the **Basics** page, provide the following: 1. Select the **Subscription** and **Resource group** for the machines. 1. Under **Region**, select the Azure region to store the servers' metadata. 1. Under **Operating system**, select the operating system that the script is configured to run on. 1. Under **Connectivity method**: 1. Select either **Public endpoint** or **Private endpoint**. If you select **Private endpoint**, you can either select an existing private link scope or create a new one. 1. If you want to use a **Proxy server URL**, enter the proxy server IP address or the name and port number that the machine uses in the format `http://<proxyURL>:<proxyport>`. 1. If you selected **Public endpoint** and you want to use [Azure Arc Gateway](arc-gateway.md), select an existing **Gateway resource** or create a new one. 1. Under **Authentication**, select **Authenticate machines manually**, then select **Next**. 1. Under **Tags**, review the default **Physical location tags** suggested and enter a value, or specify one or more **Custom tags** to support your standards. 1. Select **Next**. 1. Under **Download and run script**, review the summary information. If you need to make changes, select **Previous** and make necessary edits. 1. Select **Download**, then select **Close**. For Windows, you're prompted to save `OnboardingScript.ps1`, and for Linux `OnboardingScript.sh` to your computer. ## Install the agent on Windows # [Manual install](#tab/win-manual) You can install the Connected Machine agent manually by running the Windows Installer package *AzureConnectedMachineAgent.msi*. You can download the latest version of the [Windows agent Windows Installer package](https://aka.ms/AzureConnectedMachineAgent) from the Microsoft Download Center. > [!NOTE] > > * To install or uninstall the agent, you must have *Administrator* permissions. > * You must first download and copy the installer package to a folder on the target server, or from a shared network folder. If you run the installer package without any options, it starts a setup wizard that you can follow to install the agent interactively. If the machine needs to communicate through a proxy server to the service, after you install the agent you need to run a command described in the following steps. This command sets the proxy server system environment variable `https_proxy`. When this configuration is used, the agent communicates through the proxy server using the HTTP protocol. If you're unfamiliar with the command-line options for Windows Installer packages, review [Msiexec standard command-line options](/windows/win32/msi/standard-installer-command-line-options) and [Msiexec command-line options](/windows/win32/msi/command-line-options). For example, run the installation program with the `/?` parameter to review the help and quick reference option. ``` msiexec.exe /i AzureConnectedMachineAgent.msi /? ``` 1. To install the agent silently and create a setup log file in the `C:\Support\Logs` folder, run the following command. ```powershell msiexec.exe /i AzureConnectedMachineAgent.msi /qn /l*v "C:\Support\Logs\Azcmagentsetup.log" ``` If the agent fails to start after setup is finished, check the logs for detailed error information. The log directory is *%ProgramData%\AzureConnectedMachineAgent\log*. 1. If the machine needs to communicate through a proxy server, set the proxy server environment variable by running the following command. Replace `{proxy-url}` with your proxy server address (for example, `proxy.example.com`) and `{proxy-port}` with the port number (for example, `8080`). ```powershell [Environment]::SetEnvironmentVariable("https_proxy", "http://{proxy-url}:{proxy-port}", "Machine") $env:https_proxy = [System.Environment]::GetEnvironmentVariable("https_proxy","Machine") # For the changes to take effect, the agent service needs to be restarted after the proxy environment variable is set. Restart-Service -Name HIMDS ``` > [!NOTE] > The agent doesn't support setting proxy authentication. For more information, see [Agent-specific proxy configuration](manage-agent.md#agent-specific-proxy-configuration). 1. After installing the agent, configure it to communicate with the Azure Arc service. **Parameters** - `--resource-group` (string, example: `myResourceGroup`) - `--tenant-id` (string, example: `aaaabbbb-0000-cccc-1111-dddd2222eeee`) - `--subscription-id` (string, example: `aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e`) - `--location` (string, example: `eastus`) - `--cloud` (string, example: `AzureCloud`) - `--proxy` (string, example: `http://proxy.example.com:8080`) ```powershell & "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" connect ` --resource-group "myResourceGroup" ` --tenant-id "aaaabbbb-0000-cccc-1111-dddd2222eeee" ` --location "eastus" ` --subscription-id "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e" ``` # [Scripted install](#tab/win-script) 1. Sign in to the server. 1. Open an elevated PowerShell command prompt. > [!NOTE] > The script only supports running from a 64-bit version of Windows PowerShell. 1. Change to the folder or share that you copied the script to using the `cd` command, and execute it on the server by running the `.\OnboardingScript.ps1` script. For example: ```powershell cd $env:USERPROFILE\Downloads .\OnboardingScript.ps1 ``` If the agent fails to start after setup is finished, check the logs for detailed error information. The log directory is *%ProgramData%\AzureConnectedMachineAgent\log*. --- ## Install the agent on Linux # [Manual install](#tab/linux-manual) The Connected Machine agent for Linux is provided in the preferred package format for the distribution (`.RPM` or `.DEB`) hosted in the Microsoft [package repository](https://packages.microsoft.com/). The [shell script bundle `Install_linux_azcmagent.sh`](https://aka.ms/azcmagent) performs the following actions: * Configures the host machine to download the agent package from packages.microsoft.com. * Installs the Hybrid Resource Provider package. Optionally, you can configure the agent with your proxy information by including the `--proxy "{proxy-url}:{proxy-port}"` parameter. When this configuration is used, the agent communicates through the proxy server using the HTTP protocol. The script also contains logic to identify the supported and unsupported distributions, and it verifies the permissions that are required to perform the installation. 1. To download and install the agent, run the following commands: ```bash # Download the installation package. wget https://aka.ms/azcmagent -O ~/Install_linux_azcmagent.sh # Install the Azure Connected Machine agent. bash ~/Install_linux_azcmagent.sh ``` If your machine needs to communicate through a proxy server to connect to the internet, include the `--proxy` parameter, for example: ```bash # Download the installation package. wget https://aka.ms/azcmagent -O ~/Install_linux_azcmagent.sh # Install the Azure Connected Machine agent. bash ~/Install_linux_azcmagent.sh --proxy "proxy.contoso.com:8080" ``` 1. After installing the agent, configure it to communicate with the Azure Arc service: **Parameters** - `--resource-group` (string, example: `myResourceGroup`) - `--tenant-id` (string, example: `aaaabbbb-0000-cccc-1111-dddd2222eeee`) - `--subscription-id` (string, example: `aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e`) - `--location` (string, example: `eastus`) - `--cloud` (string, example: `AzureCloud`) - `--proxy` (string, example: `http://proxy.example.com:8080`) ```bash azcmagent connect \ --resource-group "myResourceGroup" \ --tenant-id "aaaabbbb-0000-cccc-1111-dddd2222eeee" \ --location "eastus" \ --subscription-id "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e" \ --cloud "AzureCloud" ``` # [Scripted install](#tab/linux-script) 1. Sign in to the server with an account that has root access. 1. Change to the folder or share that you copied the script to, and execute it on the server by running the `./OnboardingScript.sh` script. ```bash cd ~/Downloads ./OnboardingScript.sh ``` If you get a "Permission denied" error, ensure the script is made executable: ```bash chmod +x ~/Downloads/OnboardingScript.sh ./OnboardingScript.sh ``` If the agent fails to start after setup is finished, check the logs for detailed error information. The log directory is `/var/opt/azcmagent/log`. --- ## Verify the connection with Azure Arc After you install the agent and configure it to connect to Azure Arc-enabled servers, go to the [Azure portal](https://aka.ms/hybridmachineportal) to verify that the server successfully connected. :::image type="content" source="./media/quick-enable-hybrid-vm/enabled-machine.png" alt-text="Screenshot showing a successful machine connection in the Azure portal." border="false"::: ## Next steps - Troubleshooting information can be found in the [Troubleshoot Connected Machine agent guide](troubleshoot-agent-onboard.md). - Review the [Planning and deployment guide](plan-at-scale-deployment.md) to plan for deploying Azure Arc-enabled servers at any scale and implement centralized management and monitoring. - You can manage your machines using [Azure Policy](/azure/governance/policy/overview) for tasks such as virtual machine (VM) [guest configuration](/azure/governance/machine-configuration/overview). Azure Policy also helps verify that machines are reporting to the expected Log Analytics workspace. You can also monitor your machines with [VM insights](/azure/azure-monitor/vm/vminsights-enable-policy) and other monitoring tools.