Managing and maintaining the Connected Machine agent

After initial deployment of the Azure Connected Machine agent, you may need to reconfigure the agent, upgrade it, or remove it from the computer. These routine maintenance tasks can be done manually or through automation (which reduces both operational error and expenses).

About the azcmagent tool

The azcmagent tool is used to configure the Azure Connected Machine agent during installation, or modify the initial configuration of the agent after installation. azcmagent.exe provides the following command-line parameters to customize the agent and view its status:

  • check - Troubleshoot network connectivity issues.
  • connect - Connect the machine to Azure Arc.
  • disconnect - Disconnect the machine from Azure Arc.
  • show - View agent status and its configuration properties (Resource Group name, Subscription ID, version, etc.), which can help when troubleshooting an issue with the agent. Include the -j parameter to output the results in JSON format.
  • config - View and change settings to enable features and control agent behavior.
  • logs - Create a .zip file in the current directory containing logs to assist you while troubleshooting.
  • version - Show the Connected Machine agent version.
  • -useStderr - Direct error and verbose output to stderr. Include the -json parameter to output the results in JSON format.
  • -h or --help - Show available command-line parameters. For example, to see detailed help for the Connect parameter, type azcmagent connect -h.
  • -v or --verbose - Enable verbose logging.

You can perform a connect and disconnect manually while logged on interactively, or with a Microsoft identity platform access token, or by using the same service principal you used to onboard multiple agents. If you didn't use a service principal to register the machine with Azure Arc-enabled servers, you can create a service principal now.

Note

You must have Administrator permissions on Windows or root access permissions on Linux machines to run azcmagent.

check

This parameter allows you to run network connectivity tests to troubleshoot networking issues between the agent and Azure services. The network connectivity check includes all required Azure Arc network endpoints, but does not include endpoints accessed by extensions you install.

When running a network connectivity check, you must provide the name of the Azure region (for example, eastus) that you want to test. It's also recommended to use the --verbose parameter to see the results of both successful and unsuccessful tests:

azcmagent check --location <regionName> --verbose

If you expect your server to communicate with Azure through an Azure Arc Private Link Scope, use the --enable-pls-check (--use-private-link on versions 1.17-1.19) parameter to run additional tests that verify the hostnames and IP addresses resolved for the Azure Arc services are private endpoints.

azcmagent check --location <regionName> --enable-pls-check --verbose

connect

This parameter specifies a resource in Azure Resource Manager and connects it to Azure Arc. You must specify the subscription and resource group of the resource to connect. Data about the machine is stored in the Azure region specified by the --location setting. The default resource name is the hostname of the machine unless otherwise specified.

A certificate corresponding to the system-assigned identity of the machine is then downloaded and stored locally. Once this step is completed, the Azure Connected Machine Metadata Service and guest configuration agent service begins synchronizing with Azure Arc-enabled servers.

To connect using a service principal, run the following command:

azcmagent connect --service-principal-id <serviceprincipalAppID> --service-principal-secret <serviceprincipalPassword> --tenant-id <tenantID> --subscription-id <subscriptionID> --resource-group <ResourceGroupName> --location <resourceLocation>

To connect using an access token, run the following command:

azcmagent connect --access-token <> --subscription-id <subscriptionID> --resource-group <ResourceGroupName> --location <resourceLocation>

To connect with your elevated logged-on credentials (interactive), run the following command:

azcmagent connect --tenant-id <TenantID> --subscription-id <subscriptionID> --resource-group <ResourceGroupName> --location <resourceLocation>

disconnect

This parameter specifies a resource in Azure Resource Manager to delete from Azure Arc. Running this parameter doesn't remove the agent from the machine; you must uninstall the agent separately. After the machine is disconnected, you can re-register it with Azure Arc-enabled servers by using azcmagent connect so a new resource is created for it in Azure.

Note

If you have deployed one or more Azure VM extensions to your Azure Arc-enabled server and you delete its registration in Azure, the extensions remain installed and may continue performing their functions. Any machine intended to be retired or no longer managed by Azure Arc-enabled servers should first have its extensions removed before removing its registration from Azure.

