Tsg/update fails arc agent install

[Krasios]

This pull request adds new troubleshooting guidance for update failures caused by Arc Agent installation issues due to a locked log file. It introduces a new TSG (Troubleshooting Guide) entry and updates the documentation index to reference this scenario.

Documentation updates:

• Added a new troubleshooting guide, Update-fails-due-to-Arc-Agent-install-failure.md, detailing symptoms, diagnosis, and resolution steps for update failures caused by a locked azcmagent.log file during Arc Agent installation (affecting versions below 1.62).
• Updated README.md to include a link to the new troubleshooting guide for easier discovery.

[Copilot]

Pull request overview

Adds a new Azure Local Update troubleshooting guide covering update failures caused by Arc Agent installation issues when azcmagent.log is locked, and links it from the Update TSG index for discoverability.

Changes:

• Added a new TSG: Update-fails-due-to-Arc-Agent-install-failure.md (symptoms + resolution steps).
• Updated TSG/Update/README.md to include a link to the new TSG.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
TSG/Update/Update-fails-due-to-Arc-Agent-install-failure.md	New troubleshooting guide describing the locked-log scenario and mitigation steps.
TSG/Update/README.md	Adds an index link to the new troubleshooting guide.

[Copilot]

What: Step 2 says moving azcmagent.log will "release the lock".
Why: On Windows, a file that is actively locked/open by another process typically cannot be moved/renamed, so this guidance can fail exactly in the scenario it targets.
How: Update the resolution to first identify and stop/restart the process or service holding the handle (or otherwise ensure the handle is closed) before moving/renaming the log file, and include a quick verification that the lock is gone.

Suggested change

	2. **Back up the locked log file**
	Move the `azcmagent.log` file to a backup location outside of the `C:\ProgramData\AzureConnectedMachineAgent` directory. This releases the lock and allows the installer to create a fresh log file.
	```powershell
	# Create a backup directory if it doesn't exist
	New-Item -ItemType Directory -Path "C:\Temp\ArcAgentLogBackup" -Force
	# Move the locked log file to the backup location
	Move-Item -Path "C:\ProgramData\AzureConnectedMachineAgent\Log\azcmagent.log" -Destination "C:\Temp\ArcAgentLogBackup\azcmagent.log" -Force
	```
	> **Note:** Repeat this step on all affected nodes in the cluster.
	3. **Retry the update**
	Attempt the update again. The Arc agent installer should now be able to proceed without the lockdown issue.
	2. **Close the handle on the log file, verify the lock is gone, and then back up the log**
	Before moving `azcmagent.log`, make sure the process or service holding the file handle has released it. On most affected systems, restarting the Azure Connected Machine Agent service (`himds`) is the safest first step. After the restart, verify that the file is no longer locked, and only then move it to a backup location outside of `C:\ProgramData\AzureConnectedMachineAgent`.
	```powershell
	$ErrorActionPreference = "Stop"
	$logPath = "C:\ProgramData\AzureConnectedMachineAgent\Log\azcmagent.log"
	$backupDir = "C:\Temp\ArcAgentLogBackup"
	$backupPath = Join-Path $backupDir "azcmagent.log"
	# Restart the Azure Connected Machine Agent service to release the file handle
	$service = Get-Service -Name "himds" -ErrorAction Stop
	if ($service.Status -eq "Running") {
	Restart-Service -Name "himds"
	}
	else {
	Start-Service -Name "himds"
	Restart-Service -Name "himds"
	}
	# Verify the log file is no longer locked by opening it for write access
	$stream = $null
	try {
	$stream = [System.IO.File]::Open($logPath, 'Open', 'ReadWrite', 'None')
	}
	catch {
	throw "The log file is still in use. Identify the process holding `"$logPath`" and ensure the handle is closed before moving the file."
	}
	finally {
	if ($stream) {
	$stream.Close()
	$stream.Dispose()
	}
	}
	# Create a backup directory if it doesn't exist
	New-Item -ItemType Directory -Path $backupDir -Force | Out-Null
	# Move the log file only after confirming the lock has been released
	Move-Item -Path $logPath -Destination $backupPath -Force

Important: If the verification step reports that the file is still in use, do not force the move. Identify and stop or restart the process holding the handle, then rerun the verification before moving the file.

Note: Repeat this step on all affected nodes in the cluster.

3. Retry the update
   Attempt the update again after the file handle has been released and the old log has been moved. The Arc agent installer should now be able to proceed without the lockdown issue.

[Copilot]

What: The backup uses a fixed destination filename and Move-Item -Force.
Why: This can silently overwrite an existing backup (losing prior logs) and makes it harder to collect evidence from multiple attempts/nodes.
How: Use a unique backup filename (for example, include node name and a timestamp) and avoid -Force unless you first confirm the destination doesn’t exist; consider adding a Test-Path check and a post-step verification that the source file is gone and the backup exists.

Suggested change

	# Create a backup directory if it doesn't exist
	New-Item -ItemType Directory -Path "C:\Temp\ArcAgentLogBackup" -Force
	# Move the locked log file to the backup location
	Move-Item -Path "C:\ProgramData\AzureConnectedMachineAgent\Log\azcmagent.log" -Destination "C:\Temp\ArcAgentLogBackup\azcmagent.log" -Force
	$ErrorActionPreference = "Stop"
	$sourceLogPath = "C:\ProgramData\AzureConnectedMachineAgent\Log\azcmagent.log"
	$backupDirectory = "C:\Temp\ArcAgentLogBackup"
	$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
	$nodeName = $env:COMPUTERNAME
	$backupFileName = "azcmagent-$nodeName-$timestamp.log"
	$destinationLogPath = Join-Path -Path $backupDirectory -ChildPath $backupFileName
	# Create a backup directory if it doesn't exist
	if (-not (Test-Path -Path $backupDirectory)) {
	New-Item -ItemType Directory -Path $backupDirectory | Out-Null
	}
	if (-not (Test-Path -Path $sourceLogPath)) {
	throw "Source log file not found: $sourceLogPath"
	}
	if (Test-Path -Path $destinationLogPath) {
	throw "Backup destination already exists: $destinationLogPath"
	}
	# Move the locked log file to the backup location using a unique filename
	Move-Item -Path $sourceLogPath -Destination $destinationLogPath
	# Verify the move completed successfully
	if ((-not (Test-Path -Path $destinationLogPath)) -or (Test-Path -Path $sourceLogPath)) {
	throw "Backup verification failed. Source: $sourceLogPath Destination: $destinationLogPath"
	}

[Copilot]

What: The guide states it only applies to Arc Agent versions below 1.62 but doesn’t show how to confirm the installed Arc Agent version on the node(s).
Why: Without an explicit version check, readers may apply the mitigation unnecessarily or miss that they should upgrade instead.
How: Add a short diagnostic command/step to query the Arc Agent version and gate the rest of the steps on "< 1.62" (and ideally mention upgrading to 1.62+ as the preferred remediation when possible).