Borg 1.4.1~ynh4 released, what you should check after the upgrade

fflorent · October 12, 2025, 6:59pm

English version

( French version below)

Version 1.4.1~ynh4 has just been released.

It fixes a serious bug in 1.4.1~ynh3: when the passphrase contains ampersands (&) leading it not being correctly written in /var/www/__APP__/.env, and therefore making either backups creation fail or repository initiated with the wrong passphrase ^[1].

In other word, there are three cases:

If your passphrase does not contain any ampersand (&): you are probably good . You may still upgrade to 1.4.1~ynh4 just to keep track with the release versions.
If your passphrase contains at least one ampersand, but your initial borg installation has been done before 1.4.1~ynh3, you are probably experiencing issues with backuping^[2], you should upgrade yunohost to version 12.1.28 and upgrade borg to version 1.4.1~ynh4 and make the checks below
If your passphrase contains at least one ampersand, AND your initial borg installation has been using version 1.4.1~ynh3, then you probably need to fix the passphrase of your repository, see below

Foreword

Let’s remind that this work is driven by the work of volunteers. We do care about providing a reliable service. That being said, it is important to remind you have agreed on the terms of service and especially to this part:

YunoHost as software is released under the AGPLv3 license and is therefore provided without warranty of any kind and is not liable for any damages resulting from its use, nor from the use of the applications it allows to install.

So does this post, and its author is not liable for any possible damages.

That’s the reason why you are invited to fully read from the start to the end and understand the below steps before running the commands.

The upgrade

Follow these two steps:

Upgrade your system, this will upgrade Yunohost to version 12.1.28
Upgrade all your borg apps (borg and not borgserver which is another package)

The post-upgrade checks and fix

After the upgrade, open a shell session, log in as root, and retrieve all the borg instance IDs using the following command:

yunohost app list | grep -Po 'id: \Kborg(\b|__\d+)'

The following steps have to be run for each borg instance:

Then let’s check whether the passphrase is now correctly set in the system:

app_id=borg # change the value borg__2, borg__3, ... to check 
            # the other borg instances as returned by the command above
/var/www/$app_id/wrapper/borg list

If the command succeeds in listing your archives, STOP HERE, and repeat the commands above for the next borg instance

But if the command fails with this error:

passphrase supplied in BORG_PASSPHRASE, by BORG_PASSCOMMAND or via BORG_PASSPHRASE_FD is incorrect.

Then first and foremost, be sure that you’re passphrase actually contains an ampersand:

grep BORG_PASSPHRASE /var/www/$app_id/.env | grep --color '&' && echo "The passphrase contains an ampersand, run the fix" || echo "Do NOT run the fix, that's another problem"

If the command above prints your passphrase correctly, then your borg repository has probably been initiated with a wrong one, having & replaced with __PASSPHRASE__ (see ^[1:1] for more info).

Let’s print the command that will be run to change the passphrase with the command below:

export app_id
(set -a; source /var/www/$app_id/.env; set +a; echo BORG_NEW_PASSPHRASE="${BORG_PASSPHRASE}" BORG_PASSPHRASE="${BORG_PASSPHRASE//&/__PASSPHRASE__}"  /var/www/$app_id/venv/bin/borg key change-passphrase)

Inspect the result and when you’re ready, remove the call to echo in the command above, which will make the change effective.

If you do NOT see any output, then the command should have been run successfully.

Check now that borg is able to list your backups successfully:

/var/www/$app_id/wrapper/borg list

Don’t forget to repeat the check and (if applicable) the fix for the other instances.

And you’re done!

French version

Une nouvelle version 1.4.1~ynh4 du paquet est maintenant disponible.

Elle corrige un bug important présent dans la version 1.4.1~ynh3 : lorsque la phrase de passe (passphrase ou mot de passe si vous préférez) contient des esperluette (&), elle n’est pas correctement restituée dans le fichier /var/www/__APP__/.env, ce qui entraîne l’échec des sauvegardes ou l’initialisation d’un dépôt borg avec la mauvaise phrase de passe ^[1:2].

En d’autres termes, il y a trois cas :