To disconnect using a service principal, run the following command:

azcmagent disconnect --service-principal-id <serviceprincipalAppID> --service-principal-secret <serviceprincipalPassword>

To disconnect using an access token, run the following command:

azcmagent disconnect --access-token <accessToken>

To disconnect with your elevated logged-on credentials (interactive), run the following command:

azcmagent disconnect

config

This parameter allows you to view and configure settings that control agent behavior.

To view a list of all the configuration properties and their values, run the following command:

azcmagent config list

To get the value for a particular configuration property, run the following command:

azcmagent config get <propertyName>

To change a configuration property, run the following command:

azcmagent config set <propertyName> <propertyValue>

If the property you're changing supports a list of values, you can use the --add and --remove flags to add or remove specific items without having to re-type the entire list:

azcmagent config set <propertyName> <propertyValue> --add

azcmagent config set <propertyName> <propertyValue> --remove

To clear a configuration property's value, run the following command:

azcmagent config clear <propertyName>

Upgrade the agent

The Azure Connected Machine agent is updated regularly to address bug fixes, stability enhancements, and new functionality. Azure Advisor identifies resources that are not using the latest version of the machine agent and recommends that you upgrade to the latest version. It will notify you when you select the Azure Arc-enabled server by presenting a banner on the Overview page or when you access Advisor through the Azure portal.

The Azure Connected Machine agent for Windows and Linux can be upgraded to the latest release manually or automatically depending on your requirements. Installing, upgrading, or uninstalling the Azure Connected Machine Agent will not require you to restart your server.

The following table describes the methods supported to perform the agent upgrade:

Operating system Upgrade method
Windows Manually
Microsoft Update
Ubuntu apt
SUSE Linux Enterprise Server zypper
RedHat Enterprise, Amazon, CentOS Linux yum

Windows agent

The latest version of the Azure Connected Machine agent for Windows-based machines can be obtained from:

Microsoft Update configuration

The recommended way of keeping the Windows agent up to date is to automatically obtain the latest version through Microsoft Update. This allows you to utilize your existing update infrastructure (such as Microsoft Endpoint Configuration Manager or Windows Server Update Services) and include Azure Connected Machine agent updates with your regular OS update schedule.

Windows Server doesn't check for updates in Microsoft Update by default. To receive automatic updates for the Azure Connected Machine Agent, you must configure the Windows Update client on the machine to check for other Microsoft products.

For Windows Servers that belong to a workgroup and connect to the Internet to check for updates, you can enable Microsoft Update by running the following commands in PowerShell as an administrator:

$ServiceManager = (New-Object -com "Microsoft.Update.ServiceManager")
$ServiceID = "7971f918-a847-4430-9279-4a52d1efe18d"
$ServiceManager.AddService2($ServiceId,7,"")

For Windows Servers that belong to a domain and connect to the Internet to check for updates, you can configure this setting at-scale using Group Policy:

  1. Sign into a computer used for server administration with an account that can manage Group Policy Objects (GPO) for your organization.

  2. Open the Group Policy Management Console.

  3. Expand the forest, domain, and organizational unit(s) to select the appropriate scope for your new GPO. If you already have a GPO you wish to modify, skip to step 6.

  4. Right-click the container and select Create a GPO in this domain, and Link it here....

  5. Provide a name for your policy such as "Enable Microsoft Update".

  6. Right-click the policy and select Edit.

  7. Navigate to Computer Configuration > Administrative Templates > Windows Components > Windows Update.

  8. Select the Configure Automatic Updates setting to edit it.

  9. Select the Enabled radio button to allow the policy to take effect.

  10. At the bottom of the Options section, check the box for Install updates for other Microsoft products at the bottom.

  11. Select OK.

The next time computers in your selected scope refresh their policy, they will start to check for updates in both Windows Update and Microsoft Update.

For organizations that use Microsoft Endpoint Configuration Manager (MECM) or Windows Server Update Services (WSUS) to deliver updates to their servers, you need to configure WSUS to synchronize the Azure Connected Machine Agent packages and approve them for installation on your servers. Follow the guidance for Windows Server Update Services or MECM to add the following products and classifications to your configuration:

  • Product Name: Azure Connected Machine Agent (select all 3 sub-options)
  • Classifications: Critical Updates, Updates

