aio-interface: handle SSH key authorization error explicitly in remote backup setup

Containers/borgbackup/backupscript.sh

@@ -14,6 +14,30 @@ get_expiration_time() {
     DURATION_HOUR=$((DURATION / 3600))
     DURATION_READABLE=$(printf "%02d hours %02d minutes %02d seconds" $DURATION_HOUR $DURATION_MIN $DURATION_SEC)
 }
+# Run "borg info" and handle the exit code.
+# If the exit code indicates a connection failure (80 = ConnectionClosed,
+# 81 = ConnectionClosedWithHint) and a remote repo is configured, the SSH
+# auth error signal file is created so the mastercontainer can show a
+# targeted error message.  Returns the original borg exit code.
+borg_info() {
+    borg info > /dev/null
+    local _exit=$?
+    if [ -n "$BORG_REMOTE_REPO" ] && { [ "$_exit" -eq 80 ] || [ "$_exit" -eq 81 ]; }; then
+        touch "$SSH_AUTH_ERROR_FILE"
+    fi
+    return $_exit
+}
+
+# Signal file written when an SSH authentication failure is detected so the
+# mastercontainer can show a targeted error without needing to scan container logs.
+# Borg exit codes 80 (ConnectionClosed) and 81 (ConnectionClosedWithHint) indicate
+# connection failures that occur before the Borg protocol is established, which covers
+# SSH authentication errors and host-key verification failures.
+# These codes are available because BORG_EXIT_CODES=modern is set in start.sh.
+SSH_AUTH_ERROR_FILE="/nextcloud_aio_volumes/nextcloud_aio_mastercontainer/data/borg_ssh_auth_error"
+
+# Start with a clean state for every run
+rm -f "$SSH_AUTH_ERROR_FILE"
 
 # Test if all volumes aren't empty
 VOLUME_DIRS="$(find /nextcloud_aio_volumes -mindepth 1 -maxdepth 1 -type d)"
@@ -123,7 +147,7 @@ if [ "$BORG_MODE" = backup ]; then
     fi
 
     # Initialize the repository if can't get info from target
-    if ! borg info > /dev/null; then
+    if ! borg_info; then
         # Don't initialize if already initialized
         if [ -f "/nextcloud_aio_volumes/nextcloud_aio_mastercontainer/data/borg.config" ]; then
             if [ -n "$BORG_REMOTE_REPO" ]; then
@@ -584,7 +608,7 @@ fi
 # Do the backup test
 if [ "$BORG_MODE" = test ]; then
     if [ -n "$BORG_REMOTE_REPO" ]; then
-        if ! borg info > /dev/null; then
+        if ! borg_info; then
             echo "Borg could not get info from the remote repo."
             echo "See the above borg info output for details."
             exit 1

Containers/borgbackup/start.sh

@@ -18,6 +18,8 @@ else
 fi
 export BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes
 export BORG_RELOCATED_REPO_ACCESS_IS_OK=yes
+# Use specific exit codes (80/81 for connection failures) instead of the legacy generic exit code 2
+export BORG_EXIT_CODES=modern
 if [ -n "$BORG_REMOTE_REPO" ]; then
     export BORG_REPO="$BORG_REMOTE_REPO"
 

php/public/index.php