Si votre phrase de passe ne contient aucune esperluette (&) : vous n’avez probablement rien à faire . Vous pouvez toujours mettre à niveau vers 1.4.1~ynh4 juste pour suivre les versions de sortie.
Si votre phrase de passe contient au moins une esperluette, mais que votre installation initiale de Borg a été effectuée avant la 1.4.1~ynh3, vous rencontrez probablement des problèmes de sauvegarde^[2:1]. Vous devez mettre à niveau Yunohost vers la version 12.1.28 et mettre à niveau Borg vers la version 1.4.1~ynh4 et effectuer les vérifications ci-dessous.
Si votre phrase de passe contient au moins une esperluette, ET que votre installation initiale de Borg a été réalisée à l’aide de la version 1.4.1~ynh3, vous devrez probablement corriger la phrase de passe de votre dépôt, voir ci-dessous.

# Préambule

Nous tenons à rappeler que ce travail est mené par des bénévoles. Nous nous soucions de fournir un service fiable. Cela étant dit, il est important de rappeler que vous avez accepté les conditions d’utilisation et en particulier ce paragraphe :

YunoHost en tant que logiciel est publié sous licence AGPLv3 et est donc fourni sans garantie d’aucune sorte et n’est pas responsable des dommages résultant de son utilisation, ni de l’utilisation des applications qu’il permet d’installer.

De la même manière, dans ce message, l’auteur n’est pas responsable des éventuels dommages.

C’est pourquoi vous êtes invité·es à lire attentivement ce post du début à la fin et à comprendre les étapes ci-dessous avant d’exécuter les commandes.

# La mise à niveau

Suivez ces deux étapes :

Mettez à niveau votre système, ce qui mettra à niveau Yunohost vers la version 12.1.28
Mettez à niveau toutes vos applications Borg (Borg et non Borgserver, qui est un paquet différents)

Les vérifications et la correction post-mise à niveau

Après la mise à niveau, ouvrez une session shell, connectez-vous en tant que root et récupérez tous les ID d’instance Borg à l’aide de la commande suivante :

yunohost app list | grep -Po 'id: \Kborg(\b|__\d+)'

Les étapes ci-dessous doivent être exécutées pour chaque instance Borg :

Vérifions ensuite si la phrase de passe est maintenant correctement définie dans le système :

app_id=borg # change the value borg__2, borg__3, ... to check
            # the other borg instances as returned by the command above
/var/www/$app_id/wrapper/borg list

Si la commande parvient à lister vos sauvegardes, ARRÊTEZ-VOUS ICI, et répétez les commandes ci-dessus pour la prochaine instance Borg

Mais si la commande échoue avec cette erreur :

passphrase supplied in BORG_PASSPHRASE, by BORG_PASSCOMMAND or via BORG_PASSPHRASE_FD is incorrect.

Alors, assurez-vous d’abord que votre phrase de passe contient bien une esperluette :

grep BORG_PASSPHRASE /var/www/$app_id/.env | grep --color '&' && echo "The passphrase contains an ampersand, run the fix" || echo "Do NOT run the fix, that's another problem"

Si la commande affiche votre phrase de passe correctement, alors votre dépôt Borg a probablement été initialisé avec une mauvaise, ayant & remplacé par __PASSPHRASE__ (voir ^[1:3] pour plus d’informations).

Affichons maintenant la commande qui sera exécutée pour modifier la phrase de passe :

export app_id
(set -a; source /var/www/$app_id/.env; set +a; echo BORG_NEW_PASSPHRASE="${BORG_PASSPHRASE}" BORG_PASSPHRASE="${BORG_PASSPHRASE//&/__PASSPHRASE__}"  /var/www/$app_id/venv/bin/borg key change-passphrase)

Inspectez le résultat et, lorsque vous êtes prêt·e, supprimez l’appel à echo dans la commande que vous venez d’exécuter, ce qui rendra le changement effectif.

Si à l’exécution de la commande aucun retour ne vous est affiché, alors la commande a dû s’exécuter avec succès.

Vérifiez maintenant que Borg est capable de lister vos sauvegardes correctement :

/var/www/$app_id/wrapper/borg list

N’oubliez pas de répéter le contrôle et (si nécessaire) la correction pour les autres instances.

Et voilà !

See Passphrase not recognized when it contains ampersands (`&`) · Issue #231 · YunoHost-Apps/borg_ynh · GitHub for a more detailed explanation ↩︎ ↩︎ ↩︎ ↩︎
You should probably this message in /var/log/borg/borg.log: passphrase supplied in BORG_PASSPHRASE, by BORG_PASSCOMMAND or via BORG_PASSPHRASE_FD is incorrect. ↩︎ ↩︎

fflorent · October 12, 2025, 7:30pm

Post-mortem of the bug

