Merge pull request #295061 from Phil-Jensen/main

Improve instructions for using example runAfter shell script

Author: prmerger-automator[bot]

articles/azure-netapp-files/azacsnap-cmd-ref-runbefore-runafter.md

@@ -5,7 +5,7 @@ services: azure-netapp-files
 author: Phil-Jensen
 ms.service: azure-netapp-files
 ms.topic: reference
-ms.date: 07/29/2022
+ms.date: 02/20/2025
 ms.author: phjensen
 ---
 
@@ -17,17 +17,17 @@ This article provides a guide for using the `--runbefore` and `--runafter` capab
 
 AzAcSnap can execute external commands before or after its main execution using the options `--runbefore` or `--runafter` respectively.
 
-`--runbefore` will run a shell command before the main execution of azacsnap and provides some of the azacsnap command-line parameters to the shell environment. 
-By default, `azacsnap` will wait up to 30 seconds for the external shell command to complete before killing the process and returning to azacsnap normal execution. 
+`--runbefore` runs a shell command before the main execution of azacsnap and provides some of the azacsnap command-line parameters to the shell environment. 
+By default, `azacsnap` waits up to 30 seconds for the external shell command to complete before killing the process and returning to azacsnap normal execution. 
 This delay can be overridden by adding a number to wait in seconds after a `%` character (for example, `--runbefore "mycommand.sh%60"` will wait up to 60 seconds for `mycommand.sh` 
 to complete).
 
-`--runafter` will run a shell command after the main execution of azacsnap and provides some of the azacsnap command-line parameters to the shell environment. 
-By default, `azacsnap` will wait up to 30 seconds for the external shell command to complete before killing the process and returning to azacsnap normal execution. 
-This can be overridden by adding a number to wait in seconds after a `%` character (for example, `--runafter "mycommand.sh%60"` will wait for up to 60 seconds for `mycommand.sh` 
+`--runafter` runs a shell command after the main execution of azacsnap and provides some of the azacsnap command-line parameters to the shell environment. 
+By default, `azacsnap` waits up to 30 seconds for the external shell command to complete before killing the process and returning to azacsnap normal execution. 
+This delay can be overridden by adding a number to wait in seconds after a `%` character (for example, `--runafter "mycommand.sh%60"` will wait for up to 60 seconds for `mycommand.sh` 
 to complete).
 
-The following list of environment variables is generated by `azacsnap` and passed to the shell forked to run the commands provided as parameters to `--runbefore` and `--runafter`:
+`azacsnap` generates the following list of environment variables and passes them to the shell forked to run the commands provided as parameters to `--runbefore` and `--runafter`:
 
 - `$azCommand` = the command option passed to -c (for example, backup, test, etc.).
 - `$azConfigFileName` = the configuration filename.
@@ -39,24 +39,28 @@ The following list of environment variables is generated by `azacsnap` and passe
 > [!NOTE]
 > There's only a value for `$azSnapshotName` in the `--runafter` option.
 
-### Example usage
+### Example usage to back up to Azure Blob storage
 
-An example usage for this new feature is to upload a snapshot to Azure Blob for archival purposes using the azcopy tool 
+> [!IMPORTANT]
+> Examples are provided for informational purposes only.
+> We don't guarantee the accuracy, completeness, or usefulness of any information provided.
+> The use of these examples is at your own risk.
+> We don't accept any liability for any loss or damage that may arise from the use of these examples.
+> We don't offer support for the examples provided in this documentation.
+
+An example usage for this new feature is to upload a snapshot to Azure Blob for archival purposes using the `azcopy` tool 
 ([Copy or move data to Azure Storage by using AzCopy](../storage/common/storage-use-azcopy-v10.md)).  
 
-The following crontab entry is a single line and runs `azacsnap` at five past midnight.  Note the call to `snapshot-to-blob.sh` passing the 
-snapshot name and snapshot prefix:
+#### Shell script to upload to Azure Blob storage
 
-```output
-5 0 * * *         ( . ~/.bash_profile ; cd /home/azacsnap/bin ; ./azacsnap -c backup --volume data --prefix daily --retention 1 --configfile HANA.json --trim --ssl openssl --runafter 'env ; ./snapshot-to-blob.sh $azSnapshotName $azPrefix')
-```
-
-This example shell script has a special stanza at the end to prevent AzAcSnap from killing the external command due to the timeout described earlier.  This allows for 
+This example shell script has a special stanza at the end to prevent AzAcSnap from killing the external command due to the time-out described earlier. This stanza allows for 
 a long running command, such as uploading large files with azcopy, to be run without being prematurely stopped. 
 
-The snapshots need to be mounted on the system doing the copy, with at a minimum read-only privilege.  The base location of the mount point for the snapshots should
+The snapshots need to be mounted on the system doing the copy, with at a minimum read-only privilege. The base location of the mount point for the snapshots should
 be provided to the `sourceDir` variable in the script.
 
+The snapshot is uploaded as a single file by using the `tar` command to create a gzipped tarball. Putting the files into a single tarball keeps the file permissions and ownership, otherwise uploading the files individually loses these attributes.
+
 ```bash
 cat snapshot-to-blob.sh
 ```
@@ -240,6 +244,30 @@ cat blob-credentials.saskey
 PORTAL_GENERATED_SAS="https://<targetstorageaccount>.blob.core.windows.net/<blob-store>?sp=racwl&st=2021-06-10T21:10:38Z&se=2021-06-11T05:10:38Z&spr=https&sv=2020-02-10&sr=c&sig=<key-material>"
 ```
 
+#### Scheduling the shell script
+
+The following crontab entry is a single line and runs `azacsnap` at 12:05am. Note the call to `snapshot-to-blob.sh` passing the 
+snapshot name and snapshot prefix:
+
+```output
+5 0 * * *         ( . ~/.bash_profile ; cd /home/azacsnap/bin ; ./azacsnap -c backup --volume data --prefix daily --retention 1 --configfile HANA.json --trim --ssl openssl --runafter 'env ; ./snapshot-to-blob.sh $azSnapshotName $azPrefix')
+```
+
+#### Restoring from Azure Blob storage
+
+Restoring from one of these archives stored in Azure Blob storage at a high-level is as follows:
+
+1. Copy the snapshot archive back to the local machine. The target location should be separate from the database files and with enough capacity to allow for the file archive and the extraction, for example `/var/tmp`.
+   1. If they created the archive using the `--runafter` example shell script, then they can possibly extract the gzipped tarball directly from Azure Blob storage into the target location using an AzCopy pipe to tar to extract, for example:
+      1. `cd ${TARGET_DIRECTORY}`
+      1. `azcopy cp "${BLOB_STORE}/${ARCHIVE_BLOB_TGZ}?${BLOB_SAS_KEY}" --from-to BlobPipe | tar zxvf -`
+1. Extract the contents of the snapshot archive.
+1. Review the contents of the target location after extracting, comparing file permissions and ownership to the original database files.
+   1. For example, do `ls -lR`.
+1. Shut down the database server processes.
+1. Copy the files from the target location restored to in step 1 back to their original location.
+1. Proceed with the normal database recovery process.
+
 ## Next steps
 
 - [Take a backup](azacsnap-cmd-ref-backup.md)