@@ -142,6 +142,7 @@ $app->get('/containers', function (Request $request, Response $response, array $
         'has_backup_run_once' => $configurationManager->hasBackupRunOnce(),
         'is_backup_container_running' => $dockerActionManager->isBackupContainerRunning(),
         'backup_exit_code' => $dockerActionManager->GetBackupcontainerExitCode(),
+        'is_ssh_auth_error' => $dockerActionManager->isBorgBackupSshAuthError(),
         'is_instance_restore_attempt' => $configurationManager->instanceRestoreAttempt,
         'borg_backup_mode' => $configurationManager->backupMode,
         'was_start_button_clicked' => $configurationManager->wasStartButtonClicked,

php/src/Data/DataConst.php

@@ -68,6 +68,10 @@ class DataConst {
         return (string)realpath(__DIR__ . '/../../containers.json');
     }
 
+    public static function GetBorgSshAuthErrorFile() : string {
+        return self::GetDataDirectory() . '/borg_ssh_auth_error';
+    }
+
     public static function GetAioVersionFile() : string {
         return (string)realpath(__DIR__ . '/../../templates/includes/aio-version.twig');
     }

php/src/Docker/DockerActionManager.php

@@ -895,6 +895,10 @@ readonly class DockerActionManager {
         }
     }
 
+    public function isBorgBackupSshAuthError(): bool {
+        return file_exists(DataConst::GetBorgSshAuthErrorFile());
+    }
+
     public function GetBackupcontainerExitCode(): int {
         $containerName = 'nextcloud-aio-borgbackup';
         $url = $this->BuildApiUrl(sprintf('containers/%s/json', urlencode($containerName)));

php/templates/containers.twig

@@ -191,10 +191,17 @@
 
                             {% if not hasBackupLocation or borg_backup_mode not in ['test', 'check', ''] or backup_exit_code > 0 %}
                                 {% if borg_remote_repo and backup_exit_code > 0 %}
-                                <p>
-                                You may still need to authorize this pubkey on your borg remote:<br><strong>{{ borg_public_key }}</strong><br>
-                                To try again, resubmit your location and rerun the test.
-                                </p>
+                                    {% if is_ssh_auth_error %}
+                                        <p>
+                                        ⚠️ <strong>SSH key not authorized on the remote server.</strong> You must add the following SSH public key to the <code>authorized_keys</code> file on your remote backup server before the restore test can succeed:<br><br><strong>{{ borg_public_key }}</strong><br><br>
+                                        Once you have added the key on the remote server, resubmit your location and rerun the test.
+                                        </p>
+                                    {% else %}
+                                        <p>
+                                        You may still need to authorize this pubkey on your borg remote:<br><strong>{{ borg_public_key }}</strong><br>
+                                        To try again, resubmit your location and rerun the test.
+                                        </p>
+                                    {% endif %}
                                 {% endif %}
 
                                 <p>
@@ -420,21 +427,29 @@
                                         {% if has_backup_run_once == false %}
                                             <p>The initial backup was not successful.</p>
 
-                                            {% if borg_remote_repo %}
-                                            <p>
-                                            You may still need to authorize this pubkey on your borg remote:<br><strong>{{ borg_public_key }}</strong><br>
-                                            To try again, click <strong>Create backup</strong>.
-                                            </p>
+                                            {% if borg_remote_repo and is_ssh_auth_error %}
+                                                <p>
+                                                ⚠️ <strong>SSH key not authorized on the remote server.</strong> You must add the following SSH public key to the <code>authorized_keys</code> file on your remote backup server before the backup can succeed:<br><br><strong>{{ borg_public_key }}</strong><br><br>
+                                                Once you have added the key on the remote server, click <strong>Create backup</strong> to try again.
+                                                </p>
+                                            {% else %}
+                                                <p>
+                                                You may want to reset the backup location which allows you to enter a new one afterwards. 
+                                                </p>
+                                                <p>
+                                                If the configured backup host location <strong>{{ borg_backup_host_location }}</strong>
+                                                {% if borg_remote_repo %}
+                                                    or the remote repo <strong>{{ borg_remote_repo }}</strong>
+                                                {% endif %}
+                                                is wrong or if you want to reset the backup location due to other reasons, you can do so by clicking on the button below.
+                                                </p>
+                                                <form method="POST" action="api/configuration" class="xhr">
+                                                    <input type="hidden" name="delete_borg_backup_location_vars" value="yes"/>
+                                                    <input type="hidden" name="{{csrf.keys.name}}" value="{{csrf.name}}">
+                                                    <input type="hidden" name="{{csrf.keys.value}}" value="{{csrf.value}}">
+                                                    <input type="submit" value="Reset backup location" data-confirm='Are you sure that you want to reset the backup location?' />
+                                                </form>
                                             {% endif %}
-
-                                            <p>You may change the backup path again since the initial backup was not successful. After submitting the new value, you need to click on <strong>Create Backup</strong> to test the new value.</p>
-                                            <form method="POST" action="api/configuration" class="xhr">
-                                                <label>Local backup location</label> <input type="text" name="borg_backup_host_location" placeholder="/mnt/backup"/><br>
-                                                <label>Remote borg repo</label> <input type="text" name="borg_remote_repo" placeholder="ssh://user@host:port/path/to/repo"/><br>
-                                                <input type="hidden" name="{{csrf.keys.name}}" value="{{csrf.name}}">
-                                                <input type="hidden" name="{{csrf.keys.value}}" value="{{csrf.value}}">
-                                                <input type="submit" value="Set backup location again" />
-                                            </form>
                                         {% endif %}
                                     {% elseif backup_exit_code == 0 %}
                                         {% if borg_backup_mode == "backup" %}

tests/QA/004-initial-backup.md

@@ -23,8 +23,10 @@
     - [ ] Both a local backup location and a remote repo URL should not be accepted at the same time
     - [ ] The page should now reload
     - [ ] Now click on `Create backup`
-    - [ ] After the first failed backup attempt with a remote repo, the SSH public key for borg should be shown so it can be authorized on the remote server
-    - [ ] After authorizing the server on the remote, scroll down and click on `Create backup` again to create another backup. This time it should succeed.
+    - [ ] After the first failed backup attempt with a remote repo, the page should show **"The initial backup was not successful."** and one of two things depending on why it failed:
+        - [ ] **SSH auth error** (exit codes 80/81 – connection closed before Borg protocol established): a prominent ⚠️ **"SSH key not authorized on the remote server."** warning should appear with the public key displayed. After adding the key to `~/.ssh/authorized_keys` on the remote server, click **Create backup** again to retry.
+        - [ ] **Other error** (wrong path, unreachable host, etc.): instead of the ⚠️ warning, a **"Reset backup location"** button should appear (with a confirmation prompt) that allows resetting the configured location so a new one can be entered. Note: there are no longer inline text inputs to re-enter the location at this point.
+    - [ ] After authorizing the SSH key on the remote, scroll down and click on `Create backup` again to create another backup. This time it should succeed.
 - [ ] The initial Nextcloud credentials on top of the page that are visible when the containers are running should now be hidden in a details tag
 - [ ] After a while and a few automatic reloads (as long as the side is focused), you should be redirected to the usual page and seen in the Backup and restore section that the last backup was successful.
 - [ ] Below that you should see a details tag that allows to reveal all backup options

tests/QA/010-restore-instance.md

@@ -22,7 +22,9 @@ For the below to work, you need a backup archive of an AIO instance and the loca
     - [ ] Enter an invalid remote repo URL (e.g. `user` without `@` and `:`) which should send an error
     - [ ] Enter a valid remote borg repo URL and the correct backup password:
         - [ ] Should reload and should hide all options except the option to test the path and password
-        - [ ] After the first failed connection attempt, the SSH public key for borg should be shown so it can be authorized on the remote server
+        - [ ] After the first failed connection attempt, the behavior depends on the failure reason:
+            - [ ] **SSH auth error** (exit codes 80/81 – connection closed before Borg protocol established): a prominent ⚠️ **"SSH key not authorized on the remote server."** warning should appear with the SSH public key displayed and instructions to add it to `~/.ssh/authorized_keys` on the remote server. After adding the key, scroll down and click on the test button again.
+            - [ ] **Other error** (wrong path, unreachable host, etc.): a generic message should appear noting the public key that may still need to be authorized on the remote.
         - [ ] After authorizing the key on the remote server, scroll down and click on the test button again. This time it should succeed and show the options to check the integrity and list backup archives
         - [ ] After the test you should see the options to check the integrity of the backup and a list of backup archives that you can choose from to restore your instance
         - [ ] Clicking on either option should show a window prompt that lets you cancel the operation