This post is now about why this bug has happened. If you’re a just a user of this pacakge, you may skip this post, unless if of course you’re curious to know more.

The version 1.4.1~ynh3 of the package has changed the way the passphrase is retrieved.
Prior to this version, the passphrase used to be retrieved by directly getting it from the settings:

github.com/YunoHost-Apps/borg_ynh

conf/backup_method

b8b300e54


      
          #!/usr/bin/env bash
          set -Eeuo pipefail
          
          borg="__INSTALL_DIR__/venv/bin/borg"
          app="__APP__"
          
          BORG_PASSPHRASE="$(yunohost app setting "$app" passphrase)"
          BORG_REPO="$(yunohost app setting "$app" repository)"
          BORG_LOGGING_CONF="__INSTALL_DIR__/logging.conf"
          
          if ssh-keygen -F "__SERVER__" >/dev/null ; then
              BORG_RSH="ssh -i /root/.ssh/id_${app}_ed25519 -oStrictHostKeyChecking=yes "
          else
              BORG_RSH="ssh -i /root/.ssh/id_${app}_ed25519 -oStrictHostKeyChecking=no "
          fi
          
          do_need_mount() {

But now starting with ~ynh3, we retrieve it by sourcing an .env config file:

Where the __PASSPHRASE__ value is (or should be) replaced by the actual password as read from the settings.

This .env file is convenient for running the borg command without having to specify the long list of env variables, see this feature request that has been implemented for version ynh3.

BUT that’s at this point that the unexpected regression appears! Because Yunohost had this bug already known and reported:

github.com/YunoHost/issues

Application Passwords are not correctly parsed probably because of & char

opened 04:16PM - 02 Nov 24 UTC

closed 02:38PM - 12 Oct 25 UTC

asandikci

### Describe the bug When I type a password includes `&` char while installing a…n app. `__PASSWORD__` indicator is not correctly replaced with actual password ### Context - Hardware: tested with different hardwares (x86-64 VPS / arm Raspi) - YunoHost version: tested with latest 11.x and latest 12.x - I have access to my server: Through SSH / through the webadmin - Are you in a special context or did you perform some particular tweaking on your YunoHost instance?: as far as I know no ### To reproduce 1. *Go to 'Applications'* 2. *Click on 'Add application' (that requires a admin password)* 3. *enter a password contains `&` char* 4. *password is not correctly assigned to specified app's config/env file* ### Expected behavior Password should be correctly parsed ### Extra Info See: https://github.com/YunoHost-Apps/microbin_ynh/issues/11 Tested with: microbin, yourls. Also I remember that there was such more apps...

For usual apps, that’s not a very serious bug, as passwords are simply a way to access an app. It’s easy to circumvent the issue by just setting another password and that’s it .

But when dealing with apps like borg, in which the passphrase is used to encrypt and decrypt the archives, it is actually a big deal, especially when the bad passphrase is used for initiating the borg repo.

Under the hood, the templates are hydrated by using the sed command, and because the ampersand (&) is used by this command to print the matched substitution. For example:

echo "Yunohosters" | sed 's/.*/Hello &/g'

Will print Hello Yunohosters.

The fix has just consisted in escaping every occurrences of &:

github.com/YunoHost/yunohost

helpers: fix ampersands (&) breaking file templating because it is a special sed char (issues#2470)

dev ← fflorent:fix-ampersand-values-in-templates

opened 11:20AM - 12 Oct 25 UTC

fflorent

+17 -11

## The problem Fixes https://github.com/YunoHost/issues/issues/2470 ## Sol…ution Escape ampersands (`&`) with `\\&` so it is treated as a special character. Quoting sed manpage: > **s/regexp/replacement/** > Attempt to match regexp against the pattern space. If successful, replace that portion matched with replacement. **The replacement may contain the special character & to refer to that portion of > the pattern space which matched**, and the special escapes \1 through \9 to refer to the corresponding matching sub-expressions in the regexp. > ## PR Status Ready to be reviewed, the test pass. ## How to test ``` $ bash test_helpers.sh 2 $ bash test_helpers.sh 2.1 ```

That’s the reason why in order to fix this issue, you have to upgrade both Yunohost and less importantly borg (which just regenerates the .env file to have the correct passphrase when Yunohost is upgraded).

Artanux · October 23, 2025, 9:02am

Thanks for your work!

When I try this, I got an error :

# app_id=borg 
# /var/www/$app_id/wrapper/borg list
Got unexpected RPC data format from server:

(Details here if you have an idea to solve the problem.)