Once the updates are being synchronized, you can optionally add the Azure Connected Machine Agent product to your auto-approval rules so your servers automatically stay up to date with the latest agent software.

To manually upgrade using the Setup Wizard

  1. Sign in to the computer with an account that has administrative rights.

  2. Download the latest agent installer from https://aka.ms/AzureConnectedMachineAgent

  3. Run AzureConnectedMachineAgent.msi to start the Setup Wizard.

If the Setup Wizard discovers a previous version of the agent, it will upgrade it automatically. When the upgrade completes, the Setup Wizard closes automatically.

To upgrade from the command line

If you're unfamiliar with the command-line options for Windows Installer packages, review Msiexec standard command-line options and Msiexec command-line options.

  1. Sign on to the computer with an account that has administrative rights.

  2. Download the latest agent installer from https://aka.ms/AzureConnectedMachineAgent

  3. To upgrade the agent silently and create a setup log file in the C:\Support\Logs folder, run the following command:

    msiexec.exe /i AzureConnectedMachineAgent.msi /qn /l*v "C:\Support\Logs\azcmagentupgradesetup.log"
    

Linux agent

Updating the agent on a Linux machine involves two commands; one command to update the local package index with the list of latest available packages from the repositories, and another command to upgrade the local package.

You can download the latest agent package from Microsoft's package repository.

Note

To upgrade the agent, you must have root access permissions or an account that has elevated rights using Sudo.

Upgrade the agent on Ubuntu

  1. To update the local package index with the latest changes made in the repositories, run the following command:

    sudo apt update
    
  2. To upgrade your system, run the following command:

    sudo apt upgrade azcmagent
    

Actions of the apt command, such as installation and removal of packages, are logged in the /var/log/dpkg.log log file.

Upgrade the agent on Red Hat/CentOS/Oracle Linux/Amazon Linux

  1. To update the local package index with the latest changes made in the repositories, run the following command:

    sudo yum check-update
    
  2. To upgrade your system, run the following command:

    sudo yum update azcmagent
    

Actions of the yum command, such as installation and removal of packages, are logged in the /var/log/yum.log log file.

Upgrade the agent on SUSE Linux Enterprise

  1. To update the local package index with the latest changes made in the repositories, run the following command:

    sudo zypper refresh
    
  2. To upgrade your system, run the following command:

    sudo zypper update azcmagent
    

Actions of the zypper command, such as installation and removal of packages, are logged in the /var/log/zypper.log log file.

Renaming an Azure Arc-enabled server resource

When you change the name of a Linux or Windows machine connected to Azure Arc-enabled servers, the new name is not recognized automatically because the resource name in Azure is immutable. As with other Azure resources, you must delete the resource and re-create it in order to use the new name.

