Introduction
In this blog post, we will look at configuring and troubleshooting the Azure Connected Machine agent using the Azcmagent.exe tool (Azure Connected Machine Agent). The ‘himdsd’ is a Linux daemon process and the ‘himds’ is a Windows service.
On a Windows machine, you should see the following services:
- Azure Hybrid Instance Metadata Service
- Guest Configuration Arc Service
- Guest Configuration Extension Service
The Azcmagent.exe tool allows you to connect and disconnect the virtual or physical machine from the Azure Arc service. The other commands handle troubleshooting and other cases. Microsoft uses the Azcmagent.exe executable in the Azure Arc installation script.
By default, the Azure Arc agent is installed under the C:\Program Files\AzureConnectedMachineAgent folder.
08.11.2022 UPDATE! New PowerShell Module for Azcmagent.exe utility
Before you test these commands, ensure you have installed the latest agent! You can download the agent from the following places:
- Microsoft Update
- You can update the existing agent.
- Microsoft Update Catalog
- Microsoft Download Center
- Good for new installations.
azcmagent commands
You can find the azcmagent.exe executable under the C:\Program Files\AzureConnectedMachineAgent folder.
Available commands for the azcmagent.exe executable:
- Check – Runs connectivity checks
- Config – Change configuration settings for this machine
- Connect – Connects this machine to Azure
- Disconnect – Disconnects this machine from Azure
- Help – Help with any command
- License – Display the End-user license agreement file
- GenKey – Generates public-private key pair
- Logs – Creates a .zip file containing relevant logs. This is primarily useful for troubleshooting.
- Show – Gets machine metadata and Agent status. This is primarily useful for troubleshooting.
- Version – Display the Hybrid Management Agent version
Check
Runs endpoint connectivity checks without connecting, assuming that private link scope is not used by default. Set —enable-pls-check to check endpoint connectivity as if private link scope is used.
Flags
- –cloud string – Valid values: AzureCloud, AzureUSGovernment, AzureChinaCloud. Default AzureCloud
- –location or -l – Location of the resource [Required if not yet onboarded]
- –enable-pls-check or -p – Check connectivity in case the private link is used
- –version – version for check
Check Examples
- azcmagent.exe check –location “westeurope”
- azcmagent.exe check -l “West Europe” -v
Config
This parameter allows you to view and configure settings that control agent behavior.
Config Properties
Name | Description |
incomingconnections.ports (preview) | Comma-separated list of ports that the server will be able to listen on. Default: Empty, all incoming traffic on all ports blocked. Example: 22,8080 |
proxy.url | URL (server and optional port) of the proxy server to use. Only unauthenticated HTTP proxy servers are supported
– Default: Empty, no proxy used – Example: http://myproxy:8080 For more information, see https://aka.ms/AzcmagentProxySettings |
extensions.allowlist | Comma-separated list of allowed extensions in the format publisher/extension. If none is specified, all extensions will be allowed. If an extension exists in the allowed and blocked list, it will be blocked. – Default: Empty, all extensions allowed – Example: Publisher1/Extension1, Publisher2/Extensions2 |
extensions.blocklist | Comma-separated list of blocked extensions in the format publisher/extension. If none is specified, all extensions will be allowed. If an extension exists in the allowed and blocked list, it will be blocked. – Default: Empty. All extensions allowed – Example: Publisher1/Extension1, Publisher2/Extensions2 |
proxy.bypass | Comma-separated list of service names (not URLs) that should not use the specified proxy server. Valid input is limited to AAD, ARM, and Arc. – Default: Empty. All services will use the proxy server if specified – Example: AAD, Arc |
guestconfiguration.enabled | Boolean value describing whether or not the guest configuration agent should be Enabled – Default: true – Example: false |
extensions.enabled | Boolean value describing whether or not the extension service should be enabled. If false, extensions cannot be installed, uninstalled, or run. – Default: true – Example: false |
Config Commands
- Clear – Clear a configuration property’s value
- Get – Get a configuration property’s value
- Info – Describes the config properties users can set
- List – List all configuration properties and values
- Set – Set a value for a configuration property
Config Examples
- azcmagent.exe config list
- azcmagent.exe config get incomingconnections.ports
- azcmagent.exe config get proxy.url
- azcmagent.exe config get extensions.allowlist
- azcmagent.exe config get extensions.blocklist
- azcmagent.exe config get proxy.bypass
- azcmagent.exe config get guestconfiguration.enabled
- azcmagent.exe config get extensions.enabled
- azcmagent.exe config set –add
- azcmagent.exe config set –remove
- azcmagent.exe config clear
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.
If you want to create a service principal for onboarding, then I recommend to follow this guide – Connect hybrid machines to Azure at scale – Azure Arc | Microsoft Learn
Connect Flags
- –access-token – Access token
- –cloud string – Cloud (default “AzureCloud”)
- –correlation-id – Correlation Id
- –help or -h – help for connect
- –ignore-network-check – Ignore network check results
- –location or -l – Location of the resource [Required]
- –private-link-scope – Resource Id of private link scope
- –resource-group – Name of the resource group. [Required]
- –resource-name or -g – Service Principal Id
- –service-principal-id or -I – Service Principal Id
- –service-principal-secret or -p – Service Principal Secret
- –subscription-id or -s – Subscription Id [Required]
- –tags – Tags for resource
- –tenant-id or -t – Tenant Id
- –version – version for connect
Connect Command Examples
- Access Token
- azcmagent connect –access-token <> –subscription-id <> –resource-group <> –location <>
- Service Principal Id and secret
- azcmagent connect –service-principal-id <> –service-principal-secret <> –tenant-id –subscription-id <> –resource-group <> –location <>
- Device Log in (Interactive)
- azcmagent connect –tenant-id <> –subscription-id <> –resource-group <> –location <>
Disconnect
Deletes the resource in Azure which represents this server. This command uses the authentication options provided to remove the Azure Resource Manager resource representing this machine. After this point the Hybrid Instance Metadata Service and Guest Configuration Agent will be disconnected. This command does not stop or remove the services: remove the package in order to do that.
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.
Source – Managing the Azure Arc-enabled servers agent – Azure Arc | Microsoft Learn
Disconnect Flags
- –access-token – Access token
- –force-local-only – Delete local state only
- –help – help for disconnect
- –service-principal-id – Service Principal Id
- –service-principal-secret – Service Principal Secret
- –version – version for disconnect
Disconnect Examples
- Access Token
o azcmagent disconnect –access-token <> - Service Principal Id and secret
o azcmagent disconnect –service-principal-id <> –service-principal-secret <> - Interactive Device Log in
- azcmagent disconnect
If the agent is no longer required, it can be uninstalled manually or through the command line. If you need to uninstall it from multiple machines, it’s recommended to create a PowerShell script. To do this, you can retrieve the product code from the registry and then execute the “MSIEXEC /X {PRODUCTCODE}” command
Logs
Create a .zip file in the current directory containing logs to assist you while troubleshooting. This command gathers different log files from different folders.
Logs Examples
- azcmagent.exe logs
Show
Gets machine metadata and Agent status. This is primarily useful for troubleshooting.
Show Examples
- azcmagent.exe show
Conclusion
The Azcmagent.exe utility is a powerful tool for managing Azure Arc-enabled servers. By understanding how to use this utility, you can streamline your hybrid infrastructure management and make the most of Azure Arc-enabled servers.
