Learn how to use the Azure Arc-enabled Servers Azcmagent.exe utility
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.
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
- 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 --use-private-link to check endpoint connectivity as if private link scope is used.
Flags
- --cloud string - Cloud (default "AzureCloud")
- --location or -l - Location of the resource [Required if not yet onboarded]
- --use-private-link or -p - Check connectivity in case the private link is used
- --version - version for check
Check Examples
- azcmagent.exe check --location "West Europe"
- 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 <>
- azcmagent connect --service-principal-id <> --service-principal-secret <> --tenant-id
- 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.
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
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
Need assistance implementing Azure Arc, let me know.
Summary
Are you ready to take your on-premises servers to the next level with Azure Arc? Contact me today and let me help you implement Azure Arc for your servers and unlock the full potential of your hybrid infrastructure.
Member discussion