# Borg 1.4.1~ynh4 released, what you should check after the upgrade **URL:** https://forum.yunohost.org/t/borg-1-4-1-ynh4-released-what-you-should-check-after-the-upgrade/40385 **Category:** Apps **Tags:** borg, bug, french, english **Created:** [October 12, 2025, 6:59pm UTC](https://forum.yunohost.org/t/borg-1-4-1-ynh4-released-what-you-should-check-after-the-upgrade/40385 "2025-10-12T18:59:27Z") **Posts on this page:** 3 **Page:** 1
### Author: ![fflorent](https://forum.yunohost.org/user_avatar/forum.yunohost.org/fflorent/32/2768_2.png) [@fflorent](https://forum.yunohost.org/u/fflorent) #### Post date: [October 12, 2025, 6:59pm UTC](https://forum.yunohost.org/t/borg-1-4-1-ynh4-released-what-you-should-check-after-the-upgrade/40385/1 "2025-10-12T18:59:27Z")
# 🇬🇧 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: 1. 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. 2. 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 3. 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](https://doc.yunohost.org/en/community/terms_of_services/) and especially to this part: > YunoHost as software is released [under the AGPLv3 license](https://www.gnu.org/licenses/agpl-3.0.txt) 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: 1. Upgrade your system, this will upgrade Yunohost to version `12.1.28` 2. 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: ```bash 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: ```auto 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: ```auto 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: ```auto 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: ```auto /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 : 1. 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. 2. 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. 3. 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](https://doc.yunohost.org/en/community/terms_of_services/) et en particulier ce paragraphe : > YunoHost en tant que logiciel est publié [sous licence AGPLv3](https://www.gnu.org/licenses/agpl-3.0.txt) 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 : 1. Mettez à niveau votre système, ce qui mettra à niveau Yunohost vers la version `12.1.28` 2. 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 : ```bash 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 : ```auto 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 : ```auto 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 : ```auto 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 : ```auto /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à ! 🎉 * * * 1. See [Passphrase not recognized when it contains ampersands (`&`) · Issue #231 · YunoHost-Apps/borg\_ynh · GitHub](https://github.com/YunoHost-Apps/borg_ynh/issues/231) for a more detailed explanation 2. 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.` ---
### Author: ![fflorent](https://forum.yunohost.org/user_avatar/forum.yunohost.org/fflorent/32/2768_2.png) [@fflorent](https://forum.yunohost.org/u/fflorent) #### Post date: [October 12, 2025, 7:30pm UTC](https://forum.yunohost.org/t/borg-1-4-1-ynh4-released-what-you-should-check-after-the-upgrade/40385/2 "2025-10-12T19:30:43Z")
## 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: > 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](https://github.com/YunoHost-Apps/borg_ynh/issues/216) 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: > > > \### 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: ```auto echo "Yunohosters" | sed 's/.*/Hello &/g' ``` Will print `Hello Yunohosters`. The fix has just consisted in escaping every occurrences of `&`: > > > \## 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). ---
### Author: ![Artanux](https://forum.yunohost.org/user_avatar/forum.yunohost.org/artanux/32/2682_2.png) [@Artanux](https://forum.yunohost.org/u/Artanux) #### Post date: [October 23, 2025, 9:02am UTC](https://forum.yunohost.org/t/borg-1-4-1-ynh4-released-what-you-should-check-after-the-upgrade/40385/3 "2025-10-23T09:02:31Z")
Thanks for your work! > [@fflorent](#): > > ```auto > 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 > > ``` When I try this, I got an error : ```auto # app_id=borg # /var/www/$app_id/wrapper/borg list Got unexpected RPC data format from server: ``` ([Details here](https://forum.yunohost.org/t/borg-got-unexpected-rpc-data-format-from-server-apres-la-mise-a-jour-vers-borg-1-4-1-yhn5/40531) if you have an idea to solve the problem.)