[bug]: Backup post-hook does not receive reliable final backup file path

[TreeMonkey82]

FreePBX Version

FreePBX 17

Issue Description

I am reporting a Backup & Restore / Filestore behavior issue that affects automated off-site backup workflows using a post-backup hook.

Summary

I am using the Backup & Restore module with a Local Filestore destination and a post-backup hook. The post-backup hook uploads the completed backup archive to an external SFTP backup server.

The backup archive itself is created successfully. The issue is that the post-backup hook does not appear to receive a reliable final backup file path, and the local backup path behavior is confusing enough that the hook cannot safely know which backup file was just created.

Observed Behavior

The backup job reports output similar to:

Finished created backup file: YYYYMMDD-HHMMSS-xxxxx-17.0.28-xxxxx.tar.gz
Saving to selected Filestore locations
Saving to: Local:'Local Backup Storage' instance, File location: /var/spool/asterisk/backup/YYYYMMDD-HHMMSS-xxxxx-17.0.28-xxxxx.tar.gz
Finished Saving to selected Filestore locations
Executing Post Backup Hook: /usr/local/sbin/upload-offsite-backup.sh

However, depending on the backup job/storage configuration, backups may appear directly under:

/var/spool/asterisk/backup/

while other backup behavior suggests a job/subdirectory path such as:

/var/spool/asterisk/backup/[backup-job-name]/

Because the post-backup hook is executed without being passed the final backup archive path, the hook has no reliable way to know the exact file that was just created.

Workaround

I changed my post-backup hook to recursively search under /var/spool/asterisk/backup for the newest .tar.gz file:

find /var/spool/asterisk/backup -type f -name "*.tar.gz" -printf "%T@ %p\n" | sort -nr | head -1

This works, but it is only a workaround. It could choose the wrong file if multiple backup jobs run close together or if an older backup file is touched/modified.

Why This Should Be Addressed

The Backup & Restore module already knows the exact backup archive it created and saved. The post-backup hook should not have to guess, parse logs, or recursively search the backup directory.

Requested Product Changes

Please consider one or more of the following:

1. Pass the final backup archive path to the post-backup hook as an argument.
2. Expose the final backup archive path as an environment variable.
3. Document the expected Local Filestore path behavior clearly.
4. Ensure Local Filestore backup paths are consistent and predictable.
5. Ensure the post-backup hook runs only after the final archive is fully written and visible at its final location.

Expected Behavior

A post-backup hook should be able to reliably identify the backup file that was just created without parsing logs or searching the entire backup directory.

Related Issues

This may be loosely related to other Backup/Filestore path issues, but it is not the same as SSH Filestore authentication or SFTP subsystem failures. In this case, the backup was created successfully and the external SFTP upload worked once the hook was changed to locate the newest local .tar.gz file.

Possibly related to #1003, but this issue is specifically about post-backup hook path handling.

Operating Environment

FreePBX 17.0.28
Backup module 17.0.6
Framework module 17.0.28
Asterisk 22.8.2
Debian 12 Bookworm

Backup method:
FreePBX Backup & Restore module using a Local Filestore destination with a post-backup hook.

Post-backup hook:
/usr/local/sbin/upload-offsite-backup.sh

The hook uploads the most recent FreePBX backup archive to an external SFTP backup server.

Relevant log output

Finished created backup file: YYYYMMDD-HHMMSS-xxxxxxxxxx-17.0.28-xxxxxxxxxx.tar.gz
Performing Local Maintenance
Finished Local Maintenance
Saving to selected Filestore locations
Saving to: Local:'Local Backup Storage' instance, File location: /var/spool/asterisk/backup/YYYYMMDD-HHMMSS-xxxxxxxxxx-17.0.28-xxxxxxxxxx.tar.gz
Finished Saving to selected Filestore locations
Performing Remote Maintenance
Finished Remote Maintenance
Executing Post Backup Hook: /usr/local/sbin/upload-offsite-backup.sh

Workaround log output:
The post-backup hook was changed to locate the newest backup recursively:

find /var/spool/asterisk/backup -type f -name "*.tar.gz" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2-

After changing the hook to search recursively, the external SFTP upload succeeded:

===== Fri May 15 16:28:45 EDT 2026 Starting off-site backup upload =====
Latest backup file: /var/spool/asterisk/backup/YYYYMMDD-HHMMSS-xxxxxxxxxx-17.0.28-xxxxxxxxxx.tar.gz
Remote target: <backup-user>@<sftp-backup-server>:/<remote-backup-folder>
sftp> cd /<remote-backup-folder>
sftp> put "/var/spool/asterisk/backup/YYYYMMDD-HHMMSS-xxxxxxxxxx-17.0.28-xxxxxxxxxx.tar.gz"
sftp> ls -lh
-rw-r--r--    ? <uid>     <gid>          195M May 15 16:28 YYYYMMDD-HHMMSS-xxxxxxxxxx-17.0.28-xxxxxxxxxx.tar.gz
sftp> bye
Upload successful: /var/spool/asterisk/backup/YYYYMMDD-HHMMSS-xxxxxxxxxx-17.0.28-xxxxxxxxxx.tar.gz
===== Fri May 15 16:28:50 EDT 2026 Finished off-site backup upload =====