Connect hybrid machines to Azure using a deployment script

You can enable Azure Arc-enabled servers for one or a small number of 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.

This method requires that you have administrator permissions on the machine to install and configure the agent. On Linux, by using the root account, and on Windows, you are member of the Local Administrators group.

Before you get started, be sure to review the prerequisites and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see supported Azure regions.

If you don't have an Azure subscription, create a trial subscription before you begin.

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. From your browser, sign in to the Azure portal.

2. On the Azure Arc - Machines page, select Add at the upper left.

3. On the Add servers with Azure Arc page, under the Add a single server tile, select Generate script.

4. On the Basics page, provide the following:

   1. In the Project Details section, select the Subscription and Resource group the machine will be managed from.
   2. In the Region drop-down list, select the Azure region to store the servers metadata.
   3. In the Operating system drop-down list, select the operating system that the script is configured to run on.
   4. In the Connectivity method section, choose how the Azure Connected Machine agent should connect to the internet:
      • Public endpoint
      • Proxy server—If the machine is communicating through a proxy server, enter the proxy server IP address or the name and port number that the machine will use in the format http://<proxyURL>:<proxyport>.
      • Private endpoint—If the machine is communicating through a private endpoint, select an existing private link scope and endpoint or create a new one.
   5. In the Automanage machine best practices section, you may enable automanage if you want to onboard and configure best practice services like Machine configuration and Insights, based on your server needs.
   6. Select Next to go to the Tags page.

5. On the Tags page, review the default Physical location tags suggested and enter a value, or specify one or more Custom tags to support your standards.

6. Select Next to Download and run script page.

7. On the Download and run script page, review the summary information, and then select Download. If you still need to make changes, select Previous.

Install and validate the agent on Windows

Install manually

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 from the Microsoft Download Center.

If the machine needs to communicate through a proxy server to the service, after you install the agent you need to run a command that's described in the steps below. This command sets the proxy server system environment variable https_proxy. Using this configuration, the agent communicates through the proxy server using the HTTP protocol.

If you are unfamiliar with the command-line options for Windows Installer packages, review Msiexec standard command-line options and Msiexec 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 that exist, run the following command.

   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.

2. If the machine needs to communicate through a proxy server, to set the proxy server environment variable, run the following command:

   [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
   

   For more information, see Agent-specific proxy configuration.

3. After installing the agent, you need to configure it to communicate with the Azure Arc service by running the following command:

   "%ProgramFiles%\AzureConnectedMachineAgent\azcmagent.exe" connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID"
   

Install with the scripted method

1. Log in to the server.

2. Open an elevated PowerShell command prompt.

   Note

   The script only supports running from a 64-bit version of Windows PowerShell.

3. Change to the folder or share that you copied the script to, and execute it on the server by running the ./OnboardingScript.ps1 script.

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 and validate the agent on Linux

The Connected Machine agent for Linux is provided in the preferred package format for the distribution (.RPM or .DEB) that's hosted in the Microsoft package repository. The shell script bundle Install_linux_azcmagent.sh 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. Using this configuration, 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.

The following example downloads the agent and installs it:

# 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

1. To download and install the agent, run the following commands. If your machine needs to communicate through a proxy server to connect to the internet, include the --proxy parameter.

   # 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-url}:{proxy-port}"
   

2. After installing the agent, you need to configure it to communicate with the Azure Arc service by running the following command:

   azcmagent connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID" --cloud "cloudName"
   if [ $? = 0 ]; then echo "\033[33mTo view your onboarded server(s), navigate to https://portal.azure.cn/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.HybridCompute%2Fmachines\033[m"; fi
   

Install with the scripted method

1. Log in to the server with an account that has root access.

2. Change to the folder or share that you copied the script to, and execute it on the server by running the ./OnboardingScript.sh script.

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 to verify that the server has successfully connected. View your machines in the Azure portal.

Next steps

• Troubleshooting information can be found in the Troubleshoot Connected Machine agent guide.

• Review the Planning and deployment guide to plan for deploying Azure Arc-enabled servers at any scale and implement centralized management and monitoring.

• Learn how to manage your machine using Azure Policy, for such things as VM guest configuration, verify the machine is reporting to the expected Log Analytics workspace, and much more.