Kaido Jarvemets - Logo

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.

Unleash the Power of Azure Arc for Servers

Experience the Future of Hybrid-Cloud Management: Connect with us to learn how Azure Arc can revolutionize your infrastructure and streamline operations.
Call to Action

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.

Leave a Reply

Contact me

If you’re interested in learning about Learn how to use the Azure Arc-enabled Servers Azcmagent.exe utility. I can help you understand how this solution can benefit your organization and provide a customized solution tailored to your specific needs.

Table of Contents