Merge pull request #308475 from Phil-Jensen/main

JamesJBarnett · web-flow · commit 8fcbc80ae59f · 2025-11-19T15:06:22.000-07:00
Revise troubleshooting steps for AzAcSnap tool
diff --git a/articles/azure-netapp-files/azacsnap-troubleshoot.md b/articles/azure-netapp-files/azacsnap-troubleshoot.md
@@ -5,22 +5,66 @@ services: azure-netapp-files
 author: Phil-Jensen
 ms.service: azure-netapp-files
 ms.topic: troubleshooting
-ms.date: 10/30/2025
+ms.date: 11/18/2025
 ms.author: phjensen
 ms.custom: kr2b-contr-experiment
 # Customer intent: "As a system administrator using Azure Application Consistent Snapshot tool, I want to troubleshoot command execution issues, so that I can ensure successful operations and maintain reliable backups of my applications."
 ---
 
 # Troubleshoot the Azure Application Consistent Snapshot (AzAcSnap) tool
 
-This article describes how to troubleshoot issues when using the Azure Application Consistent Snapshot (AzAcSnap) tool for Azure NetApp Files and Azure Large Instance.
+This article describes how to troubleshoot issues when using the Azure Application Consistent Snapshot ([AzAcSnap](https://aka.ms/azacsnap)) tool.
 
 You might encounter several common issues when running AzAcSnap commands. Follow the instructions to troubleshoot the issues. 
 
 > [!IMPORTANT]
 > To ensure accurate troubleshooting and support, issues should be reproduced using the latest AzAcSnap release. Update to the most recent version before reporting any problems.
 > If you still have issues, go to the Azure portal and select Support + troubleshooting and search for guidance on issues with AzAcSnap, this allows you to open a Service Request for Microsoft Support.
 
+## Check log files, result files, and syslog
+
+Some of the best sources of information for investigating AzAcSnap issues are the log files, result files, and the system log.
+
+### Log files
+
+The AzAcSnap log files are stored in the directory configured by the `logPath` parameter in the AzAcSnap configuration file. The default configuration filename is *azacsnap.json*, and the default value for `logPath` is *./logs*, which means the log files are written into the *./logs* directory relative to where the `azacsnap` command runs. If you make the `logPath` an absolute location, such as */home/azacsnap/logs*, `azacsnap` always outputs the logs into */home/azacsnap/logs*, regardless of where you run the `azacsnap` command.
+
+The log filename is based on the application name, `azacsnap`, the command run with `-c`, such as `backup`, `test`, or `details`, and the default configuration filename, such as *azacsnap.json*. With the `-c backup` command, a default log filename would be *azacsnap-backup-azacsnap.log*, written into the directory configured by `logPath`.
+
+This naming convention allows for multiple configuration files, one per database, to help locate the associated log files. If the configuration filename is *SID.json*, then the log filename when using the `azacsnap -c backup --configfile SID.json` option is *azacsnap-backup-SID.log*.
+
+### Result files and syslog
+
+For the `-c backup` command, AzAcSnap writes to a *\*.result* file. The purpose of the *\*.result* file is to provide high-level confirmation of success/failure. If the *\*.result* file is empty, then assume failure. Any output written to the *\*.result* file is also output to the system log (for example, `/var/log/messages`) by using the `logger` command. The *\*.result* filename has the same base name as the log file to allow for matching the result file with the configuration file and the backup log file. The *\*.result* file goes into the same location as the other log files and is a simple one line output file.
+
+- Example for successful completion:
+
+   - Output to *\*.result* file:
+   
+      ```output
+      Database # 1 (PR1) : completed ok
+      ```
+
+   - Output to `/var/log/messages`:
+
+      ```output
+      Dec 17 09:01:13 azacsnap-rhel azacsnap: Database # 1 (PR1) : completed ok
+      ```
+
+- Example output where a failure occurred and AzAcSnap captured the failure:
+
+   - Output to *\*.result* file:
+   
+      ```output
+      Database # 1 (PR1) : failed
+      ```
+
+   - Output to `/var/log/messages`:
+
+      ```output
+      Dec 19 09:00:30 azacsnap-rhel azacsnap: Database # 1 (PR1) : failed
+      ```
+
 ## AzAcSnap command won't run
 
 In some cases AzAcSnap won't start due to the user's environment.
@@ -89,50 +133,6 @@ Make a `TMPDIR` for the `azacsnap` user:
 > [!IMPORTANT]
 > Changing the user's `TMPDIR` would need to be made permanent by changing the user's profile (for example, `$HOME/.bashrc` or `$HOME/.bash_profile`). Making this change means a manual clean up of the `TMPDIR` would be needed on system reboot. This `TMPDIR` clean up is typically automatic for `/tmp`.
 
-## Check log files, result files, and syslog
-
-Some of the best sources of information for investigating AzAcSnap issues are the log files, result files, and the system log.
-
-### Log files
-
-The AzAcSnap log files are stored in the directory configured by the `logPath` parameter in the AzAcSnap configuration file. The default configuration filename is *azacsnap.json*, and the default value for `logPath` is *./logs*, which means the log files are written into the *./logs* directory relative to where the `azacsnap` command runs. If you make the `logPath` an absolute location, such as */home/azacsnap/logs*, `azacsnap` always outputs the logs into */home/azacsnap/logs*, regardless of where you run the `azacsnap` command.
-
-The log filename is based on the application name, `azacsnap`, the command run with `-c`, such as `backup`, `test`, or `details`, and the default configuration filename, such as *azacsnap.json*. With the `-c backup` command, a default log filename would be *azacsnap-backup-azacsnap.log*, written into the directory configured by `logPath`.
-
-This naming convention allows for multiple configuration files, one per database, to help locate the associated log files. If the configuration filename is *SID.json*, then the log filename when using the `azacsnap -c backup --configfile SID.json` option is *azacsnap-backup-SID.log*.
-
-### Result files and syslog
-
-For the `-c backup` command, AzAcSnap writes to a *\*.result* file. The purpose of the *\*.result* file is to provide high-level confirmation of success/failure. If the *\*.result* file is empty, then assume failure. Any output written to the *\*.result* file is also output to the system log (for example, `/var/log/messages`) by using the `logger` command. The *\*.result* filename has the same base name as the log file to allow for matching the result file with the configuration file and the backup log file. The *\*.result* file goes into the same location as the other log files and is a simple one line output file.
-
-1. Example for successful completion:
-
-   1. Output to *\*.result* file:
-   
-      ```output
-      Database # 1 (PR1) : completed ok
-      ```
-
-   1. Output to `/var/log/messages`:
-
-      ```output
-      Dec 17 09:01:13 azacsnap-rhel azacsnap: Database # 1 (PR1) : completed ok
-      ```
-
-1. Example output where a failure occurred and AzAcSnap captured the failure:
-
-   1. Output to *\*.result* file:
-   
-      ```output
-      Database # 1 (PR1) : failed
-      ```
-
-   1. Output to `/var/log/messages`:
-
-      ```output
-      Dec 19 09:00:30 azacsnap-rhel azacsnap: Database # 1 (PR1) : failed
-      ```
-
 ## Troubleshoot failed 'test storage' command
 
 The command `azacsnap -c test --test storage` might not complete successfully.
@@ -182,48 +182,31 @@ You can test the AzAcSnap configuration by using Cloud Shell through the Azure p
    > [!NOTE]
    > The test command can take about 90 seconds to complete.
 
-### Failed test on Azure Large Instance
+### Failed test with Azure NetApp Files
 
-The following error example is from running `azacsnap` on Azure Large Instance:
+The following error example is from running a storage test with `azacsnap` with Azure NetApp Files:
 
 ```bash
 azacsnap -c test --test storage
 ```
 
-```output
-The authenticity of host '172.18.18.11 (172.18.18.11)' can't be established.
-ECDSA key fingerprint is SHA256:QxamHRn3ZKbJAKnEimQpVVCknDSO9uB4c9Qd8komDec.
-Are you sure you want to continue connecting (yes/no)?
-```
-
-To troubleshoot this error, don't respond `yes`. Make sure that your storage IP address is correct. You can confirm the storage IP address with the Microsoft operations team.
+#### 'Does not have authorization'
 
-The error usually appears when the Azure Large Instance storage user doesn't have access to the underlying storage. To determine whether the storage user has access to storage, run the `ssh` command to validate communication with the storage platform.
+Example output from the log file:
 
-```bash
-ssh <StorageBackupname>@<Storage IP address> "volume show -fields volume"
+```output
+The client '00001111-aaaa-2222-bbbb-3333cccc4444' with object id 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb' does not have authorization to perform action 'Microsoft.NetApp/netAppAccounts/read' over scope ...
 ```
 
-The following example shows the expected output:
+This error can be caused by having both a System Assigned Managed Identity and User Assigned Identity in use on the Virtual Machine for authentication.
 
-```bash
-ssh clt1h80backup@10.8.0.16 "volume show -fields volume"
-```
+To resolve this issue use one of the following solutions:
 
-```output
-vserver volume
---------------------------------- ------------------------------
-osa33-hana-c01v250-client25-nprod hana_data_h80_mnt00001_t020_vol
-osa33-hana-c01v250-client25-nprod hana_data_h80_mnt00002_t020_vol
-```
+- Disable or Delete the System Assigned Managed Identity.
+- Configure AzAcSnap to use the [Service Principal method](azacsnap-configure-storage.md?tabs=azure-netapp-files#generate-a-service-principal-file) for authentication.
 
-### Failed test with Azure NetApp Files
-
-The following error example is from running `azacsnap` with Azure NetApp Files:
 
-```bash
-azacsnap --configfile azacsnap.json.NOT-WORKING -c test --test storage
-```
+#### 'Could not create StorageANF object'
 
 ```output
 BEGIN : Test process started for 'storage'
@@ -250,6 +233,41 @@ To troubleshoot this error:
 > [!TIP]
 > For more information on generating a new Service Principal, see the section [Enable communication with Storage](azacsnap-configure-storage.md?tabs=azure-netapp-files#enable-communication-with-storage) in the [Install Azure Application Consistent Snapshot tool](azacsnap-installation.md) guide.
 
+### Failed test on Azure Large Instance
+
+The following error example is from running `azacsnap` on Azure Large Instance:
+
+```bash
+azacsnap -c test --test storage
+```
+
+```output
+The authenticity of host '172.18.18.11 (172.18.18.11)' can't be established.
+ECDSA key fingerprint is SHA256:AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00.
+Are you sure you want to continue connecting (yes/no)?
+```
+
+To troubleshoot this error, don't respond `yes`. Make sure that your storage IP address is correct. You can confirm the storage IP address with the Microsoft operations team.
+
+The error usually appears when the Azure Large Instance storage user doesn't have access to the underlying storage. To determine whether the storage user has access to storage, run the `ssh` command to validate communication with the storage platform.
+
+```bash
+ssh <StorageBackupname>@<Storage IP address> "volume show -fields volume"
+```
+
+The following example shows the expected output:
+
+```bash
+ssh clt1h80backup@10.8.0.16 "volume show -fields volume"
+```
+
+```output
+vserver volume
+--------------------------------- ------------------------------
+osa33-hana-c01v250-client25-nprod hana_data_h80_mnt00001_t020_vol
+osa33-hana-c01v250-client25-nprod hana_data_h80_mnt00002_t020_vol
+```
+
 ## Troubleshoot failed 'test hana' command
 
 The command `azacsnap -c test --test hana` might not complete successfully.
@@ -294,7 +312,7 @@ hdbsql -n 172.18.18.50 -i 00 -U AZACSNAP "select version from sys.m_database"
 
 For more information on setup of the `hdbuserstore`, see [Get started with AzAcSnap](azacsnap-get-started.md).
 
-### Failed test
+### Failed test with SAP HANA
 
 When validating communication with SAP HANA by running a test with `azacsnap -c test --test hana`, you might get the following error:
 
@@ -330,7 +348,7 @@ To troubleshoot this error:
    sql port      : saphana1:30013
    ```
 
-### Insufficient privilege error
+### Insufficient privilege error with SAP HANA
 
 If running `azacsnap` presents an error such as `* 258: insufficient privilege`, check that the user has the appropriate AZACSNAP database user privileges set up per the [installation guide](azacsnap-configure-database.md#enable-communication-with-the-database). Verify the user's privileges with the following command:
 