For Azure Arc-enabled servers, before you rename the machine, it's necessary to remove the VM extensions before proceeding:

  1. Audit the VM extensions installed on the machine and note their configuration using the Azure CLI or Azure PowerShell.

  2. Remove any VM extensions installed on the machine. You can do this using the Azure portal, the Azure CLI, or Azure PowerShell.

  3. Use the azcmagent tool with the Disconnect parameter to disconnect the machine from Azure Arc and delete the machine resource from Azure. You can run this manually while logged on interactively, with a Microsoft identity access token, or with the service principal you used for onboarding (or with a new service principal that you create.

    Disconnecting the machine from Azure Arc-enabled servers doesn't remove the Connected Machine agent, and you do not need to remove the agent as part of this process.

  4. Re-register the Connected Machine agent with Azure Arc-enabled servers. Run the azcmagent tool with the Connect parameter to complete this step. The agent will default to using the computer's current hostname, but you can choose your own resource name by passing the --resource-name parameter to the connect command.

  5. Redeploy the VM extensions that were originally deployed to the machine from Azure Arc-enabled servers. If you deployed the Azure Monitor for VMs (insights) agent or the Log Analytics agent using an Azure Policy definition, the agents are redeployed after the next evaluation cycle.

Uninstall the agent

For servers you no longer want to manage with Azure Arc-enabled servers, follow the steps below to remove any VM extensions from the server, disconnect the agent, and uninstall the software from your server. It's important to complete all of these steps to fully remove all related software components from your system.

Step 1: Remove VM extensions

If you have deployed Azure VM extensions to an Azure Arc-enabled server, you must uninstall the extensions before disconnecting the agent or uninstalling the software. Uninstalling the Azure Connected Machine agent doesn't automatically remove extensions, and these extensions won't be recognized if you reconnect the server to Azure Arc.

For guidance on how to identify and remove any extensions on your Azure Arc-enabled server, see the following resources:

Step 2: Disconnect the server from Azure Arc

Disconnecting the agent deletes the corresponding Azure resource for the server and clears the local state of the agent. To disconnect the agent, run the azcmagent disconnect command as an administrator on the server. You'll be prompted to log in with an Azure account that has permission to delete the resource in your subscription. If the resource has already been deleted in Azure, you'll need to pass an additional flag to clean up the local state: azcmagent disconnect --force-local-only.

Step 3a: Uninstall the Windows agent

Both of the following methods remove the agent, but they do not remove the C:\Program Files\AzureConnectedMachineAgent folder on the machine.

Uninstall from Control Panel

Follow these steps to uninstall the Windows agent from the machine:

  1. Sign in to the computer with an account that has administrator permissions.

  2. In Control panel, select Programs and Features.

  3. In Programs and Features, select Azure Connected Machine Agent, select Uninstall, and then select Yes.

You can also delete the Windows agent directly from the agent setup wizard. Run the AzureConnectedMachineAgent.msi installer package to do so.

Uninstall from the command line

You can uninstall the agent manually from the Command Prompt or by using an automated method (such as a script) by following the example below. First you need to retrieve the product code, which is a GUID that is the principal identifier of the application package, from the operating system. The uninstall is performed by using the Msiexec.exe command line - msiexec /x {Product Code}.

  1. Open the Registry Editor.

  2. Under registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall, look for and copy the product code GUID.

  3. Uninstall the agent using Msiexec, as in the following examples:

    • From the command-line type:

      msiexec.exe /x {product code GUID} /qn
      
    • You can perform the same steps using PowerShell:

      Get-ChildItem -Path HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall | `
      Get-ItemProperty | `
      Where-Object {$_.DisplayName -eq "Azure Connected Machine Agent"} | `
      ForEach-Object {MsiExec.exe /x "$($_.PsChildName)" /qn}
      

Step 3b: Uninstall the Linux agent

Note

To uninstall the agent, you must have root access permissions or an account that has elevated rights using sudo.

The command used to uninstall the Linux agent depends on the Linux operating system.

  • For Ubuntu, run the following command:

    sudo apt purge azcmagent
    
  • For RHEL, CentOS, Oracle Linux, and Amazon Linux, run the following command:

    sudo yum remove azcmagent
    
  • For SLES, run the following command:

    sudo zypper remove azcmagent
    

Update or remove proxy settings

To configure the agent to communicate to the service through a proxy server or to remove this configuration after deployment, use one of the methods described below. Note that the agent communicates outbound using the HTTP protocol under this scenario.

As of agent version 1.13, proxy settings can be configured using the azcmagent config command or system environment variables. If a proxy server is specified in both the agent configuration and system environment variables, the agent configuration will take precedence and become the effective setting. Use azcmagent show to view the effective proxy configuration for the agent.

Note

Azure Arc-enabled servers doesn't support using proxy servers that require authentication, TLS (HTTPS) connections, or a Log Analytics gateway as a proxy for the Connected Machine agent.

Agent-specific proxy configuration

Agent-specific proxy configuration is available starting with version 1.13 of the Azure Connected Machine agent and is the preferred way of configuring proxy server settings. This approach prevents the proxy settings for the Azure Connected Machine agent from interfering with other applications on your system.

Note

Extensions deployed by Azure Arc will not inherit the agent-specific proxy configuration. Refer to the documentation for the extensions you deploy for guidance on how to configure proxy settings for each extension.

To configure the agent to communicate through a proxy server, run the following command:

azcmagent config set proxy.url "http://ProxyServerFQDN:port"

You can use an IP address or simple hostname in place of the FQDN if your network requires it. If your proxy server runs on port 80, you may omit ":80" at the end.

To check if a proxy server URL is configured in the agent settings, run the following command:

azcmagent config get proxy.url

To stop the agent from communicating through a proxy server, run the following command:

azcmagent config clear proxy.url

You do not need to restart any services when reconfiguring the proxy settings with the azcmagent config command.

Proxy bypass for private endpoints

Starting with agent version 1.15, you can also specify services which should not use the specified proxy server. This can help with split-network designs and private endpoint scenarios where you want Azure Active Directory (Azure AD) and Azure Resource Manager traffic to go through your proxy server to public endpoints but want Azure Arc traffic to skip the proxy and communicate with a private IP address on your network.

The proxy bypass feature does not require you to enter specific URLs to bypass. Instead, you provide the name of the service(s) that should not use the proxy server.

Proxy bypass value Affected endpoints
Azure AD login.windows.net, login.microsoftonline.com, pas.windows.net
ARM management.azure.com
Arc his.arc.azure.com, guestconfiguration.azure.com, guestnotificationservice.azure.com, servicebus.windows.net

To send Azure Active Directory and Azure Resource Manager traffic through a proxy server but skip the proxy for Azure Arc traffic, run the following command:

azcmagent config set proxy.url "http://ProxyServerFQDN:port"
azcmagent config set proxy.bypass "Arc"

To provide a list of services, separate the service names by commas:

azcmagent config set proxy.bypass "ARM,Arc"

To clear the proxy bypass, run the following command:

azcmagent config clear proxy.bypass

You can view the effective proxy server and proxy bypass configuration by running azcmagent show.

Windows environment variables

On Windows, the Azure Connected Machine agent will first check the proxy.url agent configuration property (starting with agent version 1.13), then the system-wide HTTPS_PROXY environment variable to determine which proxy server to use. If both are empty, no proxy server is used, even if the default Windows system-wide proxy setting is configured.

Microsoft recommends using the agent-specific proxy configuration instead of the system environment variable.

To set the proxy server environment variable, run the following commands:

# If a proxy server is needed, execute these commands with the proxy URL and port.
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://ProxyServerFQDN:port", "Machine")
$env:HTTPS_PROXY = [System.Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine")
# For the changes to take effect, the agent services need to be restarted after the proxy environment variable is set.
Restart-Service -Name himds, ExtensionService, GCArcService

To configure the agent to stop communicating through a proxy server, run the following commands:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine")
$env:HTTPS_PROXY = [System.Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine")
# For the changes to take effect, the agent services need to be restarted after the proxy environment variable removed.
Restart-Service -Name himds, ExtensionService, GCArcService

Linux environment variables

On Linux, the Azure Connected Machine agent first checks the proxy.url agent configuration property (starting with agent version 1.13), and then the HTTPS_PROXY environment variable set for the himds, GC_Ext, and GCArcService daemons. There's an included script that will configure systemd's default proxy settings for the Azure Connected Machine agent and all other services on the machine to use a specified proxy server.

To configure the agent to communicate through a proxy server, run the following command:

sudo /opt/azcmagent/bin/azcmagent_proxy add "http://ProxyServerFQDN:port"

To remove the environment variable, run the following command:

sudo /opt/azcmagent/bin/azcmagent_proxy remove

Migrating from environment variables to agent-specific proxy configuration

If you're already using environment variables to configure the proxy server for the Azure Connected Machine agent and want to migrate to the agent-specific proxy configuration based on local agent settings, follow these steps:

  1. Upgrade the Azure Connected Machine agent to the latest version (starting with version 1.13) to use the new proxy configuration settings.

  2. Configure the agent with your proxy server information by running azcmagent config set proxy.url "http://ProxyServerFQDN:port".

  3. Remove the unused environment variables by following the steps for Windows or Linux.

Next steps