5 min read

Learn how to use the Azure Arc Azcmagent.exe utility

Learn how to use the Azure Arc Azcmagent.exe utility
Azcmagent.exe utility

Introduction

Configuring and troubleshooting the Azure Connected Machine agent is done using the Azcmagent.exe (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

Azcmagent.exe allows you to connect and disconnect. The other commands handle troubleshooting and other cases.

08.11.2022 UPDATE! New PowerShell Module for Azcmagent.exe utility

azcmagent.exe 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 --location "West Europe"
  • azcmagent.exe check -l "West Europe" -v
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 list
  • azcmagent.exe config get incomingconnections.ports
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.

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 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.

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

Logs Examples

  • azcmagent.exe logs
azcmagent.exe logs

Show

Gets machine metadata and Agent status. This is primarily useful for troubleshooting.

Show Examples

  • azcmagent.exe show
azcmagent.exe show

Need assistance implementing Azure Arc, let me know.